McXtrace - An X-ray ray-trace simulation package

5.5  Data formats - Analyzing and visualizing the simulation results

To analyze simulation results, one uses the same tools as for analyzing experimental data, i.e. programs such as Python/NumPy, Matlab, IDL. The output files from simulations are usually simple text files containing headers and data blocks. If data blocks are empty they may be accessed referring to an external file indicated in the header.

Each data file contains information about the simulation, the instrument, the parameters used, and of course the signal, the estimated error on the signal, and the number of events used in each bin. Additionally, all data files indicate their first moment (mean value) and second moment (half width) in the ’statistics’ field.

The available data formats are the legacy McXtrace (McCode) format, and the HDF/NeXus binary when the needed libraries are installed.

In order for the user to choose the data format, we recommend to set it using the --format=FORMAT or alternatively via the MCXTRACE_FORMAT environment variable, which will also make the front-end programs able to import and plot data and instrument consistently (see Section 5.3).

Note that the x-ray event counts in detectors are typically not very meaningful except as a way to measure the performance of the simulation. Use the simulated intensity instead whenever analyzing simulation data.

5.5.1  The McXtrace/McCode text format

The McXtrace original format, sometimes still referred to by its historical name “PGPLOT format” (the plotting package used in McXtrace 1.x/2.x), is simply columns of ASCII text that most programs should be able to read.

One-dimensional histogram monitors (time-of-flight, energy) write one line for each histogram bin. Each line contains a number identifying the bin (i.e. the time-of-flight) followed by three numbers: the simulated intensity, an estimate of the statistical error as explained in section 4.2.1, and the number of x-ray events for this bin.

Two-dimensional histogram monitors (position sensitive detectors) output \(M\) lines of \(N\) numbers representing x-ray intensities, where \(M\) and \(N\) are the number of bins in the two dimensions. The two-dimensional monitors also store the error estimates and event counts as additional matrices.

Single-point monitors output the x-ray intensity, the estimated error, and the x-ray event count as numbers on the terminal. (The results from a series of simulations may be combined in a data file using the mxrun front-end as explained in section 5.4.2).

When using one- and two-dimensional monitors, the integrated intensities are written to terminal as for the single-point monitor type, supplementing file output of the full one- or two-dimensional intensity distribution. Both one- and two-dimensional monitor output by default start with a header of comment lines, all beginning with the ‘#’ character. This header gives such information as the name of the instrument used in the simulation, the values of any instrument parameters, the name of the monitor component for this data file, etc.

In addition to the files written for each one- and two-dimensional monitor component, another file (by default named mccode.sim) is also created. This file is in a special McXtrace ASCII format. It contains all available information about the instrument definition used for the simulation, the parameters and options used to run the simulation, and the monitor components present in the instrument. It is read by the mxplot front-end (see section 5.4.6). This file stores the results from single monitors, but by default contains only pointers (in the form of file names) to data for one- and two-dimensional monitors. By storing data in separate files, reading the data with programs that do not know the special McXtrace file format is simplified.

5.5.2  NeXus format

The NeXus format [Nex] is a platform independent HDF binary data file. To have McXtrace use it

1. the HDF and NeXus libraries must have been installed (libNeXus and headers)

2. the compilation of instruments must be done with the -DUSE_NEXUS -lNeXus flag (see Section 6.3.4). This is automated with the mxrun tool (Section 5.4.2).

All results are saved in a single file, containing ’groups’ of data. To view such files, install and use HDFView (or alternatively HDFExplorer). This Java viewer can show content of all detectors, including metadata (attributes). Basic detector images may also be generated.