This section describes how to run the McXtrace compiler mcxtrace manually. Often, it will be more convenient to use the front-end program mxgui (section 5.4.1) or mxrun (section 5.4.2), which run the compilation and the simulations automatically.
Upon a command of the form
1 mcxtrace name.instr 2
the compiler mcxtrace will read the instrument definition name.instr, written in the McXtrace 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 mcxtrace -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 mcxtrace 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 x-ray through the instrument, as well as the position and orientation of every component. This option is mainly used with the mxdisplay front-end as described in section 5.4.4.
The code generation options can also be controlled by using preprocessor macros in the C compiler, without the need to re-run mcxtrace. 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 McXtrace 3.5 onwards an alternative code generator, mcxtrace-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:
mxrun --cogen=mcxtrace-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:
mxrun --edit-user-config
or via the Save/Edit configuration dialogue inside mxgui.
At the time of the McXtrace 3.6 release, mcxtrace-antlr is close to feature-complete for CPU simulations with a few more issues for GPU/OpenACC simulations.
The McXtrace compiler mcxtrace 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. McXtrace 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 McXtrace directory. Usually, the user will not need to worry about this as mcxtrace will automatically find the required files. But if users build their own component library in a separate directory or if mcxtrace 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 McXtrace directory is set when mcxtrace is compiled. It defaults to /usr/share/mcxtrace/version on Debian and derivatives, to /usr/local/mcxtrace/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/McXtrace-version.app/Contents/Resources/mcxtrace/version, and C:\mcxtrace-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 MCXTRACE:
1 setenv MCXTRACE /home/joe/mcxtrace 2
for csh/tcsh users, or
1 export MCXTRACE=/home/joe/mcxtrace 2
for bash/Bourne shell users. Windows users should define MCXTRACE from the menu ’Start/Settings/Control Panel/System/Advanced/Environment Variables’ by creating MCXTRACE with the value C:\mcxtrace\lib
To make mcxtrace search additional directories for component definitions and include files, use the -I switch:
1 mcxtrace -I/home/joe/components -I/home/joe/mcxtrace/include name.instr
Multiple -I options can be given, as shown.
By default, mcxtrace 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, mcxtrace provides the following options:
--no-main This option makes mcxtrace omit the main() function in the generated simulation program. The user must then arrange for the function mcxtrace_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 mcxtrace omit the run-time code from the generated simulation program, and the user must then explicitly link with the file mcxtrace-r.c as well as other shared libraries from the McXtrace 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 mcxtrace, 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 McXtrace 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 McXtrace 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 McXtrace on Linux or Mac OS X, set the environment variables
MCXTRACE_CC=icc
MCXTRACE_CFLAGS="-g -O2 -wd177,266,1011,181"
To use icc with MPI on Unix system (see Section 5.6) 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 McXtrace with the Intel compiler should be possible (currently untested by the McXtrace developer team).
The -O option typically enables the optimization phase of the compiler, which can make quite a difference in speed of mcxtrace-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 McXtrace WWW home page [Mcx]):
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. mcxtrace 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, McXtrace 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 6). Refer to section 5.3.4 for other optimization methods.