Generating SQW files
From Horace
This page tells you how to generate an sqw file when you have a full dataset already, and how to accumulate data files into an sqw file as you go (e.g. during an experiment. It also explains how to convert a single spe file into a tmp file (a low level command).
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);
spe_file is a cell array, each element of which is a string specifying the full file name of the input SPE files (e.g. spe_file{1} = 'C:\data\mer12345.spe'). Note that Horace now also has the capability of reading NXSPE files - a list of these is specified in exactly the same way as for SPE files.
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 must still specify an instrument parameter file, however the data in it are overridden by the information contained within the NXSPE files themselves.
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 with the same number of elements as there are SPE files.
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:
There are additional (optional) input and output arguments:
[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);
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.
tmp_file is a cell array with the same number of elements as there were SPE files. Each element is a string giving the full filename of the TMP file associated with a given SPE/NXSPE file. A TMP file contains the information from a particular SPE file, but with information about the location in reciprocal space of each pixel.
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.
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.
write_spe_to_sqw
This is a lower level command that is used within gen_sqw, however in some circumstances it can be useful to use it instead of gen_sqw. One circumstance in which you might want to do this is when you are generating data "on the fly" whilst you are still accumulating data, in order to get an idea of how the data acquired so far look. The function is used to convert one or more SPE files into TMP files. The syntax is as follows:
[grid_size, urange] = write_spe_to_sqw (spe_file, par_file, sqw_file, efix, emode, alatt, angdeg,...
u, v, psi, omega, dpsi, gl, gs, grid_size_in, urange_in)
The output arguments are optional, and have the same meaning as for gen_sqw, described above. Indeed the inputs are the same as for gen_sqw, however in this case grid_size_in and urange_in are not optional and have to specified. Normally one should use an input grid of [50,50,50,50] unless you have a good reason not to do so.
The input urange_in requires a bit more thought, however. The same input urange_in must be used for all files, otherwise the TMP files that are generated by this function cannot be combined into a single SQW dataset. There are three approaches to take to determine the numbers to use for the input urange.
- Decide on a data range yourself, if you know that you will not be looking at high Q and/or energies, etc.
- Calculate the range for your final dataset. If you know what range of energies or psi you will end up with, then you can use the program calc_sqw_urange (described below) to work out the necessary ranges to encompass all the current data, and all data yet to be taken.
- Calculate the range for a full 360 degree rotation. This will definitely mean that you encompass all possible data, which means that if your plans for the experiment change you will not have to regenerate all of your TMP files. The downside is that you could end up with much larger datasets which mostly contain no signal, which take longer to cut, plot, etc.
accumulate_sqw
This is a way of generating data 'on the fly' during an experiment, avoiding re-generating tmp files that have already been created, and hence saving time.
In order to achieve the time saving, you must first set-up the Horace configuration so that tmp files are not deleted. To do this type:
set(hor_config,'delete_tmp',0);
The use of accumulate_sqw is then as follows:
accumulate_sqw (spe_file, par_file, sqw_file, efix, emode, alatt, angdeg,...
u, v, psi, psi_planned, omega, dpsi, gl, gs)
All of the definitions are the same as for gen_sqw. The only difference is psi_planned. This is a list of psi values in the form of a vector that correspond to the range you plan to cover. e.g. if you plan to go from 0 to 90 degrees in steps of 1 degree, then psi_planned=[0:1:90].
As with gen_sqw, you can specify additional inputs grid_size_in and urange_in, and additional outputs grid_size and urange.
