VITESS is a virtual instrumentation tool for neutron scattering at pulsed and continuous sources. Please have a look on our web-site www.hmi.de/projects/ess/vitess/ for more and updated information.VITESS is supported by a graphical user interface (GUI) which generates and controls command lines 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 (see help descriptions). 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 15 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 (or Tcl) command file to be executed in a command shell. --------------------- behind the GUI-curtain...----------------------------- 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 NT/95/98/2000 systems. (For Windows9x systems please refer to the hints given in the install.txt file.) 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, i.e they have a common meaning. They can be given only once on the GUI. These options are 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. min. neutron weight --U<value> 1e-25 8. Gravity --G{0;1} 1 (Gravity on) 9. Parameter directory --P 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 initialises the random number generator (rng) of the VITESS modules. A portable random number generator is used, as described in the standard reference 'Numerical Recipes'. The routine implementing this random number generator is called ran3(). <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'. 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<value>) 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.
The specific input parameters for each module naturally must not be controlled by the general command options --f, --F, --B, --Z, --L, --J, --U, --G.
This 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 becomes shown from your browser (communicator), which becomes started automatically. 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. 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. A timeout (changable by option menu, default 28800 seconds or 8 hours) sets an upper limit for the execution time. To simulate an instrument with some few parameters changed you may File / "Generate Series" 1. specify the number of iterations and which parameters to change; this is most easily done by clicking on labels of parameters; 2. 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, 3. 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. 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.
The VITESS command pipe may contain external commands resp. 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;
VITESS homepage
Email vitess@hmi.de
Last modified: Tue Jul 23 18:15:22 MEST 2002Tuesday, 03-Jul-2007 16:14:08 CEST