source: gsas/all/gsas2cif.html @ 1160

Last change on this file since 1160 was 938, checked in by toby, 12 years ago

platform independent files
File size: 11.8 KB
Line 
1<html>
2<head>
3   <title>Use of the GSAS2CIF program</title>
4   <meta name="keywords" content="crystallography, Rietveld, diffraction,
5   GSAS, EXPGUI, CIF">
6</HEAD>
7<style>
8A:link {text-decoration:none}
9A:vlink {text-decoration:none}
10</style>
11
12<BODY BGCOLOR="#FFFFFF"
13      topmargin="0" leftmargin="0" marginwidth="0" marginheight="0" 
14      text="#000000" link="#0033ff" vlink="#0033ff" alink="#0033ff">
15
16<?
17   include("/var/www/include/navigation.inc");
18   include("/var/www/include/utility.inc");
19?>
20<blockquote><font face="arial, helvetica, sans-serif">
21
22<img src="http://www.gsas.org/Articles/gsas-logo.gif" alt="Greater Seattle Aquarium Sociey Logo (www.gsas.org) used with permission" HEIGHT=80 WIDTH=150 ALIGN=RIGHT>
23<center><h1>
24<HR noshade width="75%" size="2" align="center">
25Using the GSAS2CIF program
26<BR>
27to export
28<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/gsas.html">
29GSAS</A>
30results
31<HR noshade width="75%" size="2" align="center">
32</h1></center>
33
34<P>
35<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/">
36The crystallographic information file,
37(CIF</A>) was developed by the
38<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org">
39IUCr</A> 
40as a standardized format to document single-crystal
41structure determinations and to exchange the results between laboratories.
42More recently, the
43<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/pd/">
44pdCIF</A> dictionary was developed to allow CIF to
45document powder diffraction measurements, as well as, Rietveld results.
46A very short introduction to CIF is included at the
47<a href="#CIFintro">end of this document.</a>
48<P>
49The GSAS2CIF program is used to create CIFs from GSAS results.
50This web page documents ideas behind the program as well as how the program
51is used.
52<P>
53<H4>Overview of the steps to create a CIF in GSAS</H4>
54<BLOCKQUOTE>
55<OL>
56<LI>Complete (<I>ha!</I>) your refinement
57<LI>Run DISAGL to compute interatomic distances and angles
58<LI>(Optional) Edit the "publication flags" in the distance and angle listings
59<LI>(Optional) Copy previously completed CIF templates to the current directory
60<LI>Run GSAS2CIF
61<LI>Edit the template files to include additional information
62<LI>Run GSAS2CIF<P>... <I>and if you are like me</I>...<P>
63<LI>try out a few more ideas in GENLES
64<LI>Run DISAGL
65<LI>Run GSAS2CIF<P>... <I>repeat steps 8-10 until really finished</I>...
66(<a href="#ps">see quote</a>)
67</OL>
68</BLOCKQUOTE>
69<H4>Structure of the GSAS2CIF program</H4>
70<BLOCKQUOTE>
71<P>
72
73The GSAS2CIF program is used to prepare CIF files containing results
74from GSAS. It should be noted many important types of information that
75are needed to describe the sample and the measurement are not
76supplied as input to GSAS. A few examples of information that
77should likely be included in a CIF, but are not defined within GSAS are:
78the data measurement temperature, sample prepartion conditions,
79etc. If the CIF will be used as supplimentary material, to accompany a
80publication, this sort of documentary information certainly should be
81supplied, so that the CIF has value as archival and database materials.
82If a CIF is being prepared for submission to
83an <I>Acta Cryst.</I> journal, the IUCr has
84<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=ftp://ftp.iucr.org/pub/rietform.cif">
85template with a recommended list of CIF data items.
86</A>
87<P>
88Since the GSAS2CIF program cannot supply many items that need
89be present in a well-documented CIF, the GSAS2CIF program copies information
90from template files into each CIF. Three separate template files are
91used:
92<OL>
93<LI>one with publication and other overall information,
94<LI> one with information about the sample & specimen and
95<LI> one with information about diffraction instrumentation and
96data collection parameters.
97</OL>
98The intent is that users will modify copies of these template files and
99thus can avoid inputing the same information multiple times.
100<P>
101When GSAS2CIF is used to create a CIF file for an experiment named
102<I>expnam</I> (e.g. from file <I>expnam</I>.EXP), the GSAS2CIF program
103creates CIF file <I>expnam</I>.cif containing GSAS results. Information
104from a series of template files is copied directly into the CIF. There will
105be N+M+1 template files, where N is the number of phases and M is the number
106of data histograms. The files are named as follows:
107<OL>
108<LI><I>expnam</I>_publ.cif for the publication/overall information template file;
109<LI><I>expnam</I>_phase<U>n</U>.cif for the N sample/specimen template file(s);
110<LI><I>expnam</I>_<I>INST</I><U>mm</U>.cif for the
111the M instrument/data sample/specimen template file(s), where <I>INST</I> is the instrument name
112(<a href="#iname">see below</a>).
113</OL>
114If these files do not exist, they are created and filled
115with the contents of master vesrsions of the template files.
116In the case of the
117<I>expnam</I>_publ.cif and <I>expnam</I>_phase<U>n</U>.cif files,
118template files named template_publ.cif and template_phase.cif
119are read, if present from the same directory where the <I>expnam</I>.EXP
120file is found, and if not there, from the GSAS data directory.
121In the case of the <I>expnam</I>_<I>INST</I><U>mm</U>.cif file(s), the
122program first looks for files named template_<I>INST</I>.cif in the
123current directory and the GSAS data directory and if that file is not
124found, file  template_instrument.cif is read from the current directory
125and if not found, the GSAS data directory.
126<P>
127This somewhat complex series of template files allows for the creation
128default template files for commonly-used instruments as well as the
129potential for reuse of the other template files, by copying these files
130as needed.
131Also, if information is added only to template files, rather
132than editing the final <I>expnam</I>.cif file, if GSAS2CIF is rerun at a later
133stage in the refinement,
134the crystallographic results in the .CIF are updated and the
135template information is retained automatically.
136Note that at present, there is very little applicable software for
137editing a CIF, so editing these template files must be done with a text
138editor.
139<P>
140In addition to the reading the GSAS experiment file (file <I>expnam</I>.EXP),
141GSAS2CIF also reads the variance-covariance matrix created in GENLES
142(from file <I>expnam</I>.CMT) and a table of interatomic distances and angles
143created from program DISAGL (file <I>expnam</I>.DISAGL). If these files
144cannot be read, GSAS2CIF produces a warning message, since the CIF will be
145incomplete without this information.
146</BLOCKQUOTE>
147<a name="iname"></a><H4>Instrument Name</H4>
148<BLOCKQUOTE>
149An instrument name is needed for every GSAS histogram. It is best if this
150name is unique to a specific instrument, so for commercial instruments,
151it is best if this name contains part of the instrument serial number
152or the institution name, etc.
153The instrument name may be defined in the instrument parameter file,
154by inclusion of a record of type
155<Font type=fixed>"INS nn INAME  </font><I>Instrument name</I>".
156If this name is not defined in the original instrument parameter file,
157when GSAS2CIF is run, it will request an instrument name for each histogram,
158and this information will be added to the GSAS experiment file.
159Note that the vertical bar character, (|), should not be used in instrument
160names.
161</BLOCKQUOTE>
162<H4>Publication/Non-Publish Flag for Distances and Angles</H4>
163<BLOCKQUOTE>
164The DISAGL program will tabulate all interatomic distances within
165specified interatomic radii. This information is recorded in a
166file named <I>expnam</I>.DISAGL. These radii may be modified using EXPEDT
167(but not at present EXPGUI). The IUCr journals use a special flags
168(_geom_bond_publ_flag and _geom_angle_publ_flag) to indicate distances
169that will be tabulated in publication. When DISAGL is first run, this flag
170is set to zero, meaning "do not publish".
171If this flag is changed to a digit between 1 and 9 (at present, this must
172be done with a text editing program), the
173distance/angle flag is set to "publish." If DISAGL is rerun at later time,
174to update the distances and angles, these publication flags are transferred
175to the updated <I>expnam</I>.DISAGL file.
176</BLOCKQUOTE>
177<H3>Acknowledgements</H3>
178<BLOCKQUOTE>
179Richard L. Harlow first got me interested in the problem of a
180universal file format for powder diffraction data, leading eventually to this
181effort. I may forgive him someday.
182</BLOCKQUOTE>
183<P>
184
185<BLOCKQUOTE>
186<BLOCKQUOTE>
187<BLOCKQUOTE>
188<hr>
189<a name="ps">"A Rietveld refinement is never perfected, merely abandoned."
190Peter Stephens</a>
191<hr>
192</BLOCKQUOTE>
193</BLOCKQUOTE>
194</BLOCKQUOTE>
195<P>
196<a name="CIFintro">
197<H3>Appendix: A quick & incomplete introduction to CIF</H3>
198</a><BLOCKQUOTE>
199A CIF file consists of logical groups of information that are
200called data blocks,
201since each block is initiated by a label of form data_<I>label</I>.
202In the simple case, where a single crystallographic model is determined
203from a single diffraction dataset (histogram), the CIF can be a
204single block. In the case where either multiple datasets (histograms)
205or where multiple phases are used in the refinement, a CIF will
206require several data blocks to describe the data and results.
207<P>
208CIF consists of a series of tags, called data names, and values
209associated with these data names. Together the data name and value
210are called a data item. A separate document, the CIF (or pdCIF)
211dictionary defines the meaning of each data name. If a value does not
212contain any spaces, may be specifed without quotes, but either single or
213double quotes may be used to delimit strings. A data value of one ore more
214lines is quoted with semicolon characters (;). The semicolons must be
215the first character on a line and the final semicolon is expected to be
216the only non-blank character on the line.
217With the exception of semicolon location, CIF ignores spaces.
218The following lines give
219examples of a few CIF data items.
220
221<BLOCKQUOTE>
222<BLOCKQUOTE>
223<PRE>
224_pd_calc_method   'Rietveld Refinement'
225
226_cell_volume   1811.00(5)
227
228_symmetry_space_group_name_H-M   "I a 3 d"
229
230_pd_proc_ls_background_function
231;   GSAS Background function number 1 with 4 terms.
232 Shifted Chebyshev function of 1st kind
233      1:    139.025     2:   -11.5408     3:    9.75652     4:    3.90497   
234;
235</PRE>
236</BLOCKQUOTE>
237</BLOCKQUOTE>
238CIF also allows multiple values to be associated with a CIF data item.
239This is done by preceeding the data name with the keyword loop_. If
240two or more data names follow the loop_ keyword, a table can be
241constructed, as is shown in the following examples.
242
243<BLOCKQUOTE>
244<BLOCKQUOTE>
245<PRE>
246loop_  _symmetry_equiv_pos_as_xyz
247       +x,+y,+z     +z,+x,+y
248       +y,+z,+x     +x+1/2,+y,-z+1/2
249
250
251loop_
252      _atom_site_label
253      _atom_site_fract_x
254      _atom_site_fract_y
255      _atom_site_fract_z
256Y1      0.125        0.0          0.25     
257FE2     0.0          0.0          0.0     
258AL3     0.375        0.0          0.25     
259O4     -0.02946(5)   0.05385(5)   0.15068(6)
260</PRE>
261</BLOCKQUOTE>
262</BLOCKQUOTE>
263Finally, it should be pointed out that two values in CIF have special meanings.
264If a value is supplied as a single period (.), the meaning is the
265value is not defined or is inappropriate. If the value is a question mark
266(?), this means that the value is unknown or not specified.
267<P>
268For more information, see:
269<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/">
270The CIF home page</A>; short intros to
271<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-announce.html">
272pdCIF</A>
273&
274<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-intro.html">
275CIF syntax</A>
276
277</BLOCKQUOTE>
278
279<P><font size=-1><A HREF="MAILTO:crystal@NIST.gov?subject=WWW page <?=$PHP_SELF?>">Comments, corrections or questions: crystal@NIST.gov</A></font><BR>
280<font size=-1><? lastmod(); ?></font>
281$Revision: 0.0 $ $Date: 2002/?/? $
282</font></blockquote>
283
284</BODY>
285</HTML>
Note: See TracBrowser for help on using the repository browser.