Author: Syd Hall, Crystallography Centre, University of Western Australia, Nedlands 6907, Australia.
CIFIO reads and writes CIF data to and from the Xtal binary or ascii archive file representations.
The Crystallographic Information File (CIF) has been developed for electronic submissions to IUCr journals and databases. CIFIO converts an Xtal archive file into CIF format and vice versa. The data to be extracted from the bdf is specified by the user by entering data names into a request file cifreq. A template cifreq file is supplied with the system but this can be copied and modified according to individual needs. CIFIO will only recognise requests for data items which have been defined by the core CIF dictionary which is supplied as the file cifdic. However, users may construct their own dictionary cifdic.loc to handle local data (DO NOT edit the cifdic file).
The generated .cif file will contain information on all requested data items that are currently present on the archive bdf. The unsatisfied requests will be flagged with a question mark '?'. The unavailability of a specific data item may be that data has not been archived on the bdf (as a result of a prior calculation) or that Xtal does not generate this information. The user may use a standard text editor to add or amend a .cif file, but caution must be exercised at all times in order not to corrupt the structure of the file. This may be checked by reading the .cif file with CIFIO with the dictionary checking facility on (ie. enter "cifio cifin dict")
CIFIO uses the mapping file cifmap which is supplied with the system. This file contains the data that enables each CIF data name to be mapped to the Xtal bdf items. The cifmap file should never be changed and a single copy is usually kept in a globally-accessible read-only area of your directory.
CIFIO has four modes: read and write a CIF, read and write and ascii image of the Xtal archive file.
This is the default mode. It will cause the cif file to be read and converted into a sequence of line commands in the file .new. The file .new is automatically read and used to execute a sequence of Xtal calculations needed to create an archive bdf containing the data items in the CIF. If the dict option is set the input cif file will be checked against the dictionary files cifdic and cifdic.loc (optional).
Entering cifout will cause CIFIO to output the data values listed in the file cifreq. (supplied for Acta Crystallographica C submissions) to the file .cif. The following controls apply when generating a CIF.
dset n
Specifies which data set is output to cif. The default is data set 1.
qchr or nqch
This signals how the character data output by CIFIO is encapsulated. If qchr is entered character strings are bounded by single quotes. For example the description of the extinction method could appear as 'Zachariasen Gaussian'. If nqch is entered bounding quotes are not used but imbedded blanks are replaced with an underline. The above example would appear as Zachariasen_Gaussian. nqch is the default.
sfac or nsfa
The outputing of requested structure factor data is treated specially by CIFIO. This is because a user may wish to use a standard CIFREQ file for all CIFIO runs but only generate structure factor data in specific instances where they are required (note that in the future structure factor data may not be an automatic requirement for submission to IUCr journals). Entering sfac will cause the requested structure factor data as defined by the _refln_ data names to output to the CIF file. Entering nsfa , or as default, these data item requests will be ignored .
scal or nsca
The measured structure factor data (Frel, F2rel and Irel) on the bdf is unscaled. These options signal CIFIO to scale, or not to scale, the measured data which is output to the CIF file. The default is scal .
corr or ncor
The measured structure factor data (Frel, F2rel and Irel) on the bdf is not corrected for extinction effects. These options signal CIFIO to correct, or not to correct, the measured data which is output to the CIF file. The default is corr .
The cif file discussed above is designed for data communication external to the Xtal System. It contains only selected items that are required by the recipient journal, database or laboratory. CIFIO is able to read a standard CIF (which was not necessarily generated by CIFIO) and create input commands which enable this data to be stored on an Xtal bdf. However, the data on a CIF is users choice (for example, no structure factors) and this limits the universality of recreating a bdf. In other words, even an CIFIO generated cif file is not the exact text image of the data on the archive bdf and cannot be used therefore to produce an identical copy of the original bdf.
This is where CIFIO serves a second important archiving function. The arcout signal causes an arc archive file to be created. This is also a text file in STAR format. The arc file differs from the a cif file in that it contains every data item on the bdf and can be used to recreate and identical copy of that bdf.
The arc file has a number of important applications. First, it provides for a machine independent archive file which can be stored and reused with any machine and any future version of the Xtal System. Second, it can be sent to any other site by electronic means and converted directly into an identical bdf. Third, its contents are completely self-defined and it is suitable as a communication file with other software. Fourth, because ARC is a text file, data can be examined, added to, deleted or modified with a standard text editor. The modified arc can be used to create a new modified bdf (it goes without saying that such editing must be done with extreme caution). No additional control options are used to output an arc file.
Setting arcin on the CIFIO line will cause the arc file to be read and converted to an output archive bdf. This file will be identical to the bdf that was used to creat arc.
Optionally reads the input archive bdf ( cifout and arcout modes)
Optionally writes an output archive bdf ( cifin and arcin modes)
Optionally reads a cif line file ( cifin mode)
Optionally reads an arc line file ( arcin mode)
Optionally writes a cif line file ( cifout mode)
Optionally writes an arc line file ( arcout mode)
Optionally reads the cifreq and line file ( cifout mode)
Optionally reads the cifmap and line file ( cifout and cifin modes)
Read the .cif file and validate the data items against the dictionaries cifdic and cifdic.loc.
Create a cif file containing data items from the input archive bdf which are specified in the line file cifreq. Structure factor data should be included if requested in cifreq, and the measured structure facture data will be scaled but no extinction corrections applied.