THE PARAMETERS
INTRODUCTION
This appendix gives a brief overview of the general Keyword Data Module (KDM) set of functions which are used by ROTEGEN to define and handle its keyworded data set sometimes referred to as the Rotation Data Module in comparison with previous developments of a Laue Data Module (LDM) (Campbell, Clifton, Harding & Hao, J. Appl. Cryst. (1995) 28, 635-640). Many of the same concepts are used but the KDM routines are general whereas the LDM routines were for a specific set of parameters. This appendix also gives a specification of the individual parameters used; these are described in two sections, a summary list and a more detailed specification. Some of the parameters are global to the dataset as a whole and others may have different values for each crystal set defined within the overall dataset.List of sections:
Handling the Keyworded Parameters
Summary of Keyworded Parameters
Detailed Specification of the Parameters
Standard Set of Output Parameters
The NUMIMG parameter
HANDLING THE KEYWORDED PARAMETERS
The parameters are set up within ROTGEN making use of a general set of Keyword Data Module KDM) routines. Additional sets of routines are used to handle the input and output of KDM data and also symmetry data (KWD and KSM routines). The KDM routines enable parameters of various types to be defined e.g. integer, real or character. The dataset for ROTGEN may contain several crystal sets and some parameters refer to the dataset as a whole whilst others may have different values for the individual crystal sets within the overall dataset.
For a set based parameter the keyword may have a set number appended in square brackets e.g. ROTSTART[2] 50.0; if the set number is omitted, it is assumed that the value following the keyword refers to all sets e.g. RESOLUTION 2.0.
KDM Routines enable the monitoring of changes to KDM parameter values during the execution of a program.
For most parameters a keyword is followed by a single value. The keywords are case insensitive and need not be given in full though a certain minimum number of characters must be given in each case. In general more than one keyword/value pair may be given on a line. Keywords which may be followed by more that one value or word should be given on separate lines.
Keywords including any set specifications may not include any embedded spaces. Round brackets may be used in place of the square brackets in the set specifications. If desired, the keyword/value pairs may be separated by '=' signs rather than spaces; commas may also be used as item separators. A '=' sign or a comma with surrounding white space is treated as a single separator. Comments are indicated in a KDM based file as any text following an exclamation mark to the end of that line. Line continuation is indicated by the character '-' or '&' as the last non-blank character of the line. If the continuation line is commented, the comment must follow the continuation character. KWD/KDM based data files may contain indirect references to data in another file by giving a file name reference of the form:
@filenameIndirect files may currently be nested to a level of up to 20.
SUMMARY OF KEYWORDED PARAMETERS
This section gives a brief summary of the parameters available; a more detailed specification follows in the next section. Keywords followed by a pair of brackets [] may have separate values for each crystal set within the dataset if required.
General, Crystal System and AlignmentTitle TITLE A title for the dataset.
No. crystal sets NUMSETS Number of crystal sets defined within this dataset.
Crystal system SYSTEM The crystal system Tri, Mon, Ort, Tet, Hex, Rho or Cub.
Lattice type LATTICE Lattice type P, A, B, C, I, F or R.
Crystal symmetry SYMMETRY The space group symmetry followed by the space group number, space group name or symmetry operators (or 'clear' to clear the current symmetry).
Cell, Resolution, Wavelength and Orientation Parameters
Cell A[], B[], C[], ALPHA[], BETA[], GAMMA[]
The cell parameters in Angstroms and degrees.
Resolution RESOLUTION[] The resolution limit in Angstroms.
Wavelength WAVELENGTH[] The wavelength in Angstroms.
U-matrix UMATRIX[] The basic 'U' setting matrix (9 values).
Missetting angles PHI1[], PHI[2], PHI3[]
The misseting angles in degrees.
The Rotation Ranges, Mosaicity and Spot Sizes
Rotation ranges ROTSTART[], ROTEND[], ROTS2[], ROTE2[], ROTS3[], ROTE3[], ROTS4[], ROTE4[], ROTS5[], ROTE5[]
Rotation start and end angles in degrees.
Oscillation range OSCRANGE[] Oscillation range in degrees (+ve).
Partials limit NWMAX[] Only consider partials occurring on up to this number of images.
Mosaicity MOSAICITY[] The mosaic spread in degrees.
Spot size SPOT_SIZE[] The spot diameter in mm.
Detector Parameters
Distance DISTANCE[] The crystal to detector distance in mm.
Rmin RMIN[] Minimum radius on detector in mm.
Rmax RMAX[] Maximum radius on detector in mm.
Limits XMIN[], XMAX[], YMIN[], YMAX[]
Detector limits on 'x' and 'y' from pattern centre (mm.).
Orientation DET_ROTATIONS[] Directions of three orthogonal detector rotation axes.
Rotations TAU1[], TAU2[], TAU3[]
Rotations of the detector around the three detector axes.
Axes DET_AXES[] Detector axis vectors
Horizontal axis IAX_H[] Horizontal axis number 1-3.
vertical axis IAX_V[] Vertical axis number 1-3.
Beam vector BEAM_VECTOR[] Beam vector.
Scan axis SCAN_AXIS[] Rotation axis vector.
Other Source Parameters
Synchrotron SYNCHROTRON[] Synchrotron - yes or no.
Dispersion DISPERSION[] The dispersion delta(lambda)/lambda.
Vertical divrg. DIVV[] Vertical divergence in degrees.
Horizontal divrg. DIVH[] Horizontal divergence in degrees.
Corr. dispersion DELCOR[] Correlated dispersion.
DETAILED SPECIFICATION OF THE PARAMETERS
The following tables summarise the keyworde parameters used by ROTGEN giving a brief description of each parameter and its keyword, units, default value and permissible values. Additional details are given in notes following the list. As indicated earlier, the keywords are case insensitive but in the list below, the upper case characters as the start of each keyword indicate the minimum number of characters which need to be specified for that keyword. The output routine always outputs the full keywords.
Description Keyword Units Default Values NotesGlobal Parameters
General, Crystal System and Alignment
Title TITLe string ' ' <=250 chars. 1 No. crystal sets NUMSets integer 1 >=1 2 Crystal system SYSTem code Tri Tri, Mon, Ort, 3 Tet, Hex, Rho, Cub Lattice type LATTice code P P, A, B, C, I, 3 F, R Symmetry SYMMetry code (undef) see note 4
Crystal Set Specific Parameters
Cell, Resolution, Wavelength and Orientation Parameters
Cell A A[] Angst. 50.0 >0.0 5 Cell B B[] Angst. 60.0 >0.0 5 Cell C C[] Angst. 70.0 >0.0 5 Cell alpha ALPHa[] degrees 90.0 >0.0 5 Cell beta BETA[] degrees 90.0 >0.0 5 Cell gamma GAMMa[] degrees 90.0 >0.0 5 Resolution limit RESOlution[] Angst. 2.5 >0.0 6 U-matrix UMATrix[] 9 reals 1 0 0 any 7 0 1 0 0 0 1 Phi1 PHI1[] degrees 0.0 any 8 Phi2 PHI2[] degrees 0.0 any 8 Phi3 PHI3[] degrees 0.0 any 8
The Rotation Ranges, Mosaicity and Spot Sizes
Rotation start ROTSTart[] degrees 0.0 -360.0 to 360.0 9 Rotation end ROTENd[] degrees 0.0 -360.0 to 360.0 9 Rotation start 2 ROTS2[] degrees 0.0 -360.0 to 360.0 9 Rotation end 2 ROTE2[] degrees 0.0 -360.0 to 360.0 9 Rotation start 3 ROTS3[] degrees 0.0 -360.0 to 360.0 9 Rotation end 3 ROTE3[] degrees 0.0 -360.0 to 360.0 9 Rotation start 4 ROTS4[] degrees 0.0 -360.0 to 360.0 9 Rotation end 4 ROTE4[] degrees 0.0 -360.0 to 360.0 9 Rotation start 5 ROTS5[] degrees 0.0 -360.0 to 360.0 9 Rotation end 5 ROTE5[] degrees 0.0 -360.0 to 360.0 9 Oscillation range OSCRange[] degrees 1.0 >0.0 9 Partials limit NWMAx[] integer 3 3 to 1000 10 Mosaicity MOSAicity[] degrees .05 >=0.0 11 Spot diameter SPOT_Diameter[] mm 0.5 >0.0 12
Detector Parameters
Detector distance DISTance[] mm 60.0 >0.0 13 rmin RMIN[] mm 0.0 >=0.0 14 rmax RMAX[] mm 150.0 >0.0 14 xmin XMIN[] mm 0.0 (=all) any 14 xmax XMAX[] mm 0.0 (=all) any 14 ymin YMIN[] mm 0.0 (=all) any 14 ymax YMAX[] mm 0.0 (=all) any 14 Detector rotns. DET_Rotations[] 9 real 1 0 0 -1.0 to 1.0 15 0 1 0 0 0 1 Rotation 1 TAU1[] degrees 0.0 any 15 Rotation 2 TAU2[] degrees 0.0 any 15 Rotation 3 TAU3[] degrees 0.0 any 15 Detector axes DET_Axes[] 6 real 0 1 0 -1.0 to 1.0 16 0 0 1 Horizontal axis IAX_H[] integer 3 1 to 3 17 Vertical axis IAX_V[] integer 2 1 to 3 17 Beam vector BEAM_vector[] 3 real -1 0 0 -1.0 to 1.0 18 Scan axis SCAN_axis[] 3 real 0 0 1 -1.0 to 1.0 19
Source Parameters
Wavelength WAVElength[] Angst. 1.0 >0.0 20 Synchrotron SYNChrotron[] code Yes Yes/no 21 Dispersion DISPERSION[] real 0.0015 >=0.0 21 Vertical divrg. DIVV[] degrees 0.01 >=0.0 21 Horizontal divrg. DIVH[] degrees 0.10 >=0.0 21 Corr. dispersion DELCor[] real 0.0 any 21
Notes:
- The title parameter is a character string which is taken from the
text following the keyword to the end of the line.
- The number of crystal sets for which parameters are defined from
1 up to a program limit of 10.
- For the crystal system only the first three characters are
matched and for the lattice type a single character is
matched.
- The rotation simulations may be done without making use of the full
symmetry information and with systematic absences being based only on
the lattice type. However the full symmetry must be defined to
carry out the analyses of reciprocal space coverage. The SYMMETRY
parameter has a number of options and may not be followed by any
other parameter on the same line. These are:
SYMMETRY CLEAR Clears out the current symmetryThe space group code and symmetry operation definitions are the same as those used in the CCP4 Program Suite. If any symmetry operators are input, then, on output, all symmetry operators will be written explicitly including any derived via a space group number. By default the symmetry is treated as undefined.SYMMETRY nspg Space group code or number
SYMMETRY op1, op2, ... Add the symmetry operators to the current list
- These are the real cell parameters in Angstoms and degrees. ROTGEN ensures that they are consistent with the crystal system specified.
- The resolution limit in Angstroms for reflection prediction and
determination of the unique data; for the latter the resolution
given for the first crystal set in the dataset is used.
- The U-matrix [U] is a rotation matrix to define a standard orientation.
It rotates the crystal cartesian coordinates (x,y,z) to the laborattory
cartesian coordinate frame (X,Y,Z). It is usually a simple permutation
matrix. The elements are specified in the order U[1,1], U[1,2], U[1,3],
U[2,1], U[2,2], U[2,3], U[3,1], U[3,2], U[3,3].
- The crystal orientation is defined by a set of crystal
rotations phi1, phi2 and phi3 around the laboratory axes X, Y and Z
respectively from the setting defined using the U-matrix.
Note: ROTGEN uses the MOSFLM convention that the phi1 and phi3 rotations are in the positive sense but phi2 is in the opposite sense.
|c_z -s_z 0| | c_y 0 s_y| |1 0 0| rotation matrix = |s_z c_z 0| | 0 1 0| |0 c_x -s_x| | 0 0 1| |-s_y 0 c_y| |0 s_x c_x|where c_x = cos(phi1), s_y = sin(phi2) etc.
- The rotation ranges are defined by a rotation start angle in degrees
and a rotation end angle in degrees. Up to five rotation ranges
may be defined for a crystal set. It is always assumed that the rotation
direction is positive. If an end angle is less than or equal to the
corresponding start angle (normally two values of zero), the range is
ignored. Rotation ranges will, where appropriate, be rounded up to
be a multiple of the oscillation angle.
- The parameter NWMAX gives the maximum number of images over which a
reflection may spread to be considered as a potentially useful partial.
It may have a value
from 3 up to 1000. ROTGEN, in general, classifies partials into 4
cases, partials on 2 images, partials on 3 images partials on
4 to 'nwmax' images (if 'nwmax' = 3 there will be no reflections in
this class) and 'too wide' partials which extend over more than 'nwmax'
images.
- The mosaic spread in degrees.
- The spot diameter in mm. Circular spots of uniform size throughout the
image are assumed. The spot size parameter is used to determine which
spots will be spatially overlapped on an image.
- The crystal to detector distance in mm.
- The area of the image to be processed is assumed to be the
same for each image and is defined by a maximum radius
'rmax' and an optional exclusion region at the centre of the
image of radius 'rmin', both in mm. Additionally, the processing may be
restricted to a rectangular section (by default the whole
image) by using the limits 'xmin', 'xmax', 'ymin' and
'ymax' in mm from the pattern centre along the detector axes. Values
The 'x' limits are ignored if 'xmin' = 'xmax' e.g. both are zero and
similarly for the 'y' limits.
- The detector rotation vectors in terms of the laboratory axes define
the axes around which the detector may be rotated. One is normal to the
detector and the other two lie parallel to the plane of the detector.
These axes pass through the laboratory axes origin (crystal position).
The detector lies at the crystal to detector distance along the first
detector axis. Any required rotations around these three axes are
defined by the 'tau1', 'tau2' and 'tau3' angles. These are positive
rotations in degrees around the three defined detector rotation axes
respectively. The rotations are applied in the order 'tau1' then
'tau2' then 'tau3'.
- Vectors defining the two local axes (e.g. xd, yd) within the plane of the
detector and used to specify the predicted spot coordinates. These
are defined with respect to the laboratory axes.
- These define which of the three laboratory axes is horizontal and which
is vertical (1='X', 2='Y', 3='Z') so that the correct axes may be
identified for the horizontal and vertical beam divergence parameters.
- The vector defining the direction of the beam looking towards the X-ray
source with respect to the laboratory axes.
- The vector defining the rotation (scan) axis (+ve rotation) with respect
to the laboratory axes.
- The wavelength in Angstroms.
- A keyword indicating whether or not the X-ray source is a synchrotron source and the synchroton parameters of dispersion (delta(lambda)/lambda), horizontal and vertical divergence of the beam in degrees and a correlated component of the wavelength dispersion.
STANDARD SET OF OUTPUT PARAMETERS
When a parameters file is written from ROTGEN, a standard set of parameters will always be output even if they have the default values. The other parameters will only be output if they have been assigned values either by reading them in from a parameters file or by resetting them from within the program. The parameters not included in the standard set are:
ROTS2, ROTE2, ROTS3, ROTE3, ROTS4, ROTE4, ROTS5, ROTE5 DET_ROTATIONS, DET_AXES, TAU1, TAU2, TAU3, IAX_H, IAX_V BEAM_VECTOR, SCAN_AXIS
THE NUMIMG PARAMETER
The earliest versions of the program defined the rotation range using the rotation start angle, the oscillation angle and the number of images parameter NUMIMG[]. This parameter has now been withdrawn but if it is found when reading an input parameters file, a ROTEND parameter value will be calculated and set based on its value and a warning message will be displayed.