CHAPTER 3 - LAUE SCALING MODULE (LSM) ROUTINES

3.1 INTRODUCTION

These are sets of routines which provide some machine independent functions for implementing the Laue Scaling Module (LSM). The LSM routines are designed so that they can be used in a number of different contexts including that of the Laue Data Module (LDM). Also included are an associated set of Laue Scaling Parameter (LSP) routines designed to form the basis of a stand-alone Laue scaling, normalisation and absorption correction program.

The following sets of routines are available:

Setting up the Laue Scaling Module (LSM)
Copy KDM Stored LSM Data to/from Internal Scaling Arrays
Select and Find Reflection Sets
LSM Refinement Routines
Multiples deconvolution
Miscellaneous LSM Routines
Setting up the Laue Scaling Parameters LSP
LSP Based Convenience Routines
Analysing the Intensity Statistics after Scaling

3.2 SETTING UP THE LAUE SCALING MODULE (LSM)

3.2.1 Introduction

Routines are available to set up the LSM scaling parameters and related data prior to using the other LSM based routines provided. LSM_KEYSETUP needs to be called to set up the LSM keyworded scaling parameters, LSM_PARSETUP (or an associated routine) needs to be called to set up other parameters required by the LSM routines and LSM_KDMCOPY needs to be called to copy the read in LSM parameter values to a set of internal scaling arrays (SCP) used by the LSM routines.

The following routines are available:

Set up keyworded parameters - LSM_KEYSETUP
Set up other LSM parameters - LSM_PARSETUP
Select absorption option - LSM_ABSOPT

3.2.2 Set up keyworded parameters - LSM_KEYSETUP

This routine defines the LSM (Laue Scaling Module) set of keyworded parameters. These are considered to be a set of parameters to be used in addition to some other keyworded set of parameters (e.g. an LDM set of parameters) which contains parameters such as the number of packs and plates, symmetry, crystal to image distances and spindle angles etc. (Values of such parameters will be passed to the LSM using a routine such as LSM_PARSETUP, again prior to using the other sets of LSM routines)

 
Fortran call:
 
      SUBROUTINE LSM_KEYSETUP (KDX)

 
Parameters:
 
 KDX         i (R)   The index of the keyword set to which the LSM
                     keyworded scaling parameters are to be added)

3.2.3 Set up other LSM parameters - LSM_PARSETUP

This routine (or one of its alternatives) needs to be called to set up the parameters required by the LSM routines in addition to those defined within the LSM parameter set itself. Remember to call this routine again if any of the previously passed parameter values have changed.

 
Fortran call:
 
      SUBROUTINE LSM_PARSETUP (NPACK, NPLATES, SPIN, CTF, IDIM, CELL)

 
Parameters:
 
 NPACK       i (R)   Number of packs
 NPLATES()   i (R)   Number of plates/pack for each pack
 SPIN()      r (R)   'spindle' value for each pack (cf LDM parameters)
 CTF()       r (R)   'ctof' value for each plate and pack -
                     dimensioned CTOF(IDIM, *) - IDIM must be at
                     least NPACK. First index packs, 2'nd index plates
 IDIM        i (R)   First dimension of CTF array
 CELL(6)     r (R)   Cell parameters A, B, C, ALPHA, BETA, GAMMA

3.2.4 Select absorption option - LSM_ABSOPT

This routine is used to select the absorption correction option. The options are to model eitherthe gerneral path length, pg, or a normalised absorption scaling factor. It must be called prior to carrying out any LSM scaling or refinement.

 
Fortran call:
 
      SUBROUTINE LSM_ABSOPT (IOPT)

 
Parameters:
 
 IOPT      i (R)   Flag =1 model absorption general path length (pg)
                        =2 model normalised absorption scaling factor

3.3 COPY KDM STORED LSM DATA TO/FROM INTERNAL SCALING ARRAYS

3.3.1 Introduction

A routine is available to copy the LSM data as stored by the keyword handling routines to and from a set of internal scaling arrays (SCP) which are used to provide temporary storage during a refinement and to provide efficient access during scaling.

The following routines are available:

Copy LSM parameters to/from internal storage - LSM_KDMCOPY

3.3.2 Copy LSM parameters to/from internal storage - LSM_KDMCOPY

This routine is used to copy the current values of the LSM parameters as held in the associated KDM arrays to or from the internal scaling arrays (SCP) used internally by the scaling and refinement functions of the LSM set of routines.

 
Fortran call:
 
      SUBROUTINE LSM_KDMCOPY (IOPT, IERR, ERRSTR)

 
Parameters:
 
 IOPT        i (R)   Flag =1 copy from KDM to internal scaling arrays
                             (e.g. prior to using any scaling functions)
                          =2 copy from internal scaling arrays to KDM
                             (e.g. after refining any scaling parameters)
 IERR        i (W)   Error flag = 0 OK
                                = 1 Error
 ERRSTR      c (W)   Error string if IERR is non-zero

3.4 SELECT AND FIND REFLECTION SETS

3.4.1 Introduction

