source: branches/sandbox/doc/gsas2cif.html @ 1150

Last change on this file since 1150 was 1150, checked in by toby, 10 years ago

update documentation

  • Property svn:keywords set to Author Date Revision Id
  • Property svn:mime-type set to text/html
File size: 24.6 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="">GSAS</A>
37<HR noshade width="75%" size="2" align="center">
41<A HREF="">
42The crystallographic information file,
43(CIF</A>) was developed by the
44<A HREF="">
45IUCr</A> in the early 1990's
46as a standardized format to document single-crystal
47structure determinations and to exchange the results between laboratories.
48In the late 1990's, the
49<A HREF="">
50pdCIF</A> dictionary was developed to allow CIF to
51document powder diffraction measurements, as well as Rietveld results.
52A very short introduction to CIF is included at the
53<a href="#CIFintro">end of this document.</a>
55The GSAS2CIF program is used to create CIFs from GSAS results.
56This web page documents concepts within the program as well as how the program
57is used.
59<H4>Overview of the steps to create a CIF in GSAS</H4>
62<LI>Complete (<I>ha!</I>) your refinement, being sure to run GENLES after
63making any changes to the .EXP file with EXPEDT/EXPGUI.
64<LI>Run DISAGL to compute interatomic distances and angles.
65<LI>(Optional) Edit the "<a href="#pubflag">
66publication flags</a>" in the distance and angle listings.
67<LI>(Optional) Use EXPGUI program
68<a href="#filltemplate">FillTemplate</A>
69to customize copies of CIF template files in the current directory, or
70manually copy these files to the current directory
71and use a text editor.
72<LI>Run GSAS2CIF (this creates experiment-specific
73copies of the template files).
74<LI>Edit the template files (for example, using
75<a href="#filltemplate">FillTemplate</A>) to include information.
76<LI>Run GSAS2CIF again, to incorporate the revised versions of the
77template files into the complete .CIF file.
78<P>... <I>and if you are like me</I>...<P>
79<LI>try out a few more ideas in GENLES.
81<LI>Run GSAS2CIF<P>... <I>repeat steps 8-10 until really finished</I>...
82(<a href="#ps">see quote</a>).
85<H4>Structure of the GSAS2CIF program</H4>
89The GSAS2CIF program is used to prepare CIF files containing results
90from GSAS. It should be noted many important types of information that
91are needed to describe the sample and the measurement are not
92supplied as input to GSAS. A few examples of information that
93should likely be included in a CIF, but are not defined within GSAS are:
94the data measurement temperature, sample preparation conditions,
95publication information, and so on.
96If the CIF will be used as supplementary material, to accompany a
97publication, this sort of documentary information certainly should be
98supplied, so that the CIF has value for archival and database purposes.
99If a CIF is being prepared for submission to
100an <I>Acta Crystallographia</I> journal, the IUCr has
101<A HREF="">
102template with a recommended list of CIF data items.
104This template has been utilized for creation of the template files
105distributed with GSAS/EXPGUI.
107<H5>Template Files</H5>
108Since the GSAS2CIF program cannot obtain much of the information needed
109to create a CIF that documents a structural determination,
110this information must be supplied by the person running the program in
111the form of template files.
112The GSAS2CIF program simply copies this information
113from template files into the CIF created by GSAS2CIF.
114Three separate template files are
115used with GSAS2CIF:
117<LI>one with publication and other overall information,
118<LI> one with information about the sample & specimen and
119<LI> one with information about diffraction instrumentation and
120data collection parameters.
122Note that as distributed, these files do not contain any information,
123but rather define a set of suggested fields where the user can provide
124this information. Since much of the information in these fields will
125be the same for all CIF's prepared by a researcher or using a specific
126instrument, it will be a good idea to create customized versions of
127these template files and thus
128avoid inputing the same information multiple times.
130When GSAS2CIF is used to create a CIF file for an experiment named
131<I>expnam</I> (e.g. from file <I>expnam</I>.EXP), the GSAS2CIF program
132creates CIF file <I>expnam</I>.cif containing GSAS results. Information
133from a series of template files is copied directly into the CIF. There will
134be N+M+1 template files, where N is the number of phases and M is the number
135of data histograms. The files are named as follows:
137<LI><I>expnam</I>_publ.cif for the publication/overall information template file;
138<LI><I>expnam</I>_phase<U>n</U>.cif for the N sample/specimen template file(s);
139<LI><I>expnam</I>_<I>INST</I><U>mm</U>.cif for the
140the M instrument/data sample/specimen template file(s), where <I>INST</I> is the instrument name
141(<a href="#iname">see below</a>).
143If these files do not exist, they are created and filled
144with the contents of master versions of the template files.
145In the case of the
146<I>expnam</I>_publ.cif and <I>expnam</I>_phase<U>n</U>.cif files,
147template files named template_publ.cif and template_phase.cif
148are read, if present from the same directory where the <I>expnam</I>.EXP
149file is found, and if not present there, from the GSAS data directory.
150In the case of the <I>expnam</I>_<I>INST</I><U>mm</U>.cif file(s), the
151program first looks for files named template_<I>INST</I>.cif in the
152current directory and the GSAS data directory and if that file is not
153found, file  template_instrument.cif is read from the current directory
154and if not found, the GSAS data directory.
155This somewhat complex series of template files allows for the creation
156default template files for commonly-used instruments as well as the
157potential for reuse of the other template files, by copying these files
158as needed and also allows the GSAS2CIF program to be reused to update
159the CIF as needed without loss of input information.
161<P><B>Note</B>, that users should avoid editing the
162final <I>expnam</I>.cif file, but rather should edit the
163<I>expnam</I>_*.cif template files and then rerun GSAS2CIF to incorporate
164the revised template files into a new version of the <I>expnam</I>.cif file.
165In this way, if GSAS2CIF is rerun at a later time,
166the crystallographic results in the .CIF are updated and the
167template information is retained automatically.
168This editing can be done with any ASCII text editor, but an application
169has been included within EXPGUI,
170<a href="#filltemplate">FillTemplate</A>, for this purpose.
172<H5>Other Input Files</H5>
173In addition to the reading the GSAS experiment file (file <I>expnam</I>.EXP),
174GSAS2CIF also reads the variance-covariance matrix created in GENLES
175(from file <I>expnam</I>.CMT) and a table of interatomic distances and angles
176created from program DISAGL (file <I>expnam</I>.DISAGL). If these files
177cannot be read, GSAS2CIF produces a warning message, since the CIF will be
178incomplete without this information.
179Note that the .CMT and .DISAGL are both derived from GENLES output and thus
180the .EXP file must have been used to run GENLES and then DISAGL just prior to
181running GSAS2CIF. If you edit the .EXP file or go back to
182an archived experiment file and do not rerun GENLES and then DISAGL, 
183(<I>expnam</I>.O<I>nn</I>), the most recent <I>expnam</I>.CMT and
184<I>expnam</I>.DISAGL will be out-of-sync with the .EXP contents. GSAS2CIF
185will try to spot this and warn you, but some errors may be hard to catch.
187<a name="iname"></a><H4>Instrument Name</H4>
189An instrument name is needed for every GSAS histogram. It is best if this
190name is unique to a specific instrument, so for commercial instruments,
191it is best if this name contains part of the instrument serial number
192or the institution name, etc.
193The instrument name may be defined in the instrument parameter file,
194by inclusion of a record of type
195<Font type=fixed>"INS nn INAME  </font><I>Instrument name</I>".
196If this name is not defined in the original instrument parameter file,
197when GSAS2CIF is run, it will request an instrument name for each histogram,
198and this information will be added to the GSAS experiment file.
199Note that the vertical bar character, (|), should not be used in instrument
202<a name="pubflag">
203<H4>Publication/Non-Publish Flag for Distances and Angles</H4>
206The DISAGL program will tabulate all interatomic distances within
207specified interatomic radii. These radii may be modified using EXPEDT
208(but not at present EXPGUI). All distances and angles listed by DISAGL in
209the <I>expnam</I>.LST file will be recorded in a more compact format in
210file named <I>expnam</I>.DISAGL. All these distances and angles will then be
211included in the CIF file when GSAS2CIF is run.
213Note that when an IUCr journal publication is prepared from a CIF, these
214distances and angles are abstracted directly into the publication tables
215from the CIF,
216provided that a special CIF flag for each distance/angle
217(_geom_bond_publ_flag and _geom_angle_publ_flag) indicates that these values
218should be published. The character in the first column of the
219<I>expnam</I>.DISAGL indicates the value for this flag, when the
220distances/angles are tabulated in the CIF. If this character is anything
221other than "Y" or "y", the
222distance/angle is flagged as "do not publish". A value of "Y" or "y"
224this flag should be set to "publish." At present, the only way to change this
225flag is manually, with a text editing program, such as wordpad or emacs.
226An EXPGUI program,
227<a href="#cifselect">CIFSelect</A>, is available for this chore.
229When DISAGL is first run, this flag character is set to N (do not publish)
230for all distances and angles. However, if any of these flags are changed in
231the .DISAGL file, these flag settings will be retained if DISAGL is rerun.
234<a name="filltemplate">
235<H2>The FillTemplate program</H2>
238The EXPGUI FillTemplate program is used to edit the CIF template files
239used within GSAS2CIF. The <I>expnam</I>_*.cif files are edited by this
240program, if they exists. If these files are not found (because GSAS2CIF
241has not been run), the template_*.cif in the current directory are edited.
242If there these files are not found as well, the template_*.cif in the GSAS
243data directory are copied to the current directory and are then made available
244for editing.
246The FillTemplate program is accessed in EXPGUI from the "CIF Export" submenu
247of the "Import/Export" menu. The FillTemplate program
248opens a window, as is shown below:
251<img src="ciffill1.gif" alt="View of FillTemplate window">
254The box on the left side of the window displays the data names in the CIF
255as a hierarchical tree. Note that subentries can be displayed or hidden
256by clicking on the +/- sign to the right of each grouping. For example,
257by default the data names contained in each loop are not shown.
258However, clicking on the + sign to the right of the "loop_0" listing
259causes the data names in the loop to be shown (as in
260the <a href="#loopfig">example below</a>.)
262Clicking on an individual data name causes the
263associated value to be displayed on the right. The value associated
264with the data name can be edited by
265clicking on the entry box. The information you enter is copied into the
266in-memory copy of the CIF when you click on another
267data name, etc.
269In the example shown above, the data name
270<tt>_cell_measurement_temperature</tt> has been selected.
271This is defined in the
272CIF dictionary as a number
273between 0 and infinity with
274units of Kelvins. These units (K) are displayed adjacent to the entry box.
275When appropriate input is validated to require
276that valid numbers in the allowed range are input or that
277standard uncertainties (esd's) are entered only where allowed.
278Likewise, if the CIF dictionary defines a enumerated list of values
279for a data name, a menu button is offered in place of an entry box. In
280this way, only a valid entry from the list can be selected.
282The controls on the bottom of the window have the following effects:
286<P><DT><B>Template file</B><DD>
287The menu button labeled "Template file" offers a list of template files. This
288button can be used to select a file to be edited. If changes have been made
289to the current CIF, that have not been saved to disk, the user is offered
290a chance to save or discard these changes.
291<P><DT><B>Next ? in template</B><DD>
292If the button labeled "Next ? in template" is pressed,
293the program scans forward
294in the current file, and if needed through subsequent files, for a data item
295where the value is a single question mark (?), since this value indicates
296a item where a value has not been specified. Note that the _journal_
297data items, which are intended to be used by <I>Acta Crystallographia</I>
298editors, are ignored by this button.
300The "Exit" button causes the program to exit. If any changes have been
301made to a data item or the CIF has been changed, but have not been saved,
302a chance is offered to save these items.
303<P><DT><a name="cifcontents"><B>Show (Hide) CIF contents</B></A><DD>
304The "Show CIF contents" button causes a window to be displayed
305that shows the text of the CIF, as shown below. As CIF data items
306are selected by clicking on data names or through use of the other buttons,
307the window is scrolled forward or backward to show the appropriate section.
308Note that it is possible to make editing changes directly to the CIF
309using this window, but the program cannot verify that these edits
310have the correct syntax. Further, the program will not note that changes
311have been made to the CIF
312so another section of the file must be changed, before the edits can be
313saved to disk (see the <a href="#saveedits">Save</a> button).
315After the "Show CIF contents" button is pressed, the label changes to
316"Hide CIF contents"; pressing the button again causes the window to be hidden.
318<img src="cif_contents.gif" alt="View of CIF text window">
319<P><DT><B>Show (Hide) CIF definitions</B><DD>
320As CIF data names are selected, their definitions are shown in the
321CIF Definitions window, as shown below.
322After the "Show CIF definitions" button is pressed, the label changes to
323"Hide CIF definitions"; pressing the button again causes the
324window to be hidden.
326<img src="cifdef.gif" alt="View of CIF definitions window">
328<P><DT><a name="undo"><B>Undo</B></a><DD>
329As changes are made to the CIF template, they are recorded and can be
330reversed using the "Undo" button. There is no limit to the number of changes
331that are recorded. However, changes cannot be undone after the CIF has been
332saved to disk.
333<P><DT><a name="redo"><B>Redo</B></a><DD>
334If changes have been reversed with the <a href="#undo">"Undo"</a> button,
335the changes can be
336reapplied using the "Redo" button. The list of changes available for "Redo"
337is cleared when a new edit is made or when the CIF is saved.
339<P><DT><a name="saveedits"><B>Save</B></a><DD>
340Changes made to the CIF are not saved to the disk file automatically,
341unless the <a href="#autosave">Auto-Save</a> checkbutton is set. When changes
342have been made, but not saved to disk, this button is made active.
343<P><DT><a name="autosave"><B>Auto-Save</B></a><DD>
344When the Auto-Save mode is not selected,
345changes made to the in-memory copy of the CIF that is displayed in the
346<a href="#cifcontents">CIF Contents window</a> are not written to
347the disk file until the "<a href="#saveedits">Save</a>"
348button is pressed. If the
349Auto-Save mode is selected, these changes are saved to disk automatically.
352<H3>CIF loops</H3>
354CIF loops allow multiple values to be associated with one or more data items,
355in effect defining a table of data.
356Clicking on a loop, causes all the data names in the loop to be displayed,
357as is shown below.
360<a name="loopfig"></a>
361<img src="ciffill.gif" alt="View of FillTemplate window">
364When a loop is displayed, extra controls appear, as are defined below.
367<P><DT><a name="loopspinbox"><B>Loop element #</B></a><DD> 
368The Loop element #" spinbox" is used to select
369which "row" from the loop is displayed. The up arrow advances to the next
370row, while the down arrow reverses by one entry. Numbers can also be typed into
371the entry box; the number is accepted when Enter is pressed.
372The keyboard up and down arrows can also
373be used to advance between entries. Other keys such as Page Up, Home, etc.
374advance in large increments.
375<P><DT><B>Add to loop</B><DD> 
376A new row can be added to the end of a
377loop using the "Add to loop" button. The value for each new entry
378is initialized as "?" (meaning value unknown or unspecified.)
379<P><DT><B>Delete loop entry</B><DD> 
380This deletes the current row from the loop.
381First select the row to delete with the
382"<a href="#loopspinbox">Loop element #</A>"
383spinbox. Note that the values are displayed for confirmation before the
384delete operation is performed.
385It is not possible to delete all entries from a loop, so
386this button is disabled when a loop has only a single row defined.
389It is also possible to click on the data name for a item inside a loop, in this
390case, all entries for that data item in the loop
391are displayed (a column).
395<a name="cifselect">
396<H2>The CIFSelect utility</H2>
399The CIFselect utility is available within EXPGUI
400to view interatomic distances and
401angles generated by DISAGL and to set the CIF publication flags for these
402values. CIFselect is accessed in EXPGUI from the "CIF Export" submenu
403of the "Import/Export" menu. CIFselect opens two windows, one for controlling
404the program and one to display the distances.
406<img src="cifsel1.gif" alt="View of CIFselect window" align="right">
407The control window is shown to the right. The buttons on this window are
408described below.
409<BR clear=all>
411<P><DT><B>Select Phase</B><DD>
412This provides a list of phases.
413<P><DT><B>Select Atom</B><DD>
414This provides a list of atoms for the current phase.
415<P><DT><B>Response to Mouse Click</B><DD>
416When the mouse is clicked on a distance or angle (see below),
417the publication flag for the may be changed. The effect is dictated by
418the mode selected here. In "<B>Toggle</B>" mode the publication flag
419is set to the opposite of the previous value. In "<B>Set</B>" mode,
420the publication flag will be set to "Y" (publish), regardless of the
421previous state of the flag.
422In "<B>Clear</B>" mode,
423the publication flag will be set to "N" (do not publish), regardless of the
424previous state of the flag.
425<P><DT><B>Distance selection: select matching angles?</B><DD>
426When this option is set to Yes, the publication flag will be set to "Yes" for
427all angles where both the publication flags for the distances are also set
428to "Yes". This is illustrated in the window shown below.
429Note that the distance AL3-O6_a is set to be not published. The five angles
430that involve atom O6_a were automatically set to be not published.
431If this option is set to Yes, turning
432on the publication flag for distance AL3-O6_a would cause the publication
433flag to be set on as well. If this option is set to "No", angle flags
434must be changed individually.
437This button causes the current flag settings to be saved in the
438<I>expnam</I>.DISAGL file.
440<P><DT><B>Export Tables</B><DD>
441This button creates a file with all
442bond distances and angles for the current phase, formatted in the
443arrangement used in the window below. Each entry is separated by a
444comma, suitable for reading into spreadsheet programs.
447This button causes CIFselect to exit. If there are unsaved changes
448to publication flags, you will be given an opportunity to save or
449discard these changes.
453The distance and angle display window is shown below. The
454items that are selected for publication are highlighted in yellow.
456<img src="cifsel2.gif" alt="View of CIFselect window" align="right">
457<BR clear=all>
465The GSAS2CIF program was written by Brian H. Toby, Robert B. Von Dreele and
466Allen C. Larson. The distance/angle display format for CIFselect was
467suggested by Lachlan Cranswick, based on SHELX.
468<P>Richard L. Harlow first got me interested in the problem of a
469universal file format for powder diffraction data, leading eventually to
470my involvement with CIF and then this programming
471effort. For all this, I may someday forgive him.
477<hr noshade height=1>
478<B>Quote:</B><BR><a name="ps">
480"A Rietveld refinement is never perfected, merely abandoned."
481Peter Stephens</a>
483<hr noshade height=1>
487<a name="CIFintro">
488<H3>Appendix: A quick & incomplete introduction to CIF</H3>
490A CIF file consists of logical groups of information that are
491called data blocks,
492since each block is initiated by a label of form data_<I>label</I>.
493In the simple case, where a single crystallographic model is determined
494from a single diffraction dataset (histogram), the CIF can be a
495single block. In the case where either multiple datasets (histograms)
496or where multiple phases are used in the refinement, a CIF will
497require several data blocks to describe the data and results.
499CIF consists of a series of tags, called data names, and values
500associated with these data names. Together the data name and value
501are called a data item. A separate document, the CIF (or pdCIF)
502dictionary defines the meaning of each data name. If a value does not
503contain any spaces, may be specifed without quotes, but either single or
504double quotes may be used to delimit strings. A data value of one ore more
505lines is quoted with semicolon characters (;). The two semicolons must be
506the first character on each line and the final semicolon is expected to be
507followed by a white-space character such as a space or then end-of-line.
508With the exception of semicolon delimiters, which must be the first
509character of a line to be recognized, CIF treats multiple spaces, blank
510lines and other "white-space" characters as a single space.
512The following lines give examples of a few CIF data items.
516_pd_calc_method   'Rietveld Refinement'
518_cell_volume   1811.00(5)
520_symmetry_space_group_name_H-M   "I a 3 d"
523;   GSAS Background function number 1 with 4 terms.
524 Shifted Chebyshev function of 1st kind
525      1:    139.025     2:   -11.5408     3:    9.75652     4:    3.90497   
530CIF also allows multiple values to be associated with a CIF data item.
531This is done by preceding the data name with the keyword loop_. If
532two or more data names follow the loop_ keyword, a table can be
533constructed, as is shown in the following examples.
538loop_  _symmetry_equiv_pos_as_xyz
539       +x,+y,+z     +z,+x,+y
540       +y,+z,+x     +x+1/2,+y,-z+1/2
544      _atom_site_label
545      _atom_site_fract_x
546      _atom_site_fract_y
547      _atom_site_fract_z
548Y1      0.125        0.0          0.25     
549FE2     0.0          0.0          0.0     
550AL3     0.375        0.0          0.25     
551O4     -0.02946(5)   0.05385(5)   0.15068(6)
555Finally, it should be pointed out that two values in CIF have special meanings.
556If a value is supplied as a single period (.), the meaning is the
557value is not defined or is inappropriate. If the value is a question mark
558(?), this means that the value is unknown or not specified.
560For more information, see:
561<A HREF="">
562The CIF home page</A>; short intros to
563<A HREF="">
566<A HREF="">
567CIF syntax</A>
570<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
571</TH><TH><A Href="excledt.html">Previous page</A>
Note: See TracBrowser for help on using the repository browser.