Chemical Crystallography   Chemical Crystallography  

Crystals Now!
 
Manuals NOW!

Crystals Manual

Chapter 3: The Crystals Data-Base

3.1: General List-control Directives - \DISK

3.2: Elimination of Old Versions of LISTS - \PURGE

3.3: LISTS in Current use

3.4: Printed Summary of Data lists

3.5: Element and Atom names

3.6: Foreign Program Links

It is quite possible to use CRYSTALS so that all the data is read from text files at the start of every job (as in SHELXL). However, for interactive working, it is preferable to establsh a data-base of crystallographic information which can be used whenever it is needed. This data-base is called the CRYSTALS 'disk' file. It is usualy a permanent file on the hard disk, and usually has the extension '.DSC'.
  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. While in general input of a list will overwrite a previous version, for the atomic coordinate list, LIST 5, a new version is added to the data-base. In the event that a refinement goes wrong, the user can usually recover an earlier version of the structure.

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 instructions. For example, during a ructure 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 data-base 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 data-base. 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 Wed Jun 6 2001

3.1: General List-control Directives - \DISK

The list control table can be marked and used in various ways with this instruction.

  \DISK
  PRINT INDEX=
  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 the index containing all the lists stored
  \ on the disk
  \ Reset LIST 5 to the one with serial number 4
  \ Reset LIST 10 to the 'current serial number - 1'
  \ Retain LIST 5 with serial number 6 when the disk
  \ is purged
  \ Delete current LIST 11
  \
  PRINT INDEX=CURRENT
  PRINT INDEX=DISK
  RESET 5 4
  RESET 10 0 -1
  RETAIN 5 6
  DELETE 11
 

 

 
\DISK

This is the instruction 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 instruction causes one of the indexes to be printed.
INDEX=

       CURRENT  -  default value
       DISK
       SUMMARY
 

 
If INDEX is CURRENT, the current list index is printed (i.e. The index containing the currentn of each list stored). If INDEX is DISK , the index containing information about all the lists stored on the disk is printed. If INDEX is SUMMARY , a summary of the usage of the disk file is printed.
 
MARKERROR LIST= SERIAL= RELATIVE= ACTION=

This instruction 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= This parameter is the list type number for which there is no default value.
SERIAL= This parameter is the list serial number. The default value is zero, which represents the serial number of the current list of this type.
RELATIVE= This parameter is the offset applied to the serial. The default value is 0. If both SERIAL and RELATIVE are zero ( the default settings ) the current list of the specified type will be changed.
ACTION=

       NO
       YES  -  default value
 

 
If ACTION is NO , the entry in the list control table for the list type specified is altered so that it is not marked as an 'error list'. If ACTION is YES, the entry in the list control table for the list type specified is altered so that it is marked as an 'error list'. If a program attempts to use such a list, an error is reported, and the job terminated.
 

 
RETAIN LIST= SERIAL= RELATIVE= ACTION=

With this instruction, certain old versions of specified lists can be retained when the disk file is PURGED (see below).
LIST= This parameter is the list type number, for which there is no default value.
SERIAL= See above
RELATIVE= See above
ACTION=

       NO
       YES  -  default value
 

 
If ACTION is YES, the list with the specified type and serial number will be retained when the disk file is PURGED. If ACTION is NO , the particular list will be deleted when the disk file is PURGED.
 
DELETE LIST= SERIAL= RELATIVE= ACTION=

With this directive certain lists can be deleted from the file index.
LIST= This parameter is the list type number, for which there is no default value.
SERIAL= See above.
RELATIVE= See above
ACTION=

       NO
       YES  -  default value
 

 
If ACTION is YES, the list with the specified serial number will be marked to be deleted from the file when the file is PURGED. If ACTION is NO , the specified list will not be marked as one to be deleted when the disk file is PURGED .
 
RESET LIST= SERIAL= RELATIVE= This instruction 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 above
RELATIVE= See above
 
USAGE LIST= SERIAL= RELATIVE= FLAG= This instruction alters the list write/overwrite flag.
LIST= This parameter is the list type number, for which there is no default value.
SERIAL= See above
RELATIVE= See above
FLAG=
       OVERWRITE
       READY
       UPDATE  -  default value.
 

 

 