These are a series of routines to set which classes of singles reflections are to be retrieved from a Laue Integrated Reflection List (LIRL) for use in LSM parameter refinement or analysis or scaling of the reflection data.

The following routines are available:

Omit packs - LSM_OMIT
Select packs and plates - LSM_SELECT_PKPL
Add packs and plates to selection - LSM_ADD_PKPL
Clear packs and plates from selection - LSM_CLR_PKPL
Select reflection types - LSM_SELECT_SCREFS
Reset to top of LIRL - LSM_TOP_LIRL
Get reflection set from LIRL - LSM_NEXT_REFLN
Get LIRL reflection index- LSM_INDX
Get scaling factor for a reflection - LSM_SCFAC

3.4.2 Omit packs - LSM_OMIT

This routine is used to omit selected packs from the scaling process. The reflections from such packs will not be used in determining or refining any scaling parameters and will not be included in any R-factor analyses done using the supplied LSM routines. It is intended to provide a simple means of excluding poor packs without having to make extensive modifications to the input LSM containing data file. This will normally be called before using routines LSM_SELECT_PKPL (and related routines), LSM_SET_RFLAGS (and related routines) and LSC_RFACTS (and related routines). Such routines will need to be called again if the list of omitted packs is changed. The routine may also be used to clear the omitted packs list. On program startup, there will be no omitted packs

 
Fortran call:
 
      SUBROUTINE LSM_OMIT (NOMIT, IPACKS)

 
Parameters:
 
 NOMIT       i (R)   No. of packs to be omitted (0 clears the
                     omitted packs list)
 IPACKS()    i (R)   If NOMIT > 0 then this array gives a list of
                     the NOMIT packs to be omitted; if NOMIT = 0,
                     a dummy array may be given.

3.4.3 Select packs and plates - LSM_SELECT_PKPL

This routine is used to select the packs and plates for which data are to be retrieved from the LIRL. This must be called prior to using routines such as LSM_NUM_NEXT or LSM_NEXT_REFLN and the LSM service routines LSM_NEXT_REFOBS. After calling this routine, the selection may be modified using LSM_ADD_PKPL or LSM_CLR_PKPL. This routine overrides any previous selections. Remember also to select the required reflection classes using LSM_SELECT_SCREFS. Note that packs defined via LSM_OMIT will always be omitted.

 
Fortran call:
 
      SUBROUTINE LSM_SELECT_PKPL (IPACK, IPLATE)

 
Parameters:
 
 IPACK       i (R)   No. of pack to select (0 = all packs)
 IPLATE      i (R)   No. of plate to select (0 = all plates)

3.4.4 Add packs and plates to selection - LSM_ADD_PKPL

This routine is used to add further packs/plates to the selection made by LSM_SELECT_PKPL. Note that packs defined via LSM_OMIT will always be omitted.

 
Fortran call:
 
      SUBROUTINE LSM_ADD_PKPL (IPACK, IPLATE)

 
Parameters:
 
 IPACK       i (R)   No. of pack to add to the current packs/plates
                     selection (0 = all packs)
 IPLATE      i (R)   No. of plate to add to the current packs/plates
                     selection (0 = all plates)

3.4.5 Clear packs and plates from selection - LSM_CLR_PKPL

This routine is used to clear packs/plates from the selection made by LSM_SELECT_PKPL.

 
Fortran call:
 
      SUBROUTINE LSM_CLR_PKPL (IPACK, IPLATE)

 
Parameters:
 
 IPACK       i (R)   No. of pack to clear from the current packs/plates
                     selection (0 = all packs)
 IPLATE      i (R)   No. of plate to clear from the current packs/plates
                     selection (0 = all plates)

3.4.6 Select reflection types - LSM_SELECT_SCREFS

This routine is used to select the types of scaleable reflection that are to be retrieved from a Laue Integrated Reflections List (LIRL). This must be called prior to using routines such as LSM_NUM_NEXT or LSM_NEXT_REFLN and the LSM service routines LSM_NEXT_REFOBS. Any reflections which are flagged in the LIRL as not measured, bad or outliers will be omitted and any reflections, for which sclaing parameters lie outside the ranges defined, will also be omitted on retrieval. Remember also to select the required packs/plates using LSM_SELECT_PKPL and associated routines.

 
Fortran call:
 
      SUBROUTINE LSM_SELECT_SCREFS (SIGN_SEP, REFERENCE, SIGMA_CUT,
     +                              SPOV, OVLD)

 
Parameters:
 
 SIGN_SEP    l (R)   If .true. the I+ and I- measurements will be returned
                     as separate reflection sets; if .false. all symmetry
                     equivalents bot I+ and I- will be returned together.
 REFERENCE   l (R)   If .true. then only reflections which have a
                     reference intensity stored will be returned;
                     if .false., reflections will be returned whether
                     or not a reference intensity is present.
 SIGMA_CUT   r (R)   Omit reflections for which the intensity I is
                     less than SIGMA_CUT*sig(I).
 SPOV        l (R)   Flag = .true.  include spatially overlapped
                                    reflections which have been
                                    integrated,
                          = .false. do not.
 OVLD        l (R)   Flag = .true.  include intensity overloads,
                          = .false. do not.

