McStas logo McStas - A neutron ray-trace simulation package ILL; PSI; ESS Niels Bohr Institute DTU Physics NEXMAP


About McStas
 Conditions of use
 Project funding

 Other Downloads (share)

Mailing list

Search web/mailinglist

 Wiki (GitHub)
 McStas manual


Report bugs (GitHub)

Code-repository (GitHub)

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 20th, 2022: Minor update on the new releases

For 2.7.2 users on arm64 macOS - if you downloaded before December 20th:
Yesterday, a small mishap in the macOS Silicon / arm64 release of McStas 2.7.2, it actually contained a set of 3.x binaries and tools.
A fresh build of 2.7.2 for arm64 macOS was immediately uploaded.

For Ubuntu users where your browser can not access the documentation:
Please consult for a solution

For those of you on CentOS (v8):
We have decided to released a last set of packages:
- This will be the last packages released for CentOS and are not offered from the repo - they must be manually installed.

December 12th, 2022: McStas 2.7.2 and McStas 3.2 released

Dear all, A new PAIR of releases of McStas:

  • McStas "classic" v. 2.7.2
  • McStas "next-generation", v. 3.2
are both built and ready for download!

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

Selected highlights from the releases are listed below. The full list of changes for both releases is also available at

Please start your migration to 3.x:

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

