McXtrace - An X-ray ray-trace simulation package

5.3  Running the simulations

Once the simulation program has been generated by the McXtrace compiler mcxtrace and an executable has been obtained with the C compiler, the simulation can be run in various ways.

Simple McXtrace options

In this section, the most common simulation parameters are discussed. For a full list, please consult Tables 5.1 and 5.2.

The simplest way is to run it directly from the command line or shell:

1    ./name.out

Note the leading “.”, which is needed if the current directory is not in the path searched by the shell. When used in this way, the simulation will prompt for the values of any instrument parameters such as angular settings, and then run the simulation. Default instrument parameter values (see section 6.3), if any, will be indicated and entered when hitting the Return key. This way of running McXtrace will only give data for one instrument setting which is normally sufficient for e.g., time-of-flight, SANS or powder instruments, but not for e.g. continuous-beam reflectometers or triple-axis spectrometers where a scan over various instrument settings is required. Often the simulation will be run using one of several available front-ends, as described in the next section. These front-ends help manage output from the potentially many detectors in the instruments, as well as running the simulation for each data point in a scan.

The generated simulations accept a number of options and arguments. The full list can be obtained using the --help option:

1    ./name.out --help

The values of instrument parameters may be specified as arguments using the syntax name=val. For example

1    ./Template_1Slit_Diff.out SLITW=5e-6

The number of x-ray histories to simulate may be set using the --ncount or -n option, for example --ncount=2e5. The initial seed for the random number generator is by default chosen based on the current time so that it is different for each run. However, for debugging purposes it is sometimes convenient to use the same seed for several runs, so that the same sequence of random numbers is used each time. To achieve this, the random seed may be set using the --seed or -s option.

By default, McXtrace simulations write their results into several data files in the current directory, overwriting any previous files stored there. The --dir=dir or -ddir option causes the files to be placed instead in a newly created directory dir (to prevent overwriting previous results an error message is given if the directory already exists).

The complete list of options and arguments accepted by McXtrace simulations appears in Tables 5.1 and 5.2.

5.3.1  Choosing an output data file format

Data files contain header lines with information about the simulation from which they originate. Use --format to select among the available formats (see below).

The format of the output files from McXtrace simulations is described in more detail in section 5.5. It may be chosen either with --format=FORMAT for each simulation or globally by setting the MCXTRACE_FORMAT environment variable. The available format list is obtained using the name.out --help option. McXtrace can presently generate data in the McXtrace/McCode text format or the NeXus format (see section 5.5.2).

It is also possible to read and write x-ray event lists using the MCPL_input/MCPL_output components (see the Component Manual), which use the portable, compressed, multi-code MCPL event format rather than any particular code’s native event format. This is the recommended way to exchange x-ray events between McXtrace/McXtrace and other Monte Carlo codes. The older, code-specific event-file components (Virtual_input/Virtual_output, Virtual_mcnp_input/Virtual_mcnp_output, Virtual_tripoli4_input/Virtual_tripoli4_output, Vitess_input/Vitess_output) still exist for backward compatibility, but have moved to the obsolete component category (see the Component Manual) and are no longer recommended for new instrument work in favour of MCPL.

Additionally, adding the raw keyword to the FORMAT will produce raw \([N, p, p^2]\) data sets instead of \([N, p, \sigma ]\) (see Section 4.2.1). The former representation is fully additive, and thus enables to add results from separate simulations. Other acceptable format modifiers are transpose to transpose data matrices and append to concatenate data to existing files.

5.3.2  Basic import and plot of results

The previous example will result in a mccode.sim index file plus one data file per monitor in the output directory. These are plain-text McXtrace/McCode format files (see section 5.5) that can be read directly with NumPy (numpy.loadtxt) or any other language capable of reading text tables, or, more conveniently, with the mxplot front-end and its underlying data loader (mccodelib.mxplotloader), see section 5.4.6.

When using the HTML plotting back-end (mxplot-html), simulation results are rendered as an interactive, self-contained web page (using D3.js) rather than being saved as static images.

The full, up-to-date list of options accepted by mxrun and by the generated <instr>.out executable is given in Tables 5.1 and 5.2 below. These tables are generated automatically from the mxrun Python source (tools/Python/mxrun/mxrun.py) by the script gen_mxrun_options_table.py in this directory, so that they cannot silently go out of date; run mxrun --help for the same information at the command line.

