source: trunk/doc/gsas2cif.html @ 608

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

# on 2002/07/15 17:38:48, toby did:
guide to the GSAS2CIF process
  • Property rcs:author set to toby
  • Property rcs:date set to 2002/07/15 17:38:48
  • Property rcs:rev set to 1.1
  • Property rcs:state set to Exp
  • Property svn:keywords set to Author Date Revision Id
File size: 21.3 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 Sociey 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 prepartion conditions,
96publication information, and so on.
97If the CIF will be used as supplimentary 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 digit 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 digit is 0 (zero), the
222distance/angle is flagged as "do not publish". A value from 1 to 9 indicates
223this flag should be set to "publish." At present, the only way to change this
224flag is manually, with a text editing program, such as wordpad or emacs.
225An EXPGUI program,
226<a href="#cifselect">CIFSelect</A>, is planned for this chore.
227<P>
228When DISAGL is first run, this flag digit is set to 0 (do not publish)
229for all distances and angles. However, if any of these flags are changed in
230the .DISAGL file, these flag settings will be retained if DISAGL is rerun.
231
232</BLOCKQUOTE>
233<a name="filltemplate">
234<H3>The FillTemplate program</H3>
235<BLOCKQUOTE>
236</a>
237The EXPGUI FillTemplate program is used to edit the CIF template files
238used within GSAS2CIF. The <I>expnam</I>_*.cif files are edited by this
239program, if they exists. If these files are not found (because GSAS2CIF
240has not been run), the template_*.cif in the current directory are edited.
241If there these files are not found as well, the template_*.cif in the GSAS
242data directory are copied to the current directory and are then made available
243for editing.
244<P>
245The FillTemplate program is accessed in EXPGUI from the "CIF Export" submenu
246of the "Import/Export" menu. The FillTemplate program
247opens a window, as is shown below:
248</BLOCKQUOTE>
249<img src="ciffill1.gif" alt="View of FillTemplate window">
250<BLOCKQUOTE>
251The box on the left side of the window displays the datanames in the CIF
252as a hierarchical tree. Note that subentries can be displayed or hidden
253by clicking on the +/- sign to the right of a group. For example,
254by default the datanames contained in each loop are not shown, but
255clicking on the + sign to the right of the "loop_0" listing (shown below),
256allows the three data items included in this loop to be displayed.
257<P>
258Clicking on an individual dataname causes the
259associated value to be displayed on the right. This value can be edited by
260clicking on the entry box. Note these edits are not performed until
261the "Save Changes" button is pressed, unless the
262"<a href="#autoaccept">Auto-Accept</a>" is turned on.
263<P>
264In the case above, the dataname
265_pd_prep_temperature is defined in the CIF dictionary as a number
266between 0 and infinity and
267the units are defined as Kelvins, so the input will be validated to ensure
268that only numbers in the allowed range are input and the units are displayed.
269If the CIF dictionary defines a enumerated list of values
270for a dataname, these are the only valid choices, so a menu button offers
271a list of these options, in place of a box where text can be typed.
272<P>
273CIF loops allow multiple values to be associated with one or more data items,
274in effect defining a table of data.
275Clicking on a loop, causes all the datanames in the loop to be displayed,
276as is shown below.
277</BLOCKQUOTE>
278<img src="ciffill.gif" alt="View of FillTemplate window">
279<BLOCKQUOTE>
280When a loop is displayed, extra controls appear. The "spinbox" to the right
281of the "Loop element #" label is used to select
282which "row" from the loop is displayed. A new row can be added to the end of a
283loop using the "Add to loop" button and the displayed
284row can be deleted from a loop
285using the "Delete loop entry" button.
286It is also possible to click on the dataname for a item inside a loop, in this
287case, all entries for that data item in the loop
288are displayed (a column).
289<P>
290The controls on the bottom of the window have the following effects:
291
292<BLOCKQUOTE>
293<DL>
294<DT><B>Save Changes</B><DD>
295<P><DT><B>Template file</B><DD>
296The menu button labeled "Template file" offers a list of template files. This
297button can be used to select a file to be edited. If changes have been made
298to the current CIF, that have not been saved to disk, the user is offered
299a chance to save or discard these changes.
300<P><DT><B>Next ? in template</B><DD>
301If the button labeled "Next ? in template" is pressed,
302the program scans forward
303in the current file, and if needed through subsequent files, for a data item
304where the value is a single question mark (?), since this value indicates
305a item where a value has not been specified. Note that the _journal_
306data items, which are intended to be used by <I>Acta Crystallographia</I>
307editors, are ignored by this button.
308<P><DT><B>Exit</B><DD>
309The "Exit" button causes the program to exit. If any changes have been
310made to a data item or the CIF has been changed, but have not been saved,
311a chance is offered to save these items.
312<P><DT><a name="cifcontents"><B>Show/Hide CIF contents</B></A><DD>
313The "Show CIF contents" button causes a window to be displayed
314that shows the text of the CIF, as shown below. As CIF data items
315are selected by clicking on data names or through use of the other buttons,
316the window is scrolled forward or backward to show the appropriate section.
317Note that it is possible to make editing changes directly to the CIF
318using this window, but the program cannot verify that these edits
319have the correct syntax. Further, the program will not note that changes
320have been made to the CIF
321so another section of the file must be changed, before the edits can be
322saved to disk (see the <a href="#saveedits">Save Edits</a> button).
323<P>
324After the "Show CIF contents" button is pressed, the label changes to
325"Hide CIF contents"; pressing the button again causes the window to be hidden.
326<BR>
327<img src="cif_contents.gif" alt="View of CIF text window">
328<P><DT><B>Show/Hide CIF definitions</B><DD>
329As CIF datanames are selected, their definitions are shown in the
330CIF Definitions window, as shown below.
331After the "Show CIF definitions" button is pressed, the label changes to
332"Hide CIF definitions"; pressing the button again causes the
333window to be hidden.
334<BR>
335<img src="cifdef.gif" alt="View of CIF definitions window">
336<P><DT><a name="saveedits"><B>Save Edits</B></a><DD>
337Changes made to the CIF are not saved to the disk file automatically,
338unless the <a href="#autosave">Auto-Save</a> checkbutton is set. When changes
339have been made, but not saved to disk, this button is made active.
340<P><DT><a name="autoaccept"><B>Auto-Accept</B></a><DD>
341When the Auto-Accept mode is not selected,
342as information is added to the edit boxes for CIF items, these changes are
343not made to the in-memory copy of the CIF that is displayed in the
344<a href="#cifcontents">CIF Contents window</a>. The "Save Changes"
345button causes these changes to be applied. If the
346Auto-Accept mode is selected, these changes are made automatically.
347<P><DT><a name="autosave"><B>Auto-Save</B></a><DD>
348When the Auto-Save mode is not selected,
349changes made to the in-memory copy of the CIF that is displayed in the
350<a href="#cifcontents">CIF Contents window</a> are not written to
351the disk file until the "<a href="#saveedits">Save Changes</a>"
352button is pressed. If the
353Auto-Save mode is selected, these changes are saved to disk automatically.
354</DL>
355</BLOCKQUOTE>
356
357</BLOCKQUOTE>
358<a name="cifselect">
359<H3>The CIFSelect program</H3>
360<BLOCKQUOTE>
361</a>
362This EXPGUI program is planned to display the distances and angles generated
363within DISAGL and to allow the publication flag to be changed.
364
365</BLOCKQUOTE>
366<H3>Acknowledgements</H3>
367<BLOCKQUOTE>
368Richard L. Harlow first got me interested in the problem of a
369universal file format for powder diffraction data, leading eventually to
370my involvement with CIF and then this programming
371effort. For all this, I may someday forgive him.
372</BLOCKQUOTE>
373<P>
374
375<BLOCKQUOTE>
376<BLOCKQUOTE>
377<BLOCKQUOTE>
378<hr>
379<a name="ps">"A Rietveld refinement is never perfected, merely abandoned."
380Peter Stephens</a>
381<hr>
382</BLOCKQUOTE>
383</BLOCKQUOTE>
384</BLOCKQUOTE>
385<P>
386<a name="CIFintro">
387<H3>Appendix: A quick & incomplete introduction to CIF</H3>
388</a><BLOCKQUOTE>
389A CIF file consists of logical groups of information that are
390called data blocks,
391since each block is initiated by a label of form data_<I>label</I>.
392In the simple case, where a single crystallographic model is determined
393from a single diffraction dataset (histogram), the CIF can be a
394single block. In the case where either multiple datasets (histograms)
395or where multiple phases are used in the refinement, a CIF will
396require several data blocks to describe the data and results.
397<P>
398CIF consists of a series of tags, called data names, and values
399associated with these data names. Together the data name and value
400are called a data item. A separate document, the CIF (or pdCIF)
401dictionary defines the meaning of each data name. If a value does not
402contain any spaces, may be specifed without quotes, but either single or
403double quotes may be used to delimit strings. A data value of one ore more
404lines is quoted with semicolon characters (;). The two semicolons must be
405the first character on each line and the final semicolon is expected to be
406followed by a white-space character such as a space or then end-of-line.
407With the exception of semicolon delimiters, which must be the first
408character of a line to be recognized, CIF treats multiple spaces, blank
409lines and other "white-space" characters as a single space.
410<P>
411The following lines give examples of a few CIF data items.
412<BLOCKQUOTE>
413<BLOCKQUOTE>
414<PRE>
415_pd_calc_method   'Rietveld Refinement'
416
417_cell_volume   1811.00(5)
418
419_symmetry_space_group_name_H-M   "I a 3 d"
420
421_pd_proc_ls_background_function
422;   GSAS Background function number 1 with 4 terms.
423 Shifted Chebyshev function of 1st kind
424      1:    139.025     2:   -11.5408     3:    9.75652     4:    3.90497   
425;
426</PRE>
427</BLOCKQUOTE>
428</BLOCKQUOTE>
429CIF also allows multiple values to be associated with a CIF data item.
430This is done by preceeding the data name with the keyword loop_. If
431two or more data names follow the loop_ keyword, a table can be
432constructed, as is shown in the following examples.
433
434<BLOCKQUOTE>
435<BLOCKQUOTE>
436<PRE>
437loop_  _symmetry_equiv_pos_as_xyz
438       +x,+y,+z     +z,+x,+y
439       +y,+z,+x     +x+1/2,+y,-z+1/2
440
441
442loop_
443      _atom_site_label
444      _atom_site_fract_x
445      _atom_site_fract_y
446      _atom_site_fract_z
447Y1      0.125        0.0          0.25     
448FE2     0.0          0.0          0.0     
449AL3     0.375        0.0          0.25     
450O4     -0.02946(5)   0.05385(5)   0.15068(6)
451</PRE>
452</BLOCKQUOTE>
453</BLOCKQUOTE>
454Finally, it should be pointed out that two values in CIF have special meanings.
455If a value is supplied as a single period (.), the meaning is the
456value is not defined or is inappropriate. If the value is a question mark
457(?), this means that the value is unknown or not specified.
458<P>
459For more information, see:
460<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/">
461The CIF home page</A>; short intros to
462<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-announce.html">
463pdCIF</A>
464&
465<A HREF="http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.iucr.org/iucr-top/cif/powder-intro.html">
466CIF syntax</A>
467
468<TABLE BORDER BGCOLOR="#FFFF40" ALIGN=RIGHT>
469<TR><TH><A  Href="expgui.html">EXPGUI top</A> 
470</TH><TH><A Href="excledt.html">Previous page</A>
471</TH></TR></TABLE><BR CLEAR=ALL>
472
473</BLOCKQUOTE>
474
475<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>
476<font size=-1><? lastmod(); ?></font>
477$Revision: 608 $ $Date: 2009-12-04 23:09:01 +0000 (Fri, 04 Dec 2009) $
478</font>
479</BLOCKQUOTE>
480
481</BODY>
482</HTML>
Note: See TracBrowser for help on using the repository browser.