About McXtrace
Publications
Project Partners
Project People
Goal
Documentation
Manual
Commands
Wiki (GitHub)
Tutorial
5 Running McXtrace
This chapter describes usage of the McXtrace simulation package. In case of problems regarding installation or usage, the McXtrace mailing list [Mcx] or the authors should be contacted.
Performing a simulation using McXtrace can be divided into the following steps/elements
-
To use McXtrace, an instrument definition file describing the instrument to be simulated must be written. Alternatively, an example instrument file can be obtained from the examples/ directory in the distribution or from another source.
-
The input files (instrument and component files) are written in the McXtrace meta-language and are edited either by using your favorite editor or by using the built-in editor of the graphical user interface (mxgui).
-
Next, the McXtrace compiler mcxtrace is invoked to translate the instrument and component files into a C program. The program mcxtrace itself is written in C, using the parser flex and the compiler compiler bison.
-
The resulting C program can then be compiled with a C compiler and run in combination with various front-end programs for example to present the intensity at the detector as a motor position is varied.
-
The output data may be analyzed and visualized in the same way as regular experiments by using the data handling and visualization tools in McXtrace. As of McXtrace 3.x, these front-ends (mxplot, mxdisplay, …) are all implemented in Python, using matplotlib, pyqtgraph and browser/HTML (D3.js) back-ends, see section 5.4. Further data output formats including NeXus are available, see section 5.5.
5.1 Brief introduction to the graphical user interface
5.2 Running the instrument compiler
5.2.1 Code generation options
5.2.2 Specifying the location of files
5.2.3 Embedding the generated simulations in other programs
5.2.4 Running the C compiler
5.3 Running the simulations
5.3.1 Choosing an output data file format
5.3.2 Basic import and plot of results
5.3.3 Interacting with a running simulation
5.3.4 Optimizing simulation speed
5.3.5 Optimizing instrument parameters
5.4 Using simulation front-ends
5.4.1 The graphical user interface (mxgui)
5.4.2 Running simulations on the commandline (mxrun)
5.4.3 Interactive notebooks (mcxtrace-jupylab)
5.4.4 GPU acceleration via OpenACC
5.4.5 Graphical display of simulations (mxdisplay)
5.4.6 Plotting the results of a simulation (mxplot)
5.4.7 Creating and viewing the library, component/instrument help and Manuals (mxdoc)
5.4.8 Self-testing the installation (mxtest, mxviewtest)
5.5 Data formats - Analyzing and visualizing the simulation results
5.5.1 The McXtrace/McCode text format
5.5.2 NeXus format
5.6 Using MPI for parallel computing
5.6.1 Parallel computing (MPI)
5.6.2 McRun options for MPI
5.6.3 McXtrace/MPI Performance
5.6.4 MPI Bugs and limitations
5.0.1 Important note for Windows users
It is a known problem that some of the McXtrace tools do not support filenames / directories with spaces. We recommend avoiding spaces in the paths used for McXtrace work directories and instrument files. As of McXtrace 3.x, all tools (mxgui, mxrun, mxplot, mxdisplay, …) are pure Python and are bundled with the conda-forge package, so no separate Perl installation is required on any platform, including Windows.
