Virtual Instrumentation (VITESS) for pulsed and continuous sources

# Virtual Instrumentation (VITESS)
for pulsed and continuous sources

## Introduction

| General Information | Pipe Execution | Graphical User Interface | External Commands | Helper Threads | Grid Runs

## VITESS modules

source
guide
bender
spacewindow
spacewindow multiple
chopper disc
chopper fermi_str
chopper fermi_cur
velselect
collimator
New monochromator module
Old monochr_analyser module

polariser he3
polariser sm
sm_ensemble
flipper coil
flipper gradient
resonator drabkin
precessionfield
rotating_field

sample elasticisotr
sample environ
sample inelast
sample nxs
sample powder
sample reflectom
sample s_q
sample sans
sample singcryst

detector
eval_elast
eval_elast2
eval_inelast
frame
monitor
runtime
visual
writeout

beamstop
crys analyzer spec
grid
lense
raytracing
spin reset

Compiling VITESS Modules

## VITESS tools

| Compute Chopper Phases Convert ASCII to binary | Define Direction Direct View Standard Deviation | Generate Mirror Files Generate Surface Files Generate Extraction System | Read and Visualize Output Distance-Time Plot Crystal Analyzer Spectrometer

## VITESS options

| Generate Series | Execution Mode | Check Mode | Trajectory Visualization | more options

## General Information

VITESS is a virtual instrumentation tool for neutron scattering at pulsed and continuous sources.
Please have a look on our web-site http://www.helmholtz-berlin.de/vitess for more and updated information.

VITESS is supported by a graphical user interface (GUI) which generates and controls commands according to the given input. A simulation comprises one or more modules co-working sequentially in a so called 'pipe':

- Each module passes its neutron data to the following one, without storing the intermediate results to a file.
- The first module should be a neutron source module, or read an old output file.
- The last module should be initialised to generate an output file, if simulation results are not shown otherwise.

If you are interested in intermediate results without disturbing the pipe stream you can insert the modules monitor or writeout. Each module refers to the coordinate system provided by the preceding module. For composing a virtual instrument by coupling different modules it is appropriate to work with local reference frames. Their (automatic) generation and orientation is described in the help manual for each VITESS module.

The GUI can control up to 50 modules. Nevertheless it is recommended for the sake of clarity to work with less than 10 modules per pipe. A second pipe which continues e.g. a very detailed instrument description can then simply be initiated by taking the output file from the preceding one as an input.

This GUI allows to enter, edit, and check the various parameters of VITESS modules. You may save these parameters to a text file and load them later from that file. Upon entering the parameters, you may start the command under the control of the VITESS GUI, or generate a batch (sh,tcl,perl,python) command file to be executed in a command shell.

## Pipe Execution

The pipe command looks as follows (the experienced user might tune this directly without using the GUI):

    module1 --f<inputfilename> -a<value> ... | module2 -a<value> ... | moduleN -a<value> ... --F<outputfilename>

The pipe ('|') command is part of the command shell and is common in Unix and Windows systems.

In effect the above example couples the standard output stream 'stdout' of module1 with the standard input stream 'stdin' of module2. The same is true for subsequent modules. Finally the last one, moduleN, writes its data to the file "outputfilename".

Several command line options are common for all modules in the program package VITESS. They are provided to modules by the GUI. Most of them are provided with the same value for all pipe modules (like gravity), others have individual values (1,2,5,13,14).

To distinguish parameters for specific modules from general parameters, only general parameters begin with --.

parameter | option | default
--- | --- | ---
1 neutron input filename | --f<filename> | stdin
2 neutron output filename | --F<filename> | stdout, no_file for the last module
3 rng init | --Z<value> | 1
4 neutron buffer size | --B<value> | 10000
5 logfilename | --L<filename> | stderr
6 dotter | --J
7 gravity | --G[0|1] | 1 (Gravity on)
8 min. neutron weight | --U<value> | 1e-25
9 parameter directory | --P<directory>
10 helper threads | --T<value> | 0
11 read potentially compressed | --c<bytesize>
12 write compressed | --C<mode> | 0
13 generate geometry file | --v<filename> | do not generate trajectory file
14 generate trajectory file | --V<filename> | do not generate trajectory file

1. neutron input filename (--f<filename>)
This option is necessary for the first VITESS module of a pipe, if it is not a source module!
<filename> denotes the file from which the VITESS module will read the incoming neutrons in batches of the neutron buffer size, as indicated by the -B option (e.g. 10000 neutrons). The file <filename> must have been written earlier by another VITESS module.

In principle you are free to choose the filename <filename>, but for the sake of simplification one should keep a common extension of the filename, e.g. '.dat'.

2. neutron output filename (--F<filename>)
This option is used to write the neutron data to a file. This option is only relevant for the last module of a pipe.
<filename> denotes the file to which the processed neutron data are written in batches of the neutron buffer size. For filename restrictions see point 1.

