Xtal Files

Most Xtal calculations are initiated, and controlled, from a input line file usually known as the .datfile. The results of a calculation are output to files and a screen device (as in graphics applications). Xtal calculations use various files to store intermediate and archival data. This strong dependence on files means that Xtal is considered a file-driven archival system, rather than an interactive menu-driven system. This is not strictly true because of the interactive graphics programs such as PIG and PREVUE , but for most calculations the file-driven approach has been adopted as the " Xtal philosophy" for the most efficient use of both computing and human resources.

File types

Xtal employs two basic file types: line (character) and binary.

Line files are composed of ascii text which may be manipulated with a normal text editor. The two principal line files are the line input file ( compid.dat) and print file ( compid.lst). The former contains data that determines which and how calculations are performed, and the latter is the printed results of these calculations. Xtal uses other line files for certain calculations. These include a punch file, formatted sequential files, formatted direct-access files, various ancillary database files (e.g. cifmap, cifdic, symmap ) and an error message file. Later there will be a more detailed description of the format of line files.

Binary files are used extensively as working files (ie. intermediate files for exchanging within, and between, calculations), and to archive certain types of data. Binary files are more efficient than line files for certain operations because of their compactness and because they do not require decoding or encoding when data is extracted from or transferred to computer memory. A binary file is often referred to in Xtal documentation as a ' bdf ' (binary data file).

Xtal binary files are divided into two categories: archive and auxilliary. Archive bdf's are used as an archive record of accumulated crystal structure data. These files are updated as the analysis progresses. For example, lratom: and lrrefl: are stored in an archive file. The data structure for archive files is carefully defined for all programs (see the Archive Files description below and the Archivesection at the end of this manual).

Auxilliary bdf's are used to transfer data from one calculation to another. They are created by a calculation for a specific data exchange purpose. Electron density maps are typical of data stored in an auxiliary file. The actual format of these files is similar to the archival files, but their contents are only known to the programs that write or read them. These are dicussed in detail later.

Filename syntax

The convention for filename construction for all Xtal files is normally <compid>. <ext> where compid is the compound identification code (maximum of six characters), and ext is the extension code (three characters). The compid code is defined by the user at the start of the input commands with the line " compid compid " (see System). [Note: If needed at your site, the filename construction can be changed via the system macro filename: in the supplied file xmacro.r . ]

Archive Files

Binary

The concept of an archive bdf has been introduced above. Most Xtal programs employ two archive binary files; one for input and one for output. These have filename extensions .aa1and .aa2. At the start of an Xtal run the file .aa1is assumed to be the input archive file, and this file will be read by the first calculation requiring data from the archive file. If a calculation adds to, or changes archive data, this will initially be written to the file aa2so that it contains the latest archive data. At the close of this calculation the nucleus will reverse the roles of the two archive files so that aa2becomes the input file and aa1becomes the output file. This interchange process is repeated for every calculation that writes data to an archive file.

Master

Xtal provides a procedure for automatically saving the latest archive bdf. This is referred to as the master file option. When this is switched on the most recent archive binary file ( aa1or aa2) is saved as an ascii file with the filename extension aaa(for details of the format read the CIFIO description if the arcfile which is identical). Unlike the binary files aa1or aa2, the master file aaamay be read or edited using a normal text/screen editor, and is independent of machine or compiler types.

The master file option is set during installation via the definition of the the macro masterfile:. This option may also be set at run time using the master line (described in 2. below). If this option is switched off, the user is responsible for ensuring that at the start of a calculation the latest archive binary file is labelled aa1. If the master file option is switched on, the file aaais automatically converted to the binary file aa1at the start of a calculation sequence and the latest binary file is automatically converted to the file aaaat the end of an Xtal run. Note that the aaafile is generated only when an Xtal run terminates with a finish line or an Xtal error. It will not be generated if a program terminates through a program execution error or an operating system fault. Note that if an aaafile does not exist at the start of a run, Xtal assumes that the file aa1is the input archive binary file.