3.4.7 Reset to top of LIRL - LSM_TOP_LIRL

Prepare for LIRL access via LSM routines and reset the current retrieval position in the LIRL to the start of the list. Must be called before calling routines such LSM_NEXT_REFLN, LSM_NUM_NEXT, LSM_SCFAC and the LSM service routine LSM_NEXT_REFOBS and whenever the list needs to be re-read using these routines. Note that the routine sets various internal flags and calculates various intermediate values used in the scaling functions if any parameters etc. have been changed which could affect these.

 
Fortran call:
 
      SUBROUTINE LSM_TOP_LIRL (LINDX, IERR)

 
Parameters:
 
 LINDX       i (R)   The index of the Laue Integrated Reflections List
 IERR        i (W)   Error flag =0 OK
                                =1 invalid LINDX or no spots present
                                =2 Error in sorting data
                                =3 Error from LSM_KDMCOPY

3.4.8 Get reflection set from LIRL - LSM_NEXT_REFLN

Gets the next singles reflection set from the LIRL. The reflection set includes only those reflections of the selected packs and plates (LSM_SELECT_PKPL, LSM_ADD_PKPL, LSM_CLR_PKPL) and classes (LSM_SELECT_SCREFS). The function returns the number of individual reflections in the set or -1 when the end of the list is reached. The LIRL indices of the individual reflections in the set can be obtained using the supplied function LSM_INDX and using this the reflection details can be retrieved using the normal LIRL set of routines.

 
Fortran call:
 
      INTEGER FUNCTION LSM_NEXT_REFLN (IERR)

 
Parameters:
 

 IERR        i (R)   Error flag =0 OK, =1 error (markup_required flag
                     or select_required flag found to be set)

        Returns >=1   the number of reflections in the set
                 -1   when the end of the list is reached

3.4.9 Get LIRL reflection index- LSM_INDX

Gets the LIRL index of a reflection in the latest set of reflections returned by the routine LSM_NEXT_REFLN. The index may then be used to access the individual reflection data from the LIRL next singles reflection set from the LIRL using the normal LIRL set of routines.

 
Fortran call:
 
      INTEGER FUNCTION LSM_INDX (IR)

 
Parameters:
 
 IR       i (R)   The reflection number within the range of 1 to the
                  value returned by the last call to LSM_NEXT_REFLN

            Returns the index number for the reflection in the LIRL

3.4.10 Get scaling factor for a reflection - LSM_SCFAC

Gets the required intensity scaling factor for a given reflection intensity of a reflection in the LIRL. Note that the current values of the scaling parameters must have been copied to the internal scaling arrays (using LSM_KDMCOPY) before using this routine and the routine LSM_TOP_LIRL must also have been called. The reflection list accessed is that selected when LSM_TOP_LIRL was called. **Note** Remember to declare this as a REAL function wherever used.

 
Fortran call:
 
      REAL FUNCTION LSM_SCFAC (IREF, IERR)

 
Parameters:
 
 IREF        i (R)   The reflection index within the LIRL
 IERR        i (W)   Error flag =0     OK
                                =1     Cannot get scaling factor
                                =-1    'markup_required' flag found to
                                       be set
                                =-100  LINDX is invalid.

3.5 LSM REFINEMENT ROUTINES

3.5.1 Introduction

These routines are used to set up the list of LSM parameters which are to be refined and to carry out the refinement of such parameters.

The following routines are available:

Set LSM parameter refinement flags - LSM_SET_RFLAGS
Add a LSM parameter refinement flag - LSM_ADD_RFLAG
Clear a LSM parameter refinement flag - LSM_CLR_RFLAG
General LSM refinement routine - LSM_REFINE
Refine local absorption correction - LSM_ABSCOR_RFN

3.5.2 Set LSM parameter refinement flags - LSM_SET_RFLAGS

This routine sets which parameters are to be refined using the next call to the refinement routine LSM_REFINE. For special cases it may also be necessary to call the associated routines LSM_ADD_RFLAG and LSM_CLR_RFLAG may to 'fine tune' the list of parameters set by LSM_SET_RFLAGS. Plate scaling factors for the top plate of a pack are ignored and the pack scale and temperature factors for pack 1 are never refined. Note that parameters based on packs defined via LSM_OMIT will always be omitted.

 
Fortran call:
 
      SUBROUTINE  LSM_SET_RFLAGS (IPLATE_SC1, IPACK_SC1,
     +            IPACK_BFAC1, NORM1, ABSCORGLOB1, ABSCORLOC1, REF_SC1,
     +            REF_BFAC1)

 