3. rng init (--Z<value>)
The --Z option initializes the random number generator of the VITESS module. The generator is selected from a suite of generators of the GNU scientific library, modules are reading an environment variable with its name.
<value> has to be a positive integer number.

4. neutron buffer size (--B<value>)
The --B<value> option determines the size of the neutron input and output buffers of the VITESS modules, in terms of the 'Neutron' structure storing the vital information of a neutron, i.e. position, direction, wave length etc.. The 'Neutron' structure consists of 12 'double' variables, 1 'long', 1 'short', and 3 characters (see below); thus it has a length of 105 bytes on most computer architectures. The optimal value of the neutron buffer size depends on the computer the VITESS modules runs on, but 10000 is a good choice for a range of computers.

5. logfilename (--L<filename>)
The GUI automatically generates temporary log-files, which are displayed in the output window in correct sequence after a pipe is finished providing some usable control information. Running VITESS without the GUI a logfile can be generated for each module by the command option --L<filename>. Omitting this option means that the information is written to 'stderr', which produces scrambled output in a pipe.

6. dotter (--J)
Only useful for operating without GUI: If --J appears in the command line of a module, dots are written to the logfile (or stderr) giving an impression of the computation speed (one dot corresponds to the size of the neutron output buffer).

7. min. neutron weight (--U<value>)
The --U<value> determines which trajectories are discarded. If the probability weight of a trajectory is less than the given --U<value>, it is removed.

8. Gravity (--G<value>)
With this parameter it can be determined, whether the influence of gravity shall be considered in the simulation (--G1) or not (--G0).

9. Parameter directory (--P<directory>)
Some modules need to know where they may read and store files not stated with parameters. The natural place for these files is the parameter directory.

10. helper threads (--T<value>)
Some modules are capable to exploit multi core CPUs by delegating work load to helper threads. If you specify a number > 0, this may speed up simulations. The outcome of simulations may vary with helper threads, because the random numbers generated are used in a pertubated order, but the outcome is the same for two runs with the same number of helper threads, no matter how many CPU cores a system may have.

11. read potentially compressed data (--c)
If the first program in the pipe is an external program like gzip, which decompresses a neutron trajectory file, the second program in the pipe will be the first module of the instrument. This module knows to accept data from standard input then, potentially compressed, and the value of this parameter gives the byte file size of the data file decompressed by the first program.

12. write compressed data (--C)
If the compression mode is set to nodebug by global option, tracing information in neutron structures are stripped off, reducing the file size to approximately 63%.
For the compression mode float neutron data are further reduced from double to float values, reducing the file size to approx. 40%.
These compression modes will even improve VITESS performance, because they are straight forward and reduce I/O sizes.
Data files may be further compressed by gzip in a second step, independent of this.

13. generate geometry file (--v<filename>)
In this mode all modules of the pipe do not generate neutron trajectories, but write geometric information about the module to a file.

14. generate trajectory file (--V<filename>)
With this mode modules additionally write geometric information of interaction points.

## Graphical User Interface

The graphical user interface (GUI) helps to input and edit the parameters of a VITESS simulation.

Starting from scratch you select modules of the simulation pipe, beginning with the first module. Upon selection the input parameters of that module appear.

Each parameter has a label in bold characters. If you click (left mouse button) on that label you might get some lengthier explanation for that parameter in the output window. If you need even more information you might select a module from the Help / Modules menu. HTML text is shown by your browser, which will be started automatically if not already open.

Parameters may be input textually (of type integer, float, string ...) in the light blue entry fields, or by selecting a radio button. Some filenames may be input by browsing, use the BrowseN button to browse a new file name.
Without change, the parameter entries appear in the main Xcontrol window 'here'. If you like it select the other menu entry 'separate' to edit this modules parameters in a separate window, or leave these parameters invisible by now by selecting 'hidden'.

The simulation pipe happens to become longer, if you select a new module for the last entry, which by default is the dummy entry indicated with '-----'. If you need to insert a new module e.g. between the first and the second module, press the button labelled with a down array left to Module 1. If you do not need a module, press the button labelled with a big X beneath.

In any situation you may check if your inputs are formally correct by pressing the Check-button. The Xcontrol message window will explain any errors, and your computer will beep, if something is unacceptable. Otherwise the pipe command is to be seen.
By pressing the Start-button you actually start the simulation. The pipe is active how long it takes to complete the programs.
Stop the simulation prematurely with the Stop-button. (Modules not conforming to standards may need the Kill-button.)
You may set a timeout, that is an an upper limit for the execution time, by option menu; default is no timeout.

To simulate an instrument with some few parameters changed you may File / Generate Series

