McStas - A neutron ray-trace simulation package

McStas is a general tool for simulating neutron scattering instruments and experiments. It is actively supported by DTU Physics, NBI KU, ESS, PSI and ILL.

Simulated scattering from a hollow-cylinder vanadium sample.

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.

Recent news

Migrating from McStas 2.x to 3.x? - Use the wiki-based guides

December 12th, 2025: McStas and McXtrace 3.6.1 released

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

What's Changed - Main Highlights:

Overall release focus:

Code quality improvements: Suppression of warnings from c-compilers and our static code analysis tool cppcheck
Continuous integration improvement: Any change in instrument/component code is tested via GitHub CI features

New tool features / capabilities:

mcrun/mxrun simulation launch tool: (@willend)
- Scans can be parallelised at the "step number" level, use --scan_split. Contribution from @Lomholy.
- If installed, cppcheck can be used to perform static code analysis on the generated code, use -C/--c-lint?
- Improved string-handling in input parameters, e.g. in use with NCrystal config strings. Contribution from @tkittel.
mcplot/mxplot simulation plot tools: (@willend)
- Better support for 'intermediate saves' done via kill -USR2 or Progress_bar, and plots should work on an unfinished simulation.
- Plotting a completed simulation with 'intermediate saves' will give you latest plot version in the 2D case and multiple, overplotted curves in the 1D case
- The mcplot-matlab/mxplot-matlab tool is back. You need to manually install either Matlab or Octave to make use of this
mcdisplay/mxdisplay instrument visualisation tools: (@willend)
- On conda-based installations, the mcdisplay-cad/mxdisplay-cad tool includes the cadquery dependency. On completion of building the model, the OS is asked to handle the resulting CAD model.
- The mcdisplay-matlab/mxdisplay-matlab tool is back. You need to manually install either Matlab or Octave to make use of this
- For better integration with McStasScript, the mcdisplay-webgl-classic/mxdisplay-webgl-classic is used in such scenarios
- The 'newer/fancy' mcdisplay-webgl/mxdisplay-webgl based on THREE.js, react and other javascript requires a slightly time-consuming installation process on 1st launch. The user now gets an info box about this.
- The McStas-specific mcdisplay-mantid IDF generator tool received a bug fix for OFF geometry detectors.
mcdoc/mxdoc documentation tool: (@willend)
- Higher quality / more complete comp/instr doc pages
mctest/mxtest test tool: (@willend)
- Easier to use locally for component/instrument developers

Components and instruments:

McXtrace:

The Fluorescence components have a new flag to enhance statistics/signal from low concentration materials. Work by @farhi.

McStas:

The Union subsystem now handles 'surface physics' with the introduction of a system of refraction/reflection processes on geometry surfaces. Work by @mads-bertelsen.
The Union subsystem now has a functional 3D-mesh system (Union_mesh) that supports CAD style geometries. (Ascii/binary STL files and OFF files are supported. - For now only those with triangular meshing.) Work by @Lomholy.
As part of the overall code-quality improvement process, various aspects of the Union subsystem have been tested / improved / revised. Contributions by @tkittel and @willend in close collaboration with @mads-bertelsen.
New ISIS-related instrument files, components and data:
- ISIS_LET by Ross Stewart and Rob Bewley, serves as test-instrument for Commodus_I3 (ISIS source model - corresponds to ViewModISIS with a different parameter interface)
- Updated / larger set of input files for the ISIS moderator components
- Multilayer_sample from Rob Dalgliesh was updated with nrepeats which allows to repeat an SLD material stack. ISIS_CRISP was updated to include this feature.
- TOF_PSDmonitor_toQ is a new component with built-in data reduction from Rob Dalgliesh. Uses ToF to calculate Q. Test_TOF_PSDmonitor_toQ is a basic instrument to showcase the component.
Several of the basic McStas sample components received a systematic validation against analytical methods, thanks to @Lomholy with help from KU/NBI students.
As part of the overall code-quality improvement process, the whole component / instrument base got a BIG overhaul as such (@willend)

Platform support:

The Windows/conda platform which uses the MSVC compiler is now fully functional for all McStas code and a good part of the McXtrace code. As part of this process a new header-file mccode-complex-lib.h should be used by all code requiring complex numbers. (Implements functions for e.g. +-*/ operations across platforms - MSVC does not self implement these operations...) @willend

For all release details, please refer to the github release page for version 3.6.1

Seasons greetings from all of McStas/McXtrace - and hope you will enjoy this new release!
Peter Willendrup

June 17th, 2025: McStas and McXtrace 3.5.32 released

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

What's Changed

Common changes to McStas and McXtrace