Parameters:
 
 IPLATE_SC1   i (R)   Flag >0  Refine plate scaling parameters for
                               plate IPLATE_SC (for all packs).
                           =0  Refine plate scaling parameters for all
                               plates with valid data present in LIRL.
                               (for all packs)
                           =-1 Do not refine plate scaling parameters.
 IPACK_SC1    i (R)   Flag >0  Refine pack scaling factor for pack
                               IPACK_SC (must not be pack 1).
                           =0  Refine pack scaling factors for all
                               packs (except pack 1) with valid data
                               present in LIRL.
                           =-1 Do not refine pack scale factors.
 IPACK_BFAC1  i (R)   Flag >0  Refine pack temperature factor for pack
                               IPACK_SC (must not be pack 1),
                           =0  Refine pack temperature factors for all
                               packs (except pack 1) with valid data
                               present in LIRL.
                           =-1 Do not refine pack temperature factors.
 NORM1        l (R)   Flag =.true.  Refine normalisation curves for all
                                    defined ranges.
                           =.false. Do not refine normalisation curves.
 ABSCORGLOB1  l (R)   Flag =.true.  Refine global absorption correction.
                           =.false. Do not refine absorption correction.
 ABSCORLOC1   l (R)   Flag =.true.  Refine local absorption correction.
                           =.false. Do not refine local absorption
 REF_SC1      l (R)   Flag =.true.  Refine scale factor to reference
                                    data.
                           =.false. Do not refine scale factor to
                                    reference data.
 REF_BFAC1    l (R)   Flag =.true.  Refine temperature factor to reference
                                    data.
                                    correction.
                           =.false. Do not refine temperature factor to
                                    reference data.

3.5.3 Add a LSM parameter refinement flag - LSM_ADD_RFLAG

This routine can be used to add a further parameter to the list of scaling parameters to refine set up by the routine LSM_SET_RFLAGS. Note that parameters based on packs defined via LSM_OMIT will always be omitted.

 
Fortran call:
 
      SUBROUTINE  LSM_ADD_RFLAG (ITYP, IPACK, IPLATE, IRANGE)

 
Parameters:
 
 ITYP        i (R)   Parameter type =1 Plate scaling parameters
                                    =2 Pack scale factor
                                    =3 Pack temperature factor
                                    =4 Normalisation curve
 IPACK       i (R)   Pack number (ignored if ITYP=4)
 IPLATE      i (R)   Plate number >1 (for ITYP=1 only)
 IRANGE      i (R)   Range for normalisation curve (for ITYP=4 only)

3.5.4 Clear a LSM parameter refinement flag - LSM_CLR_RFLAG

This routine can be used to clear a parameter from the list of scaling parameters to refine set up by the routine LSM_SET_RFLAGS

 
Fortran call:
 
      SUBROUTINE  LSM_CLR_RFLAG (ITYP, IPACK, IPLATE, IRANGE)

 
Parameters:
 
 ITYP        i (R)   Parameter type =1 Plate scaling parameters
                                    =2 Pack scale factor
                                    =3 Pack temperature factor
                                    =4 Normalisation curve
 IPACK       i (R)   Pack number (ignored if ITYP=4)
 IPLATE      i (R)   Plate number >1 (for ITYP=1 only)
 IRANGE      i (R)   Range for normalisation curve (for ITYP=4 only)

3.5.5 General LSM refinement routine - LSM_REFINE

This routine allows for a general refinement of any selection of the LSM scaling parameters including the global (but not local) absorption surface. The parameters to be refined by the current call to the routine are set via LSM_SET_RFLAGS (and LSM_ADD_RFLAG, LSM_CLR_RFLAG if required) which must be called prior to calling LSR_REFINE. The classes of data to be used must also be set up prior to calling LSM_REFINE by calls to LSM_SELECT_PKPL and LSM_SELECT_SCREFS.

 
Fortran call:
 
      SUBROUTINE  LSM_REFINE (LINDX, REFERENCE, IRFTYP, TUNE, FMIN,
     +                        IERR, MESSAGE)

 
Parameters:
 
 LINDX       i (R)   The index of the Laue Integrated Reflections List
 REFERENCE   l (R)   Flag = .true.  Refine against reference data -
                                    cf LAUESCALE.
                                    (Must have called LSM_SELECT_SCREFS
                                     with REFERENCE = .true.)
             l            = .false. Refine against current scaled mean
                                    intensities (internal scaling - cf
                                    LAUENORM.
 IRFTYP      i (R)   Refinement routine type =1 Use LSQMIN
                                             =2 Use LSQMQL
 TUNE()      r (R)   Tuning parameters specific to the refinement type
                     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) = tolerance (ACC)
                                 TUNE(2) = step size (H)
 FMIN        r (W)   The refined function value (sum of squares)
 IERR        i (W)   Error flag = 0 OK
                                =-1 Too little work spce for LSQMIN - 
                                    try LSQMQL instead
                                = 1 Too little work space for LSQMQL
 MESSAGE     c (W)   Message string from refinement (up to 80 chars)

3.5.6 Refine local absorption correction - LSM_ABSCOR_RFN

This routine allows for the refinement of the local absorption correction parameters for a pack. The classes of data to be used must be set up prior to calling LSM_ABSCOR_RFN by calls to LSM_SELECT_PKPL and LSM_SELECT_SCREFS.

 
Fortran call:
 
      SUBROUTINE  LSM_ABSCOR_RFN (LINDX, IPACK, REFERENCE, IRFTYP, TUNE,
     +                            FMIN, IERR, MESSAGE)

 