1. specify the number of iterations;
2. specify which parameters to change; this is most easily done by clicking on labels of parameters;
3. input values; the first iteration has default values as set in modules;
   if you input a delta value and press RETURN all n-th values will be v1 + n*delta, v1 being the first value, n >= 2,
4. execute that series or save a tcl command file to be executed without GUI support.

With the Exit-button you terminate VITESS.

If you save all GUI settings with the 'Save instrument' button of the 'File' title menu to a file, you may re-use these parameters later with the 'Load instrument' action. 'Save as Command' stores the pipe command to a text file.

You may save parts of an instrument, like some series of neutron guides, with 'Save Packet', and later add that part with 'Add Packet' or insert it with 'Insert Packet' when composing a new instrument.

1d or 2d plots of simulation results come with the 'Plot file' and '2d Plot file' buttons of the 'File' title menu. Monitor output files may be plotted at the end of a simulation, if this has been chosen by a select button.

Help on modules comes with the corresponding buttons of the 'Help' menu. The help system allows to search for keywords.

With the Trajectories-button you start a trajectory simulation which additionally writes geometric information and neutron trajectories to be visualized afterwards.

## Helper Threads

If you run VITESS on a modern multi core CPU, you may speed up simulations by using helper threads. If it is a quadcore CPU, try 3 or 4 helper threads. Processing of neutron trajectories in suitables modules will be done in parallel.

Caveat: Simulations with identical input have the same result statistically, when using different numbers of helper threads. The same holds, it you run simulations on different CPU types, where the result will not be exactly the same. Results are exactly the same, if simulations with equal input run on a given CPU / operating system with the same number of helper threads specified.

## Grid Runs

A simulation with a very big number of e.g. 1e10 trajectories may take a long time on a normal PC. If you have access to a computer grid like the dirac cluster at HZB, it may be of interest to use many nodes for parallel simulation.
The first step is to export your instrument as a .grd file. The gridrun script for Linux clusters may then be used to start a batch job either per ssh, Sun Grid Engine (SGE), or SLURM batch system commands. For further information do `<path-to-installation>/gridrun -h` and read the concept text.

## External Commands

The VITESS command pipe may contain commands with external programs.

These programs must read neutron data from standard input and write resulting neutron data to standard output.

The external command may be supplied with (argc, argv)-style options, which are specified by option string. This option string is given as the contents of a text file.

Neutron data have the following C structure type:

    typedef double VectorType[3];

    typedef struct
    {
      char          IDGrp[2];
      unsigned long IDNo;
    }
    TotalID;

    typedef struct
    {
      TotalID       ID;
      char          Debug;
      short         Color;
      double        Time;
      double        Wavelength;
      double        Probability;
      VectorType    Position;
      VectorType    Vector;
      VectorType    Spin;
    }
    Neutron;

## Compiling VITESS Modules

We distribute VITESS sources with compiled binaries for Windows, Linux, and Mac OS. With these binaries you may execute VITESS out of the box on most systems.
You will need to compile sources, when your system is of another Unix flavor or some system libraries are not compatible, or you want to use the latest compiler's optimization for ultimate speed.

### Compiling the C/C++ Sources on Unix Systems

1. `cd <path-to-installation>/SRC`
2. `./mmake.pl`
3. `make`
4. `make install`

The mmake.pl script explores your system hardware and given Linux or Mac OS software and generates a Makefile.
Making depends on compiled GSL PRNG and g2 libraries, to be found in the rng and g2/g2-0.72 subdirectory.
You may provide some parameters for the generation, see `mmake.pl -h`
If something is missing you may edit Makefile to your needs, please feel free to ask for help at the vitess@helmholtz-berlin.de mailing list.
mmake.pl also states the given VITESS version and the date of its call in the binaries.
We use the GNU C compiler as default, but you may use the optimizing Intel compiler by editing the Makefile at the #Compiler lines.
Installing the binaries means to move the linked files to the MODULES directory, with a name extension like _Linux (for 32 bit Intel Linux systems), _Linux_x86_64 (64 bit Intel Linux) or _Darwin (32 bit Intel Mac) and _Darwin_x86_64 (64 bit Intel Mac).

### Compiling the Sources on Windows systems

SRC\vitess.mak in the distribution is a nmake makefile for MS Visual C compilers, to be called in a command shell. Both files may be generated with the Unix mmake.pl script.

1. `cd <path-to-installation>\SRC`
2. edit compile.bat and vitess.mak to your needs
3. `compile.bat`
4. `copy Release\*.exe ..\MODULES`

You need to edit the path statement of compile.bat, and the CPATH, SROOT, SVNROOT and CPATH2 lines of vitess.mak.
Calling compile.bat should produce .exe binaries in SRC\Release. The last step installs these.

Back to start of page
VITESS homepage
Email vitess@helmholtz-berlin.de

Last modified: Fri Nov 22 15:36:27 MET 2013