source: trunk/doc/gsas2cif.html @ 610

Last change on this file since 610 was 610, checked in by toby, 14 years ago

# on 2002/07/18 19:59:42, toby did:
clean spelling
change DISAGL flag to Y/N
  • Property rcs:author set to toby
  • Property rcs:date set to 2002/07/18 19:59:42
  • Property rcs:lines set to +14 -10
  • Property rcs:rev set to 1.2
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 21.4 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<font face="arial, helvetica, sans-serif">
21
22<BLOCKQUOTE>
23
24<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=RIGHT>
25<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
26</TH><TH><A Href="excledt.html">Previous page</A>
27</TH></TR></TABLE><BR CLEAR=ALL>
28
29<img src="http://www.gsas.org/Articles/gsas-logo.gif" alt="Greater Seattle Aquarium Society Logo (www.gsas.org). Used with permission" HEIGHT=80 WIDTH=150 ALIGN=RIGHT>
30<center><h1>
31<HR noshade width="75%" size="2" align="center">
32Using the GSAS2CIF program
33<BR>
34to export
35<A Href="http://www.ncnr.nist.gov/programs/crystallography/software/gsas.html">
36GSAS</A>
37results
38<HR noshade width="75%" size="2" align="center">
39</h1></center>
40
41<P>
42<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/">
43The crystallographic information file,
44(CIF</A>) was developed by the
45<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org">
46IUCr</A> in the early 1990's
47as a standardized format to document single-crystal
48structure determinations and to exchange the results between laboratories.
49In the late 1990's, the
50<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/pd/">
51pdCIF</A> dictionary was developed to allow CIF to
52document powder diffraction measurements, as well as Rietveld results.
53A very short introduction to CIF is included at the
54<a href="#CIFintro">end of this document.</a>
55<P>
56The GSAS2CIF program is used to create CIFs from GSAS results.
57This web page documents concepts within the program as well as how the program
58is used.
59<P>
60<H4>Overview of the steps to create a CIF in GSAS</H4>
61<BLOCKQUOTE>
62<OL>
63<LI>Complete (<I>ha!</I>) your refinement, being sure to run GENLES after
64making any changes to the .EXP file with EXPEDT/EXPGUI.
65<LI>Run DISAGL to compute interatomic distances and angles.
66<LI>(Optional) Edit the "<a href="#pubflag">
67publication flags</a>" in the distance and angle listings.
68<LI>(Optional) Use EXPGUI program
69<a href="#filltemplate">FillTemplate</A>
70to customize copies of CIF template files in the current directory, or
71manually copy these files to the current directory
72and use a text editor.
73<LI>Run GSAS2CIF (this creates experiment-specific
74copies of the template files).
75<LI>Edit the template files (for example, using
76<a href="#filltemplate">FillTemplate</A>) to include information.
77<LI>Run GSAS2CIF again, to incorporate the revised versions of the
78template files into the complete .CIF file.
79<P>... <I>and if you are like me</I>...<P>
80<LI>try out a few more ideas in GENLES.
81<LI>Run DISAGL.
82<LI>Run GSAS2CIF<P>... <I>repeat steps 8-10 until really finished</I>...
83(<a href="#ps">see quote</a>).
84</OL>
85</BLOCKQUOTE>
86<H4>Structure of the GSAS2CIF program</H4>
87<BLOCKQUOTE>
88<P>
89
90The GSAS2CIF program is used to prepare CIF files containing results
91from GSAS. It should be noted many important types of information that
92are needed to describe the sample and the measurement are not
93supplied as input to GSAS. A few examples of information that
94should likely be included in a CIF, but are not defined within GSAS are:
95the data measurement temperature, sample preparation conditions,
96publication information, and so on.
97If the CIF will be used as supplementary material, to accompany a
98publication, this sort of documentary information certainly should be
99supplied, so that the CIF has value for archival and database purposes.
100If a CIF is being prepared for submission to
101an <I>Acta Crystallographia</I> journal, the IUCr has
102<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=ftp://ftp.iucr.org/pub/rietform.cif">
103template with a recommended list of CIF data items.
104</A>
105This template has been utilized for creation of the template files
106distributed with GSAS/EXPGUI.
107<P>
108<H5>Template Files</H5>
109Since the GSAS2CIF program cannot obtain much of the information needed
110to create a CIF that documents a structural determination,
111this information must be supplied by the person running the program in
112the form of template files.
113The GSAS2CIF program simply copies this information
114from template files into the CIF created by GSAS2CIF.
115Three separate template files are
116used with GSAS2CIF:
117<OL>
118<LI>one with publication and other overall information,
119<LI> one with information about the sample & specimen and
120<LI> one with information about diffraction instrumentation and
121data collection parameters.
122</OL>
123Note that as distributed, these files do not contain any information,
124but rather define a set of suggested fields where the user can provide
125this information. Since much of the information in these fields will
126be the same for all CIF's prepared by a researcher or using a specific
127instrument, it will be a good idea to create customized versions of
128these template files and thus
129avoid inputing the same information multiple times.
130<P>
131When GSAS2CIF is used to create a CIF file for an experiment named
132<I>expnam</I> (e.g. from file <I>expnam</I>.EXP), the GSAS2CIF program
133creates CIF file <I>expnam</I>.cif containing GSAS results. Information
134from a series of template files is copied directly into the CIF. There will
135be N+M+1 template files, where N is the number of phases and M is the number
136of data histograms. The files are named as follows:
137<OL>
138<LI><I>expnam</I>_publ.cif for the publication/overall information template file;
139<LI><I>expnam</I>_phase<U>n</U>.cif for the N sample/specimen template file(s);
140<LI><I>expnam</I>_<I>INST</I><U>mm</U>.cif for the
141the M instrument/data sample/specimen template file(s), where <I>INST</I> is the instrument name
142(<a href="#iname">see below</a>).
143</OL>
144If these files do not exist, they are created and filled
145with the contents of master versions of the template files.
146In the case of the
147<I>expnam</I>_publ.cif and <I>expnam</I>_phase<U>n</U>.cif files,
148template files named template_publ.cif and template_phase.cif
149are read, if present from the same directory where the <I>expnam</I>.EXP
150file is found, and if not present there, from the GSAS data directory.
151In the case of the <I>expnam</I>_<I>INST</I><U>mm</U>.cif file(s), the
152program first looks for files named template_<I>INST</I>.cif in the
153current directory and the GSAS data directory and if that file is not
154found, file  template_instrument.cif is read from the current directory
155and if not found, the GSAS data directory.
156This somewhat complex series of template files allows for the creation
157default template files for commonly-used instruments as well as the
158potential for reuse of the other template files, by copying these files
159as needed and also allows the GSAS2CIF program to be reused to update
160the CIF as needed without loss of input information.
161
162<P><B>Note</B>, that users should avoid editing the
163final <I>expnam</I>.cif file, but rather should edit the
164<I>expnam</I>_*.cif template files and then rerun GSAS2CIF to incorporate
165the revised template files into a new version of the <I>expnam</I>.cif file.
166In this way, if GSAS2CIF is rerun at a later time,
167the crystallographic results in the .CIF are updated and the
168template information is retained automatically.
169This editing can be done with any ASCII text editor, but an application
170has been included within EXPGUI,
171<a href="#filltemplate">FillTemplate</A>, for this purpose.
172<P>
173<H5>Other Input Files</H5>
174In addition to the reading the GSAS experiment file (file <I>expnam</I>.EXP),
175GSAS2CIF also reads the variance-covariance matrix created in GENLES
176(from file <I>expnam</I>.CMT) and a table of interatomic distances and angles
177created from program DISAGL (file <I>expnam</I>.DISAGL). If these files
178cannot be read, GSAS2CIF produces a warning message, since the CIF will be
179incomplete without this information.
180Note that the .CMT and .DISAGL are both derived from GENLES output and thus
181the .EXP file must have been used to run GENLES and then DISAGL just prior to
182running GSAS2CIF. If you edit the .EXP file or go back to
183an archived experiment file and do not rerun GENLES and then DISAGL, 
184(<I>expnam</I>.O<I>nn</I>), the most recent <I>expnam</I>.CMT and
185<I>expnam</I>.DISAGL will be out-of-sync with the .EXP contents. GSAS2CIF
186will try to spot this and warn you, but some errors may be hard to catch.
187</BLOCKQUOTE>
188<a name="iname"></a><H4>Instrument Name</H4>
189<BLOCKQUOTE>
190An instrument name is needed for every GSAS histogram. It is best if this
191name is unique to a specific instrument, so for commercial instruments,
192it is best if this name contains part of the instrument serial number
193or the institution name, etc.
194The instrument name may be defined in the instrument parameter file,
195by inclusion of a record of type
196<Font type=fixed>"INS nn INAME  </font><I>Instrument name</I>".
197If this name is not defined in the original instrument parameter file,
198when GSAS2CIF is run, it will request an instrument name for each histogram,
199and this information will be added to the GSAS experiment file.
200Note that the vertical bar character, (|), should not be used in instrument
201names.
202</BLOCKQUOTE>
203<a name="pubflag">
204<H4>Publication/Non-Publish Flag for Distances and Angles</H4>
205</a>
206<BLOCKQUOTE>
207The DISAGL program will tabulate all interatomic distances within
208specified interatomic radii. These radii may be modified using EXPEDT
209(but not at present EXPGUI). All distances and angles listed by DISAGL in
210the <I>expnam</I>.LST file will be recorded in a more compact format in
211file named <I>expnam</I>.DISAGL. All these distances and angles will then be
212included in the CIF file when GSAS2CIF is run.
213<P>
214Note that when an IUCr journal publication is prepared from a CIF, these
215distances and angles are abstracted directly into the publication tables
216from the CIF,
217provided that a special CIF flag for each distance/angle
218(_geom_bond_publ_flag and _geom_angle_publ_flag) indicates that these values
219should be published. The character in the first column of the
220<I>expnam</I>.DISAGL indicates the value for this flag, when the
221distances/angles are tabulated in the CIF. If this character is anything
222other than "Y" or "y", the
223distance/angle is flagged as "do not publish". A value of "Y" or "y"
224indicates
225this flag should be set to "publish." At present, the only way to change this
226flag is manually, with a text editing program, such as wordpad or emacs.
227An EXPGUI program,
228<a href="#cifselect">CIFSelect</A>, is planned for this chore.
229<P>
230When DISAGL is first run, this flag character is set to N (do not publish)
231for all distances and angles. However, if any of these flags are changed in
232the .DISAGL file, these flag settings will be retained if DISAGL is rerun.
233
234</BLOCKQUOTE>
235<a name="filltemplate">
236<H3>The FillTemplate program</H3>
237<BLOCKQUOTE>
238</a>
239The EXPGUI FillTemplate program is used to edit the CIF template files
240used within GSAS2CIF. The <I>expnam</I>_*.cif files are edited by this
241program, if they exists. If these files are not found (because GSAS2CIF
242has not been run), the template_*.cif in the current directory are edited.
243If there these files are not found as well, the template_*.cif in the GSAS
244data directory are copied to the current directory and are then made available
245for editing.
246<P>
247The FillTemplate program is accessed in EXPGUI from the "CIF Export" submenu
248of the "Import/Export" menu. The FillTemplate program
249opens a window, as is shown below:
250</BLOCKQUOTE>
251<img src="ciffill1.gif" alt="View of FillTemplate window">
252<BLOCKQUOTE>
253The box on the left side of the window displays the datanames in the CIF
254as a hierarchical tree. Note that subentries can be displayed or hidden
255by clicking on the +/- sign to the right of a group. For example,
256by default the datanames contained in each loop are not shown, but
257clicking on the + sign to the right of the "loop_0" listing (shown below),
258allows the three data items included in this loop to be displayed.
259<P>
260Clicking on an individual dataname causes the
261associated value to be displayed on the right. This value can be edited by
262clicking on the entry box. Note these edits are not performed until
263the "Save Changes" button is pressed, unless the
264"<a href="#autoaccept">Auto-Accept</a>" is turned on.
265<P>
266In the case above, the dataname
267_pd_prep_temperature is defined in the CIF dictionary as a number
268between 0 and infinity and
269the units are defined as Kelvins, so the input will be validated to ensure
270that only numbers in the allowed range are input and the units are displayed.
271If the CIF dictionary defines a enumerated list of values
272for a dataname, these are the only valid choices, so a menu button offers
273a list of these options, in place of a box where text can be typed.
274<P>
275CIF loops allow multiple values to be associated with one or more data items,
276in effect defining a table of data.
277Clicking on a loop, causes all the datanames in the loop to be displayed,
278as is shown below.
279</BLOCKQUOTE>
280<img src="ciffill.gif" alt="View of FillTemplate window">
281<BLOCKQUOTE>
282When a loop is displayed, extra controls appear. The "spinbox" to the right
283of the "Loop element #" label is used to select
284which "row" from the loop is displayed. A new row can be added to the end of a
285loop using the "Add to loop" button and the displayed
286row can be deleted from a loop
287using the "Delete loop entry" button.
288It is also possible to click on the dataname for a item inside a loop, in this
289case, all entries for that data item in the loop
290are displayed (a column).
291<P>
292The controls on the bottom of the window have the following effects:
293
294<BLOCKQUOTE>
295<DL>
296<DT><B>Save Changes</B><DD>
297<P><DT><B>Template file</B><DD>
298The menu button labeled "Template file" offers a list of template files. This
299button can be used to select a file to be edited. If changes have been made
300to the current CIF, that have not been saved to disk, the user is offered
301a chance to save or discard these changes.
302<P><DT><B>Next ? in template</B><DD>
303If the button labeled "Next ? in template" is pressed,
304the program scans forward
305in the current file, and if needed through subsequent files, for a data item
306where the value is a single question mark (?), since this value indicates
307a item where a value has not been specified. Note that the _journal_
308data items, which are intended to be used by <I>Acta Crystallographia</I>
309editors, are ignored by this button.
310<P><DT><B>Exit</B><DD>
311The "Exit" button causes the program to exit. If any changes have been
312made to a data item or the CIF has been changed, but have not been saved,
313a chance is offered to save these items.
314<P><DT><a name="cifcontents"><B>Show/Hide CIF contents</B></A><DD>
315The "Show CIF contents" button causes a window to be displayed
316that shows the text of the CIF, as shown below. As CIF data items
317are selected by clicking on data names or through use of the other buttons,
318the window is scrolled forward or backward to show the appropriate section.
319Note that it is possible to make editing changes directly to the CIF
320using this window, but the program cannot verify that these edits
321have the correct syntax. Further, the program will not note that changes
322have been made to the CIF
323so another section of the file must be changed, before the edits can be
324saved to disk (see the <a href="#saveedits">Save Edits</a> button).
325<P>
326After the "Show CIF contents" button is pressed, the label changes to
327"Hide CIF contents"; pressing the button again causes the window to be hidden.
328<BR>
329<img src="cif_contents.gif" alt="View of CIF text window">
330<P><DT><B>Show/Hide CIF definitions</B><DD>
331As CIF datanames are selected, their definitions are shown in the
332CIF Definitions window, as shown below.
333After the "Show CIF definitions" button is pressed, the label changes to
334"Hide CIF definitions"; pressing the button again causes the
335window to be hidden.
336<BR>
337<img src="cifdef.gif" alt="View of CIF definitions window">
338<P><DT><a name="saveedits"><B>Save Edits</B></a><DD>
339Changes made to the CIF are not saved to the disk file automatically,
340unless the <a href="#autosave">Auto-Save</a> checkbutton is set. When changes
341have been made, but not saved to disk, this button is made active.
342<P><DT><a name="autoaccept"><B>Auto-Accept</B></a><DD>
343When the Auto-Accept mode is not selected,
344as information is added to the edit boxes for CIF items, these changes are
345not made to the in-memory copy of the CIF that is displayed in the
346<a href="#cifcontents">CIF Contents window</a>. The "Save Changes"
347button causes these changes to be applied. If the
348Auto-Accept mode is selected, these changes are made automatically.
349<P><DT><a name="autosave"><B>Auto-Save</B></a><DD>
350When the Auto-Save mode is not selected,
351changes made to the in-memory copy of the CIF that is displayed in the
352<a href="#cifcontents">CIF Contents window</a> are not written to
353the disk file until the "<a href="#saveedits">Save Changes</a>"
354button is pressed. If the
355Auto-Save mode is selected, these changes are saved to disk automatically.
356</DL>
357</BLOCKQUOTE>
358
359</BLOCKQUOTE>
360<a name="cifselect">
361<H3>The CIFSelect program</H3>
362<BLOCKQUOTE>
363</a>
364This EXPGUI program is planned to display the distances and angles generated
365within DISAGL and to allow the publication flag to be changed.
366
367</BLOCKQUOTE>
368<H3>Acknowledgments</H3>
369<BLOCKQUOTE>
370The GSAS2CIF program was written by Brian H. Toby, Robert B. Von Dreele and
371Allen C. Larson.
372<P>Richard L. Harlow first got me interested in the problem of a
373universal file format for powder diffraction data, leading eventually to
374my involvement with CIF and then this programming
375effort. For all this, I may someday forgive him.
376</BLOCKQUOTE>
377<P>
378
379<BLOCKQUOTE>
380<BLOCKQUOTE>
381<BLOCKQUOTE>
382<hr>
383<a name="ps">"A Rietveld refinement is never perfected, merely abandoned."
384Peter Stephens</a>
385<hr>
386</BLOCKQUOTE>
387</BLOCKQUOTE>
388</BLOCKQUOTE>
389<P>
390<a name="CIFintro">
391<H3>Appendix: A quick & incomplete introduction to CIF</H3>
392</a><BLOCKQUOTE>
393A CIF file consists of logical groups of information that are
394called data blocks,
395since each block is initiated by a label of form data_<I>label</I>.
396In the simple case, where a single crystallographic model is determined
397from a single diffraction dataset (histogram), the CIF can be a
398single block. In the case where either multiple datasets (histograms)
399or where multiple phases are used in the refinement, a CIF will
400require several data blocks to describe the data and results.
401<P>
402CIF consists of a series of tags, called data names, and values
403associated with these data names. Together the data name and value
404are called a data item. A separate document, the CIF (or pdCIF)
405dictionary defines the meaning of each data name. If a value does not
406contain any spaces, may be specifed without quotes, but either single or
407double quotes may be used to delimit strings. A data value of one ore more
408lines is quoted with semicolon characters (;). The two semicolons must be
409the first character on each line and the final semicolon is expected to be
410followed by a white-space character such as a space or then end-of-line.
411With the exception of semicolon delimiters, which must be the first
412character of a line to be recognized, CIF treats multiple spaces, blank
413lines and other "white-space" characters as a single space.
414<P>
415The following lines give examples of a few CIF data items.
416<BLOCKQUOTE>
417<BLOCKQUOTE>
418<PRE>
419_pd_calc_method   'Rietveld Refinement'
420
421_cell_volume   1811.00(5)
422
423_symmetry_space_group_name_H-M   "I a 3 d"
424
425_pd_proc_ls_background_function
426;   GSAS Background function number 1 with 4 terms.
427 Shifted Chebyshev function of 1st kind
428      1:    139.025     2:   -11.5408     3:    9.75652     4:    3.90497   
429;
430</PRE>
431</BLOCKQUOTE>
432</BLOCKQUOTE>
433CIF also allows multiple values to be associated with a CIF data item.
434This is done by preceding the data name with the keyword loop_. If
435two or more data names follow the loop_ keyword, a table can be
436constructed, as is shown in the following examples.
437
438<BLOCKQUOTE>
439<BLOCKQUOTE>
440<PRE>
441loop_  _symmetry_equiv_pos_as_xyz
442       +x,+y,+z     +z,+x,+y
443       +y,+z,+x     +x+1/2,+y,-z+1/2
444
445
446loop_
447      _atom_site_label
448      _atom_site_fract_x
449      _atom_site_fract_y
450      _atom_site_fract_z
451Y1      0.125        0.0          0.25     
452FE2     0.0          0.0          0.0     
453AL3     0.375        0.0          0.25     
454O4     -0.02946(5)   0.05385(5)   0.15068(6)
455</PRE>
456</BLOCKQUOTE>
457</BLOCKQUOTE>
458Finally, it should be pointed out that two values in CIF have special meanings.
459If a value is supplied as a single period (.), the meaning is the
460value is not defined or is inappropriate. If the value is a question mark
461(?), this means that the value is unknown or not specified.
462<P>
463For more information, see:
464<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/">
465The CIF home page</A>; short intros to
466<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-announce.html">
467pdCIF</A>
468&
469<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-intro.html">
470CIF syntax</A>
471
472<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=RIGHT>
473<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
474</TH><TH><A Href="excledt.html">Previous page</A>
475</TH></TR></TABLE><BR CLEAR=ALL>
476
477</BLOCKQUOTE>
478
479<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>
480<font size=-1><? lastmod(); ?></font>
481$Revision: 610 $ $Date: 2009-12-04 23:09:03 +0000 (Fri, 04 Dec 2009) $
482</font>
483</BLOCKQUOTE>
484
485</BODY>
486</HTML>
Note: See TracBrowser for help on using the repository browser.