Parameters:
 
 LINDX       i (R)   The index of the Laue Integrated Reflections List
 IPACK       i (R)   The pack number of the pack for which the local
                     absorption correction parameters are to be refined.
 REFERENCE   l (R)   Flag = .true.  Refine against reference data -
                                    cf LAUESCALE.
                                    (Must have called LSM_SELECT_SCREFS
                                     with REFERENCE = .true.)
             l            = .false. Refine against current scaled mean
                                    intensities (internal scaling - cf
                                    LAUENORM.
 IRFTYP      i (R)   Refinement routine type =1 Use LSQMIN
                                             =2 Use LSQMQL
 TUNE()      r (R)   Tuning parameters specific to the refinement type
                     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) = tolerance (ACC)
                                 TUNE(2) = step size (H)
 FMIN        r (W)   The refined function value (sum of squares)
 IERR        i (W)   Error flag = 0 OK
                                =-1 Too little work spce for LSQMIN - 
                                    try LSQMQL instead
                                = 1 Too little work space for LSQMQL
 MESSAGE     c (W)   Message string from refinement (up to 80 chars)

3.6 MULTIPLES DECONVOLUTION

3.6.1 Introduction

These are routines for retrieving the reflections makrked as multiples from the LIRL-list for multiples deconvolution. The deconvoluted multiples are then added with scaled intensities to the LIRL-reflection list

The following routines are available:

Multiples deconvolutions LSM_MULTIPLES_DECONV
Reset to top of LIRL - LSM_TOP_MULTS_LIRL

3.6.2 Multiples deconvolutions LSM_MULTIPLES_DECONV

This routine deconvolutes reflections marked as multiples (energy overlapps) and adds their scaled(!) intensities to the LIRL used. The wavelength will be stored as 0.0 and the multiples flag with be set to MULT=0 to identify deconvoluted multiples when needed.

 
Fortran call:
 

      SUBROUTINE LSM_MULTIPLES_DECONV (LINDX, TUNE,  
     +                   IRFTYP, NUMOUT, IERR, MESSAGE)

 
Parameters:
 
 LINDX     i (R)     The index of the Laue Integrated Reflections List 
 TUNE()    r (R)     Tuning parameters specific to the refinement type
                     If LSQMQL   TUNE(1) = tolerance (ACC)
                                 TUNE(2) = step size (H)
 IRFTYP    i (R)     Refinement routine type =1 Use LSQMIN
                                                  =2 Use LSQMQL
 NUMOUT()  i (W)     Array containing various details of the deconvolution
 IERR      i (W)     Error flag = 0 OK
                                = 1 Error
 MESSAGE   c (W)     Error message if IERR is non-zero

3.6.3 Reset to top of LIRL - LSM_TOP_MULTS_LIRL

 
Fortran call:
 
      SUBROUTINE LSM_TOP_MULTS_LIRL (LINDX, SIGMA_CUT,
     +                              SPOV, OVLD, IERR)

 
Parameters:
 
 LINDX       i (R)   The index of the Laue Integrated Reflections List
 SIGMA_CUT   r (R)   Omit reflections for which the intensity I is
                     less than SIGMA_CUT*sig(I).
 SPOV        l (R)   Flag = .true.  include spatially overlapped
                                    reflections which have been
                                    integrated,
                          = .false. do not.
 OVLD        l (R)   Flag = .true.  include intensity overloads,
                          = .false. do not.
 IERR        i (W)   Error flag =0 OK
                                =1 invalid LINDX or no spots present
                                =2 Error in sorting data
                                =3 Error from LSM_KDMCOPY

3.7 MISCELLANEOUS LSM ROUTINES

3.7.1 Introduction

These are a miscellaneous set of routines to be used in conjunction with the Laue Scaling Module (LSM).

The following routines are available:

Return maximum numbers of plates and packs - LSM_MAXPKPL
Set up other LSM parameters - LSM_PARSETUP_LDM

3.7.2 Return maximum numbers of plates and packs - LSM_MAXPKPL

This routine returns the maximum number of packs and plates for which the Laue Scaling Module is currently set up.

 
Fortran call:
 
      SUBROUTINE  LSM_MAXPKPL (MAXPK, MAXPL)

 
Parameters:
 
 MAXPK       i (W)   The maximum number of packs defined for the LSM
 MAXPL       i (W)   The maximum number of plates defined for the LSM

3.7.3 Set up other LSM parameters - LSM_PARSETUP_LDM

This routine may be used instead of LSM_PARSETUP if the program using the LSM is based on an LDM file from which the required parameter values are to be taken. Remember to call this routine again if any of the relevant LDM parameter values may have changed.

 
Fortran call:
 
      SUBROUTINE LSM_PARSETUP_LDM (IERR)

 
Parameters:
 
 IERR      i (W)   Error flag =0 OK,
                              =1 Number of packs is zero
                              =2 A zero CTOF value found

