Crystals User Guide

Chapter 1: The Crystals User Guide

1.1: EXAMPLE

1.2: The disk file

1.3: The output files

1.4: The work files

1.5: The HELP facility

1.6: The manual

1.7: SYSTEM instructions

*************************************************************************
This document is still under revision
*************************************************************************

The CRYSTALS package is being developed to meet the need of both experienced and new crystallographers. Because it is a very large system, the range of options available may daunt newcomers. For such users, CRYSTALS is distributed with a worked example, on-line HELP files (which may of course be printed out) and this Guide.

The new \SCRIPT instructions are prototypes for an interogative interface, in which the user is offered short menues of commands, and prompted for data. THESE ARE STILL ONLY PROTOTYPES to what we hope will be a computer aided teaching system, but even in their present form they may help beginners get going.

There is a myth that CRYSTALS is more difficult to use than SHELX. We hope the following example will correct this misunderstanding. This example does not, of course, show any of the advanced features of CRYSTALS nor the easy links between CRYSTALS and direct Methods programs.
 
Emulation of SHELX
 
A Worked example

CRYSTALS will not emulate SHELX completely, - in particular there is no Direct Methods code, but for most other SHELX operations, there is a good correspondence plus many other options. The input to CRYSTALS is longer, but the directive names should make it easier to remember what must be input. Once the basic data has been loaded, many operations are very quickly requested.
 

In these examples, comments have been added to the data file in lower case.
 

 
SHELX example

This example is based on a SHELX manual example. The space group is Pbcn with four molecules of C13,H8,O,I2 per cell. Systematic absences are rejeceted, equivalent reflections averaged, and reflections less than 2.5 sigma(F) suppressed. The structure is refined by 4 cycles of full matrix least squares with anisotropic I and weight 'optimisation'. C7 and O1 lie on special positions with crystallographic site occupancy of .5. Since the chemical occupancy is unity, no special actipn is needed in CRYSTALS. C1, C3 and C5 are used to define a regular hexagon which is refined as a rigid group. Bond lengths, angles and esd's are computed, followed be a weighted difference map, peak search and molecule assembly. The atoms and peaks are plotted on the line printer, and 2 copies of the structure factors are printed. Site occupation factors are 1 and U[iso] is .05 for the phenyl group.

X
 TITL 3,3'-DIIODOBENZOPHENONE
 CELL 0.71069 4.05 11.74 24.80 90 90 90
 SYMM .5-X, .5-Y, .5+Z
 SYMM .5+X, .5-Y, -Z
 SYMM -X, Y, .5-Z
                    scattering factors built into program
 SFAC C H O
 SFAC I 20.1472 4.347 18.9949 .3814 7.5138 27.766 2.2735 =
     66.8776 4.0712 -.726 1.812 7246 1.5 (MOKALPHA)
 UNIT 52 32 4 8
 HKLF 4
                                minimum F/sigma(F) is 2.5
 MERGE -2 2.5
 L.S. -4
 WGHT -.001 2
 FVAR .879 1.0
              fix the I occupation number, and refine the 
                          anisotropic temperature factors
 ANIS 1
 I 4 .342 .158 .044 11 .054
                            generate a phenyl nucleus and 
                                     refine it as a group
 AFIX 76
 C1 1 .009 .074 .197
                                             a dummy atom
 C2 1 0 0 0
 C3 1 -.128 -.082 .139
                                             a dummy atom
 C4 1 0 0 0
 C5 1 .156 .018 .103
                                             a dummy atom
 C6 1 0 0 0
                                            refine freely
 AFIX 0
                          fix next two atoms at x=0,z=.25 
                       with fixed occupation number of .5
 C7 1 10 .136 10.25 10.5 .056
 O1 3 10 .239 10.25 10.5 .071
 BOND .5
                           specify details of Fourier map
 FMAP 2 1 13 50 0.3
                         specify volume of map to compute
 GRID -5 -2 -1 5 2 1
                            assemble molecule and plot it
 PLAN 15
 LIST 1 -2
 END

