User guide to
R E S T R A X
Monte Carlo simulations and data fitting for neutron three-axis spectrometers
Authors: ,
1Nuclear Physics Institute ASCR, Řež
2Institute Laue-Langevin, Grenoble
Refer to http://omega.ujf.cas.cz/restrax/ for project details.
Contents
- 1. Introduction
- 2. Quick start
- 3. Installation
- 3.1. Package description
- 3.2. Installation guide
- 4. Commands reference
- 4.1. Command line interpreter
- 4.2. Input/output
- 4.3. Execution commands
- 4.4. Special settings
- 4.5. DATA submenu
- 4.6. FIT submenu
- 4.7. PLOT submenu
- 5. Input data
- 5.1. Input parameters
- 5.2. Data format
- 5.3. TAS configuration file
- 6. Data fitting
- 6.1. Requirements
- 6.2. Initial steps
- 6.3. Simulation and fitting
- 7. S(Q,E) modules
- 7.1. Requirements
- 7.2. Compiling
- 7.3. Implementation of S(Q,E)
- 8. Theoretical background
- 8.1. Resolution functions
- 8.2. Convolution in (Q,E) space
Monte Carlo simulations and data fitting for neutron three-axis spectrometers
Authors:
,
Refer to http://omega.ujf.cas.cz/restrax/ for project details.
1. Introduction
RESTRAX is a tool for simulating TAS resolution functions and data fitting. The program includes both a high-speed analytical (Gaussian) convolution algorithm and a Monte Carlo ray-tracing code providing enhanced accuracy in description of most of the spectrometer components. The non-linear least-squares fitting routine is available with several scattering function models, which may be used either directly or as templates for other models created by users and called by Restrax as a dynamically linked run-time module. Graphical output permits visualisation of resolution functions in an arbitrary projection in the (Q,ω) space, plotting both simulated and experimental data and mapping S(Q,ω) as 2-dimensional sections in reciprocal space.
Typical tasks where RESTRAX may help:
- Planning an experiment
- RESTRAX permits to find optimum instrument configuration with respect to required size and orientation of the resolution function.
- Simulating data for a given scattering model
- Smearing due to instrumental resolution and relative intensities of diverse signal components can be assessed by simulation of experimental data with an expected scattering law.
- Analysis of experimental data
- The data fitting with RESTRAX is particularly useful in two cases: (1) when the Gaussian approximation of the resolution function is not sufficient and/or (2) when a complex scattering model is needed, which cannot be expressed as a simple analytical formula. With RESTRAX, you can also simultaneously fit multiple datasets with a single set of model parameters.
Note: This page does not refer to another modification of RESTRAX called SIMRES - an enhanced ray-tracing code useful for simulation of newly designed or upgraded instruments and optimisation of their configuration. Please consult the http://omega.ujf.cas.cz/restrax/ for more information and downloads.
2. Quick start
This section is a brief guide describing how to start simulations with RESTRAX. It assumes the program is already installed on your system (see description [chap. 3.]). If you need to compile/install the program first, see the installation guide.
Step 1
To start your work, just call restrax
from a terminal window:
% restrax
or try this if it doesn't work.
In the first menu, select the EXCI module (definition of the scattering function S(Q,E)) to be loaded initially. You can reload another module at runtime by the command EXCI. It is therefore good idea to start just with the default one (damped harmonic oscillators):
Start with model :
------------------
1 ... Damped oscillators
2 ... Damped oscillators with an adjustable dispersion gradient
3 ... Bond charge model (phonons in Si, Ge, ...)
4 ... Diffuse incommensurate fluctuations
In the second menu, the starting script offers a choice from available instrument configurations. There is a set of
demo configurations available in the default installation. Select any one. The demo
sessions would start with
a tutorial-like session from a job file, default
just starts the interactive mode. You can also switch to the
interactive mode from a job file execution by typing <Q><ENTER>.
Select session/instrument:
------------------------------------------------------------------
1 ... default
2 ... demo, data fitting (damped oscillators)
3 ... demo, phonons in Si
4 ... demo, flatcone multianalyzer, diffuse satellites
5 ... demo, simultaneus fitting of multiple data (damped oscillators)
RESTRAX then starts with initial prompts as follows. Press ENTER to accept offered answers:
Configurations will be searched in /usr/local/restrax/demo/osc
Path to data files [/usr/local/restrax/demo/osc] :
Configuration updated: restrax46.cfg
Name of a parameter or data file [303] :
ResTrax>
?
to list available commands, or see the commmands reference page.Alternatively, if you have chosen a demo, RESTRAX would guide you through the selected session. Look in the corresponding jobfile to learn the commands used.
Step 2
In order to get correct results, the TAS configuration file [chap. 5.3.] has to describe your instrument correctly. Typically, there are several files for each instrument available, which correspond to different options (monochromator choice, beam collimation etc.). Try the command LSCFG to list *.cfg files in your search directory and the command CFG to load the required one.
You can also edit the *.cfg file by yourself. Copy any *.cfg file as a template to your current directory. When you call it by CFG, it will have priority over those in remote directories. Try to edit it as a text file (see help [chap. 5.3.]), or using the form on the RESTRAX server. Don't forget to update the configuration by re-loading the file with CFG.
If RESTRAX doesn't start
It is possible that there is a link missing on your workstation from RESTRAX installation directory to a directory listed in your $PATH environment variable, e.g. /usr/local/bin. In such a case, look whether you can see the restrax starting script,
% ls /usr/local/restrax/start
If yes, call this script directly and/or make an alias to it in your .profile (or .login) file so that you can call it with a simple name:
% alias restrax /usr/local/restrax/start
% restrax
If you cannot find restrax on your system, ask your system administrator or install it locally under your account (see the installation guide [chap. 3.2.]).
3. Installation
- 3.1. Package description
- 3.1.1. Customized options
- 3.1.2. Search directories
- 3.1.3. PGPLOT
- 3.2. Installation guide
- 3.2.1. Compiling
- 3.2.2. Installation
- 3.2.3. Configuration
3.1. Package description
RESTRAX is installed from the compiled package by the script Install
(see the installation guide [chap. 3.2.]), which copies all necessary files to a specified target directory. In following we assume this is /usr/local/restrax
and call it a root directory. RESTRAX can be installed locally or system-wide. In the latter case, there should be a link made from the start
script to a directory listed in the $PATH variable so that you can call it simply by typing restrax
from your terminal window, e.g.
ln -sf /usr/local/restrax/start /usr/local/bin/restrax
Alternatively, you can use an alias:
alias restrax /usr/local/restrax/start
Actually, there are two starting scripts:
start
— provides initial menus and callsrestrax_run
with appropriate options.restrax_run
— sets all necessary environment settings and options so that no environment settings on the users' side are needed.
3.1.1. Customized options
Each TAS instrument should have a subdirectory under the installation root with corresponding configuration files, lookup tables etc. The starting script sets the search path for configurations to the selected instrument. There is the file restrax.ini
in each of these directories, where you can specify some start-up options — load a configuration or parameter file, select the EXCI module or start a job file (see example). As usual in RESTRAX, a restrax.ini
file in the working directory (./
) will have priority over the others. You can use such a local copy of restrax.ini
to customize the start-up behaviour. Moreover, you can make a copy of the start
script and modify it with respect to your needs. In such a way, you would have full control over command line options, initial menus etc.
3.1.2. Search directories
Configuration files (*.cfg, *.res, lookup tables, EXCI module parameters, restrax.ini file, etc.) are searched in several directories in the following order:
- current directory (
./
) - directory selected at the start-up menu (actually passed to RESTRAX as a command line option
-dir=
). It can be also modified by the command CPATH. - The
./setup
subdirectory of the installation root.
Data files are searched in the directory specified at the program start-up (initially set to a value in the restrax.ini file, DATAPATH=pathname
statement). This path can be changed any time by the command PATH.
./lib
subdirectory of the installation root. Source files to the EXCI modules can be found in the subdirectory ./exci
. The search order depends on the sequence in LD_LIBRARY_PATH environment variable. For default RESTRAX installation, this variable defines following search order: - current directory (
./
) ./lib
- <installation root>/lib
- system directories like
/usr/lib
,/lib
etc.
3.1.3. PGPLOT
RESTRAX needs the PGPLOT library.It is either linked with the shared version or with the archive library. Even in the latter case, you
would need some PGPLOT files (graphics servers, fonts) to get graphical output from RESTRAX. The starting script tries to find them in several directories, including any one specified as $PGPLOT_DIR variable or /usr/local/pgplot. To force RESTRAX to use the library from a particular directory, either set it as the $PGPLOT_DIR variable, or edit the restrax_run
script and set the variable $PG.
3.2. Installation guide
Compiling | Installation | Configuration
3.2.1. Compiling
If you are installing binary files, just unpack the distribution and follow instructions in the section Installation.
Requirements
- Source files with RESTRAX (available at the http://omega.ujf.cas.cz/restrax/)
- Fortran 90 (or F77 with extensions) is required for compilation. The GNU g77 compiler can be used to compile the EXCI modules, but not for the rest of the package. Configuration files with appropriate options are available for Absoft Fortran 95 on PC/Linux and Digital Fortran on Alpha/OSF1. Contact the authors for help with porting to other systems.
- Shared PGPLOT library (libpgplot.so) is needed for both compiling and running RESTRAX.
Configure and make
Unzip the distribution, e.g.
% gunzip < restrax-4.8.1.tar.gz | tar -xf -
The distribution would unzip into a new subdirectory restrax-4.8.1
. Make it your current directory and use
following commands to compile RESTRAX:
% configure <sys> -all
% make
<sys>
defines the extension of a configuration file ./config/config.<sys>
with
system dependent linker and compiler options. There should be config.<sys> files available for following
systems/compilers:
- Linux/Absoft Fortran 95 (Absoft)
- OSF1/Digital Fortran 90 (DEC)
- GNU g77 (g77, only for EXCI)
Use one of these files as a template for porting to other systems.
You may test the program now — just call the starting script:
% start
and follow the steps described in the section Quick start [chap. 2.].
Other make targets:
Compile EXCI modules separately:
% make excilib
Create source documentation:
% make srcdoc
Make archive with source distribution:
% make dist
Make archive with binary distribution:
% make distbin
Make archive with html documentation:
% make distdoc
Clean temporary objects:
% make clean
Clean all (requires configure before next make command):
% make cleandist
3.2.2. Installation
Call the script Install <dir>
with the <dir> argument specifying the target directory,
e.g.
% Install /usr/local/restax
NOTE: the installation directory must already exist and you need write permissions to it.
In order to permit access for all system users, make a link to a directory listed in the environment variable
$PATH
, e.g. /usr/local/bin:
% ln -sf /usr/local/restax/start /usr/local/bin/restrax
% chmod 755 /usr/local/bin/restrax
Otherwise you will need to call /usr/local/restax/start
directly. You may also edit the start
script to add or modify start-up menus.
3.2.3. Configuration
(see also the description of installation package [chap. 3.])restrax.ini
The restrax.ini
file is read at the start-up, either from the current directory or from a directory with
instrument configurations (see the search order). It contains default input values required when you start RESTRAX (configuration file, path to data files, data filename etc.). You can also specify
a job file to be executed initially (JOB=filename
).
Environment variables
Environment variables for the PGPLOT and for the shared library loader are defined in the starting scripts
start
or restrax_run
. You can edit these scripts to set the environment according to your
requirements. The shared library with the EXCI run-time module is searched according to the paths defined the environment
variable LD_LIBRARY_PATH (see the search order).
4. Commands reference
- 4.1. Command line interpreter
- 4.2. Input/output
- 4.3. Execution commands
- 4.4. Special settings
- 4.5. DATA submenu
- 4.6. FIT submenu
- 4.7. PLOT submenu
4.1. Command line interpreter
At present, RESTRAX is a console application controlled from a command line. In addition to the commands specific to a given menu context (see below), the command interpreter recognises the following general commands:
? |
Display the list of commands available in the current menu with short hints. |
QUIT |
Quit the current menu (or quit the program from the top menu). |
LIST |
List the parameter values on the screen (when applicable) |
ECHO…END |
Copy any input to the output until the END command (useful in job files). |
PAUSE |
Stop and wait for <ENTER>. Type <Q><ENTER> to interrupt jobfile execution. |
The interpreter accepts abbreviations as long as they are unambiguous, e.g. QU
and QUIT
are
equivalent. There are submenus you can enter and then work in the scope of this submenu commands set (PLOT, [M]FIT, DATA) or pass them a single command as an argument from the main menu. For example, follwing command from the main menu
ResTrax> PLOT RES
would do the same as
PLOT> RES
in the PLOT submenu.
4.2. Input/output
There are two sets of input parameters: (1) those entered interactively [chap. 5.] from the command line and (2) TAS configuration [chap. 5.3.] loaded from a *.cfg file. Follow the above links for details.
The interactive input parameters can be loaded from an ASCII file (*.res) or extracted from the ILL data file.
Appart of the current directory, these files are searched by RESTRAX also in other places according to the given search order.
FILE [filename] |
Load a data file or a parameter file (*.res). Multiple datasets can be loaded as with the command OPEN of the DATA submenu. |
DATA | Switch to data handling menu. In this menu, you can load/unload multiple data sets for subsequent simultaneous fitting. |
SAVE [as] |
Save current parameter values to a *.res file (use "as" to give a new filename). |
LSCFG |
List *.cfg files available in your search path. Note that, if there are multiple files of the same name, those in your current directory override. |
CFG [filename] |
Load the TAS configuration from a *.cfg file. Use this command to update configuration whenever the *.cfg file has changed. |
WRITE [filename] |
Write simulated data or a result of data fitting to an ASCII file. |
PRINT |
Print the last graph. The postscript file restrax.ps is created and sent to the printer using the UNIX system
commands lp -d$PRINTER or lpr . |
PLOT | Calls a submenu that encapsulates the commands needed for graphical representation of the results. You can access
these submenu commands directly by passing them as argumments to PLOT .
|
PATH [dir] |
Change path to the data files. |
CPATH [dir] |
Change path to the configuration (*.cfg) and parameter (*.res) files. |
HELP |
The same as ? – help on commands in the main menu. |
BAT [jobfile] |
Call a job file. This is an ASCII file with one command per line. The sequence and syntax of the commands should be exactly the same as in the interactive mode. Empty lines and lines starting with # are ignored. |
OUT [outfile] |
Redirect output from STDOUT to an ASCII file. Without argument, the output is redirected back to STDOUT. |
EXIT |
Equivalent to QUIT in top menu – program exits, but warning is issued if there are unsaved changes of input parameters. |
EXFF |
Exit without any warning. |
4.3. Execution commands
Some of the execution commands exist in two variants, with and without an M-prefix. This prefix indicates that the Monte Carlo ray-tracing should be used instead of the analytical (Gaussian) method to obtain the resolution function. The M-commands should be preferred as the analytical method is less accurate and actually inadequate for certain configurations (e.g. focussing guides or flat-cone analyzer).
You can use a real number as an additional argument to the M-commands in order to force RESTRAX to repeat the ray-tracing simulation with a different number of events, e.g.
ResTRax> MBRAG 5
would re-run the simulation for 5000 events (passed through the whole instrument).
[M]BRAG |
Calculatesthe projection ("vanadium") and section ("Bragg") widths of the resolution function in the Cooper & Nathans coordinates. |
[M]FWHM [h k l] |
Calculates the "vanadium" and "Bragg" widths of the resolution function along a given direction in reciprocal lattice coordinates. |
[M]RES [n] |
Calculates resolution volumes [n=1] and matrices in various coordinate systems [n=2..4]. |
[M]PHON |
Calculates scan width and plots the profile using planar phonon dispersion. If data are loaded, fits intensity and background to them. The planar dispersion is defined by GH,GK,GL,GMODE [chap. 5.] parameters (direction and gradient in [meV/r.l.u]). |
[M]FIT | Starts the menu for data fitting. The module with the S(Q,E) model is loaded automatically when needed (see the command EXCI). |
PROF [n] |
R(Q,E) profile along n=ord[h,k,l,E,kf], integrated over the others. |
EXCI [libname] |
Load a shared library with the S(Q,E) model. Some of the EXCI codes may prompt for a specific input from the command line or from a file. |
GENDT [n][int] |
Generate simulated data including counting statistics for current TAS setting. Scattering function is defined by the EXCI module. Optionally, specify number of Monte Carlo events [n]x1000 and/or sum of counts on the curve [int].) |
SHELL [command] |
Executes a single UNIX shell command (string argument up to 256 characters). Just calls the SYSTEM(command) procedure. |
4.4. Special settings
RO [n n n n] |
Calculates optimum curvatures of the monochromator and analyzer.
The four integers in the argument are masks defining, which values should be modified.
For example, RO 1 0 1 0 would change ROMH and ROAH (horizontal curvatures of monochromator and analyzer).
The optimum is calculated numerically on the basis of a matrix method (TRAX, M. Popovici): the procedure searches for a minimum of <energy resolution>2/<intensity> for a "vanadium" sample (at given energy transfer). |
ROA [n n n n] |
Similar to RO, but using the analytical formulas: ROMH,ROAH: Rowland (monochromatic) focusing ROMH: parallel beam focusing ROAH: focusing from the sample center to the middle of the detector center. |
EMOD [0|1] |
Switch the diffractometer mode ON|OFF (for setups without analyzer, as corresponds SA=0 in TASMAD) |
AMOD [0|1] |
Switch between the normal (0) and "flat-cone" (1) analyzer modes. |
SIMFC [n] |
Create n empty data sets for the flatcone mode (n<=64). Each data set corresponds to one channel. The step between channel (axis a4) is given by the parameter DA4 in [deg]. Scan by sample rotation (a3) is assumed. The step size is defined by the parameter DA3 [deg]. The QH, QK, QL, EN can be listed for each channel in the DATA menu, where you can also manipulate these data sets: load data, delete them etc. |
SPOS [x y z] |
Shift sample from the axis center. x,y,z are in [mm], x is parallel to ki, z is vertical. |
4.5. DATA submenu
Enter this submenu by the command DATA. It allows for handling multiple data files.
OPEN [datalist] |
Open datafiles with names in a given list or range of numors. The datalist can be a comma-delimitted
range of numbers (for numor-like filenames) or a space-delimitted list of filenames. The data are loaded sequentially to
the current dataset, new dataset positions are added when needed. |
ADD [datalist] |
Add new data. As OPEN, but new datasets are appended on the top of the current list. |
DEL [p1[ p2]] |
Delete data from the positions p1 to p2. Note the space separating p1 and p2! |
LIST |
Print the list of loaded data. |
[n] |
Set the n-th dataset/channel as the current one. When you quit the DATA submenu, the commands, which do not treat multiple datasets (e.g. BRAG, RES etc.), will refer to this dataset and to the corresponding parameter values. |
TAG [n] |
Tag/untag the dataset (n-th or current). The tagged datasets are excluded from data fitting. |
MC [n] |
Simulate resolution function by Monte Carlo for all datasets. Accumulate n x 1000 events for each one. |
4.6. FIT submenu
Enter this submenu by the command [M]FIT. It allows to fit the data by a model defined in the EXCI run-time module. Up to 64 adjustable model parameters
a1 .. an
can be refined by a non-linear
(Marquardt-Levenberg) least squares algorithm. Their number and meaning is specific to the currently loaded EXCI module.
The resulting fit is plotted together with the measured data and saved in a file automatically when you QUIT this
menu.
INIT |
Run the initialization part of the EXCI module. Depending on the particular implementation of EXCI, the model parameters may be reset to the default values and/or a file with model parameters is reloaded. |
FIX n1 [n2 ..] |
Switch the FIX attribute for the model parameters n1 n2 …. The fixed parameters are excluded from fitting, as well as those exactly equal to zero. Without arguments, the commmand will fix all parameters. On the contrary, FIX 0 will free all of them. |
OMEXC [h k l] |
Returns excitation energies [meV] and S(Q,Eexc) values for all dispersion branches defined by the EXCI module. |
RUN [n] |
Start the fitting for n iterations |
PLOT |
Plots the simulated scan curves and experimental data (if loaded) for all datasets. |
MAPSQ |
Plot the map of S(Q,E) at E=const., cut through the scattering plane (the one defined by the AX..AZ and BX..BZ [chap. 5.] vectors). |
QUIT, LIST, ? |
General commands |
4.7. PLOT submenu
Enter this submenu by the command PLOT. It encapsulates commands needed for graphical representation of the results.
These commands can be accessed from the main menu by passing the submenu command as an argument. For example, follwing
command from the main menu
ResTrax> PLOT RES
would do the same as
PLOT> RES
in the PLOT submenu.
ELL [n] |
Resolution ellipsoids in C&N cooordinates calculated by TRAX (Popovici's method). If n=2, plots also ellipsoids calculated from Monte Carlo events. |
RES |
R(Q,E) in C&N cooordinates represented as clouds of points in (Q,E) space. |
CRES |
R(Q,E) in reciprocal lattice coordinates for the current dataset. Plotting plane is defined interactively by any pair of [h,k,l,E] coordinates and specified range. |
MRES |
As CRES, but merges R(Q,E) for all datasets into one plot. For flat-cone multianalyzer, it shows all channels for the central and limit A3 values of assumed scan by DA3 (sample rotation, 91 steps). |
PROF [n] |
R(Q,E) profile along n=ord[h,k,l,E,kf], integrated over the other directions. |
SCAN |
Previously simulated scan profile(s) and data. It does not update the simulation of scan curves! However, the resolution function is updated and plotted for actual settings (may be different from your data), so that the situation in the upper and lower plots may not agree. To get a complete update, you should call [M]FIT PLOT or [M]PHON commands instead. In the upper plot, the x-axis is defined by GH,GK,GL values. You can choose any one, including off-plane directions (vertical). This permits browsing in the reciprocal space without need of continual updating (sometimes lengthy) of the scan profiles. |
SQOM |
Map of S(Q,E) at E=const., cut through the scattering plane (the one defined by the AX..AZ and BX..BZ vectors). |
PRINT |
Print the last graph. The postscript file restrax.ps is created and sent to the printer using a command from UNIX
system (commands lp –d$PRINTER or lpr ). |
5. Input data
- 5.1. Input parameters
- 5.1.1. List of input parameters
- 5.2. Data format
- 5.2.1. ILL data format
- 5.2.2. 3-column format
- 5.3. TAS configuration file
- 5.3.1. Configuration file format
- 5.3.2. Collimator components
5.1. Input parameters
(*.res files)
The basic set of TAS parameters is compatible, apart of some extensions, with the older program RESCAL. These parameters are entered interactively from the command line or loaded via the FILE command from a *.res file (an ASCII file containing a sequence of real numbers) or from the header of an ILL data file.
To modify a value, use the syntax
ResTrax> name value [value …]
Several parameter values can be modified simultaneously in the sequence as they appear in the list. For example
ResTrax> QH 2 2 0.5 12
would set all the QH, QK, QL and EN values.
The list of actual values can be obtained by the LIST command:
ResTrax> LIST
DM = 3.13500 DA = 3.13500
ETAM = .00 ETAA = .00 ETAS = .01
SM = -1. SS = 1. SA = -1.
KFIX = 4.47753 FX = 2.
ALF1 = 500.00 ALF2 = 500.00 ALF3 = 500.00 ALF4 = 500.00
BET1 = .00 BET2= .00 BET3 = .00   BET4 = .00
AS = 5.6576 BS = 5.6576 CS = 5.6576
AA = 90.0000 BB = 90.0000 CC = 90.0000
AX = -1.0000 AY = -1.0000 AZ = .0000
BX = .0000 BY = .0000 BZ = -1.0000
QH = -.2500 QK = -.2500 QL = 4.0000 EN = 8.2800 DA3 = 0.0000 DA4 = 0.0000
DH = .0100 DK = .0100 DL = .0000 DE = .0000
GH = 1.0000 GK = 1.0000 GL = .0000 GMOD = -19.0000
ROMH = .090 ROMV = 1.500 ROAH = .190 ROAV = 3.2000
SDI = 1.00 SHI = 2.00
5.1.1. List of input parameters
DM,DA | dhkl of the monochromator and analyzer | |
ETAM,ETAA,ETAS | mosaic widths (fwhm) of monochromator, analyzer and sample | |
SM,SS,SA | signs of scattering angles for monochromator, analyzer and sample | |
KFIX,FX | fixed neutron wave-vector; FX=1 fixed ki; FX=2 fixed kf | |
ALF1 .. ALF4 | divergence (horizontal) of the soller collimators =0 no collimator, ≥500 coarse collimator (no lamellae) |
|
BET1 .. BET4 | the same for vertical divergence | |
AS,BS,CS | sample unit cell parameters | |
AA,BB,CC | sample unit cell angles | |
AX,AY,AZ BX,BY,BZ | [hkl] components of two vectors defining the scattering plane (should be perpendicular for correct representation of some plots) | |
QH,QK,QL,EN | current TAS setting in (Q,&omega) space, corresponds to the scan center | |
DH,DK,DL,DE | scan increments in (Q,&omega) | |
DA3,DA4 | step of a scan in a3 (sample rotation) and a4 (scattering anngle); DA4 should be non-zero only in the flat-cone analyzer mode, where it defines the angle between analyzer channels | |
GH,GK,GL,GMOD | components of the gradient of the dispersion surface and its module | |
ROMH,ROMV | monochromator curvatures (1/radius), horizontal and vertical | |
ROAH,ROAV | analyzer curvatures (1/radius), horizontal and vertical | |
SDI,SHI | sample diameter and height (cylindrical shape is assumed) |
rlu … reciprocal lattice units
5.2. Data format
Apart of the *.res files [chap. 5.] with TAS setting, RESTRAX can read experimental data in two text formats:
- ILL data format
- general 3-column format
The syntax rules are rather relaxed so that other data formats can be easily transformed to a form readible by RESTRAX.
5.2.1. ILL data format
The file header is optional. It should contain at least the lines describing spectrometer position and scan step, e.g.
POSQE: QH= 0.3000, QK= 0.0000, QL= 3.0000, EN= 0.2000, UN=meV
STEPS: QH = 0.0000, QK = 0.0000, QL = 0.0000, EN = 0.1000
In addition, the file header can contain any other parameters reported by the command LIST, following the syntax:
name1 = value1, name2 = value2, …
Space, comma and semi-colon delimiters are equally interpreted. One line can contain up to 256 characters.
Parameter values missing in the file header are taken from the current setting. The only obligatory item is the row starting with DATA_:
string, which identifies the end of the file header and the start of a data table below.
The data table consists of a single line with column headers and up to 129 lines with corresponding values. Items in the columns are interpreted according to the header. The table must contain at least following columns:
PNT | step numbers |
CNTS | counts |
PAL | index of polarization analysis loop (if used) |
QH,QK,QL,EN,A3 | at least one of these step variables |
The step variables must vary monotonoulsy and stand on the left from the CNTS column.
Examples of valid data files
- full header, E-scan
- simple header, A3 scan
- no header, Q-scan
- data with polarization analysis
5.2.2. 3-column format
The 3-column format differs from the ILL format by missing the DATA_:
line. It must contain at least three columns, which are interpreted as variable (col. 1), intensity (col.2) and errors (col.3). If only one of the DH,DK,DL,DEN,DA3
parameters differs from zero, no header is required and the file can consist of only three number columns. Otherwise, a table header should tell which of the scan variables is listed in the first column.
Examples of valid data files
- full header, E-scan
- simple header, A3 scan
- simple header, Q-scan
- no header (assumed E-scan)
5.3. TAS configuration file
RESTRAX needs a number of additional parameters compared to the matrix method of Cooper&Nathans. These parameters describe in more details the TAS components and their distances. They are stored in the configuration file ( restrax46.cfg by default). RESTRAX prompts for this file upon startup, later on the CFG command can be used to update the configuration, when the *.cfg file has been modified.
A new configuration file can be generated by filling a form on the RESTRAX server.
5.3.1. Configuration file format
The file consists of a sequence of line pairs. The first line (ignored by RESTRAX) contains a header with parameter names, in the second one the parameter values are given in the corresponding order in a free number format (do not put decimal dot where integer is expected!). All dimensions are given in [cm] except of the curvatures [1/m] of guides and focusing devices.
title (max.60 characters):
sample setup for RESTRAX 4.6
This caption would appear in the printed output.
source (shape,diameter,width,height):
0 10. 8. 8.
shape | circular (0), rectangular (1) or elliptical (2) |
diameter | used if shape=0 | width, height | used if shape >=1 |
n-guide (use,dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
0 10. 6300. 2.5 2.5 5. 15. 2.4E-4
1 1 1 1
This line describes the first collimator section between source and monochromator. Together with the "collimator 1" it describes a neutron guide or an in-pile collimation system. The first parameter is an integer specifying the presence of this section (>0 yes, 0 no). The other parameters have a meaning common to all collimator components (cf. below).
monochromator (chi,aniz.,poiss.,thick.,height,length,segments H&V):
0.0 1 0.3 0.3 12.0 10.0 1 3
chi | crystal cutting angle [deg], 0 for the symmetric Bragg reflection |
aniz | ratio of the vertical and horizontal mosaicity |
poiss | Poisson number for the elastically bent crystals (usually about 0.3) |
thick.,height,length | monochromator dimensions |
segments H&V | number of crystal segments in horizontal and vertical direction; if the crystal is perfect (ETAM=0), only vertical segments are considered and the horizontal curvature is interpreted as elastic bending |
analyzer(chi,aniz.,poiss.,thick.,height,length,segments H&V):
0.0 1 0.3 0.3 12.0 10.0 1
3
Analyzer parameters. Syntax and meaning are the same as for the monochromator.
detector (shape,diameter,width,height):
1 4.0
3.0 5.0
Detector window. Syntax and meaning are the same as for the source.
distances (l1,l2,l3,l4):
900. 210. 150. 70.
Distances between the source, monochromator, sample , analyzer and detector. If the n-guide is present, the first distance is measured from its exit, otherwise from the source.
1st collimator (dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
236. 534. 8.05 5. 9.05 11. 0. 0. 0
. 1 1
2nd collimator (dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
87. 35. 4. 4. 7. 7. 0. 0. 0.
1 1
3nd collimator (dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
60. 35. 4. 4. 7. 7. 0. 0. 0.
1 1
4th collimator (dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
35. 20. 4. 4. 12. 12. 0. 0. 0.&nbs
p; 1 1
These 4 items describe the collimators between the source (after n-guide), monochromator, sample , analyzer and detector. The meaning of parameters is described in the section on collimator components.
5.3.2. Collimator components
Neutron guides, benders, soller collimators etc. are represented in ray-tracing routines of RESTRAX by a single component schematically sketched bellow.
The corresponding line in the configuration file is:
n-guide (use,dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
0 10. 6300. 2.5 2.5 5. 15. 2.4E-4
1 1 1 1
for the guide section or
1st collimator (dist,length,hor1,hor2,ver1,ver2,ro,gh,gv,refh,refv):
236. 534. 8.05 5. 9.05 11. 0. 0. 0
. 1 1
for the collimator sections.
These two differ only by the first integer in the line for n-guide, which indicates the presence of the guide section (if use=0, then the guide segment is ignored). The meaning of other items is defined in the figure and table below.
dist | distance of the entrance opening from the preceding component | |
length | L | collimator length |
hor1,hor2 | w1, w2 | widths of the entrance and exit window |
ver1,ver2 | h1, h2 | heights of the entrance and exit window |
ro | 1/R | curvature of the collimator [m-1] (1/R < 0 in the figure) |
gh,gv | mh, mv | critical angles of the horizontal and vertical reflecting mirrors (*) |
refh,refv | rh,rv | reflectivities corresponding to mh, mv |
| D | thickness of the lamellas (fixed to 0.2 mm in this version) |
(*) mh, mv are expressed in the units of the critical angle of nat. Ni.
The number of lamellas is calculated to fit the collimator size and divergence angle (ALF1 .. ALF4).
Special
cases:
ALFn≥500 … no lamellas are considered.
ALFn=0 … the n-th collimator is ignored.
Lookup tables for guide reflectivity
Whenever mh or mv differs from zero, a file with a corresponding lookup table for the mirror reflectivity is searched. The naming convention is mirrorx.x, where x.x is the critical angle specified as mh or mv.The directory search order is the same as for the other configuration files, i.e. first the current directory, then the other directories with *.cfg and *.res files defined upon startup and finally the installation directory. If the corresponding mirrorx.x file is not found, a step-function is taken with r(theta)=rh (or rv) for theta lower than the critical angle for the given neutron wavelength.
Example:
The file mirror4.1 contains a table for the supermirror reflectivity, which will
be used any time when 4.1 (or 4.14, 4.06 etc.) is specified as the critical angle for a collimator. Its 3 columns
contain the angle of incidence theta [Ni nat.] and r(theta) for the two spin states (e.g. polarizing guide
can be simulated in this way.
Caution! This table must contain one row as a header and up to 128 rows with a constant step in theta.
All following lines are ignored, i.e. the reflectivity is cut to 0 for theta>theta(last line).
6. Data fitting
The scattering function S(Q,E) is defined by the module EXCI (actually a dynamically loaded library). This module is used in the convolution algorithm with resolution function to produce simulated data. Moreover, RESTRAX provides a non-linear fitting procedure (Levenberg-Marquardt) to fit the free parameters of anS(Q,E) model to experimental data. This section describes the basic steps of a data fitting session in RESTRAX.
6.1. Requirements
You need an EXCI module describing appropriate scattering function and possibly the file with model
parameters loaded
at the module initialization. Default installation of RESTRAX offers several models, which are
accessible in the
subdirectory ./lib
of the installation root directory:
Modules distributed with version 4.8.0:
res_exci_osc.f | … Damped harmonic oscillators |
res_exci_osc1.f | … Damped harmonic oscillators with a dispersion gradient" |
res_exci_bcm.f | … Bond charge model (phonons in Si, Ge, ...)" |
res_exci_incom.f | … Incommensurate fluctuations (diffuse satellites) |
The source files and the corresponding parameter files can be found in the subdirectory
./exci
.
If you need another model, you can create the corresponding module yourself, using an existing source file as a template. The package with EXCI source files and compilation scripts is available at http://omega.ujf.cas.cz/restrax/.
6.2. Initial steps
- Use the FILE or DATA command to load the data.
- Use the EXCI command to initialize the current module or to load another one.
6.3. Simulation and fitting
Use the FIT or MFIT command to start the fitting procedure. Refer to the list of commands available. RESTRAX plots the data and fitted curves after each iteration step so that you can follow the progress.
Any free parameter can be fixed either explicitly by the command FIX, or by setting its value to zero. To fit a parameter value close to zero, start with a small non-zero initial value.
S(Q,E) models in RESTRAX can contain up to 6 different components (e.g. dispersion branches). There is a width parameter defined for each of them. RESTRAX tests whether this width is zero to select an appropriate convolution algorithm. For zero-width branches, the algorithm requires typically higher number of events accumulated in the resolution function than for the finite-width branches (see How to create own S(Q,E) modules for more details).
The results are saved in a single ASCII file. It contains all information about the model, parameter values, fitted curves and experimental data). You can save it also at a later (WRITE) stage.
7. S(Q,E) modules
How to write own scattering modules for data fitting
version 4.8.1 and higher
7.1. Requirements
- A package with EXCI source files (download from
here)
This archive includes:
- source files of template modules (called
res_exci_name.f
) in./exci
- include files with common block declarations etc. in
./includes
- other source code to be linked with EXCI in
./src
- script
configure.EXCI
, which creates the makefile for easy compilation - the
./config
directory with configuration files containing settings and options for various types of UNIX/compiler systems.
- source files of template modules (called
- A fortran source code with an implementation of the user supplied S(Q,E) function. An existing source file from ./exci subdirectory should be taken as a template (see an example). Comments contained in this file provide a guide how to implement the model in a way compatible with RESTRAX.
- A fortran compiler. Options for Absoft Fortran for Linux, Digital Fortran (DEC Alpha) and GNU g77 are already available. The g77 should be available by default on Linux systems.
Extract the package:
The following command will extract the archive into a new subdirectory called
restrax-version-exci
:
gunzip < restrax-version-exci.tar.gz | tar -xf -
Make it your current directory:
cd restrax-version-exci
7.2. Compiling
Copy your source file into the ./exci
subdirectory and add its name (without
.f
extension) to the list in the script configure.EXCI
. Comment out the
others if you want to compile only your module:
EXCIFILES=" \
# res_exci_osc \
# res_exci_osc1 \
# res_exci_phon \
# res_exci_bcm \
# res_exci_incom \
res_exci_mymodule "
Decide which compiler to use and select the appropriate config.<sys>
file from
./config
, or create your own file with appropriate compiler options. The <sys>
extension is used as an argument to the
configure.EXCI
script. For example, to create a makefile for g77, you have to call
configure.EXCI g77
The script creates a file ./exci/makefile
. Compile the module by calling
make -f exci/makefile
Your module res_exci_mymodule.so
is now created in the ./lib
subdirectory and should be accessible from the normal RESTRAX installation (./lib overrides the
default path to the generic modules).
Note: in the win32 version, res_exci_mymodule.dll
is created in ./bin directory. Since the version 4.8.3, the distributions include makefile_exci.amk
for Absoft Fortran 90 compiler and appropriate batch file for compilation, makeexci.bat
.
Load the library from RESTRAX using the command EXCI and the library name (without extension) as an argument:
ResTrax> EXCI res_exci_mymodule
Note: The environment variable LD_LIBRARY_PATH can be modified in the start-up scripts of RESTRAX to define another search paths for the shared EXCI libraries.
Compiler options:
Consider following options in order to make a module compatible with RESTRAX (g77 equivalents are given in the brackets):
- mangle names to lowercase (
-fcase-lower
) - append _ suffix (g77 default)
- no prefix for commons (g77 default)
- align data on 64-bit boundaries (
-malign-double
) - create position independent code (
-fPIC
) - and of course create a shared module (
-shared
)
7.3. Implementation of S(Q,E)
Only main features are documented here, see comments in a template source file for details.
Interface
SUBROUTINE EXCI(icom,q,omexc,sqom)
integer*4 icom
real*8 q(4),omexc(6),sqom(6)
The subroutine should return the values of excitation energies, omexc(6)
and structure
factors, sqom(6)
for a given Q and E, q(4)
. Use [meV] for
energy and reciprocal lattice units [h,k,l] for Q.
Tasks
The parameter ICOM controls following tasks:
ICOM<-10
Model initialization, called only once when loaded at runtime; sets the model title, number of
branches, default filename for model parameters, parameter names, etc.
ICOM=0
Model initialization called on initialization request (e.g. before each FIT command). Sets the
initial values of model parameters (if not done once for all in the previous task), creates lookup
tables when needed.
ICOM=-1
Only omexc(6)
values are required (e.g. for plotting dispersion branches).
ICOM=-2
Only sqom(6)
values are required (e.g. for mapping S(Q,E).
ICOM>0
In this part implement the algorithm representing the scattering function
S(Q,E).
The value passed by ICOM corresponds to the index of the particular ray-tracing event being passed
in q(4). This feature can be employed when implementing lookup tables. The
(Q,E,probability) values for all events are accessible in EXCI via the common
REAL*4
variables QOM(1:4,j), PQOM(j)
. Similarly, the common integer variable
NDATQOM
informs about the dataset index for which the actual event was simulated. This
permits to define model parameters specific to given dataset (e.g. temperature or background)
The maximum number of fitted parameters is currently limitted to 64. The maximum number of model
components (e.g. dispersion branches) is 6.
8. Theoretical background
- 8.1. Resolution functions
- 8.1.1. Incident intensity (monitor)
- 8.1.2. Intensity at the detector
- 8.1.3. Normalization of R(Q,E)
- 8.1.4. Norm factors reported by RESTRAX
- 8.2. Convolution in (Q,E) space
- 8.2.1. Excitations — zero width in energy
- 8.2.2. Diffuse dispersion — finite width in energy
8.1. Resolution functions
The resolution function R(Q,E) of a neutron spectrometer is defined by the
relationship between the scattering function S(Q,E) as a material property of the
sample, and the measured function I(Q0,E0), which is
smeared by the instrument resolution:
(1)
.
In this formalism, R(Q,E) is a purely instrumental property independent of the
sample material.
In a quasi-classical approximation we can express the resolution function by inspecting neutron
trajectories and their transmission probabilities through the spectrometer.
Let PM(r,ki) and
PA(r,kf) be the probabilities of neutron transmission
through the monochromator and analyzer parts of the spectrometer with (r,ki)
and (r,kf) being the phase-space coordinates of incident and scattered
neutrons at the point r in the sample, where the scattering event takes place. Using these
probabilities, we can express the intensities at the sample and at the detector.
8.1.1. Incident intensity (monitor)
For an isotropic homogeneous source with wave-vector distribution
, the flux
distribution at a point r in the sample is
(2)
.
The incident flux is usually monitored using a detector with low efficiency, inversely proportional
to the neutron velocity (or wave-number),
η(ki) = η0ki-1. The
monitor count-rate per unit area, M, averaged over the sample volume is then
(3)
,
where the integral ranges over the full momentum space of incident neutrons and the sample
volume.
8.1.2. Intensity at the detector
The structure factor S(Q,E) returned by the EXCI module of RESTRAX is related
to the differential scattering cross-section by the equation
(4)
.
In order to simplify notation, our definition of S(Q,E) already includes the
density of unit cells. Neutron current registered by the detector of an instrument set to
(Qj,Ej) is then
(5)
,
where
,
and
.
We have introduced the resolution function defined by the integral expression
(6)
.
Our definition is similar to the one of Dorner [1], except for the additional integration over sample volume, V. This permits to take into account possible correlations
between ki and kf and the dependence of detected count-rate on the
irradiated volume of the sample. The dependence of R'(Q,E) on
(Qj,Ej) is implicitly included in the transport probabilities
PM, PA.
8.1.3. Normalization of R(Q,E)
In RESTRAX, we normalize the resolution function so that the detected count-rate,
Cj, can be written as a simple convolution integral,
(7)
.
The definition of R(Q,E) then follows from (5) and (7), which imply that
(8)
.
The integral (8) is evaluated by two methods:
- Matrix method — analytical method based on Gaussian approximation of the transmission
probabilities, developed and implemented in the program TRAX by Popovici et al. [2].
Related commands: RES, BRAG, FWHM, PHON, FIT
- Monte Carlo ray-tracing — simulation of neutron trajectories through the TAS components.
Related commands: MRES, MBRAG, MFWHM, MPHON, MFIT
Integral norm of the resolution function is
(9)
.
For small samples, we can assume that
does not depend on r and arrive thus to
(10)
.
Comparison with (3) gives
(11)
.
We can thus normalize intensities on monitor counts:
In RESTRAX, the count-rates are normalized to 106 monitor counts per
unit area (M = 106 cm-2) at η0 = 1 Å-1.
8.1.4. Norm factors reported by RESTRAX
The commands RES 1
and MRES 1
report several norm factors related to the
resolution function, R(Q,E). In Gaussian approximation,
(12)
R(Q,E) ≡ R0 exp(-0.5 XTMX)
,
where M is the resolution matrix and
X≡(Q-Q0,E-E0).
The resolution volume, Vol(QE) is then defined as
Vol(QE)TRAX
≡
(2π)2|M|-1/2
and is expressed in units [Å-3meV].
The resolution matrix corresponds to the inverse of the covariance matrix
<XTX>. Therefore, we can calculate the resolution volume also from
Xi events obtained by ray-tracing method,
Vol(QE)MC
≡
(2π)2|<XTX>|1/2 .
Similarly, the resolution volumes Vol(ki)
, Vol(kf)
(equivalent to
VI,VF notation in this paper) are calculated in
[Å-3] as
Vol(ki)
≡
(2π)3/2|<kiTki>|1/2
Vol(kf)
≡
(2π)3/2|<kfTkf>|1/2
The other norm reported by the [M]RES command is derived from the resolution volumes:
R0 ≡ Vol(ki) Vol(kf) / Vol(QE)
It corresponds to the commonly used normalization by Dorner [1] and Popovici [3], who followed (apart of the kf/ki factor) the concept introduced by Cooper & Nathans [4].
The norm RN from (11) is calculated in Gaussian approximation as
(13)
,
where <X> is the covariance matrix of a random vector variable X and
|<X>| denotes its determinant. The factor 24/π is used to compensate for the ratio
between the cylindrical sample volume and its Gaussian approximation. This expression takes into
account possible correlations between ki, r and kf.
8.2. Convolution in (Q,E) space
Scan curves are simulated as a 4-dimensional convolution of the resolution function
R(Q,E) with model scattering function S(Q,E). There are two
kinds of the scattering function available in RESTRAX:
- Planar dispersion — a plane in (Q,E) space defined by the parameters GH,GK,GL and GMOD. The scan is simulated by the commands PHON, MPHON
- User-defined — anything defined in the EXCI module. Simulation of the scan curves and
fitting to experimental data is performed using the commands in the FIT (or MFIT) menu.
For the purpose of convolution with S(Q,E), the resolution
function is always represented as a set of points
(Qα,Eα) with weights pα. Such
representation is either obtained directly by the ray-tracing method or by generation of random
numbers with a Gaussian distribution corresponding to the resolution matrix. The 4-dimensional convolution integral is then evaluated by the Monte Carlo method
described below. To preserve the normalization of the resolution function, we set
where
RN is calculated according to (13).
8.2.1. Excitations — zero width in energy
The resolution function — a cloud of events
(Qα,Eα,pα) — is swept
through the dispersion surface Eexc(Q) along the scan. The events are sorted
into a histogram, weighted by the value of scattering function. Intensity in the j-th step can
be thus expressed as
(14)
.
The δ-function in the sum is approximated by counting only those events, which cross the
dispersion branch within the step interval (j-0.5 ;j+0.5 ). Normalization of the delta
function is ensured by weighting each such event by the factor 1/ΔEj, where
ΔEj is the step width in energy with respect to the dispersion surface,
ΔEj = |
Eexc(Qj) -
Eexc(Qj-1) -
Ej +
Ej-1|.
8.2.2. Diffuse dispersion — finite width in energy
The procedure is similar, but the events are added in each step, weighted by the value of
S(Q,E):
(15)

.
Note: In both cases, the convolution method is correct under the assumption that
changes of shape or size of the resolution function are negligible within the scan range. This
condition is always fulfilled for a3-scans (sample rotation).
References
- B. Dorner, Acta Cryst. (1972), A28, 319-327.
- M. Popovici, A. D. Stoica and I. Ionita, J. Appl. Cryst. (1987)
20, 90-101.
- M. Popovici, Acta Cryst. (1975), A31, 507-513.
- M. J. Cooper, R. Nathans, Acta Cryst. (1967), 23, 357-367.