LAUE DATA MODULE (LDM) ====================== Version: 1.8 John W. Campbell, CCLRC Daresbury Laboratory CONTENTS -------- CHAPTER 1: THE LAUE DATA MODULE (LDM) 1.1 INTRODUCTION 1.2 Scope of the Laue Data Module 1.3 LDM Keyworded Data Files 1.4 Reading and Writing LDM Data 1.5 LDM Routines 1.6 Coordinate Systems 1.7 Laue Reflection List (LRL) 1.8 LDM Related Functions 1.9 The LDM Parameters 1.10 Extended LDM Parameter Sets 1.11 References CHAPTER 2: LAUE DATA MODULE (LDM) ROUTINES 2.1 INTRODUCTION 2.2 Read, Parse and Write LDM Data 2.2.1 Introduction 2.2.2 Read Line of Data from a File - LDM_READLINE 2.2.3 Handle Indirect File References in a String - LDM_READSTR 2.2.4 Parse Line Containing LDM Data - LDM_PARSE 2.2.5 Parse LDM Data with Additional Checking - LDM_CHK_PARSE 2.2.6 Parse and LDM Item - LDM_PARSEITEM 2.2.7 Write LDM Parameters Data - LDM_WRITE 2.3 Setting LDM Parameter Values 2.3.1 Introduction 2.3.2 General Routine to Set LDM Parameter Value - LDM_SET 2.3.3 Reset Default LDM Parameter Value(s) - LDM_RESET 2.3.4 Individual Routines to Set LDM Parameter Values - LDM_SET_... 2.4 Getting LDM Parameter Values 2.4.1 Introduction 2.4.2 General Routine to Get LDM Parameter Value - LDM_GET 2.4.3 Individual Routines to Get LDM Parameter Values - LDM_GET_... 2.4.4 Routine to Get All SPD... Parameter Values - LDM_SPDXY 2.5 Symmetry Handling Routines 2.5.1 Introduction 2.5.2 Get Full Symmetry Data - LDM_GET_SYMM 2.5.3 Get Basic Space Group Details - LDM_GET_SPGRP 2.5.4 Get Number of Symmetry Operators - LDM_GET_NSYM 2.5.5 Check for Systematic Absence - LDM_SYSABS 2.5.6 Get Systematic Absence Based on H, K - LDM_SYSAHK 2.5.7 List Symmetry Data - LDM_SYMM_LIST 2.5.8 Prepare to Convert Indices to Assymetric Unit - LDM_AUSET 2.5.9 Write symmetry to MTZ file - LDM_LWSYMM 2.5.10 Write symmetry to LIRL - LDM_LIRLSYMM 2.6 Convenience and Supplementary LDM Routines 2.6.1 Introduction 2.6.2 Interpret Axis Order String - LDM_AXORD 2.6.3 Millimetre to Raster Conversion Factors - LDM_MMRAST 2.6.4 Get Image File Name From Definition or Template - LDM_FILENAME 2.6.5 Find LDM Limit SPD Polynomial Coefficients - LDM_SPDMAX 2.6.6 Find LDM Number of Packs - LDM_PKMAX 2.6.7 Find LDM Number of Plates per Pack - LDM_PLMAX 2.6.8 Decode Character String into a Number - LDM_INTFP 2.7 Monitor LDM Parameter Value Changes 2.7.1 Introduction 2.7.2 Reset Parameter Change Monitoring Flags - LDM_CH_RESET 2.7.3 Check for Parameter Value Changes - LDM_ANY_CH 2.8 Make Distortion Corrections to Coordinates 2.8.1 Introduction 2.8.2 Make Distortion Corrections to Ideal Coordinates - LDM_CORR 2.9 Save and Restore Refineable Parameter Values 2.9.1 Introduction 2.9.2 Save Refineable Parameters - LDM_SAVERP 2.9.3 Restore Saved Refineable Parameters - LDM_RESTRP 2.10 Special Routines for Use with Laue Reflection Lists 2.10.1 Introduction 2.10.2 Set LRL Generation Flags - LDM_LRL_CALC 2.10.3 See if LRL Needs to be Regenerated - LDM_CHK_GEN 2.11 Special Reciprocal Lattice to Detector Conversions 2.11.1 Introduction 2.11.2 Convert Reciprocal Lattice to Detector Coordinates - LDM_RTOD 2.11.3 Double Precision Version of LDM_RTOD - LDM_RTOD_DP 2.11.4 Convert Detector to Reciprocal Lattice Coordinates - LDM_DTOR 2.11.5 Convert Detector to 'Q' Axis Coordinates - LDM_DTOQAX 2.12 Handle Extended LDM Data 2.12.1 Introduction 2.12.2 Define a New Integer Parameter - LDM_NEWINT 2.12.3 Define a New Floating Point Parameter - LDM_NEWFLP 2.12.4 Define a New String Parameter - LDM_NEWSTR 2.12.5 Get Index to KDM Keyword Set - LDM_KDX CHAPTER 3: LAUE REFLECTION LIST (LRL) ROUTINES 3.1 INTRODUCTION 3.2 Generating the Laue Reflection List 3.2.1 Introduction 3.2.2 Generate Laue Reflection List (High Level) - LRL_GEN 3.2.3 Generate Laue Reflection List (Low Level) - LRL_GNR 3.2.4 Calculate Orientation Matrix - LDM_MK_ORIENT 3.2.5 Calculate the Master 'A' Matrix - LRL_A_CALC 3.2.6 Find and Mark Spatial Overlaps - LRL_OVLP 3.2.7 Find All Spatial Overlaps - LRL_OVALL 3.3 Sort the Laue Reflection List 3.3.1 Introduction 3.3.2 Sort Reflections List - LRL_SORT 3.4 Calculate an Individual Spot Position 3.4.1 Introduction 3.4.2 Calculate Individual Reflection Position - LRL_CALC_POS 3.5 Get Global Laue Reflection List Data Items 3.5.1 Introduction 3.5.2 Return the Number of Spots - LRL_NUMSPOTS 3.5.3 Get Spot Counts - LRL_COUNTS 3.5.4 Return Status of Laue Reflection List - LRL_STATUS 3.5.5 Get Corrected Centre Position - LRL_GET_XYCEN 3.5.6 Number of Reflection Tries - LRL_TRIES 3.5.7 Get Pack and Plate Number - LRL_GET_PLATE 3.5.8 Return the Nodal Index Limit - LRL_NODMAX 3.6 Get Individual Spot Data from Laue Reflection List 3.6.1 Introduction 3.6.2 Get Spot Details - LRL_GET 3.6.3 Get Harmonics Data for a Spot - LRL_GET_HARM 3.6.4 Return Coordinates for a Spot - LRL_GET_XFYFD 3.6.5 Return Integrated Intensity of a Spot - LRL_GET_INT 3.6.6 Get Nodal Index for a Spot - LRL_GET_NIDX 3.6.7 Return Spatial Overlaps Flags for a Spot - LRL_GET_OVLP 3.6.8 Return No. of Overload Pixels for a Spot - LRL_GET_OVPIX 3.7 Set Global Laue Reflection List Data Items 3.7.1 Introduction 3.7.2 Clear Intensity Data - LRL_CLR_ALL 3.7.3 Set the 'Integration Done' Flag - LRL_SET_IDONE 3.8 Set Individual Spot Data in Laue Reflection List 3.8.1 Introduction 3.8.2 Store Integrated Intensity - LRL_SET_INT 3.8.3 Clear Intensity Data for a Spot - LRL_CLR_INT 3.8.4 Set Spatially Overlapped Flag for a Spot - LRL_SET_SPOV 3.8.5 Set 'Too Close' Flag for a Spot - LRL_SET_CLOS 3.8.6 Set No. of Overload Pixels for a Spot - LRL_SET_OVPIX 3.8.7 Set Non-spatially Overlapped Nodal Flag - LRL_SET_OKNOD 3.9 Interface for XDL_VIEW Laue Simulations 3.9.1 Introduction 3.9.2 Interface to X-windows Laue Simulation - LRL_XDLSIM 3.9.3 Interface to X-windows Gnomonic Simulation - LRL_XDLGNM 3.10 Re-assign Spatial Overlaps and Multiplicities 3.10.1 Introduction 3.10.2 Reassigning spatial overlaps - LRL_REASSIGN 3.10.3 Get Re-assigned Spot Flags - LRL_GET_REASS 3.11 Determine Spatial Overlap Between Two Spots 3.11.1 Introduction 3.11.2 Determine Spot Ellipse Overlap (analytical) - LRL_OVQ 3.11.3 Determine Spot Ellipse Overlap (using mask) - LRL_OVM 3.12 Miscellaneous Routines 3.12.1 Introduction 3.12.2 Highest Common Factor of Two Numbers - LRL_HCF 3.12.3 Convert Between Real and Reciprocal Cells - LRL_RECCEL 3.12.4 Get Nodal Index from Indices - LRL_NODIDX CHAPTER 4: LDM RELATED FUNCTIONS (LFN) 4.1 INTRODUCTION 4.2 Crystal Orientation Refinement 4.2.1 Introduction 4.2.2 Refine Orientation Parameters - LFN_RFN 4.2.3 List Refined Parameter Values - LFN_SHOWREF 4.2.4 List Refined Values for XDL_VIEW - LFN_SHOW_XDL 4.2.5 Automatic Orientation Refinement - LFN_AUTO_REFN 4.2.6 Log Automatic Refinement Results - LFN_REFN_LOG 4.2.7 Log Automatic Refinement Errors - LFN_REFN_ERR 4.2.8 Get Nodals Histogram Data - LFN_NODHIST 4.2.9 Get Refinement Nodals List - LFN_GET_SPOTS 4.2.10 Clear Observations List - LFN_CLROBS 4.2.11 Add Spot to Refinement Observations List - LFN_ADDOBS 4.2.12 Get Spot from Refinement Observations List - LFN_GETOBS 4.2.13 Get Number of Refinement Observations - LFN_NUMOBS 4.2.14 Get Spot Position - LFN_SPOT_CG 4.2.15 Get Radially Masked Spot Position - LFN_SPOT_RD 4.3 In Memory Image Routines 4.3.1 Introduction 4.3.2 Read Section from Image in Memory - LFN_IMG_RECT 4.4 Integration and Soft Limit Routines 4.4.1 Introduction 4.4.2 Standalone Integration Routine - LFN_SAINT 4.4.3 Integration Parameter Defaults - LFN_SAINT_DF 4.4.4 Get Profile Parameters - LFN_GET_PROFPARS 4.4.5 Get Profile Maximum - LFN_GET_PROFMAX 4.4.6 Get Spot Profile - LFN_GET_PROFILE 4.4.7 Get Profile Pixel Details - LFN_GET_PROFPIX 4.4.8 Get Integrated Spot Parameters - LFN_GET_SPOTPARS 4.4.9 Get Integrated Spot Code - LFN_GET_SPOTCODE 4.4.10 Get Integrated Spot Data - LFN_GET_INTSPOT 4.4.11 Get Spot Pixel Details - LFN_GET_SPOTPIX 4.4.12 Write Spot Profiles - LFN_LIST_PROFS 4.4.13 List Integrated Spot Details - LFN_LIST_INTSPOT 4.4.14 Basic Integration Statistics - LFN_INT_STATS1 4.4.15 Integration Statistics Table 1 - LFN_INT_TAB1 4.4.16 Find Improved Soft Limit - LFN_SOFT 4.4.17 List Soft Limit Results - LFN_SOFT_LIST 4.4.18 Automatic Soft Limit Determination - LFN_AUTO_SOFT 4.4.19 Soft Limits Determination Defaults - LFN_SOFT_DF 4.4.20 Log Automatic Soft Limits Errors - LFN_SOFT_ERR 4.4.21 Monitor Automatic Soft Limits Steps - LFN_SOFT_MON 4.4.22 Monitor Integration Progress (Dummy) - LFN_SOFT_PROG 4.5 Laue Unique Data Analysis 4.5.1 Introduction 4.5.2 Generate Unique Reflections List - LFN_UNQ_GEN 4.5.3 Re-initialise Unique Reflections Counts - LFN_UNQ_RESET 4.5.4 Get Indices of a Unique Reflection - LFN_UNQ_HKL 4.5.5 Increment Counts in Unique Reflections List - LFN_UNQ_INC 4.5.6 Get Reflection Counts - LFN_UNQ_GET 4.5.7 Statistics Relative to Unique Data - LFN_UNQ_STAT 4.5.8 Statistics Table 1 Versus Unique Data - LFN_UNQ_TAB1 4.5.9 Statistics Table 2 Versus Unique Data - LFN_UNQ_TAB2 4.5.10 Statistics Table 3 Versus Unique Data - LFN_UNQ_TAB3 4.6 Determine Spot Positions and Sizes 4.6.1 Introduction 4.6.2 Find Spot Positions in an Image - LFN_FINDSPOTS 4.6.3 Analyse the Spots List - LFN_SPOTS_ANALYSE 4.6.4 List Spot Size Analysis Results - LFN_SPOTS_ANA_LIS 4.7 Dummy Cancel Routine 4.7.1 Introduction 4.7.2 Dummy Cancel Routine - LFN_DUMMY_CNCL 4.8 Create .ge1/.ge2 files 4.8.1 Introduction 4.8.2 Create .ge1/.ge2 Files from LIRL - LFN_LIRLGE 4.9 Read Data into LIRL 4.9.1 Introduction 4.9.2 Read Data from .ge1/.ge2 Files to LIRL - LFN_GELIRL 4.9.3 Read Data from MTZ File to LIRL - LFN_MTZLIRL FIGURES: CHAPTER 1 1.1 Flowchart for Reading LDM Data 1.2 Laboratory and Detector Axes 1.3 Ideal & detector axes and Camera Constants 1.4 Flowchart for Parameter Refinement 1.5 Flowchart for Soft Limits Determination CHAPTER 1: THE LAUE DATA MODULE (LDM) ===================================== 1.1 INTRODUCTION A Laue Data Module (LDM) (Campbell et al., 1994) has been defined and implemented in as part of the development of the Daresbury Laboratory Laue Software Suite (see Helliwell et al.,1989). Keyworded input of the LDM parameter values has been provided. The Laue Data Module is designed to be program independent and the principle of data encapsulation is followed so that the application programmer is not concerned with the details of how the data items are actually stored and may only access the data items through the functions provided. Basically, the Laue Data Module consists of a set of standard parameters for the processing of Laue X-ray diffraction data and a set of program independent functions for handling these parameters. There are also a number of closely related developments following the same principles including, in particular, the functions to handle the generation of a Laue Reflection List (LRL) and to access the data in that list. The Laue Data Module code is written in standard FORTRAN77 with the exception that long names are used for both variable and subroutine names and underscore characters may be used in such names. Also 'INCLUDE' files are used to include PARAMETER and COMMON data though a utility program is available to include this code in the source file if necessary. Any machine dependent functions are dealt with via calls to routines from the CCP4 Suite libraries. List of sections: Scope of the Laue Data Module LDM Keyworded Data Files Reading and Writing LDM Data LDM Routines Coordinate Systems Laue Reflection List (LRL) LDM Related Functions The LDM Parameters Extended LDM Parameter Sets References 1.2 SCOPE OF THE LAUE DATA MODULE The LDM parameters cover those needed in the initial stages of processing a set of Laue X-ray diffraction images. Basically they are those parameters which are needed in order to generate predicted Laue diffraction patterns which closely match the observed images prior to the intensity integration stage. They are essentially in three categories:- 1) The crystal parameters such as the crystal system, lattice type, cell parameters, crystal orientation parameters and the resolution limit of the diffraction. 2) The parameters relating to the X-ray and detector system such the wavelength range and the positioning of the detector. 3) The parameters describing the scanned images and the spots on these images such as pixel size, numbers of rasters, spot sizes and area to be processed. Distortion parameters are included. The Laue Data Module parameters are intended to describe the properties of the system and not the parameters which are specific to a particular program. However, data files containing LDM parameters for input to a program may also contain additional program specific data if required. The basic unit for parameter storage and processing of the Laue data is a set of image packs (each of which may contain one or more plates) with the packs being recorded from the crystal with orientations normally being related by a rotation around a single (spindle) axis. When describing the LDM parameters it is also useful to classify them in two further ways. In one classification, a distinction is made between those parameters are fixed and those which may be refined. In the other classification, the distinction is made between those which apply to the dataset as a whole, those which apply to each pack and those which apply to each plate of each pack. 1.3 LDM KEYWORDED DATA FILES In a parameter data file, each LDM parameter is represented by a keyword followed by a value, normally either a number or a code string. The general rule is that each parameter has its own keyword and that all the parameters are effectively independent and therefore may be specified in any order. The two exceptions are the convenience parameters, DTILT and SPACING parameters (see below). Apart from the TITLE, CRYSTAL_NAME and SYMMETRY parameters whose values are taken from the contents of the remainder of the line, all LDM keyword/value pairs may be followed by other such pairs on the same line. Keywords and code strings are case insensitive. For parameters which apply to the dataset as a whole, the keyword is a simple text string which may, in some cases contain an underscore character e.g. SYSTEM triclinic ROTATION_AXIS +b* NXRAST 1200 RMAX 90.0 Where parameters are pack specific, the keyword may have a pack identifier attached to it. This is a pair of square brackets with enclosing the pack number as an integer. If the pack number is omitted, all packs are implied. Omitting the pack specification also implies all packs. The cases are illustrated for the phi_x parameter e.g. PHIX 86.4 (Value of 86.4 set for all packs) PHIX[2] = 49.5 (Value of 49.5 set for pack 2 only) PHIX[] -70 (Value of -70.0 set for all packs) Where parameters may be specific to each plate of a pack, a pack/plate identifier may be attached to the keyword. This is similar to the pack identifier but has two parts, one for the pack number and one for the plate number. If the pack number is omitted then all packs for the given plate are assumed, If the plate number is omitted, all plates are assumed for the specified pack. If both the pack and plate number are omitted then the parameter value will be assigned for all packs and plates. Omitting the pack/plate specification also implies all packs and all plates. The cases are illustrated for the crystal to image (film) distance parameter e.g. CTOF[1][2] 126.4 (Value of 126.4 set for plate 2 of pack 1) CTOF[][3] 126.9 (Value of 126.9 set for plate 3 of each pack) CTOF[2][] 130.2 (Value of 130.2 set for each plate of pack 2) CTOF[][] 150.7 (Value of 150.7 set for all packs and plates) CTOF 150.7 (Same as previous case) CTOF[] 150.7 (Same as previous case) CTOF[2] 130.2 (Same as third case with a value of 130.2 set for each plate of pack 2) Keywords including any pack/plate specifications may not include any embedded spaces. Round brackets may be used in place of the square brackets in the pack/plate 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 an LDM 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. LDM data files may contain indirect references to data in another file by giving a file name reference of the form: @filename Indirect files may currently be nested to a level of up to 20. 1.4 READING AND WRITING LDM DATA Functions are supplied to make the reading and writing of LDM data easy for the application programmer. In reading data from a file, the subroutine LDM_READLINE allows for the next logical line of data to be read. Any continuation lines are combined into the single string returned and any comments are removed. The maximum logical line length allowed is 1000 characters. Indirect file specifications are processed by the LDM_READLINE routine when encountered. In cases where data are not being read from a file but a text string containing the LDM specifications is available for processing, the subroutine LDM_READSTR will perform a similar function on this string again handling any indirect file references. When the next logical line of data has been obtained using one of these routines, the line is parsed for LDM data using the LDM_PARSE routine. If any valid LDM keywords are found, then the data values will be checked and the data will be automatically stored in the module. LDM and non-LDM data may not be present on the same line of input. Any errors in the LDM data values or other LDM keywords on the line will be flagged. If there is no LDM data on the line then it is returned to the program for further processing by the calling program and thus program specific data may be given in the same file as the LDM data. The reading of LDM data is illustrated in the figure below. Figure 1.1 Flowchart for Reading LDM Data For writing LDM data files or outputting a listing of the current LDM data to a terminal, the subroutine LDM_WRITE is used. The LDM data may be output at different levels of detail as desired though all non-default LDM parameter values will always be given. If the output data are read in again the LDM parameter data will of course always have the same values regardless of the output level used. The four output levels are as follows:- 1) Only output non-default values. 2) Always output a standard set of parameters even if they have default values and also any additional parameters which have non-default values. Where possible, the minimum output will be given for pack/plate specific parameters by examining, for example, whether a parameter value is the same for all pack or all plates in a pack. This option is recommended as the standard form of output for an LDM file. 3) Output all LDM parameters but minimise output where possible as in the previous case. 4) Give all LDM parameters and all individual pack/plate parameters explicitly. It is important that the LDM parameter values are output sufficiently accurately so that there is no significant loss of accuracy when a set of LDM data is written out and read in again. To ensure this, each parameter has its own default output format specified internally. This is only used if the parameter value has been recalculated within the program. Otherwise the parameter values are output with the same number of decimal places that were used when they were input thus giving more readable files with no additional loss of accuracy. A facility is also available within the LDM routines to monitor parameter changes and write out only those parameters which have changed between specified points in a program. This enables a clearer record to be made of parameter value changes, e.g. to a log file, particularly if a windows based program is used where parameters may be manually changed at almost any stage. 1.5 LDM ROUTINES As indicated above, the application programmer must always access the LDM data through the routines supplied. Each LDM parameter has its own routines to get and to set the parameter values. In addition, there is a general purpose get routine LDM_GET and a general purpose set routine LDM_SET which in which each parameter is identified by its keyword string. There are also some additional convenience routines available and special routines for handling the space group symmetry. 1.6 COORDINATE SYSTEMS The internal and external coordinate systems used in the LDM specification and coding are basically those used in the Daresbury Laboratory Laue Software Suite (see Helliwell et al., 1989) which were in turn based on those used in MOSFLM. The features relevant to the description of the Laue Data Module are illustrated in Figures 2 and 3. The illustrations are for flat plate detectors.If the cylindrical camera option is used, the cylinder axis is assumed to be parallel to the rotation (laboratory 'Z' axis) with the crystal situated on the axis. Figure 1.2 Laboratory and Detector Axes Figure 1.3 Ideal & detector axes and Camera Constants 1.7 LAUE REFLECTION LIST (LRL) One of the basic functions required when processing Laue diffraction data is to be able to predict a list of reflections for the image being processed. For this purpose a Laue Reflection List (LRL) structure has been defined and routines written to enable such a list to be generated from the Laue Data Module. Again, the structure of the list is effectively encapsulated and all access to its data must be made through the routines supplied. The reflections list is generated for the individual plate whenever it is needed using for example the LRL_GEN subroutine. If this routine is used, a record is kept such that, if the routine is called again for the current plate, the list will only be re-generated if any of the LDM parameters, which affect the prediction, have been changed. The Laue reflections list is, more strictly, a predicted spots list and is accessed by spot number. Details are stored for multiple spots so that the individual reflections within such a spot may be generated if required. For each spot, storage space is available to hold an integrated intensity value. If several images are to be integrated, the integrated intensities from each need to be copied to other storage or to an output file after each one has been integrated as the Laue Reflection List applies to only one image at a time. For each generated spot, the data stored include the following:- * h, k, l - the indices. For a multiple spot these will be the indices of the lowest harmonic present. * x, y - the spot position in mm from the diffraction pattern centre (normally distortion corrected) * lambda - the wavelength. For a multiple spot, the wavelength for the lowest harmonic is stored. * (1/d_min)**2 threshold for the occurrence of the spot. * multipliciity, minimum harmonic, maximum harmonic, harmonic increment - this information enables the component reflections for a multiple spot to be generated. * spatial overlap flags - these indicate which spots are spatially overlapped and which are too close to deconvolute at integration time. * integrated intensity and flags - this is space to store, on a temporary basis, an integrated intensity for a spot, its standard deviation and related flags. The flags include an 'intensity measured' flag, a 'good/bad flag', an 'overload' flag and a code which may be defined by the integration routines. Routines are available to return details from the spots in the LRL and to store an integrated intensity value if required. A routine is also available to sort the data in a number of ways. The data actually remain in place but all spots are accessed internally via a indexing array. 1.8 LDM RELATED FUNCTIONS A number of routines have already been written to make use of the data in the Laue Data Module and the generated Laue Reflections List. Two examples of how the LDM and LRL are used are given here. The first shows a crystal orientation parameter refinement routine which, in addition to the LDM and LRL, requires a list of observed spot positions for a selected set of spots. The second shows the procedure of Hao, Harding & Campbell (1994) using routines for carrying out spot integration and for determining improved values for the lambda_min or d_min soft limits. Figure 1.4 Flowchart for Parameter Refinement Figure 1.5 Flowchart for Soft Limits Determination 1.9 THE LDM PARAMETERS The following tables summarise the LDM parameters 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 LDM_WRITE routine always outputs the full keywords. Some abbreviations used in the list are: ch Character Ipix Pixel intensity in an image file o.d. Optical density undef Undefined (R) Real number (I) Integer deg Degrees mu Microns Description Keyword Units Default Values Notes Non-refineable Parameters ========================= Dataset Crystal name CRYStal string ' ' 50ch 1 Title TITLe string ' ' 250ch 1 Crystal system SYSTem code Tri (1) Tri, Mon, Ort, 2, 30 Tet, Hex, Rho, Cub, (1-7) Lattice type LATTice code P (1) P, A, B, C, I, 2, 30 F, R, (1-7) Symmetry SYMMetry code (undef) see note 3 Set: beam BEAM_axis code +b* (2) +a*, +b*, +c*, 4, 30 -a*, -b*, -c*, (+/- 1, 2, 3) Set: rotation ROTAtion_axis code +a* (1) +a*, +b*, +c* 4, 30 -a*, -b*, -c*, (+/- 1, 2, 3) No. of packs NUMPack integer 0 >=0 5 No. plates/pack NPLAtes integer 1 >0 5 Image type IMAGE_Type code ip (2) film, ip (1, 2) 6, 30 Image data IMAGE_Data code i2 (2) byte, i2, mar, 6, 30 pfbyte (1-4) Detector geometry DGEOm code flat (1) flat, cyl (1,2) 6, 12, 28, 30, 31 Data order AXORd code +xd+yd see note 6 No. x-rasters NXRAst integer 1200 >0 7 No. y-rasters NYRAst integer 1200 >0 7 Raster size RASTer_size mu 100.0 >0.0 7 File template TEMPlate string img####.od 120ch 8 rmin RMIN mm 0.0 >=0.0 9 rmax RMAX mm 50.0 >0.0 9 xlow XLOW rasters 0.0 >=0.0 9 xhigh XHIGh rasters 0.0 (=all) >=0.0 9 ylow YLOW rasters 0.0 >=0.0 9 yhigh YHIGh rasters 0.0 (=all) >=0.0 9 Detector tilt DTILt degrees 0.0 any real 10 Spindle increment DSPIn degrees 20.0 any 11 Distortion type DISTortion_type code standard standard, 12, 30 (1) r/toff, spdxy, (1-3) Overload value OVERload_pixel Ipix(I) (0=max) >=0 13 Spot epsilon SPOT_EPsilon mm 0.05 >0.0 14 Fiducials use FIDType code no no, yes (0, 1) 15, 30 Fiducials FIDX1 10mu -4000.0 any 15 FIDY1 10mu 5000.0 any 15 FIDX2 10mu -4000.0 any 15 FIDY2 10mu -5000.0 any 15 FIDX3 10mu 4000.0 any 15 FIDY3 10mu -5000.0 any 15 Fids threshold FTHResh Ipix(R) 125.0 >=0.0 15 Fids box size FIDBox mm 5.0 0.0 15 Spot threshold STHResh Ipix(R) 100.0 >=0.0 16 Film n1od N1OD Ipix(I) 128 >0 17 Film g1od G1OD mu 2.3 >0.0 17 Film baseod BASEod o.d.(R) 0.04 >=0.0 17 Non-linearity NONLinearity real 0.07 any 17 Pack Spindle SPINdle[] degrees 0.0, 20... any 18 pack id. PACK_Id[] integer 1, 2... >=0 19 key plate KEYPlate integer 1 >0 20 Plate file name FILEname[][] string ' ' 120ch 21 x_cen_f X_CEN_f[][] rasters 0.0 undef >=0.0 22 y_cen_f Y_CEN_f[][] rasters 0.0 undef >=0.0 22 plate spacing SPACing[][] mm 0.0 >=0.0 23 Refineable Parameters ===================== Dataset Cell A A A 50.0 >0.0 24 Cell B B A 60.0 >0.0 24 Cell C C A 70.0 >0.0 24 Cell alpha ALPHa degrees 90.0 >0.0 24 Cell beta BETA degrees 90.0 >0.0 24 Cell gamma GAMMa degrees 90.0 >0.0 24 Pack lambda-min LMIN[] A 0.25 >=0.0 25 lambda-max LMAX[] A 2.5 >0.0 25 dmin DMIN[] A 2.5 >0.0 25 PhiX PHIX[] degrees 0.0 any 18 PhiY PHIY[] degrees 0.0 any 18 PhiZ PHIZ[] degrees 0.0 any 18 Plate c_to_f CTOF[][] mm 60.0 >0.0 23 y_scale Y_SCale[][] real 1.0 >0.0 26 x_c X_C[][] mm 0.0 any 27 y_c Y_C[][] mm 0.0 any 27 w_c W_C ][] degrees 0.0 any 27 spot length SPOT_LEngth[][] mm 0.5 >0.0 28 spot width SPOT_WIdth[][] mm 0.0 >=0.0 28 spot factor SPOT_FActor[][] real 0.0 any 28 spot border SPOT_BOrder[][] pixels 2.0 >0.0 28 spot delta SPOT_DElta[][] mm 0.5 >0.0 28 twist TWISt[][] 0.01deg 0.0 any 12 tilt TILT[][] 0.01deg 0.0 any 12 bulge BULGe[][] 0.01deg 0.0 any 12 roff ROFF[][] 10mu 0.0 any 12 toff TOFF[][] 10mu 0.0 any 12 spdxy SPDXY[][] real 0.0 any 12 spdx_n SPDX_N[][] integer 1 >0 12 spdx_min SPDX_MIN[][] mm -150.0 <=-10.0 12 spdx_max SPDX_MAX[][] mm +150.0 >=+10.0 12 spdx1, spdx2 ... SPDXi[][] real 0.0 any 12 i = 1, 2, 3 ... spdy_n SPDY_N[][] integer 1 >0 12 spdy_min SPDY_MIN[][] mm -150.0 <=-10.0 12 spdy_max SPDY_MAX[][] mm +150.0 >=+10.0 12 spdy1, spdy2 ... SPDYi[][] real 0.0 any 12 i = 1, 2, 3 ... refined flag RFL[][] integer 0 0=no, 1=yes 29 Notes: 1) The title and crystal name parameters are character strings which are taken from the text following the keyword to the end of the line. 2) For the crystal system only the first three characters are matched and for the lattice type a single character is matched. 3) The initial data processing of Laue data is normally done without making use of the full symmetry information and with systematic absences being based only on the lattice type. However the full symmetry may be defined if required and in this case the systematic absences will be determined using this information. The SYMMETRY parameter has a number of options and may not be followed by any other LDM parameter on the same line. These are: SYMMETRY CLEAR Clears out the current symmetry SYMMETRY nspg Space group code number SYMMETRY op1, op2, ... Add the symmetry operators to the current list The 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. 4) A standard setting is defined by indicating which reciprocal axis is closest to the X-ray beam direction and which reciprocal axis is closest to the crystal rotation axis. The orientation is calculated relative to this setting. 5) The number of packs of images used in the experiment and the number of plates (/films) in each pack. 6) The image (detector) types currently recognised are film and image plate. Four image data formats are specifically recognised. 'Byte' and 'i2' indicate image files with no header information and with each pixel instensity being stored as an unsigned byte or unsigned two-byte integer quantity. The third format 'mar' is the current format for the MAR image plate system. The fourth option 'pfbyte' is for Photon factory images with each pixel being stored as an unsigned byte value representing the pixel intensity on a logarithmic scale (pixel intensity = nint(10**(4.0*ipix/255.0)-1) where 'ipix' is the stored pixel value from 0-255). Alternatively, a code of the general form site:type (identified by the presence of the colon) may be given; this is passed back to the calling program to enable site specific data formats to be handled. Additional image types and data types may be added to the LDM specification at a later stage as needed. The detector geometry parameter specifies whether the detector is a flat plate (the normal case) or a cylindrical camera. The data order code defines the axis order in the image in terms of x and y (the detector xd, yd axes). The slower moving axis is given first followed by the faster moving axis. A minus sign is used when the order of an axis is reversed. The code 's' if present indicates that byte swapping is to be done and the code 'n' indicates that no byte swapping is to be done (byte swapping only relevant for some image data types). Characters, other than 'x', 'y', '-', '+', 's' and 'n', or their upper case equivalents, are ignored. Examples of valid axis order strings are xy, +xd+yd and -yxs. 7) These are the number of rasters in the detector xd and yd directions and the raster size in the x direction. If the raster is rectangular rather than square, this is handled via the refineable y_scale parameter. 8) Image file names may be specified explicitly if required but the filename template parameter provides a convenient way of giving the file names for a systematically named set of images. A field of # symbols in the template will be replaced by the pack identifier number (with an additional alphabetic plate identifier if there is more than one plate in a pack). The idenfifier will fill at least the number of positions occupied by the # characters with leading zeros being added if required. Complete details are given in the documentation of the LDM_FILENAME routine. 9) 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'. Additionally, the processing may be restricted to a rectangular section (by default the whole image) by using the limits 'xlow', 'xhigh', 'ylow' and 'yhigh' along the detector axes. 10) Normally the detector is normal to the X-ray beam. The detector tilt allows for the rotation of the detector around the same axis as the crystal rotation axis. A tilt of 180 may be used for back reflection Laue. The tilt parameter is ignored for a cylindrical camera. 11) This is only used if a series of spindle angles are defined implicitly for a set of packs. If the SPINDLE parameter is defined in its global form with the value of the spindle angle, spindle, for the first pack and the DSPIN parameter is set to dspin , then the spindle angles for the subsequent packs will be set to spindle+dspin, spindle+2dspin etc. The required value of DSPIN must be set before the definition of SPINDLE or otherwise it will have no effect. By default the spindle angles will be set to 0.0, 20.0, 40.0 etc. 12) Three ways of describing distortion in the scanned image are currently available. The 'standard' option is that used originally for film distortions in the MOSFLM program. The 'r/toff' distortion correction was introduced, into MOSFLM originally, for handling the radially scanned MAR image plates. The 'spdxy' distortion correction is a correction using two orthogonal polynomial based correction terms and a cross xy term as described by Campbell (1994) except that Chebyshev Polynomials are now used rather than simple polynomials. In all three cases, detector tilt and twist angles may be defined. For the 'standard' distortion type, an additional bulge parameter is defined. For the 'r/toff' option, radial and tangential offset parameters roff and toff are defined. For the 'spdxy' case the various spd.. parameters define the polynomial range, order and coefficients and also a value for the cross term. The formulae used in the distortion corrections are given by Campbell et al., 1994. Note that the distortion correction types are designed for use with a flat plate and will give limited success with a cylindrical camera; y_scale should be appropriate and twist, tilt and the 'spdxy' corrections will probably be the best option to use. 13) Pixel intensities >= this value will be considered to be detector overloads. If a value of zero is given then all pixel intensities in the image will be considered to be valid. 14) When a reflection list is generated, spots closer than this epsilon limit will be flagged as being too close to be considered for spatial deconvolution at the intensity integration stage. 15) Fiducial marks were routinely used in the processing of X-ray diffraction data recorded on film packs. A flag indicates whether or not fiducials are to be used and the approximate positions of the three fiducial marks from the image mid-point may be stored. The box size, for searching for the actual fiducial positions around the approximate positions, and a fiducials intensity threshold (absolute) can be defined. If fiducials are defined then the plate centre is calculated from the mid point between fiducial marks 1 and 3 and the line joining fiducial marks 2 and 3 is assumed to be approximately parallel to the detector xd axis. 16) The spot intensity threshold is used when spot positions are to be found for auto-indexing or crystal orientation refinement. The threshold is an intensity level above the local background level on the image. 17) These parameters are for the processing of data recorded on film. 'n1od' is the pixel intensity corresponding to an optical density of 1.0 units, 'g1od' is the Selwyn granularity at unit optical density and 'baseod' is the optical density of the film base. A non-linearity constant is also defined. 18) The crystal orientation is defined by a set of crystal rotations phi_x, phi_y and phi_z around the laboratory axes from the setting defined using the ROTATION_AXIS and BEAM_AXIS parameters plus an additional rotation around the spindle axis (equivalent to a change in phi_z). For a set of packs with exposures related by rotating the crystal around the spindle axis, the mis-orientation angles for the first pack may be determined assuming an arbitrary spindle angle of zero degrees. Basically the same mis-orientation angles may then be used for the subsequent packs with the spindle angles for these packs being set to their offsets from the first pack. Note: The Daresbury Laboratory Laue Suite uses the convention that the phi_x and phi_z rotations are in the positive sense but phi_y 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(phi_x), s_y = sin(phi_y) etc. See also Carr, Cruickshank & Harding, J. Appl. Cryst. (1992) 25, 294-308 and in particular the note at the bottom of page 297. 19) Packs have integer pack identifiers associated with them. If a global value is input for the pack identifier, then this is taken as being the value for the first pack and successive pack identifiers will be incremented by 1. By default the pack identifiers are the same as the pack numbers 1, 2, 3 ... NUMPACK. 20) For a multi-plate pack, the key plate is the one to be used for the orientation determination and initial refinement of that pack. This will normally be the first plate in the pack but another one may be selected using the KEYPLATE parameter if required. 21) A file name may be defined explicitly for each plate of each pack. If the image filename for a plate is blank, then the file name for that plate will be constructed from the filename template as described above. 22) The x_cen_f and y_cen_f parameters define the input or measured position for the centre of the diffraction pattern. The exact centre use for pattern prediction is this input centre with additions of the refineable camera constants x_c, y_c (see Figure 3) . 23) The c_to_f parameter defines the cystal to detector distance for each pack and plate. If global (for the plate specification) c_to_f parameter values are input, then the spacing parameters of successive plates are used to set the successive c_to_f values. Any spacing value defined for the first plate is ignored. Spacings are distances from the front of the previous plate. 24) These are the real cell parameters in Angstoms and degrees. Where relevant, it is the responsibility of the application program to ensure that they are consistent with the crystal system specified. 25) Soft-limits are defined for the minimum and maximum wavelengths lambda_min and lambda_max and for the resolution limit of the diffraction d_min. These are treated as refineable parameters and separate values may be assigned for each pack. 26) The y_scale parameter allows for the fact that the pixels may not be exactly square. It may be defined as the the raster size in the detector x direction divide by the raster size in the detector y direction. It is treated as a refineable parameter. 27) These are the refineable camera constants as shown in Figure 3 . It may be noted that any relative rotation of plates within, for example, a pack of scanned films and derived from the fiducial positions is incorporated into the value of w_c. This is in contrast to the definition used in the MOSFLM program and also in some programs of the Laue Software Suite where separate w_f and w_c rotations are defined. The value of wc is normally taken as 0.0 for the first plate of a pack and any such rotation is incorporated in the refined mis-orientation angles. 28) These parameters define the spot shape. If a spot width of 0.0 is given then round spots with a diameter equal to the defined spot length are assumed. In this case the spot delta value is used to define that any spots closer than this are spatially overlapped. If spot width is defined, then the spots are treated as having an elliptical shape and are treated as described by Greenhough & Shrive (1994). Spatial overlaps are determined by whether or not the spot ellipses, optionally including the background border, overlap. The spot border is an elliptical ring around the spot of the defined value in pixels and is used for background determinations at the intensity integration stage. The spot factor allows for variable spot lengths in a radial direction. A value of 0.0 gives constant spot lengths, a value >0 gives increasing length with distance from the pattern centre and a negative value gives decreasing spot lengths. The spot length is given by the expression spotlength(1.0+spot_factor*r/c_to_f) where 'r' is the distance of the spot from the pattern centre. The general formulation is not really appropriate for a cylindrical camera where round spots should probably be assumed. 29) The refined flag is given to indicate whether or not the crystal orientation etc. refinement has been carried out for the plate in question. This is intended to be used as a safeguard to prevent, for example, attempting to integrate spot intensities for an image without having carried out the required orientation refinement. 30) These items may be set or returned as either code strings or integer flags. 31) If the cylindrical camera option is used, the cylinder axis is assumed to be parallel to the rotation (laboratory 'Z' axis) with the crystal situated on the axis. Note that the LDM spot shape formulation using radially oriented ellipses is not really appropriate for the cylindrical camera case. Note also, that the distortion correction types are designed for use with a flat plate. 1.10 EXTENDED LDM PARAMETER SETS The basic specification of LDM parameters is largely fixed though it may prove necessary to add a few more parameters, or to add further options to some existing ones. Such additions would be expected to lie within the scope of the Laue Data Module as defined above. Examples of such legitimate developments would be to add a new image format, spatial distortion correction type or detector geometry. It may well be desirable, however, to be able to extend the range of parameters available for particular programs or suites of Laue data processing software and to include some parameters which are really program specific (e.g. integration options). As it is felt that the Laue Data Module itself should not have parameters added for these purposes, an alternative mechanism has been provided which preserves the integrity of the LDM definition but enables, in practice, an extended set of parameters to be used. Following the development of the LDM data module, another more general set of routines were developed (this time in 'C' but with Fortran interfaces) which allows keyworded parameters to be set up under program control. These Keyword Data Module (KDM) routines are used as the mechanism to create additional keywords under program control and to store the data relating to such items. Additional LDM routines have been supplied to enable the creation of effectively an extended LDM parameter set under program control. Such extended LDM parameters will automatically be handled by the routines which are currently used to read and write LDM data and the general LDM routines used to set and to get parameter values. Parameters may have integer, real or character string values (some other options are also availble). As in the case of the LDM parameters, the newly defined parameters may refer either to the dataset as a whole, to each pack being processed or to each image within a pack. If an extended LDM parameter set is to be used for a Laue program suite, then it is probably desirable that all programs of the suite should be able to make use of the same set of parameters. Thus the facility should be used with some thought and some caution. 1.11 REFERENCES Greenhough, T. J., & Shrive, A. K., (1994) J. Appl. Cryst. 27111-121 Hao, Q., Harding, M.M. & Campbell, "Determination of d-min and lambda-min from the intensity distribution of Laue Patterns" J. Appl. Cryst. (1995) 28447-450 Helliwell, J.R., Habash, J., Cruickshank, D.W.J, Harding, M.M., Greenhough, T.J., Campbell, J.W., Clifton, I.J., Elder, M., Machin, P.A., Papiz, M.Z. & Zurek, S. (1989). J. Appl. Cryst. 22483-497. Campbell, J.W., Clifton, I.J., Harding, M.M. & Hao Q., "The Laue Data Module (LDM) - a software development for Laue X-ray diffraction data processing" J. Appl. Cryst. (1995) 28635-640 CHAPTER 2: LAUE DATA MODULE (LDM) ROUTINES ========================================== 2.1 INTRODUCTION This chapter gives details of the routines which are available to read, write and access the Laue Data Module (LDM) Data. The following sets of routines are available: Read, Parse and Write LDM Data Setting LDM Parameter Values Getting LDM Parameter Values Symmetry Handling Routines Convenience and Supplementary LDM Routines Monitor LDM Parameter Value Changes Make Distortion Corrections to Coordinates Save and Restore Refineable Parameter Values Special Routines for Use with Laue Reflection Lists Special Reciprocal Lattice to Detector Conversions Handle Extended LDM Data 2.2 READ, PARSE AND WRITE LDM DATA 2.2.1 Introduction Routines are available to read lines of data from a file (accessing indirect file references if present) and to examine such lines for LDM data; if such data are found the data will be checked for validity and stored in the Laue Data Module. Any non-LDM data lines will be returned to the calling program for interpretation by that program and this LDM and other control or parameters data may be included in the file being read. Lines of data from other sources may also be interpreted using the parsing routine and indirect file references in such data may be handled if required. A routine is also available to write out the current LDM data to a file; this has a number of options ranging from only writing non-default data items to writing all data items for every pack and plate where relevant. There is also an option to write out only LDM parameter values which have been changed since a particular point in a program. The following routines are available: Read Line of Data from a File - LDM_READLINE Handle Indirect File References in a String - LDM_READSTR Parse Line Containing LDM Data - LDM_PARSE Parse LDM Data with Additional Checking - LDM_CHK_PARSE Parse and LDM Item - LDM_PARSEITEM Write LDM Parameters Data - LDM_WRITE 2.2.2 Read Line of Data from a File - LDM_READLINE This routine will return, on repeated calls, the next logical line of data read from a parameters file. Any indirectly referenced parameter files will be read as required. The logical line returned will contain any continuation lines present but will exclude any comments found. Fortran call: SUBROUTINE LDM_READLINE (IUN, KUN, INDIRECT, LINE, EOF, IERR) Parameters: IUN i (R) Logical unit number of file/stream being read. KUN i (R) Start logical unit number for use with indirect files. Unit nos. (up to MAXIND e.g. 20) in sequence will be used but any already open will be skipped. INDIRECT i (R/W) Current indirection level. MUST be set to 0 on first call to read the file and subsequently must give the previously returned value.You should ensure that the program repeats calls to the routine until EOF is returned as .TRUE. or INDIRECT is returned as 0 (otherwise files will be left open) LINE c (W) Returns the next logical line with comments removed and with all continuation lines included. EOF l (W) .TRUE. End of file encountered on main input stream (IUN) .FALSE. No end of file on main input stream. IERR i (W) Returned error flag = 0 OK = 1 LINE too short, data truncated = 2 Error opening indirect file = 3 Maximum allowed level of indirection exceeded = 4 Insufficient Fortran units available for opening indirect files = 5 Calling error (invalid INDIRECT value) For error flags > 1, all opened indirect files will be closed Notes: Allows for indirect reads from specified files up to MAXIND levels (e.g. 20) in depth. Conventions for comments & continuations similar to CCP4 parser but only '!' introduces comments (and not '#') If '@' not followed by a file name is found, then all indirection is cancelled and the next line is read from the main input stream. 2.2.3 Handle Indirect File References in a String - LDM_READSTR This routine is similar to LDM_READLINE in its handling of indirect files. The difference is that the line for examination is passed to the routine rather than being read from a top level parameter file. Fortran call: SUBROUTINE LDM_READSTR (LINE, KUN, INDIRECT, IFLAG, IERR) Parameters: LINE c (R/W) On input is the line to be decoded for indirect file specification. The string should not contain comment or continuation characters and, if an indirect file specification is used, then it should only contain that specification. On output is the next line read from an indirect file (or the original line if no indirection found (or blank if the input line contained '@' only)). KUN i (R) Start logical unit number for use with indirect files. Unit nos. (up to MAXIND e.g. 20) in sequence will be used but any already open will be skipped. INDIRECT i (R/W) Current indirection level. MUST be set to 0 on first call to read the file and subsequently must give the previously returned value. You should ensure that the program repeats calls to the routine until IFLAG or INDIRECT are returned as 0 (otherwise files will be left open). IFLAG i (W) Flag = 0, if first call and string does not contain indirect file specification. 'LINE' is returned as input. = 1, Line read from indirect file =-1, End of indirect data reached IERR i (W) Returned error flag = 0 OK = 1 LINE too short, data truncated = 2 Error opening indirect file = 3 Maximum allowed level of indirection exceeded = 4 Insufficient Fortran units available for opening indirect files = 5 Calling error (invalid INDIRECT value) For error flags > 1, all opened indirect files will be closed Notes: Allows for indirect reads from specified files up to MAXIND levels (e.g. 20) in depth. Conventions for comments & continuations similar to CCP4 parser but only '!' introduces comments (and not '#') If '@' not followed by a file name is found, then all indirection is cancelled. A blank line will be returned and IFLAG will be returned as 0 (see above) 2.2.4 Parse Line Containing LDM Data - LDM_PARSE This routine parses a given line of data, examining it for the presence of LDM data. Any such data found is automatically checked and, if valid, stored in the Laue Data Module. If the line does not contain LDM data, then it is merely passed back to the calling program to allow further interpretation by that program. LDM and non-LDM data must not be given in the same line of data and a line of data containing any valid LDM keyword will be assumed to be an LDM parameter line. The calling program should also take account of the fact that incorrectly specified LDM keyords may result in the line being returned to the calling program. Fortran call: SUBROUTINE LDM_PARSE (LINE, IFLAG, BADTOK, ERRSTR) Parameters: LINE c (R) Character string containing line to be parsed (Assume comments & continuations already removed) IFLAG i (W) Return flag = 0, Laue module data found & OK = 1, Not Laue module data = 2, No non-blank tokens < 0, Laue module data but error(s) =-1, Invalid or inappropriate pack specification =-2, Invalid or inappropriate plate specification =-3, Syntax error in pack/plate specification =-4, Invalid code/string value or syntax error =-5, Invalid value - must be >=0.0 (>=0) =-6, Invalid value - must be >0.0 (>0) =-7, Other out of range value =-8, Non-LDM data mixed with LDM data (Possibly miss-spelt keyword) -100, Coding error in LDM routines, information supposedly already checked is found later to be invalid! BADTOK c (W) Returns the token string for an invalid token ERRSTR c (W) Error string (max 80 chars) if IFLAG<0 2.2.5 Parse LDM Data with Additional Checking - LDM_CHK_PARSE This routine is similar to LDM_PARSE but a user supplied routine may make an additional check on each LDM parameter and disable its update if desired. Fortran call: SUBROUTINE LDM_CHK_PARSE (LINE, PGM_CHK, IFLAG, BADTOK, ERRSTR) Parameters: LINE c (R) Character string containing line to be parsed (Assume comments & continuations already removed) PGM_CHK s (R) Subroutine to make additional check on LDM parameters to restrict updates (or return other information to calling program about the parameters found via common blocks) The call will be as follows: CALL PGM_CHK (KEYWORD, OK) KEYWORD (R) CHARACTER*(*) variable holding the full name of the LDM parameter or extended LDM parameter. OK (W) Logical flag; return .TRUE. if parameter may be updated or .FALSE. if it may not. IFLAG i (W) Return flag = 0, Laue module data found & OK = 1, Not Laue module data = 2, No non-blank tokens < 0, Laue module data but error(s) =-1, Invalid or inappropriate pack specification =-2, Invalid or inappropriate plate specification =-3, Syntax error in pack/plate specification =-4, Invalid code/string value or syntax error =-5, Invalid value - must be >=0.0 (>=0) =-6, Invalid value - must be >0.0 (>0) =-7, Other out of range value =-8, Non-LDM data mixed with LDM data (Possibly miss-spelt keyword) -100, Coding error in LDM routines, information supposedly already checked is found later to be invalid! BADTOK c (W) Returns the token string for an invalid token ERRSTR c (W) Error string (max 80 chars) if IFLAG<0 2.2.6 Parse and LDM Item - LDM_PARSEITEM This routine is used by the higher level parsing routines described above but may be called by the user if required. It examines a given string to see if it is a valid LDM keyword and, if so, interprets and returns any pack/plate specification given. Fortran call: SUBROUTINE LDM_PARSEITEM (STR, KEYWORD, IPACK, IPLATE, + KTYP, IERR) Parameters: STR c (R) String containing the keyword string to be examined KEYWORD c (W) Returns the full keyword name if the string is an LDM parameter (up to 20 characters in length) IPACK i (W) Returns pack specification for an LDM parameter if allowed and if present IPLATE i (W) Returns plate specification for an LDM parameter if allowed and if present KTYP i (W) For LDM parameter returns 0 if global parameter 1 if pack parameter 2 if plate parameter IERR i (W) Error flag = 0 OK, LDM parameter & correct syntax = 1 Non-LDM parameter =-1 Pack specified when none allowed =-2 Plate specified when none allowed =-3 Syntax error in pack/plate specification 2.2.7 Write LDM Parameters Data - LDM_WRITE This is used to write out the current LDM parameters data to a data file or to a terminal. The data may be listed in different degrees of detail though any non-default parameter values are always written. A special option is available for use, in conjunction with the routines LDM_CH_RESET and LDM_ANY_CH, to write out parameter values changed since a flag was set at a particular point in a program. Fortran call: SUBROUTINE LDM_WRITE (IUNOUT, IOPTYP) Parameters: IUNOUT i (R) Unit number for output (if <0 then terminal output is required on unit -IUNOUT) IOPTYP i (R) Type of output = 1 minimum, do not o/p parameters with default values = 2 standard output (selected parameters with default values will be included) = 3 full (all parameters will be included) = 4 all individual values given for plate/pack parameters. < 0 write changed parameter values since last reset of flag for channel -IOPTYP (1-16) (see LDM_CH_RESET) 2.3 SETTING LDM PARAMETER VALUES 2.3.1 Introduction The data in the Laue data module must only be accessed via a set of supplied routines to make its use independent of the actual way the data are held. There is a set of routines available for setting the parameter values. Each LDM parameter has its own routine which should be used where efficient access is required. There is also a general routine to set a parameter value by giving the keyword and a value string. For parameters with real values there is also the following distinction made. When a value is set by the explicit routine, then subsequent o/p will be done with the default number of decimal places for that parameter; when set via the keyword and string values the subsequent o/p will use the same number of decimal places as the given string. This is intended so that any unrefined values can basically be output as they were originally input in order to clarify the parameters file. The following routines are available: General Routine to Set LDM Parameter Value - LDM_SET Reset Default LDM Parameter Value(s) - LDM_RESET Individual Routines to Set LDM Parameter Values - LDM_SET_... 2.3.2 General Routine to Set LDM Parameter Value - LDM_SET This routine is used to set an LDM parameter value given the full LDM keyword and a value string. Any pack/plate specifications are checked and the parameter value is also checked for validity. Fortran call: SUBROUTINE LDM_SET (KEYWORD, IPACK, IPLATE, VALSTR, + IERR, ERRSTR) Parameters: KEYWORD c (R) Full keyword string (upper case) IPACK i (R) Pack number or 0=all packs (if relevant for the parameter) IPLATE i (R) Plate number or 0=all plates (if relevant for the parameter) VALSTR c (R) The string containing the parameter value IERR i (W) Error flag = 0 OK =-1 Invalid pack specification =-2 Invalid plate specification =-3 Invalid LDM keyword =-4 Invalid polynomial coefficient no. =-4 Memory allocation error = 1 Invalid code/string or syntax error in number = 2 Invalid value - must be >=0.0 (>=0) = 3 Invalid value - must be >0.0 (>0) = 4 Invalid value - must be <=0.0 (<=0) = 5 Invalid value - must be <0.0 (<0) = 6 Other out of range number = 7 Invalid value for extended LDM keyword ERRSTR c (W) Returns string for error message (max. 80 chars) 2.3.3 Reset Default LDM Parameter Value(s) - LDM_RESET This routine is used to reset the default parameter value for an individual LDM parameter or for all LDM parameters. A blank keyword string indicates all parameters. Fortran call: SUBROUTINE LDM_RESET (KEYWORD, IPACK, IPLATE, IERR, ERRSTR) Parameters: KEYWORD c (R) Full keyword string (upper case) or blank to reset all LDM parameters. IPACK i (R) Pack number or 0=all packs (if relevant for the parameter) IPLATE i (R) Plate number or 0=all plates (if relevant for the parameter) IERR i (W) Error flag = 0 OK =-1 Invalid pack specification =-2 Invalid plate specification =-3 Invalid LDM keyword ERRSTR c (W) Returns string for error message (max. 80 chars) 2.3.4 Individual Routines to Set LDM Parameter Values - LDM_SET_... These are the individual routines for setting LDM parameter values. As there are a large number of routines involved and as these routines have very similar parameters, a general description of the parameters is given here and only the list of parameters is given with each individual subroutine. General description of parameters for 'set' routines: KEYWORD c (R) Full keyword string (upper case) (blank = all parameters for LDM_RESET) VALUE r (R) The real parameter value to be set IVAL i (R) The integer parameter value to be set VALSTR c (R) A string containing the parameter value SVAL() r (R) Values of the polynomial coefficients for Spatial distortion polynomial parameters; for single coefficient put value in first element of the array. (if ICOEFF.EQ.0) dimension to at least LDM_MAXSPD) IPACK i (R) Pack number or 0=all packs (if relevant for the parameter) IPLATE i (R) Plate number or 0=all plates (if relevant for the parameter) ICOEFF i (R) Coefficient no. if > 0, 0=all coefficients (Spatial distortion polynomial parameters) IERR i (W) Error flag = 0 OK =-1 Invalid pack specification =-2 Invalid plate specification =-3 Invalid LDM keyword =-4 Invalid polynomial coefficient no. = 1 Invalid code/string or syntax error in number = 2 Invalid value - must be >=0.0 (>=0) = 3 Invalid value - must be >0.0 (>0) = 4 Invalid value - must be <=0.0 (<=0) = 5 Invalid value - must be <0.0 (<0) = 6 Other out of range number ERRSTR c (W) Returns string for error message if IERR is non-zero (max. 80 chars) Routines: CRYStal SUBROUTINE LDM_SET_CRYST (VALSTR, IERR, ERRSTR) TITLe SUBROUTINE LDM_SET_TITLE (VALSTR, IERR, ERRSTR) SYSTem SUBROUTINE LDM_SET_SYST (VALSTR, IVAL, IERR, ERRSTR) LATTice SUBROUTINE LDM_SET_LATT (VALSTR, IVAL, IERR, ERRSTR) SYMMetry SUBROUTINE LDM_SET_SYMM (VALSTR, IERR, ERRSTR) BEAM_axis SUBROUTINE LDM_SET_BEAM (VALSTR, IVAL, IERR, ERRSTR) ROTAtion_axis SUBROUTINE LDM_SET_ROT (VALSTR, IVAL, IERR, ERRSTR) IMAGE_Type SUBROUTINE LDM_SET_IMTYP (VALSTR, IVAL, IERR, ERRSTR) IMAGE_Data SUBROUTINE LDM_SET_IMDAT (VALSTR, IVAL, IERR, ERRSTR) DGEOm SUBROUTINE LDM_SET_DGEOM (VALSTR, IVAL, IERR, ERRSTR) AXORd SUBROUTINE LDM_SET_AXORD (VALSTR, IERR, ERRSTR) FIDType SUBROUTINE LDM_SET_FIDT (VALSTR, IVAL, IERR, ERRSTR) FIDX1 SUBROUTINE LDM_SET_FIDX1 (VALUE, IERR, ERRSTR) FIDY1 SUBROUTINE LDM_SET_FIDY1 (VALUE, IERR, ERRSTR) FIDX2 SUBROUTINE LDM_SET_FIDX2 (VALUE, IERR, ERRSTR) FIDY2 SUBROUTINE LDM_SET_FIDY2 (VALUE, IERR, ERRSTR) FIDX3 SUBROUTINE LDM_SET_FIDX3 (VALUE, IERR, ERRSTR) FIDY3 SUBROUTINE LDM_SET_FIDY3 (VALUE, IERR, ERRSTR) NXRAst SUBROUTINE LDM_SET_NXRAS (IVAL, IERR, ERRSTR) NYRAst SUBROUTINE LDM_SET_NYRAS (IVAL, IERR, ERRSTR) RASTer_size SUBROUTINE LDM_SET_RAST (VALUE, IERR, ERRSTR) RMIN SUBROUTINE LDM_SET_RMIN (VALUE, IERR, ERRSTR) RMAX SUBROUTINE LDM_SET_RMAX (VALUE, IERR, ERRSTR) XLOW SUBROUTINE LDM_SET_XLOW (VALUE, IERR, ERRSTR) XHIGh SUBROUTINE LDM_SET_XHIGH (VALUE, IERR, ERRSTR) YLOW SUBROUTINE LDM_SET_YLOW (VALUE, IERR, ERRSTR) YHIGh SUBROUTINE LDM_SET_YHIGH (VALUE, IERR, ERRSTR) DISTortion_type SUBROUTINE LDM_SET_DSTOR (VALSTR, IVAL, IERR, ERRSTR) FTHResh SUBROUTINE LDM_SET_FTHR (VALUE, IERR, ERRSTR) FIDBox SUBROUTINE LDM_SET_FBOX (VALUE, IERR, ERRSTR) STHResh SUBROUTINE LDM_SET_STHR (VALUE, IERR, ERRSTR) OVERload_pixel SUBROUTINE LDM_SET_OVPIX (IVAL, IERR, ERRSTR) NUMPack SUBROUTINE LDM_SET_NUMP (IVAL, IERR, ERRSTR) NPLAtes SUBROUTINE LDM_SET_NPLAT (IVAL, IERR, ERRSTR) TEMPlate SUBROUTINE LDM_SET_TEMPL (VALSTR, IERR, ERRSTR) SPOT_Epsilon SUBROUTINE LDM_SET_EPS (VALUE, IERR, ERRSTR) DTILt SUBROUTINE LDM_SET_DTILT (VALUE, IERR, ERRSTR) N1OD SUBROUTINE LDM_SET_N1OD (IVAL, IERR, ERRSTR) G1OD SUBROUTINE LDM_SET_G1OD (VALUE, IERR, ERRSTR) BASEod SUBROUTINE LDM_SET_BASE (VALUE, IERR, ERRSTR) NONLinearity SUBROUTINE LDM_SET_NONL (VALUE, IERR, ERRSTR) DSPIn SUBROUTINE LDM_SET_DSPIN (VALUE, IERR, ERRSTR) SPINdle SUBROUTINE LDM_SET_SPIN (IPACK, VALUE, IERR, ERRSTR) PACK_id SUBROUTINE LDM_SET_PID (IPACK, IVAL, IERR, ERRSTR) KEYPlate SUBROUTINE LDM_SET_KEYP (IPACK, IVAL, IERR, ERRSTR) FILEname SUBROUTINE LDM_SET_FNAME (IPACK, IPLATE, VALSTR, + IERR, ERRSTR) X_CEN_f SUBROUTINE LDM_SET_XCENF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) Y_CEN_f SUBROUTINE LDM_SET_YCENF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPACing SUBROUTINE LDM_SET_SPAC (IPACK, IPLATE, VALUE, + IERR, ERRSTR) A SUBROUTINE LDM_SET_A (VALUE, IERR, ERRSTR) B SUBROUTINE LDM_SET_B (VALUE, IERR, ERRSTR) C SUBROUTINE LDM_SET_C (VALUE, IERR, ERRSTR) ALPHA SUBROUTINE LDM_SET_ALPHA (VALUE, IERR, ERRSTR) BETA SUBROUTINE LDM_SET_BETA (VALUE, IERR, ERRSTR) GAMMA SUBROUTINE LDM_SET_GAMMA (VALUE, IERR, ERRSTR) LMIN SUBROUTINE LDM_SET_LMIN (IPACK, VALUE, IERR, ERRSTR) LMAX SUBROUTINE LDM_SET_LMAX (IPACK, VALUE, IERR, ERRSTR) DMIN SUBROUTINE LDM_SET_DMIN (IPACK, VALUE, IERR, ERRSTR) PHIX SUBROUTINE LDM_SET_PHIX (IPACK, VALUE, IERR, ERRSTR) PHIY SUBROUTINE LDM_SET_PHIY (IPACK, VALUE, IERR, ERRSTR) PHIZ SUBROUTINE LDM_SET_PHIZ (IPACK, VALUE, IERR, ERRSTR) CTOF SUBROUTINE LDM_SET_CTOF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) Y_SCale SUBROUTINE LDM_SET_YSCAL (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPOT_Length SUBROUTINE LDM_SET_SPOTL (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPOT_Width SUBROUTINE LDM_SET_SPOTW (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPOT_Factor SUBROUTINE LDM_SET_SPOTF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPOT_Border SUBROUTINE LDM_SET_SPOTB (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPOT_Delta SUBROUTINE LDM_SET_SPOTD (IPACK, IPLATE, VALUE, + IERR, ERRSTR) X_C SUBROUTINE LDM_SET_XC (IPACK, IPLATE, VALUE, + IERR, ERRSTR) Y_C SUBROUTINE LDM_SET_YC (IPACK, IPLATE, VALUE, + IERR, ERRSTR) W_C SUBROUTINE LDM_SET_WC (IPACK, IPLATE, VALUE, + IERR, ERRSTR) TWISt SUBROUTINE LDM_SET_TWIST (IPACK, IPLATE, VALUE, + IERR, ERRSTR) TILT SUBROUTINE LDM_SET_TILT (IPACK, IPLATE, VALUE, + IERR, ERRSTR) BULGe SUBROUTINE LDM_SET_BULGE (IPACK, IPLATE, VALUE, + IERR, ERRSTR) ROFF SUBROUTINE LDM_SET_ROFF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) TOFF SUBROUTINE LDM_SET_TOFF (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDXY SUBROUTINE LDM_SET_SPDXY (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDX_N SUBROUTINE LDM_SET_SPDXN (IPACK, IPLATE, IVAL, + IERR, ERRSTR) SPDX_MIn SUBROUTINE LDM_SET_SXMIN (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDX_MAx SUBROUTINE LDM_SET_SXMAX (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDX1, SPDX2... SUBROUTINE LDM_SET_SPDX (ICOEFF, IPACK, IPLATE, + SVAL, IERR, ERRSTR) SPDY_N SUBROUTINE LDM_SET_SPDYN (IPACK, IPLATE, IVAL, + IERR, ERRSTR) SPDY_MIn SUBROUTINE LDM_SET_SYMIN (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDY_MAx SUBROUTINE LDM_SET_SYMAX (IPACK, IPLATE, VALUE, + IERR, ERRSTR) SPDY1, SPDY2... SUBROUTINE LDM_SET_SPDY (ICOEFF, IPACK, IPLATE, + SVAL, IERR, ERRSTR) RFL SUBROUTINE LDM_SET_RFL (IPACK, IPLATE, IVAL, + IERR, ERRSTR) . 2.4 GETTING LDM PARAMETER VALUES 2.4.1 Introduction The data in the Laue data module must only be accessed via a set of supplied routines to make its use independent of the actual way the data values are stored internally. Each LDM parameter has its own routine which should be used where efficient access is required. There is also a general routine to retrieve a parameter value for a given LDM keyword string The following routines are available: General Routine to Get LDM Parameter Value - LDM_GET Individual Routines to Get LDM Parameter Values - LDM_GET_... Routine to Get All SPD... Parameter Values - LDM_SPDXY 2.4.2 General Routine to Get LDM Parameter Value - LDM_GET This routine will return the value of any LDM parameter except for the 'SYMMETRY' parameter. The parameter value is returned as string, and where relevant as a real or integer value. The symmetry data may only be returned via the specific LDM_GET_SYMM routine. For AXORD only the string is returned and not IORD or ISWAP Fortran call: SUBROUTINE LDM_GET (KEYWORD, IPACK, IPLATE, VALSTR, VALUE, ND, + IVAL, IFLAG, ITYP, IERR, ERRSTR) Parameters: KEYWORD c (R) Full keyword string (upper case) Note: All LDM keywords valid excepy SYMMETRY. The symmetry data may only be returned via the specific LDM_GET_SYMM routine. For AXORD only the string is returned and not IORD or ISWAP IPACK i (R) Pack number (explicit) if relevant for the parameter IPLATE i (R) Plate number (explicit) if relevant for the parameter VALSTR i (W) The value returned as a string (max 120 chars) VALUE r (W) The parameter value as a real number for 'real number' parameters. ND i (W) The number of decimal places to be printed for 'real number' parameters (-ve for E format) IVAL i (W) The parameter value as an integer for integer parameters IFLAG i (W) The status of the parameter value =-1 undefined = 0 default = 1 set explicitly = 2 set globally ITYP i (W) = 0 string value returned = 1 string value and integer code = 2 integer value (string also returned) = 3 real value (string also returned) = 4 LDM extended integer parameter = 5 LDM extended float parameter = 6 LDM extended single token string parameter = 7 LDM extended multiple token string parameter = 8 LDM extended variable array parameter IERR i (W) Error flag = 0 OK = 1 Invalid keyword = -1 Invalid pack number = -2 Invalid plate number = -3 Invalid polynomial coefficient number = -4 Any error from extended LDM keyword ERRSTR c (W) Returns string for error message (max. 80 chars) Note: for an extended LDM parameter, only the first integer or real value will be returned for any parameter which has more than one value. Also the value string length of 120 may not be adequate in all cases. Special purpose routines should be written to get values for such parameters (or use KDMF_GETVALUE calls directly) 2.4.3 Individual Routines to Get LDM Parameter Values - LDM_GET_... These are the individual routines for getting LDM parameter values. As there are a large number of routines involved and as these routines have very similar parameters, a general description of the parameters is given here and only the list of parameters is given with each individual subroutine. General description of parameters for 'get' routines: KEYWORD c (R) Full keyword string (upper case) without any pack/plate specification. IPACK i (R) Pack number (explicit) if relevant for the parameter IPLATE i (R) Plate number (explicit) if relevant for the parameter ICOEFF i (R) Coefficient no. if > 0, 0=all coefficients (for spatial distortion polynomial parameters only) VALSTR c (W) The value returned as a string (max 120 chars) VALUE r (W) The parameter value as a real number for 'real number' parameters. ND i (W) The number of decimal places to be printed for 'real number' parameters (-ve for E format). This may be the default for the parameter or may be derived from the value string used to set the parameter value (see the LDM parameter value setting routines) IVAL i (W) The parameter value as an integer for integer parameters SVAL() r (W) Returns polynomial coefficients (for the spatial parameters only). (if ICOEFF.GT.0 value is returned in SVAL(1)) (if ICOEFF.EQ.0 dimension to at least LDM_MAXSPD) IFLAG i (W) The status of the parameter value =-1 undefined = 0 default = 1 set explicitly = 2 set globally ITYP i (W) = 0 string value returned = 1 string value and integer code = 2 integer value (string also returned) = 3 real value (string also returned) IERR i (W) Error flag = 0 OK = 1 Invalid keyword = -1 Invalid pack number = -2 Invalid plate number = -3 Invalid polynomial coefficient number ERRSTR c (W) Returns string for error message (max. 80 chars) Routines: CRYStal SUBROUTINE LDM_GET_CRYST (VALSTR, IFLAG) TITLe SUBROUTINE LDM_GET_TITLE (VALSTR, IFLAG) SYSTem SUBROUTINE LDM_GET_SYST (VALSTR, IVAL, IFLAG) LATTice SUBROUTINE LDM_GET_LATT (VALSTR, IVAL, IFLAG) SYMMetry SUBROUTINE LDM_GET_SYMM (NSPG, SPGNAME, PGNAME, + NSYMMP, NSYMM, RSM, RSMT, IFLAG) (see separate section on Symmetry Handling Routines) BEAM_axis SUBROUTINE LDM_GET_BEAM (VALSTR, IVAL, IFLAG) ROTAtion_axis SUBROUTINE LDM_GET_ROT (VALSTR, IVAL, IFLAG) IMAGE_Type SUBROUTINE LDM_GET_IMTYP (VALSTR, IVAL, IFLAG) IMAGE_Data SUBROUTINE LDM_GET_IMDAT (VALSTR, IVAL, IFLAG) DGEOm SUBROUTINE LDM_GET_DGEOM (VALSTR, IVAL, IFLAG) AXORd SUBROUTINE LDM_GET_AXORD (VALSTR, IORD, ISWAP, IFLAG) FIDType SUBROUTINE LDM_GET_FIDT (VALSTR, IVAL, IFLAG) FIDX1 SUBROUTINE LDM_GET_FIDX1 (VALUE, IFLAG, ND) FIDY1 SUBROUTINE LDM_GET_FIDY1 (VALUE, IFLAG, ND) FIDX2 SUBROUTINE LDM_GET_FIDX2 (VALUE, IFLAG, ND) FIDY2 SUBROUTINE LDM_GET_FIDY2 (VALUE, IFLAG, ND) FIDX3 SUBROUTINE LDM_GET_FIDX3 (VALUE, IFLAG, ND) FIDY3 SUBROUTINE LDM_GET_FIDY3 (VALUE, IFLAG, ND) NXRAst SUBROUTINE LDM_GET_NXRAS (IVAL, IFLAG) NYRAst SUBROUTINE LDM_GET_NYRAS (IVAL, IFLAG) RASTer_size SUBROUTINE LDM_GET_RAST (VALUE, IFLAG, ND) RMIN SUBROUTINE LDM_GET_RMIN (VALUE, IFLAG, ND) RMAX SUBROUTINE LDM_GET_RMAX (VALUE, IFLAG, ND) XLOW SUBROUTINE LDM_GET_XLOW (VALUE, IFLAG, ND) XHIGh SUBROUTINE LDM_GET_XHIGH (VALUE, IFLAG, ND) YLOW SUBROUTINE LDM_GET_YLOW (VALUE, IFLAG, ND) YHIGh SUBROUTINE LDM_GET_YHIGH (VALUE, IFLAG, ND) DISTortion_type SUBROUTINE LDM_GET_DSTOR (VALSTR, IVAL, IFLAG) FTHResh SUBROUTINE LDM_GET_FTHR (VALUE, IFLAG, ND) FIDBox SUBROUTINE LDM_GET_FBOX (VALUE, IFLAG, ND) STHResh SUBROUTINE LDM_GET_STHR (VALUE, IFLAG, ND) OVERload_pixel SUBROUTINE LDM_GET_OVPIX (IVAL, IFLAG) NUMPack SUBROUTINE LDM_GET_NUMP (IVAL, IFLAG) NPLAtes SUBROUTINE LDM_GET_NPLAT (IVAL, IFLAG) TEMPlate SUBROUTINE LDM_GET_TEMPL (VALSTR, IFLAG) SPOT_Epsilon SUBROUTINE LDM_GET_EPS (VALUE, IFLAG, ND) DTILt SUBROUTINE LDM_GET_DTILT (VALUE, IFLAG, ND) N1OD SUBROUTINE LDM_GET_N1OD (IVAL, IFLAG) G1OD SUBROUTINE LDM_GET_G1OD (VALUE, IFLAG, ND) BASEod SUBROUTINE LDM_GET_BASE (VALUE, IFLAG, ND) NONLinearity SUBROUTINE LDM_GET_NONL (VALUE, IFLAG, ND) DSPIn SUBROUTINE LDM_GET_DSPIN (VALUE, IFLAG, ND) SPINdle SUBROUTINE LDM_GET_SPIN (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) PACK_id SUBROUTINE LDM_GET_PID (IPACK, IVAL, IFLAG, + IERR, ERRSTR) KEYPlate SUBROUTINE LDM_GET_KEYP (IPACK, IVAL, IFLAG, + IERR, ERRSTR) FILEname SUBROUTINE LDM_GET_FNAME (IPACK, IPLATE, VALSTR, IFLAG, + IERR, ERRSTR) X_CEN_f SUBROUTINE LDM_GET_XCENF (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) Y_CEN_f SUBROUTINE LDM_GET_YCENF (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPACing SUBROUTINE LDM_GET_SPAC (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) A SUBROUTINE LDM_GET_A (VALUE, IFLAG, ND) B SUBROUTINE LDM_GET_B (VALUE, IFLAG, ND) C SUBROUTINE LDM_GET_C (VALUE, IFLAG, ND) ALPHa SUBROUTINE LDM_GET_ALPHA (VALUE, IFLAG, ND) BETA SUBROUTINE LDM_GET_BETA (VALUE, IFLAG, ND) GAMMa SUBROUTINE LDM_GET_GAMMA (VALUE, IFLAG, ND) LMIN SUBROUTINE LDM_GET_LMIN (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) LMAX SUBROUTINE LDM_GET_LMAX (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) DMIN SUBROUTINE LDM_GET_DMIN (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) PHIX SUBROUTINE LDM_GET_PHIX (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) PHIY SUBROUTINE LDM_GET_PHIY (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) PHIZ SUBROUTINE LDM_GET_PHIZ (IPACK, VALUE, IFLAG, ND, + IERR, ERRSTR) CTOF SUBROUTINE LDM_GET_CTOF (IPACK, IPLATE, VALUE, IFLAG, +ND, IERR, ERRSTR) Y_SCale SUBROUTINE LDM_GET_YSCAL (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPOT_Length SUBROUTINE LDM_GET_SPOTL (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPOT_Width SUBROUTINE LDM_GET_SPOTW (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPOT_Factor SUBROUTINE LDM_GET_SPOTF (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPOT_Border SUBROUTINE LDM_GET_SPOTB (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPOT_Delta SUBROUTINE LDM_GET_SPOTD (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) X_C SUBROUTINE LDM_GET_XC (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) Y_C SUBROUTINE LDM_GET_YC (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) W_C SUBROUTINE LDM_GET_WC (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) TWISt SUBROUTINE LDM_GET_TWIST (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) TILT SUBROUTINE LDM_GET_TILT (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) BULGe SUBROUTINE LDM_GET_BULGE (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) ROFF SUBROUTINE LDM_GET_ROFF (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) TOFF SUBROUTINE LDM_GET_TOFF (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDXY SUBROUTINE LDM_GET_SPDXY (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDX_N SUBROUTINE LDM_GET_SPDXN (IPACK, IPLATE, IVAL, IFLAG, + IERR, ERRSTR) SPDX_MIn SUBROUTINE LDM_GET_SXMIN (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDX_MAx SUBROUTINE LDM_GET_SXMAX (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDX1, SPDX2... SUBROUTINE LDM_GET_SPDX (ICOEFF, IPACK, IPLATE, SVAL, + IFLAG, ND, IERR, ERRSTR) SPDY_N SUBROUTINE LDM_GET_SPDYN (IPACK, IPLATE, IVAL, IFLAG, + IERR, ERRSTR) SPDY_MIn SUBROUTINE LDM_GET_SYMIN (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDY_MAx SUBROUTINE LDM_GET_SYMAX (IPACK, IPLATE, VALUE, IFLAG, + ND, IERR, ERRSTR) SPDY1, SPDY2... SUBROUTINE LDM_GET_SPDY (ICOEFF, IPACK, IPLATE, SVAL, + IFLAG, ND, IERR, ERRSTR) RFL SUBROUTINE LDM_GET_RFL (IPACK, IPLATE, IVAL, IFLAG, + IERR, ERRSTR) . 2.4.4 Routine to Get All SPD... Parameter Values - LDM_SPDXY This routine enables all the parameters related to using a polynomial based spatial distortion to be retrieved in one call and should be used where several such parameter values are required and where efficiency of retrieval is important. Fortran call: SUBROUTINE LDM_SPDXY (IPACK, IPLATE, SPD_XY, + NSPDX, SPDX_MIN, SPDX_MAX, SXVAL, + NSPDY, SPDY_MIN, SPDY_MAX, SYVAL, + MAXDIM, IERR, ERRSTR) Parameters: IPACK i (R) Pack number (explicit) IPLATE i (R) Plate number (explicit) SPD_XY r (W) Returns spdxy correction factor NSPDX i (W) Returns polynomial order SPDX_N SPDX_MIN r (W) Returns lower x chebyshev polynomial bound SPDX_MAX r (W) Returns upper x chebyshev polynomial bound SXVAL() r (W) Returns polynomial coefficients for x (see MAXDIM) NSPDY i (W) Returns polynomial order SPDY_N SPDY_MIN r (W) Returns lower y chebyshev polynomial bound SPDY_MAX r (W) Returns upper y chebyshev polynomial bound SYVAL() r (W) Returns polynomial coefficients for y (see MAXDIM) MAXDIM i (R) Maximum dimension of SXVAL, SYVAL arrays (Note: only MAXDIM coefficients will be returned if this is less than the LDM limit which may be found using the LDM_SPDMAX function. IERR i (W) Error flag = 0 OK =-1 Invalid pack number =-2 Invalid plate number ERRSTR c (W) Error string if error found 2.5 SYMMETRY HANDLING ROUTINES 2.5.1 Introduction A special set of routines are required to retrieve symmetry information as the symmetry parameter data is more complex than for the other LDM parameters. Routines are also available to determine systematic absences, list symmetry operators and to set up the information to enable reflections to be assigned to a standard assymetric unit using CCP4 routines. The following routines are available: Get Full Symmetry Data - LDM_GET_SYMM Get Basic Space Group Details - LDM_GET_SPGRP Get Number of Symmetry Operators - LDM_GET_NSYM Check for Systematic Absence - LDM_SYSABS Get Systematic Absence Based on H, K - LDM_SYSAHK List Symmetry Data - LDM_SYMM_LIST Prepare to Convert Indices to Assymetric Unit - LDM_AUSET Write symmetry to MTZ file - LDM_LWSYMM Write symmetry to LIRL - LDM_LIRLSYMM 2.5.2 Get Full Symmetry Data - LDM_GET_SYMM This routine is used to get the full symmetry detail including such items as the space group, point group and symmetry operator matrices. Fortran call: SUBROUTINE LDM_GET_SYMM (NSPG, SPGNAME, PGNAME, NSYMMP, NSYMM, + RSM, RSMT, IFLAG) Parameters: NSPG i (W) Space group number (will be 0 if symmetry operators were input explicitly. SPGNAME c (W) Space group name (will be blank if symmetry operators were input explicitly) (10 characters) PGNAME c (W) Point group name (10 characters) NSYMMP i (W) No. of primitive symmetry operators NSYMM i (W) Total number of symmetry operators (0 if symmetry not defined) RSM() r (W) The NSYMM symmetry operators - dimensioned (4,4,192) RSMT() r (W) The NSYMM inverted symmetry operators -dimensioned (4,4,192) IFLAG i (W) Flag = -1 undefined value = 0 default value = 1 value set explicitly = 2 value set globally 2.5.3 Get Basic Space Group Details - LDM_GET_SPGRP This routine rentuns where possible the space group number and name and the number of primitive and totla number of symmetry operators. Fortran call: SUBROUTINE LDM_GET_SPGRP (NSPG, SPGNAME, NSYMMP, NSYMM) Parameters: NSPG i (W) Space group number (will be 0 if symmetry operators were input explicitly. SPGNAME c (W) Space group name (will be blank if symmetry operators were input explicitly) (10 characters) NSYMMP i (W) No. of primitive symmetry operators NSYMM i (W) Total number of symmetry operators (0 if symmetry not defined) 2.5.4 Get Number of Symmetry Operators - LDM_GET_NSYM This routine returns the number of symmetry operators or 0 if no symmetry has been defined. This provides the simplest way of determining whether the symmetry has been defined. Fortran call: SUBROUTINE LDM_GET_NSYM (NSYMM, IFLAG) Parameters: NSYMM i (W) Total number of symmetry operators (0 if symmetry not defined) IFLAG i (W) Flag = -1 undefined value = 0 default value = 1 value set explicitly = 2 value set globally 2.5.5 Check for Systematic Absence - LDM_SYSABS This routine checks whether a given reflection is a systematic absence based on the symmetry information available. Its initial checks are based on the lattice type but it will then use the full symmetry information if this has been defined. Fortran call: SUBROUTINE LDM_SYSABS (IH,IK,IL,ABSNT) Parameters: IH i (R) h index IK i (R) k index IL i (R) l index ABSNT l (W) returns =.TRUE. systematically absent, =.FALSE. not 2.5.6 Get Systematic Absence Based on H, K - LDM_SYSAHK This is a variant on LDM_SYSABS and checks to see if a given 'h', 'k' reflection is absence regardless of 'l'. It only uses the lattice type and not the full symmetry. Fortran call: SUBROUTINE LDM_SYSAHK (IH,IK,ABSNT) Parameters: IH i (R) h index IK i (R) k index ABSNT l (W) returns =.TRUE. systematically absent, =.FALSE. not 2.5.7 List Symmetry Data - LDM_SYMM_LIST This routine lists the symmetry operators to a file or a terminal. Fortran call: SUBROUTINE LDM_SYMM_LIST (IUN, TERM) Parameters: IUN i (R) Unit no. for listing o/p TERM l (R) .TRUE. o/p is to a terminal; .FALSE. o/p is to a file 2.5.8 Prepare to Convert Indices to Assymetric Unit - LDM_AUSET This routine calls the CCP4 routine ASUSET to prepare for converting indices to the asyymetric unit etc. using ASUPUT, ASUGET. The ASUSET routine is called via the LDM routine because it can access data stored internally within the Laue Data Module and avoid having to duplicate such data unnecessarily. Fortran call: SUBROUTINE LDM_ASUSET (MLAUE) Parameters: MLAUE i (W) Returns the Laue group number 2.5.9 Write symmetry to MTZ file - LDM_LWSYMM This routine calls the MTZ library routine LWSYMM to write the symmetry data (if defined) to the header of an MTZ file. The LWSYMM routine is called via the LDM routine because it can access data stored internally within the Laue Data Module and avoid having to duplicate such data unnecessarily. Fortran call: SUBROUTINE LDM_LWSYMM (MTZIDX) Parameters: MTZIDX i (R) MTZ file index 2.5.10 Write symmetry to LIRL - LDM_LIRLSYMM This routine calls the Laue Integrated Reflection List (LIRL) routine LIRLF_SETSYM to set the symmetry for the list. The LIRLF_SETSYM routine is called via the LDM routine because it can access data stored internally within the Laue Data Module and avoid having to duplicate such data unnecessarily. Fortran call: SUBROUTINE LDM_LIRLSYMM (MINDX) Parameters: MINDX i (R) Index for the LIRL 2.6 CONVENIENCE AND SUPPLEMENTARY LDM ROUTINES 2.6.1 Introduction This section includes a number of useful routines for decoding axis order strings, getting mm to raster conversion factors, determining an image file name (using template or explicit definition as appropriate). Routines are also listed in this section for returning the spatial distortion polynomial coefficient limit and for converting strings to integer or real numbers. The following routines are available: Interpret Axis Order String - LDM_AXORD Millimetre to Raster Conversion Factors - LDM_MMRAST Get Image File Name From Definition or Template - LDM_FILENAME Find LDM Limit SPD Polynomial Coefficients - LDM_SPDMAX Find LDM Number of Packs - LDM_PKMAX Find LDM Number of Plates per Pack - LDM_PLMAX Decode Character String into a Number - LDM_INTFP 2.6.2 Interpret Axis Order String - LDM_AXORD This routine decodes an axis order string as described in the parameter list. Fortran call: SUBROUTINE LDM_AXORD (VALSTR, IORD, ISWAP, IERR, ERRSTR) Parameters: VALSTR c (R) The string containing the axis order code string to be interpreted. The string defines the axis order in terms of x and y (the detector xd, yd axes). The slower moving axis is given first followed by the faster moving axis. Minus signs are used when the order of an axis is reversed. The code 's' if present indicates that byte swapping is to be done and the code 'n' indicates that no byte swapping is to be done (byte swapping only relevant for image plate data). Characters, other than 'x', 'y', '-', '+', 's' and 'n', or their upper case equivalents, are ignored. Some examples follow and the returned flags are indicated: xy IORD = 1, ISWAP = 0 +x+y IORD = 1, ISWAP = 0 -xy IORD = 3, ISWAP = 0 x-y s IORD = 2, ISWAP = 2 -Y, +X, n IORD = 7, ISWAP = 1 S IORD = 0, ISWAP = 2 +yd, +xd IORD = 4, ISWAP = 0 Invalid strings: +x-x (Same axis defined twice) +x+y-x (More than two axes defined) xysn (Byte swapping and no byte swapping both defined) IORD i (W) Returns the axis order as a number from 1 - 8 0 if none specified (or syntax error) 1 +xd slow +yd fast 2 +xd slow -yd fast 3 -xd slow +yd fast 4 -xd slow -yd fast 5 +yd slow +xd fast 6 +yd slow -xd fast 7 -yd slow +xd fast 8 -yd slow -xd fast ISWAP i (W) Returns byte swap type =1 do not swap bytes =2 swap bytes =0 not specified (or syntax error) IERR i (W) Error flag 0 = OK 1 = Only one axis defined 2 = Both axes the same 3 = More than two axes defined 4 = byte swap and no byte swap both given ERRSTR c (W) Error message string (up to 80 chars) 2.6.3 Millimetre to Raster Conversion Factors - LDM_MMRAST This routine returns the conversion factors from millimetres to rastors for the requested pack and plate number. Fortran call: SUBROUTINE LDM_MMRAST (IPACK, IPLATE, MM_RAST_X, MM_RAST_Y) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number MM_RAST_X r (W) Conversion factor for mm to x-rasters MM_RAST_Y r (W) Conversion factor for mm to y-rasters 2.6.4 Get Image File Name From Definition or Template - LDM_FILENAME This routine returns the image file name for a given pack and plate. If an explicit name has been defined for the file name then this will be returned. Otherwise the name will be created from the file name template using the pack id and plate number. Full details are given in the parameter descriptions for the routine. Fortran call: SUBROUTINE LDM_FILENAME (IPACK, IPLATE, FILNAM) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number FILNAM c (W) Returns file name If explicit one present then this is returned. If not then one is derived from the template which normally contains a sequence of '#' characters; these are replaced with the pack_id (+plate identifier) with at least as many characters use as '#' characters in the sequence. The pack_id is output as an integer with leading zeros if needed; If the number of plates in the pack is greater than one then the pack_id will be followed by the plate letter 1=a, 2=b etc. Examples: 1) Template lys####.i2 pack_id=15 1 plate file name returned = lys0015.od 2) Template pf####.od pack_id=12 no. 1 of 6 plates file name returned = pf012a.od 3) As above but for 2'nd plate file name returned = pf012b.od 3) Template pf#.od pack_id=12 no. 1 of 6 plates file name returned = pf12a.od For non-standard cases, the treatments are as follows: If no '#' is present in the template, the pack_id (+ plate identifier) will be added just before the '.' of file extension; if there is no file extension the pack_id (+ plate identifier) will be added at the of the template string. If there are more than 26 plates in the pack the plate identifier will be added as an underscore followed by the plate number 2.6.5 Find LDM Limit SPD Polynomial Coefficients - LDM_SPDMAX This function returns the currently compiled in limit for the maximum coefficient for polynomial based spatial distortion corrections. Programs which use a LDM routines to retrieve all coefficients in an array will need to be aware of this limit and take appropriate steps if it is not consistent with the dimensions of the program's own arrays. Fortran call: INTEGER FUNCTION LDM_SPDMAX(IDUM) Return: Maximum allowed order for SPDXi, SPDYi terms. CD-end Arguments: INTEGER IDUM D-Parameters: IDUM (R) Dummy argument 2.6.6 Find LDM Number of Packs - LDM_PKMAX This function returns the currently compiled in limit for the maximum number of packs. Fortran call: INTEGER FUNCTION LDM_PKMAX(IDUM) Return: Maximum allowed number of packs. CD-end Arguments: INTEGER IDUM D-Parameters: IDUM (R) Dummy argument 2.6.7 Find LDM Number of Plates per Pack - LDM_PLMAX This function returns the currently compiled in limit for the maximum number of plater per pack. Fortran call: INTEGER FUNCTION LDM_PLMAX(IDUM) Return: Maximum allowed number of plates per pack. CD-end Arguments: INTEGER IDUM D-Parameters: IDUM (R) Dummy argument 2.6.8 Decode Character String into a Number - LDM_INTFP This routine will decode a character string into an integer or floating point number. Fixed point or scientific notation numbers are both valid. Fortran call: FUNCTION LDM_INTFP (CHSTR, FP, IV, ND) Return: = 0 Syntax error in the number = 1 integer (no decimal point present) = 2 floating point no. =-1 blank string Parameters: CHSTR c (R) Character string containing the number to be decoded (Leading spaces ignored; further space terminates the number string interpreted) FP r (W) Returns the value as a floating point value (0.0 if syntax error) IV i (W) Returns the value as an integer (the nearest integer if value contained a decimal point) (0 if syntax error) ND i (W) No. of digits after the decimal point. (-ve if E format number) 2.7 MONITOR LDM PARAMETER VALUE CHANGES 2.7.1 Introduction Routines are available to enable the monitoring of changes to LDM parameter values. A routine is available to set a flag on one of 16 independent channels and the Laue Data Module will keep track of any LDM parameter value changes since that flag was set. The changed parameter values may be written out using an option of the LDM_WRITE routine. A routine is also provided to check whether there have been any changes on a given channel. The following routines are available: Reset Parameter Change Monitoring Flags - LDM_CH_RESET Check for Parameter Value Changes - LDM_ANY_CH 2.7.2 Reset Parameter Change Monitoring Flags - LDM_CH_RESET This routine resets the flag for monitoring subsequent LDM parameter value changes for the requested channel or for all channels. Fortran call: SUBROUTINE LDM_CH_RESET (ICH) Parameters: ICH i (R) Initialise/clear parameter changed flags for this channel (1-16, 0 = all channels) 2.7.3 Check for Parameter Value Changes - LDM_ANY_CH This routine enables a check to be made on whether and LDM parameter values have been changed since the changes monitoring flag was set for a particular channel. Fortran call: LOGICAL FUNCTION LDM_ANY_CH (ICH) Parameters: ICH i (R) Examine flags for this channel (1-16, 0 = all channels) Return: .TRUE. if any changes found, otherwise .FALSE. 2.8 MAKE DISTORTION CORRECTIONS TO COORDINATES 2.8.1 Introduction A routine is avaiable to make the appropriate distortion corrections to an ideal predicted spot position. The routine takes account of the current distortion type and the various distortion parameters. The following routines are available: Make Distortion Corrections to Ideal Coordinates - LDM_CORR 2.8.2 Make Distortion Corrections to Ideal Coordinates - LDM_CORR This routine will make the appropriate distortion corrections to an ideal predicted spot position. The routine takes account of the current distortion type and the various distortion parameters. cos(w_c) and sin(w_c) are passed as parameters to the routine so that, in suitable circumstances, they need not be re-calculated each time that LDM_CORR is called. Fortran call: SUBROUTINE LDM_CORR (IPACK, IPLATE, COS_WC, SIN_WC, CF, XF, YF, + XFD, YFD) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number COS_WC r (R) cos(w_c) for the pack and plate SIN_WC r (R) sin(w_c) for the pack and plate CF r (R) crystal-film distance for the pack and plate XF r (R) Predicted reflection 'xf' coordinate in mm with respect to the predicted pattern centre. YF r (R) Predicted reflection 'yf' coordinate in mm with respect to the predicted pattern centre. XFD r (W) Distortion corrected 'xfd' parameter in mm with respect to the predicted centre. The coordinate is now along the direction of the actual image 'xd' axis YFD r (W) Distortion corrected 'yfd' parameter in mm with respect to the predicted centre. The coordinate is now along the direction of the actual image 'yd' axis 2.9 SAVE AND RESTORE REFINEABLE PARAMETER VALUES 2.9.1 Introduction These routines enable the refineable LDM parameter values to be saved for a given pack and plate before a refinement is carried out and restore, if required, if the refined values are not deemen to be acceptable. The routines are included as LDM routines as they need to access internal flags within the LDM. The following routines are available: Save Refineable Parameters - LDM_SAVERP Restore Saved Refineable Parameters - LDM_RESTRP 2.9.2 Save Refineable Parameters - LDM_SAVERP This routine will save the values of the refineable parameters for a requested pack and plate. Fortran call: SUBROUTINE LDM_SAVERP (IPACK, IPLATE) Parameters: IPACK i (R) Pack number (explicit) IPLATE i (R) Plate number (explicit) 2.9.3 Restore Saved Refineable Parameters - LDM_RESTRP Restore the refineable LDM parameters saved by the last call to LDM_SAVERP. Fortran call: SUBROUTINE LDM_RESTRP (IPACK, IPLATE) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number 2.10 SPECIAL ROUTINES FOR USE WITH LAUE REFLECTION LISTS 2.10.1 Introduction These routines enable flags to be set when Laue Reflection List (LRL) routine have been used to predict a set of spots. The LDM module keeps track of whether any of the parameters required for the prediction have been changed since the list was predicted and a routine is available to query such changes. This can be used to save regenerating lists when they are not required and checking when they need to be regenerated. These routines are used for example by the LRL_GEN routine and if this is used to generate spot lists then the routines described in this section will not normally need to be called explicitly from an application program. The following routines are available: Set LRL Generation Flags - LDM_LRL_CALC See if LRL Needs to be Regenerated - LDM_CHK_GEN 2.10.2 Set LRL Generation Flags - LDM_LRL_CALC This routine is used to inform the Laue Data Module that a stage of the generation of a Laue Reflection List (LRL) for a given pack and plate has been completed. There are three stages identified in the generation of the LRL. Fortran call: SUBROUTINE LDM_LRL_CALC (IPACK, IPLATE, ISTAGE) Parameters: IPACK i (R) Pack number of LRL generation IPLATE i (R) Plate number of LRL generation ISTAGE i (R) Stage = 1, matrix calculation = 2, LRL generation = 3, overlaps calculation 2.10.3 See if LRL Needs to be Regenerated - LDM_CHK_GEN This routine determines which of the three calculation stages need to be carried out to obtain a valid Laue Reflection List (LRL) for the required pack and plate. Fortran call: SUBROUTINE LDM_CHK_GEN (IPACK, IPLATE, MTX, GEN, OVL) Parameters: IPACK i (R) Pack number for which LRL is to be generated IPLATE i (R) Plate number for whic LRL is to be generated MTX l (W) =.TRUE. need to recalculate matrices, =.FALSE. do not GEN l (W) =.TRUE. need to regenerate LRL, =.FALSE. do not OVL l (W) =.TRUE. need to recalculate overlaps, =.FALSE. do not 2.11 SPECIAL RECIPROCAL LATTICE TO DETECTOR CONVERSIONS 2.11.1 Introduction Some routines are available for converting between reciprocal lattice and detector coordinates. Where appropriate, these routines should be used as they would be modified to cope with any new requirements for a detector arrangement. The currently cope with a normal or tilted detector. The following routines are available: Convert Reciprocal Lattice to Detector Coordinates - LDM_RTOD Double Precision Version of LDM_RTOD - LDM_RTOD_DP Convert Detector to Reciprocal Lattice Coordinates - LDM_DTOR Convert Detector to 'Q' Axis Coordinates - LDM_DTOQAX 2.11.2 Convert Reciprocal Lattice to Detector Coordinates - LDM_RTOD This routine will convert from reciprocal lattice to ideal detector xf, yf coordinates. It also returns a flag to indicate whether the reflection would be recorded on the detector at all assuming that it is sufficiently large. Fortran call: LOGICAL FUNCTION LDM_RTOD (X, Y, Z, DSTAR2, CTF, XF, YF) Parameters: X r (R) Reciprocal lattice X coordinate (Wonacott convention) Y r (R) Reciprocal lattice Y coordinate (Wonacott convention) Z r (R) Reciprocal lattice Z coordinate (Wonacott convention) DSTAR2 r (R) (d*)**2 for the reflection CTF r (R) Crystal to film distance (mm) XF r (W) Detector xf coordinate (mm) (Wonacott convention) YF r (W) Detector yf coordinate (mm) (Wonacott convention) Return: Returns .TRUE. if reflection would be recorded on the detector (if sufficiently large) or .FALSE. if it would not. Check to avoid divide overflow incorporated. Note: For untilted detector xf || Y, yf || Z 2.11.3 Double Precision Version of LDM_RTOD - LDM_RTOD_DP This is a double precision version of LDM_RTOD Fortran call: LOGICAL FUNCTION LDM_RTOD_DP (X, Y, Z, DSTAR2, CTF, XF, YF) Parameters: X dp (R) Reciprocal lattice X coordinate (Wonacott convention) Y dp (R) Reciprocal lattice Y coordinate (Wonacott convention) Z dp (R) Reciprocal lattice Z coordinate (Wonacott convention) DSTAR2 dp (R) (d*)**2 for the reflection CTF dp (R) Crystal to film distance (mm) XF dp (W) Detector xf coordinate (mm) (Wonacott convention) YF dp (W) Detector yf coordinate (mm) (Wonacott convention) Return: Returns .TRUE. if reflection would be recorded on the detector (if sufficiently large) or .FALSE. if it would not. Check to avoid divide overflow incorporated. Note: For untilted detector xf || Y, yf || Z 2.11.4 Convert Detector to Reciprocal Lattice Coordinates - LDM_DTOR This routine converts ideal detector coordinates to reciprocal lattice coordinates. Fortran call: SUBROUTINE LDM_DTOR (XF, YF, DSTAR2, CTF, X, Y, Z) Parameters: XF r (R) Detector xf coordinate (mm) (Wonacott convention) YF r (R) Detector yf coordinate (mm) (Wonacott convention) DSTAR2 r (R) (d*)**2 for the reflection CTF r (R) Crystal to detector distance (mm) X r (W) Reciprocal lattice X coordinate (Wonacott convention) Y r (W) Reciprocal lattice Y coordinate (Wonacott convention) Z r (W) Reciprocal lattice Z coordinate (Wonacott convention) Note: For untilted detector xf || Y, yf || Z 2.11.5 Convert Detector to 'Q' Axis Coordinates - LDM_DTOQAX This routine converts idela detector axes to coordinates with respect to a 'q' set of axes as defined in the parameter description of the routine. Fortran call: SUBROUTINE LDM_DTOQAX (XF, YF, CTF, XQ, YQ, ZQ) Parameters: XF r (R) Detector xf coordinate (mm) (Wonacott convention) YF r (R) Detector yf coordinate (mm) (Wonacott convention) CTF r (R) Crystal to detector distance (mm) XQ r (W) Reciprocal lattice X coordinate wrt 'q' axes YQ r (W) Reciprocal lattice Y coordinate wrt 'q' axes ZQ r (W) Reciprocal lattice Z coordinate wrt 'q' axes 'q' axes are as follows: Origin at crystal XQ along Wonacott Y YQ along Wonacott Z ZQ along Wonacott X (X-ray beam) For untilted flat detector: XQ=XF, YQ=YF, ZQ=CTF 2.12 HANDLE EXTENDED LDM DATA 2.12.1 Introduction Routines are available to enable the handling of LDM data with an extended set of parameters. These are managed via the 'C' based 'KDM' (Keyword Data Module) routines. LDM routines are available to add new keyword parameters of various types. The KDMF_DEFINE_... routines may also be used to define parameters of some other types and the index to the keyword set required in such calls may be obtained by calling the LDM_KDX function. If such additional parameters are defined then they will be automatically handled by routines such as LDM_PARSE, LDM_WRITE, LDM_SET, LDM_RESET, LDM_CH_RESET, LDM_ANY_CH. In most cases LDM_GET may also be used though it will not fully handle integer, real or variable array parameter value keywords with more than one integer/real value. Also the returned string for such parameters could exceed the standard 120 characters maximum. For such cases the KDMF_GETVALUE routine may be called directly to enable the full data to be returned. The following routines are available: Define a New Integer Parameter - LDM_NEWINT Define a New Floating Point Parameter - LDM_NEWFLP Define a New String Parameter - LDM_NEWSTR Get Index to KDM Keyword Set - LDM_KDX 2.12.2 Define a New Integer Parameter - LDM_NEWINT This routine is used create a new integer LDM parameter to form part of an extended LDM parameter set. Fortran call: SUBROUTINE LDM_NEWINT (KEYWORD, MINL, ITYP, ISTD, I_DEFLT, + I_MIN, I_MAX, ICHK, IERR) Parameters: KEYWORD (R) Parameter name (full) character string MINL (R) Minimum length for keyword match ITYP (R) Parameter type 1=dataset, 2=pack, 3=plate specific ISTD (R) Standard parameter for output = 1 yes, =0 no I_DEFLT (R) Default parameter value I_MIN (R) Minimum allowed value (if ICHK==5) I_MAX (R) Maximum allowed value (if ICHK==5) ICHK (R) Check value option =0 any integer OK, =1 any >=0 =2 any >0 =3 any <=0 =4 any <0 =5 must be in range I_MIN to I_MAX IERR (W) Error return = 0 OK = 1 Parameter error =-1 Cannot allocate memory 2.12.3 Define a New Floating Point Parameter - LDM_NEWFLP This routine is used create a new floating point (real) LDM parameter to form part of an extended LDM parameter set. Fortran call: SUBROUTINE LDM_NEWFLP (KEYWORD, MINL, ITYP, ISTD, F_DEFLT, + F_MIN, F_MAX, ICHK, ND, ND_DFLT, IERR) Parameters: KEYWORD (R) Parameter name (full) character string MINL (R) Minimum length for keyword match ITYP (R) Parameter type 1=dataset, 2=pack, 3=plate specific ISTD (R) Standard parameter for output = 1 yes, =0 no F_DEFLT (R) Default parameter value F_MIN (R) Minimum allowed value (if ICHK==5) F_MAX (R) Maximum allowed value (if ICHK==5) ICHK (R) Check value option =0 any integer OK, =1 any >=0.0 =2 any >0.0 =3 any <=0.0 =4 any <0.0 =5 must be in range F_MIN to F_MAX ND (R) No. of decimal places for printing value when it was recalculated by a program ND_DFLT (R) No. of decimal places for printing the default value IERR (W) Error return = 0 OK = 1 Parameter error =-1 Cannot allocate memory 2.12.4 Define a New String Parameter - LDM_NEWSTR This routine is used create a new string LDM parameter to form part of an extended LDM parameter set. Fortran call: SUBROUTINE LDM_NEWSTR (KEYWORD, MINL, ITYP, ISTD, MAXLEN, + S_DFLT, STRINGS, NUMS, LENS, ICHK, + MATCH, IERR) Parameters: KEYWORD (R) Parameter name (full) character string MINL (R) Minimum length for keyword match ITYP (R) Parameter type 1=dataset, 2=pack, 3=plate specific for single token; 4=dataset, 5=pack, 6=plate specific multiple token string ISTD (R) Standard parameter for output = 1 yes, =0 no MAXLEN (R) Maximum string length for parameter value S_DEFLT (R) Default character string STRINGS() (R) Array of character strings containing allowed values CHARACTER*LENS STRINGS(NUMS) NUMS (R) No. of strings in STRINGS LENS (R) Length of each character string element in the STRINGS array ICHK (R) Check value option =0 any string OK =1 check using allowed strings MATCH (R) Minimum no. of characters to be matched if ICHK==1; if -MATCH given then only MATCH characters will be checked and remainder will be ignored; if MATCH==0 all characters will be checked IERR (W) Error return = 0 OK = 1 Parameter error =-1 Cannot allocate memory 2.12.5 Get Index to KDM Keyword Set - LDM_KDX This routine is used get the index required to access the KDM routines for parameters belonging to an extended LDM parameter set in cases where the direct calling of such routines is required (e.g. to set up new parameters for which specific LDM routines have not been prepared or to return parameter values from multi-value parameters). Fortran call: INTEGER FUNCTION LDM_KDX(IDUM) Parameters: IDUM (R) Dummy parameter CHAPTER 3: LAUE REFLECTION LIST (LRL) ROUTINES ============================================== 3.1 INTRODUCTION These are a set of routines for generating and accessing a Laue Reflection List (LRL) for the current pack and plate based on the current values in the Laue Data Module (LDM). The list is actually a list of spots rather than individual reflections and each spot has a slot in which an integrated intensity may be stored. Spot details include multiplicity information which enables generatation of the individual reflection data if required. Functions are available to sort the spot list in a number of ways. The following sets of routines are available: Generating the Laue Reflection List Sort the Laue Reflection List Calculate an Individual Spot Position Get Global Laue Reflection List Data Items Get Individual Spot Data from Laue Reflection List Set Global Laue Reflection List Data Items Set Individual Spot Data in Laue Reflection List Interface for XDL_VIEW Laue Simulations Re-assign Spatial Overlaps and Multiplicities Determine Spatial Overlap Between Two Spots Miscellaneous Routines 3.2 GENERATING THE LAUE REFLECTION LIST 3.2.1 Introduction A high level routine is available which checks whether a list needs to be generated or whether the relevant LDM parameters are unchanged since the last call to the function; this also calls routines to calculate the orientation and 'A' matrices prior to the actual generation of the list. The lower level functions for these tasks may also be accessed directly if desired. The following routines are available: Generate Laue Reflection List (High Level) - LRL_GEN Generate Laue Reflection List (Low Level) - LRL_GNR Calculate Orientation Matrix - LDM_MK_ORIENT Calculate the Master 'A' Matrix - LRL_A_CALC Find and Mark Spatial Overlaps - LRL_OVLP Find All Spatial Overlaps - LRL_OVALL 3.2.2 Generate Laue Reflection List (High Level) - LRL_GEN This routine checks whether a new reflection list needs to be generated or whether the relevant LDM parameters are unchanged since the last call to the function. If required it calls routines to calculate the orientation and 'A' matrices prior to the actual generation of the list. Normally distortion corrected coordinates are calculated for the spot positions but there is an option to omit the distortion correction. Various ways of determining the criterion for spatially overlapped spots are available. Fortran call: SUBROUTINE LRL_GEN (IPACK, IPLATE, DISTOR, IOVTYP, IERR, ERRSTR) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number DISTOR l (R) Flag = .true. Include distortion corrections (normal case) = .false. Do not include distortion corrections IOVTYP i (R) Flag for calculation of spatial overlaps = 0, do not calculate these = 1, analytical calculation (spot + unused pixel + border) v spot = 2, analytical calculation (spot + border) v spot = 3, analytical calculation spot v spot = 4, mask method (spot + unused pixel + border) v spot = 5, mask method (spot + border) v spot = 6, mask method spot v spot Note: If radial masking is not used (SPOT_WIDTH = 0.0) then if IOVTYP > 0, the overlaps are calculated on the basis of SPOT_DELTA IERR i (W) Returned error flag = 0, OK =-1, Invalid pack (outside program limits) =-2, Invalid plate (outside program limits) = 1, Too many reflections to store = 2, Invalid overlap type flag = 3, Too many spots in a strip for overlaps calculation. ERRSTR c (W) Returned error message string (max 80 chars) 3.2.3 Generate Laue Reflection List (Low Level) - LRL_GNR This routine performs the actual generation of a Laue Reflection List using the current LDM parameters and Orientation and 'A' matrices. Normally distortion corrected coordinates are calculated for the spot positions but there is an option to omit the distortion correction. This is used as a service routine to LRL_GEN but may also be called directly if required. Fortran call: SUBROUTINE LRL_GNR (IPACK, IPLATE, A, DISTOR, IERR, ERRSTR) Parameters: IPACK i (R) Pack number (pre-check before calling this routine) IPLATE i (R) Plate number (pre-check before calling this routine) A(3,3) r (R) 'A' matrix DISTOR l (R) Flag = .true. apply distortion correction to stored coordinates (normal case), =.false. do not. IERR i (W) Error flag, =0 OK, =1 too many reflections for arrays (list truncated) ERRSTR c (W) Error message string (max 80 chars) 3.2.4 Calculate Orientation Matrix - LDM_MK_ORIENT This routine calculates the orientation matrix based on the current LDM parameters. This is normally used as a service routine to the subroutine LRL_GEN but may be called directly if required. Fortran call: SUBROUTINE LRL_MK_ORIENT (ORIENT) Parameters: ORIENT(3,3) r (W) Returns the orientation matrix 3.2.5 Calculate the Master 'A' Matrix - LRL_A_CALC This routine calculates the master matrix, a_mat, from the crystal system, crystal alignment and cell parameters. This is then premultiplied by the phi matrices. It is used as a service routine for the subroutine LRL_GEN but may be called directly if required. Fortran call: SUBROUTINE LRL_A_CALC (IPACK, ORIENT, A_MAT) Parameters: IPACK i (R) Pack number ORIENT(3,3) r (R) Orientation matrix from crystal setting & cell parameters A_MAT(3,3) r (W) The master matrix 3.2.6 Find and Mark Spatial Overlaps - LRL_OVLP This routine is used to determine an mark the spatial overlaps in a Laue Reflection List. A number of ways of specifying the overlap criterion are available. Fortran call: SUBROUTINE LRL_OVLP (IOVTYP, IERR, ERRSTR) Parameters: IOVTYP i (R) Flag for calculation of spatial overlaps = 1, analytical calculation (spot + unused pixel + border) v spot = 2, analytical calculation (spot + border) v spot = 3, analytical calculation spot v spot = 4, mask method (spot + unused pixel + border) v spot = 5, mask method (spot + border) v spot = 6, mask method spot v spot IERR i (W) Error flag = 0, OK = 1, Invalid overlaps type flag = 2, Too many spots in a strip for overlaps check ERRSTR c (W) Error message string (max 80 characters) 3.2.7 Find All Spatial Overlaps - LRL_OVALL This routine is used to find all the spots (up to a requested limit) which overlap with a given spatially overlapped spot. A number of ways of specifying the overlap criterion are available (as in LRL_OVLP). The Laue Reflection List (LRL) must be sorted on 'xfd' or 'yfd' before this routine is called. Fortran call: SUBROUTINE LRL_OVALL (IOVTYP, N, NSPOT, SPOT_L, SPOT_W, + SPOTFAC, SPOT_B, SPOT_D, RMAX, CTOF, + MM_RAST_X, MM_RAST_Y, MAX_OVLPS, + NUM_OV, X_OV, Y_OV, IERR, ERRSTR) Parameters: IOVTYP i (R) Flag for calculation of spatial overlaps = 1, analytical calculation (spot + unused pixel + border) v spot = 2, analytical calculation (spot + border) v spot = 3, analytical calculation spot v spot = 4, mask method (spot + unused pixel + border) v spot = 5, mask method (spot + border) v spot = 6, mask method spot v spot N i (R) Spot number in sorted LRL NSPOT i (R) Number of spots in the LRL SPOT_L r (R) Spot length (mm) SPOT_W r (R) Spot width (mm) SPOTFAC r (R) Spot expansion factor (See LDM parameter defns.) SPOT_B r (R) Spot border width (pixels) SPOT_D r (R) Spot delta (mm) RMAX r (R) Maximum radius (mm) CTOF r (R) Crystal to image diastance MM_RAST_X r (R) Conversion factor mm to x-rasters MM_RAST_Y r (R) Conversion factor mm to y-rasters MAX_OVLPS i (R) Maximum number of overlaps to return NUM_OV i (W) Number of overlapping spots found X_OV() r (W) 'x' coordinates of the NUM_OV overlapping spots (rasters) Y_OV() r (W) 'y' coordinates of the NUM_OV overlapping spots (rasters) IERR i (W) Error flag = 0, OK = 1, Spot list not sorted on 'xfd' or 'yfd' = 2, Spot was not found to be overlapped ERRSTR c (W) Error message string (max 80 characters) 3.3 SORT THE LAUE REFLECTION LIST 3.3.1 Introduction A routine is available to sort the Laue Reflection List in a number of ways. In actual fact an internal index list is generated through which the spots in the 'sorted' list are accessed though the actual generated spot data remains in situ. The following routines are available: Sort Reflections List - LRL_SORT 3.3.2 Sort Reflections List - LRL_SORT This routine sorts the Laue Reflection List in a number of ways. In actual fact an internal index list is generated through which the spots in the 'sorted' list are accessed; the actual generated spot data remains in situ. Spots may be sorted by index, detector position, lambda or resolution. Fortran call: SUBROUTINE LRL_SORT (ISOR) Parameters: ISOR i (R) Sort order flag = 1, sort on k, k, l = 2, sort on nodal h, k, l = 3, sort on XFD (stored x-coordinate) = 4, sort on YFD (stored y-coordinate) = 5, sort on lambda = 6, sort on dmin_thr2 3.4 CALCULATE AN INDIVIDUAL SPOT POSITION 3.4.1 Introduction A routine is available to calculate the predicted detector position for an individual Laue reflection. The following routines are available: Calculate Individual Reflection Position - LRL_CALC_POS 3.4.2 Calculate Individual Reflection Position - LRL_CALC_POS This routine calculates the predicted detector position for an individual reflection. Distortion corrections are applied. Fortran call: SUBROUTINE LRL_CALC_POS (IPACK, IPLATE, X_CEN, Y_CEN, + COSOM, SINOM, + AMAT, H, K, L, XFD, YFD, IERR) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number X_CEN r (R) Corrected x centre value (raster units) Y_CEN r (R) Corrected y centre value (raster units) COSOM r (R) cos (omega) SINOM r (R) sin (omega) AMAT(3,3) r (R) A matrix calculated using current LDM parameters H i (R) Reflection h index K i (R) Reflection k index L i (R) Reflection l index XFD r (W) Predicted x position (raster units) (distortion corrected) YFD r (W) Predicted y position (raster units) (distortion corrected) IERR i (W) = 0 OK =-1, Invalid pack (outside program limits) =-2, Invalid plate (outside program limits) = 1 could not be recorded with current detector position 3.5 GET GLOBAL LAUE REFLECTION LIST DATA ITEMS 3.5.1 Introduction A series of routines are available to access data from the Laue Reflection List which refer to the list as a whole. The following routines are available: Return the Number of Spots - LRL_NUMSPOTS Get Spot Counts - LRL_COUNTS Return Status of Laue Reflection List - LRL_STATUS Get Corrected Centre Position - LRL_GET_XYCEN Number of Reflection Tries - LRL_TRIES Get Pack and Plate Number - LRL_GET_PLATE Return the Nodal Index Limit - LRL_NODMAX 3.5.2 Return the Number of Spots - LRL_NUMSPOTS This routine returns the number of spots in a Laue Reflection List (LRL) Fortran call: SUBROUTINE LRL_NUMSPOTS (NUMSPOTS) Parameters: NUMSPOTS i (W) The number of spots in the Laue Reflection List 3.5.3 Get Spot Counts - LRL_COUNTS This routine returns counts of the number of spots/reflections in the Laue Reflection List in a number of different categories. Fortran call: SUBROUTINE LRL_COUNTS (NUMSPOTS, NUMREFL, NUMSING, NUMMULT, + NUMSPAT, NUMCLOS) Parameters: NUMSPOTS i (W) The number of spots in the Laue Reflection List NUMREFL i (W) The number of reflections in the Laue Reflection List NUMSING i (W) The number of single spots in the Laue Reflection List NUMMULT i (W) The number of multiple spots in the Laue Reflection List NUMSPAT i (W) The number of spots marked as spatially overlapped in in the Laue Reflection List NUMCLOS i (W) The number of spots marked as too close to spatially deconvolute at integration time in the Laue Reflection List 3.5.4 Return Status of Laue Reflection List - LRL_STATUS This routine returns status information from the Laue Reflection List including the number of spots, the current sort order, the spatial overlap criterion, whether or not the coordinates were distortion corrected and whether or not intensity integration has been carried out. Fortran call: SUBROUTINE LRL_STATUS (NUMSPOTS, ISORTED, IOVTYP, DISTOR, + INTEG, INTCOD) Parameters: NUMSPOTS i (W) The number of spots in the Laue Reflection List ISORTED i (W) Sort order 0 = none 1 = sorted on h, k, l 2 = sorted on nodal h, k, l 3 = sorted on 'xfd' 4 = sorted on 'yfd' 5 = sorted on lambda 6 = sorted on dminthr2 IOVTYP i (W) Overlaps calculation option used (0=none calculated) (Value as used in call to LRL_GEN) DISTOR l (W) Distortion correction flag = .true. distortion correction was applied to stored coordinates = .false. distortion correction was not applied Note: LRL_GET routine returns distortion corrected coordinates in either case; LRL_GET_XFYFD will return stored coordinates. INTEG l (W) Integration done flag =.true. yes, =.false. no INTCOD i (W) Integration code type flag = 0 if not known to the LRL routines. =1 Integration using Q. Hao's routine LFN_SAINT as used in INTLDM/LAUEGEN 3.5.5 Get Corrected Centre Position - LRL_GET_XYCEN This routine returns the corrected centre position used when the Laue Reflection List was generated. Note that it is only valid after such a list has been generated and does not provide a means of calculating the corrected centre position. Fortran call: SUBROUTINE LRL_GET_XYCEN (XCEN, YCEN) Parameters: XCEN r (W) Corrected 'x' centre position in rasters (wrt image origin) YCEN r (W) Corrected 'y' centre position in rasters (wrt image origin) 3.5.6 Number of Reflection Tries - LRL_TRIES this routine returns the number of reflection tried when generating the Laue Reflection List and the indices of the last reflection tried. Fortran call: SUBROUTINE LRL_TRIES (NUMTRIES, LAST_HKL) Parameters: NUMTRIES i (W) The number reflections tried during the reflection list generation. LAST_HKL(3) i (W) The indices of the last reflection tried 3.5.7 Get Pack and Plate Number - LRL_GET_PLATE This routine returns the pack and plate number used when the Laue Reflection List was generated. Note that it is only valid after such a list has been generated. Fortran call: SUBROUTINE LRL_GET_PLATE (IPACK, IPLATE) Parameters: IPACK i (W) Pack number IPLATE i (W) Plate number 3.5.8 Return the Nodal Index Limit - LRL_NODMAX This routine returns the maximum nodal index for which a spot may be considered to be a nodal spot. This value is used in flagging nodal spots in the LRL. Fortran call: SUBROUTINE LRL_NODMAX (NODMAX) Parameters: NODMAX i (W) The maximum nodal index for which a spot may be considered to be a nodal spot. This value is used in flagging nodal spots in the LRL. 3.6 GET INDIVIDUAL SPOT DATA FROM LAUE REFLECTION LIST 3.6.1 Introduction This section describes a set of routines to get information about individual spots from the Laue Reflection List. The following routines are available: Get Spot Details - LRL_GET Get Harmonics Data for a Spot - LRL_GET_HARM Return Coordinates for a Spot - LRL_GET_XFYFD Return Integrated Intensity of a Spot - LRL_GET_INT Get Nodal Index for a Spot - LRL_GET_NIDX Return Spatial Overlaps Flags for a Spot - LRL_GET_OVLP Return No. of Overload Pixels for a Spot - LRL_GET_OVPIX 3.6.2 Get Spot Details - LRL_GET This routine returns the basic details of a spot from the Laue Reflections List. Additional routines are available to get other information as described below. Fortran call: SUBROUTINE LRL_GET (ISPOT, IH, IK, IL, XD, YD, ALAM, DMTHR2, + MULT, OKNOD, SPOV, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) IH i (W) Reflection 'h' index (lowest harmonic present for a multiple) IK i (W) Reflection 'k' index (lowest harmonic present for a multiple) IL i (W) Reflection 'l' index (lowest harmonic present for a multiple) XD r (W) 'x' position on detector in raster units (corrected for distortion and centre) wrt image origin YD r (W) 'y' position on detector in raster units (corrected for distortion and centre) wrt image origin ALAM r (W) Reflection lambda value (lowest harmonic for a multiple) DMTHR2 r (W) Reflection dmin_thresold2 (lowest harmonic for a multiple) MULT i (W) Multiplicity OKNOD l (W) Flag = .true. non-spatially overlapped nodal spot = .false. not SPOV l (W) Flag = .true. spatially overlapped spot, = .false. not IERR i (W) Error flag = 0, OK = 1, Invalid spot number = -1, Plate centre was not set (coordinates will be returned wrt. predicted pattern centre) 3.6.3 Get Harmonics Data for a Spot - LRL_GET_HARM This routine returns the harmonics data for a spot in the Laue Reflections List. All the component reflections of a multiple may easily be generated from this information if required. Fortran call: SUBROUTINE LRL_GET_HARM (ISPOT, IH, IK, IL, H_N, K_N, L_N, + MULT, MINHARM, MAXHARM, INCHARM, + ALNOD, DTHR2NOD, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) IH i (W) Reflection 'h' index (lowest harmonic present for a multiple) IK i (W) Reflection 'k' index (lowest harmonic present for a multiple) IL i (W) Reflection 'l' index (lowest harmonic present for a multiple) H_N i (W) Nodal 'h' index K_N i (W) Nodal 'k' index L_N i (W) Nodal 'l' index MULT i (W) Multiplicity MINHARM i (W) Minimum harmonic number MAXHARM i (W) Maximum harmonic number INCHARM i (W) Harmonics increment (returns 1 for a single) IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.6.4 Return Coordinates for a Spot - LRL_GET_XFYFD This routine returns the predicted coordinates for a spot in the Laue Reflections List. The spot position may or may not be distortion corrected depending on the option selected when the Laue Reflection List was generated. Fortran call: SUBROUTINE LRL_GET_XFYFD (ISPOT, XFD, YFD, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) XFD r (W) Predicted 'x' coordinate of stored spot along 'xd' ('xf') wrt. predicted pattern centre YFD r (W) Predicted 'y' coordinate of stored spot along 'yd' ('yf') wrt. predicted pattern centre Note: These will be distortion corrected if this option was selected when the reflection list was generated (normal) case (LRL_GEN, LRL_GNR). The distortion correction status can be found by calling the routine LRL_STATUS IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.6.5 Return Integrated Intensity of a Spot - LRL_GET_INT This routine will return the integrated intensity of a spot in the Laue Reflection List if this has been measured and stored (LRL_SET_INT). Fortran call: SUBROUTINE LRL_GET_INT (ISPOT, AI, SIGI, MEASURED, BAD, + OVERLOAD, ICODE, ICODE_TYPE, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) AI r (W) The integrated intensity SIG I r (W) sig(I) MEASURED l (W) Spot has been integrated flag .TRUE. yes, .FALSE. no BAD l (W) Bad spot flagged .TRUE. bad, .FALSE. good OVERLOAD l (W) Overload flag .TRUE. yes, .FALSE. no ICODE i (W) Status code fom integration program For ICODE_TYPE=1 bit 0 no non-overlapped peak pixels bit 1 < 20% of peak pixels are non-overlapped. bit 2 <3 non-overlapped background pixels bit 4 < 20% of background pixels are non-overlapped. ICODE_TYPE i (W) Integration code type; should be 0 if of a type unknown to the 'LRL' routines = 1 Integration using Q. Hao's routines LFN_SAINT as used in INTLDM and LAUEGEN IERR i (W) Error flag = 0, OK = 1, Invalid spot number = 2, No integration done 3.6.6 Get Nodal Index for a Spot - LRL_GET_NIDX This routine returns the 'nodal index' for a spot from the Laue Reflections List (i.e. the maximum absolute nodal index for the three indices). Fortran call: SUBROUTINE LRL_GET_NIDX (ISPOT, NOD_IDX, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) NOD_IDX i (W) The nodal index IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.6.7 Return Spatial Overlaps Flags for a Spot - LRL_GET_OVLP This routine returns the spatial overlaps flags for a spot in the Laue Reflections List. Fortran call: SUBROUTINE LRL_GET_OVLP (ISPOT, SPOV, CLOS, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) SPOV l (W) Spatially overlapped flag .TRUE. = yes, .FALSE. = no CLOS l (W) Too close for spatial deconvolution flag = .TRUE. yes, =. FALSE. no IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.6.8 Return No. of Overload Pixels for a Spot - LRL_GET_OVPIX This routine returns the number of overloaded pixels in a spot if set by the integration routine for a spot in the Laue Reflections List. Fortran call: SUBROUTINE LRL_GET_OVPIX (ISPOT, NOVLD, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) NOVLD i (W) Returns the number of overloaded pixels in the spot if set by the integration routine (0-255). -1 indicates not set; 255 means 255 or more are overloaded. IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.7 SET GLOBAL LAUE REFLECTION LIST DATA ITEMS 3.7.1 Introduction The routines described in this section are for setting parameters which apply to the Laue Reflection List as a whole. The following routines are available: Clear Intensity Data - LRL_CLR_ALL Set the 'Integration Done' Flag - LRL_SET_IDONE 3.7.2 Clear Intensity Data - LRL_CLR_ALL This routine clears (re-initialises) the intensities data for all the spots in the Laue Reflections List. The 'integration done' flag is also cleared. Fortran call: SUBROUTINE LRL_CLR_ALL Parameters: none 3.7.3 Set the 'Integration Done' Flag - LRL_SET_IDONE This routine sets the 'integration done' flag for the Laue Reflections List and also stores the integration code type. Fortran call: SUBROUTINE LRL_SET_IDONE (ICODE_TYPE) Parameters: ICODE_TYPE i (R) Integration code type 0 if not known to LRL routines (Used for interpreting the meanings of the 'ICODE' flags assigned when an intensity is integrated) =1 Integration using Q. Hao's routine LFN_SAINT as used in INTLDM/LAUEGEN 3.8 SET INDIVIDUAL SPOT DATA IN LAUE REFLECTION LIST 3.8.1 Introduction The routines described in this section enable the setting of values associated with a particular spot in the Laue Reflection List. The following routines are available: Store Integrated Intensity - LRL_SET_INT Clear Intensity Data for a Spot - LRL_CLR_INT Set Spatially Overlapped Flag for a Spot - LRL_SET_SPOV Set 'Too Close' Flag for a Spot - LRL_SET_CLOS Set No. of Overload Pixels for a Spot - LRL_SET_OVPIX Set Non-spatially Overlapped Nodal Flag - LRL_SET_OKNOD 3.8.2 Store Integrated Intensity - LRL_SET_INT This routine is used to store an integrated intensity value for a spot in the Laue Reflections List. Fortran call: SUBROUTINE LRL_SET_INT (ISPOT, AI, SIGI, BAD, OVERLOAD, + ICODE, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) AI r (R) The integrated intensity SIG I r (R) sig(I) BAD l (R) Bad spot flag .TRUE. bad, .FALSE. good OVERLOAD l (R) Overload flag .TRUE. yes, .FALSE. no ICODE i (R) Status code from integration program (0 to 255) See for example LFN_SAINT or LRL_GET_INT IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.8.3 Clear Intensity Data for a Spot - LRL_CLR_INT This routine will clear (re-initialise) the integrated intensity data for a spot in the Laue Reflections List. Fortran call: SUBROUTINE LRL_CLR_INT (ISPOT) Parameters: ISPOT i (R) Spot index number (in current sort order) 3.8.4 Set Spatially Overlapped Flag for a Spot - LRL_SET_SPOV This routine sets the spatially overlapped flag for a spot in the Laue Reflection List. It is basically written for internal use but may be called by the user if desired. Fortran call: SUBROUTINE LRL_SET_SPOV (ISPOT) Parameters: ISPOT i (R) Spot index number (in current sort order) 3.8.5 Set 'Too Close' Flag for a Spot - LRL_SET_CLOS This routine sets the 'spots too close for spatial deconvolution' flag for a spot. It is basically written for internal use but may be called by the user if desired. Fortran call: SUBROUTINE LRL_SET_CLOS (ISPOT) Parameters: ISPOT i (R) Spot index number (in current sort order) 3.8.6 Set No. of Overload Pixels for a Spot - LRL_SET_OVPIX This routine sets the number of overloaded pixels in a spot for use within an integration routine for a spot in the Laue Reflections List. Fortran call: SUBROUTINE LRL_SET_OVPIX (ISPOT, NOVLD, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) NOVLD i (R) The number of overloaded pixels in the spot. If there are more than 255 pixels overloaded, a value of 255 will be stored. -1 clears the count in the list. IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.8.7 Set Non-spatially Overlapped Nodal Flag - LRL_SET_OKNOD This routine sets the 'non-spatially overlapped nodal spot' flag for a spot. It is basically written for internal use but may be called by the user if desired. Fortran call: SUBROUTINE LRL_SET_OKNOD (ISPOT) Parameters: ISPOT i (R) Spot index number (in current sort order) 3.9 INTERFACE FOR XDL_VIEW LAUE SIMULATIONS 3.9.1 Introduction Special routines are available for interfacing to the XDL_VIEW X-windows toolkit Laue simulations view-object. The following routines are available: Interface to X-windows Laue Simulation - LRL_XDLSIM Interface to X-windows Gnomonic Simulation - LRL_XDLGNM 3.9.2 Interface to X-windows Laue Simulation - LRL_XDLSIM This routine provides an interface the the XDL_VIEW Laue simulation view-object routine xdlf_laue_sim. Its use enables the internal arrays storing the reflection data to be accessed directly and hence saves the user having to duplicate such information. Fortran call: SUBROUTINE LRL_XDLSIM (IVH, IVHPARENT, IX, IY, ICSET, ITYPE, + ISIZE, IREPL, MINW, MINH, IERR) Parameters: IVH i (R) View object handle for laue simulations view-object IVHPARENT i (R) View-object handle for parent, 0 if none IX i (R) X position (may be -1 if no parent to give default) IY i (R) Y position (may be -1 if no parent to give default) ICSET i (R) Colorset number ITYPE i (R) Type of simulation = 1, colour = 2, interactive (b/w with sliders) ISIZE i (R) Halfwidth size in pixels IREPL i (R) =0 new simulation, =1 replace an existing one MINW i (R) Minimum width for view-object or 0 if no minimum MINH i (R) Minimum height for view-object or 0 if no minimum IERR i (W) Error flag = 0, OK = -1, no spots in list > 0, error code from xdl_laue_sim function 3.9.3 Interface to X-windows Gnomonic Simulation - LRL_XDLGNM This routine provides an interface the the XDL_VIEW Laue simulation view-object routine xdlf_laue_sim in its mode to display a gnomonic projection of the Laue patters. Its use enables the internal arrays storing the reflection data to be accessed directly and hence saves the user having to duplicate such information. Fortran call: SUBROUTINE LRL_XDLGNM (IVH, IVHPARENT, IX, IY, ICSET, ITYPE, + ISIZE, IREPL, GNOMR, MINW, MINH, IERR) Parameters: IVH i (R) View object handle for laue simulations view-object IVHPARENT i (R) View-object handle for parent, 0 if none IX i (R) X position (may be -1 if no parent to give default) IY i (R) Y position (may be -1 if no parent to give default) ICSET i (R) Colorset number ITYPE i (R) Type of simulation = 1, colour = 2, interactive (b/w with sliders) ISIZE i (R) Halfwidth size in pixels IREPL i (R) =0 new simulation, =1 replace an existing one GNOMR r (R) Minimum radius in mm (>0.1) from image centre for conversion of plot to a gnomonic projection. (If a value <= 0.1 is given a normal Laue simulation will be given) MINW i (R) Minimum width for view-object or 0 if no minimum MINH i (R) Minimum height for view-object or 0 if no minimum IERR i (W) Error flag = 0, OK = -1, no spots in list > 0, error code from xdl_laue_sim function 3.10 RE-ASSIGN SPATIAL OVERLAPS AND MULTIPLICITIES 3.10.1 Introduction A set of routines have been written to enable an alternative assignment of spatially overlapped and multiple spots using revised values of the Laue soft limits. This effectively enables some re-processing of the data without having to re-integrate spot intensities provided that conservative values have been used for the soft limits when the reflection list was generated. The re-assigned flags are held separately from the original flags and are accessed via the routines described in this section. The following routines are available: Reassigning spatial overlaps - LRL_REASSIGN Get Re-assigned Spot Flags - LRL_GET_REASS 3.10.2 Reassigning spatial overlaps - LRL_REASSIGN This routine enables the spatial overlap/multiplicity flags to be re-assigned for different values of the Laue soft limits (lambda-min, lambda-max, dmin) without regenerating the Laue Reflection List. The re-assigned flags are saved separately from the original flags and may be accessed via the LRL_GET_REASS routine. The LDM values for the soft limits are not reset. Fortran call: SUBROUTINE LRL_REASSIGN (IOVTYP, WMIN, WMAX, DMIN, + IERR, ERRSTR) Parameters: IOVTYP i (R) Flag for calculation of spatial overlaps = 1, analytical calculation (spot + unused pixel + border) v spot = 2, analytical calculation (spot + border) v spot = 3, analytical calculation spot v spot = 4, mask method (spot + unused pixel + border) v spot = 5, mask method (spot + border) v spot = 6, mask method spot v spot WMIN r (R) New value for lambda-min WMAX r (R) New value for lambda-max DMIN r (R) New value for 'dmin' Note: New lambda soft limits must be within range of those used in generating the reflection list and new 'dmin' must not be lower than that used generating the reflection list; otherwise the limits will be reset to meet these conditions and IERR will be returned with a value of -1 IERR i (W) Error flag = 0, OK =-1, New limits reset to be within range = 1, Invalid overlaps type flag = 2, Too many spots in a strip for overlaps check ERRSTR c (W) Error message string (max 80 characters) 3.10.3 Get Re-assigned Spot Flags - LRL_GET_REASS This routine enables the reassigned spot flags to be retrieved for a given spot in the Laue Reflections List after such re-assignment has been done via a call to the routine LRL_REASSIGN Fortran call: SUBROUTINE LRL_GET_REASS (ISPOT, MULT, MINHARM, MAXHARM, INCHARM, + SPOV, CLOS, OKNOD, IERR) Parameters: ISPOT i (R) Spot index number (in current sort order) MULT i (W) Multiplicity (Note: may be 0 after re-assigning limits i.e. spot may no longer be recorded MINHARM i (W) Minimum harmonic number MAXHARM i (W) Maximum harmonic number INCHARM i (W) Harmonics increment (returns 1 for a single) SPOV l (W) Spatially overlapped = .TRUE. yes, = .FALSE. no CLOS l (W) Too close to deconvolute = .TRUE. yes, = .FALSE. no OKNOD l (W) Non-spatially overlapped nodal = .TRUE. yes, = .FALSE. no IERR i (W) Error flag = 0, OK = 1, Invalid spot number 3.11 DETERMINE SPATIAL OVERLAP BETWEEN TWO SPOTS 3.11.1 Introduction These routines are to determine whether two spots are spatially overlapped. The elliptical LDM spot shapes are used and two different methods are available. The following routines are available: Determine Spot Ellipse Overlap (analytical) - LRL_OVQ Determine Spot Ellipse Overlap (using mask) - LRL_OVM 3.11.2 Determine Spot Ellipse Overlap (analytical) - LRL_OVQ This routine determines whether two elliptical spots, with or without a background border, overlap using an anlytical procedure. The routine makes the approximation that the two ellipses are the same size and have the same orientation (reasonable as close spots are being considered). Fortran call: LOGICAL FUNCTION LRL_OVQ (SPOT_L, SPOT_W, SPOTFAC, SPOT_B, CTOF, + RASTOMM, X1, Y1, X2, Y2, ITYP) Parameters: SPOT_L r (R) Spot length in mm. SPOT_W r (R) Spot width in mm. SPOTFAC r (R) Spot expansion factor SPOT_B r (R) Background border width in rasters CTOF r (R) Crystal to plate distance in mm. RASTOMM r (R) Conversion factor rasters to mm (x) X1 r (R) 'x' position of reference spot in mm. Y1 r (R) 'y' position of reference spot in mm. X2 r (R) 'x' position of second spot in mm. Y2 r (R) 'y' position of second spot in mm. ITYP i (R) Flag = 1, Check that (spot + unused pixel + background border) does not overlap with next spot = 2, Check that (spot + background border) does not overlap with next spot = 3, Check overlap strictly for spot area Return is .TRUE. if spots overlap, otherwise .FALSE. 3.11.3 Determine Spot Ellipse Overlap (using mask) - LRL_OVM This routine determines whether two elliptical spots, with or without a background border, overlap using a mask procedure based on code from the UPDATE program by T.J. Greenhough and A.K. Shrive. Fortran call: LOGICAL FUNCTION LRL_OVM (SPOT_L, SPOT_W, SPOTFAC, SPOT_B, CTOF, + MM_RAST_X, MM_RAST_Y, X1, Y1, X2, Y2, ITYP) Parameters: SPOT_L r (R) Spot length in mm. SPOT_W r (R) Spot width in mm. SPOTFAC r (R) Spot expansion factor SPOT_B r (R) Background border width in rasters CTOF r (R) Crystal to plate distance in mm. MM_RAST_X r (R) Conversion factor mm to x-rasters MM_RAST_Y r (R) Conversion factor mm to y-rasters X1 r (R) 'x' position of reference spot in mm. Y1 r (R) 'y' position of reference spot in mm. X2 r (R) 'x' position of second spot in mm. Y2 r (R) 'y' position of second spot in mm. ITYP i (R) Flag = 1, Check that (spot + unused pixel + background border) does not overlap with next spot = 2, Check that (spot + background border) does not overlap with next spot = 3, Check overlap strictly for spot area Returns .TRUE. if spots overlap, otherwise .FALSE. 3.12 MISCELLANEOUS ROUTINES 3.12.1 Introduction This section describes some routines which are basically for internal use but may also be called by the user if desired. The following routines are available: Highest Common Factor of Two Numbers - LRL_HCF Convert Between Real and Reciprocal Cells - LRL_RECCEL Get Nodal Index from Indices - LRL_NODIDX 3.12.2 Highest Common Factor of Two Numbers - LRL_HCF This routine, based on code by I.J. Clifton, returns the highest common factor of two integers. Fortran call: INTEGER FUNCTION LRL_HCF (II,JJ) Parameters: II i (R) First integer JJ i (R) Second integer Returns the highest common factor of the two integers 3.12.3 Convert Between Real and Reciprocal Cells - LRL_RECCEL This routine converts between real and reciprocal cell parameters. Fortran call: SUBROUTINE LRL_RECCEL(RX ,CX ,WAVE) Parameters: RX(6) r (W) Converted cell parameters reciprocal or real CX(6) r (R) Input cell parameters real or reciprocal WAVE r (R) Standard wavelength 3.12.4 Get Nodal Index from Indices - LRL_NODIDX This routine determines the nodal index from a set of reflection indices. Fortran call: SUBROUTINE LRL_NODIDX (IH, IK, IL, NODIDX) Parameters: IH i (R) 'h' index IK i (R) 'k' index IL i (R) 'l' index NODIDX i (W) Returns nodal index CHAPTER 4: LDM RELATED FUNCTIONS (LFN) ====================================== 4.1 INTRODUCTION These are sets of routines which provide some machine independent functions for inclusion in programs for processing Laue diffraction data. They are used in association with the Laue Data Module (LDM) routines. The following sets of routines are available: Crystal Orientation Refinement In Memory Image Routines Integration and Soft Limit Routines Laue Unique Data Analysis Determine Spot Positions and Sizes Dummy Cancel Routine Create .ge1/.ge2 files Read Data into LIRL 4.2 CRYSTAL ORIENTATION REFINEMENT 4.2.1 Introduction These routines are for refining the crystal orientation parameters and cell/distortion parameters as required. The following routines are available: Refine Orientation Parameters - LFN_RFN List Refined Parameter Values - LFN_SHOWREF List Refined Values for XDL_VIEW - LFN_SHOW_XDL Automatic Orientation Refinement - LFN_AUTO_REFN Log Automatic Refinement Results - LFN_REFN_LOG Log Automatic Refinement Errors - LFN_REFN_ERR Get Nodals Histogram Data - LFN_NODHIST Get Refinement Nodals List - LFN_GET_SPOTS Clear Observations List - LFN_CLROBS Add Spot to Refinement Observations List - LFN_ADDOBS Get Spot from Refinement Observations List - LFN_GETOBS Get Number of Refinement Observations - LFN_NUMOBS Get Spot Position - LFN_SPOT_CG Get Radially Masked Spot Position - LFN_SPOT_RD 4.2.2 Refine Orientation Parameters - LFN_RFN This routine is used to refine the setting, cell and distortion parameters as desired. A refinement list must be set up using a call to LFN_CLROBS and calls to LFN_ADDOBS before the routine LFN_RFN is called. Fortran call: SUBROUTINE LFN_RFN (IPACK, IPLATE, IFLAG, JFLAG, KFLAG, + X_CEN_F, Y_CEN_F, + IRFTYP, TUNE, RMS, IERR, MESSAGE) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number IFLAG() i (R) Parameter refinement flags 1=refine, 0=do not refine IFLAG(1) PHIX IFLAG(2) PHIY IFLAG(3) PHIZ IFLAG(4) CTOF IFLAG(5) X_C IFLAG(6) Y_C IFLAG(7) W_C JFLAG() i (R) Cell parameter refinement flags for compressed cell (i.e. minimum cell parameters required for the crystal system (e.g. triclinic 6, orthorhombic 3, cubic 1) 1=refine, 0=do not refine KFLAG() i (R) Distortion parameter refinement flags For distortion type 1: KFLAG(1) Y_SCALE KFLAG(2) TWIST KFLAG(3) TILT KFLAG(4) BULGE For distortion type 2: KFLAG(1) Y_SCALE KFLAG(2) TWIST KFLAG(3) TILT KFLAG(4) ROFF KFLAG(5) TOFF For distortion type 3: KFLAG(1) Y_SCALE KFLAG(2) TWIST KFLAG(3) TILT KFLAG(4) SPDXY KFLAG(5) SPDX KFLAG(6) SPDY X_CEN_F r (R) Un-corrected x-centre position in rasters Y_CEN_F r (R) Un-corrected y-centre position in rasters IRFTYP i (R) Refinement type =1 LSR, =2 Powell TUNE(3) r (R) Refinement tuning parameters If IRFTYP = 1 TUNE(1) = shift limit e.g.0.001 TUNE(2) = step parameter e.g. 1.0E-10 TUNE(3) = damping factor e.g. 0.5 If IRFTYP = 2 TUNE(1) = accuracy e.g. 0.000001 RMS r (W) rms deviation (mm) after refinement IERR i (W) Error flag =0, OK =-1, Spatial distortion arrays cannot handle all coefficients =1, Refinement not completed =2, Other refinement error =3, Spots found outside Chebyshev limits MESSAGE c (W) Message string from refinement (up to 80 characters) 4.2.3 List Refined Parameter Values - LFN_SHOWREF This routine is used to list the refined parameter values to a terminal or to an output file. Fortran call: SUBROUTINE LFN_SHOWREF (IUN, ITERM, IPACK, IPLATE, RMS, OLD_RMS) Parameters: IUN i (R) Unit no. for listing ITERM i (R) =1, o/p to terminal, =0 o/p to file IPACK i (R) Pack number IPLATE i (R) Plate number RMS r (R) rms error after the refinement OLD_RMS r (R) rms error before the refinement (will not be o/p if 0.0 given) 4.2.4 List Refined Values for XDL_VIEW - LFN_SHOW_XDL This routine is used to list the refined parameter values to an XDL_VIEW I/O window. Fortran call: SUBROUTINE LFN_SHOW_XDL (IVH, IPACK, IPLATE, RMS, OLD_RMS) Parameters: IVH i (R) View-object handle for the xdl_view i/o window IPACK i (R) Pack number IPLATE i (R) Plate number ITERM i (R) =1, o/p to terminal, =0 o/p to file RMS r (R) rms error after the refinement OLD_RMS r (R) rms error before the refinement (will not be o/p if 0.0 given) 4.2.5 Automatic Orientation Refinement - LFN_AUTO_REFN This routine is used to carry out an automatic orientation refinement for a single plate, a pack or all packs and plates. The refinement procedure is split into three phases after an initial spot search. Spots with a fixed nodal index (program set default e.g. 4 or a user specified nodal index or minimum number of spots) are used throughout the procedure until the final refinement phase is reached. The first phase will attempt to get the refinement started even if the initial rms is poor (> 0.25 mm or less than half the spots found). This phase will continue to try and get a reasonable rms (up to a maximum of 8 cycles) provided that, either the number of spots found is increasing or the rms is falling and the number of spots does not decrease by more than one quarter in a cycle. The main refinement phase is entered when the rms is <= 0.25 mm provided that at least half the spots have been found. It carries out a standard refinement protocol of 4 cycles (7 if the polynomial based spatial distortion correction is being used). The final refinement phase uses a nodal index with a program set default e.g. 6 (or a user specified nodal index or minimum number of spots) and carries out a final two cycles of refinement (4 if the polynomial based spatial distortion correction is being used). If a plate has already been refined the final refinement phase will be entered immediately provided that the rms is <= .075 mm. When a pack is being refined, the key plate will be refined first. The user specifies whether or not cell parameters are to be refined (applies to key plate of key pack only); the default is defined by the program e.g. refine cell. Spot positions are found using the LFN_GET_SPOTS routine. Fortran call: SUBROUTINE LFN_AUTO_REFN (IPACK, IPLATE, OPTSTR, + IPKPL_DF, ICLL_DF, NODS_DF, NODF_DF, + IMG_PK, IMG_PL, RD_IMG, + IMG, MAXIMG, ITYPE, NF_OFF, + IUN_LOG, LOG_RESULTS, LOG_ERR, + MAXHALF, IDATA, IWORK, + CANCEL, RMS, UPD, IERR, ERRSTR, + ERRSTR2) Parameters: IPACK i (M) Current pack number (On o/p last pack accessed) IPLATE i (M) Current plate number (On o/p last pack accessed) OPTSTR c (R) Options string (max. 80 characters long) 'plate' or 'pack' or 'all' 'cell' or 'nocell' nnods nnodf (nodal indices for start/main and final refinement phases if <=20 or minimum no. of predicted nodals to use for refinement if >20. The default values are nodal indices defined via parameters NODS_DF and NODF_DF below. If a single value is given, it is assumed to refer to nnodf for the final refinements. For the nodal index options, values are adjusted, if necessary, to be in the range 4-12. IPKPL_DF i (R) Default value for plate/pack/all (1,2,3) ICLL_DF i (R) Default refine cell flag 1=yes, 2=no NODS_DF i (R) Default nodal index for initial refinements (4-12) e.g. 4 NODF_DF i (R) Default nodal index for final refinements (4-12) e.g. 6 IMG_PK i (M) Pack number for current image in IMG; 0 if none. On output will be for the last image read or 0 if there was an error reading the image. IMG_PL i (M) Plate number for current image in IMG; 0 if none. On output will be for the last image read or 0 if there was an error reading the image. RD_IMG s (R) Subroutine to open the image file and read an image. The call is as follows: CALL RD_IMG (IPK, IPL, ITYPE, NF_OFF, IMG, + MAXIMG, KERR, KERRSTR) where IPK i (R) Pack number IPL i (R) Plate number ITYPE i (M) See below NF_OFF i (M) See below IMG(*) i (W) See below MAXIMG i (R) See below KERR i (W) Error return flag: Routine must set this to 0 if image read was successful or to a non-zero value if there was an error. KERRSTR c (W) Error message string set by the routine if an error was encountered when reading the image. Note: In some instances it may be appropriate for the routine to set x_cen_f, y_cen_f values e.g derived from fiducial positions if it finds that these parameters have not already been set as the refinement procedure needs these in order to continue IMG(*) i (R) Array containing the (possibly packed) image data for the current plate. MAXIMG i (R) Maximum no. of words in IMG array ITYPE i (M) Image data type in IMG =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 squashed i2 data Note: May be reset by RD_IMG subroutine but must be given an input value if a previously read image is passed to the routine. NF_OFF i (M) Fast offset between (slow) rasters of image (e.g. 1'st dimension of the the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type as indicated by ITYPE. Note: May be reset by RD_IMG subroutine but must be given an input value if a previously read image is passed to the routine. IUN_LOG i (R) Unit number for output passed to LOG_RESULTS and LOG_ERR routines as one of their parameters when called. LOG_RESULTS s (R) User defined subroutine to output results of the refinement. For output to a log file only, this may be the routine LFN_REFN_LOG. Note that the routine must be declared as EXTERNAL in the calling program. The call is as follows: CALL LOG_RESULTS (IUN_LOG, ISTAGE, IPACK, IPLATE, + IGEN, NSEARCH, NOBS, + OLD_RMS, RMS, RFMSG, + IFLAG, JFLAG, KFLAG) where IUN_LOG i (R) Unit number for log file as passed to LFN_AUTO_REFN ISTAGE i (R) Refinement stage to be logged (ipack, iplate are always passed unless ISTAGE is 0 or 20; other parameters which need to be set for a particular stage are shown in brackets): = 0 Main heading for auto refinement = 1 Current pack/plate = 2 'INITIAL SEARCH' phase started = 3 Start image read = 4 End image read = 5 Start spots list generation = 6 End spots list generation = 7 Spot generation results (IGEN) = 8 Start spots search = 9 End spots search = 10 Initial spot search results for the current plate (NSEARCH, NOBS, RMS) = 11 Other spot search results (NSEARCH, NOBS, RMS) = 12 'INITIAL REFINEMENT' phase started = 13 List of parameters to be refined (IFLAG, JFLAG, KFLAG) = 14 Start refinement cycle = 15 End refinement cycle = 16 Refinement results except for last cycle. (NOBS, OLD_RMS, RMS, RFMSG, IFLAG, JFLAG, KFLAG) = 17 Refinement results for last cycle. (NOBS, OLD_RMS, RMS, RFMSG, IFLAG, JFLAG, KFLAG) = 18 'MAIN REFINEMENT' phase = 19 'FINAL REFINEMENT' phase = 20 Refinement completed IPACK i (R) Current pack number IPLATE i (R) Current plate number IGEN(6) i (R) Counts from reflection generation (the 6 parameters returned from LRL_COUNTS) NSEARCH i (R) No. of spots searched for. NOBS i (R) No. spots found and used in refinement OLD_RMS i (R) Rms from spot search prior to refinement RMS i (R) Rms from spot search or refinement RFMSG c (R) Message string from refinement routine IFLAG(7) i (R) See LFN_RFN routine JFLAG(6) i (R) See LFN_RFN routine KFLAG(6) i (R) See LFN_RFN routine LOG_ERR s (R) User defined subroutine called when an error condition is encountered. For certain conditions the routine may allow the refinement to continue for the next plate etc. For output only the subroutine LFN_REFN_ERR may be used. This outputs the error message to IUN_LOG and terminates the refinement after any error is found. Note that the routine must be declared as EXTERNAL in the calling program. The call is as follows: CALL LOG_ERR (IUN_LOG, ICONT, ERRSTR, + ERRSTR2, NEXT) where IUN_LOG i (R) Unit number for log file. ICONT i (R) = 0 terminate refinement = 1 may continue with next plate if desired. = 2 may continue with next pack if required =-1 Interrupted ERRSTR c (R) Error string (max 80 chars) ERRSTR2 c (R) Subsidiary error string - may be blank (max 80 chars) NEXT l (W) Set by the routine. If .true. then refinement will be continued with next pack or plate. If .false. then refinement will be terminated. Note: the routine must set it to .false. if ICONT is 0 or -1. MAXHALF i (R) Maximum half size in rasters allowed for background determining box which will be three times the spot search box (each dimension) in size. IDATA i (*) Work array to hold the spot data returned from the image. Must be dimensioned to at least (2*MAXHALF+1)*(2*MAXHALF+1) IWORK i (*) Work array dimensioned to at least (2*MAXHALF+1) CANCEL f (R) Logical function used to interrupt procedure It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) RMS f (W) Returns the final RMS value in mm. UPD(9) l (R) Automatic update flags .true. yes, .false. no. The automatic updates, if done, will be as follows: For a pack based parameter, update parameter for subsequent packs if pack just refined is the first pack. For a plate based parameter, update the parameter for other plates if the plate just refined is the key plate for the pack. If, in addition, the pack is the first pack, then update the parameter for all packa and plates. UPD(1) Phis UPD(2) ctof UPD(3) x_c, y_c UPD(4) w_c UPD(5) y_scale UPD(6) twist, tilt UPD(7) bulge UPD(8) roff/toff UPD(9) spd parameters IERR i (W) Error flag for last error found = 0 OK (no errors) = -1 Invalid current pack number. = -2 Invalid current plate number. = -3 Invalid/ambiguous option requested options string = 1 Required Key plate not yet refined = 2 Error reading image = 3 Centre not defined for plate = 4 Error generating reflection list = 5 Error in spots search = 6 Cannot home in on solution = 7 Less than 5 spots found = 8 Least squares refinement error =100 REfinement interrupted ERRSTR c (W) Error message string (max 80 chars) if IERR is non-zero ERRSTR2 c (W) Additional error information (max 80 chars) if IERR is non-zero (blank for some error conditions) 4.2.6 Log Automatic Refinement Results - LFN_REFN_LOG This routine is used to log the results from the automatic refinement procedure of the routine LFN_AUTO_REFN. If used, it is passed as the user supplied LOG_RESULTS subroutine which is one of the LFN_AUTO_REFN parameters and must be defined as external. Its sections of output may also be used by calling it from a user supplied routine. (Note that this version does not do output for all the possible stages) Fortran call: SUBROUTINE LFN_REFN_LOG (IUN_LOG, ISTAGE, IPACK, IPLATE, IGEN, + NSEARCH, NOBS, OLD_RMS, RMS, RFMSG, + IFLAG, JFLAG, KFLAG) Parameters: IUN_LOG i (R) Unit number for log file as passed to LFN_AUTO_REFN ISTAGE i (R) Refinement stage to be logged (ipack, iplate are always passed unless ISTAGE is 0 or 20; other parameters which need to be set for a particular stage are shown in brackets): = 0 Main heading for auto refinement = 1 Current pack/plate = 2 'INITIAL SEARCH' phase started = 3 Start image read = 4 End image read = 5 Start spots list generation = 6 End spots list generation = 7 Spot generation results (IGEN) = 8 Start spots search = 9 End spots search = 10 Initial spot search results for the current plate (NSEARCH, NOBS, RMS) = 11 Other spot search results (NSEARCH, NOBS, RMS) = 12 'INITIAL REFINEMENT' phase started = 13 List of parameters to be refined (IFLAG, JFLAG, KFLAG) = 14 Start refinement cycle = 15 End refinement cycle = 16 Refinement results except for last cycle. (NOBS, OLD_RMS, RMS, RFMSG, IFLAG, JFLAG, KFLAG) = 17 Refinement results for last cycle. (NOBS, OLD_RMS, RMS, RFMSG, IFLAG, JFLAG, KFLAG) = 18 'MAIN REFINEMENT' phase = 19 'FINAL REFINEMENT' phase = 20 Refinement completed IPACK i (R) Current pack number IPLATE i (R) Current plate number IGEN(6) i (R) Counts from reflection generation (the 6 parameters returned from LRL_COUNTS) NSEARCH i (R) No. of spots searched for. NOBS i (R) No. spots found and used in refinement OLD_RMS i (R) Rms from spot search prior to refinement RMS i (R) Rms from spot search or refinement RFMSG c (R) Message string from refinement routine IFLAG(7) i (R) See LFN_RFN routine JFLAG(6) i (R) See LFN_RFN routine KFLAG(6) i (R) SEe LFN_RFN routine 4.2.7 Log Automatic Refinement Errors - LFN_REFN_ERR This routine is used to log errors from the automatic refinement procedure of the routine LFN_AUTO_REFN. If used, it is passed as the user supplied LOG_ERR subroutine which is one of the LFN_AUTO_REFN parameters an must be declared as external. This version of the error handling routine treats all errors as ones which will terminate the automatic refinement procedure. Fortran call: SUBROUTINE LFN_REFN_ERR (IUN_LOG, ICONT, ERRSTR, ERRSTR2, + NEXT) Parameters: IUN_LOG i (R) Unit number for log file ICONT i (R) = 0 treat as error which terminates refinent = 1 may continue with next plate if desired = 2 may continue with next pack if required =-1 interrupted ERRSTR c (R) Error string (max 80 chars) ERRSTR2 c (R) Subsidiary error string - may be blank (max 80 chars) NEXT l (W) Set by the routine. If .true. then refinement will be continued with next pack or plate. If .false. then refinement will be terminated. Note: the routine must set it to .false. ICONT is 0 or -1. 4.2.8 Get Nodals Histogram Data - LFN_NODHIST This routine is used to return a histogram of the number of non-spatially overlapped nodal spots (cumulative) as a function of nodal index using the data in the current Laue Reflection List (LRL). Fortran call: SUBROUTINE LFN_NODHIST (NNODS, MAXDIM, NODMAX) Parameters: NNODS(*) i (W) Cumulative numbers of non-spatially overlapping nodal spots as a function of nodal index. Zero values will be returned if no spot list has been generated. MAXDIM i (R) Maximum dimension of NNODS array; if this is less than NODMAX then only the first MAXDIM values will be returned in NNODS. NODMAX i (W) Returns the maximum nodal index as defined for the Laue Reflection List (LRL) 4.2.9 Get Refinement Nodals List - LFN_GET_SPOTS This routine is used to get a list of refinement nodal spots from the currently generated Laue Reflection List and determine their positions from the image. The spots found will be stored in the refinement observations list which will be automatically cleared on entry to the subroutine. The routine accesses a number of LDM parameters internally including image and spot related parameters and the spot search threshold. The background is normally calculated by taking a box three times the spot search box size and averaging the lowest 50% of the pixels. Fortran call: SUBROUTINE LFN_GET_SPOTS (NH, NK, NL, SPOTBOX, SORT, + CANCEL, IMG, ITYPE, NF_OFF, + MAXHALF, IDATA, IWORK, + NSEARCH, NOBS, RMS, IERR, ERRSTR) Parameters: NH i (R) 'h' nodal selection index (maximum absolute nodal index for including spots in list). NK i (R) 'k' nodal selection index (maximum absolute nodal index for including spots in list). NL i (R) 'l' nodal selection index (maximum absolute nodal index for including spots in list). SPOTBOX r (R) Spot box size for spot position determination (if 0.0 then use default box size if the spot_width = 0.0 or radial masking option if the spot_width is > 0.0). If negative then then a box of size ABS(SPOTBOX) is used for both the spot box and background box e.g. for trying a large box when starting refinement from a rather poor match. SORT l (R) Sort LRL so that spots in the observations list will be in an efficient order for accessing the in-memory image. CANCEL f (R) Logical function used to interrupt procedure It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) IMG(*) i (R) Array containing the (possibly packed) image data for the current plate. ITYPE i (R) Image data type in IMG =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 squashed i2 data NF_OFF i (R) Fast offset between (slow) rasters of image (e.g. 1'st dimension of the the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type as indicated by ITYPE. MAXHALF i (R) Maximum half size in rasters allowed for background determining box which will be three times the spot search box (each dimension) in size (unless a negative value was given for SPOTBOX (see above). IDATA i (*) Work array to hold the spot data returned from the image. Must be dimensioned to at least (2*MAXHALF+1)*(2*MAXHALF+1) IWORK i (*) Work array dimensioned to at least (2*MAXHALF+1). NSEARCH i (W) No. of spot positions searched for. NOBS i (W) Returns the number of spot position observations found and returned in in the refinement observations list. RMS r (W) Rms deviation in mm between predicted and observed spot positions. IERR i (W) Error flag = 0 OK, spots found (but check IWARN also) = 1 No spots list generated or no spots in list = 2 Laue Reflection List needs to be re-generated as LDM parameters have been changed since it was created =-1 No. of 2'nd axis image rasters greater than 2*MAXHALF+1 =-2 Required half box size greater than MAXHALF =-3 Invalid image type requested =-4 Byte handling not available =-100 Cancelled via CANCEL routine ERRSTR c (W) Error message string (max 80 chars) if IERR is non-zero 4.2.10 Clear Observations List - LFN_CLROBS This routine is used to clear the refinement observations list. I must be called before spot positions are added to it using the routine LFN_ADDOBS. Fortran call: SUBROUTINE LFN_CLROBS Parameters: None 4.2.11 Add Spot to Refinement Observations List - LFN_ADDOBS This routine is used to add the observed spot position for a given reflection to the refinement observations list. Fortran call: SUBROUTINE LFN_ADDOBS (IH, IK, IL, XM, YM, IERR) Parameters: IH i (R) 'h' index IK i (R) 'k' index IL i (R) 'l' index XM r (R) Observed 'x' position (rasters) YM r (R) Observed 'y' position (rasters) IERR i (W) Error flag =0 OK, =1 list full 4.2.12 Get Spot from Refinement Observations List - LFN_GETOBS This routine is used to get the spot details (indices and position) from the current refinement observations list as created using LFN_CLROBS and LFN_ADDOBS. The number of observations in the list may be found using the routine LFN_NUMOBS. Fortran call: SUBROUTINE LFN_GETOBS (I, IH, IK, IL, XM, YM, IERR) Parameters: I i (R) Position of spot in the list IH i (W) 'h' index IK i (W) 'k' index IL i (W) 'l' index XM r (W) Observed 'x' position (rasters) YM r (W) Observed 'y' position (rasters) IERR i (W) Error flag =0 OK, =1 requested number not in current list 4.2.13 Get Number of Refinement Observations - LFN_NUMOBS This routine returns the number of refinement observations in the current refinement observations list as created using the LFL_CLROBS and LFN_ADDOBS routines. Fortran call: SUBROUTINE LFN_NUMOBS (NUMOBS) Parameters: NUMOBS i (W) Returns the number of observations in the list 4.2.14 Get Spot Position - LFN_SPOT_CG This routine finds a spot position by determining the centre of gravity of intensities lying within a defined box allowing for a constant intensity threshold. It is based on a routine from the Daresbury Laboratory Laue suite program GENLAUE as of September 1990) Fortran call: SUBROUTINE LFN_SPOT_CG (IXC, IYC, IXSIZ, IYSIZ, IDATA, IWORK, + ITHRESH, IMG, ITYPE, IORDER, NFOFF, + NXRAST, NYRAST, NOVER, CGX, CGY, IERR) Parameters: IXC i (R) X pixel position for box centre (numbered from 1 up) IYC i (R) Y pixel position for box centre IXSIZ i (R) X box parameter (Box size will be (2*IXSIZ+1)*(2*IYSIZ+1) IYSIZ i (R) Y box parameter (See previous parameter) IDATA i (W) Array to hold read in data. Must be dimensioned to at least (2*IXSIZ+1) * (2*IYSIZ+1) elements IWORK i (R) Work array (dimensioned to at least larger of (2*IXSIZ+1) * (2*IYSIZ+1) elements ITHRESH i (R) Intensity threshold IMG i (R) In memory image data ITYPE i (R) Data type in stored image 1=unsigned byte, 2=unsigned two-byte IORDER i (R) Image data order flag (1-8) NFOFF i (R) Offset in pixels between lines in stored image NXRAST i (R) The number of x rasters in the image NYRAST i (R) The number of y-rasters in the image NOVER i (W) Returns the number of pixels over the threshold value CGX r (W) Returns the x coordinate (in raster units) of the c of g CGY r (W) Returns the y coordinate (in raster units) of the c of g IERR i (W) Error flag =0 OK, =-1 flag error, =-2 byte handling not available =1 box partly out of range =2 box completely out of range of image. 4.2.15 Get Radially Masked Spot Position - LFN_SPOT_RD This routine finds a spot position by determining the centre of gravity of intensities lying within a radially masked ellipse allowing for a constant intensity threshold. It is based on code from the program GENLAUE including the radial masking code of T.J. Greenhough and A.K. Shrive (University of Keele) Fortran call: SUBROUTINE LFN_SPOT_RD (IPACK, IPLATE, IXC, IYC, + IXSIZ, IYSIZ, IDATA, + IWORK, ITHRESH, IMG, ITYPE, IORD, NFOFF, + NXRAST, NYRAST, + X_CEN, Y_CEN, NOVER, + CGX, CGY, IERR) Parameters: IXC i (R) X pixel position for box centre (numbered from 1 up) IYC i (R) Y pixel position for box centre IXSIZ i (R) X box parameter (Box size will be (2*IXSIZ+1)*(2*IYSIZ+1) IYSIZ i (R) Y box parameter (See previous parameter) IDATA i (W) Array to hold read in data. Must be dimensioned to at least (2*IXSIZ+1) * (2*IYSIZ+1) elements IWORK i (R) Work array (dimensioned to at least larger of (2*IXSIZ+1) * (2*IYSIZ+1) elements ITHRESH i (R) Intensity threshold IMG i (R) In memory image data ITYPE i (R) Data type in stored image 1=unsigned byte, 2=unsigned two-byte IORD i (R) Image data order flag (1-8) NFOFF i (R) Offset in pixels between lines in stored image NXRAST i (R) No. of x-rasters NYRAST i (R) No. y-rasters X_CEN r (R) Corrected 'x' centre position (rasters) Y_CEN r (R) Corrected 'y' centre position (rasters) NOVER i (W) Returns the number of pixels over the threshold value CGX r (W) Returns the x coordinate (in raster units) of the c of g CGY r (W) Returns the y coordinate (in raster units) of the c of g IERR i (W) Error flag =0 OK, =-1 flag error, =-2 byte handling not available =1 box partly out of range =2 box completely out of range of image. 4.3 IN MEMORY IMAGE ROUTINES 4.3.1 Introduction The routine described in this section is for extracting a section of an image which has been stored in memory. Its use is associated with the development of the Laue Data Module (LDM) routines though it may be used independently of these. The following routines are available: Read Section from Image in Memory - LFN_IMG_RECT 4.3.2 Read Section from Image in Memory - LFN_IMG_RECT This routine is used to read in a rectangular section of an 'in memory' image into an integer array. The data in the image itself may be stored in byte format, unsigned two-byte format, signed integer format or a 'squashed' two byte integer format. In the 'squashed i2' format an intensity>32767 is as 65536-intensity/8. Fortran call: SUBROUTINE LFN_IMG_RECT (IMG, ITYPE, IORDER, NF_OFF, + IAX1_ORIG, IAX2_ORIG, NAX1, NAX2, + NAX1_RASTS, NAX2_RASTS, IOUTLIM, + IDATA, IWORK, IERR) Parameters: IMG (*) i (R) Image data array (may hold signed integer data or unsigned byte data packed into an integer array or unsigned two byte data packed into an integer array or 'squashed' two byte data packed into an integer array. ITYPE i (R) Image data type =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 'squashed i2' (if intensity>32767 then stored as 65536-intensity/8) IORDER i (R) Order of data in image wrt. the two local axes =1 +ax1 +ax2 =2 +ax1 -ax2 =3 -ax1 +ax2 =4 -ax1 -ax2 =5 +ax2 +ax1 =6 +ax2 -ax1 =7 -ax2 +ax1 =8 -ax2 -ax1 NF_OFF i (R) Fast offset between (slow) rasters of image (e.g. first dimension of the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type (bytes, 2-bytes, integers or 'squashed i2' as set by ITYPE) IAX1_ORIG i (R) The origin pixel of the required section along the first local axis IAX2_ORIG i (R) The origin pixel of the required section along the second local axis NAX1 i (R) Size of the section in pixels along the first local axis NAX2 i (R) Size of the section in pixels along the second local axis NAX1_RASTS i (R) No. of rasters in the image along the first local axis NAX2_RASTS i (R) No. of rasters in the image along the second local axis IOUTLIM i (R) Value to which returned data pixels are to be set if they lie outside the image IDATA i (W) Array returning the image section data first local axis is the slow axis (2'nd dimension) and second local axis is the fast axis (1'st) dimension. IWORK i (*) Work array dimensioned to at least NAX2 if IORDER = 1-4 or NAX1 if IORDER = 5-8; may be a dummy if ITYPE=3 IERR i (W) Error flag = 0 OK, =-1 Invalid type or order flag =-2 Byte handling not available = 1 Box partly outside image = 2 Box totally outside image Note: pixels within the image are numbered from 1 upwards Note: byte handling (via CCP4 library routines) must be available for data types 1 and 2 4.4 INTEGRATION AND SOFT LIMIT ROUTINES 4.4.1 Introduction A set of routines is available to measure integrated intensities for a Laue image. They were written by Hao Quan to determine integrated intensities of reflections for use in improving the Laue soft limits 'lambda-min' and 'dmin' and routines are included for determining these improved values. They make use of the Laue Data Module (LDM) routines and work with an image read into memory. The following routines are available: Standalone Integration Routine - LFN_SAINT Integration Parameter Defaults - LFN_SAINT_DF Get Profile Parameters - LFN_GET_PROFPARS Get Profile Maximum - LFN_GET_PROFMAX Get Spot Profile - LFN_GET_PROFILE Get Profile Pixel Details - LFN_GET_PROFPIX Get Integrated Spot Parameters - LFN_GET_SPOTPARS Get Integrated Spot Code - LFN_GET_SPOTCODE Get Integrated Spot Data - LFN_GET_INTSPOT Get Spot Pixel Details - LFN_GET_SPOTPIX Write Spot Profiles - LFN_LIST_PROFS List Integrated Spot Details - LFN_LIST_INTSPOT Basic Integration Statistics - LFN_INT_STATS1 Integration Statistics Table 1 - LFN_INT_TAB1 Find Improved Soft Limit - LFN_SOFT List Soft Limit Results - LFN_SOFT_LIST Automatic Soft Limit Determination - LFN_AUTO_SOFT Soft Limits Determination Defaults - LFN_SOFT_DF Log Automatic Soft Limits Errors - LFN_SOFT_ERR Monitor Automatic Soft Limits Steps - LFN_SOFT_MON Monitor Integration Progress (Dummy) - LFN_SOFT_PROG 4.4.2 Standalone Integration Routine - LFN_SAINT This routine is used to measure integrated intensities from a Laue image stored in memory. It may be used in a one pass mode to carry out box integration or, more usually, in a two pass mode to carry out profile fitted integration. The Laue Reflection List (LRL) must be generated for the plate being integrated prior to calling LFN_SAINT. Note also that when profile fitted integration is done for a plate, the spot size parameters used will be those used in the profile determination pass which might not necessarily be the same as those defined for the plate in question. A special option is available to carry out a profile fitted integration for an individual spot for diagnostic purposes. The LRL must be sorted on 'xfd' or 'yfd' before calling the routine. The best order is that which will progress through the image in the order that the image data is stored in memory. Fortran call: SUBROUTINE LFN_SAINT (IPACK, IPLATE, IPASS, IMG, ITYPE, IORDER, + NF_OFF, NAX1_RASTS, NAX2_RASTS, PROMIN, + NTHE, PROF_ROT, NOVLD, PROGRESS, CANCEL, + IERR, ERRSTR) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number IPASS i (R) =0 Box integration =1 forming profile =2 profile fitting >10 profile fit individual spot no. (IPASS-10) in spot list (for diagnostic purposes - intensity will not be stored in LRL) Data may be returned using LFN_GET_INTSPOT IMG (*) i (R) Image data array (may hold signed integer data or unsigned byte data packed into an integer array or unsigned two byte data packed into an integer array ITYPE i (R) Image data type =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 'squashed i2' IORDER i (R) Order of data in image wrt. the two local axes =1 +ax1 +ax2 =2 +ax1 -ax2 =3 -ax1 +ax2 =4 -ax1 -ax2 =5 +ax2 +ax1 =6 +ax2 -ax1 =7 -ax2 +ax1 =8 -ax2 -ax1 NF_OFF i (R) Fast offset between (slow) rasters of image (e.g. first dimension of the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type (bytes, 2-bytes or integers as set by ITYPE) NAX1_RASTS i (R) No. of rasters in the image along the first local axis NAX2_RASTS i (R) No. of rasters in the image along the second local axis PROMIN r (R) Minimum intensity to include in profile determination e.g. 100 for film, 600 for image plate NTHE i (R) Number of theta bins for profile fitting (e.g. 8, max=17 unless program limit was reset) PROF_ROT l (R) Flag to rotate/do-not-rotate profiles data to theta = 0.0 around the beam direction when forming profiles from elliptical spots. (.TRUE./.FALSE.) No rotation is done when spots are circular. Allowing rotation means that account is taken of the lengths and theta angles around the beam direction of the individual spots used to form the profiles but at the expense of accuracy in the mapping of the pixel positions done during the rotation. When using the profile for integrating a spot, the reverse rotation is applied to the bin profile. If no rotation is done, the profiles are gatherd by superimposing the spots used to determine a bin profile in the orientations in which they occur and the profile is used as gathered when profile fitting a spot for integration. Rotation may well be beneficial if the spots cover many pixels but should be used with caution if the spots only cover a few pixels. This flag is only used in a profile forming pass. When doing profile_fitted integration the value of the flag used when forming the profiles applies. NOVLD i (R) Number of overload pixels allowed in a spot for it still to be integrated as a 'good' spot which will not be flagged as having a overload intensity. PROGRESS ( ) Subroutine which will be called at intervals during the integration which may be used to display its progress if required (See below for its arguments). If not required, the dummy routine LFN_SOFT_PROG may be passed. Note that the routine must be declared as EXTERNAL in the calling program. CANCEL f (R) Logical function used to interrupt procedure It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) IERR i (W) Error flag = 0, OK = -1, Invalid pack number = -2, Invalid plate number = -3, Invalid image type or order flag = -4, Byte handling not available = 1, Box size required based on spot size exceeds current program limits = 2, Too many bins requested for profile fitting = 3, Invalid pass flag = 4, LRL not generated for current plate = 5, No profiles calculated = 6, Spot not present for individual spot integration request = 7, LRL not sorted on 'xfd' or 'yfd' = 10, Integration of 'too close to integrate' single spot requested = 11, Cannot integrate - <3 non-overlapped background pixels = 12, Cannot integrate - no non-overlapped/ non-overloaded peak pixels (may also be <3 non-overlapped background pixels) = 20, Out of limits box - cannot integrate single spot = 100 Interrupted via 'cancel' routine ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero Subroutine PROGRESS (IPASS, NSPOT, ISPOT) This routine called by the integration routine with the following parameters:- IPASS i (R) Integration pass = 0 box integration, = 1 get profiles, = 2 profile fitted integration NSPOT i (R) No. of spots to be integrated ISPOT i (W) Last spot integrated The routine sets the integration error code (see LRL_GET_INT, LRL_SET_INT) for bad spots as follows (the Bad spot flag will also be set): bit 0 no non-overlapped/non-overloded peak pixels. bit 1 < 20% of peak pixels are non-overlapped/non-overloaded. bit 2 <3 non-overlapped background pixels. bit 4 < 20% of background pixels are non-overlapped. The 20% (approx) values are calculated from the expression (NPIX-3)/5 where NPIX is the number of pixels is the peak or background as relevant. 4.4.3 Integration Parameter Defaults - LFN_SAINT_DF This routine returns some default values for use with the LFN_SAINT integration routine. Note that The profile intensity cutoff returned depends on the current image type. Fortran call: SUBROUTINE LFN_SAINT_DF (NPROF, PROMIN, PROF_ROT) Parameters: NPROF i (W) No. of bins for determining intensity profiles (8) PROMIN r (W) Minimum intensity of spot for inclusion in profiles 100.0 for film, otherwise 600.0 PROF_ROT l (W) Rotate elliptical profiles flag (.TRUE.) 4.4.4 Get Profile Parameters - LFN_GET_PROFPARS This routine is used to return details of the profile parameters calculated by a profile determining pass of the routine LFN_SAINT. Fortran call: SUBROUTINE LFN_GET_PROFPARS (IPK, IPL, NP_HALF, NUMP, NUMBIN, + PROF_ROT) Parameters: IPK i (W) Pack no. used in profiles calculation IPL i (W) Plate no. used in profiles calculation NP_HALF i (W) Half size of box used in profiles calculation (box 2*NP_HALF+1 square) NUMP i (W) No. of pixels used in profiles NUMBIN i (W) No. of profile bins PROF_ROT l (W) Profiles rotated flag 4.4.5 Get Profile Maximum - LFN_GET_PROFMAX This routine is used to return the maximum value for a requested profile calculated by a profile determining pass of the routine LFN_SAINT. Fortran call: SUBROUTINE LFN_GET_PROFMAX (IPROF, PROFMAX, IERR) Parameters: IPROF i (R) Profile no. (must be in range of those PROFMAX r (W) Maximum value in profile IERR i (W) Error flag =0 OK, =1 profile no. out of range 4.4.6 Get Spot Profile - LFN_GET_PROFILE This routine is used to return the details of a spot profile calculated by a profile determining pass of the routine LFN_SAINT. Fortran call: SUBROUTINE LFN_GET_PROFILE (IPROF, INDX_PROF, MAX_HALF, + IMASK, IXPR, IYPR, PRF, MAX_PROF, + IPK, IPL, NP_HALF, NUMP, NUMBIN, + IERR, ERRSTR) Parameters: IPROF i (R) Profile no. (must be in range of those calculated) INDX_PROF(-MAX_HALF:MAX_HALF,-MAX_HALF:MAX_HALF) i (W) Indices to pixels in profile arrays (0 for pixels not used). First dimension is along 'x' and 2'nd is along 'y' MAX_HALF i (R) Dimension parameter for INDX_PROF IMASK(MAX_PROF) i (W) Pixel use 0/1 background, -1 omitted 1 pixel border round peak, -2 = omitted pixel from spot overlap, -3 = omitted pixel from overloaded pixel, >=10 peak pixel IXPR(MAX_PROF) i (W) 'x' offset of pixel from box centre IYPR(MAX_PROF) i (W) 'y' offset of pixel from box centre PRF(MAX_PROF) r (W) Profile values MAX_PROF i (R) Maximum dimension of profile arrays passed IPK i (W) Pack no. used in profiles calculation IPL i (W) Plate no. used in profiles calculation NP_HALF i (W) Half size of box used in profiles calculation (box 2*NP_HALF+1 square) NUMP i (W) No. of pixels used in profiles NUMBIN i (W) No. of profile bins IERR i (W) Error flag =0 OK =1 Requested bin out of range =2 Profile arrays too small -1 Index array too small (central portion will be filled) - non-fatal ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.7 Get Profile Pixel Details - LFN_GET_PROFPIX This routine is used to return the details of a pixel from a spot profile calculated by a profile determining pass of the routine LFN_SAINT. Fortran call: SUBROUTINE LFN_GET_PROFPIX (IPROF, IX, IY, IMASK, PRF, IERR) Parameters: IPROF i (R) Profile no. (must be in range of those IX i (R) Pixel offset in 'x' from profile centre IY i (R) Pixel offset in 'y' from profile centre IMASK i (W) Pixel use 0/1 background, -1 omitted 1 pixel border round peak, -2 = omitted pixel from spot overlap, -3 = omitted pixel from overloaded pixel, >=10 peak pixel (Returned as -100 if outside profile box or pixel not used in profile determination) PRF r (W) Profile value for the pixel IERR i (W) Error flag =0 OK =1 Requested bin out of range =2 Requested pixel out of range 4.4.8 Get Integrated Spot Parameters - LFN_GET_SPOTPARS This routine is used to return the basic parameters of the last integrated spot calculated using the diagnostic option of the routine LFN_SAINT to integrate an individual profile-fitted spot. Fortran call: SUBROUTINE LFN_GET_SPOTPARS (KSPOT, KH, KK, KL, + XPOS_S, YPOS_S, NUM_S, NREJ_S, + BACK_S, AINTEN_S, SIGI_S, + IERR, ERRSTR) Parameters: KSPOT i (W) Spot no. in LRL of last integrated spot KH i (W) 'h' index of last integrated spot KK i (W) 'k' index of last integrated spot KL i (W) 'l' index of last integrated spot XPOS_S r (W) Spot 'x' position in rasters YPOS_S r (W) Spot 'y' position in rasters NUM_S i (W) No. of pixels in spot NREJ_S i (W) No. of rejected pixels BACK_S(3) r (W) Background plane constants AINTEN_S r (W) Integrated intensity SIGI_S r (W) sig(I) IERR i (W) Error flag =0 OK =1 No spot stored ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.9 Get Integrated Spot Code - LFN_GET_SPOTCODE This routine is used to return the integration code flag of the last integrated spot calculated using the diagnostic option of the routine LFN_SAINT to integrate an individual profile-fitted spot. Fortran call: SUBROUTINE LFN_GET_SPOTCODE (BAD_SP, I_CODE, IERR, ERRSTR) Parameters: BAD_S l (W) Bad spot flag =.true. yes, = .false. not I_CODE i (W) Integration code flag =0 clear Bit 0 set: Bad spot, no non-overlapped pixels in peak - LFN_SAINT returns error Bit 1 set: Bad spot, <20% non-overlapped pixels in peak Bit 2 set: Bad spot, <3 non-overlapped pixels in background - LFN_SAINT returns error Bit 3 set: Bad spot, <20% non-overlapped pixels in background IERR i (W) Error flag =0 OK =1 No spot stored ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.10 Get Integrated Spot Data - LFN_GET_INTSPOT This routine is used to return the details of the last integrated spot calculated using the diagnostic option of the routine LFN_SAINT to integrate an individual profile-fitted spot. Fortran call: SUBROUTINE LFN_GET_INTSPOT (MAX_NUMS, KSPOT, KH, KK, KL, + XPOS_S, YPOS_S, NUM_S, + IXP_S, IYP_S, ISHAPE_S, PIXV_S, + PROF_S, SUBPR_S, IREJ_S, NREJ_S, + BACK_S, AINTEN_S, SIGI_S, + IERR, ERRSTR) Parameters: MAX_NUMS i (R) Maximum dimension for returned spot arrays KSPOT i (W) Spot no. in LRL of last integrated spot KH i (W) 'h' index of last integrated spot KK i (W) 'k' index of last integrated spot KL i (W) 'l' index of last integrated spot XPOS_S r (W) Spot 'x' position in rasters YPOS_S r (W) Spot 'y' position in rasters NUM_S i (W) No. of pixels in spot IXP_S(MAX_NUMS) i (W) Pixel 'x' offsets from spot centre IYP_S(MAX_NUMS) i (W) Pixel 'y' offsets from spot centre ISHAPE_S(MAX_NUMS) i (W) Mask 0,1 = background; -1 omitted border pixel; -2 omitted pixel from overlapped spot; -3 saturated pixels (omitted) >=10 peak pixel PIXV_S(MAX_NUMS) r (W) Pixel OD values PROF_S(MAX_NUMS) r (W) Profile values SUBPR_S(MAX_NUMS) r (W) Background subtracted pixel values IREJ_S(MAX_NUMS) i (W) Reject pixels flags (=0 OK , =1 rejected) NREJ_S i (W) No. of rejected pixels BACK_S(3) r (W) Background plane constants AINTEN_S r (W) Integrated intensity SIGI_S r (W) sig(I) IERR i (W) Error flag =0 OK =1 No spot stored =2 Spot arrays too small ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.11 Get Spot Pixel Details - LFN_GET_SPOTPIX This routine is used to return the details of a pixel from the last integrated spot calculated using the diagnostic option of the routine LFN_SAINT to integrate an individual profile-fitted spot. Fortran call: SUBROUTINE LFN_GET_SPOTPIX (IPIX, IXP_S, IYP_S, IMASK_S, PIXV_S, + PROF_S, SUBPR_S, IREJ_S, IERR) Parameters: IPIX i (R) Pixel number in spot pixels list IXP_S i (W) Pixel 'x' offset from spot centre IYP_S i (W) Pixel 'y' offset from spot centre IMASK_S i (W) Mask 0,1 = background; -1 omitted border pixel; -2 omitted pixel from overlapped spot; -3 saturated pixel (omitted) >=10 peak pixel (return as -100 if pixel no. out of range) PIXV_S r (W) Pixel OD value PROF_S r (W) Profile value SUBPR_S r (W) Background subtracted spot profile pixel value IREJ_S i (W) Reject pixel flag 0=Ok, 1=rejected IERR i (W) Error flag =0 OK =1 Requested pixel out of range 4.4.12 Write Spot Profiles - LFN_LIST_PROFS This routine is used to write a spot profile or set of spot profiles calculated by a profile determining pass of the routine LFN_SAINT. Fortran call: SUBROUTINE LFN_LIST_PROFS (IUN, ITERM, IPROF, NPL, MAXLIN, + NSEP, NBLANK, IERR, ERRSTR) Parameters: IUN i (R) Unit number for listing (0=no printing) ITERM i (R) =1 output to a terminal, =0 output to a file IPROF i (R) Bin no. of profile to be listed, 0=all NPL i (R) No. of profiles to o/p per line (if 0 then will be calculated from MAXLIN). Will be reduced to that calculated from MAXLIN if it exceeds that. (Only relevant if IPROF=0) MAXLIN i (R) Maximum length for o/p line (up to 132) (note if the width of a single profile exceeds this then the line length will also exceed this). (Only relevant if IPROF=0) NSEP i (R) No. of separating spaces between profile o/p on same line (>=1) (Only relevant if IPROF=0) NBLANK i (R) No. of blank lines between rows of profiles (>=1) (Only relevant if IPROF=0) IERR i (W) Error flag =0 OK =1 Requested profile bin out of range ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.13 List Integrated Spot Details - LFN_LIST_INTSPOT This routine is used to write spot data from an integration pass of the routine LFN_SAINT for the last individually integrated spot (for diagnostic purposes). The pixel values plot and the spot profile plot are each scaled to a maximum of 99.0. The background subtracted pixel values plot is scaled by the same factor as for a pixel values plot. Fortran call: SUBROUTINE LFN_LIST_INTSPOT (IUN, ITERM, OP_BGPLAN, OP_PIXV, + OP_PIXSB, OP_PROF, IERR, ERRSTR) Parameters: IUN i (R) Unit number for listing (0=no printing) ITERM i (R) =1 output to a terminal, =0 output to a file OP_BGPLAN l (R) Output background plane parameters if .TRUE. OP_PIXV l (R) Output scaled pixel values plot if .TRUE. OP_PIXSB l (R) Output scaled background subtracted pixels plot if .TRUE. OP_PROF l (R) Output scaled spot profile plot if .TRUE. IERR i (W) Error flag =0 OK =1 No such spot data currently stored ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero 4.4.14 Basic Integration Statistics - LFN_INT_STATS1 This routine is used to collect some basic statistics about the integrated intensties from either the current Laue Reflection List (LRL) or for a requested plate stored in a Laue integrated spots list. Fortran call: SUBROUTINE LFN_INT_STATS1 (LINDX, IPACK, IPLATE, NS, NG, NO, NN, + NB, AIM, AIS, N3, N10, IERR) Parameters: LINDX i (R) Index for LIRL (>=0) or -1 for collect data from LRL IPACK i (R) Pack number (ignored if LRL used) IPLATE i (R) Plate number (ignored if LRL used) NS(5) i (W) No. of spots present for the 5 spot categories NG(5) i (W) No. of spots integrated & good for the 5 spot categories NO(5) i (W) No. of overload spots flagged for the 5 spot categories NN(5) i (W) No. of OK negative intensities for the 5 spot categories NB(5) i (W) No. of bad spots spots flagged for the 5 spot categories AIM(5) r (W) Mean I value for the 5 spot categories (for OK positive intensities only) AIS(5) r (W) Mean I/sig(I) values for the 5 spot categories (for OK positive intensities only) N3(5) i (W) No. OK spots with I>3*sig(I) for the 5 spot categories N10(5) i (W) No. OK spots wit I>10*sig(I) for the 5 spot categories IERR i (W) Error flag =0 OK =1 No LRL or plate not found or matched Notes: The five spot categories: 1) Total numbers of spots 2) Spatially separated singles 3) Spatially separated multiples 4) Spatially overlapped singles 5) Spatially overlapped multiples AIM, AIS, N3 and N10 values include overloads but not bad spots Good = measured (integrated) and not bad/overload OK = measured (integrated) and not bad (i.e. may include overloads) 4.4.15 Integration Statistics Table 1 - LFN_INT_TAB1 This routine is used used to produce a table of Laue statistics data using the statistics returned by the routine LFN_INT_STATS1. Fortran call: SUBROUTINE LFN_INT_TAB1 (IUN, ITERM, KEY, NS, NG, NO, NN, NB, + AIM, AIS, N3, N10) Parameters: IUN i (R) Unit no. for listing (0 if none) ITERM i (R) =1, o/p to terminal, =0 o/p to file KEY i (R) = 0 no key, =1 o/p key, =2 o/p key only key NS(5) i (R) No. of spots present for the 5 spot categories NG(5) i (R) No. of spots integrated & good for the 5 spot categories NO(5) i (R) No. of overload spots flagged for the 5 spot categories NN(5) i (R) No. of OK negative intensities for the 5 spot categories NB(5) i (R) No. of bad spots spots flagged for the 5 spot categories AIM(5) r (R) Mean I value for the 5 spot categories (for OK positive intensities only) AIS(5) r (R) Mean I/sig(I) values for the 5 spot categories (for OK positive intensities only) N3(5) i (R) No. OK spots with I>3*sig(I) for the 5 spot categories N10(5) i (R) No. OK spots wit I>10*sig(I) for the 5 spot categories AIM, AIS, N3 and N10 values include overloads but not bad spots Good = measured (integrated) and not bad/overload OK = measured (integrated) and not bad (i.e. may include overloads) 4.4.16 Find Improved Soft Limit - LFN_SOFT This routine determines an improved value for the 'dmin' or 'lambda-min' soft limits used in the processing of Laue data. The method involves over predicting the data, measuring integrated intensities and examining the statistics of the integrated intensities as a function of resolution or wavelength respectively. A preferred value is returned by the routine as well as the statistical data which may be further examined. Fortran call: SUBROUTINE LFN_SOFT (IPACK, IPLATE, IOPT, IMG, ITYPE, IORDER, + NF_OFF, NAX1_RASTS, NAX2_RASTS, PROMIN, + NTHE, PROF_ROT, PROGRESS, CANCEL, + FRAC, SIGTEST, FRTEST, NUMBINS, BIN_WIDTH, + NTOT_MEAS, NTOT_GTSIG, NMEAS, NGTSIG, RBIN, + SOFT_MIN, SOFT_MAX, SOFT_SEL, IBIN_SEL, + IERR, ERRSTR, IWARN, WARNSTR) Parameters: IPACK i (R) Pack number IPLATE i (R) Plate number IOPT i (R) Option =1 Dmin soft limit determination =2 Lambda-min soft limit determination IMG (*) i (R) Image data array (may hold signed integer data or unsigned byte data packed into an integer array or unsigned two byte data packed into an integer array or squashed i2 data packed into an integer array ITYPE i (R) Image data type =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 squashed i2 data IORDER i (R) Order of data in image wrt. the two local axes =1 +ax1 +ax2 =2 +ax1 -ax2 =3 -ax1 +ax2 =4 -ax1 -ax2 =5 +ax2 +ax1 =6 +ax2 -ax1 =7 -ax2 +ax1 =8 -ax2 -ax1 NF_OFF i (R) Fast offset between (slow) rasters of image (e.g. 1'st dimension of the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type (bytes, 2-bytes or integers as set by ITYPE) NAX1_RASTS i (R) No. of rasters in the image along the first local axis NAX2_RASTS i (R) No. of rasters in the image along the second local axis PROMIN r (R) Minimum intensity to include in profile determination e.g. 100 for film, 600 for image plate NTHE i (R) Number of theta bins for profile fitting (e.g. 8, max=17 unless program limit was reset) PROF_ROT l (R) Rotate profiles for elliptical spots integrattion flag PROGRESS ( ) Subroutine which will be called at intervals during the integration which may be used to display its progress if required (See below for its arguments). If not required, the dummy routine LFN_SOFT_PROG may be passed. Note that the routine must be declared as EXTERNAL in the calling program. CANCEL f (R) Logical function used to interrupt procedure It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) FRAC r (R) Fraction of current soft limit for use in reflection generation (suggested value = 0.8) SIGTEST r (R) No. of sigmas to be used for determining significant intensities for statistics (suggested value = 5.0) FRTEST r (R) Fraction for population of significant reflections just above soft limit (suggested value = 0.15) NUMBINS i (R) Number of bins to use (suggested value = 20) BIN_WIDTH r (R) Width of soft limit bins (suggest 0.02 if current value <=0.5, 0.05 if >0.5 and <= 1.0 and 0.1 if > 1.0 NTOT_MEAS i (W) Total number of measured spots NTOT_GTSIG i (W) Total number of significant spots NMEAS(*) i (W) Number of measured spots in each bin (dimensioned to at least NUMBINS) NGTSIG(*) i (W) Number of significant spots in each bin (dimensioned to at least NUMBINS) RBIN(*) r (W) Ratios of significant to measured spots in each bin (dimensioned to at least NUMBINS) SOFT_MIN r (W) Soft limit minimum used (rounded down to nearest bin_width multiple value) SOFT_MAX r (W) Soft limit maximum used SOFT_SEL r (W) Selected value for the soft limit IBIN_SEL i (W) Selected bin number (just above selected soft limit) IERR i (W) Error flag = 0, OK = -1, Invalid pack number = -2, Invalid plate number = -3, Invalid image type or order flag = -4, Byte handling not available = 1, Box size required based on spot size exceeds current program limits = 2, Too many bins requested for profile fitting = 3, Less than 2 bins requested for statistics = 100 Procedure interrupted ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero IWARN i (W) Warning flag = 0 OK (provided IERR = 0) = 1 No bin has 10 or more significant reflections = 2 First bin selected; soft limit needs to be determined with a lower start value = 3 Less than five significant reflection in selected 'above soft limit' bin WARNSTR c (W) Warning message string if IWARN is non-zero Subroutine PROGRESS (IPASS, NSPOT, ISPOT) This routine is passed on to the integration routine LFN_SAINT which will call it with the following parameters:- IPASS i (R) Integration pass = 0 box integration, = 1 get profiles, = 2 profile fitted integration NSPOT i (R) No. of spots to be integrated ISPOT i (W) Last spot integrated 4.4.17 List Soft Limit Results - LFN_SOFT_LIST This routine is used to list the results from a soft-limit determination using the LFN_SOFT routine. Output may be to a terminal or a file. Fortran call: SUBROUTINE LFN_SOFT_LIST (IUN, ITERM, IPACK, IPLATE, IOPT, + PROMIN, NTHE, PROF_ROT, SIGTEST, FRTEST, + NUMBINS, BIN_WIDTH, + NMEAS, NGTSIG, RBIN, + SOFT_MIN, SOFT_MAX, SOFT_SEL, IBIN_SEL, + IWARN, WARNSTR) Parameters: IUN i (R) Unit number for listing ITERM i (R) =1 output to a terminal, =0 output to a file IPACK i (R) Pack number IPLATE i (R) Plate number IOPT i (R) Option =1 Dmin soft limit determination =2 Lambda-min soft limit determination PROMIN r (R) Minimum intensity included in profiles determination NTHE i (R) Number of theta bins used in profile fitting PROF_ROT l (R) Rotate profiles for elliptical spots flag SIGTEST r (R) No. of sigmas used for determining significant intensities for statistics. FRTEST r (R) Fraction for population of significant reflections just above soft limit. NUMBINS i (R) Number of bins used. BIN_WIDTH r (R) Width of soft limit bins. NMEAS(*) i (R) Number of measured spots in each bin (dimensioned to at least NUMBINS) NGTSIG(*) i (R) Number of significant spots in each bin (dimensioned to at least NUMBINS) RBIN(*) r (R) Ratios of significant to measured spots in each bin (dimensioned to at least NUMBINS) SOFT_MIN r (R) Soft limit minimum used (rounded down to nearest bin_width multiple value) SOFT_MAX r (R) Soft limit maximum used SOFT_SEL r (R) Selected value for the soft limit IBIN_SEL i (R) Selected bin number IWARN i (R) Warning flag = 0 OK = 1 No bin has 10 or more significant reflectionns = 2 First bin selected; soft limit needs to be determined with a lower start value = 3 Less than five significant reflection in selected 'above soft limit' bin WARNSTR c (R) Warning message string if IWARN is non-zero Note: The parameters are those input/returned from the call to LFN_SOFT (apart from IUN, ITERM) 4.4.18 Automatic Soft Limit Determination - LFN_AUTO_SOFT This is a high level routine used to carry out an automatic procedure for determining improved soft limits (dmin and lambda-min) for pack or set of packs. It enables control of non-default parameters via a user defined options string. The routine make use of the LFN_SOFT routine in the actual determination of the soft limit. A number of routines are passed to the LFN_AUTO_SOFT routine and these may be tailored to meet any particular requirements of the calling program. Possible routines for some of those functions are supplied. Fortran call: SUBROUTINE LFN_AUTO_SOFT (IPACK, IPLATE, IOPT, OPTSTR, + IPKALL_DF, NPROF_DF, PROF_ROT_DF, + PROMIN_DF, + FRAC_DF, SIGTEST_DF, FRTEST_DF, + NBINS_DF, BINW_DF, + IMG_PK, IMG_PL, RD_IMG, + IMG, MAXIMG, ITYPE, NF_OFF, + IUN_LOG, MONITOR, PROGRESS, + LOG_RESULTS, LOG_ERR, CANCEL, + MAXBINS, NMEAS, NGTSIG, RBIN, + IUPD, IERR, ERRSTR, ERRSTR2) Parameters: IPACK i (M) Current pack number (On o/p last pack accessed) IPLATE i (M) Current plate number (On o/p last pack accessed) IOPT i (R) Option =1 dmin determination, =2 lambda-min determination OPTSTR c (R) Options string (max. 80 characters long) All keywords may be upper or lower case. 'PACK' or 'ALL' (default=pack) may be specified. Any combination of the following keyword/value pairs may be given . NPROF nprof No. of bins for determining intensity profiles PROMIN promin Minimum intensity of spot for inclusion in profiles NBINS nbins Number of bins to use in analysis BINW binw Bin width to use FRAC frac Fraction of current dmin or lambda-min defining low end of range for the analysis SIGTEST sigtest No. of sigmas used to define significant intensity FRTEST frtest Significant/measured ratio test for soft limit Defaults are passed as parameters (see below) - note some values may be dependent on current LDM parameter values IPKALL_DF i (R) Default flag for pack or all packs (1 or 2) NPROF_DFi i (R) Default no. of bins for determining intensity profiles e.g. 8 PROF_ROT_DF l (R) Default value for rotate profiles when integrating elliptical spots flag. PROMIN_DF r (R) Default minimum intensity of spot for inclusion in profiles e.g. 100.0 for film, otherwise 600.0 FRAC_DF r (R) Default fraction of current dmin or lambda-min defining low end of range for the analysis e.g. .8 SIGTEST_DF r (R) Default no. of sigmas used to define significant intensity e.g. 5.0 FRTEST_DF r (R) Default significant/measured ratio test for soft limit e.g. 0.15 NBINS_DF i (R) Default number of bins to use e.g. for DMIN = 5*((NINT (DMIN/BINW)+4)/5) e.g. for LMIN = 50 BINW_DF r (R) Default bin width to use e.g for DMIN 0.02 if dmin <=1.0 0.05 if dmin >1.0 & <=3.0 otherwise 0.1 e.g. for LMIN 0.02 IMG_PK i (M) Pack number for current image in IMG; 0 if none. On output will be for the last image read or 0 if there was an error reading the image. IMG_PL i (M) Plate number for current image in IMG; 0 if none. On output will be for the last image read or 0 if there was an error reading the image. RD_IMG s (R) Subroutine to open the image file and read an image. The call is as follows: CALL RD_IMG (IPK, IPL, ITYPE, NF_OFF, IMG, + MAXIMG, KERR, KERRSTR) where IPK i (R) Pack number IPL i (R) Plate number ITYPE i (M) See below NF_OFF i (M) See below IMG(*) i (W) See below MAXIMG i (R) See below KERR i (W) Error return flag: Routine must set this to 0 if image read was successful or to a non-zero value if there was an error. KERRSTR c (W) Error message string set by the routine if an error was encountered when reading the image. Note: In some instances it may be appropriate for the routine to set x_cen_f, y_cen_f values e.g derived from fiducial positions if it finds that these parameters have not already been set as the refinement procedure needs these in order to continue IMG(*) i (R) Array containing the (possibly packed) image data for the current plate. MAXIMG i (R) Maximum no. of words in IMG array ITYPE i (M) Image data type in IMG =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 squashed i2 data Note: May be reset by RD_IMG subroutine but must be given an input value if a previously read image is passed to the routine. NF_OFF i (M) Fast offset between (slow) rasters of image (e.g. 1'st dimension of the the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type as indicated by ITYPE. Note: May be reset by RD_IMG subroutine but must be given an input value if a previously read image is passed to the routine. IUN_LOG i (R) Unit number for output passed to LOG_RESULTS and LOG_ERR routines as one of their parameters when called. MONITOR s (R) Subroutine called at various stages of the procedure to enable the progress to be monitored. If desired the routine LFN_SOFT_MON may be passed. Note that the routine must be declared as EXTERNAL in the calling program. The call for the MONITOR routine is as follows: CALL MONITOR (IUN_LOG, IOPT, ISTAGE, + IPACK, IPLATE) IUN_LOG i (R) Log file unit number as passed to LFN_AUTO_SOFT IOPT i (R) 1=dmin, 2-lambda-min determination ISTAGE i (R) Stage reached flag = 0 Start of new pack = 1 Starting to read image = 2 Finished image reading = 3 Starting actual soft limit determination for the pack = 4 Finished soft limit determination for the pack IPACK i (R) Pack number IPLATE i (R) Plate number PROGRESS s (R) Subroutine which will be called at intervals during the integration which may be used to display its progress if required. It is passed as a parameter to the LFN_SAINT routine (see LFN_SAINT routine documentation for details of its arguments). If progess display is not required, the dummy routine LFN_SOFT_PROG may be passed. Note that the routine must be declared as EXTERNAL in the calling program. LOG_RESULTS s (R) User defined subroutine to output results of the refinement. For output to a log file only, this may be the routine LFN_SOFT_LIST. Note that the routine must be declared as EXTERNAL in the calling program. The call is as documented for the LFN_SOFT_LIST subroutine. LOG_ERR s (R) User defined subroutine called when an error condition is encountered. For certain conditions the routine may allow the refinement to continue for the next plate etc. For output only the subroutine LFN_SOFT_ERR may be used. This outputs the error message to IUN_LOG and terminates the refinement after any error is found. Note that the routine must be declared as EXTERNAL in the calling program. The call is as follows: CALL LOG_ERR (IUN_LOG, ICONT, ERRSTR, + ERRSTR2, NEXT) where IUN_LOG i (R) Unit number for log file as passed to LFN_AUTO_SOFT ICONT i (R) = 0 terminate refinement = 1 may continue with next pack if desired. =-1 Interrupted ERRSTR c (R) Error string (max 80 chars) ERRSTR2 c (R) Subsidiary error string - may be blank (max 80 chars) NEXT l (W) Set by the routine. If .true. then refinement will be continued with next pack or plate. If .false. then refinement will be terminated. Note: the routine must set it to .false. if ICONT is 0 or -1. CANCEL f (R) Logical function used to interrupt procedure It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) MAXBINS i (R) Maximum no. of 'd' or lambda bins which may be used for soft limit determination. NMEAS(*) i (*) Work array to hold no. of spots measured in each bin (dimensioned to at least MAXBINS) NGTSIG(*) i (*) Work aray to hold no. of significant spots in each bin. (dimensioned to at least MAXBINS) RBIN(*) r (*) Work array for significant/measured ratios in each bin. (dimensioned to at least MAXBINS) IUPD r (R) Update LDM with determined soft limits flag = 1 Update provided no error in determination = 2 Update provided no error in determination unless IWARN = 1, or IWARN = 3 from the LFN_SOFT call. = 0 Do not update. In this case the updating should be done in a user supplied version of the LOG_RESULTS or MONITOR subroutines. This may, if required, give the user an opportunity of deciding whether or not to accept the new limit(s). IERR i (W) Error flag for last error found = 0 OK (no errors) = -1 Invalid current pack number. = -2 Invalid current plate number. = -3 Invalid soft-limit type = -4 Invalid/ambiguous option requested options string = 1 Key plate not yet refined = 2 Error reading image = 3 Error from LFN_SOFT soft limit determining routine =100 Procedure interrupted ERRSTR c (W) Error message string (max 80 chars) if IERR is non-zero ERRSTR2 c (W) Additional error information (max 80 chars) if IERR is non-zero (blank for some error conditions) 4.4.19 Soft Limits Determination Defaults - LFN_SOFT_DF This routine returns a suggested set of default values for use with the automatic soft limit determination procedure LFN_AUTO_SOFT. Note that the number of bins and bin width values are based on the current value of the requested soft limit (for the key pack i.e. the first pack) and the profile intensity cutoff depends on the current image type. The profile fitting parameters are obtained internally via the LFN_SAINT_DF routine. Fortran call: SUBROUTINE LFN_SOFT_DF (IOPT, MAXBINS, NPROF, PROMIN, PROF_ROT, + FRAC, SIGTEST, FRTEST, NBINS, BINW) Parameters: IOPT i (R) Soft limit type 1=dmin, 2=lambda-min MAXBINS i (R) Maximum number of bins allowed NPROF i (W) No. of bins for determining intensity profiles (8) PROMIN r (W) Minimum intensity of spot for inclusion in profiles 100.0 for film, otherwise 600.0 PROF_ROT l (W) Rotate elliptical profiles flag (.TRUE.) FRAC r (W) Fraction of current dmin or lambda-min defining low end of range for the analysis (0.8) SIGTEST r (W) No. of sigmas used to define significant intensity (5.0) FRTEST r (W) Significant/measured ratio test for soft limit (0.15) NBINS i (W) Number of bins to use for DMIN = 5*((NINT (DMIN/BINW)+4)/5) for LMIN = 50 BINW r (W) Bin width to use for DMIN 0.02 if dmin <=1.0 0.05 if dmin >1.0 & <=3.0 otherwise 0.1 for LMIN 0.02 4.4.20 Log Automatic Soft Limits Errors - LFN_SOFT_ERR This routine is used to log errors from the automatic soft limit determining procedure of the routine LFN_AUTO_SOFT. If used, it is passed as the user supplied LOG_ERR subroutine which is one of the LFN_AUTO_SOFT parameters and must be declared as external. This version of the error handling routine treats all errors as ones which will terminate the automatic refinement procedure. Fortran call: SUBROUTINE LFN_SOFT_ERR (IUN_LOG, ICONT, ERRSTR, ERRSTR2, + NEXT) Parameters: IUN_LOG i (R) Unit number for log file ICONT i (R) = 0 treat as error which terminates refinent = 1 may continue with next pack if desired =-1 interrupted ERRSTR c (R) Error string (max 80 chars) ERRSTR2 c (R) Subsidiary error string - may be blank (max 80 chars) NEXT l (W) Set by the routine. If .true. then refinement will be continued with next pack. If .false. then refinement will be terminated. Note: the routine must set it to .false. ICONT is 0 or -1. 4.4.21 Monitor Automatic Soft Limits Steps - LFN_SOFT_MON This routine is used to monitor the steps from the automatic soft limit determining procedure of the routine LFN_AUTO_SOFT. If used, it is passed as the user supplied MONITOR subroutine which is one of the LFN_AUTO_SOFT parameters and must be declared as external. This version of the monitoring routine just outputs one message to the log file at the start of the soft limit determination for each pack processed. Fortran call: SUBROUTINE LFN_SOFT_MON (IUN_LOG, IOPT, ISTAGE, IPACK, IPLATE) Parameters: IUN_LOG i (R) Unit number for log file IOPT i (R) Option flag =1dmin, =2 lambda-min ISTAGE i (R) = 0 Start of new pack = 1 Starting to read image = 2 Finished image reading = 3 Starting actual soft limit determination for the pack = 4 Finished soft limit IPACK i (R) Pack number IPLATE i (R) Plate number 4.4.22 Monitor Integration Progress (Dummy) - LFN_SOFT_PROG This is a dummy routine which may be passed as the PROGRESS routine to the subroutine LFN_AUTO_SOFT, LFN_SOFT or LFN_SAINT. It is set up with the required parameters and merely returns when called. Fortran call: SUBROUTINE LFN_SOFT_PROG (IPASS, NSPOT, ISPOT) Parameters: IPASS i (R) Pass =0 box integration =1 get profiles =2 profile fitted integration NSPOT i (R) No. of spots to be integrated ISPOT i (R) Last spot integrated 4.5 LAUE UNIQUE DATA ANALYSIS 4.5.1 Introduction A number of routines are available for generating lists of unique reflections, making counts of measured or predicted Laue reflections and generating tables of statistics showing the amount of unique data measured or predicted. The following routines are available: Generate Unique Reflections List - LFN_UNQ_GEN Re-initialise Unique Reflections Counts - LFN_UNQ_RESET Get Indices of a Unique Reflection - LFN_UNQ_HKL Increment Counts in Unique Reflections List - LFN_UNQ_INC Get Reflection Counts - LFN_UNQ_GET Statistics Relative to Unique Data - LFN_UNQ_STAT Statistics Table 1 Versus Unique Data - LFN_UNQ_TAB1 Statistics Table 2 Versus Unique Data - LFN_UNQ_TAB2 Statistics Table 3 Versus Unique Data - LFN_UNQ_TAB3 4.5.2 Generate Unique Reflections List - LFN_UNQ_GEN This routine will generate a list of the unique relections for a given resolution range based on the current LDM parameter values for the cell and symmetry which must be defined. The unique reflections list is stored internally. This routine could equally well be used to aid the analysis of monochromatic data. Fortran call: SUBROUTINE LFN_UNQ_GEN (RESMIN, RESMAX, NUNIQUE, IERR) Parameters: RESMIN r (R) Minimum resolution limit in Angstroms RESMAX r (R) Maximum resolution limit in Angstroms NUNIQUE i (W) No. of unique reflections generated IERR i (W) Error flag =0 OK, =1 No symmetry defined, =2 too may reflections to store Resolution limits may be in either order 4.5.3 Re-initialise Unique Reflections Counts - LFN_UNQ_RESET This subroutine is used to re-initialise all the counts flags in the unique reflections list as generated by LFN_UNQ_GEN. Fortran call: SUBROUTINE LFN_UNQ_RESET Parameters: None 4.5.4 Get Indices of a Unique Reflection - LFN_UNQ_HKL This routine returns the indices of a reflection from a unique reflections list as genertated by the routine LFN_UNQ_GEN Fortran call: SUBROUTINE LFN_UNQ_HKL (IREF, IH, IK, IL) Parameters: IREF i (R) Reflection number in the list IH i (W) 'h' index IK i (W) 'k' index IL i (W) 'l' index h, k, l returned as 0, 0, 0, if invalid IREF given 4.5.5 Increment Counts in Unique Reflections List - LFN_UNQ_INC This routine enables counters, associated with the unique reflections list, to be incremented for a reflection in the list so that statistics may be subsequently produced comparing the counted reflections with the numbers of unique reflections. Fortran call: SUBROUTINE LFN_UNQ_INC (IREF, MULT, I_SIGN, ISPAT, IERR) Parameters: IREF i (R) Reflection number in the list MULT i (R) Multiplicity (1 for a single) I_SIGN i (R) +1 for I+, -1 for I- ISPAT i (R) =0 non-spatially overlapped, =1 spatially overlapped IERR i (W) =0 OK, =1 invalid IREF 4.5.6 Get Reflection Counts - LFN_UNQ_GET This routine returns the number of times a reflection has been registerd as being present in various categories in the unique reflections list whose counts have been updated by calls to the LFN_UNQ_INC routine. Fortran call: SUBROUTINE LFN_UNQ_GET (IREF, NSING, NMULT, NDOUBLE, NTRIPLE, + NHIGHER, NPLUS, NMINUS, NCLEAR, NSPAT) Parameters: IREF i (R) Reflection number in the list NSING i (W) No. of occurrences as a single (returns -1 if error in IREF) NMULT i (W) No. of occurrences as a multiple of any kind NDOUBLE i (W) No. of occurrences as part of a double NTRIPLE i (W) No. of occurrences as part of a multiple NHIGHER i (W) No. of occurrences as part of a higher multiple NPLUS i (W) No. of I+ occurrences NMINUS i (W) No. of I- occurrences NCLEAR i (W) No. of occurrences as a non spatially overlapped reflection NSPAT i (W) No. of occurrences as a spatially overlapped reflection 4.5.7 Statistics Relative to Unique Data - LFN_UNQ_STAT This routine resturns statistics based on the current counts of reflections marked in the unique reflections list using the LFN_UNQ_INC routine. The statistics are in bins of 4*sin**2theta/lambda**2. Fortran call: SUBROUTINE LFN_UNQ_STAT (NBIN, SPAT, RESMIN, RESMAX, + NCOUNT, NCOUNT_TOT, + PERCENT, PERCENT_TOT, IERR) Parameters: NBIN i (R) No. of 4*sin**2theta/lambda**2 bins SPAT l (R) =.TRUE. include spatially overlapped data, =.FALSE. do not RESMIN(10,NBIN) r (W) Start resolution of bins RESMAX(10,NBIN) r (W) End resolution of bins NCOUNT(10,NBIN) i (W) No. counts for each bin (see also below) NCOUNT_TOT(NBIN) i (W) Total numbers (see also below) PERCENT(10,NBIN) r (W) Percentages of the unique data in bins (see also below) PERCENT_TOT(NBIN) r (W) Percentage totals (see also below) IERR i (W) Error flag =0 OK, =1 no reflns. or no bins First index: = 1 No. of unique reflections = 2 No. of Laue (single or multiple) = 3 No. of singles (may also be multiples) = 4 No. of multiples (may also be singles) = 5 No. of doubles (may also be otherwise) = 6 No. of triples (may also be otherwise) = 7 No. of higher mults. (may also be otherwise) = 8 No. with double as lowest multiplicity = 9 No. with triple as lowest multiplicity = 10 No. with higher mult as lowest multiplicity 4.5.8 Statistics Table 1 Versus Unique Data - LFN_UNQ_TAB1 This routine is used used to produce a table of Laue statistics data using the statistics returned by the routine LFN_UNQ_STAT. The analysis is in bins of 4*sin**2theta/lambda**2. This routine lists counts in classes of multiplicity; note that a given Laue reflection may fall into more than one class (cf LFN_UNQ_TAB2). The data may be written to the terminal or to a file. Fortran call: SUBROUTINE LFN_UNQ_TAB1 (IUN, ITERM, NBIN, SPAT, RESMIN, RESMAX, + NCOUNT, NCOUNT_TOT) Parameters: IUN i (R) Unit no. for listing ITERM i (R) =1, o/p to terminal, =0 o/p to file NBIN i (R) No. of 4*sin**2theta/lambda**2 bins SPAT l (R) =.TRUE. spatially overlapped data were included, =.FALSE. spatially overlapped data not included, This must be the value used when LFN_UNQ_STAT was called. RESMIN(10,NBIN) r (R) Start resolution of bins RESMAX(10,NBIN) r (R) End resolution of bins NCOUNT(10,NBIN) i (R) No. counts for each bin (see also below) NCOUNT_TOT(NBIN) i (R) Total numbers (see also below) First index: = 1 No. of unique reflections = 2 No. of Laue (single or multiple) = 3 No. of singles (may also be multiples) = 4 No. of multiples (may also be singles) = 5 No. of doubles (may also be otherwise) = 6 No. of triples (may also be otherwise) = 7 No. of higher mults. (may also be otherwise) = 8 No. with double as lowest multiplicity = 9 No. with triple as lowest multiplicity = 10 No. with higher mult as lowest multiplicity 4.5.9 Statistics Table 2 Versus Unique Data - LFN_UNQ_TAB2 This routine is used used to produce a table of Laue statistics data using the statistics returned by the routine LFN_UNQ_STAT. The analysis is in bins of 4*sin**2theta/lambda**2. This routine lists counts in classes of minimum multiplicity from which each reflection may be obtained; note that a given Laue reflection may fall into only one class for this table (cf LFN_UNQ_TAB1). The data may be written to the terminal or to a file. Fortran call: SUBROUTINE LFN_UNQ_TAB2 (IUN, ITERM, NBIN, SPAT, RESMIN, RESMAX, + NCOUNT, NCOUNT_TOT) Parameters: IUN i (R) Unit no. for listing ITERM i (R) =1, o/p to terminal, =0 o/p to file NBIN i (R) No. of 4*sin**2theta/lambda**2 bins SPAT l (R) =.TRUE. spatially overlapped data were included, =.FALSE. spatially overlapped data not included, This must be the value used when LFN_UNQ_STAT was called. RESMIN(10,NBIN) r (R) Start resolution of bins RESMAX(10,NBIN) r (R) End resolution of bins NCOUNT(10,NBIN) i (R) No. counts for each bin (see also below) NCOUNT_TOT(NBIN) i (R) Total numbers (see also below) First index: = 1 No. of unique reflections = 2 No. of Laue (single or multiple) = 3 No. of singles (may also be multiples) = 4 No. of multiples (may also be singles) = 5 No. of doubles (may also be otherwise) = 6 No. of triples (may also be otherwise) = 7 No. of higher mults. (may also be otherwise) = 8 No. with double as lowest multiplicity = 9 No. with triple as lowest multiplicity = 10 No. with higher mult as lowest multiplicity 4.5.10 Statistics Table 3 Versus Unique Data - LFN_UNQ_TAB3 This routine is used used to produce a table of Laue statistics data using the statistics returned by the routine LFN_UNQ_STAT. The analysis is in bins of 4*sin**2theta/lambda**2. This routine lists cumulative (cf LFN_UNQ_TAB1, LFN_UNQ_TAB2) counts in classes of minimum multiplicity from which each reflection may be obtained; note that a given Laue reflection may fall into only one class (cf LFN_UNQ_TAB1). The data may be written to the terminal or to a file. Fortran call: SUBROUTINE LFN_UNQ_TAB3 (IUN, ITERM, NBIN, SPAT, RESMIN, RESMAX, + NCOUNT, NCOUNT_TOT, PERCENT, PERCENT_TOT) Parameters: IUN i (R) Unit no. for listing ITERM i (R) =1, o/p to terminal, =0 o/p to file NBIN i (R) No. of 4*sin**2theta/lambda**2 bins SPAT l (R) =.TRUE. spatially overlapped data were included, =.FALSE. spatially overlapped data not included, This must be the value used when LFN_UNQ_STAT was called. RESMIN(10,NBIN) r (R) Start resolution of bins RESMAX(10,NBIN) r (R) End resolution of bins NCOUNT(10,NBIN) i (R) No. counts for each bin (see also below) NCOUNT_TOT(NBIN) i (R) Total numbers (see also below) PERCENT(10,NBIN) r (R) Counts for each bin as percentages of unique data PERCENT_TOT(NBIN) r (R) Total counts as percentages of unique data First index: = 1 No. of unique reflections = 2 No. of Laue (single or multiple) = 3 No. of singles (may also be multiples) = 4 No. of multiples (may also be singles) = 5 No. of doubles (may also be otherwise) = 6 No. of triples (may also be otherwise) = 7 No. of higher mults. (may also be otherwise) = 8 No. with double as lowest multiplicity = 9 No. with triple as lowest multiplicity = 10 No. with higher mult as lowest multiplicity 4.6 DETERMINE SPOT POSITIONS AND SIZES 4.6.1 Introduction A set of routines is available to determine the scanner coordinates of of the spots on a Laue image, to determine the spot lengths and widths and to analyse the results. A routine to output the results is also available. The following routines are available: Find Spot Positions in an Image - LFN_FINDSPOTS Analyse the Spots List - LFN_SPOTS_ANALYSE List Spot Size Analysis Results - LFN_SPOTS_ANA_LIS 4.6.2 Find Spot Positions in an Image - LFN_FINDSPOTS This routine is used to find the Laue spot positions in an image stored in memory. A pre-calculated background image is passed to the routine and the routine searches for pixels at a certain threshols above background to determine those pixels which are presumed to belong to spots. The routine continuously updates the spot position by updating the calculation of its centre of gravity as the spot is built up from contiguous above threshold pixels. At the same time as the spot is being built up, a rotated image of the spot is also being built up along the horizontal axis so that the spot length is just determined as the horizontal extent of the finished spot and the spot width as the vertical extent of the rotated spot. A list of spot details is stored in an in-memory spot list managed by the 'DML' set of routines. Fortran call: SUBROUTINE LFN_FINDSPOTS (IMG, ITYPE, IORDER, NF_OFF, + NAX1_RASTS, NAX2_RASTS, + IMG_BG, NF_BGOFF, NBGCMP, + IDATA, IWORK, + XCEN, YCEN, RMIN, RMAX, + XLOW, XHIGH, YLOW, YHIGH, REXCLUDE, + THRESHFAC, PROGRESS, CANCEL, + MINDX_SPOT, NSPOT, IERR, + ERRSTR) Parameters: IMG (*) i (R) Image data array (may hold signed integer data or unsigned byte data packed into an integer array or unsigned two byte data packed into an integer array. A fourth 'squashed' i2 format is also available. ITYPE i (R) Image data type =1 unsigned byte =2 unsigned two byte =3 signed (full) integer =4 'squashed i2' IORDER i (R) Order of data in image wrt. the two local axes =1 +ax1 +ax2 =2 +ax1 -ax2 =3 -ax1 +ax2 =4 -ax1 -ax2 =5 +ax2 +ax1 =6 +ax2 -ax1 =7 -ax2 +ax1 =8 -ax2 -ax1 NF_OFF i (R) Fast offset between (slow) rasters of image (e.g. first dimension of the image data if the data are held in a two dimensional array). This value is the number of elements for the image data type (bytes, 2-bytes or integers as set by ITYPE) IMG_BG i (R) Background image (same data format as IMG) NF_BGOFF i (R) Fast offset between (slow) rasters of background image (e.g. first dimension of the background image data if the data are held in a two dimensional array). This value is the number of elements for the image data type (bytes, 2-bytes or integers as set by ITYPE) NBGCMP i (R) No. of pixels in each direction which were compressed into 1 for the background calculation. NAX1_RASTS i (R) No. of rasters in the image along the first local axis. NAX2_RASTS i (R) No. of rasters in the image along the second local axis. IDATA i (*) Work array to hold the spot data returned from the image. Must be dimensioned to at least the maximum no. of rasters in either of the two dimensions of the full image. IWORK i (*) Work array dimensioned to at least the maximum no. of rasters in either of the two dimensions of the full image. XCEN r (R) 'x' centre of pattern image in rasters (corrected) YCEN r (R) 'y' centre of pattern image in rasters (corrected) RMIN r (R) Minimum radius of active area (rasters) RMAX r (R) Maximum radius of active area (rasters) XLOW r (R) Low limit on 'x' of area to include (0.0=image min.) (rasters) XHIGH r (R) High limit on 'x' of area to include (0.0=image max.) (rasters) YLOW r (R) Low limit on 'y' of area to include (0.0=image min.) (rasters) YHIGH r (R) High limit on 'y' of area to include (0.0=image max.) (rasters) REXCLUDE r (R) The routine uses RMIN+REXCLUDE and RMAX-REXCLUDE as actual limits for min and max radii to avoid edge of detector problems with background calculation (rasters). Also uses XLOW+REXCLUDE, XHIGH-REXCLUDE, YLOW+REXCLUDE and YHIGH-REXCLUDE as limits if XLOW, XHIGH etc. are set. A suggestion is to use a value value of (dimension in pixels of background calculation box)/sqrt(2) if XDLF_BG_CALC was used to calculate the background image. THRESHFAC i (R) Uses pixels more than THRESHFAC*background above background as being pixels which belong to spots. PROGRESS ( ) Subroutine which will be called at intervals during the spots find which may be used to display its progress if required (See below for its arguments). Note that the routine must be declared as EXTERNAL in the calling program. CANCEL f (R) Logical function used to interrupt procedure. It has one dummy argument and must return a logical value of .TRUE. to cancel the procedure or .FALSE. to let it proceed. The actual function passed must be declared as both LOGICAL and EXTERNAL in the calling program. (The dummy function LFN_DUMMY_CNCL may be used) MINDX_SPOT i (W) 'DML' record storage routines index. Spots list returned. Seven words/spot Word 1 SX Spot 'x' position (rasters) (real) Word 2 SY Spot 'y' position (rsaters) (real) Word 3 SUMI Spot intensity (real) Word 4 NPIX No. of pixels in spot (integer) Word 5 SPOT_LENGTH Spot length (pixels) (integer) Word 6 SPOT_WIDTH Spot width (pixels) (integer) Word 7 SPOT_ANGLE Spot angle in degrees (real) NSPOT i (W) No. of spots found. IERR i (W) Error flag = 0, OK = 1, Memory allocation error for spots list = 2, Too many active spots =100, Cancelled ERRSTR c (W) Error message string (max 80 chars) set if IERR is non-zero. Subroutine PROGRESS (IFLAG, NSTRIPS, ISTRIP) This routine called by the spot find routine with the following parameters:- IFLAG i (R) Integration pass = 0 start = 1 spot search in progress = 2 finished NSTRIP i (R) No. strips for spot search ISTRIP i (W) Current strip 4.6.3 Analyse the Spots List - LFN_SPOTS_ANALYSE This routine is used to analyse the list of spots determined by the routine LFN_FINDSPOTS. The analysis is performed for a series of angular bins around the image centre. Fortran call: SUBROUTINE LFN_SPOTS_ANALYSE (MINDX_SPOT, IOPT, CUT, N_BIN, + BIN_START, BIN_END, SUM, NUMBIN, + VARIANCE, STDDEVN, AVBIN, + N_REJECT, SUM_GOOD, N_GOOD, + SEL_SIZE, IERR, ERRSTR) Parameters: MINDX_SPOT i (R) Index to in memory spots list from LFN_FINDSPOTS IOPT i (R) Flag = 1 analyse spot length, = 2 analyse spot width. CUT r (R) No. of standard deviations from mean spot dimension for which spots are eliminated as too small or too big. Suggested value 3.5. N_BIN i (R) Divide into N_BIN angular bins for the analysis. BIN_START(*) r (W) Start angle for each bin (must be dimensioned to at least N_BIN). BIN_END(*) r (W) End angle for each bin (must be dimensioned to at least N_BIN). SUM(*) r (W) Sum for each bin of spot length/width (must be dimensioned to at least N_BIN). NUMBIN(*) i (W) Number of spots in each bin (must be dimensioned to at least N_BIN). VARIANCE(*) r (W) Variance of spot length/width for each bin (must be dimensioned to at least N_BIN). STDDEVN(*) r (W) Standard deviation of spot length/width for each bin (must be dimensioned to at least N_BIN). AVBIN (*) r (W) Average of spot length/width for each bin (must be dimensioned to at least N_BIN). N_REJECT(*) i (W) No. of spots rejected for each bin (must be dimensioned to at least N_BIN). SUM_GOOD(*) r (W) Sum of spot lengths/widths for each bin after rejection on standard deviation cutoff (must be dimensioned to at least N_BIN). N_GOOD(*) i (W) No. of spots for each bin after rejection on standard deviation cutoff (must be dimensioned to at least N_BIN). SEL_SIZE r (W) Selected spot length/width. IERR i (W) Error return flag = 0 OK = 1 spots list not found ERRSTR c (W) Error message returned if IERR is non-zero (should be dimensioned to 80 characters). 4.6.4 List Spot Size Analysis Results - LFN_SPOTS_ANA_LIS This routine is used to list the results from the spot size analysis routine LFN_SPOTS_ANALYSE. Output may be to a terminal or a file. Fortran call: SUBROUTINE LFN_SPOTS_ANA_LIS (IUN, ITERM, IOPT, N_BIN, BIN_START, + BIN_END, SUM_GOOD, N_GOOD, N_REJECT, + SEL_SIZE,RAST_MM, THRESHFAC, CUT, + SIZE_FAC, IPACK, IPLATE) Parameters: IUN i (R) Unit number for listing. ITERM i (R) =1 output to a terminal, =0 output to a file IOPT i (R) Flag = 1 spot length analysis results, = 2 spot width analysis results. N_BIN i (R) Data divided into N_BIN angular bins for analysis. (value as passed to LFN_SPOTS_ANALYSE) BIN_START(*) r (R) Start angle for each bin (as returned from LFN_SPOTS_ANALYSE). BIN_END(*) r (R) End angle for each bin (as returned from LFN_SPOTS_ANALYSE). SUM_GOOD(*) r (R) Sum of spot lengths/widths for each bin after rejection on standard deviation cutoff (as returned from LFN_SPOTS_ANALYSE). N_GOOD(*) i (R) No. of spots for each bin after rejection on standard deviation cutoff (as returned from LFN_SPOTS_ANALYSE). N_REJECT(*) i (R) No. of spots rejected for each bin based of standard deviation cutoff (as returned from LFN_SPOTS_ANALYSE). SEL_SIZE r (R) Spot length or width selected by LFN_SPOTS_ANALYSE RAST_MM r (R) Conversion factor (rasters to mm). THRESHFAC r (R) Threshold factor for picking spots as used in call to LFN_FINDSPOTS. CUT r (R) Standard deviation cutoff factor for rejecting spots as used in LFN_SPOTS_ANALYSE. IPACK i (R) Pack no. for which spot size is being determined. IPLATE i (R) Plate no. in pack for which spot size is being determined. 4.7 DUMMY CANCEL ROUTINE 4.7.1 Introduction A number of routines allow for a 'cancel' or 'interrupt' routine to be passed as an argument (e.g. automatic parameter refinement, soft-limits determination, integration). A dummy routine is provided for use where the facility is not required and no user-specific routine is passed. The following routines are available: Dummy Cancel Routine - LFN_DUMMY_CNCL 4.7.2 Dummy Cancel Routine - LFN_DUMMY_CNCL This routine may be used when a 'cancel' routine is required. It is a dummy and always returns a .FALSE. value i.e. it will never cause the procedure to be interrupted. Fortran call: LOGICAL FUNCTION LFN_DUMMY_CNCL (IDUM) Parameters: IDUM i (R) Dummy parameters 4.8 CREATE .GE1/.GE2 FILES 4.8.1 Introduction These routines are for creating .ge1/.ge2 files from a Laue Integrated Reflection List (LIRL) containing integrated intensities. The following routines are available: Create .ge1/.ge2 Files from LIRL - LFN_LIRLGE 4.8.2 Create .ge1/.ge2 Files from LIRL - LFN_LIRLGE This routine is used to create a pair of .ge1/.ge2 files from a Laue Integrated Reflection List (LIRL) containing integrated intensities. The output files must be opened prior to calling the routine and will be closed by the routine. Fortran call: SUBROUTINE LFN_LIRLGE (MINDX, IUN_GE1, IUN_GE2, KPACK, SCAL, + LAMBDA_BINS, NUM_SPOTS, NUM_MULTIPLETS, + NUM_SPATIALS, NUM_BOTH, NUM_NODALS, + RESCALE, SCALOUT, KERR) Parameters: MINDX i (R) Index for LIRL IUN_GE1 i (R) Unit no. for .ge1 file (already opened) IUN_GE2 i (R) Unit no. for .ge2 file (already opened) KPACK i (R) Pack number SCAL r (R) Scale factor to apply to intensities LAMBDA_BINS i (R) Lambda bins histogram NUM_SPOTS i (W) No. of spots written NUM_MULTIPLETS i (W) No. of multiplets NUM_SPATIALS i (W) No. of spatials NUM_NODALS i (W) No. nodals NUM_BOTH i (W) No. both spatial & multiple RESCALE l (W) O/p scale factor recalculated flag SCALOUT r (W) O/p scale factor actually used KERR i (W) Error flag = 0 OK = 1 error in sorting - unable to allocate memory(file not written) 4.9 READ DATA INTO LIRL 4.9.1 Introduction These routines are for reading reflections data (with intensities) from .ge1/.ge2 files or an MTZ file as output by LAUEGEN into a Laue Integrated Reflection List (LIRL). The following routines are available: Read Data from .ge1/.ge2 Files to LIRL - LFN_GELIRL Read Data from MTZ File to LIRL - LFN_MTZLIRL 4.9.2 Read Data from .ge1/.ge2 Files to LIRL - LFN_GELIRL This routine is used to read data from a pair of .ge1/.ge2 files into a Laue Integrated Reflection List (LIRL). The input files must be opened prior to calling the routine and will remain open after the routine has been called. Data are only copied for plates for which at least one measured intensity is recorded. Certain irems have flags stored instead of intensity/sigma values. Such reflections will normally be excluded from calulations but the following values will be assigned for the following cases: not-measured II=0, SIGI=0; overload II=32767, SIGI=1000; bad spot II as stored, SIGI=1000. Fortran call: SUBROUTINE LFN_GELIRL (MINDX, IUN_GE1, IUN_GE2, IPLATE, KPACK, + NSPOT, IERR) Parameters: MINDX i (R) Index for LIRL IUN_GE1 i (R) Unit no. for .ge1 file (already opened) IUN_GE2 i (R) Unit no. for .ge2 file (already opened) IPLATE i (R) Copy data for this plate. 0=all plates for which any measured intensities recorded KPACK i (R) Pack number (>0) (or index to pack list) to be stored in the LIRL for this set of data. NSPOT i (W) No. of spots added to LIRL IERR i (W) Error flag = 0 OK = 1 Error reading .ge1 file = 2 Error reading .ge2 file = 3 Error adding record to LIRL 4.9.3 Read Data from MTZ File to LIRL - LFN_MTZLIRL This routine is used to read data from an MTZ integrated reflections data file as output by the LAUEGEN or INTLDM programs into a Laue Integrated Reflection List (LIRL). The input file must be opened prior to calling the routine and will remain open after the routine has been called unless an error is encountered. Fortran call: SUBROUTINE LFN_MTZLIRL (MINDX, MTZ_INDX, NUMP, IPACK_ID, + KPACK, IPLATE, NSPOT, IERR) Parameters: MINDX i (R) Index for LIRL MTZ_INDX i (R) Index for MTZ file (already opened) NUMP i (R) Number of packs for which data are to be read IPACK_ID() i (R/W) The pack id's for the NUMP packs - must all be given (>=0) unless NUMP=1. IF NUMP=1 and IPACK_ID(1)<0 then the data will be read for the first pack in the file. The pack id of the pack will be returned in IPACK_ID(1). KPACK() i (R) The pack numbers (>0) (or indices to pack list) for the NUMP packs to be stored in the LIRL. IPLATE i (R) The number of the plate for which the data are to be stored. NSPOT i (W) No. of spots added to LIRL IERR i (W) Error flag = 0 OK =-1 Invalid index for LIRL = 1 NUMP<=0 = 2 All required MTZ columns not found = 3 Error adding record to LIRL