root/branches/mcstas-1.x/mcrun.1

.TH mcrun 1  "" "McStas X.Y.Z, Month Day, Year" "USER COMMANDS"
.SH NAME
mcrun \- Command-line simulator of the McStas neutron ray-trace simulation package
.SH SYNOPSIS
.B mcrun
[\-cpnN] file.instr [\-sndftgahi] param1={val|min,max} ...
.SH DESCRIPTION
The
.B mcrun
command is the instrument builder and launcher of the McStas package.
.PP
.B McStas
is a general tool for simulating neutron scattering instruments and experiments. It is actively supported by
.I Risoe National Laboratory
and
.I ILL

.PP
McStas is based on a compiler [mcstas(1)] that reads a high-level specification language defining the instrument to be simulated and produces C code that performs the Monte Carlo Simulation. The system is very fast in use, both when setting up the instrument definition and when doing calculations.
.PP
McStas supports triple-axis,  time-of-flight instruments, and polarised neutrons. It comes with a comprehensive manual and a library of well-tested components that include most standard elements of neutron scattering instruments, including steady-state and pulsed sources, monochromators/analysers, guides, collimators, vanadium and powder samples, velocity selectors and choppers, and a variety of detectors.
.PP
The package consists of the following user commands:
.TP
mcgui(1)
is the graphical user interface. Then use the
.I Neutron Site
menu to select an example instrument, and access the whole documentation for the
.I Help
menu. It contains an instrument editor, methods to plot simulation results, and much more
.TP
.B mcrun(1)
is the command-line tool for building and running simulations
.TP
mcplot(1)
is the simulation results plotting tool
.TP
mcdisplay(1)
is the instrument geometry and neutron trajectory viewer
.TP
mcdoc(1)
is the documentation tool
.TP
mcstas(1)
is the instrument compiler
.TP
mcconvert(1)
can convert Matlab data files into Scilab data files, and vice-versa. It also handles data sets with binary encoding. It also handles parameter scan results.
.TP
mcformat(1)
can transform any text data set from one format to an other. It does not support conversion from binary data sets. It can also merge equivalent results.
.PP
We encourage users to refer to the User and Component Manuals, which are available with the command
.B
mcdoc
.P
.SH OPTIONS
.TP
\-h | \-\-help
displays the command help
.TP
\-N NP | \-\-numpoints=NP
Set number of scan points or maximum iteration number for optimization
.TP
\-\-mpi=NB_CPU
Spread simulation over NB_CPU machines using MPI (when MPICH has been installed)
.TP
\-\-machines=MACHINES
Read machine names from file MACHINES (MPI/grid)
.TP
\-\-optim=COMP
Add COMP to the list of monitors to maximize (optimization criteria)
.TP
\-\-optim
Maximize all monitors
.TP
\-\-optim-prec=PREC
Relative requested accuracy of criteria for optimization (1e-3)
.TP
\-\-test
Execute McStas selftest and generate report
.SH INSTRUMENT OPTIONS
These options apply to the generated instrument code (foo.c and foo.out)
.TP
\-s SEED | \-\-seed=SEED
Set random seed (must be non zero)
.TP
\-n COUNT | \-\-ncount=COUNT
Set number of neutrons to simulate
.TP
\-d DIR | \-\-dir=DIR
Put all data files in directory DIR
.TP
\-f FILE | \-\-file=FILE
Put all data in a single file
.TP
\-t | \-\-trace
Enable trace of neutron through instrument (must have been set during code generation with mcstas(1)). This is necessary for mcdisplay(1) to run
.TP
\-g | \-\-gravitation
Enable gravitation for all trajectories
.TP
\-a | \-\-data-only
Do not put any headers in the data files
.TP
\-\-no-output-files
Do not write any data files
.TP
\-h | \-\-help
Show help message for the instrument
.TP
\-i | \-\-info
Detailed instrument information, including valid parameters
.TP
\-\-format=FORMAT
Output data files using format FORMAT (format list obtained from foo.out -h, e.g. Matlab, Scilab, PGPLOT, HTML, XML, Octave)
.SH EXAMPLES
The three following examples are equivalent to the single command:
 mcrun -c foo.instr param1=value1 ...
.TP
Typical usage (forcing to recompile instrument)
.B mcrun
-c foo.instr param1=value1 ...
.SH ENVIRONMENT
The
.B MCSTAS
environment variable may be set to define the McStas library location. This is /usr/local/lib/mcstas on Linux systems. Executables are usually located in /usr/local/bin.
The McStas configuration file is MCSTAS/tools/perl/mcstas_config.perl
.P
The
.B MCSTAS_FORMAT
environment variable may be set to define the default data format used for storing results. This is usually 'PGPLOT', 'Matlab', or 'Scilab'.
.P
The
.B
MCSTAS_CC
environment variable may be set to define the compiler to use (e.g. gcc)
.P
The
.B
MCSTAS_CFLAGS
environment variable may be set to define the options for compilation (e.g. -O2)
.SH BUGS
Some implementations of Perl for Windows do not support background execution. This may hang mcrun (and mcgui).
McStas is a large package, and bugs might be found. If so, please report to
.B http://mcstas.org/McZilla/
and the mailing list
.B neutron-mc@risoe.dk
.SH EXIT STATUS
mcrun returns 1 in case of error, 0 when all went fine
.SH AUTHOR
Peter Kjaer Willendrup, Emmanuel FARHI, Kim Lefmann, and Klaus Lieutenant
.SH SEE ALSO
mcstas(1), mcrun(1), mcdisplay(1), mcplot(1), mcgui(1), mcdoc(1), mcformat(1), mcconvert(1)
.P
web site:     <http://www.mcstas.org>
.P
mailing list: <mailto:neutron-mc@risoe.dk>
.P
matlab(1), idl(1), scilab(1), octave(1), vitess(1), NISP(1), restrax(1), mcnp(1), tripoli(1)