The corresponding CRYSTALS input file. The reflections are in the file REFLECTIONS.DAT

X
 \TITLE 3,3'-DIIODOBENZOPHENONE
 \ load the basic crystallographic data. 
 \ This is only done once.
 \QUICKSTART
 CELL 4.05 11.74 24.80
 SPACEGROUP P b c n
 CONTENT C 13 H 8 O I 2
 DATA 1.5418 I
 FILE CRDIR:REFLECTIONS.DAT
 FORMAT (3F4, 2X, 2F8.2)
 END
 \ set the minimum I/sigma(I) to be used. 
 \ This can be reset at any time
 \LIST 28
 MINIMA RATIO=2.5
 \LIST 5
 OVERALL SCALE=.879
 READ NATOM=6
 \ Input the known model. 
 \ Some of the 'keyword =' are redundant
 ATOM I 1 U[ISO]=.054 X=.342 Y=.158 Z=.044 
 ATOM O 1 U[ISO]= .071  0 .239 0.25 
 ATOM C 7 U[ISO]= .056 0. .136 0.25 
 ATOM C 1 X= .009 .074 .197
 ATOM C 3 X= -.128 -.082 .139
 ATOM C 5 X= .156 .018 .103
 \ generate the phenyl nucleus
 \REGULARISE REPLACE
 GROUP 6
 OLD C(1) C(2) C(3) C(4) C(5) C(6)
 PHENYL
 \LIST 12
 FULL I(1,X'S,U'S) C(7,X'S) O(1,Y) O(1,U[ISO]) UNTIL C(6)
 GROUP C(1) UNTIL C(6)
 \ generate the special position restraints
 \SPECIAL
 END
 \SFLS
 REFINE
 REFINE
 REFINE
 \LIST 4
 \ automatic re-weighting before the final cycle
 SCHEME 10 NPARAM=4
 \SFLS
 REFINE
 \DIST
 E.S.D YES
 \ compute final structure factors for the latest model
 \SFLS
 CALC
 \FOURIER
 MAP TYPE=DIFF
 REFLECT WEIGHT=SIM
 PEAKS HEIGHT=.3 NPEAK=50 
 \PEAKS
 \ assemble a molecule
 \COLLECT
 \ plot all the atoms and peaks onto their best plane
 \MOLAX
 ATOM FIRST UNTIL LAST
 PLOT
 \ analysis of variance
 \ANALYSE
 \ reflection listing
 \REFLECTIONS
 \FINISH

CRYSTALS contains routines for performing most parts of a structure analysis with the exceptions of diffractometer data pre-processing, analytical absorption corrections, Direct Methods and interactive computer graphics. Excellent programs for direct methods and graphics are available from groups specialising in those areas, and initial data processing tend to be rather site specific.

The code has been written to be efficient in the maths and data handling, and robust and informative in the user interaction. There are no intrinsic limits on the numbers of atoms, reflections or refined parameters. Only one array need be redimensioned to increase the size of matrix handled. The current limit is 512 variables in a single block. However, such a task would probably be ill-considered. CRYSTALS has been used to refine large molecules, such as Insulin.
 

Plain language keyed free format input, unified command syntax for batch and interactive modes, parameter defaults, data checking, plain text error messages, 'data subroutine' libraries, data libaries, data-base management and an optional interogative user interface.
 

Extensive documentation, including a 250 page manual, this Guide, user modifiable HELP files, interactive querying for instructions and keywords, examples and test decks.
 

Simple syntax for refering to individual atoms, and to groups of atoms, with or without the application of symmetry.
 

Data reduction of photographic and diffractometer data, including empirical absorption corrections. Application of decay curves, rejection of systematic absences, merging of equivalent reflections with special treatment of outliers, processing of both X-ray and neutron diffraction data.
 

Structural parameter editor for modifying individual parameters, atoms or groups of atoms. Modifications available include: addition, subtraction, multiplication, division of parameters; application of matrices to coodinates; renaming, deletion, reordering generation of atoms; application of symmetry operators; selection by type or parameter value; interconversion between U[aniso] and U[equiv]
 

Structural analysis and model building. Best line and plane through groups of atoms, projection of other atoms onto these planes, forcing planarity onto parts of structure. TLS analysis of groups of atoms, forcing U[aniso] for groups to conform to rigid body motion. Comparison between a group of atoms and another group, a geometric figure or structure from the literature. Model a group of atoms onto another group, figure or structure. Geometric hydrogen and other atom placing.
 

Reflections to be skipped or included are selected individually or by tests. Testable parameters include Fo, Fc, sigma, I/sigma(I), phase, sin theta, index, zone, etc. The test conditions can be changed at any time without loss of data.
 

Restrained refinement. Distances and angles restrained to numeric values or their mean values; components of U[aniso] along bonds; planarity of groups; sums and averages of parameters; shift limiting restraints; and user defined FORTRAN-like expressions given as data.
 

Highly flexible least-squares process. User can define up to 256 blocks per cycle. Blocks can be as small as one parameter per block, one atom per block, or full matrix, or any intermediate combination of parameters. Any atom parameter shifts (X's, U's, Occ) can be equivalenced, linked, made to ride. Parameters can be redefined as sums and diferences. Atoms can be refined as rigid groups. Shift multipliers can be applied, the current matrix can be re-used, structure factors need only be calculated for partial structures. Data for up to 8 twin components can be refined. Refinable parameters include overall scale, overall Uiso, Dummy Uiso, Larson extinction, Rogers polarity, Flack enantiopole, batch scales, layer scales, twin components, x, y, z, Occ, Uiso, Uaniso.
 

15 weighting schemes are available, including statistical, unit, Hughes Cruickshank and Dunitz schemes. Weighting optimisation via a Chebychev polynomial, checking for outliers by the method of Tukey and Prince, can be used to to get 'correct' parameter esds. Analysis of residuals by Fo, sintheta, index, class, parity.
 

Fourier maps are computed with any number of points at any resolution along x, y, z. Map types are Fo, Fc, Fo-Fc, 2Fo-Fc, Fo**2, Fc**2. Maps can be weighted, including Sim weighting. Peak search gives indication of peak quality. Automatic Fourier refinement, peak rejection and molecule assembly. Lineprinter and VDU plots of atoms and peaks.
 

Comprehensive distance and angle calculation, with selection by atom type, interatomic distance, connectivity, inter molecular, intramolecular. Symmetry included. Esds from the full variance-covariance matrix. Torsion angles, planes, lines, TLS (with bond correction), principal axes of Uaniso.
 

Publication listings of atomic parameters, distances, angles, torsion angles, reflections.
 

 
A strategy for structure analysis
 

An over all scheme for a well behaved structure analaysis is:

X
 1. Select the best crystal you can find. This is your primary
 data source, and determines the quality and ease of the rest
 of the procedure. Complex mathematics is a poor substitute 
 for good experimental practices.
 
 2. Collect the best data you can. Collect some (at least 10%)
 equivalent reflections for an indication of the data quality.
 Collect systematic absences for glide planes  and screw axes.
 Collect systematic absences for centred cells out to theta =
 theta(max)/2.
 
 3. Preprocess the reflection data with some local software to 
 get a file of h, k, l, I, sigma(I), and setting angles if 
 these are needed for some geometry dependent absorption 
 correction.
 
 4. Use CRYSTALS to do data reduction, and submit a Direct 
 Methods job with MULTAN, SHELXS, or SIR.
 
 5. If Direct Methods fail, check the data, space group, 
 crystal density, data reduction process. If these are all 
 OK, use CRYSTALS or SHELXS to compute a Patterson  map. 
 Seek help.
 
 6. Input the trial structure to CRYSTALS and perform Fourier 
 refinement. IT IS IMPORTANT to realize that though least 
 squares refinement is often used early in a refinement, there
 is no guarantee that it will converge, and in fact the results
 may actually be mis-leading. Proceed to refinement with care.
 
 7. Compare the final results critically with your expectations.
 An unusual effect in part of the structure, even if of no 
 direct interest for the current investigation, may be 
 symptomatic of a faulty refinement.

The CRYSTALS system can be used in many ways. The program can be used in batch and interactively - the best solution probably being a combination of both modes. Each CRYSTALS job may be made independent of preceeding jobs by inputing all numeric data from card image files at the start of each job, or the analysis may be carried out as a cumulative process, with the results of each stage being held in a binary data file. Data is inserted into this file by reading it from a card image file, from the terminal, or as a result of a succesful calculation. Data in this file can always be listed to a terminal or printer, or output as a card image file for archiving and communication with other programs.

Commands to CRYSTALS may include some numeric data as part of the command, but in general they require that the data has been input previously. The crystallographic routines check for the existence of the necessary data before they start computations, and generate error messages if the data is not available. Batch jobs consisting of multiple commands, which fail through lack of some resource (time, disk space), may usually be restarted after the last succesful command.

The numeric data for CRYSTALS is collected into groups of related parameters, called LISTS. The data is both stored on the disk and represented to the user as LISTS. Thus LIST 5 contains all the refinable parameters, so that the model under refinement is often refered to as 'LIST 5'. In their character representatons, these LISTS may either be typed directly into a running CRYSTALS system, or put into character files using some method provided by the computers operating system.

The following table, which can be displayed online from a running CRYSTALS program by typing \MANUAL LISTS, gives the function of most lists.

 Lists marked * cannot be input by the User
 
 List  Volume   Type of data
 Number  Name
         
   1    VOL2    Cell parameters
   2    VOL2    Unit cell symmetry
   3    VOL2    Atomic scattering factors
   4    VOL5    Weighting parameters
   5    VOL4    Atomic parameters
   6    VOL3    Reflection data
  10*   VOL6(4) Peak coordinates from Fourier
  11    VOL5    Least squares matrix
  12    VOL5    Refinement directives
  13    VOL2    Crystal and collection data
  14    VOL6    Fourier directives
  16    VOL5    General Restraint instructions
  17    VOL5    Special Restraint instructions
  22    VOL5    Refinement directives in internal format
  23    VOL5    Structure factor calculation control list
  24*   VOL5    Least squares shift list
  25    VOL5    Twin component operators
  26*   VOL5    Constraints in internal format
  27    VOL3    Diffractometer scales
  28    VOL5    Reflection condition list
  29    VOL2    Contents of asymmetric unit 
                and elemental properties
  31    VOL2    Cell parameter E.S.D.'s
  33*   VOL5    Internal - Refinement control

This table, available via \MANUAL COMMANDS, lists the commands currently implemented in CRYSTALS.

              Available INSTRUCTIONS
 
 Volume 1      Introduction to the system
 
 \FINISH       \ text     \TITLE        \COMMANDS     
 \HIDE         \SHOW      \LOG          \USE          
 \PAUSE        \TYPE      \MANUAL       \DISK      
 \PURGE        \RELEASE   \SUMMARY      \FOREIGN
 
 Volume 2      Initial data input
 
 \SPACEGROUP  \COMPOSITION \QUICKSTART
 
 Volume 3      Reflection handling
 
 \HKLI         \LP        \SYSTEMATIC   \SORT         
 \MERGE        \REORDER   \REFLECTIONS  \DIFABS
 
 Volume 4      Atomic and structural parameters
 
 \EDIT         \CONVERT   \HYDROGENS    \REGULARISE
 
 Volume 5      Structure factors and refinement
 
 \SFLS         \LIST 22   \LIST 26      \SPECIAL      
 \CHECK        \TRIAL     \ANALYSE      \WEIGHT       
 \CLEAR
 
 Volume 6      Fourier maps
 
 \FOURIER      \SLANT     \PEAKS        \COLLECT      
 \REGROUP
 
 Volume 7      Analysis of results
 
 \AXES         \DISTANCES \MOLAX        \TORSION      
 \PARAMETERS   \ANISO

By default, interactive running of CRYSTALS starts up in 'SRIPT' mode, in which the user is offered short menues of possible actions, and prompted for required data. The action of the program, including the questions posed, the defaults offered and the actions taken, is under the joint control of the user and of data files called SCRIPTS. These are to be found, on the VAX, under the logical name CRSCP:, and look rather like PASCAL programmes. However, they are only data, and the users are encouraged to modify and extend them. Changing these files CANNOT corrupt the CRYSTALS program, though they can of course be made to corrupt data.

The master script, CONTROL, call other scripts in a tree like way, and is perhaps useful for beginners. However, if the user knows the name and function of a sub-script, he can enter it directly from command level with the command '\SCRIPT scriptname'. This list (June 1988) shows what scripts are available.

 CONTROL        CRYSHELP       DATRED         DEVELOP        
 DIFABS         DIFFOUR        DIRECT         EDEMAP         
 EDLIST1        EDLIST29       EDPEAKS        ENDLSQ         
 EXECUTE        FINISH         FOURDEVEL      FOURREF        
 GENERAL        HELP           INCAD4         INFORN         
 INHKLI         INITIALLSQ     INLIST1        INLIST12       
 INLIST13       INLIST14       INLIST2        INLIST23       
 INLIST29       INLIST3        INLIST5        INPUT          
 INSPACE        LISTS          LOOK           MITHRIL        
 MODIFY         MULTAN         NEWMODEL       NEWSTRUCTURE   
 PATTERSON      QUESTIONS      REDFOR         REFINE         
 RENAME         SHELXS         SIR            SOLVE          
 SPAWN          STARTUP        TYPE           USE            
 WEIGHTS        

CRYSTALS can be run in a mixed mode. In this mode, the user initiates an interactive job and then via the USE instruction directs CRYSTALS to take input from the nominated file. If the file ends with \USE CONTROL, control is returned to the interactive terminal, where the user may issue the next instruction, which indeed could be another \USE. USE files may call other files, to a depth of 5, though any file already being USEd may not be called from another in-use USE file (the data stack may not be used recursively). Note that the file being USEd need not be a complete LIST or INSTRUCTION block. It can for example be a single line of data, such as a scattering factor to be included into a LIST 3 from a library. The USE instruction is also available in batch mode.

The user has files of the type 'atom.cu' containing the scattering factor for the given atom with the anomalous component for Cu radiation.

      C.CU contains:
      
 SCATT C 0 0 1.930 12.72 1.878 28.65 1.57 .59 .37 65.03 0.25
 
      The CRYSTALS commands are:
 
 \LIST 3
 READ NSCAT=3
 \USE H.CU
 \USE C.CU
 SCATT F 0 0 3.304 11.265 3.017 4.665 1.357 .338 .836 27.99
 END

The user has in his file store four files :- his DISK file, his initial data (LISTINPUT), his compressed reflections (PLANES), and his current parameters (ATOMS). His aim is to compute structure factors.
 
OPTION 1
 
Use a system facility (such as an editor) to append PLANES and ATOMS to LISTINPUT, and add a final instruction to compute structure factors. Use the resulting file (BIG) as the control file for a batch job.
 
OPTION 2

Initiate an on-line job with BIG as the control file. In an on-line job the user is computing in real time, but the course of the calculation is pre-determined by the control file.
 
OPTION 3

Initiate an interactive job and issue the instruction \USE BIG. An interactive job is one in which control returns to the users terminal at the completion of each task
 
OPTION 4.

Issue 4 sequential batch jobs being respectively controlled by LISTINPUT, PLANES, ATOMS and a file requesting the structure factors.
 
OPTION 5

Initiate an interactive job issuing sequentially \USE LISTINPUT, \USE PLANES, \USE ATOMS and then the instruction to compute structure factors.
 
OPTION 6

Initiate an interactive job and type in all the information from a plain-language listing!
 

The last option is normally the least attractive. However, in the quite possible situation where the reflections are available in a machine-readable form and the atomic coordinates and other data are available in plain-language, the user might well introduce his reflections via a \USE command and type the other data directly into the system. Such a procedure has an advantage over preparing the data file independently (using an editor for example) since CRYSTALS will monitor the input. However, since only syntactically correct information is transfered to the DISK, typing errors lead to the loss of the current item of data. CRYSTALS provides a mechanism for retrieving the partially correct data through the LOG file. Unless the user specifically inhibits it, all data input to CRYSTALS is copied verbatim to a LOG file. Because this is an exact copy of instructions presented to the system, it can itself be used as a control file for a subsequent job. If it is error free, it can be used unmodified, otherwise a service editor may be used to correct it. The basic data file for a structure can thus be assembled by running an interactive job, hooking in via \USE previously archived data such as scattering factors and space group information, and typing in data specific to the compound. The LOG file produced can then be edited to remove the \USE lines leaving only those lines either read from files or input directly. This file would probably end \USE LAST so that it could itself be USEd later.
 

During a given run of CRYSTALS, the program MUST be linked to a direct access file (DISK) holding the data-base for the current structure. This file provides the mechanism for data transfer between different stages of the task, one stage of which may well be the input of the data itself. On sites where users are allocated sufficient file store to preserve their DISK file between jobs, the DISK also provides a mechanism for communicating between jobs. In fact, if the DISK is preserved, CRYSTALS makes no distinction between successive tasks run in the same job and the same tasks run in successive jobs. Instructions exist in CRYSTALS for 'punching' out files containing reflections in various formats, including a compressed format, and the structure coordinates. In most systems, the 'punched' files will remain in the filestore as character (ASCII) files in a format suitable for direct re-input to a subsequent job. If therefore, the user keeps a file of his initial data, such as cell parameters and scattering factors, and terminates each job by outputting his current parameters as a 'punched' file, he is in a position to create a scratch DISK file for the duration of a job, and then delete it at the end. Even if the user is able to preserve his DISK between jobs, it is prudent to punch out the parameters from time to time and keep these in a safe place, together with the initial data and the compressed reflections.

CRYSTALS plain-language output to a number of devices. Depending on the installation and mode of use, one or more of these devices may be a VDU. In the list below, the default VAX file extension is given in parenthesis.
 
PRINTER (.LIS)

This is the main output stream for the system, and contains detailed accounts of the calculation performed.
 
MONITOR (.MON)

This is an abbreviated output, suitable for directing to the VDU in online or interactive modes. For batch mode jobs, it provides a summary of the computation performad.
 
PUNCH (.PCH)

Use for ouputting LISTs in a format suitable for later re-input to CRYSTALS. These files can be used for archiving or communication with other systems. (This is a FORTRAN card image file, so column 1 may not be displayed on some operating systems - it is there though)
 
LOG (.LOG)

A verbatim copy of the input presented to CRYSTALS. It can be used as input for a subsequent job, and is thus a mechanism for rescuing partially correct user input.
 
ERRORS (.ERR)

This only contains operating system error information.
 

The \USE instruction permits the user to feed in input from several different files. The \RELEASE instruction permits the user to disconnect the current PRINTER,PUNCH or MONITOR files from CRYSTALS (new ones are automatically connected). The \TYPE instruction permits the user to examine any file available to him, including a previously RELEASEd file, so that he may examine the output from some earlier part of a task without exiting from CRYSTALS. A long batch job can RELEASE its MONITOR file after, say, each round of refinement so that the user can see how the job is progressing.

CRYSTALS uses a number of work files in the course of most calculations. Of particular interest to the normal user are the sequential files simulating magnetic tapes. Their use in initial reflection processing is explained in the VOL3. The system manager will provide a suitable JCL procedure or program environment to assign these files to scratch files. The user should however be aware of the existence of these files on systems where file store quotas operate. Similar watch should be kept on output files if these are attributed to the user while waiting to be listed.

In general, however, on a well regulated system the user should normally only be concerned with his primary source of reflection data, his initial crystallographic data, his DISK file and those files he creates for controlling individual jobs.

The help facility in CRYSTALS is neither a computer aided learning facility nor a substitute for the manuals, but rather an aide-memoire for the interactive user.

The instruction \HELP HELP lists those facilities for which some descriptive help is provided in the form of hints or tips.

The instruction \MANUAL INDEX explains where definitions of LISTS and INSTRUCTIONS can be found in the manual. The manual is indexed by Volume, Chapter, Section and Page number.

If he can remember which INSTRUCTION he needs to use, the \COMMAND facility will tell the User what DIRECTIVES, KEYWORDS and PARAMETERS are available for that INSTRUCTION. Where appropriate, it will also show default values. In addition, it also gives the values of some data-base and system parameters mainly of use to programmers.

The 'query' facility enables the user to interrogate the data-base. Lines beginning with '?' are not interpreted as data, but generate brief output from the data-base. The user curious about the workings of the input processing routines should read the volume DATABASE in the manual.
 

The manual is in several Volumes, and contains chapters of interest both to users and programmers. It is vital that users become familliar with the following volumes:-

     VOL1     INTRODUCTION
     VOL2     INITIAL
     VOL3     REFLECTIONS
     VOL4     ATOMS
     VOL5     SFLS
     VOL6     FOURIER
     VOL7     RESULTS

The above list is roughly in the order the material should be read, though one would have to read FOURIER to do a Patterson synthesis, possibly before reading about atoms and structure factors. The manual occasionally refers to 'default' values. These values are set at the discretion of the system manager, who may well wish to change them for specfic reasons. The file COMMANDS should be available to show the values currently installed, and the user can always use the \COMMAND facility to obtain unequivocal values.

The manual VOL1 defines the main system INSTRUCTIONS :-
 

 \FINISH \TITLE     \ comment   \SET     \OPEN      
 \HELP   \USE       \PAUSE      \RELEASE \TYPE    
 \MANUAL    \$

The instruction SET MONITOR OFF might well be the first instruction in a file to be USEd to recreate a DISK file, and SET MONITOR ON the penultimate. They would inhibit the listing of information the user knows to be valid, and restore it before returning to the main control stream. Comment lines, which begin \<space>, can be inserted anywhere in the control channel data except in the body of a LIST 6 (reflections), and should be included in all files that are to be archived.

The introduction also defines the LIST input and output instructions:-
 

 \LIST     \PRINT     \PUNCH     \SUMMARY

The \LIST instruction is used to introduce a discrete group of data, called a LIST, into CRYSTALS, which validates it and then stores it on the DISK. Lists can be introduced to the DISK in any order and whenever the user likes, provided that the lists required for a calculation are on the DISK when that calculation is asked for. The program checks that the necessary lists are present before the calculation is started, and warns the user of omissions. All lists stored on the DISK can be PRINTed, though the format is rarely useful for publication purposes( for that, see RESULTS). These listings do however show the value associated with every element of the LIST, including those taken by default or modified by a calculation. \SUMMARY produces a summary of the required LIST. The \PUNCH instruction produces character files suitable for archiving or re-input to CRYSTALS.

The DISK house-keeping can be altered by the instructions:-
 

 \DISK     \PURGE

When the DISK is created, special code is run to allocate space in the file to hold two indices, the DISK index and the CURRENT index. An entry is put into the DISK index for each LIST subsequently added to the DISK. In general, when a new LIST is input or generated by calculation or modification, this new list is put after the last existing list on he DISK, and its address entered into the DISK index. This index will now contain two or more entries for lists of the given type, and so that subsequent calculations will know which one to use, the address of the most recent is inserted into the CURRENT index. Thus the CURRENT index is of fixed length, with one slot for each possible list type, and the DISK index is of variable length with a slot for each list present on the DISK. The DISK index itself consists of fixed length blocks. In the event that a block becomes full, a new block is chained to the old one. This new block will be after the last list which was written. The indexing of the DISK, and hence the addressing of the lists, may become undefined if the last DISK index block extends beyond the physical end of the file. Neither the DISK nor the CURRENT index is updated until a list is safely written to the DISK, so that in the event of a system failure or a crash of the program, no evidence remains of the incomplete list, i.e. the integrity of the DISK is preserved. Exceptions to this are during access to the reflection list (LIST 6) and the normal matrix, LIST 11. Because these lists are so large, the system will either try to update or overwrite them. If a job fails during an update, the list cannot be accessed again until a job has been run to complete the update. For example, if a job fails during a round of least squares, there may be some Fc values present for the current atomic parameters, and some left from a previous calculation. The user will not be able to access LIST 6 for, say, a FOURIER synthesis until he has recomputed structure factors for all the reflections.

Because new lists are usually added to the end of the DISK, the user has on his DISK a short term archive and record of the calculations he has done. In order to return to some previous state of the calculation, he merely has to enter the address of the list he wishes to use into the CURRENT index. To simplify this, each list is given a SERIAL number when it is written to the DISK. The serial number for LIST 5 (parameters) is usually displayed whenever the list is written to the DISK, and the user can RESET a LIST to a previous SERIAL if it is prefered to the current list. Other lists can be monitored by the instructions \SET WATCH and \SET LIST. Eventually there may be so many versions of lists on the DISK that it risks becomming full. The user can PURGE his DISK of old lists, only the current or spacially marked ones remaining. If there are some particularly important early versions, the user can RETAIN them during the purge. A purge rewrites the required files at the beginning of the DISK, releasing space for new ones. It does not physically shorten the file. During a purge the DISK is in a very delicate state, possibly with some of the vital information only existing in the computer memory. A machine or job failure during a purge could well produce a DISK file that is unusable. The system may during certain types of machine or calculation failure mark lists as being in error, or alter their write/overwrite ststus. Such lists cannot normally be accessed for calculations, but if the user is convinced he understands why the flags were set, he can if he wishes reset them with MARK or USAGE. Thus the status of LIST 6 may reasonably be reset if a failure occurs during the calculation of structure factors, since the Fo values will still be valid, and new Fc values can be recomputed. It would be quite unreasonable to reset the status of a LIST 6 marked as in error during data reduction. The EXTEND directive in \DISK allows the user to control the growth of the disk file.
 

 
The environment
 

In addition to being familiar with the organisation of CRYSTALS, the user will profit from being familiar with his operating environment. In particular, a fluency with the system editor will simplify many tasks. Editors with means of repeating blocks of instructions may prove particularly useful for processing large files, such as reflection lists, and should be mastered. The facilities in CRYSTALS for modifying atomic parameters are very powerfull, but the user should always be alert for ways of achieving particular results by using system editors if that would be more efficient. It is important to see CRYSTALS as only part of the whole system available to the user. On systems offering hierarchic filenames, much of the management and control of files for different users and structures can be automatically achieved by intelligent use of system services. It is the system manager's task to provide the JCL procedures needed to profit from the system services, and the users task to understand them.