Deployment, platforms and CI
- [Bugfixes] to Windows conda script and related README by @willend in#1976 #1978, #1984, #1985, #1986
- [CI] Let "autobuild" CI scripts create arm64 debs for mccode.org by @willend in #1981
Tools:
- [Feature] mcgui/mxgui: show current instrument name in dialogues by @farhi in #1989
- [Feature] VSCode McStas/McXtrace grammar extension
  - Update vs code extension by @Lomholy in #1975
  - Small updates to editor, as well as updated installation information by @Lomholy in #1977
- [Feature] LaTeX math (formulae etc) for mcdoc %Description headers by @willend in #2054
Code generator/Grammar:
- [Feature] Unified McStas/McXtrace, c and .py code generators defined from common set of files in mccode/src
  - Unify grammar take2 by @willend in #2008
  - Unify instr y c py: unify our code generators for C and Python by @farhi in #2009
- [Feature] NEW INHERIT keyword in the component grammar: Allows to mix and match component sections from multiple components to achieve new functionality.
  For an example use see
  - Grammar multiple comp copy extend by @farhi in #2012 (-> INHERIT)
  - FluoPowder in McXtrace
  - https://github.com/mccode-dev/McCode/blob/main/doc/GRAMMAR/ADR-records/ADR_20250612_INHERIT_COMP.md
  - Edits by @farhi and @willend in #2062
- [Feature] Add ADR (Architectural Design Record) for grammar changes
  - Add doc folder for proposed, accepted, rejected, deprecated, superseded changes of McCode GRAMMAR by @willend in #2064
  - Put in place folder for grammar documentation by @willend in #2070
- [Feature] The McStas/McXtrace code generators have a new commandline switch --version-num to print the version number only.
- [Feature] New CLI default for mcstas / mcxtrace: --trace is on (This allows any compiled instrument to run with --trace=0 by @willend in #2010 and #2023)
Libs and runtime (various minor changes)
- Add Open_File in header (used from e.g. PowderN) by @willend in #2014
- Wrap cabs in OpenACC settings by @willend in #2016
- Swap default trace behaviour to 'enabled' by @willend in #2023
- cif2hkl: update to solve F^2 for Xrays using latest CrysFML by @farhi in #2021
- Openacc minor rectifications by @willend in #2027
MCPL Components
- [Feature] Update MCPL components for MCPL 2.2.0 features (including stat:sum). by @tkittel in #2046
- [Feature] Sync MCPL components McStas <-> McXtrace for MCPL 2.2.0 support by @willend in #2019
- [Feature] Please consult the GitHub discussion on MCPL > 2.0 support in McStas / McXtrace

McStas specific:

[Bugfix] Source_custom
- Fixed minor typo in docs by @pablogila in #1980
- Fixed pulse normalisation for all values of n by @pablogila in #2024
- Simplified redundant code for the peak integral calculation by @pablogila in #2025
[Bugfix and feature] Resolution sample/monitor
- Reso: Updates by @tweber-ill in #1992
- Add infrastructure to save calculated resolution/covariance matrices by @willend in #1993
- Sync Res_monitor <-> TOFRes_monitor by @willend in #1995
[Bugfix] Add mcresplot to debian metapackage by @willend in #2022
[Bugfix] Monitor_nD pixel id and buffer fix by @mads-bertelsen in #2002
[Bugfix] Add exit attenuation to Incoherent.comp for finite order scattering by @Lomholy in #2042
[Bugfix] Updates to Monochromator_bent from @Lomholy by @willend in #2059 and #2058

McXtrace specific:

[Features and bugfixes] McXtrace fluorescence:
- McXtrace: fix header doc in fluo sample (powder and SX) by @farhi in #1974
- McXtrace fluo fix pow 0 by @farhi in #1979
- McXtrace fluo fix 2 by @farhi in #1988
- McXtrace fluo fix : fix in powder select - use gaussian line shape by @farhi in #1994
- McXtrace: samples: fluo: add M-lines via XrayLib Kissel CSb calls by @farhi in #2004
- McXtrace: samples: fluo: fix again the Fluo share by @farhi in #2005
- McXtrace add fluo mcdisplay by @farhi in #2015
- McXtrace fluo add detector 0 by @farhi in #2029
[Bugfix] Fix compilation of McXtrace Test_PowderN instr by @willend in #2000
[Bugfixes] McXtrace various example instrument updates by @farhi in
- #2033, #2034, #2045, #2048, #2051, #2056, #2057
[Bugfix] cif2hkl: update to solve F^2 for Xrays using latest CrysFML by @farhi in #2021
[Feature]McXtrace: add SWING BL at SOLEIL by @farhi in #2036

Full Changelog: https://github.com/mccode-dev/McCode/compare/v3.5.27...v3.5.32

April 29th, 2025: McStas and McXtrace 3.5.27 released

Dear all,
McStas and McXtrace release 3.5.27 is now available.
McStas installation instructions are found on GitHub .

What's Changed - common McStas/McXtrace highlights:

[Feature] McStas and McXtrace are now fully on conda-forge also for Windows, since MCPL 2.0 arrived.
This means that we now recommend to install via this mechanism on Windows. See the instructions for details.
[Feature] mcrun/mxrun have a new -y switch which runs a given instrument using its default parameters.
[BUGFIX] mcplot/mxplot should now deal better with negative / very small numbers in 'log' mode plotting.
[Feature] mcgui/mxgui improved tooltips on the run dialogue.
[Feature] rootmccode works with newer versions of ROOT
[BUGFIX] The KISS random number generator was earlier running with systematically different random numbers (and a shorter period) on Windows.
Identical instruments now run with identical random numbers across platforms, when using identical seed.
[CI, packaging, platform support] Lots of work behind the scenes for portability, packaging, and improved CI of the code on GitHub.
Better standard solutions and easier possibility of spotting when/if we make errors!

What's Changed - McStas specific highlights:

[BUGFIX] As reported on mcstas-users, reflective/transmissive polarisers/analysers could sometimes lead to |P|>1.
This is now fixed by ellimination of "non-up-down" polarisation components when measuring an "up-down" polarisation.
[Feature] Contributed component Source_custom by @pablogila, useful features for simulatiung e.g. CANS and other pulsed sources.
Comes with corresponding new test instrument.

What's Changed - McXtrace specific highlights:

[Feature] New components for Fluorescence + Single_crystal and Fluoresence + Powder.
Come with corresponding new test instruments.

For a full list of changes, please consult the CHANGES or GitHub release notes

April 6th, 2025: Component doc pages back online

We are now in the air with new server hardware.

Among other things this means that component mcdoc pages are back online - by popular demand!

April 5th, 2025: Ongoing webserver upgrade

We are in the process of upgrading the webserver for McStas, McXtrace and other sites. Please bear with us if you experience service interruptions. :-)

