*************************************************************************
**************************************************************************
***************                                        *******************
***************         Documentation for XRAYL        *******************
***************                                        *******************
**************************************************************************
**************************************************************************


  PROGRAM AUTHORS - C. R. Hubbard, B. Morosin & J. M. Stewart.


 ----------------------------------------------------------------------

  XRAYL - A program for producing idealised powder diffraction line 
          profiles from overlapped powder diffraction patterns.
          This program may be used as a preliminary to the program
          CRYSIZ, for computing crystallite size and strain from
          the broadening of powder diffraction lines.

 ----------------------------------------------------------------------


  Please note that the executables of XRAYL itself and of the ancillary
  programs listed at the end of this document can be found in the
  appropriate "/ccp14/operating-system/crysiz" directory.  Numerous
  example input files are available in the current directory.

  Please Note : this file is a condensed version of the full XRAYL
                documentation, which will become available, and which 
                will replace this file, in April 1997.


COMMAND LINES
-------------

The executables of any of the programs referred to in this file can be
invoked simply by typing the program name (eg. "xrayl", "powtes", ...) on
UNIX and PC, or "run xrayl", "run powtes", etc.  on VMS.

                


USING THE PROGRAM XRAYL
-----------------------

The XRAYL program will open and process a number of prepared files and produce
output files in the process.  Each file type is defined by an "extension"
mnemonic following a period.  Before the period, an 11-character code, here
referred to as the <identity>, may be prefixed.  The <identity> code should
be mnemonic of the data set being treated.  The extension codes are fixed
by the program while the identity is chosen by the user.  For some 
computers or operating systems, such as disk operating system (DOS) for a PC,
it may not be possible to use all 11 characters.  In fact, for DOS the limit     
be only four characters.

File Types :

".XIN" ... Program instruction file.  Program may be run interactively to
           supply the information contained in a ".XIN" file, but the
           creation, beforehand, of this file by a local line editor is
           much more productive. 

".DA" .... Raw observed intensity data input files.  Usually, one for reference
           profiles and one for broadened profiles.  Covers a "window" of
           2theta containing up to five reflection profiles.

".XPN" ... Output files containing summary of run suitable for printing.

".XPL" ... Optional output file containing crude line printer plots for
           inspection.

".XEX" ... Optional output file containing raw plot data for use with local
           plotting software.

".IDL" ... Output files containing the separated, idealised output profiles.

".IDM" ... Optional output files like ".IDL" but with least-squares parameters
           displaced by a specified number of standard deviations down from
           the best result.

".IDP" ... Optional output files like ".IDL" but with the parameters 
           displaced up.

".FIT" ... Optional output file containing the refined least-squares parameters
           of fit for each processed profile.


In order to use the program XRAYL, it is usually necessary to have two input
files: one with the reference data and one with the broadened data.  These
files must both scan the same regions of 2theta in "windows".  There may be
up to five unique reflections in eachj window.  The files will be opened if 
they have the designation <identity>.DA, where <identity1> and <identity2>
are the names chosen by the user fir the data sets (eg. "NaClrf.DA" for the
reference pattern and "NaClb1.DA" for the broadened sample 1).  Within these
ASCII files there is a 53-character user-provided title which should be used
to further identofy the sample.

