About McStas
Conditions of use
Authors/Contacts
Project funding
Download
Components
Other Downloads (share)
Documentation
Wiki (GitHub)
McStas manual
Publications
McStas - A neutron ray-trace simulation package
|
| The plot shows the intensity of scattered neutrons (red is
highest intensity). The sample is at the center of the sphere with the
neutron beam coming from the left. Clearly seen is the shadowing effect
of the sample causing a lower intensity opposite the beam. Also seen is
the effect of the non-symmetric geometry of the sample, causing lower intensity
directly above and to the side of the sample. |  |
Simulated
scattering from a hollow-cylinder Recent news
Migrating from McStas 2.x to 3.x? - Use the wiki-based guides
September 11th, 2026: McStas and McXtrace 3.8.4 released
Installation
- For McStas proceed to the McStas install docs (GitHub)
- For McXtrace proceed to the McXtrace install docs (GitHub)
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.compsources (closing a long-standing manual/code drift);mcdocitself 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 mcdoc. Also visible on this website:
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.datfiles by @willend in #2560, #2562, #2564 — later reworked to show %-difference in #2599 and to always write diff datasets in #2585mcviewtestnow spawnsmcplotdiff-htmlautomatically by @willend in #2568
- New tools
mccoplot-html/mccoplot-pyqtgraph/mccoplot-matplotlib: companion tomcplotdiff, 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 #2589mcviewtestalso spawnsmccoplotgeneration by @willend in #2588, #2595
mctest: added-s/--seedoption and an option to emulate McCode's classic "Unix epoch" default seed, for reproducible test runs by @willend in #2575, #2576mctest: new--strictmode 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 #2613mctest: fixedTypeErroron re-runs caused bydisplaytimenever being restored from the saved JSON state by @mads-bertelsen-agentic in #2624mcplot-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-Mwith list-scan-Land new scan/list syntaxpar=a:delta:bfor both -N and L modes by @willend in #2618- Plottable
mccode.datin the NeXus-scan case by @willend in #2619 mcgui/mxgui: non-numeric entries in nsteps are now deferred tomcrunfor interpretation instead of rejected up front by @willend in #2625mcdoc: 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
SPLITloop (silently corrupting RNG state), and the Mersenne-Twister seed was never actually applied at start-up due to a staleRNG_ALGcheck — both fixed by @mads-bertelsen-agentic in #2620 - Cogen: simplify
COPY(instance)to no longer transferEXTENDet al. by @willend in #2627 (two affected instruments updated in #2640) - Enable
mcstas-antlrin McCode GitHub CI by @willend in #2610 - Edits for increased compatibility with
mcstas-antlrby @willend in #2612 - Consequence-edits from antlr-compatibility: add missing pragmas by @willend in #2616
- Add input parameters to base
.pyinstrument generated bymccode-pygenby @willend in #2601 - Implement pygen-suggestion from @MilanKlausz (#2554) by @willend in #2555
- Fix for collision between
stdlib::syntax andmcrunmin:delta:maxscan 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 inINITIALIZEbeats astrcmp()in TRACE
Infrastructure / build system / CI
- New CMake
FetchContentintegration for Greg Tucker'smcstas-chopper-libby @willend in #2631, with a test instrument added in #2632 - Consolidate conda/non-conda 'basictest' workflows and use with new
mcviewtestby @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=2on 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
cif2hklinTest_Powdersby @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_butterflyandNXdisk_chopper, with their test/example instrumentsMasked_ESS_butterfly_image,NXdisk_chopper_displayandNXdisk_chopper_image, courtesy of @g5t'smcstas-chopper-lib— installed directly into the normalmcstas-comps/contribandexamples/Tests_opticslocations, so they appear inmcdoc/mcguilike any other McStas component - PowderN: remove erroneous
orderparameter 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_Bendergravity always disabled by @MilanKlausz in #2638 - Union: add
nowritefileparameter 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_nDinstances 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_objectstest 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-htmlMcXtrace 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
- For McStas 3.7.9
- For McXtrace 3.7.9
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:
- mcrun
- Shared lib-codes
- Provide SCATTER_func for libraries to replicate SCATTER functionality by @mads-bertelsen in #2535
McStas only
- Minor comp / instrument improvements
- Exit minus 1 harmonization by @willend in #2503
- Fix for Incoherent component limited order + hollow geometry by @mads-bertelsen in #2506
- Various fixes for FZJ_BenchmarkSfin2/SANS_benchmark2 by @willend in #2517
- ILL_H15_SAM.instr: Common SPLIT=100 at sample(s) ensure ncount >=1e7 by @willend in #2518
- Ensure 1e7 for non-display runs of ILL_H22_D1B by @willend in #2519
- Various fixes for McXtrace and McStas instruments by @willend in #2520
- Various fixes for McXtrace instruments by @willend in #2520
- Added mcdisplay section to FlatEllipse_finite_mirror component by @mads-bertelsen in #2521
- Fix ascii reallocation in Union_mesh by @mads-bertelsen in #2532
- H frielinghaus SANS_benchmark2 input files by @willend in #2536
- Fix #2537: Bug in PSD_monitor_4PI found by BSc. student Christian Thyssen NBI. by @willend in #2538
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: McStas and McXtrace 3.7.6 released
Installation:
See McStas install pages on GitHub for details
What's Changed
Common to McStas and McXtrace:
Tools
mcgui/mxguilist mode scanning:- Small but important improvements to
mcdisplay/mxdisplay:pyqtgraphvariant:- Restore various click/keyboard control across PyQt5/PyQt6
- Improvements to mcdisplay(-pyqtgraph) component list (do not underflow main window) by @willend in #2489
- Fix missing PyQt5->PyQt6 correction for mcdisplay-pyqtgraph by @willend in #2481
- Fix of another mcdisplay-pyqtgraph PyQt6 vs PyQt5 bug by @willend in #2485
matplotlibvariant:- Common, parsing-system:
Libraries
- KDSource functional in mingw builds (+other minor improvements) by @willend in #2497 (comes with both McStas and McXtrace even though
KDSource.compis McStas-only for now - Get rid of 'dirent' dependency on Windows systems
Installers
- New MSVC-based installer-bundle for both McStas and McXtrace, will eventually fully replace the MinGW installer-bundle
- See McStas windows install page for details
- See McXtrace windows install page for details
McStas only:
Components
McXtrace only:
- No McXtrace-specific comp/instr changes
Infrastructure, common to McStas/McXtrace:
- Fixes to installdocs by @willend in #2476
- Various work on GitHub actions by @willend in #2488
- Give mctest a --displaymax handle by @willend in #2495
- Prepare for 3.7.6 release by @willend in #2498
Full Changelog: v3.7.1...v3.7.6
May 22nd, 2026: McStas and McXtrace 3.7.1 released
Installation instructions
- For McStas go to The McStas install page on GitHub
- For McXtrace go to The McXtrace install page on GitHub
What's Changed
Main new developments:
Common McStas and McXtrace developments:
- Up to 10
USERVARSsupported withMonitor_nD(nameduser0,...,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/mxdoccan render.texand.mdin addition to.html- Example instruments come with an in-repo
README.mdgenerated via this mechanism - See e.g. McStas BNL_H8 or McXtrace ESRF ID01
- CI/test improvements:
McStas specific developments:
- Integrated support for KDSource
- New component
KDSource - For usage details, see example instrument
Test_KDSourceand the KDSource documentation website - Available as automatic dependency on
conda-forgebased installations (including macOS and Windows 'installers' - Not available as .deb package on Debian systems but may function by installing via pip.
Recommendation: Just useconda-forge.
- New component
- Pulse-length adjustment available for
ESS_butterfly- Handled via specifically named instrument input parameter and
DEPENDENCYline - See example instrument
ESS_butterfly_Adjustable_Pulse
- Handled via specifically named instrument input parameter and
PowderNnow supportsNCrystalcfg-strings.- Forwards request to
NCrystalthat populates datastructures without intermediate.laz/.laufiles - See example instrument Test_Powders -
comp=0mode
- Forwards request to
- Bugfixes:
- Fix to Union, orientation of loggers wrt. master comp
- Bugfixes to recently added improved Union mesh
- Contributions from NBI/KU:
Inhomogenous_incoherent_processin Union from @Lomholy, (via ‘tinyexpr' string-expression inputs) - see rel. test instrument- New spinwave comp
SpinWave_BCOfrom @SSBNS - see rel. test instrument - ESS KVASIR instrument proposal - backend instrument with MCPL input from BIFROST optic. @AmalieFalkenberg. Includes Jupyter notebook in McStasScript syntax.
- McStas component manual uses
.texsnippets from generated via componentsmcdoc
McXtrace specific developments:
- Much improved Union subsystem for McXtrace by @ebknudsen. Makes use of Xraylib for Compton and Rayleigh scattering models.
- Test instruments for the new Union processes, both from @ebknudsen
- PowderCompton_union - Compton scattering and powder diffraction
- Test_KN_Comp_Rayl_union - test instrument using Klein-Nishina, Rayleigh, or Compton
scattering processes.
New Contributors
- @SSBNS made their first contribution in #2373
- @AmalieFalkenberg made their first contribution in #2345
Full Changelog: v3.6.14...v3.7.1
April 13th, 2026: McStas and McXtrace 3.6.14 released
Installation instructions
- For McStas go to The McStas install page on GitHub
- For McXtrace go to The McXtrace install page on GitHub
What's Changed
(Selected items, please consult the GitHub changelog for full set)
New comps/instruments
New tool feature: NeXus scans become entries in one common HDF file
Various updates to instruments/components/data files
- Fix Union mcdisplay bugs by @Lomholy in #2294
- Fix to MPI-mode use of Brilliance Transfer calculation. by @willend in #2300
- Minor instrument and comp updates, McStas by @willend in #2332
- More %Example tests for McStas instruments by @willend in #2333
- More additions of McStas %Example lines by @willend in #2337
- Update of McXtrace Incoherent_process comp from EBK branch by @willend in #2338
- Add more %Example lines to McStas instruments by @willend in #2341
- Add Test instrument for Be-filter models by @willend in #2349
- Re-enable a few tests on the nightlies by @willend in #2364
- ESS_butterfly: Wrap all printf / fprintf in MPI_MASTER( ); by @willend in #2372
- Updated Rubredoxin lau file from @aaronfinke by @willend in #2384
- Updated Example values following updated Rubredoxin.lau by @willend in #2386
- Adapt Guide_m interface -> style of Guide_gravity parameters by @willend in #2389
- McStas Monitor_nD “nexusbins” only in listmode by @willend in #2387
- Mono bent complex string parsing by @Lomholy in #2395
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: McStas 2.x and McXtrace 1.x formally out of support
Dear all,
We have decided to formally declare that we no longer support McStas 2.x and McXtrace 1.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.
Dear all,
In connection with a user request I realised that occasionally we may all benefit from easier access to old McStas variants.
I have therefore put together a "Best of McStas compilation" - a Linux image with McStas version 1.12c, 2.7.2 and the latest 3.6.8.
You can give the image a quick trial spin via binder:
Or alternatively pull docker.io/mccode/mcstas_v1.12c_v2.7.2_v3.6.8:latest via Docker / podman / etc., i.e. something like
Best and hope this may be useful,
Screenshot of the running compilation:
What's Changed - Main Changes:
Full Changelog:https://github.com/mccode-dev/McCode/compare/v3.6.1...v3.6.5
Previous news items: 2025, 2024,
2023, 2022, 2021,2020,2019, 2018, 2017, 2016,
2015, 2014, 2013,
2012, 2011, 2010, 2009,
2008, 2007, 2006,
2005, 2004, 2003, 2002, 2001, 2000, 1999,
1998.
March 13th, 2026: "Best of McStas compilation"
https://mybinder.org/v2/gh/mccode-dev/jupyter-mcstas-mcxtrace-desktop/HEAD?urlpath=desktop
(will not in practice sustain much actual work / load)
podman run -p 8888:8888 docker.io/mccode/mcstas_v1.12c_v2.7.2_v3.6.8:latest
Peter
January 7th, 2026: McStas and McXtrace 3.6.5 released
McStas and McXtrace release 3.6.5 is now available.
McStas installation instructions are found on GitHub .
Bugfixes, new features, all common to McStas and McXtrace:
Other stuff