3.8 SETTING UP THE LAUE SCALING PARAMETERS LSP

3.8.1 Introduction

A routine is provided to defines a set of Laue Scaling Parameters (LSP) which together with the Laue Scaling Module (LSM) parameters (and SYMM parameters) form a complete set of parameters for use in a standalone Laue scaling program. It makes use of the Keyword Data Module (KDM) for defining and handling the keyworded data.

The following routines are available:

Set up LSP Parameters - LSM_SETLSP

3.8.2 Set up LSP Parameters - LSM_SETLSP

This routine defines a set of Laue scaling parameters which together with the Laue Scaling Module (LSM) parameters (and SYMM parameters) form a complete set of parameters for use in a standalone Laue scaling, normalisation and absorption correction program.

 
Fortran call:
 
      SUBROUTINE LSM_SETLSP (KDX)

 
Parameters:
 
 KDX       i (W)   Returns the index of the keyword set of LSP parameters

3.9 LSP BASED CONVENIENCE ROUTINES

3.9.1 Introduction

These are a set of routines used to call various Laue Scaling Module (LSM) routines with parameters derived internally from the Laue Scaling Parameter (LSP) set of keywords.

The following routines are available:

Set up other LSM parameters - LSM_PARSETUP_LSP
Select absorption option - LSM_ABSOPT_LSP
Select reflection types - LSM_SELECT_SCREFS_LSP
Omit packs from processing - LSM_OMIT_LSP

3.9.2 Set up other LSM parameters - LSM_PARSETUP_LSP

This routine may be used instead of LSM_PARSETUP if the program using the LSM is based on an LSP keyworded file from which the required parameter values are to be taken. Remember to call this routine again if any of the relevant LSP parameter values may have changed.

 
Fortran call:
 
      SUBROUTINE LSM_PARSETUP_LSP (KDX, IERR, ERRSTR)

 
Parameters:
 
 KDX       i (R)   The index of the LSP keyworded parameter set.
 IERR      i (W)   Error flag = 0 OK
                              = 1 Error
 ERRSTR    c (W)   Error string if IERR is non-zero (max 80 characters)

3.9.3 Select absorption option - LSM_ABSOPT_LSP

This routine calls LSM_ABSOPT with its parameter derived from the LSP parameter set.

 
Fortran call:
 
      SUBROUTINE LSM_ABSOPT_LSP

 
Parameters:
 
 none

3.9.4 Select reflection types - LSM_SELECT_SCREFS_LSP

This routine calls LSM_SELECT_SCREFS with its parameters derived from the LSP parameter set.

 
Fortran call:
 
      SUBROUTINE LSM_SELECT_SCREFS_LSP (IERR, REFERENCE, ERRSTR)

 
Parameters:
 
 IERR      i (W)   Error flag = 0 OK
                              = 1 Error
 REFERENCE l (R)   If .true. then only reflections which have a
                   reference intensity stored will be returned;
                   if .false., reflections will be returned whether
                   or not a reference intensity is present.
 ERRSTR    c (W)   Error string if IERR is non-zero (max 80 characters)

3.9.5 Omit packs from processing - LSM_OMIT_LSP

This routine is equivalent to a call to LSM_OMIT with its parameter derived from the LSP parameter set.

 
Fortran call:
 
      SUBROUTINE  LSM_OMIT_LSP (IERR, ERRSTR)

 
Parameters:
 
 IERR      i (W)   Error flag = 0 OK
                              = 1 Error
 ERRSTR    c (W)   Error string if IERR is non-zero (max 80 characters)

3.10 ANALYSING THE INTENSITY STATISTICS AFTER SCALING

3.10.1 Introduction

Routines are available to collect R-factor statistics data and routines are available to print the gathered information to a Fortran output channel or to return it for alternative use e.g. within a windows based program.

The following routines are available:

Prepares graphic windows for statistics output - LSC_GRAPHSETUP
Calculates and outputs statistical data - LSC_ANALYSES
Refines reference set scale factors - LSC_SCALESTAT_OUT
Output of reference set scaling results - LSC_HIST
Graphical output of scaling results - LSC_MENU1
Graphical output of scaling results - LSC_MENU1ABS
Graphical output of scaling results - LSC_MENU2
Graphical output of scaling results - LSC_MENU2ABS
Graphical output of scaling results - LSC_MENU3
Graphical output of scaling results - LSC_MENU3ABS
Get R-factor tables data - LSC_RFACTS_LSP
Output of RSCALE of multiples vs. reference data - LSC_MULT_ANALOG
Outputs mtz- and/or shelx-files - LSC_FILE_OUTPUT

3.10.2 Prepares graphic windows for statistics output - LSC_GRAPHSETUP

This routines sets the size and layout for the graphics output windows and menus.

 
Fortran call:
 

      SUBROUTINE LSC_GRAPHSETUP (IERR, MESSAGE)

 
Parameters:
 
 IERR    i  (W)   Error flag = 0 OK
                             = 1 Error
 MESSAGE c  (W)   Error message if IERR = 1

3.10.3 Calculates and outputs statistical data - LSC_ANALYSES