EXTEND RECORDS= FREE= TRIES= SIZE= This instruction ( only available in some implementations ) allows the user to extend a disk file by a specified number of records, and to control the auto-extension.
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 time 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 accomodate the current operation. The usual default is 5. If the write still fails after TRIES x SIZE records have been added, an error is signaled. Setting SIZE to zero enables uncontrolled extension of the disk file. This may be a useful but dangerous option!!
 

 
CHECK This directive checks the integrity of the disk file.
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. If the final versionof a list is corrupt, use RESET point to an earlier version and punch that. If the disk file becomes totally unusable, delete it, read in the reflections again, and then read in these 'punched' lists. Use the DELETE directive in \DISK to mark defective LISTS for deletion, and then use \PURGE NEW to create a new disk file.
  The following lists can always safely be deleted since CRYSTALS creates
  new ones automatically.
 
       10, 11, 20, 22, 24, 26, 33, 36
 

 

EXAMPLE

 Imagine that the current versions of LIST 5 and LISY 29 have beome corrupt.
 We will also delete any recreatable lists.
 
       \DISK
       CHECK
       DEL 5
       RESET 5 0 -1
       DEL 29
       DEL 10
       DEL 11
       DEL 20
       DEL 22
       DEL 24
       DEL 26
       DEL 33
       DEL 36
       \RELEASE PUNCH SAVE.DAT
       \PUNCH 5
       \PUNCH 12
       \PUNCH 16
       \PURGE RESCUE
       \FINISH
 

 
At this point it would be useful on a stand-alone computer to run a system utility (e.g. SCANDISK on a PC) to check the integrity of the computers hard disk, since CRYSTALS rarely corrupts the disk itself.
 

[Top] [Index] Manuals generated on Wed Jun 6 2001

3.2: Elimination of Old Versions of LISTS - \PURGE

  \PURGE FILE= INITIALSIZE= LOG= LIST=
  END
 

 

 
\PURGE

This instruction 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. ( This option is only available in some implementations ). 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
LIST = n

'n' is the type of list to be purged, and all generations of other lists are preserved. If LIST=0 (the default value) lists of all types are purged.
 

 


[Top] [Index] Manuals generated on Wed Jun 6 2001

3.3: LISTS in Current use

     Lists marked * cannot be input by the User
     Lists marked \ are not currently available
 
    List  type of data
   Number
 
      1    Cell parameters
      2    Unit cell symmetry
      3    Atomic scattering factors
      4    Weighting parameters
      5    Atomic parameters
      6    Reflection data
      7\   Reflection data not used for refinement
     10    Peak coordinates from Fourier
     11    Least squares matrix
     12    Refinement directives
     13    Crystal and collection data
     14    Fourier directives
     16    General Restraint instructions
     17    Special Restraint instructions
     22*   Refinement directives in internal format
     23    Structure factor control list
     24*   Least squares shift list
     25    Twin component operators
     26*   Constraints in internal format
     27    Diffractometer scales
     28    Reflection condition list
     29    Contents of asymmetric unit and elemental properties
     30    General information
     31    Cell parameter E.S.D.'s
     33*   Internal - Refinement control
 

 

 

[Top] [Index] Manuals generated on Wed Jun 6 2001

3.4: Printed Summary of Data lists


 
\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=

This parameter has three values which indicate the level of detail required in the data summary. The parameter is ignored unless the list type is 5 or 10.

       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 Wed Jun 6 2001

3.5: Element and Atom names


 

 
Element 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) and the atomic properties (LIST 29) 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 ().

        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.

It 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.

        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)
        C(99,-1)
 

 

For more detailed information, see Atomic and Structural parameters.
 


[Top] [Index] Manuals generated on Wed Jun 6 2001

3.6: Foreign Program Links


 
\FOREIGN

This Instruction provides links to 'FOREIGN' programs, that is, programs which are not part of CRYSTALS, but which provide usefull 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, under VAX VMS, initiate a subprocess to execute the program.
PROGRAM=

       SNOOPI  - A plotting program using Tektronix 4010 devices.
       CAMEON  - 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
       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, 2002
Comments or queries to Richard Cooper - richard.cooper@chem.ox.ac.uk Telephone +44 1865 270835
This page last changed on Wednesday 6 June 2001.
The website was re-generated on Friday 15 February 2002.
Mirrors: [ Original | CCP14 UK Web Mirror | CCP14 Australian Mirror | CCP14 Canadian Mirror ]