McXtrace logo

McXtrace - An X-ray ray-trace simulation package

Synchrotron SOLEIL DTU Physics


About McXtrace
 Project Partners
 Project People


 Wiki (GitHub)

Mailing list



Code-repository (GitHub)

Report bugs (GitHub)

McXtrace 1.7.1 and McXtrace 3.1 released

[16/12/2022]Dear all, A new PAIR of releases of McXtrace:

McXtrace "classic" v. 1.7.1
McXtrace "next-generation", v. 3.1
are both built and ready for download!

Download and installation instructions are available via our GitHub INSTALL-doc pages.

Selected highligts from the releases are listed below. The full list of changes for both releases is also available at our CHANGES_McXtrace document

Please start your migration to 3.x:

McXtrace 1.7.1 is very likely the "last update" to the 1.x series, sharing a subset of tool features with McXtrace 3.1. The Wiki has a dedicated section on McXtrace 1.x -> McXtrace 3.x conversion that includes:

- If you are still in trouble, please write us a GitHub issue or an email to

Release highligts
(!!3.1 only denotes features or improvements that are 3.1 specific!!)

  • Documentation & guides:
    • The component pages now include an extra column in the parameter-table. When filling in this column with wanted values, plus filling the entry-boxes for AT, ROTATED and instance name, pressing "Generate" will put a code-snipet for your component instance directly on your computer clipboard, for easy transfer to the mxgui editor or any other editor of choice!
    • mxdoc has been made "less picky" wrt. component and instrument structure for a more robust experience.
    • mxgui has a new "Docs" button for easier access to the generated mxdoc pages (that give easy access to components, instruments, manuals, datafiles and more.
  • Interoperability with other codes:
    • We have worked on the interface with MCPL (v. 1.6.1 included) and a mechanism was developed to automatically detect its location using the mcpl-config util. In practice this happens prior/during to the code-generation step, see below under mxrun. Thanks to Thomas Kittelmann (ESS) for your help in this area.
  • Tools:
    • mxrun has a new solution to support 3 new keywords CMD(), ENV() and GETPATH() through the DEPENDENCY line as collected by the code-generator. (see CHANGES doc for more details)
    • As mentioned above, mxdoc has been made "less picky" wrt. component and instrument structure and enriched with JavaScript for easy transfer of information to you editor.
    • mxplot(-pyqtgraph) has received a nice update with an infobar at the bottom of the window. The infobar is updated with coordinates of the cursor on the active plot, meaning that you can easily determine the coordinates of e.g. a peak. The code has also received a number of bugfixes relating to colorbars, the order of monitor output in overviews etc. Thanks to Tobias Weber (ILL) for your work on mxplot.
    • 3.1 only: The new mxdisplay-cad variant has come along, and is currently included in the form of a technology-preview. The code uses the Python module cadquery ( and is able to write e.g. STEP or STL output. For now, resolving the required dependencies is left to the user, but we foresee that this tool will mature over the coming releases. Thanks to Greg Tyler (ESS) for contributing this tool.
  • Components and Instruments:
    • 3.1 only: Most of the standard monitors will now fill in their own "instance name" as filename in case a filename was not defined. A small but very useful convenience.
    • The Isotropic_Sqw sample which can be used to model structure and dynamics in isotropic materials, such as powders and liquids has been added. The component is developed by Emmanuel Farhi and also exists in the McStas code. The component is currently in "Experimental" state in McXtrace.
    • Multiple new SOLEIL instruments have been added, thanks to lots of work from Antoine Pado, Stephane Bac and Emmanuel Farhi:
      • SOLEIL_ANATOMIX.instr tomography beam-line
      • SOLEIL_DISCO.instr in the imaging mode
      • SOLEIL_MARS.instr in the XRD mode
      • SOLEIL_PX2a.instr protein crystallography beam-line
    • The AstroX toolbox for simulating X-ray telescopes has been included as a special component category.3.1 only: GPU support in the related components/instruments is newly developed and likely not perfect in all cases.
    • Lens_elliptical.comp fixed
    • Grating_reflect.comp fixed, and created a test for it.
    • Udated/fixed Mirror_elliptic.comp and created a test for it.
    • Beamline ssrl 11-2 (in it's unfocused and uncollimated mode) added (related to work done on glitches).
    • Czerny_Turner instrument created.
    • Single_crystal component, corrected absorption cross-section.
  • Core and libs:
    • 3.1 only: Previously, any component present in a McXtrace instrument would trigger the transformation of every photon to its local coordinate system, even in the case of an Arm() (empty TRACE) without an EXTEND block. We now instead detect components with an empty TRACE that have no EXTEND block and are able to completely skip these in the calculation. This results in a speedup in case of instruments with many "empty" components. Thanks to Mads Bertelsen (ESS) for investigating the problem and finding a good solution.
    • 3.1 only: A new syntax called SHELL has been added to the grammar, allowing users to run a system command prior to code-generation. This may for instance be used to generate an instrument-snippet that you may %include in the instrument (think for-loops of an assembly of identical components). One could also imagine compilation of a needed library, wget of a data file etc. The synax is SHELL "command-to-execute" and it should be placed directly after a DEPENDENCY line within an instrument or component. We expect that applications and examples will come in the next couple of releases.
    • 3.1 only: Components may from McXtrace 3.1 request USERVARS that become part of the particle struct. (For the time being only in the form of basic C types like double, int etc. and corresponding arrays / pointers.) This will mean that e.g. the optimisations in Single_crystal and PowderN in SPLIT scenarios can be introduced also in GPU settings.
    • A flaw was spotted in our NeXus implementation in the case of event lists: A small chunk-size of (1,6) was used, leading to slow I/O and lots of size-overhead. Thanks to Simon Heybrock (ESS) for spotting this!

    We still support 64bit Windows 10/11 on Intel, all recent 64bit macOS including 11.x - 13.x Monterey on both Intel and Apple Silicon/M1 processors. Debian/Ubuntu-based distros on Intel and Arm, our RPM-based distro is Fedora on Intel. (Official support for CentOS has been dropped, but you should be able to "roll your own" from the src packages.)

    Our Docker and binder containers will be updated within the following weeks.

    We hope you will enjoy these new releases!!!

    macOS 13 Ventura

    Dear all,

    If you upgrade to macOS 13 Ventura (intel/x86_64), your already installed Python tools of McXtrace 1.7 / 3.0 and /Application bundles may not work after the upgrade.

    A workaround is to:

    • In a terminal, start your "McXtrace shell" (e.g. run mcxtrace-3.0-environment, /Applications/McXtrace-3.0-environment.command or /Applications/
    • Issue the command
      export PATH=$MCXTRACE/miniconda3/bin:$PATH
    • Next, you may issue the mxgui command

    New releases 1.7.1 and 3.1 are in preparation and should be released during November or December.

    another Python 3.10 / pyqtgraph issue in current releases

    [01/11/2022] Dear all,

    Several users have reported "yet another Python issue" that arise in current releases of McXtrace (1.7 / 3.0). After following the advice from September 23rd to replace mxgui/ and mccodelib/, mxplot-pyqtgraph fails with

    mxplot error: scale(self): too many arguments
    Traceback (most recent call last):
    File "C:\mcxtrace-1.7\lib\tools\Python\mxplot\pyqtgraph\", line 67, in 
    File "C:\mcxtrace-1.7\lib\tools\Python\mxplot\pyqtgraph\", line 57, in main
    raise e
    File "C:\mcxtrace-1.7\lib\tools\Python\mxplot\pyqtgraph\", line 51, in main
    File "C:\mcxtrace-1.7\lib\tools\Python\mcplot\pyqtgraph....\mccodelib\", line 62, in runplot
    plot_node(node, self.plot_func, plt_layout, viewmodel)
    File "C:\mcxtrace-1.7\lib\tools\Python\mcplot\pyqtgraph....\mccodelib\", line 144, in plot_node
    viewbox_lst.append(add_plot(layout, node, plot_func, i, n, viewmodel))
    File "C:\mcxtrace-1.7\lib\tools\Python\mcplot\pyqtgraph....\mccodelib\", line 382, in add_plot
    view_box, plt_itm = plot_node_func(node, i, plt, options)
    File "C:\mcxtrace-1.7\lib\tools\Python\mcplot\pyqtgraph\", line 33, in plot
    view_box, lyt = plot_Data2D(data, plt, log=opts['log'], legend=opts['legend'], icolormap=opts['icolormap'],
    File "C:\mcxtrace-1.7\lib\tools\Python\mcplot\pyqtgraph\", line 203, in plot_Data2D
    TypeError: scale(self): too many arguments'
    To fix this issue, please replace your

    New releases 1.7.1 and 3.1 are in preparation and should be released during November or December.

    Python 3.10 issues in current releases

    [23/09/2022] Dear all,

    We have recently become aware of a couple of issues that arise with all current releases of McXtrace (1.7 / 3.0)

    On system with the newest Python versions (3.10 and beyond) you may experience that

    In case you experience these problems you may replace the following files within your installation folder:

    • $MCXTRACE/tools/Python/mxgui/ - please replace by this new version
    • $MCXTRACE/tools/Python/mccodelib/ - please replace by this new version

    New stable releases of McXtrace should be released during November/December this year.

    Best and sorry for the inconvenience,

    Peter Willendrup

    New ready-to-run McXtrace box in a browser

    [18/02/2022] Dear all, we are happy to provide a ready-to-run system with McXtrace pre-installed. It typically pulls-out an 8-cores computer running at Binder, for free, with both McXtrace 1.7 and 3.0 (with MPI multi-core support but no GPU). Perfect for running McXtrace from anywhere, for training/schools/workshops.

    Start it in a single click here:

    (Please note that load-time can be a couple of minutes.)



    The above docker image has been pushed to dockerhub and can also be run locally at your machine using docker:
    • Install docker (if needed)
    • docker run -p 8888:8888
    • Connect your browser to the URL communicated by the docker command

    Updated RPM metapackages for McXtrace 3.0

    [09/02/2022] Dear all,

    If you were fast enough to try out installing McXtrace 3.0 already yesterday on your CentOS or Fedora system, you may have come across some installation issues, as the mcxtrace-suite-python-ng packages had a couple of shortcomings.

    Updated packages have now been uploaded, please use yum clean and yum reinstall to have access to the updates.

    McXtrace 3.0 is released

    [08/02/2022] Dear all,

    The McXtrace team is happy to announce that our McXtrace 3.0 "next generation" release is now available.

    McXtrace 3.0 is the first release in the 3.0 series with a completely rewritten code-generator and thereby support for GPU-acceleration through the OpenACC programming model.

    We have seen speedups of 1-2 orders of magnitude over the CPU version, depending on the computational Problem / complexity.


    • Thanks to: all members of the team (and also to the McStas team), for pulling together to make this possible.
    • Thanks to the mentors at the GPU Hackathons that really made this happen
    • Thanks to NVIDIA for making the hackathons happen


    • Installation instructions for McXtrace-3.0 and support libraries may be found on our the McCode github-site
    • OpenACC acceleration is at present available out of the box on Linux.
    • On windows it is possible to target GPU-acceleration through Windows Subsystem For Linux v2: WSL2.
    • The present McXtrace-3.0 implementation relies the concept managed memory, which is at the time of writing only supported by the Linux version of the NVHPC-kit (downloadable from

    For more information on the GPU-features of the release, please consult the CHANGES_McXtrace document on GitHub and the section "Migrating from McStas 2.x to 3.x (and McXtrace 1.x to 3.x)" in our McCode wiki

    Happy simulation!

    McXtrace 1.7 is released

    [25/01/2022] Dear simulators, The team is happy to announce that McXtrace 1.7 is out!

    1.7 has been focused mainly on stability and bugfixes, but also provides a set of new features. Binary packages are provided for the main platforms: Debian /Ubuntu, Fedora, Windows 10, Mac OSX (arm and intel based). As is the presenty custom, see for speecific installation instructions for you platform.

    Please also keep an eye out for the for upcoming release of McXtrace 3.0, which is a technology preview release of an improved code-generator enabling McXtrace to run on GPUs.

    Happy simulation!

    CHANGES in McXtrace 1.7

    1. Improved installation scripts
      1. Installs cleanly on Mac silicon
    2. Updated examples:
      1. MAXIV_DanMAX_pxrd1d.instr
      2. MAXIV_DanMAX_pxrd2d.instr
    3. New examples:
      1. SOLEIL ROCK beamline.
      2. ESRF BM29 skeleton beamline.
      3. Example of Air-scattering block.
      4. Test example for the GROUP langnuage feature
      5. Union demo test example
      6. New Example of Compton scattering union process.
    4. Updated Components
      1. PowderN.comp: Fix bug with faulty packing factor logic, which lead to wrong intensities when used with SPLIT.
      2. Lens_parab_Cyl_rough.comp, Lens_parab_rough.comp, Lens_Kinoform.comp: documentation issues
      3. Mirror.comp: documentation update
      4. Mirror_curved.comp, Mirror_elliptic.comp: Use reflectivity library
      5. Mirror_toroid.comp: Fix for stable handling of reflectivity file
      6. Absorption_sample.comp: Fix inner/outer volume logic
      7. Source_genesis13.comp, Source_simplex.comp: Documentation issues.
      8. Air.comp: Correct scattering amplitude.
      9. New: Laue_crystal_BC.comp: experimental model of a Laue crystal available for testing.
    5. Updated libraries:
      1. Reflectivity-lib has a series of bugfixes.
    6. New tools:
      1. Test tool for component writers' convenience.
      2. Scripts for generating reflectivity files.
    7. License change: The release includes a switch to the GPLv3-license for McXtrace. The underlying reason for this is to help collaboration wih the Debian project.

    2020 and older News

    Last Modified: Thursday, 06-Jul-2023 10:17:03 CEST
  • Search website mailinglist archive GitHub repos