In addition to the data files, information concerning the instructions for the
run must be given.  These may be given interactively or, more conveniently,
by preparation of an <identity>.XIN file.  Whichever method is chosen, the 
options to be specified concern which method of fitting is to be carried out,
the indices and 2theta of each reflection, the plots to be generated, the
extent of the printed details, and the reflections to be placed in the output
".IDL" files.  In the interactive mode, the options are presented to the user
as a set of tedious questions to be answered in turn.  It is crucial to
recognise that the program depends on the values of 2theta given in the
"HKL_2TH_SHP" input line.  The least squares refinement requires a value
within its convergence "circle".  If the values given are too far from the        
profile maximum, or if there is serious overlap with adjacent profiles, the 
program may fail during the refinement.  A reasonable strategy to employ is to
use the reference pattern alone, assuming that it is resolved, to establish
the values of 2theta for each reflection.  Then make a separate run for the
broadened sample, fixing the 2theta value for the broadened reflections at the
refined values of their reference counterparts.  To be successful,
complicated patterns may require two iterations in which the values of 2theta
given in the "HKL_2TH_SHP" lines are reset by the user.  The result of a bad
starting 2theta can be anything from the coalescence of two profiles, to a         
detected problem which produces a diagnostic message, to a divide overflow in the
least-squares routines.  All divisions in the program outside the SLATEC package
of matrix manipulation routines are protected.  Those inside are not.  It may 
also be found that if one function will not refine properly, another will.
If Pearson 7 fails, Gaussian may well work.



FORMAT OF THE ".XIN" FILE
----------------------------

This file, which specifies the calculations to be done and the results to be
displayed, must consist of a series of "free format lines" which are parsed into
the fields separated by blanks.  The lines and the order in which they must be
specified are :

Unit cell parameter line :

"CELL_PARAMET" (one per .XIN file)

Wavelength and general refinement control line :

"WAV_LEN_REFN" (one per .XIN file)

Window instruction lines :

"REGIN_2_THET" (one per window)

Three lines for each reflection in the window :

"HKL_2THT_SHP"
"SIG_PARM_REF"
"NUM_ERR_GENR"

(one set for each reflection in window)

Repeating, if necessary, at least four lines for each subsequent window :

"REGIN_2_THET" (one per subsequent window)

Three lines for each reflection in the window :

"HKL_2THT_SHP"
"SIG_PARM_REF"
"NUM_ERR_GENR"
(one set for each reflection in subsequent window)

One line that marks the end of the whole ".XIN" file :

"REGIN_2_THET" -1



It is important to note that since these input lines are free format, every field
must be given a value; none may be lefty blank.

The "NUM_ERR_GENR" line is used to prepare additional profiles which may be
used to estimate errors in the size and strain parameters determined through
the use of program CRYSIZ. 



FORMAT OF THE ".DA"  FILES
--------------------------

The format of the input ".DA" files read by XRAYL is as shown below.
These files contain, in FORTRAN formatted ASCII, the intensity measurements
from regions of the 2theta "windows", in steps of 2theta taken from the
diffractometer.  
                                                      
RECORD        FORMAT          CONTENTS

1             A53             Title; up to the first 11 characters may be the
                              <identity> used to identify the files of the
                              compound

1             A19             Time/date as bhh:mm:ssbdd/MMM/yy where "b"
                              represents a blank space

2             I4              h index of reflection

2             I4              k index of reflection

2             I4              l index of reflection

2             I4              Number of records of type 3, intensity data,
                              NREC, which must be > 15 and < 1023

2             F10.2           Counting time per intensity point

2             F10.4           Beginning 2theta for intensity measurements

2             F10.4           Ending 2theta for intensity measurements

2             F10.4           2theta step size, lower limit 0.001 degrees

2             F10.6           Wavelength of K-alpha1 used for measurement

3 through     F10.2           Intensity at measured point
2 + NREC



ANCILLARY PROGRAMS TO SUPPORT XRAYL
-----------------------------------

POWCON ..... A utility for converting raw data files to type ".DA"

POWLAP ..... A utility program for generating overlapping line tests
             from input data

POWTES ..... A utility program for generating single Gaussian lines to
             test XRAYL

POWTESTW ... A utility program for generating double lines to test XRAYL

POWWID ..... A utility program to convolute Gaussian data to test CRYSIZ

RDCON ...... A program to convert SCINTAG.RD files to ".DA" files required
             by XRAYL

TAGFOR ..... A utility for sequencing FORTRAN programs in columns 73-80


 ---------------------------------------------------------------------------