source: trunk/doc/gsas2cif.html @ 701

Last change on this file since 701 was 652, checked in by toby, 12 years ago

# on 2002/09/05 21:18:57, toby did:
more updates

  • Property rcs:author set to toby
  • Property rcs:date set to 2002/09/05 21:18:57
  • Property rcs:lines set to +87 -51
  • Property rcs:rev set to 1.4
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 25.2 KB
3   <title>Use of the GSAS2CIF program</title>
4   <meta name="keywords" content="crystallography, Rietveld, diffraction,
8A:link {text-decoration:none}
9A:vlink {text-decoration:none}
13      topmargin="0" leftmargin="0" marginwidth="0" marginheight="0" 
14      text="#000000" link="#0033ff" vlink="#0033ff" alink="#0033ff">
17   include("/var/www/include/");
18   include("/var/www/include/");
20<font face="arial, helvetica, sans-serif">
25<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
26</TH><TH><A Href="excledt.html">Previous page</A>
29<img src="" alt="Greater Seattle Aquarium Society Logo ( Used with permission" HEIGHT=80 WIDTH=150 ALIGN=RIGHT>
31<HR noshade width="75%" size="2" align="center">
32Using the GSAS2CIF program
34to export
35<A Href="">
38<HR noshade width="75%" size="2" align="center">
42<A HREF="">
43The crystallographic information file,
44(CIF</A>) was developed by the
45<A HREF="">
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="">
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>
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.
60<H4>Overview of the steps to create a CIF in GSAS</H4>
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.
82<LI>Run GSAS2CIF<P>... <I>repeat steps 8-10 until really finished</I>...
83(<a href="#ps">see quote</a>).
86<H4>Structure of the GSAS2CIF program</H4>
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="">
103template with a recommended list of CIF data items.
105This template has been utilized for creation of the template files
106distributed with GSAS/EXPGUI.
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:
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.
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.
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:
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>).
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.
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.
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.
188<a name="iname"></a><H4>Instrument Name</H4>
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
203<a name="pubflag">
204<H4>Publication/Non-Publish Flag for Distances and Angles</H4>
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.
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"
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 available for this chore.
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.
235<a name="filltemplate">
236<H2>The FillTemplate program</H2>
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.
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:
252<img src="ciffill1.gif" alt="View of FillTemplate window">
255The box on the left side of the window displays the data names in the CIF
256as a hierarchical tree. Note that subentries can be displayed or hidden
257by clicking on the +/- sign to the right of each grouping. For example,
258by default the data names contained in each loop are not shown.
259However, clicking on the + sign to the right of the "loop_0" listing
260causes the data names in the loop to be shown (as in
261the <a href="#loopfig">example below</a>.)
263Clicking on an individual data name causes the
264associated value to be displayed on the right. The value associated
265with the data name can be edited by
266clicking on the entry box. The information you enter is copied into the
267in-memory copy of the CIF when you click on another
268data name, etc.
270In the example shown above, the data name
271<tt>_cell_measurement_temperature</tt> has been selected.
272This is defined in the
273CIF dictionary as a number
274between 0 and infinity with
275units of Kelvins. These units (K) are displayed adjacent to the entry box.
276When appropriate input is validated to require
277that valid numbers in the allowed range are input or that
278standard uncertainties (esd's) are entered only where allowed.
279Likewise, if the CIF dictionary defines a enumerated list of values
280for a data name, a menu button is offered in place of an entry box. In
281this way, only a valid entry from the list can be selected.
283The controls on the bottom of the window have the following effects:
287<P><DT><B>Template file</B><DD>
288The menu button labeled "Template file" offers a list of template files. This
289button can be used to select a file to be edited. If changes have been made
290to the current CIF, that have not been saved to disk, the user is offered
291a chance to save or discard these changes.
292<P><DT><B>Next ? in template</B><DD>
293If the button labeled "Next ? in template" is pressed,
294the program scans forward
295in the current file, and if needed through subsequent files, for a data item
296where the value is a single question mark (?), since this value indicates
297a item where a value has not been specified. Note that the _journal_
298data items, which are intended to be used by <I>Acta Crystallographia</I>
299editors, are ignored by this button.
301The "Exit" button causes the program to exit. If any changes have been
302made to a data item or the CIF has been changed, but have not been saved,
303a chance is offered to save these items.
304<P><DT><a name="cifcontents"><B>Show (Hide) CIF contents</B></A><DD>
305The "Show CIF contents" button causes a window to be displayed
306that shows the text of the CIF, as shown below. As CIF data items
307are selected by clicking on data names or through use of the other buttons,
308the window is scrolled forward or backward to show the appropriate section.
309Note that it is possible to make editing changes directly to the CIF
310using this window, but the program cannot verify that these edits
311have the correct syntax. Further, the program will not note that changes
312have been made to the CIF
313so another section of the file must be changed, before the edits can be
314saved to disk (see the <a href="#saveedits">Save</a> button).
316After the "Show CIF contents" button is pressed, the label changes to
317"Hide CIF contents"; pressing the button again causes the window to be hidden.
319<img src="cif_contents.gif" alt="View of CIF text window">
320<P><DT><B>Show (Hide) CIF definitions</B><DD>
321As CIF data names are selected, their definitions are shown in the
322CIF Definitions window, as shown below.
323After the "Show CIF definitions" button is pressed, the label changes to
324"Hide CIF definitions"; pressing the button again causes the
325window to be hidden.
327<img src="cifdef.gif" alt="View of CIF definitions window">
329<P><DT><a name="undo"><B>Undo</B></a><DD>
330As changes are made to the CIF template, they are recorded and can be
331reversed using the "Undo" button. There is no limit to the number of changes
332that are recorded. However, changes cannot be undone after the CIF has been
333saved to disk.
334<P><DT><a name="redo"><B>Redo</B></a><DD>
335If changes have been reversed with the <a href="#undo">"Undo"</a> button,
336the changes can be
337reapplied using the "Redo" button. The list of changes available for "Redo"
338is cleared when a new edit is made or when the CIF is saved.
340<P><DT><a name="saveedits"><B>Save</B></a><DD>
341Changes made to the CIF are not saved to the disk file automatically,
342unless the <a href="#autosave">Auto-Save</a> checkbutton is set. When changes
343have been made, but not saved to disk, this button is made active.
344<P><DT><a name="autosave"><B>Auto-Save</B></a><DD>
345When the Auto-Save mode is not selected,
346changes made to the in-memory copy of the CIF that is displayed in the
347<a href="#cifcontents">CIF Contents window</a> are not written to
348the disk file until the "<a href="#saveedits">Save</a>"
349button is pressed. If the
350Auto-Save mode is selected, these changes are saved to disk automatically.
353<H3>CIF loops</H3>
355CIF loops allow multiple values to be associated with one or more data items,
356in effect defining a table of data.
357Clicking on a loop, causes all the data names in the loop to be displayed,
358as is shown below.
361<a name="loopfig"></a>
362<img src="ciffill.gif" alt="View of FillTemplate window">
365When a loop is displayed, extra controls appear, as are defined below.
368<P><DT><a name="loopspinbox"><B>Loop element #</B></a><DD> 
369The Loop element #" spinbox" is used to select
370which "row" from the loop is displayed. The up arrow advances to the next
371row, while the down arrow reverses by one entry. Numbers can also be typed into
372the entry box; the number is accepted when Enter is pressed.
373The keyboard up and down arrows can also
374be used to advance between entries. Other keys such as Page Up, Home, etc.
375advance in large increments.
376<P><DT><B>Add to loop</B><DD> 
377A new row can be added to the end of a
378loop using the "Add to loop" button. The value for each new entry
379is initialized as "?" (meaning value unknown or unspecified.)
380<P><DT><B>Delete loop entry</B><DD> 
381This deletes the current row from the loop.
382First select the row to delete with the
383"<a href="#loopspinbox">Loop element #</A>"
384spinbox. Note that the values are displayed for confirmation before the
385delete operation is performed.
386It is not possible to delete all entries from a loop, so
387this button is disabled when a loop has only a single row defined.
390It is also possible to click on the data name for a item inside a loop, in this
391case, all entries for that data item in the loop
392are displayed (a column).
396<a name="cifselect">
397<H2>The CIFSelect utility</H2>
400The CIFselect utility is available within EXPGUI
401to view interatomic distances and
402angles generated by DISAGL and to set the CIF publication flags for these
403values. CIFselect is accessed in EXPGUI from the "CIF Export" submenu
404of the "Import/Export" menu. CIFselect opens two windows, one for controlling
405the program and one to display the distances.
407<img src="cifsel1.gif" alt="View of CIFselect window" align="right">
408The control window is shown to the right. The buttons on this window are
409described below.
410<BR clear=all>
412<P><DT><B>Select Phase</B><DD>
413This provides a list of phases.
414<P><DT><B>Select Atom</B><DD>
415This provides a list of atoms for the current phase.
416<P><DT><B>Response to Mouse Click</B><DD>
417When the mouse is clicked on a distance or angle (see below),
418the publication flag for the may be changed. The effect is dictated by
419the mode selected here. In "<B>Toggle</B>" mode the publication flag
420is set to the opposite of the previous value. In "<B>Set</B>" mode,
421the publication flag will be set to "Y" (publish), regardless of the
422previous state of the flag.
423In "<B>Clear</B>" mode,
424the publication flag will be set to "N" (do not publish), regardless of the
425previous state of the flag.
426<P><DT><B>Distance selection: select matching angles?</B><DD>
427When this option is set to Yes, the publication flag will be set to "Yes" for
428all angles where both the publication flags for the distances are also set
429to "Yes". This is illustrated in the window shown below.
430Note that the distance AL3-O6_a is set to be not published. The five angles
431that involve atom O6_a were automatically set to be not published.
432If this option is set to Yes, turning
433on the publication flag for distance AL3-O6_a would cause the publication
434flag to be set on as well. If this option is set to "No", angle flags
435must be changed individually.
438This button causes the current flag settings to be saved in the
439<I>expnam</I>.DISAGL file.
441<P><DT><B>Export Tables</B><DD>
442This button creates a file with all
443bond distances and angles for the current phase, formatted in the
444arrangement used in the window below. Each entry is separated by a
445comma, suitable for reading into spreadsheet programs.
448This button causes CIFselect to exit. If there are unsaved changes
449to publication flags, you will be given an opportunity to save or
450discard these changes.
454The distance and angle display window is shown below. The
455items that are selected for publication are highlighted in yellow.
457<img src="cifsel2.gif" alt="View of CIFselect window" align="right">
458<BR clear=all>
466The GSAS2CIF program was written by Brian H. Toby, Robert B. Von Dreele and
467Allen C. Larson. The distance/angle display format for CIFselect was
468suggested by Lachlan Cranswick, based on SHELX.
469<P>Richard L. Harlow first got me interested in the problem of a
470universal file format for powder diffraction data, leading eventually to
471my involvement with CIF and then this programming
472effort. For all this, I may someday forgive him.
478<hr noshade height=1>
479<B>Quote:</B><BR><a name="ps">
481"A Rietveld refinement is never perfected, merely abandoned."
482Peter Stephens</a>
484<hr noshade height=1>
488<a name="CIFintro">
489<H3>Appendix: A quick & incomplete introduction to CIF</H3>
491A CIF file consists of logical groups of information that are
492called data blocks,
493since each block is initiated by a label of form data_<I>label</I>.
494In the simple case, where a single crystallographic model is determined
495from a single diffraction dataset (histogram), the CIF can be a
496single block. In the case where either multiple datasets (histograms)
497or where multiple phases are used in the refinement, a CIF will
498require several data blocks to describe the data and results.
500CIF consists of a series of tags, called data names, and values
501associated with these data names. Together the data name and value
502are called a data item. A separate document, the CIF (or pdCIF)
503dictionary defines the meaning of each data name. If a value does not
504contain any spaces, may be specifed without quotes, but either single or
505double quotes may be used to delimit strings. A data value of one ore more
506lines is quoted with semicolon characters (;). The two semicolons must be
507the first character on each line and the final semicolon is expected to be
508followed by a white-space character such as a space or then end-of-line.
509With the exception of semicolon delimiters, which must be the first
510character of a line to be recognized, CIF treats multiple spaces, blank
511lines and other "white-space" characters as a single space.
513The following lines give examples of a few CIF data items.
517_pd_calc_method   'Rietveld Refinement'
519_cell_volume   1811.00(5)
521_symmetry_space_group_name_H-M   "I a 3 d"
524;   GSAS Background function number 1 with 4 terms.
525 Shifted Chebyshev function of 1st kind
526      1:    139.025     2:   -11.5408     3:    9.75652     4:    3.90497   
531CIF also allows multiple values to be associated with a CIF data item.
532This is done by preceding the data name with the keyword loop_. If
533two or more data names follow the loop_ keyword, a table can be
534constructed, as is shown in the following examples.
539loop_  _symmetry_equiv_pos_as_xyz
540       +x,+y,+z     +z,+x,+y
541       +y,+z,+x     +x+1/2,+y,-z+1/2
545      _atom_site_label
546      _atom_site_fract_x
547      _atom_site_fract_y
548      _atom_site_fract_z
549Y1      0.125        0.0          0.25     
550FE2     0.0          0.0          0.0     
551AL3     0.375        0.0          0.25     
552O4     -0.02946(5)   0.05385(5)   0.15068(6)
556Finally, it should be pointed out that two values in CIF have special meanings.
557If a value is supplied as a single period (.), the meaning is the
558value is not defined or is inappropriate. If the value is a question mark
559(?), this means that the value is unknown or not specified.
561For more information, see:
562<A HREF="">
563The CIF home page</A>; short intros to
564<A HREF="">
567<A HREF="">
568CIF syntax</A>
571<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
572</TH><TH><A Href="excledt.html">Previous page</A>
577<P><font size=-1><A HREF=" page <?=$PHP_SELF?>">Comments, corrections or questions:</A></font><BR>
578<font size=-1><? lastmod(); ?></font>
579$Revision: 652 $ $Date: 2009-12-04 23:09:45 +0000 (Fri, 04 Dec 2009) $
Note: See TracBrowser for help on using the repository browser.