The need for master archive files will depend on local applications and on the local computing environment. If you are an expert user, or there is a shortage of disc space, or there are very large files, the extra time and space needed for master file operations may be unacceptable. Where Xtal is being applied to many analyses simultaneously this option should be useful to ensure that the latest archive file is retained after each run. It is recommended that master file be made the default condition (i.e. set masterfile: to yes: on installation) and users switch it off with a master no line if it is not required.

Auxiliary files

Unlike the archive files, auxiliary files are only used for the storage of intermediate data. Programs which write auxiliary files assign filename extensions to files according to their contents. Files with the extensions xx*are scratch files and may be deleted after a calculation run.

Format of line files

Xtal line files may be free format or fixed format. Character data is case insensitive (i.e. upper- or lower-case alphabetical characters are treated identically except for atom site labels).

Concept of a field

A field is a string of contiguous characters delimited by a blank. Every input line must start (in column 1) with a line identification code. This requirement may be overridden with the setid system command (see the setid description in System). The identification code constitutes field 0 of the input line and must terminate with a blank. In free format input mode subsequent fields are numbered from left to right, 1, 2, 3, etc. If the system lines field and/or order are entered, the widths and/or the numbering of the input fields may be specified by the user (the field and order descriptions are in 2. below).

Note that the sequential numbering of fields should not be confused with the order that data is entered in a given program. For many calculations data may be entered in any order. This is clearly indicated in the User's Guide when no field numbers are attached. This is usually the case when numerical data follows control codes (e.g. see the reset line described in System).

Types of fields

There are three distinct types of input field; the numerical field, the alphanumerical field, and the void field. They are defined as follows:

Numerical field: a set of contiguous characters composed of the integers 0to 9and characters plus, minus and period. All numerical fields are entered and stored as real numbers, independent of whether a decimal point is entered. A number in 'scientific notation' is entered without the letter 'E' used by Fortran formatting routines. For example, the 0.000001 may be entered as 1.0-6. The numbers in the following fields are identical

3 3.0 30.-1 +3 +3. +.3+1 +30.-1 30-1 .03+2

Alphanumerical field: a set of contiguous characters containing at least one alphabetic character ( ato zand Ato Z). The character strings A123and 123Aare treated as alphanumerical fields. Internally the nucleus treats numerical and alphanumerical fields quite differently.

Void field: a field that contains only a blank. Internally this type of field is identified as a floating-point word with a value defined by the macro voidflg:. The default value for voidflg: is -4.0+20 -- this value must not be used for any other purpose.

Field delimiter character: blank

A field is delimited by any contiguous sequence of blanks.

Field skip control: $n

The digraph $ n in an input line is interpreted as a signal to skip n fields. That is, this digraph causes the internal field pointer to be incremented by n . The digraph is not stored in the input buffer. For example, the following line will cause the number 5 to be placed in field 1 and the number 9 to be placed in field 7.

                param 5 $5 9

Field position control: *n

The digraph * n in the input line is interpreted as a signal to set the internal field position pointer at n . Data immediately following this digraph will be placed in field n of the input buffer. For example, *10 places the next string encountered into field 10. Field position strings are not stored in the input buffer. Once set, subsequent fields are stored in n +1, n +2, etc. unless another field pointer directive is entered. For example,

              map 2.6 *6 C $5 1 .31

will result in the number 2.6being stored in field 1, the character Cbeing stored in field 6, and the numbers 1.and 0.31being stored in fields 12 and 13, respectively. All input fields except 1, 6, 12, and 13 will be set to void. Note that field position numbers do not have to be used in ascending order. The above data input could be entered as:.

              map *6 C *1 2.6  *12 1 .31                

Input line delimiter character: ' :'

The character colon (:) is used to signal the end of input fields. Note that a colon in column 1 of a line implies that the line is to be ignored. The colon allows additional unprocessed information to be placed on the input image. For example, the image containing the following line is processed only through to the field containing .035.

       atom C12 .5 .6 .9 .035 
:new site at -x, -y,
z
       :pig 
:pig is disabled by the
colon