Virtual Instrumentation (VITESS)
for pulsed and continuous sources

Introduction

VITESS modules

VITESS tools

VITESS options

General 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.

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>

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.

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

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

External Commands

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

Compiling the Sources on Windows systems

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

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