McXtrace logo

McXtrace - An X-ray ray-trace simulation package
Synchrotron SOLEIL DTU Physics

McXtrace

About McXtrace
 Publications
 Project Partners
 Project People
 Goal

Download
 Components

Documentation
 Manual
 Commands
 Wiki (GitHub)
 Tutorial

Mailing list

Links

Search

Code-repository (GitHub)

Report bugs (GitHub)

McXtrace - Monte Carlo Xray Tracing, is a joint venture by

DTU_logo.gif Soleil.png

Our code is based on technology from mcstas_logo_thumb.png

Code repository (shared with 'McStas') is located at github.com/mccode-dev

For information on our progress, please subscribe to our user mailinglist..

Recent McXtrace News

Migrating from McXtrace 1.x to 3.x? - Use the wiki-based guides

September 11th, 2026: McStas and McXtrace 3.8.4 released

Installation

Changes in McStas/McXtrace 3.8.4

Covers everything since the last full release, 3.7.9 (July 2, 2026), including all changes already shipped quietly via the intermediate conda-forge releases 3.7.10–3.8.3, and a ground-up rewrite of the McStas/McXtrace manuals.

Sorry for any incovenience caused if you installed any of 3.8.1-3... Some doc-details were still not in place!

What's Changed

Common to McStas and McXtrace

Manuals

  • First full manual makeover since the McStas 2.x / McXtrace 1.x series. Tool-usage chapters (mcrun/mxrun, mcplot, mcdisplay, mcgui, mcdoc, ...) rewritten against the actual CLI code; component reference/parameter tables now generated directly from the current .comp sources (closing a long-standing manual/code drift); mcdoc itself reworked to support it. By @willend in #2592
  • Numerous long-standing inaccuracies fixed along the way: RNG engine description (KISS default / MT optional), obsolete components now explicitly labelled as such, stale legacy sections removed, http->https, and a batch of LaTeX build-pipeline fixes; McXtrace manual also had McStas copy-paste leftovers removed and its "running"/RNG sections aligned with McStas's — all by @willend in #2592
  • AI-assisted: reference material and source code (usage articles, grammar/cogen.c, example instruments, component sources, tool CLIs) were given to an AI coding agent to draft the updated text, reviewed and merged by @willend. Given the scale of the rewrite, minor errors/omissions in the manuals are expected — please flag anything you spot via a GitHub issue
  • mcdoc's browser-based overview page now also links to per-tool cheat-sheets (mcrun, mcgui, mcplot, mcdisplay, mctest, mcdoc, code generators) and to new standalone Instrument/Component grammar reference pages, all a click away from the component browser by @willend

New links in mxdoc. Also visible on this website:
Documentation overview page
Tool documentation overview
INSTRUMENT grammar
COMPONENT grammar

New tooling

  • New tools mcplotdiff-html/mcplotdiff-pyqtgraph/mcplotdiff-matplotlib: plot the difference between two simulation results, monitor by monitor (diff.monN = a.monN - b.monN), with a diverging blue/white/red colour scale for 2D monitors and diff datasets written out as normal, reopenable McCode .dat files by @willend in #2560, #2562, #2564 — later reworked to show %-difference in #2599 and to always write diff datasets in #2585
    • mcviewtest now spawns mcplotdiff-html automatically by @willend in #2568
  • New tools mccoplot-html/mccoplot-pyqtgraph/mccoplot-matplotlib: companion to mcplotdiff, overlaying two (or more) datasets' 1D monitors on the same axes for direct curve comparison by @willend in #2587, with n-way overlay support in #2594 and a McXtrace-side fix in #2589
    • mcviewtest also spawns mccoplot generation by @willend in #2588, #2595
  • mctest: added -s/--seed option and an option to emulate McCode's classic "Unix epoch" default seed, for reproducible test runs by @willend in #2575, #2576
  • mctest: new --strict mode fails a test if an instrument is missing its %Example: header line(s) by @willend in #2602 (spillover-bug fix in #2604), plus general robustness improvements in #2603 and a GPU-box-specific fix in #2613
  • mctest: fixed TypeError on re-runs caused by displaytime never being restored from the saved JSON state by @mads-bertelsen-agentic in #2624
  • mcplot-html: added a slider to control plot iframe size, and geometry/scaling adjustments, by @willend in #2547, #2548, #2549, #2550
  • Fix issue #2561 — make 2D-plot colourbars visible in more cases by @willend in #2563
  • Speed up execution of mcplot-matplotlib (especially for large 2D matrices) by @willend in #2570
  • Matplotlib-plotters: fix for non-draggable legends by @willend in #2614
  • mcrun/mxrun: allow multiscan -M with list-scan -L and new scan/list syntax par=a:delta:b for both -N and L modes by @willend in #2618
  • Plottable mccode.dat in the NeXus-scan case by @willend in #2619
  • mcgui/mxgui: non-numeric entries in nsteps are now deferred to mcrun for interpretation instead of rejected up front by @willend in #2625
  • mcdoc: list %Example: lines in bold by @willend in #2636
  • Minor tweak on mcviewtest — tolerate a trailing / in ref path by @willend in #2593

