Crystals User Guide
Chapter 1: The Crystals User Guide
************************************************************************* 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.
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.
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
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
Publication listings of atomic parameters, distances, angles, torsion
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.
Over-view of CRYSTALS
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
The SCRIPT processor
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.
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.
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
Issue 4 sequential batch jobs being respectively controlled by
LISTINPUT, PLANES, ATOMS and a file requesting the structure factors.
Initiate an interactive job issuing sequentially \USE LISTINPUT,
\USE PLANES, \USE ATOMS and then the instruction to compute structure factors.
Initiate an interactive job and type in all the information from a
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.
This is the main output stream for the system, and contains detailed
accounts of the calculation performed.
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
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)
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.
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:-
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.
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.