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 McStas (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 MCSTAS_FORMAT environment variable, which will also make the front-end programs able to import and plot data and instrument consistently (see Section 3.4).
Note that the neutron 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.
The McStas original format, sometimes still referred to by its historical name “PGPLOT format” (the plotting package used in McStas 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 2.2.1, and the number of neutron events for this bin.
Two-dimensional histogram monitors (position sensitive detectors) output \(M\) lines of \(N\) numbers representing neutron 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 neutron intensity, the estimated error, and the neutron event count as numbers on the terminal. (The results from a series of simulations may be combined in a data file using the mcrun front-end as explained in section 3.5.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. The headers may be disabled using the --data-only option in case the file must be read by a program that cannot handle the headers.
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 McStas 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 mcplot front-end (see section 3.5.5). 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 McStas file format is simplified. The --file option may be used to store all data inside the mccode.sim file instead of in separate files.
The NeXus format [Nex] is a platform independent HDF binary data file. To have McStas use it
the HDF and NeXus libraries must have been installed (libNeXus and headers)
the compilation of instruments must be done with the -DUSE_NEXUS -lNeXus flag (see Section 4.3.8). This is automated with the mcrun tool (Section 3.5.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.