February 19th, 2025: McStas and McXtrace 3.5.24 released

Dear all,
McStas and McXtrace release 3.5.24 is now available - McStas installation instructons on GitHub .

What's Changed

Important note

McStas and McXtrace will soon change organisation-name on GitHub - from McStasMcXtrace -> mccode-dev

User interfaces and tools

[Feature] mcgui/mxgui Let configuration dialogue spawn your EDITOR to edit your local mccode_config.json by @willend in https://github.com/mccode-dev/McCode/pull/1838 (available also by --edit-user-config from mcrun/mxrun)
[Feature] mcrun/mxrun: New switch --cogen to allow on-demand switch to non-standard code generator. See also interoperability with mccode-antlr below by @willend in https://github.com/mccode-dev/McCode/pull/1851
[Feature] mcrun/mxrun Solution for picking up code generator from PATH if not found where expected by @willend in https://github.com/mccode-dev/McCode/pull/1840
[Feature] pygen minor revision: Build importable make() function and call from generic notebook by @willend in https://github.com/mccode-dev/McCode/pull/1827
[Fix] Support Scintilla editor on Debian with Qt6 by @willend in https://github.com/mccode-dev/McCode/pull/1813
[Fix] Drop hard-coded check for PyQt5 by @willend in https://github.com/mccode-dev/McCode/pull/1814
[Fix] No more hidden Perl dependencies! (perl -> python 1-liner readlinkf()) by @willend in https://github.com/mccode-dev/McCode/pull/1824
[Fix] too-restrictive mcdisplay/mxdisplay instrument line parsing by @g5t in https://github.com/mccode-dev/McCode/pull/1834
[Fix] Patches for mcdisplay/mxdisplay in Windows from @LelandWH https://github.com/mccode-dev/McCode/issues/1853

Components and instruments

[Fix] McStas Vertical_bender: Add max iteration criterion for while loop (default 1000). by @willend in https://github.com/mccode-dev/McCode/pull/1815
[Fix] McStas NCrystal_sample: Remove possible out-of-bounds memory access by @g5t in https://github.com/mccode-dev/McCode/pull/1821
[Fix] McStas Elliptic_guide_gravity and Pol_mirror: Minor comp revisions, suppresses compilation warnings from clang by @willend in https://github.com/mccode-dev/McCode/pull/1826
[Fix] McStas SNS_ARCS.instr edits by @willend in https://github.com/mccode-dev/McCode/pull/1838
[Fix] McStas ISIS_IMAT.instr DEPENDENCY " @NEXUSFLAGS@ " added by @willend in https://github.com/mccode-dev/McCode/pull/1839
[Fix] McStas Union_master Adjustment of default parameter by @willend in https://github.com/mccode-dev/McCode/pull/1840
[Fix] McStas Union-related fixes and imports from DMSC school by @willend in https://github.com/mccode-dev/McCode/pull/1841
[Fix] McStas Elliptical_guide_gravity did not work in GROUPS as it always SCATTERS by @mads-bertelsen in https://github.com/mccode-dev/McCode/pull/1843
[Fix] Monitor_nD on GPU: Adjustments for coherence between CPU and GPU particle lists by @willend in https://github.com/mccode-dev/McCode/pull/1816