5.3.3  Interacting with a running simulation

Once the simulation has started, it is possible, under Unix, Linux and Mac OS X systems, to interact with the on-going simulation. This feature is not available when using MPI parallelization.

McXtrace attaches a signal handler to the simulation process. In order to send a signal to the process, the process-id pid must be known. Users may look at their running processes with the Unix ’ps’ command, or alternatively process managers like ’top’ and ’gtop’. If a file.out simulation obtained from McXtrace is running, the process status command should output a line resembling

1<user> 13277 7140 99 23:52 pts/2   00:00:13   file.out
 
2

where user is your Unix login. The pid is there ’13277’.

Once known, it is possible to send one of the signals listed in Table 5.3 using the ’kill’ unix command (or the functionalities of your process manager), e.g.

1    kill -USR2 13277
 
2

This will result in a message showing status (here 33 % achieved), as well as the position in the instrument of the current x-ray.

1# McXtrace: [pid 13277] Signal 12 detected SIGUSR2 (Save simulation) 
2# Simulation: file (file.instr) 
3# Breakpoint: MyDetector (Trace) 33.37 % (  333654.0/ 1000000.0) 
4# Date      : Wed May  7 00:00:52 2003 
5# McXtrace: Saving data and resume simulation (continue)

followed by the list of detector outputs (integrated counts and files). Finally, sending a kill 13277 (which is equivalent to kill -TERM 13277) will end the simulation before the initial ’ncount’ preset.

A typical usage example would be, for instance, to save data during a simulation, plot or analyze it, and decide to interrupt the simulation earlier if the desired statistics has been achieved. This may be done automatically using the Progress_bar component.

Whenever simulation data is generated before end (or the simulation is interrupted), the ’ratio’ field of the monitored data will provide the level of achievement of the computation (for instance ’3.33e+05/1e+06’). Intensities are then usually to be scaled accordingly by the user.

Additionally, any system error will result in similar messages, giving indication about the occurrence of the error (component and section). Whenever possible, the simulation will try to save the data before ending. Most errors appear when using a newly written component, in the INITIALIZE, TRACE or FINALLY sections. Memory errors usually show up when C pointers have not been allocated/unallocated before usage, whereas mathematical errors are found when, for instance, dividing by zero.

---

---

5.3.4  Optimizing simulation speed

There are various ways to speed up simulations

• Optimize the compilation of the instrument, as explained in section 5.2.4.

• Execute the simulation in parallel on a computer cluster using MPI, or simply across the cores of a single machine, as explained in section 5.6.

• Divide simulation into parts using a file for saving or generating x-ray events. In this way, a guide may be simulated only once, saving the x-ray events at the guide exit as a file, which is being read quickly by the second simulation part. Use the MCPL_output and MCPL_input components for this technique (see the Component Manual).

• Use source optimizers like the components Source_adapt or Source_Optimizer. Such component may sometimes not be very efficient, when no x-ray importance sampling can be achieved, or may even sometimes alter the simulation results. Be careful and always check results with a (shorter) non-optimized computation.

• Complex components usually take into account additional small effects in a simulation, but are much longer to execute. Thus, simple components should be preferred whenever possible, at least in the beginning of a simulation project.

• The SPLIT keyword may artificially repeat events reaching specified positions in the instrument. This is very efficient, but requires to cast random numbers in the course of the remaining propagation (e.g. at samples, crystals, ...). See section 6.4.7 for details.

A general comment about optimization is that it should be used cautiously, checking that the results are not significantly affected.

5.3.5  Optimizing instrument parameters

Often, the user may wish to optimize the parameters of a simulation, i.e. the best geometry of a given component, for example the optimal curvature of a monochromator.

The choice of the optimization routine, of the simulation quality value to optimize, the initial parameter guess and the simulation length all have a large influence on the results. The user is advised to be cautious when interpreting the optimization results.

Using iFit for optimization

One of the authors of McXtrace has developed a very flexible and general data analysis and fitting package called iFit [EF14; Ifi] based on Matlab. Matlab itself is not required, as a stand-alone distributable binary of iFit exists.

iFit contains wrapper functionality for compiling and running McXtrace simulations as object functions, and allows to select many different optimizers, including swarms and other non-gradient methods. Please see the iFit documentation for more information.

