|
CRYSTALS Contents+ Frequently Asked Questions + Crystals Primer + Crystals User Guide + Cameron Manual + Menu and toolbar + Getting Started + Crystals Worked Examples + IndexManuals built:
|
Crystals ManualChapter 3: The Crystals Database
It is a direct-access binary file. DO NOT try to print or edit it. The data is organised in this file as lists, corresponding to the
external user-input lists. In modern terminology, these 'lists'
would be called 'objects' or 'data structures'. Each list groups
together related information, e.g. the cell parameters, the atoms,
the reflections etc.
In the CRYSTALS system, most of the data required to refine a crystal structure must be input to the computer as ASCII, translated into an internal format and stored on a random access disk file. On the disk, different types of data are recorded separately, in what are called LISTS. Each list holds only one type of crystallographic information and is identified by a number called the 'list type number'. Normally, each structure uses a separate disk file, which is preserved between different jobs and updated whenever a program generates some new data. This means that several different versions of a given list may be produced during the course of a structure analysis. In order that each list may be uniquely identified, every list has associated with it a second number, called the 'list serial number'. To specify unambiguously a list that is stored in the database, it is necessary to know both the relevant list type number and the list serial number. In most cases, however, the version of a given list that is required is the latest list of that type to be created. Accordingly, an index called the 'current list index' is maintained, which contains an entry for the latest version of each list. When a program requires information about the current version of a list, it accesses the current list index. As well as an index of the current version of each list, a second index is kept, called the 'file index'. For each disk file, this latter index contains the information for every list that is present in the database. This index is always checked when a list is written to the database, to ensure that its list type number and list serial number refer to only one list. For a user, the major advantage of splitting the input data into logical units in the database is that, for any run, only those lists which need to be changed have to be re-input to the database. New versions of each list that are generated by programs are automatically output to the database so that, provided the database file is not destroyed or erased, it is probable that each run will contain only control commands. For example, during a structure factor least squares calculation a new set of Fcalcs and a new normal matrix will be generated and stored in the database ready for further calculations. Old versions of a list may be reused, provided that they have not been overwritten or deleted, by finding the relevant entry in the file index and copying it into the current list index. The database contains two indices which control access to it. Current List Index
This index contains the serial numbers of each list to be used in calculations. This index is updated whenever a list is written to database. Disk Index This is an index of all the lists contained in the database. When a
new list is added to the database, its internal address is added to this
index, and also inserted into the current disk index. It is possible to
copy address from this index to the current disk index, thus changing
the currently active version of a list.
[Top] [Index] Manuals generated on Wednesday 27 April 2011 3.1: General List-control Directives - \DISKThe list control table can be marked and used in various ways with this command. \DISK PRINT INDEX= PUNCH= LIST= MARKERROR LIST= SERIAL= RELATIVE= ACTION= RETAIN LIST= SERIAL= RELATIVE= ACTION= DELETE LIST= SERIAL= RELATIVE= ACTION= RESET LIST= SERIAL= RELATIVE= USAGE LIST= SERIAL= RELATIVE= FLAG= EXTEND RECORDS= FREE= TRIES= SIZE= CHECK END
\DISK \ Print the current list index PRINT INDEX=CURRENT \ Print the index containing all the lists stored \ on the disk PRINT INDEX=DISK \ Reset LIST 5 (the model parameters) to the one with serial number 4 RESET 5 4 \ Reset LIST 10 (Fourier peaks) to the 'current serial number - 1' RESET 10 0 -1 \ Retain LIST 5 with serial number 6 when the disk \ is purged RETAIN 5 6 \ Delete current LIST 11 (normal/inverted least squares matrix) DELETE 11 END
\DISK
This is the command which initiates the routines to modify the list control table. The directives MARKERROR, DELETE, RETAIN, USAGE, and RESET all accept the parameters SERIAL and RELATIVE. The parameters SERIAL and RELATIVE should not both be changed from their default settings on the same directive. All directives are executed immediately after they have been entered. PRINT INDEX=
This directive causes one of the indexes to be printed. INDEX=
CURRENT - default value
DISK
SUMMARY
PUNCH=
NO - default value
YES
MARKERROR LIST= SERIAL= RELATIVE= ACTION=
This directive can either mark a specified type of list as an 'error list', or alternatively, such a mark can be removed from the list control table. LIST=n
'n' is the list type number (there is no default value).
SERIAL=n
'n' is the list serial number. The default value is zero, which
represents the serial number of the current list of this type.
RELATIVE=n
'n' is the offset applied to the serial. The default value
is 0. If both SERIAL and RELATIVE are zero (the defaults)
the current list of the specified type will be
the one that is marked.
ACTION=
NO
YES - default value
RETAIN LIST= SERIAL= RELATIVE= ACTION=
With this directive, certain old versions of specified lists can be retained when the disk file is PURGED (see 3.2). LIST=n
'n' is the list type number (there is no default value).
SERIAL=n
See markerror definition above (3.1).
RELATIVE=
See markerror definition above (3.1).
ACTION=
NO
YES - default value
DELETE LIST= SERIAL= RELATIVE= ACTION=
With this directive certain lists can be deleted from the file index. LIST=
See markerror definition above (3.1).
SERIAL=
See markerror definition above (3.1).
RELATIVE=
See markerror definition above (3.1).
ACTION=
NO
YES - default value
RESET LIST= SERIAL= RELATIVE=
This directive alters the entry for the list type in the
current list index.
LIST=
This parameter is the list type number,
for which there is no default value.
SERIAL=
See markerror definition above (3.1).
RELATIVE=
See markerror definition above (3.1).
USAGE LIST= SERIAL= RELATIVE= FLAG=
This directive alters the list write/overwrite flag.
LIST=n
'n' is the list type number
(there is no default value).
SERIAL=
See markerror definition above (3.1).
RELATIVE=
See markerror definition above (3.1).
FLAG=
OVERWRITE
READY
UPDATE - default value.
EXTEND RECORDS= FREE= TRIES= SIZE=
This directive
allows the user to extend the database by a specified number
of records, and to control the auto-extension. On modern
platforms the extension of the database is automatic by
default.
RECORDS=
This parameter specifies a number of records to be added to the
file. The default value is zero i.e. no records are added.
FREE=
This parameter specifies a number of records that must be available
for use in the file. The file will be extended until there are at
least 'FREE' records unused after the next free disk address.
TRIES=
This is the number of times the system may try adding 'SIZE' records to
the disk file to achieve enough space for the current operation. Usual
default is 1.
SIZE=
This is the size, in records, that the system will increase the disk by
to try to accommodate the current operation. The usual default is 5.
If the write still fails after TRIES x SIZE records have been added it
produces an error. Setting SIZE to zero enables uncontrolled
extension of the disk file. This is the default, but if the
user gets carried away doing crystallography, they may fill their
disk.
CHECK
This directive checks the integrity of the disk file. It takes
no parameters.
Errors in the DISK file.
If CRYSTALS
reports errors in the disk file, run this utility to get a list of those
LISTS corrupted. Use \PUNCH 5, \PUNCH 12 and \PUNCH 16 to make ASCII
copies of these important lists (by default output to the 'punch'
file, bfile.pch - rename it after punching to e.g. 'savedlists.pch').
If the final version
of a list is corrupt, use \DISK RESET (see above 3.1) to point
the program
to an earlier version and punch that instead.
If the disk file becomes totally
unusable, delete it, read in the reflections again, and then read in
these 'punched' lists (\USE savedlists.pch).
If only certain lists are unusable, use the DELETE directive in \DISK to mark defective LISTS for deletion, and then use \PURGE NEW to create a new disk file (by default new.dsc). Rename new.dsc to crfilev2.dsc to make CRYSTALS open it by default when it starts in that directory. The following lists can always safely be deleted since CRYSTALS creates new ones automatically.
Example 1
Imagine that the current versions of LIST 5 (the model parameters)
and LIST 29 (element properties) have beome corrupt.
We will also delete any recreatable lists.
\DISK
\ Check the index
CHECK
\ Delete current version of atomic params
DEL 5
\ Point index to the previous version
RESET 5 0 -1
\ Remove corrupt and safe-to-delete lists:
DEL 29
DEL 10
DEL 11
DEL 20
DEL 22
DEL 24
DEL 26
DEL 33
DEL 36
END
\ Open a new file save.dat on the 'PUNCH device'.
\ Release is equivalent to CLOSE followed by OPEN.
\RELEASE PUNCH SAVE.DAT
\ Output the important data lists:
\PUNCH 5
END
\PUNCH 12
END
\PUNCH 16
END
\ Write a new database called rescue.dsc with only the
\ current index of lists in it:
\PURGE RESCUE
\ Close CRYSTALS
\FINISH
del crfilev2.dsc
ren rescue.dsc crfilev2.dsc
\USE save.dat
[Top] [Index] Manuals generated on Wednesday 27 April 2011 3.2: Elimination of Old Versions of LISTS - \PURGE\PURGE FILE= INITIALSIZE= LOG= LIST= END
\PURGE
This command deletes all but the current version of each list, and any lists explicitly marked to be deleted, except for lists marked to be retained, and then rewrites the disk file so that the space occupied by the old deleted lists is overwritten. This operation does not normally shorten the file physically (see parameter FILE below for a method of doing this) , but frees a lot of space that can be reused. The optional parameters 'FILE' and 'INITIALSIZE' (available in some implementations only), allow the user to create a new file with only the current version of each list in it. This file may be smaller than the original disk file. FILE=
OLD - default value
name - The root to be used form the new database - name.DSC
DATE - The root name is generated by CRYSTALS from the date and
time.
This parameter controls whether a new file is created. If the value specified is not OLD, a new file will be created containing only the current versions of each list, and any which are marked to be retained. The program automatically extends the file to the size required for all the lists to be retained. This new file has the extension .DSC, and may be used in future CRYSTALS tasks. INITIALSIZE=
This parameter is used to specify an initial size for a new file. If a new file is not to be created, the value is ignored. The default value of zero causes the new file to have the smallest size necessary to contain all the copied lists. LOG=
OFF - default value
ON
If the value 'ON' is given for this parameter, the types and serial numbers of all lists deleted because they were old versions are listed. The types and serials of all lists not copied for other reasons, e.g. deleted lists, and lists which are marked as being updated, are always listed [Top] [Index] Manuals generated on Wednesday 27 April 2011 3.3: LISTS in Current useList Number Type of data 1 Cell parameters (section 4.2) 2 Unit cell symmetry (section 4.8) 3 Atomic scattering factors (section 4.11) 4 Weighting parameters (section 7.28) 5 The model parameters (section 6.3) 6 Reflection data (section 5.3) 7 Reflection data not used for refinement (section 5.4) 10 Peak coordinates from Fourier (section 8.7) 11 Least squares matrix (section 7.51) 12 Refinement directives (section 7.11) 13 Crystal and collection data (section 4.13) 14 Fourier directives (section 8.2) 16 General Restraints (section 7.17) 17 Special Restraints (section 7.24) 18 SMILEs string representation (section 4.15) 20* Transformation matrices saved by \GEOMETRY (section 9.6) 22* Refinement directives in internal format (section 7.51) 23 Structure factor control list (section 7.7) 24* Least squares shift list (section 7.51) 25 Twin component operators (section 10.0) 26* Constraints in internal format (section 7.51) 27 Diffractometer scales (section 5.12) 28 Reflection condition/filter list (section 7.40) 29 Contents of asymmetric unit and elemental properties (section 4.18) 30 General information (section 4.20) 31 Cell parameter E.S.D.'s (section 4.5) 33* Internal - Refinement control (last SFLS command, see 7.43) 36* Tracking interdependencies of parameters, normal matrix, weights etc. 40 Bond forming/breaking directives (section 6.16) 41* Bonds between atoms (section 6.15) [Top] [Index] Manuals generated on Wednesday 27 April 2011 3.4: Printed Summary of Data lists\SUMMARY OF= TYPE= LEVEL= END
\ Detailed list of model parameters: \SUMMARY OF=LIST TYPE=5 LEVEL=HIGH END \ Again, but less typing: \SUM L 5 HI END \ Summary of reflection data: \SUM L 6 END
\SUMMARY OF= TYPE= LEVEL=
OF=
This parameter determines the extent of the data summary.
LIST
EVERYTHING
If 'LIST' is specified, a summary of a specific list whose type is given by the 'TYPE' parameter is produced. If 'EVERYTHING' is specified, a summary of all current lists for which summaries are available is produced. If 'OF = EVERYTHING' is specified, the value of 'TYPE' is ignored. TYPE=
This parameter indicates the
list type for which a summary is required. If a summary of this list
type is not available, a warning message will be printed.
LEVEL=
LOW
MEDIUM
HIGH
List Level Data printed ---- ----- ---- ------- 5 or 10 LOW Atom names 5 or 10 MEDIUM Atom names and positional parameters 5 or 10 HIGH All atomic and overall parameters [Top] [Index] Manuals generated on Wednesday 27 April 2011 3.5: Element and Atom namesElement Names
Elements are specified by a name, called the atom TYPE. The
'TYPE' is used to associate the refined atoms with atomic properties,
such as form factors, radii, etc. The TYPE must start with a letter,
and is not case sensitive.
REMEMBER that 'blank'
is used as a delimiter in CRYSTALS and so must
not appear in an atom TYPE. Elements in the form factor list (LIST 3 - see
section 4.11)
and the atomic properties (LIST 29 - section 4.18) are associated by
their TYPE with atoms in the parameter list (LIST 5). Numeric properties of the
elements are pre-prepared in the files SCATT, SCATCU, SCATMO and
PROPERTI(.dat) in the SCRIPT directory (Often CRYSTALS\SCRIPT). The
'elements' C', C", H' and H" are in these files with the properties of C and H.
You can define your own element names, but may not use +,- or *.
Atom names
Individual atoms are specified by combining the TYPE with a SERIAL number. This is an integer in the range 1-9999. When combined with the TYPE, it must be enclosed in parentheses (). e.g. C(2) CL(123)
Symmetry equivalent atoms
Atoms specified as above correspond exactly to those in the refinable atom list (LIST 5). If a symmetry equivalent atom is required, up to 5 additional items are included inside the parentheses. The full specification of an atom is:
TYPE(SERIAL,S,L,Tx,Ty,Tz)
S
is the serial number of the symmetry operator in the stored list of
space group operators. If negative, it indicates that the atom
coordinates are first negated before being operated upon. The default is
1
L
is the serial number of the non-centring lattice translation to be
used. The default is 1.
Tx,Ty,Yz
are whole cell translations parallel to the cell axes. The
default is 0.
If the value of an item is its default, it may be omitted altogether, though its place must be marked by its associated comma. A series of trailing commas may also be omitted. For example:
C(99,-1,1,0,0,0) - an atom related by inversion at the origin
(assuming x,y,z is the first operator).
C(99,-1,1,,,0) - same atom as above, omitting defaults.
C(99,-1) - same atom as above, omitting
defaults and trailing commas.
For more detailed information, see Atomic and
Structural parameters (section 6.0)
[Top] [Index] Manuals generated on Wednesday 27 April 2011 3.6: Foreign Program Links\FOREIGN
This command provides links to 'FOREIGN' programs, that is, programs which are not part of CRYSTALS, but which provide useful functions in providing a complete system. These programs often come from other laboratories, and are only distributed with the authors permission unless they are public domain. Where practical, we make no changes to the original code. We offer little or no support in connection with these programs, though usually they are in frequent use in Oxford. The linking routine prepares data files for the foreign program, and may initiate a subprocess to execute the rogram. PROGRAM=
SNOOPI - A plotting program using Tektronix 4010 devices.
CAMERON - An interactive graohics program.
MULTAN - Prepares files for MULTAN 84.
SHELXS - Prepares files for SHELXS.
SIRxx - Prepares files for the SIR direct methods system
MODE=
This keyword controls the mode of operation of the foreign program. It currently only applies to SHELXS and SIR.
NORMAL - DEFAULT, prepares a default data file with recommended
settings.
DIFFICULT - Prepares a file with non-default settings.
PATTERSON - Prepares a default Patterson calculation (SHELXS only).
SPECIAL - Prepares a full SHELX data file (SHELX only)
|
© Copyright Chemical Crystallography Laboratory, Oxford, 2011. Comments or queries to Richard Cooper - richard.cooper@chem.ox.ac.uk Telephone +44 1865 285019. This page last changed on Wednesday 27 April 2011.