Core simulation toolkit

[Feature] NeXus: sort comp instances by index and include comp parameter information by @willend in https://github.com/mccode-dev/McCode/pull/1828
[Fix] Increased stability in NeXus x wide MPI by @willend in https://github.com/mccode-dev/McCode/pull/1811
[Fix] Portability, Windows + cl.exe: Remove variable length array allocations for issue #1817 by @g5t in https://github.com/mccode-dev/McCode/pull/1819 and https://github.com/mccode-dev/McCode/issues/1818 by @willend in https://github.com/mccode-dev/McCode/pull/1822

Interfaces and interoperability with other codes

NCrystal

Thanks to @tkittel for ping-pong on this :)
[Feature] McStas 3.5.24 and later now depends on NCrystal 4.0.0 and later. NCrystal is now available also on Windows! by @willend in https://github.com/mccode-dev/McCode/pull/1848 and https://github.com/mccode-dev/McCode/pull/1855

`mccode-antlr`

Thanks to @g5t for ping-pong on this :)
[Feature] mccode-antlr is an alternative code-generator for McStas and McXtrace - a new development by @g5t and based on ANTLR instead of lex/yacc. The new tool is mainly written in python and thus has a lower barrier for changes in language syntax and code generation. The tool implementations mcstas-antlr and mcxtrace-antlr are thus a candidate implementations to potentially replace the classic mcstas and mcxtrace code generators in the future. Current status is that
- McStas: mcstas-antlr is fully feature complete wrt. mcstas for CPU simulations and close to complete for GPU simulations
- McXtrace: Not all instruments will compile using mcxtrace-antlr but basic functionality is in place
- To try:
  1. Install mccode-antlr from conda-forge or via pip
  2. Adapt your configuration to use e.g. mcstas-antlr by
    - Setting the new --cogen=mcstas-antlr option in mcrun
    - Enable or edit the MCCOGEN field of mccode_config.json using the new Save/Edit configuration in mcgui
    - (The antlr tools default to download comps etc. to an internal cache: Add e.g. -I${MCSTAS} to prefer ingredients fromyour local library)
  3. Use the mcrun-antlr/mxrun-antlr tools provided directly by mccode-antlr

Platform support

Debian/Ubuntu
- [Fix] Make hidden numpy dependency explicit also on Debian by @willend in https://github.com/mccode-dev/McCode/pull/1825
- [Fix] McXtrace meta-pkgs for Debian add libgsl-dev as dependency by @farhi in https://github.com/mccode-dev/McCode/pull/185
Windows
- [Feature] NCrystal is now available with McStas on Windows
- [Info] Windows via cross-compiled .exeinstaller from mccode.org: Please place the MCPL-related .bat files from the extras folder in e.g. c:\mcstas-3.5.24\bin to enable MCPL (May require giving your user 'full access' permissions to the bin folder)
- [Info] Windows via conda-forge: MCPL is not yet available but expected during the spring

Full Changelog: https://github.com/mccode-dev/McCode/compare/v3.5.16...v3.5.24

January 8th, 2025: Monte Carlo Satellite to ICNS2025

Dear all,

The ICNS2025 conference is taking place in Copenhagen and Lund this summer, and the abstract submission is closing January 15th - in one week.

Of special interest to McStas users:
A satellite event is being planned for July 11th, arranged by Mads Bertelsen, ESS and Peter Willendrup DTU/ESS. We envision a one-day event with contributed talks on instrument simulation and its use, abstract submission will open soon:

Advanced computer simulations methods for neutron scattering instruments

Abstract:
Neutron scattering relies heavily on computer simulations of neutron scattering instrumentation to optimize their performance. These simulation tools are also evolving to be more relevant for a running facility, aiding in both preparation and analysis for individual experiments. It is even becoming possible to make better decisions during experiments by running simulations in parallel.

All the best and hope to see you this summer in Copenhagen,
Peter Willendrup

Previous news items: 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.

Printable version

Last Modified: Friday, 12-Dec-2025 12:15:02 CET