Code generator & grammar

  • RNG correctness fix: the KISS generator's 7-word per-particle random state was only partially backed up/restored across a SPLIT loop (silently corrupting RNG state), and the Mersenne-Twister seed was never actually applied at start-up due to a stale RNG_ALG check — both fixed by @mads-bertelsen-agentic in #2620
  • Cogen: simplify COPY(instance) to no longer transfer EXTEND et al. by @willend in #2627 (two affected instruments updated in #2640)
  • Enable mcstas-antlr in McCode GitHub CI by @willend in #2610
  • Edits for increased compatibility with mcstas-antlr by @willend in #2612
  • Consequence-edits from antlr-compatibility: add missing pragmas by @willend in #2616
  • Add input parameters to base .py instrument generated by mccode-pygen by @willend in #2601
  • Implement pygen-suggestion from @MilanKlausz (#2554) by @willend in #2555
  • Fix for collision between stdlib:: syntax and mcrun min:delta:max scan syntax by @willend in #2626
  • Fix issue #2606 + other unneeded use of GETPATH() by @willend in #2609
  • [Ref] move static comparison out of the hot TRACE path by @g5t in #2591 — a good general reminder that a WHEN(...) clause runs once per particle, so precomputing a flag in INITIALIZE beats a strcmp() in TRACE

Infrastructure / build system / CI

  • New CMake FetchContent integration for Greg Tucker's mcstas-chopper-lib by @willend in #2631, with a test instrument added in #2632
  • Consolidate conda/non-conda 'basictest' workflows and use with new mcviewtest by @willend in #2577
  • Minor bugfixes for testsuite-workflows/nightlies by @willend in #2578, #2581
  • Back to 1e6, testsuite workers are killed by time-limit by @willend in #2582
  • Let testsuite run with 2 cores on macOS, auto elsewhere by @willend in #2583
  • Use mpi=2 on macOS also in basictests by @willend in #2586
  • Include GitHub worker id as unique identifier for datasets by @willend in #2598
  • Trigger 'RUNALL' if > 4 comps were changed by @willend in #2641
  • Suppress use of cif2hkl in Test_Powders by @willend in #2634
  • Repair 'autobuild' download of 'innosetup' installer by @willend in #2573
  • Release doc updates 3.7.9 by @willend in #2545
  • Update pullrequesttemplate.md by @willend in #2559
  • Update notebook template to reflect McStasScript 0.0.89 properties by @willend in #2580
  • CI: various workflow fixes by @willend in #2615
  • Minor instrument header fixes + plug missing README.md's by @willend in #2639
  • Rectification of Windows batch-wrappers by @willend in #2566, #2567

McStas only

  • New instrument: import of FRMII_SPODI / FRMII_SPODI_MULTI, a powder diffractometer at MLZ Garching (contributed by V. Kochetov, C. Hauf, M. Hoelzel and A. Senyshyn) by @kinetik161 in #2608 — enabled to run on GPU/OpenACC by @willend in #2623
  • New instruments: import of 3 x imaging instruments from various sources (PSI_ICON, Radiography_Lithium_Battery, Radiography_Sword) by @willend in #2569
  • New components (via mcstas-chopper-lib, see FetchContent integration above): Masked_ESS_butterfly and NXdisk_chopper, with their test/example instruments Masked_ESS_butterfly_image, NXdisk_chopper_display and NXdisk_chopper_image, courtesy of @g5t's mcstas-chopper-lib — installed directly into the normal mcstas-comps/contrib and examples/Tests_optics locations, so they appear in mcdoc/mcgui like any other McStas component
  • PowderN: remove erroneous order parameter by @Lomholy in #2622
  • Sans spheres intensity fix by @Lomholy in #2600
  • ILL_SALSA: fix linter and add n reflections to parameters by @Lomholy in #2572
  • Patch issue #2637 — Vertical_Bender gravity always disabled by @MilanKlausz in #2638
  • Union: add nowritefile parameter to all Union loggers and abs_loggers by @mads-bertelsen-agentic in #2607
  • Work on ESS source description / comparison with MCPL inputs by @willend in #2596
  • Fix for compilation failure of ESS/MCPL instrument under openacc by @willend in #2597
  • Use filenames in MCPL instrument Monitor_nD instances to get rid of timestamps by @willend in #2574
  • Add another MCPL_output -> producing neutrons in instrument coordinate frame by @willend in #2629
  • MCPL file was moved - update instrument file by @willend in #2630

McXtrace only

  • McXtrace: work toward fixing #2514 (GPU) by @willend in #2556
  • Likely fix for McXtrace / Abs_objects test on GPU by @willend in #2557
  • WORKAROUNDS: disable key tests in McXtrace (#2514) by @willend in #2558
  • Filter.comp: better handling of non-standard input files by @willend in #2552
  • Fix for mxcoplot-html McXtrace by @willend in #2589

New Contributors

  • @kinetik161 made their first contribution in #2608
  • @mads-bertelsen-agentic made their first contribution in #2624
  • @MilanKlausz made their first contribution in #2638

Full Changelog: https://github.com/mccode-dev/McCode/compare/v3.7.9...v3.8.4

July 2nd, 2026: McStas and McXtrace 3.7.9 released

Changes in McStas/McXtrace 3.7.9, July 2nd, 2026

Release 3.7.9 marks a milestone for McXtrace that finally gets full support for complex number calculations using MSVC on Windows. We further improve the installation experience on Windows by addition of a new install script for downloading and setting up the MSVC compiler tool chain.

Install instructions

What's Changed

Common to McStas and McXtrace

Platform suppport

  • Windows
    • mctest / windows output improvement by @willend in #2505
    • batch-script to help install msvc on Windows by @willend in #2505
    • Add micromamba clean --all -y in install batches by @willend in #2507
    • Improved wording for README and add non-admin option to msvc-install script by @willend in #2508
    • Add git when setting up dev-env on Windows by @willend in #2510
  • Tools
    • mctest:
    • mcplot-html
    • mcdisplay:
      • Pass at key points in mcdisplay particleparser instead of raising exceptions. by @willend in #2516
    • mcrun
      • New --dirsuffix/--dirprefix switches for mcrun/mxrun by @willend in #2533
  • Shared lib-codes

McStas only

  • Minor comp / instrument improvements

McXtrace only

  • General
    • Support for MSVC (and complex numebers via mccode-complex-lib) on Windows
  • Comp / instrument improvements
    • McXtrace: Fix of #1579 for most (if not all) comps/instrs by @willend in #2504
    • McXtrace test target updates by @willend in #2515
    • Various fixes for McXtrace instruments by @willend in #2520
    • Filter.comp is in fact incomplete for refraction and shape != cube. by @willend in #2522
    • Temporary hack to avoid McXtrace cif2hkl fct. in Single_crystal on Windows by @willend in #2524
    • Windows/cif2hkl issue workaround for Test_PowderN by @willend in #2525
    • Various changes to stabilise McXtrace SOLEIL_PX2a tests by @willend in #2526
    • More McXtrace tweaks, SOLEIL_PX2a and SOLEIL_PSICHE by @willend in #2527
    • Beef up required stats for SOLEIL_PSICHE + adjust target val by @willend in #2528
    • McXtrace Enable all tests in Test_Mirrors by @willend in #2529
    • Fix header by @willend in #2530
    • Fix of McXtrace/mxdisplay of specific instr by @willend in #2533
    • Fix filter geometry by @ebknudsen in #2534
    • Improve on flexibility of McXtrace Filter.comp input types by @willend in #2543

Full Changelog: v3.7.6...v3.7.9

June 16th, 2026: McXttrace and McStas 3.7.6 released

Installation:

See McXtrace install pages on GitHub for details

What's Changed

Common to McXtrace and McStas:

Tools

  • mxgui/mcgui list mode scanning:
    • Support mxrun -L scan mode via mxgui 'Scan steps' entry by @willend in #2493
  • Small but important improvements to mxdisplay/mcdisplay:
    • pyqtgraph variant:
      • Restore various click/keyboard control across PyQt5/PyQt6
      • Improvements to mxdisplay(-pyqtgraph) component list (do not underflow main window) by @willend in #2489
      • Fix missing PyQt5->PyQt6 correction for mxdisplay-pyqtgraph by @willend in #2481
      • Fix of another mxdisplay-pyqtgraph PyQt6 vs PyQt5 bug by @willend in #2485
    • matplotlib variant:
      • Silence mxdisplay-matplotlib noise when pressing 'q' by @willend in #2483
    • Common, parsing-system:
      • Fix for rare bug: Add fflush(stdout) protection of DEBUG_COMPONENT (fix #2486) by @willend in #2487

Libraries

  • KDSource functional in mingw builds (+other minor improvements) by @willend in #2497 (comes with both McStas and McXtrace even though KDSource.comp is McStas-only for now
  • Get rid of 'dirent' dependency on Windows systems

Installers

McStas only:

Components

McXtrace only:

  • No McXtrace-specific comp/instr changes

Infrastructure, common to McStas/McXtrace:

Full Changelog: v3.7.1...v3.7.6

May 22nd, 2026: McXtrace and McStas 3.7.1 released

Installation instructions

What's Changed

Main new developments:

Common McXtrace and McStas developments:

  • Up to 10 USERVARS supported with Monitor_nD (named user0,...,user9)
  • Qt5 -> Qt6 across the package and dependencies
  • Bugfix: Fix of rare visualisation bug in mcdisplay/mxdisplay (e.g. box was not allowed as a comp name)
  • Doc improvements:
    • mcdoc/mxdoc can render .tex and .md in addition to .html
    • Example instruments come with an in-repo README.md generated via this mechanism
    • See e.g. McStas BNL_H8 or McXtrace ESRF ID01
  • CI/test improvements:
    • mcdisplay/mxdisplay visualisation is performed as part of mctest/mxtest runs (-> CI)
    • See top html files in McStas and McXtrace nightly test runs

McXtrace specific developments:

McStas specific developments:

  • Integrated support for KDSource
    • New component KDSource
    • For usage details, see example instrument Test_KDSource and the KDSource documentation website
    • Available as automatic dependency on conda-forge based installations (including macOS and Windows 'installers'
    • Not available as .deb package on Debian systems but may function by installing via pip.
      Recommendation: Just use conda-forge.
  • Pulse-length adjustment available for ESS_butterfly
  • PowderN now supports NCrystal cfg-strings.
    • Forwards request to NCrystal that populates datastructures without intermediate .laz/.lau files
    • See example instrument Test_Powders - comp=0 mode
  • Bugfixes:
    • Fix to Union, orientation of loggers wrt. master comp
    • Bugfixes to recently added improved Union mesh
  • Contributions from NBI/KU:
  • McStas component manual uses .tex snippets from generated via components mcdoc

New Contributors

Full Changelog: v3.6.14...v3.7.1

April 13th, 2026: McXtrace and McStas 3.6.14 released

Installation instructions

What's Changed
(Selected items, please consult the GitHub changelog for full set)

New comps/instruments

  • Adding the ILL SANS instrument 'SAM' by @nmgm in #2388

New tool feature: NeXus scans become entries in one common HDF file

  • Prototype solution to allow 'append' mode for datasets by @willend in #2376

Various updates to instruments/components/data files

Various tool improvements

  • mctest / timeout system - ensure to kill underlying processes by @willend in #2363
  • Add timers for maximal compile / runtime in mctest by @willend in #2356
  • Add hints for alternative mcdisplay visualisation in Jupyter... by @willend in #2353
  • mcrun -L list was broken, fixed here by (re-)calculating number of elements … by @willend in #2377
  • Changed (hard-coded) mcgui 3D visualiser to be webgl-classic by @willend in #2381
  • On Windows use psutil for probing number of available cores in MPI by @willend in #2367

Other changes

Please consult the GitHub changelog

  • Fixes to various bugs
  • LaTeX in doc headers
  • Clang-format formatting of component syntax
  • Various updates to project infrastructure: PR template, CI etc.
  • Various GPU related fixes

New Contributors

Full Changelog: v3.6.5...v3.6.14

March 31st: First circular: PHOTONS AND NEUTRONS REALISTIC ARTIFICIAL INTELLIGENCE DATASETS (PaNRAID)

Dear Colleagues,

In collaboration with the French DIADEM Academy, we invite interested participants to attend the following course in September:

PHOTONS AND NEUTRONS REALISTIC ARTIFICIAL INTELLIGENCE DATASETS (PaNRAID)

Dates: 21-25 September
Location: Île d’Oléron, France

Objective

The course will develop an integrated approach for generating synthetic data for supervised learning. This approach combines multi-scale materials simulations (DFT, MD, XAS spectroscopy) with comprehensive digital twins of experimental X‑ray and neutron facilities, explicitly accounting for instrumental effects and experimental artefacts.

Intended audience

  • Doctoral students
  • Postdoctoral researchers
  • Faculty and teaching-research staff
  • Researchers and research engineers

Further information and pre-registration: https://formation.pepr-diadem.fr/formation-panraid

Attached are PDF flyers in French and English.

Best regards,
Peter Willendrup

March 28th, 2026: McXtrace 1.x and McStas 2.x formally out of support

Dear all,

We have decided to formally declare that we no longer support McXtrace 1.x and McStas 2.x, so user issues with these released will from now on always prompt us to request that you upgrade.

If you are still running such an old release, please upgrade and port your comps/instruments using the information in the use the wiki-based porting-guides

We are of course at your service if you have issues porting your existing code, please create a GitHub issue.

January 7th, 2026: McStas and McXtrace 3.6.5 released


McStas and McXtrace release 3.6.5 is now available.
McXtrace installation instructions are found on GitHub .

What's Changed - Main Changes:

Bugfixes, new features, all common to McStas and McXtrace:

  • macOS bundles in 3.6.1 did not actually install that version but something earlier. Fixed by pinning in yml file, @willend in #2285
  • PDF manuals had wrong version numbers, @willend in #2285
  • Allow mcrun / mcdisplay to run / visualize without access to .c/.instr by @willend in #2281
  • mcgui/mxgui editable font colors, handle long filenames without extreme window resizing by @willend in #2275
  • Fix cross-platform sort-order issue in PowderN by @willend in #2272
  • Platform-independent reflection list sort in Single_crystal by @willend in #2273
  • mcrun/mxrun: feature addition - scan by seed by @willend in #2276
  • Add mcplot toggle to "plot 1D-curves from 0-value" in linear mode by @willend in #2278
  • Add commentstring to vim editor by @Lomholy in #2284

Other stuff

  • %Example adjustments, McXtrace by @willend in #2269
  • Test_SANS/Test_SAXS, supplement stats by x10 SPLIT by @willend in #2270
  • Use ${{ matrix.mpi }} to ensure different output dirs by @willend in #2271
  • Fix indentation bug - issue #2279 by @willend in #2280
  • Temporarily disable this instr from McXtrace tests by @willend in #2283

Full Changelog:https://github.com/mccode-dev/McCode/compare/v3.6.1...v3.6.5

2025, 2024, 2023, 2022, 2021, 2020 and older News mailto:webmaster@mcxtrace.org

Last Modified: Friday, 11-Sep-2026 15:00:02 CEST
Search website mailinglist archive GitHub repos