This routine calculates and prepares various statistical graphs and marks reflections as outliers according to the input cutoff criteria.

 
Fortran call:
 

      SUBROUTINE LSC_ANALYSES (LINDX, REFERENCE, IFL1, IFL2, 
     +                        EXOUT, CUTOFF)

 
Parameters:
 

  LINDX     i  (R)    The index of the Laue Integrated Reflections List
  REFERENCE l  (R)    If .true. then only reflections which have a
                      reference intensity stored will be returned;
                      if .false., reflections will be returned whether
                      or not a reference intensity is present.
  IFL1,IFL2 i  (R)    Output flags
                      IFL1 = 0, IFL2 = 0
                      no winows output
                      IFL1 = 1, IFL2 = 1
                      internal refinement, no refset
                      IFL1 = -1, IFL2 = 1
                      external refinement, refset
                      IFL1 = 1, IFL2 = -1
                      internal refinement, refset scaling
  CUTOFF    r  (R)    Outlier cutoff
  EXOUT     l  (R)    Outlier exclusion flag (if .true. then exclude outliers)

3.10.4 Refines reference set scale factors - LSC_SCALESTAT_OUT

This subroutine refines the reference scale factor if a reference set is present and if the scale factors haven't been refined at that point. It calls LSC_REFSET_ANALYSES to output statistical tables of the scaling results to the log-file

 
Fortran call:
 
      SUBROUTINE LSC_SCALESTAT_OUT (MINDX, EXOUT, CUTOFF, IRFTYP, 
     +                         TUNE, IUN)

 
Parameters:
 
