This section describes how to run the McStas compiler mcstas manually. Often, it will be more convenient to use the front-end program mcgui (section 3.5.1) or mcrun (section 3.5.2), which run the compilation and the simulations automatically.
Upon a command of the form
1 mcstas name.instr 2
the compiler mcstas will read the instrument definition name.instr, written in the McStas meta-language, and translate it into a Monte Carlo simulation program in the programming language C. The output is by default written to a file in the current directory with the same name as the instrument file, but with extension .c rather than .instr. This can be overridden using the -o option as follows:
1 mcstas -o code.c name.instr 2
which gives the output in the file code.c. A single dash ‘-’ may be used for both input and output filename to represent standard input and standard output, respectively.
By default, the code generated by mcstas is ISO-C with some extensions (currently the only extension is the creation of new directories, which is not possible in pure ISO-C). The use of extensions may be disabled with the -p or --portable option. With this option, the output is strictly ISO-C compliant, at the cost of some slight reduction in capabilities.
The -t or --trace option puts special “trace” code in the output. This code makes it possible to get a complete trace of the path of every neutron ray through the instrument, as well as the position and orientation of every component. This option is mainly used with the mcdisplay front-end as described in section 3.5.4.
The code generation options can also be controlled by using preprocessor macros in the C compiler, without the need to re-run mcstas. If the preprocessor macro MC_PORTABLE is defined, the same result is obtained as with the --portable option. The effect of the --trace option may be obtained by defining the MC_TRACE_ENABLED macro. Most Unix-like C compilers allow preprocessor macros to be defined using the -D option, e.g.
1 cc -DMC_TRACE_ENABLED -DMC_PORTABLE ... 2
Finally, the --verbose option will list the components and libraries being included in the instrument.
From McStas 3.5 onwards an alternative code generator, mcstas-antlr, is available alongside the classic generator. It is built on the ANTLR parser framework rather than the traditional lex/yacc toolchain, is implemented primarily in Python, and is a candidate replacement for the default generator in future releases.
Select it on a per-run basis with the –cogen flag:
mcrun --cogen=mcstas-antlr MyInstrument.instr -n 1e8
The active code generator can also be set permanently by editing the MCCOGEN field in mccode_config.json. This file is accessible from the command line with:
mcrun --edit-user-config
or via the Save/Edit configuration dialogue inside mcgui.
At the time of the McStas 3.6 release, mcstas-antlr is close to feature-complete for CPU simulations with a few more issues for GPU/OpenACC simulations.
The McStas compiler mcstas needs to be able to find various files during compilation, some explicitly requested by the user (such as component definitions and files referenced by %include), and some used internally to generate the simulation executable. McStas looks for these files in three places: first in the current directory, then in a list of directories given by the user, and finally in a special McStas directory. Usually, the user will not need to worry about this as mcstas will automatically find the required files. But if users build their own component library in a separate directory or if mcstas is installed in an unusual way, it will be necessary to tell the compiler where to look for the files.
The location of the special McStas directory is set when mcstas is compiled. It defaults to /usr/share/mcstas/version on Debian and derivatives, to /usr/local/mcstas/version on RedHat and derivatives and on other Unix-like systems, including Mac OS X, where it is a link to the actual location /Applications/McStas-version.app/Contents/Resources/mcstas/version, and C:\mcstas-version\lib on Windows systems, but it can be changed to something else, see the installation instructions for details.
The location can be overridden by setting the environment variable MCSTAS:
1 setenv MCSTAS /home/joe/mcstas 2
for csh/tcsh users, or
1 export MCSTAS=/home/joe/mcstas 2
for bash/Bourne shell users. Windows users should define MCSTAS from the menu ’Start/Settings/Control Panel/System/Advanced/Environment Variables’ by creating MCSTAS with the value C:\mcstas\lib
To make mcstas search additional directories for component definitions and include files, use the -I switch:
1 mcstas -I/home/joe/components -I/home/joe/neutron/include name.instr
Multiple -I options can be given, as shown.
By default, mcstas will generate a stand-alone C program, which is what is needed in most cases. However, for advanced usage, such as embedding the generated simulation in another program or even including two or more simulations in the same program, a stand-alone program is not appropriate. For such usage, mcstas provides the following options:
--no-main This option makes mcstas omit the main() function in the generated simulation program. The user must then arrange for the function mcstas_main() to be called in some way.
--no-runtime Normally, the generated simulation program contains all the run-time C code necessary for declaring functions, variables, etc. used during the simulation. This option makes mcstas omit the run-time code from the generated simulation program, and the user must then explicitly link with the file mcstas-r.c as well as other shared libraries from the McStas distribution.
Users that need these options are encouraged to contact the authors for further help.
After the source code for the simulation program has been generated with mcstas, it must be compiled with the C compiler to produce an executable. Since the generated C code obeys the ISO-C standard, it should be easy to compile it using any ISO-C (or C++) compiler. E.g. a typical Unix-style command would be
1 cc -O -o name.out name.c -lm
The McStas team recommends these compiler alternatives for the Intel (and AMD) hardware architectures:
gcc which is a very portable, open source, ISO-C compatible c compiler, available for most platforms. For Linux it is usually part of your distribution, for Windows the McStas distribution package includes a version of gcc (in the Dev-CPP sub-package), and for Mac OS X gcc is part of the Xcode tools package available on the installation medium.
icc or the Intel c compiler is available for Linux, Mac OS and Windows systems and is a commercial software product. Generally, simulations run with the Intel compiler are a factor of 2 faster than the identical simulation run using gcc. To use icc with McStas on Linux or Mac OS X, set the environment variables
MCSTAS_CC=icc
MCSTAS_CFLAGS="-g -O2 -wd177,266,1011,181"
To use icc with MPI on Unix system (see Section 3.7) installations, it seems that editing the mpicc shell script and setting the CC variable to "icc" is the only requirement! On Windows, the Intel c compiler is ’icl’, not ’icc’ and has a dependency for Microsoft Visual C++. If you have both these softwares available, running McStas with the Intel compiler should be possible (currently untested by the McStas developer team).
The -O option typically enables the optimization phase of the compiler, which can make quite a difference in speed of mcstas-generated simulations. The -o name.out sets the name of the generated executable. The -lm options is needed on many systems to link in the math runtime library (like the \(\cos ()\) and \(\sin ()\) functions).
Monte Carlo simulations are computationally intensive, and it is often desirable to have them run as fast as possible. Some success can be obtained by adjusting the compiler optimization options. Here are some example platform and compiler combinations that have been found to perform well (up-to-date information will be available on the McStas WWW home page [Mcs]):
Intel x86 (“PC”) with Linux and GCC, using options gcc -O3.
Intel x86 with Linux and EGCS (GCC derivate) using options egcc -O6.
Intel x86 with Linux and PGCC (pentium-optimized GCC derivate), using options gcc -O6 -mstack-align-double.
HPPA machines running HPUX with the optional ISO-C compiler, using the options -Aa +Oall -Wl,-a,archive (the -Aa option is necessary to enable the ISO-C standard).
SGI machines running Irix with the options -Ofast -o32 -w
Optimization flags will typically result in a speed improvement by a factor about 3, but the compilation of the instrument may be 5 times slower.
A warning is in place here: it is tempting to spend far more time fiddling with compiler options and benchmarking than is actually saved in computation times. Even worse, compiler optimizations are notoriously buggy; the options given above for PGCC on Linux and the ISO-C compiler for HPUX have been known to generate incorrect code in some compiler versions. mcstas actually puts an effort into making the task of the C compiler easier, by in-lining code and using variables in an efficient way. As a result, McStas simulations generally run quite fast, often fast enough that further optimizations are not worthwhile. Also, optimizations are highly time and memory consuming during compilation, and thus may fail when dealing with large instrument descriptions (e.g. more that 100 elements). The compilation process is simplified when using components of the library making use of shared libraries (see SHARE keyword in chapter 4). Refer to section 3.4.4 for other optimization methods.