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 from the command line and (2) TAS configuration 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 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 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).