Our experience is that iFit together with McXtrace can be a more robust optimization solution than the McXtrace built-in --optimize mode described next, in particular for problems with many free parameters.

Using the built-in --optimize mode

The McXtrace package comes with a built-in optimization mode to find instrument parameters that maximize (or minimize) the value of all, or some specified, monitors. As of McXtrace 3.x this is implemented in mxrun using the scipy.optimize.minimize family of solvers [Sci], replacing the earlier built-in Simplex/Nelder–Mead implementation. Available methods include powell (the default), nelder-mead, cg, bfgs, newton-cg, l-bfgs-b, tnc, cobyla, slsqp, trust-constr, dogleg, trust-ncg, trust-exact and trust-krylov; consult the SciPy documentation for the properties of each. As with any non-linear optimizer, results depend on the initial guess and the chosen method, and higher-dimensional problems (many free parameters) are not guaranteed to converge to a meaningful, global optimum.

When using mxrun (section 5.4.2), the optimization mode is set by using the --optimize flag, together with instrument parameter ranges specified exactly as for a scan, e.g. param=min,max. The solver is selected with --optimize-method=METHOD, the convergence tolerance with --optimize-tol=TOL, and the maximum number of iterations with --optimize-maxiter=N. By default all monitors are summed as the figure of merit; a single monitor may be targeted instead with --optimize-monitor=NAME, and --optimize-minimize inverts the sense of the search (minimize rather than maximize). For full control over the optimized quantity (e.g. optimizing on peak width rather than intensity), use --optimize-eval=EXPR with an expression combining the fields of a detector structure d (d.intensity, d.error, d.values, d.X0/d.Y0, d.dX/d.dY), e.g. --optimize-eval="d.intensity/d.dX". See Table 5.1 for the complete, up-to-date option list.

Example:

1mxrun MyBeamline.instr --optimize --optimize-monitor=detector Slit_width=0.1,2

From mxgui (section 5.4.1), one should choose the ’Optimization’ execution mode (instead of the Simulation or Trace mode). Then specify the instrument parameters to optimize by indicating their variation range param=min,max (e.g. Lambda=1,4) just like parameter scans. Finally, run the simulation. The optimum set of parameters is then printed at the end of the simulation process. You may ask to maximize only a given monitor (instead of all) by selecting its component name in the Run Dialog.

If you would like to maximize the flux at a given monitor, with some divergence constrains, you should for instance simply add a divergence collimator before the monitor. Alternatively, write a new component that produce the required ’figure-of-merit’.

The optimization search interval constrains the evolution of parameters. It should be chosen carefully. In particular it is safer for it to indeed contain a high signal domain, and be preferably symmetric with respect to that maximum.

Using custom optimization routines

For cases the built-in --optimize mode (or iFit) does not cover, the user may still write a custom function/script or program that

• inputs the simulation parameters, which are usually numerical values such as a mirror curvature or a slit width, taken from an instrument in the examples directory of the package.

• builds a command line from these parameters.

• executes that command, and waits until the end of the computation.

• reads the relevant data from the monitors.

• outputs a simulation quality measurement from this data, usually the integrated counts or some peak width.

For instance, we could write a function for Python using scipy.optimize (or Matlab, if preferred) in order to study the effect of a beamline parameter P on a given monitor’s intensity:

1import subprocess 
2from scipy.optimize import minimize_scalar 
3import numpy as np 
4 
5def instr_value(P): 
6    outdir = f"opt_{P:.3f}" 
7    subprocess.run(["mxrun", "MyBeamline.instr", "-d", outdir, "-n", "1e6", 
8                    f"P={P}"], check=True) 
9    # read back the relevant monitor’s plain-text McCode data file directly 
10    data = np.loadtxt(f"{outdir}/detector.dat") 
11    return -data[:, 1].sum()   # negative intensity column sum: we minimize below 
12 
13result = minimize_scalar(instr_value, bounds=(0.1, 2.0), method="bounded")

will determine the best value of P in order to maximize the mean detector counts. This is essentially what mxrun --optimize already automates for you (section 5.3.5.0); writing a custom driver like this remains useful mainly when the figure of merit cannot be expressed as a simple --optimize-eval expression, or when a non-scipy optimizer (e.g. a Matlab/iFit swarm optimizer) is preferred.