MINDX      i (R)    The index of the Laue Integrated Reflections List     
CUTOFF     r (R)    Outlier cutoff
EXOUT      l (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers
IRFTYP     i (R)    Refinement routine type =1 Use LSQMIN
                                            =2 Use LSQMQL
TUNE()     r (R)    Tuning parameters specific to the refinement type
                          If LSQMQL   TUNE(1) = tolerance (ACC)
                                      TUNE(2) = step size (H)
IUN        i (R)    Output number for log-file

3.10.5 Output of reference set scaling results - LSC_HIST

This routine is called by LSC_HIST_RES, LSC_HIST_INT, LSC_HIST_THETA, and LSC_HIST_LAMBDA and outputs histogramms of the reference set scaling statistics prpared by those calling routines

 
Fortran call:
 

      SUBROUTINE LSC_HIST (IOPT, OUTPUT, NUMBINS, BIN_WIDTH, 
     +                      VAL_MIN, VAL_MAX, RBIN)

 
Parameters:
 
 IOPT      i   (R)  Option flag =1 lambda, =2 resolution, 
                              =3 intensity, = 4 theta
 OUTPUT    i   (R)  Option flag =1 no. of relections per bin vs IOPT
                         flag =2 mean IL/IS ratio per bin vs IOPT
                         flag =3 mean IL per bin vs IOPT
                         flag =4 mean IS per bin vs IOPT
                         flag =5 R-factor per bin vs IOPT 
                         flag =6 log(IL/IS) per bin vs resolution 
 NUMBINS   i   (R)  Number of bins
 BIN_WIDTH r   (R)  Bin width
 VAL_MIN   r   (R)  Minimum soft limits value
 VAL_MAX   r   (R)  Maximum soft limits value
 RBIN()    r   (R)  Significant/Measured intensity ratios for NUMBINS bins

3.10.6 Graphical output of scaling results - LSC_MENU1

This subroutine outputs statistics after internal scaling when no reference data set is present and no absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU1 (MINDX, EXOUT, CUTOFF)

 
Parameters:
 
MINDX   i    (R)    The index of the Laue Integrated Reflections List     
CUTOFF  r    (R)    Outlier cutoff
EXOUT   l    (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers

3.10.7 Graphical output of scaling results - LSC_MENU1ABS

This subroutine outputs statistics and the abssorption surface after internal scaling when no reference data set is present and an absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU1ABS (MINDX, EXOUT, CUTOFF)

 
Parameters:
 
MINDX   i    (R)    The index of the Laue Integrated Reflections List     
CUTOFF  r    (R)    Outlier cutoff
EXOUT   l    (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers

3.10.8 Graphical output of scaling results - LSC_MENU2

This subroutine outputs statistics after external scaling when no reference data set is present and no absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU2 (MINDX, EXOUT, CUTOFF, MULTDECONV, IUN)

 
Parameters:
 
MINDX      i (R)    The index of the Laue Integrated Reflections List     
CUTOFF     r (R)    Outlier cutoff
EXOUT      l (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers
MULTDECONV l (R)    multiples deconvolution flag
                    .true.  = deconvolute multiples
                    .false. = don't deconvolute multiples
IUN        i  (R)    Output number for log-file

3.10.9 Graphical output of scaling results - LSC_MENU2ABS

This subroutine outputs statistics and the abssorption surface after external scaling when no reference data set is present and an absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU2ABS (MINDX, EXOUT, CUTOFF, MULTDECONV, IUN)

 
Parameters:
 
MINDX      i (R)    The index of the Laue Integrated Reflections List     
CUTOFF     r (R)    Outlier cutoff
EXOUT      l (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers
MULTDECONV l (R)    multiples deconvolution flag
                    .true.  = deconvolute multiples
                    .false. = don't deconvolute multiples
IUN        i (R)    Output number for log-file

3.10.10 Graphical output of scaling results - LSC_MENU3

This subroutine outputs statistics after internal scaling when a reference data set is present and no absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU3 (MINDX, EXOUT, CUTOFF, IRFTYP, 
     +                      TUNE, MULTDECONV, IUN)

 
Parameters:
 
MINDX      i (R)    The index of the Laue Integrated Reflections List     
CUTOFF     r (R)    Outlier cutoff
EXOUT      l (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers
IRFTYP     i (R)    Refinement routine type =1 Use LSQMIN
                                            =2 Use LSQMQL
TUNE()     r (R)    Tuning parameters specific to the refinement type
                          If LSQMQL   TUNE(1) = tolerance (ACC)
                                      TUNE(2) = step size (H)
MULTDECONV l (R)    multiples deconvolution flag
                    .true.  = deconvolute multiples
                    .false. = don't deconvolute multiples
IUN        i (R)    Output number for log-file

3.10.11 Graphical output of scaling results - LSC_MENU3ABS

This subroutine outputs statistics and the abssorption surface after internal scaling when a reference data set is present and an absorption correction has been refined. It is called by the main programm LSCALE.

 
Fortran call:
 
      SUBROUTINE LSC_MENU3ABS (MINDX, EXOUT, CUTOFF, IRFTYP, 
     +                         TUNE, MULTDECONV, IUN)

 
Parameters:
 
MINDX      i (R)    The index of the Laue Integrated Reflections List     
CUTOFF     r (R)    Outlier cutoff
EXOUT      l (R)    Outlier exclusion flag 
                    .true.  = exclude outliers
                    .false. = include outliers
IRFTYP     i (R)    Refinement routine type =1 Use LSQMIN
                                            =2 Use LSQMQL
TUNE()     r (R)    Tuning parameters specific to the refinement type
                          If LSQMQL   TUNE(1) = tolerance (ACC)
                                      TUNE(2) = step size (H)
MULTDECONV l (R)    multiples deconvolution flag
                    .true.  = deconvolute multiples
                    .false. = don't deconvolute multiples
IUN        i (R)    Output number for log-file

3.10.12 Get R-factor tables data - LSC_RFACTS_LSP

Calls LSC_RFACTS with parameters derived from LSP and then calls LSC_RFACTS_OUT with flags derived from LSP.

 
Fortran call:
 
      SUBROUTINE LSC_RFACTS_LSP (LINDX, IUN, PLATEMERGE, IERR)

 
Parameters:
 
 LINDX      i  (R)  Index for LIRL
 IUN        i  (R)  Unit no. for tables output
 IERR       i  (W)  Error flag as returned from LSC_RFACTS
 PLATEMERGE l  (R)  .true.  = Merge plate data prior to statistics
                    .false. = keep all data seperate

3.10.13 Output of RSCALE of multiples vs. reference data - LSC_MULT_ANALOG

This routine writes RSCALE of deconvoluted multiples reflections against the reference set to the log-file.

 
Fortran call:
 

      SUBROUTINE LSC_MULT_ANALOG (LINDX, IUN)

 
Parameters:
 
  LINDX   i  (R)    The index of the Laue Integrated Reflections List
  IUN     i  (R)    Output unit number of log-file

 
Fortran call:
 

      SUBROUTINE LSC_DECONV_LOGOUTPUT(IUN, NUMOUT)

 
Parameters:
 
 IUN      i  (R)   Output unit number of log-file
 NUMOUT() i  (R)   Array containing various details of the deconvolution

3.10.14 Outputs mtz- and/or shelx-files - LSC_FILE_OUTPUT

This routine gets various data output options and criteria and writes scaled reflections merged or unmerged to mtz- and/or shelx-files. It refines the reference scale and temperature factor if a reference data set is present and if they have not been refined so far. If reference intensities are present they will be stored in the mtz.-output files. If multiples reflections have been deconvoluted they will be added to the output files.

 
Fortran call:
 

      SUBROUTINE LSC_FILE_OUTPUT (KDX, MTZ_IDX, MINDX,
     +                            IUNOUT, IUNLOG, REFSET)

 
Parameters:
 

KDX     i    (R)     The index of the keyword set to which the LSM
                     keyworded scaling parameters are to be added)
MTZ_IDX i    (R)     indicates which MTZ file - one index points to 
                     both input and output files 
MINDX   i    (R)     The index of the Laue Integrated Reflections List     
IUNOUT  i    (R)     output unit number for shelx-file
IUNLOG  i    (R)     output unit number for log-file
REFSET  l    (R)    .true. = Reference data set exist
                    .false. = no reference data present

John W. Campbell
CCLRC Daresbury Laboratory
Last update 14 Dec 1998