Generating SQW files

From Horace
Jump to: navigation, search

This page tells you how to generate an SQW file when you have a full dataset already. It also details how to accumulate data files into an SQW file as you go (e.g. during an experiment).

To generate the SQW file neutron data for each individual run needs to be provided in one of two formats: the legacy ASCII format SPE file, together with an ASCII detector parameter file (the PAR file), or their replacements the HDF (hierarchical Data Format) NXSPE file. More details about these files and how to create them can be found here


accumulate_sqw

This is a way of generating data 'on the fly' during an experiment. It saves time by appending new data to an already existing SQW file.

The syntax is as follows:

spe_dir='/home/maps/maps_users/Gruenwald/SPE/';%directory where spe files are found
runno=[19780:19960];%anticipated list of files (we do not need all of them to exist yet)

spe_file=cell(1,numel(runno));
for i=1:numel(runno)
    spe_file{i}=[spe_dir,'map',num2str(runno(i)),'_ei100.spe'];%filename of runs
end

psi=[0:2:180 1:2:179];%list of anticipated scan angles

par_file='/usr/local/mprogs/Libisis/InstrumentFiles/maps/4to1_124.par';%detector parameter file

sqw_file='/home/maps/maps_users/Gruenwald/data_accumulation.sqw';%name of output file

efix=100;%incident energy
emode=1;%indicates direct geometry

alatt=[5.7,5.7,5.7];%lattice parameters
angdeg=[90,90,90];%lattice angles

