McStas/McXtrace v3.8.4

[willend]

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 AI Documentation revamp #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 AI Documentation revamp #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 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 New tool: mcplotdiff-html, render difference plots between two datasets #2560, New tool: mcplotdiff-pyqtgraph, render difference plots between two datasets (follow-up for #2560) #2562, New tool: mcplotdiff-matplotlib, render difference plots between two datasets (follow-up for #2562) #2564 — later reworked to show %-difference in mcplotdiff-* reengineered to show %-difference in diff-plots #2599 and to always write diff datasets in Let the HTML diffplotter write "diff datasets" #2585
  • mcviewtest now spawns mcplotdiff-html automatically by @willend in mcviewtest: spawn the new mcplotdiff-html plotter #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 New tools: mccoplot folder_A/ folder_B/  #2587, with n-way overlay support in Coplot solution with n x coplots #2594 and a McXtrace-side fix in Fix for mxcoplot-html McXtrace  #2589
  • mcviewtest also spawns mccoplot generation by @willend in Let mcviewtest spawn coplot generation also #2588, Fix mcviewtest syntax for calling mccoplot after updates #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 Add -s --seed option to mctest #2575, Add option to "emulate" McCode default 'Unix epoch' seed in mctest #2576
• mctest: new --strict mode fails a test if an instrument is missing its %Example: header line(s) by @willend in Add --strict mode for mctest: fail if no %Example: line(s) #2602 (spillover-bug fix in Fix spillover-issue in --strict mode #2604), plus general robustness improvements in Various improvements for mctest #2603 and a GPU-box-specific fix in Fix for mctest issue seen on GPU box #2613
• mctest: fixed TypeError on re-runs caused by displaytime never being restored from the saved JSON state by @mads-bertelsen-agentic in Fix mctest TypeError on re-runs: displaytime never restored from JSON #2624
• mcplot-html: added a slider to control plot iframe size, and geometry/scaling adjustments, by @willend in More html plotter tweaks (m*plot-html, as used from mctest) #2547, Add slider for control of iframe size #2548, More html plotter tweaks #2549, Final adjustment of geometry/scaling for mcplot-html #2550
• Fix issue [BUG]: mcplot-pyqtgraph does not show colorbars on overview plots in mixed 1D/2D plots #2561 — make 2D-plot colourbars visible in more cases by @willend in Fix issue 2561 - make 2D-plot colorbars visible in “more” cases #2563
• Speed up execution of mcplot-matplotlib (especially for large 2D matrices) by @willend in Speed up execution of mcplot-matplotlib (especially for big 2D matrices) #2570
• Matplotlib-plotters: fix for non-draggable legends by @willend in Matplotlib-plotters: Fix for non-draggable legends #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 mcrun: allow multiscan -M with list -L #2618
• Plottable mccode.dat in the NeXus-scan case by @willend in Plottable mccode.dat in NeXus scan case #2619
• mcgui/mxgui: non-numeric entries in nsteps are now deferred to mcrun for interpretation instead of rejected up front by @willend in If non-numeric entries appear in mcgui / nsteps - defer interpretation to mcrun #2625
• mcdoc: list %Example: lines in bold by @willend in Mcdoc list percent examples in bold #2636
• Minor tweak on mcviewtest — tolerate a trailing / in ref path by @willend in Minor tweak on mcviewtest - tolerate trailling ‘/‘ in ref #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 Fix MT random seed and SPLIT KISS random state restore #2620
• Cogen: simplify COPY(instance) to no longer transfer EXTEND et al. by @willend in Cogen: Simplify COPY(instance) to not transfer EXTEND et al. #2627 (two affected instruments updated in Adapt two affected instruments for consequences of 2627 #2640)
• Enable mcstas-antlr in McCode GitHub CI by @willend in Enable mcstas-antlr in McCode GitHub CI #2610
• Edits for increased compatibility with mcstas-antlr by @willend in Edits for increased compatibility with mcstas-antlr #2612
• Consequence-edits from antlr-compatibility: add missing pragmas by @willend in Consequence-edits from antlr-compatibility: add pragmas #2616
• Add input parameters to base .py instrument generated by mccode-pygen by @willend in Add input parameters to base .py instrument generated by mccode-pygen #2601
• Implement pygen-suggestion from @MilanKlausz ([FEATURE]: Support input_path in generated make() functions from mcstas-pygen #2554) by @willend in Implement pygen-suggestion from @MilanKlausz(#2554) #2555
• Fix for collision between stdlib:: syntax and mcrun min:delta:max scan syntax by @willend in Fix for collision between stdlib:: syntax and mcrun min:delta:max #2626
• Fix issue [BUG]: ESS_BEER_MCPL.instr GETPATH(data) DEPENDENCY is no longer needed #2606 + other unneeded use of GETPATH() by @willend in Fix issue 2606 + other unneeded use of GETPATH() #2609
• [Ref] move static comparison out of the hot TRACE path by @g5t in [Ref] move static comparison out of hot TRACE path #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 FetchContent solution for mcstas-chopper-lib from Greg Tucker #2631, with a test instrument added in Add test for fetched instr from @g5t chopper-lib #2632
• Consolidate conda/non-conda 'basictest' workflows and use with new mcviewtest by @willend in Consolidate conda/non-conda ‘basictest’ workflows and use with new mcviewtest #2577
• Minor bugfixes for testsuite-workflows/nightlies by @willend in Minor bugfixes for testsuite-workflows / nightlies #2578, Tweaks to stabilise test output from in workflows #2581
• Back to 1e6, testsuite workers are killed by time-limit by @willend in Back to 1e6, testsuite workers are killed by time-limit #2582
• Let testsuite run with 2 cores on macOS, auto elsewhere by @willend in Let testsuite run with 2 cores on macOS, auto elsewhere #2583
• Use mpi=2 on macOS also in basictests by @willend in Use mpi=2 on macOS also in basictests #2586
• Include GitHub worker id as unique identifier for datasets by @willend in Include github worker id as unique identifier for datasets #2598
• Trigger 'RUNALL' if > 4 comps were changed by @willend in Trigger 'RUNALL' if > 4 comps were changed. #2641
• Suppress use of cif2hkl in Test_Powders by @willend in Suppress use of cif2hkl in Test_Powders #2634
• Repair 'autobuild' download of 'innosetup' installer by @willend in Repair 'autobuild' download of 'innosetup' installer #2573
• Release doc updates 3.7.9 by @willend in Release doc updates 3.7.9 #2545
• Update pull_request_template.md by @willend in Update pull_request_template.md #2559
• Update notebook template to reflect McStasScript 0.0.89 properties by @willend in Update notebook template to reflect McStasScript 0.0.89 properties #2580
• CI: various workflow fixes by @willend in CI: Various workflow fixes #2615
• Minor instrument header fixes + plug missing README.md's by @willend in Minor instr header fixes + plug missing README.md's #2639
• Rectification of Windows batch-wrappers by @willend in Rectification of windows batch-wrappers #2566, Correction of batch-wrapper snippets #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 Add instrument examples of SPODI (FRMII) powder diffractometer #2608 — enabled to run on GPU/OpenACC by @willend in Allow recent FRMII SPODI contributions to run on GPU/ OpenACC #2623
• New instruments: import of 3 x imaging instruments from various sources (PSI_ICON, Radiography_Lithium_Battery, Radiography_Sword) by @willend in Import 3 x imaging instruments from various sources #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 PowderN remove erroneous order parameter #2622
• Sans spheres intensity fix by @Lomholy in Sans spheres intensity fix #2600
• ILL_SALSA: fix linter and add n reflections to parameters by @Lomholy in ILL_SALSA fix linter and add n reflections to parameters #2572
• Patch issue [BUG]: Vertical_Bender (contrib): dangling if/else silently disables gravity regardless of -g #2637 — Vertical_Bender gravity always disabled by @MilanKlausz in Patch issue #2637 - Vertical_Bender gravity always disabled #2638
• Union: add nowritefile parameter to all Union loggers and abs_loggers by @mads-bertelsen-agentic in Add nowritefile parameter to all Union loggers and abs_loggers #2607
• Work on ESS source description / comparison with MCPL inputs by @willend in Work on ESS source description / comparison with MCPL inputs #2596
• Fix for compilation failure of ESS/MCPL instrument under openacc by @willend in Fix for compilation failure ESS/MCPL instrument, openacc #2597
• Use filenames in MCPL instrument Monitor_nD instances to get rid of timestamps by @willend in Use filenames in MCPL instrument Monitor_nD instances to get rid of timestamps #2574
• Add another MCPL_output -> producing neutrons in instrument coordinate frame by @willend in Add another MCPL_output -> producing neutrons in instr coordinate frame #2629
• MCPL file was moved - update instrument file by @willend in MCPL file was moved - update instrument file #2630

McXtrace only

• McXtrace: work toward fixing [BUG]: McXtrace and GPU: Indications of thread collisions / undefined behaviour #2514 (GPU) by @willend in McXtrace: Work toward fixing #2514 (GPU) #2556
• Likely fix for McXtrace / Abs_objects test on GPU by @willend in Likely fix for McXtrace / Abs_objects test on GPU #2557
• WORKAROUNDS: disable key tests in McXtrace ([BUG]: McXtrace and GPU: Indications of thread collisions / undefined behaviour #2514) by @willend in WORKAROUNDS: Disable key tests in McXtrace (#2514) #2558
• Filter.comp: better handling of non-standard input files by @willend in McXtrace Filter.comp: Better handling of non-standard inputfiles #2552
• Fix for mxcoplot-html McXtrace by @willend in Fix for mxcoplot-html McXtrace  #2589

New Contributors

• @kinetik161 made their first contribution in Add instrument examples of SPODI (FRMII) powder diffractometer #2608
• @mads-bertelsen-agentic made their first contribution in Fix mctest TypeError on re-runs: displaytime never restored from JSON #2624
• @MilanKlausz made their first contribution in Patch issue #2637 - Vertical_Bender gravity always disabled #2638

Full Changelog: v3.7.9...v3.8.4

---

This discussion was created from the release McStas/McXtrace v3.8.4.