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
This message informs you about the path to configuration files.

Path to data files [/usr/local/restrax/demo/osc] :
Here you can modiffy the path to your data files (or do it later using the command PATH).

Configuration updated: restrax46.cfg
This is information about the current TAS configuration [chap. 5.3.] loaded. You can change it later by the command CFG.

Name of a parameter or data file [303] :
Now you have to load some data or a parameter file (*.res).

ResTrax>
The interactive session can start. Use ? 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:

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:

  1. current directory (./)
  2. 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.
  3. 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.

EXCI modules are placed in the ./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:

  1. current directory (./)
  2. ./lib
  3. <installation root>/lib
  4. 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

  1. Source files with RESTRAX (available at the http://omega.ujf.cas.cz/restrax/)
  2. 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.
  3. 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:

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.
DATASwitch 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.
PLOTCalls 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]FITStarts 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

 
variable
description
units
DM,DAdhkl  of the monochromator and analyzer 
Å
ETAM,ETAA,ETASmosaic widths (fwhm) of monochromator, analyzer and sample
min.
SM,SS,SAsigns of scattering angles for monochromator, analyzer and sample
[-1,+1]
KFIX,FXfixed neutron wave-vector; FX=1 fixed ki; FX=2 fixed kf
Å
ALF1 .. ALF4divergence (horizontal) of the soller collimators
=0 no collimator, ≥500 coarse collimator (no lamellae)
min.
BET1 .. BET4the same  for vertical divergence
min.
AS,BS,CSsample unit cell parameters 
Å
AA,BB,CCsample unit cell angles 
deg.
AX,AY,AZ
BX,BY,BZ
[hkl] components of two vectors defining the scattering plane (should be perpendicular for correct representation of some plots)
rlu
QH,QK,QL,ENcurrent TAS setting in (Q,&omega) space, corresponds to the scan center
rlu, meV
DH,DK,DL,DEscan increments in (Q,&omega)
rlu, meV
DA3,DA4step 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
deg
GH,GK,GL,GMODcomponents of the gradient of the dispersion surface and its module 
rlu,  meV/rlu
ROMH,ROMVmonochromator curvatures (1/radius), horizontal and vertical
m-1
ROAH,ROAVanalyzer curvatures (1/radius), horizontal and vertical
m-1
SDI,SHIsample diameter and height (cylindrical shape is assumed)
cm

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:

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:

PNTstep numbers
CNTScounts
PALindex of polarization analysis loop (if used)
QH,QK,QL,EN,A3at 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.

shapecircular (0), rectangular (1) or elliptical (2)
diameterused 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

chicrystal cutting angle [deg], 0 for the symmetric Bragg reflection
anizratio of the vertical and horizontal mosaicity
poissPoisson number for the elastically bent crystals (usually about 0.3)
thick.,height,lengthmonochromator dimensions
segments H&Vnumber 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.

Definition of a collimator in RESTRAX

dist  distance of the entrance opening from the preceding component
lengthL collimator length
hor1,hor2w1,  w2   widths of the entrance and exit window
ver1,ver2h1,   h2 heights of the entrance and exit window
ro1/R curvature of the collimator [m-1] (1/R < 0 in the figure)
gh,gvmh, mv critical angles of the horizontal and vertical reflecting mirrors (*)
refh,refvrh,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

6.1. Requirements
6.2. Initial steps
6.3. Simulation and 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

  1. Use the FILE or DATA command to load the data.
  2. 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

7.1. Requirements
7.2. Compiling
7.3. Implementation of S(Q,E)

How to write own scattering modules for data fitting

version 4.8.1 and higher

7.1. Requirements

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):

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)    i  .

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:

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:

  1. 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
  2. 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)    ij .

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

  1. B. Dorner, Acta Cryst. (1972), A28, 319-327.
  2. M. Popovici, A. D. Stoica and I. Ionita, J. Appl. Cryst. (1987) 20, 90-101.
  3. M. Popovici, Acta Cryst. (1975), A31, 507-513.
  4. M. J. Cooper, R. Nathans, Acta Cryst. (1967), 23, 357-367.