u=[1,1,0]; v=[0,0,1]; %orientation of sample (u//ki, v perp ki in horizontal plane)

omega=0; dpsi=0; gl=0; gs=0;%offset angles for sample misalignment

accumulate_sqw (spe_file, par_file, sqw_file, efix, emode, alatt, angdeg,...
    u, v, psi, omega, dpsi, gl, gs, <optional input parameters>);

The input parameters are defined as follows:

spe_file is a cell array, each element of which is a string specifying the full file name of the input SPE or NXSPE files (e.g. spe_file{1} = 'C:\data\mer12345.spe').

par_file is a string giving the full file name of the parameter file for the instrument on which the data were taken. This is required for SPE files. For NXSPE files you do not need to specify an instrument parameter file (Provide empty string '' instead), as detector information will be picked up from NXSPE files themselves. If you do specify par_file, the detector info is taken from there and overrides the information contained within the NXSPE files. sqw_file is a string giving the full file name of the sqw output file you wish to generate.

efix is the incident neutron energy for each SPE file. If a single incident energy was used for all runs then this number is a scalar, otherwise it must be a vector with the same number of elements are there are SPE files.

emode is either 1 for direct geometry instruments, or 2 for indirect geometry.

alatt is a vector with 3 elements, specifying the lengths in Angstroms of the crystal's lattice parameters.

angdeg is a vector with 3 elements, specifying the lattice angles in degrees.

u and v are both 3-element vectors. These specify how the crystal's axes were oriented relative to the spectrometer in the setup for which you define psi to be zero. u specifies the lattice vector that is parallel to the incident neutron beam, whilst v is a vector perpendicular to this in the horizontal plane.

psi specifies the angle of the crystal relative to the setup described in the above paragraph (i.e. the angle about the vertical axis through which the sample has been rotated). If a single orientation of the crystal was used for all measurements then this number can be a scalar, otherwise it is a vector. For the case of it use in accumulate_sqw it is a vector listing the expected values of psi that will be used. It is important to get this about right, as it ensures that the underlying reciprocal space grid in the SQW file is big enough to encompass all of the data you plan to collect. If it is not, then you lose all the time-saving and the file has to be generated from scratch!

omega, dpsi, gl, and gs specify the offsets (in degrees of various angles). gl and gs describe the settings of the large and small goniometers. omega is the offset of the axis of the small goniometer with respect to the notional u. Finally dpsi allows you to specify an offset in psi, should you wish. These angle definitions are shown below:

Virtual goniometer angle definitions

The optional input arguments are as follows:

grid_size_in: A scalar or row vector of grid dimensions. The default, if not given or [], is is [50,50,50,50]

urange_in: The range of data grid for output as a 2x4 matrix - [x1_lo,x2_lo,x3_lo,x4_lo;x1_hi,x2_hi,x3_hi,x4_hi]. The default if not given or [] is the smallest hypercuboid that encloses the whole data range.

instrument: A structure or object containing instrument information [scalar or array length nfile]

sample: A structure or object containing sample geometry information [scalar or array length nfile]

'clean': Create the sqw file from fresh. This option deletes existing sqw file (if any) and forces fresh generation of sqw file from the list of data files provided. It is possible to get confused about what data has been included in an sqw file if it is built up slowly over an experiment. Use this option to start afresh.

'replicate': Normally the function forbids an spe file from appearing more than once. This is to trap common typing errors. However, sometimes you might want toto create an sqw file using, for example, just one spe file as the source of data for all crystal orientations in order to construct a background from an empty piece of sample environment. In this case, use the keyword 'replicate' to override the uniqueness check.

gen_sqw

This is the main function you will use to turn the data accumulated in multiple SPE files into a single SQW file that will be used by the rest of the Horace functions. An introduction to its use is given in the getting started section. Here we list simply the format of the input and output arguments, and give a brief description of their meanings.

The essential inputs take the following form:

gen_sqw (spe_file, par_file, sqw_file, efix, emode, alatt, angdeg,...
                                                u, v, psi, omega, dpsi, gl, gs);


There are additional (optional) input and output arguments as with accumulate_sqw:

[tmp_file,grid_size,urange] = gen_sqw (spe_file, par_file, sqw_file, efix, emode, alatt, angdeg,...
                                                u, v, psi, omega, dpsi, gl, gs, grid_size_in, urange_in,'replicate');

grid_size_in is a row vector with 4 elements, each of which specifies the number of blocks of data along each Q/E direction into which the pixels will be grouped in each intermediate tmp files. If this argument is left blank then a default 50x50x50x50 grid is used. This 'coarse graining' is to speed up the process of reading data from file - it does not affect the resolution of your data.

urange_in is a 2x4 matrix which specifies the the upper and lower limits along each Q/E direction. If this is left blank then the program will calculate the range of a hypercuboid that encompasses all of the data along all 4 directions.

grid_size is a vector with 4 elements which specifies the actual grid size required. e.g. if every data point has the same value of Qz then the third element will be 1.

'replicate': Normally the function forbids an spe file from appearing more than once. This is to trap common typing errors. However, sometimes you might want to create an sqw file using, for example, just one spe file as the source of data for all crystal orientations in order to construct a background from an empty piece of sample environment. In this case, use the keyword 'replicate' to override the uniqueness check.

urange gives the range in reciprocal space of the data. If urange_in was specified then this will be the same, but if not then it tells you the calculated range of the 4-dimensional hypercuboid which encompasses all of the data.

Applying symmetry operations to an entire dataset

In the explanation below, we wish to apply symmetrisation to the entire data file. Under the hood, what happens is that the data for each run is symmetrised, and then these symmetrised data are combined to make the sqw file. This avoids the problem of running out of memory when attempting to symmetrise large sections of the unfolded sqw file / object.

To use this functionality, call gen_sqw or accumulate_sqw as above, with the following additional arguments:

gen_sqw (spefile, par_file, sym_sqw_file, efix, emode, alatt, angdeg,...
    u, v, psi, omega, dpsi, gl, gs,'transform_sqw',@(x)(symmetrise_sqw(x,v1,v2,v3)))

or more generally

gen_sqw (spefile, par_file, sym_sqw_file, efix, emode, alatt, angdeg,...
    u, v, psi, omega, dpsi, gl, gs,'transform_sqw',@(x)(user_symmetrisation_routine(x))


The first example above would build a sqw file reflected as in the example for the reflection in memory, but with the transformation applied to the entire dataset. In the second, more general, case the user defined function (in a m-file on the Matlab path) can define multiple symmetrisation operations that are applied sequentially to the entire data. An example is as follows, which folds a cubic system so that all six of the symmetrically equivalent (1,0,0) type positions are folded on to each other:

function wout = user_symmetrisation_routine(win)

wout=symmetrise_sqw(win,[1,1,0],[0,0,1],[0,0,0]);%fold about line (1,1,0) in HK plane
wout=symmetrise_sqw(wout,[-1,1,0],[0,0,1],[0,0,0]);%fold about line (-1,1,0) in HK plane
wout=symmetrise_sqw(wout,[1,0,1],[0,1,0],[0,0,0]);%fold about line (1,0,1) in HL plane
wout=symmetrise_sqw(wout,[1,0,-1],[0,1,0],[0,0,0]);%fold about line (1,0,-1) in HL plane

VERY IMPORTANT NOTE 1: When defining the function to apply the symmetrisation (as above) one can ONLY use symmetrisation operations, given by symmetrise_sqw. Any other transformations may modify the data ranges in unexpected ways, making the resulting transformed sqw file into complete nonsense!

Note 2: when a complex transformation is run on the isiscompute cluster in parallel mode, one may want to increase number of MPI workers to increase gen_sqw speed during symmetrisation (if the cluster load permits that). The current default number of workers is optimal for using the maximal bandwidth of parallel file system. If bigger computations are performed in memory, it could be beneficial to increase number of workers to use more CPU power. This can be done by issuing the following commands:

hc = hor_config
hc.accumulating_process_num = 16

This instructs Horace to use 16 MPI workers instead of the default of 8.