Fixes of issues from last releases:
A good number of issues from the earlier 2.7.1 and 3.1 releases were addressed, see the relevant GitHub issues for details:
Full 2.7.1 issue list
Full 3.1 issue list

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

  • Documentation & guides:
    • 3.2 only: All 3.2 component and instrument headers have been given an overhaul and should render correctly in mcdoc / your browser.
    • 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 mcgui editor or any other editor of choice!
    • mcdoc has been made "less picky" wrt. component and instrument structure for a more robust experience.
    • mcgui has a new "Docs" button for easier access to the generated mcdoc pages (that give easy access to components, instruments, manuals, datafiles and more.
  • Interoperability with other codes:
    • We have worked on the interfaces with MCPL (v. 1.6.1 included) and NCrystal (v. 3.5.1 included) and a mechanism was developed to automatically detect their location using the mcpl-config and ncrystal-config utils. In practice this happens prior/during to the code-generation step, see below under mcrun. Thanks to Thomas Kittelmann (ESS) for your help in this area.
  • Tools:
    • mcrun 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, mcdoc has been made "less picky" wrt. component and instrument structure and enriched with JavaScript for easy transfer of information to you editor.
    • mcplot(-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 mcplot.
    • 3.2 only: The new mcdisplay-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:
    • The Union framework is now considered a fully "official" part of McStas and is hence now found in the $MCSTAS/union folder. In McStas 3.2 Union_master is a still a NOACC component when running on GPU (i.e. performs its calculations on CPU in FUNNEL mode). We expect Union_master to receive full GPU suport within 2023. The NCrystal_process.comp is back in Union on 3.2 - will work only in a NOACC/CPU COMPONENT setting.
    • By popular demand, the ConicTracer code for simulating Wolter optics from Boris Khaykovich et. al. (MIT) has been included. The main "library" code is conic.h found in $MCSTAS/share and is used from 3 different example Wolter optic components: Conics_EH.comp, Conics_PH.comp, Conics_PP.comp. The illustrate how to mplement Elliptic-Hyperbolic, Parabolic-Hyperbolic and Parabolic-Parabolic Wolter mirrors, and two of these are used in the Test_Conics_pairs.instr instrument.
    • 3.2 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.
    • Source_div_quasi.comp allows to sample source phase-space using Halton-sequences, which proves to be a very effective way to ensure an evenly distributed phase space region of interest, e.g. for imaging/SANS settings where a very low-divergent beam is relevant. This contribution is from Mads Carlsen and Erik B. Knudsen (DTU) and was originally developed for McXtrace.
    • PSD_Pol_monitor.comp measures (local) polarisation over the (x,y) cross-section of a beam. Contributed by Alexander Backs (LU/ESS).
    • 3.2 only: Single_crystal_inelastic.comp (NOACC), Single_magnetic_crystal.comp (NOACC), SANS_benchmark2.comp and Guide_multichannel are now all available in the McStas 3 series. Also, the Fermi_chop2a.comp and Vertical_T0a.comp chopppers from Garrett Granroth (SNS) have received a GPU-oriented update.
  • Core and libs:
    • 3.2 only: Previously, any component present in a McStas instrument would trigger the transformation of every neutron 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, such as big Union assemblies. Thanks to Mads Bertelsen (ESS) for investigating the problem and finding a good solution.
    • 3.2 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.2 only: Components may from McStas 3.2 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. The first component to make use of this mechanism is Res_monitor.comp as used in Test_TasReso.instr.
    • The (r-)interoff-lib.c family of codes have received multiple updates, thanks to McStas users Kyle Grammer (ORNL) and Gaetano Mangiapia (HZH):
      • The intersection routines now work correctly with gravity
      • The r-interoff-lib (and the related Guide_anyshape_r component) now support specifying a "full" reflectivity curve pr. OFF face, columns of m, alpha and W values should be added in this order to the OFF face.
    • 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!
    • A correction to ref-lib.c was recieved from Gaetano Mangiapia (HZH), allowing closer correspondance between simulated and measured mirror-reflectivities.

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!!!

November 1st, 2022: macOS 13 Ventura issues

Dear all,

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

A workaround is to:

  • In a terminal, start your "McStas shell" (e.g. run mcstas-3.1-environment, /Applications/McStas-3.1-environment.command or /Applications/
  • Issue the command
    export PATH=$MCSTAS/miniconda3/bin:$PATH
  • Next, you may issue the mcgui command

New releases 2.7.2 and 3.2 are in preparation and should be released during November or December.

November 1st, 2022: Python 3.10 / pyqtgraph issues in current releases.

Dear all,

Several users have reported "yet another Python issue" that arise in current releases of McStas (2.7.1 / 3.1). After following the advice from September 23rd to replace mcgui/ and mccodelib/, mcplot-pyqtgraph fails with

mcplot error: scale(self): too many arguments
Traceback (most recent call last):
File "C:\mcstas-2.7.1\lib\tools\Python\mcplot\pyqtgraph\", line 67, in 
File "C:\mcstas-2.7.1\lib\tools\Python\mcplot\pyqtgraph\", line 57, in main
raise e
File "C:\mcstas-2.7.1\lib\tools\Python\mcplot\pyqtgraph\", line 51, in main
File "C:\mcstas-2.7.1\lib\tools\Python\mcplot\pyqtgraph....\mccodelib\", line 62, in runplot
plot_node(node, self.plot_func, plt_layout, viewmodel)
File "C:\mcstas-2.7.1\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:\mcstas-2.7.1\lib\tools\Python\mcplot\pyqtgraph....\mccodelib\", line 382, in add_plot
view_box, plt_itm = plot_node_func(node, i, plt, options)
File "C:\mcstas-2.7.1\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:\mcstas-2.7.1\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 2.7.2 and 3.2 are in preparation and should be released during November or December.

September 23rd, 2022: Python 3.10 issues in current releases.

Dear all,

We have recently become aware of a couple of issues that arise with all current releases of McStas (2.7.1 / 3.1)

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:

  • $MCSTAS/tools/Python/mcgui/ - please replace by this new version
  • $MCSTAS/tools/Python/mccodelib/ - please replace by this new version

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

Best and sorry for the inconvenience,

Peter Willendrup

August 20th, 2022: Preview of ICNS 2022 presentation available.

On behalf of the McStas team, Peter Willendrup is giving an ICNS2022 presentation, entitled:

Speeding up legacy: GPU-accelerating the McStas instrument simulation code using OpenACC.


The McStas neutron ray-tracing simulation package is a versatile tool for producing accurate simulations of neutron scattering instruments at reactors, short- and long-pulsed spallation sources such as the European Spallation Source.
McStas is extensively used for design and optimization of instruments, virtual experiments, data analysis and user training. McStas was founded as an scientific, open-source collaborative code in 1997 and thus celebrates 25 years of service to the neutron community in 2022.
The contribution presents the project at its current state, with emphasis on recent modernisation-efforts and GPU-acceleration. Using the OpenACC precompiler-mechanism, McStas and its X-ray counterpart McXtrace have received speedups in the range of 10-600 depending on problem size and model complextiy.
By a detailed walk-through of a selected instrument example including the utilised components, we will illustrate the few simple steps users should carry out to port their existing instrument-models.

The video has been pre-recorded and is now available at or on YouTube

May 14th, 2022: Neutron-optics and McStas/Union related Post Doc position at PSI:

Dear all,

An interesting Post Doc position is available within the Neutron Optics and Scientific Computing Group at PSI:

A central part of the position is expanding features of the McStas Union by adding support for reflectivity (and potentially refraction).

Main tasks are:

  • Simulation and code development for neutron optics
  • Extend the Monte-Carlo Ray-tracing software McStas
  • Design an advanced signal-to-noice enhancing neutron optics
  • Conceptualize tutorials for users
  • Participate in neutron scattering experiments

For more information please refer to the link below or contact Dr. Christine Klauser <>

Peter Willendrup

February 18th, 2022: New ready-to-run McStas box in a browser

We are happy to provide a ready-to-run system with McStas pre-installed. It typically pulls-out an 8-cores computer running at Binder, for free, with both McStas 2.x and 3.x (with MPI multi-core support but no GPU). Perfect for running McStas 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

Previous news items: 2021,2020,2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012, 2011, 2010, 2009, 2008, 2007, 2006, 2005, 2004, 2003, 2002, 2001, 2000, 1999, 1998.

Last Modified: Tuesday, 10-Jan-2023 11:24:01 CET
Search website mailinglist archive GitHub repos