GENLAUE - REFINE ORIENTATION AND CREATE .GE1/.GE2 FILES ======================================================= INTRODUCTION GENLAUE is like NEWLAUE in that it generates predicted spot positions from a set of crystal andexperimental parameters, but can also refine the parameters against observed spot positions taken from a film image (or image-plate) file. With a new crystal and probably with a new film pack you should expect to have to make several passes through GENLAUE using different facilities in turn. (See the flow diagram at the end of the GENLAUE documentation). The main author of the program was I.J. Clifton, Daresbury Laboratory. List of sections: Running the Program Using GENLAUE Input and Output Files The .gen File Structure The .ge1/.ge2 Files Sample .gen Files Flowchart RUNNING THE PROGRAM Use the command 'laue genlaue' The program runs in an interactive manner and prompts the user for input as needed. USING GENLAUE Introduction Once the .gen file has been read in and the pattern predicted, the user can choose not to do any refinement, in which case the output files can be written out straight away, or can choose to refine some of the parameters. At the end of a run the user can choose whether or not to write out the three (.ge1, .ge2, .gen) output files. A record of the run is saved in a log file generally named genlaue.log. Refining the parameters requires a scanned film file to be used (or a previously saved set of matches (see below)). By default, on a VAX, GENLAUE looks in the directory assigned to the logical name FILM and assumes a file type of .dat. On a Unix system an environment variable named FILM may be set with the name of a default directory if required. There are two strategies for refinement: `Automatic' mode and `Displaue' (named after an earlier program) mode. Automatic mode involves placing boxes of a user-specified size at the predicted positions on the film and then taking the centre-of-gravity inside each box to give a set of vector shifts from the predicted position. The program calls a routine which adjusts the parameters so as to minimize the shifts. In `displaue' mode, a threshold plot of the film is generated and then the predicted spot pattern is superimposed on the film plot. The user matches up corresponding spots (a minimum of 20) by eye, and enters the vector shifts with the graphics cursor. The set of shifts is then minimized by the same method as for automatic mode. Generally, `displaue' mode is used until the predicted spot pattern is almost in register with the film plot, then there is a final `automatic' refinement cycle. The user can select a subset of nodalspots for display in the `displaue' mode. Nodal spots are low order reflections; you choose the maximum index (Here the indices referred to are the indices of the `inner point' of the `ray' on which the rlp lies. i.ee, the indices are reduced by dividing out by their highest common factor), and the higher the index the more nodal spots there will be. GENLAUE prints a histogram of the number of nodal spots for up to index 12, as a guide. Typically 100 spots may be required at the refinement stage. The overlapcriterion determines which spots are classed as spatial overlaps. It is also used to evaluate the size of the box for centre of gravity fitting for refinement purposes, (as OVERLAP - SPOT_DIAM/ 2), though the user can optionally reset this box size. Therefore it is usually sensible to initially set the overlap value to be high (say 0.5 - 1.0 mm) for the refinement stage (to use well separated nodal spots), then to set it more realistically for the final pattern generation. Note also that in the initial fitting stages it may be useful to have a 'd_min' larger than the real value e.g. 3.0 instead of 1.8 for as this will predict only the reflections with higher than average intensity. List of subsections in this section: Saving Images Saving a File of Matches Refining on Several Films The Phi and Omega Parameters Refinement Protocol Difference Maps Laue Cameras Radial Masking Saving Images Because calculating a threshold plot is IO intensive, re-plotting the film image in `displaue' mode can take a long time. As an alternative, an `image' file can be saved - this is a file containing just the Tektronix vectors sent to the terminal and is therefore normally much smaller. Also, re-plotting such a file does not involve any calculation, so image files can be replotted several times faster than the film itself. Saving a File of Matches An extra facility is available with `displaue' mode which may be useful when experimenting with refinement. After matching up spots in `displaue' mode, a file containing the observed and calculated nodal positions can be saved (reply `Yes' to 'Dump spots?'). This file can then be re-read in a subsequent run of GENLAUE (reply `Yes' to 'Use a saved file of matches?'). By means of this facility, refinement can be repeated again and again without having to cursor in a set of spots each time. This is the only option in which refinement can be done without a film file being read. Refining on Several Films In its usual mode of operation GENLAUE refines its parameters against just the A film, on the assumption that the parameters for the other films will follow the A film. However, in some circumstances, (e.g., missing fiducials, or doubts about whether films have moved in the pack during the data collection process) it is necessary to determine the film centre and omega for each film individually. So there is an option to refine against the other films in the pack. If this option is chosen, the program steps through the pack a film at a time. At each stage the user is asked for a crystal-film distance increment to the next film, this should allow for film thickness (normally .22mm) and foil if present. The crystal-film distance can be refined, of course. {NB at present, GENLAUE can store only the A film's parameters in the .GEN file. This means that it is impossible to break off part way through refining with several films without losing the refined parameters. So the recommended way of proceeding is to firstwork on the A film as described below until the parameters are right thenfinally refine on all six films in a single run.} The Phi and Omega Parameters Please refer to Alan Wonacott's MOSFLM manual for a discussion of camera constants etc. Informally, the parameter 'omega' is meant to take care of any skewness between the film's vertical and the diffraction pattern's vertical. Two sources of this error can be distinguished: 1) When a film is taped onto the microdensitometer for scanning, i.e. the discrepancy between `fiducial vertical' and `scanner vertical'. This error, called 'omega_f', can easily be estimated from the slope of the fiducials. 2) The difference between `fiducial vertical' and the true `pattern vertical'. This is called 'omega_c' and has to be refined against the pattern itself. As 'omega_f' is usually well-determined by the fiducials, it is just treated as a constant by GENLAUE. 'omega' in the discussion below refers to 'omega_c'. Clearly the film pack as a whole has an 'omega' and sometimes individual films will have different 'omega' values. However, the crystal missetting angles (in particular 'phi_x') will be correlated with 'omega' making refinement unstable. Therefore GENLAUE uses the following interpretation of the 'phi' angles and 'omega': * When the A film is being processed, the 'phi' angles are refined (together with 'c_to_f',f,'x_c', 'y_c' and the cell parameters) but not 'omega'. The 'omega for film A is assumed to be absorbed (Apart from the contribution of 'omega_f'} into the 'phi' parameters. * On the B--F films, only 'omega' can be refined (together with 'c_to_f',f,'x_c', 'y_c') Wto allow for skewed films in the pack. Refinement Protocol At present up to six experimental parameters ('phi_x', 'phi_y', 'phi_z') or ('omega', 'c_to_f', 'x_c', 'y_c') and up to six crystal cell parameters can be refined. Refining the cell parameters involves more calculation and so takes much longer than just refining the experimental parameters. Before the refinement starts, the user has a chance to set the initial values of the parameters and to set a `scaling factor' for each parameter. A scaling factor of 0 can be used to fix a parameter at its starting value. Absolute cell parameters are not determinable from Laue photographs, only axial ratios; the recommendation is to fix the cell parameter nearest to the spindle direction. Refinement of parameters in the following order is recommended: phi_x, phi_y, phi_z until convergence is reached phi_x, phi_y, phi_z, c_to_f, x_c, y_c until convergence is reached above and cell parameters In particular crystal settings, one of the cell parameters (the one parallel to the beam) may have very little significance and be sloppy in refinement. It is then best to fix the parameter. A well matched pattern should give a final rms of <0.05 mm, particularly when the cell parameters have been included in the refinement. Don't worry if the initial rms in INTLAUE is a bit different, since the two programs use different algorithms and thresholds. Difference Maps Once the observed and calculated spot positions have been found for refinement (either automatically or by the user) a `difference map' is produced. The scale of this plot is approximately 1.5 times that of the actual film. A dot (or star) is placed at each observed position and a vector, exaggerated 5 times, is drawn representing the shift to the calculated position. A star is plotted if the length of the shift is greater than the current spatial overlap resolution. After refinement, there is an optional second difference map. The vectors (again scaled up by 5) represent the shifts from the original observed positions and the spot positions calculated from the new, refined parameters. Spots are plotted as a square if the observed position (evaluated as the centre-of-gravity of a box at the calculated position) differs from the calculated position by more than the current spatial overlap resolution. Laue Cameras Different cameras in current use place the fiducial marks i different positions in relation to the spindle and horizontal. The appropriate values must be selected in NEWLAUE or input on the .gen file. They are (for 50 micron scans): Arndt Wonacott camera: -5000 -4000 -5000 4000 5000 4000 Huber camera: -4000 5000 -4000 -5000 4000 -5000 Radial Masking GENLAUE can use the radial masking options of T.J. Greenhough and A.K. Shrive. When the streaky spots option is used then the following variable or constant radial elliptical masking parameters are requested by the program. 1) cmaskFull length of major (radial) ellipse axis (mm) For the Andrews et al (1987) formulation this should be set to mosaic spread x cf, while {\tt kmask} (below) should be set to 1.0. 2) bmaskFull tangential width of streaks (in mm) 3) kmaskConstant defining the variable nature of the mask When 'kmask' is less than 0, radially decreasing streak lengths are provided based on the central length given by 'cmask'. When 'kmask' = 0, constant streak lengths of length 'cmask' are provided. When 'kmask' is greater than 0, radially increasing streak lengths are provided, with the Andrews et al (1987) formulation being set for 'kmask' = 1.0 and 'kmask' = eta x c_to_f. 4) borderWidth of bg border round ellipse (in rasters) Note: Please note that overlaps are not treated according to the ellipse shape but simply on the smaller dimension (usually 'bmask'). INPUT AND OUTPUT FILES The input files are as follows: a) The .gen parameters file b) The image files The output files are: a) An updated .gen parameters file b) A .ge1 generate file c) A .ge2 harmonics file THE .GEN FILE STRUCTURE The .gen file contains the crystal and experimental parameters, and film constants. It has a dual role: as an input file it contains initial parameters for the prediction; as an output file it accompanies the .ge1/.ge2 file of predicted spots and acts as a record of the parameters used to produce that file. On starting GENLAUE, it first asks for the name of a .gen file. This may be a file created in NEWLAUE or by using an editor, or it may be created within GENLAUE by answering the prompts given if is typed in response to the prompt for the .gen file name. If an incomplete file is given the program will prompt for the outstanding parameters. The data items are as follows: compound name crystal identifier (6 characters) a* b* c* al* be* ga* syst cent axes (recip cell + codes) phi_x phi_y phi_z (missetting angles) lambda standard, minimum, maximum (Angstroms) c_to_f d_min film-radius (Crystal-to-film, resolution) spindle (Spindle angle) x_c y_c omega_c (offsets -film centre, skewness) twist, tilt, bulge (distortion corrections) y_scale (scanner parameter) x_rej y_rej (reject spots close to centre) nfid fidx1 fidy1 fidx2 fidy2 fidx3 fidy3 (fiducials) wfilm n1od baseod g1od curve (film constants) nxrast nyrast dscal [x_cen_in y_cen_in] [rast] [xlow xhigh ylow yhigh imfilm] Notes: 1) The minimum number of cell parameters for a given crystal system are required, i.e. 3 cell lengths for orthorhombic, 1 for cubic, and 3 lengths and one angle for monoclinic etc. 2) The crystal system is TRICLINIC, MONOCLINIC, ORTHORHOMBIC, TETRAGONAL, HEXAGONAL, RHOMBOHEDRAL or CUBIC. The centering code is P, A, B, C, I, F or R. The axes defime the axis nearest to the beam and rotation axes as codes such as +a* -b*. 3) The units for most items apart from the reciprocal cell are mms and degrees. 4) Fiducials: No. of fiducials (must be 0 or 3), positions of the fiducials in 10 micron units relative to the mid-point of the image 5) Film constants are Width of film (mm), size (mm) of fiducial box, followed by four film characteristics {See A.J. Wonacott's MOSFLM manual} * Scanner intensity corresponding to 1OD * Optical density of film base. * The Selwyn granularity at unit optical density. * Non-linearity constant. 6) nxrast yrast etc. * No. of rasters in 'x' direction. * No. of rasters in 'y' direction. * Scaling factor for INTLAUE's film plot (NB GENLAUE does {\em not\/} use this scalingfactor). * Measured image centre in pixels ('x' and 'y'; If given and non-zero values are specified, then this is used as the centre for all films in the pack. Also 'omega_f' is set to 0.0 and the fid positions (if any) are ignored. This option is intended for use, in particular, with image plates. * Raster size (in 'x') (microns). If <= 0.0, then the program will calculate the nearest standard raster size (100, 50 or 25) from the film width and number of x rasters; the value may then be confirmed or changed when the program is run. The y raster size is rast/y_scale}. * Limits (in pixels) of area to be included in prediction; if zero values are given the limits are taken as (1 nxrast 1 nyrast}. * The code word 'image-plate' or 'film' (default=film) THE .GE1/.GE2 FILES GENLAUE produces a generate `file', (in reality, two files .ge1/.ge2) which has a header containing parameters followed by a list of predicted spots (h, k, l , x, y, lambda) with empty slots ready to be filled in by a spot integration program. The format of these files is described in the documentation file gefile.txt. On output, spatial overlaps and spots in the central box area (as defined by 'x_rej', 'y_rej' can optionally be omitted. GENLAUE requires a few extra parameters to be put into the file header. One of these is a minimum intensity to by-pass measurements on subsequent films. The .ge1 file header contains a set of crystal-film distances for the pack. There are several choices which can be used for these values. 1) A constant spacing of .22 mm between films can be assumed. 2) Alternatively, the user can type in each film-film interval. In this way the presence of metal foils can be allowed for. 3) If refinement on the A--F films has been done, the refined crystal-film distances can be written out to the file. SAMPLE .GEN FILES This section gives two examples of .gen files. 1) Film data file for Proflavin proflavin 0.0787538 0.0501504 0.0465217 87.81577 MONOC P +ast +bst -178.6900 -1.980000 44.87000 1.000000 0.2500000 2.500000 61.00000 1.100000 59.00000 0.0000000E+00 0.1500000 0.0500000 0.0000000E+00 0.0000000E+00 0.0000000E+00 0.0000000E+00 0.9980000 0.0000000E+00 0.0000000E+00 3 -5000.0 -4000.0 -5000.0 4000.0 5000.0 4000.0 125.0 8.0 128 0.400E-01 0.230E+01 0.700E-01 2400 2400 1.8 0.00 0.00 50.00 1 2400 1 2400 film 2) Image plate file for Lysozyme LYSOZYME CRYS 0.0126279 0.0263019 TETRA P +ast +bst 94.25000 -15.22000 -103.7500 1.000000 0.4000000 2.200000 200.0000 2.800000 90.00000 0.0000000E+00 0.200000 -0.5400000 0.0000000E+00 0.0000000E+00 0.0000000E+00 0.0000000E+00 1.000000 0.0000000E+00 0.0000000E+00 3 -9000.0 -9000.0 -9000.0 -9000.0 -9000.0 -9000.0 180.0 5.0 128 0.400E-01 0.230E+01 0.700E-01 1200 1200 2.0 583.00 593.00 150.00 1 1200 1 1200 image-plate FLOWCHART GENLAUE FLOW DIAGRAM START | Input .gen file |<----------------------------------------------- Calculate spot positions | (Questions about overlaps, nodals etc.) | | | (Display predicted pattern) | | | --<--[NO]--Refinement?--[YES]---- ^ | | | | Spot posns. | (Refine another film -<-[.dmpfile]--from ?---[image file]-- | in pack? (Crystal to | | | film distance only)) | Fetch digitised image. | | | Find fiducials and | Calculate all spot | background. | positions, write to | | | .ge1, .ge2 files. | Display film image as | | | --<---[NO]------threshold plot ? | Questions about C-F | | | | distances. | | [YES] | | | Find centres of | | Rewrite .gen file w. | gravity of density (Save image as .img | additional parameters | around predicted file for quicker | | | positions display next time) | END | | | | | | Pick spot positions | | | with the cursor | | | | | | ------------------------- | | | | | Save spot positions | | in .dmp file | |--------------------------| | Display difference map | (obs-calc positions) | |<---------------- | Select parameters | | for refinement | | | | ^ Refine ^ | | | | (Display difference map) | | ( ) indicates optional choices | | | Further refine?--[YES]-- | | | [NO] | |----------------------