Abstract
A key element of the success of McStas is the component layer where users and developers alike are contributing to the description of new physical models and features. In McStas, components realise all physical elements of the simulated instrument from source via optics and samples to detector. In this second review paper of the McStas package, we present an overview of the component classes in McStas:
Introduction
We present the second article in a review series concerning the neutron simulation package McStas. The first article in the series described the package, its use, philosophy, and mathematical background [29]. For reasons of clarity and conciseness, we will here often refer to material in the previous article.
Since the foundation of McStas in 1997–1998 the software has been Open Source and Free Software.1
McStas was originaly under a special RISØ license, but is since v.1.8 (2004) under GNU Public License v.2.0
By this separation of instrument-near functionality from the (complex) basic McStas system, it has proved possible for users and the central McStas team alike to develop a large number of components, each with a different purpose. In most cases, each component contains less than 200 lines of C-code, facilitating overview and maintenance by persons different from the author. Since year 2000, the component library including the example instrument files has been the largest growth area of the McStas project, as illustrated in Fig. 1.
In this article, we will present the different classes of McStas components and present selected components in additional detail. We will present two demonstration instrument files that contain most of the selected components: A two-axis diffractometer for a continuous source and a powder diffractometer for a time-of-flight source. In addition, we will elaborate on the expectations for component contribution to the McStas project, with the hope that this will inspire even more user contributions in the future.

The development of the number of components in the McStas component library since the beginning of the project….
The McStas component library is naturally divided into categories, depending on the component functionality. The categories in the current (v. 2.6) release are:
Components used to define the starting condition of the neutron state. In McStas the term source corresponds to the neutron moderators of real-world facilities like steady-state reactor sources or pulsed spallation sources. The reason for this is that McStas does not include the needed physics to describe e.g. fission or spallation.2
To measure or visualise beam characteristics in the instrument, McStas includes so-called monitor components. Almost all monitors can be said to be perfect probes of the neutron state, i.e. no physical detection process is simulated. The output of a monitor generally is a one- or two-dimensional histogram, but can also be a list of neutron events.
This component category covers any device on the instrument used to transport or manipulate the neutron beam. Examples are super-mirror neutron guides, slits and collimators, rotating optics like disk choppers or velocity selectors or Bragg optics like monochromators.3
Naturally, our diffracting sample components can also be used to monochromatize the neutron beam, but are most often also more demanding computationally, c.f. the Single_crystal component.
Components used to model matter on the beam-line, e.g. to be included as a scientific sample in an experiment. Since this review series will include a dedicated article on these complex components, the paper at hand only includes a brief overview of the available models.
Components that do not fit in the other categories. Examples are the components supporting i/o for the MCPL particle list format and the Scatter_logger components used to study beam-losses in neutron guide systems.
Components that are written by McStas users (i.e. not the package developers). This is a rich library of functionality for McStas in categories of sources, monitors, optics and samples. A special case among these components are the contrib/Union components written by Mads Bertelsen [3], allowing to assemple complex arrangements of material and perform multiple scattering within this assembly, e.g. a sample inside a cryostat.
A McStas component receives an incoming neutron state (a ray)
The component coordinate system can be chosen freely as to whatever is the easy system of the device/problem at hand. However, the usual starting condition in McStas sources is to have

(top) Illustration of a neutron source (left) and the entrance of the primary guide (right), displaced 1 m along the positive
To be a valid McStas component, a file needs to be written in the syntax of the C-language and have the following structure and properties
If our intended component is a The first section in the component file is a documentation header, enclosed in c-style ( – Information about who wrote the component, when and where – Description of what exactly – Parameter list of format:
– Optional subsection, typically with scientific references or hyperlinks – marks the End of the document header Declares that the component is a Foobar (label should match the chosen filename). List of component input ‘define’ parameters, i.e. given to the component in the form of a c-style List of parameters for the component. Type can be List of (internal) variables in the component that should be made private, i.e. masked from the scope of other components of the same type present in the instrument. (What technically happens is a variable-prefixing based on the component instance name.) The Section to define common types (e.g. structs) and functions for all used components of type Section to declare variables of the component. In the McStas 3.0 release, this section is used to automatically generate a component struct, so please Section to initialize (internal) variables and state of the component, based on the given input This is where to write lines of C-code that control the action, i.e. handle your incoming neutron state This is where you draw a sketch of the component using a subset of these basic macros:
to draw a line between two points.
to draw a dashed line with n dashes between two points.
to draw a set of n line segments
draws a circle with given radius on the
draws a rectangle of given dimensions on the
draws a box centered on a given point in space.
draws a cylinder centered on point c, directed along normal n with radius r, height h and with N lines to illustrate the cylinder wall.
draws a sphere of radius r centered on c, with N lines illustrating longitude and latitude. Marks the end of the component code.
Example components from the library
We here attempt the difficult task of describing the contents of the McStas component library. For brevity, we limit ourselves to only a few examples within each component category. A description of all components can be found in the online component documentation on the McStas home page [21] and in the McStas component manual [22]. Two test instruments, showing the use of most components described, are presented in Section 4.
Sources
All McStas simulations start with a Source-type component, which can initialize the parameters of the simulated neutron ray, i.e. its position
In the first McStas review article [29], we presented the rule for intensities of a simulation at component j in the instrument,
This focusing was also discussed in Ref. [29], where we presented the fundamental equation
This is the initial weight used in the most basic source components, including the component
Different continuous sources can be provided in the same way, where only the flux function
For pulsed sources, there is a further complication that the intensity varies with time. The component
A much more elaborate time-of-flight component is
When a McStas component description or parameter-file does not yet exist for your source, an option is to use the MCPL_input component which makes use of the MCPL [9] framework. MCPL provides a very nice interchange-format for particle lists, with backends available for McStas and McXtrace, SIMRES [18]-[19], Vitess [30], Geant4 [1], PHITS [20] and several variants of MCNP [27]. Thus you can perform your McStas simulations with particle data directly out of your neutron source simulations performed in e.g. MCNP. You should however bear in mind that your derived McStas simulation is in principle statistically limited to what the chosen input-file contains and avioding bias can be dificult. The MCPL_input component provides facilities for smoothing when repeating the particle data an integer number of times, which e.g. happens implicitly when running MPI-parallel simulations. This is done by making Monte Carlo choices within a small sphere of confusion around each event in the input file. When using these user-parameters to resample the MCPL data, please examine your MCPL data carefully and make conservative choices, e.g. based on inspection of the particle distributions. Please also consider the energy-ranges available in your MCPL-input and set relevant, physically meaningful E_min and E_max limits in MCPL_input. – McStas is for instance not suited for transport of eV, keV, or MeV range neutrons!
Monitors
The term “monitor” in McStas is rather loosely defined and describes any way to gather information about the beam passing a component (typically a specified surface). The neutron ray is propagated until it intersects the specified surface, and the monitor component will determine whether the ray is within the boundary of the monitor. If so, the neutron ray will be registered in a way particular for each monitor (see details below). The monitor will keep track of both number of rays,
Unlike a physical monitor or detector, the neutron ray is not affected by the monitor and may continue after the interaction. In fact, if the flag
Monitors are as ubiquitous as source components, since this is the only way McStas simulations can produce results. Typically, each monitor will produce one data file for every simulation run. Monitor data are almost always histogrammed. The corresponding bins are either one-dimensional (for example in the
A number of monitors exist that can perform rudimentary data treatment, for example by transforming time-of-flight and scattering angle into scattering vector, given proper information on the instrument geometry. The use of such components may speed up the design of full instruments, since simulated data are immediately in a human understandable format. However, a detailed description of these more complex monitors is outside the scope of this review.
Below, we describe in more detail some of the most used monitor components.
L_monitor(). This component is a rectangular shaped one-dimensional monitor that registers the true neutron wavelength and histograms the incoming intensity on a number of wavelength bins. A typical output from this monitor is shown in Fig. 3.
TOF_monitor(). This component is very reminescent of

The simulation results obtained from shooting neutron rays from
PSD_monitor(). This monitor is another example that actually has a physical counterpart. It produces a two dimensional image of the neutron intensity in real space. It is often used to characterize the beam in a guide or just before the sample – or as the detector for neutron imaging instruments. An example of output from this component is shown in a later example, Fig. 7.
Divergence_monitor(). This two-dimensional monitor ditributes the neutrons according to their divergence in the two dimensions perpendicular to the detector normal. This unphysical monitor is usually used to inspect the phase space distribution of the beam inside a neutron guide system or at the sample position.
Monitor_nD(). This monitor can measure almost anything you can imagine, by means of a flexible
PreMonitor_nD(). The PreMonitor_nD component can store the neutron properties for use later in the simulation work flow, e.g. measure the originating state of the neutron at the source to be studied at the sample position. The component has a single input, namely the instance name of the Monitor_nD which will perform the measurement. (That Monitor_nD should correspondingly have
We now turn to the optical components that in general are used to modify the beam characteristics. The geometry of the components in this section is shown in Fig. 5.
Arm(). This is possibly the most used McStas component, yet it does not affect the neutron ray at all(!) The component is to be used as a reference for the internal coordinate system in McStas. Typically, an Arm() is placed at an axis of rotation, and following components – including further Arm()’s – are to be placed relative to the first Arm(). Used in this way, the Arm() component has the same function as an optical bench.
Slit() aka. Diaphragm(). This component is a simple slit, which in effect is an infinitely wide, 100% effective absorber with a single central opening, being either circular or rectangular. As rectangular, the slit opening width is given by the parameters xmin and xmax. Alternatively, a symmetric opening is given by instead setting the parameter xwidth. The corresponding parameters setting the opening height are denoted ymin and ymax, alternatively yheight. These variable names are generally used for heights and widths of components within McStas – as described in the (rarely studied) NOMENCLATURE document on the McStas home page [21].
If Slit() should rather have a circular opening (in this case centered at the origin of the local coordinate system), this is done by setting the input parameter radius. This way of controlling the component functionality via setting of input variables is a frequent feature within McStas library components.
The Slit() functions in the following way: First the neutron ray is propagated to the plane of the component. Next, a check is performed to see if the neutron has hit the slit opening. If not, the neutron ray is discarded, using the McStas command ABSORB.
Collimator_linear(). This component models a linear Soller collimator, physically made from a stack of absorbing, parallel blades. It is box-shaped with the physical dimensions xwidth, yheight, and length, as shown in Fig. 5. The degree of collimation is parametrised as the maximal divergence allowed through, using the parameters for the two directions: eta_x and eta_y – just as for a Soller collimators on an experimental set-up. If any of these parameters is zero, this is interpreted as if there is no collimation restriction in the corresponding direction (the default value).
The neutron ray is first propagated to the entry plane, then to the exit plane of the component. If the ray does not pass the collimator opening at both planes, it is ABSORB’ed. If the neutron ray has a larger divergence than the maximally allowed, in either the x or the y direction, it is also ABSORB’ed.
In a physical Soller collimator, the transmission of a certain neutron is either 0 or 1, depending whether the neutron trajectory intersects one of the absorbing plates. The test for collision for each of the plates is somewhat tedious, so in this McStas component we use a stochastic approach. If we assume that we do not know exactly where the absorber blades are positioned (but only the distance between them), we can calculate the probability of being transmitted as a function of divergence (for collimation in one dimension):
Guide(). McStas contains a number of neutron guide components. We here describe the simplest of them, Guide(). This is a neutron guide with rectangular openings. The entry has the dimensions h1 × w1, while the exit has dimensions h2 × w2, i.e. it is possible to describe a linearly tapering guide by making the entry and exit rectangles having different sizes. The length of the guide is given by l.
The inner surface of Guide() is imagined to be covered by a neutron-reflecting layer or layers, where the outermost layer is Ni, which has a critical scattering vector of
To quantify this, we need to define the actual scattering vector, q, in the conventional way,
The component functions by propagating the neutron ray to the entry plane. If the rectangular opening is not hit, the neutron is ABSORB’ed. Otherwise it continues into the guide. Each time the ray intersects one of the four guide sides, a specular reflectivity event is assumed. The scattering vector, q, is calculated, and the neutron weight multiplier becomes
For a consistent description of the mirror reflectivity, it can be recommended in stead of R0 and alpha to use the library ref-lib, which contains updated descriptions of reflectivity for mirrors of different values of m. This library is used for all McStas components that decribe optics with reflecting surfaces, such as Guide_gravity(), Guide_wavy(), Mirror() and several others. The current version of the reflectivity profiles is illustrated in Fig. 4.

The reflectivity profiles,
Monochromator_flat(). This component models a simple crystal monochromator of dimensions yheight × zwidth. The coordinate z is here used to denote the width, since the unrotated monochromator lies in the
The Monochromator_flat() is assumed to be an ideally imperfect mosaic crystal, i.e. it is assumed to have a Gaussian mosaic spread of tiny crystallites, each too small to have significant primary extinction. This, in turn, gives rise to a Gaussian distribution of the scattering from the monochromator. The divergence of the scattered beam is characterized by the parameters mosaich and mosaicv, for the horizontal and vertical directions, respectively. In other words, mosaich is the effective mosaic in the horisontal direction, such that an in-plane oriented monochromator will display a rocking curve width (FWHM) with the value mosaich. Likewise, mosaicv is the effective mosaic in the vertical direction, such that a pencil-beam reflected from the same monochromator will have a vertical spread (FWHM) of
Two other monochromators exist in the McStas package: Monochromator_curved() is a multi-slab composite of crystals, focusing the scattering to a particular point, while Monochromator_pol is a flat, neutron polarizing monochromator. Polarized neutrons are described in a later article in this review series.
Monochromators of perfect (or bent perfect) single crystals are at present not present in McStas, as primary extinction is not implemented. An approximation does however exist in the Single_crystal component, where the crystal lattice can be bent locally, keeping the external geometry of the crystal unchanged. In this approximation, curvature is spherical along the outer vertical and horizontal axes of the crystal.
DiskChopper(). This component models a disk chopper; a neutron-absorbing flywheel spinning with its axis along the beam direction, and with wedges cut into the wheel to let through neutrons at particular times. A sketch of the component is shown in Fig. 5.
The component takes the geometry parameters radius, nslit, yheight, theta0 – the latter representing the angular width of each slit (in degres). In addition, we have the chopper frequency nu (in Hz) and the phase of the choppers (at time zero), phase.
A special feature of this component is its effect on a continuous beam. Here, the intention is that the beam will be pulsed after hitting the chopper. However, naively used, this could result in a huge loss in simulated neutron rays. This we have remedied by letting all neutron rays pass the first chopper, while its time is being adjusted to a (random) value where the chopper was indeed open for this ray. This functionality is activated by setting the flag isfirst. It should, however, be used on the fist chopper only, since otherwise very misleading results could arise.
McStas also features other rotating optical components, such as the descriptions of spinning velocity selectors, Selector() and V_selector(), and two different descriptions of Fermi choppers, FermiChopper() and Vitess_ChopperFermi(). For descriptions of these components, we refer to the McStas documentation.

Geometries of the five described beam-optical elements with the standard naming of geometrical parameters shown. Top: Guide(), Monochromator(), Collimator() and Slit(). Bottom: DiskChopper().
At this place, we only briefly touch upon scattering samples in McStas, since a later article in this series is dedicated to exactly samples. For this reason, we here initially present two very simplified examples and then only list all presently available samples in McStas.
Incoherent(). This sample scatters all incoming neutron rays incoherently, i.e., uniformly in the
Powder1(). This sample introduces powder diffraction from a single value of q. The neutron rays are Bragg scattered out into different directions, forming a Debye-Scherrer cone. The scattering and absoption cross sections for the sample are parametrized by F2 and sigma_abs, respectively. The sample has a larger sibling, PowderN(), which can tackle an arbitrary number of powder lines, read from an specified crystallographic input file.
The McStas sample suite. For completeness, in Table 1 we list the presently available scatering samples in McStas. All samples take as parameters their physical size, their absorption (and possibly incoherent) cross section, and then a parametrized or file-based description of their scattering cross section.
A list of sample components currently supported in the McStas package
A list of sample components currently supported in the McStas package
Our miscellaneous component category contains the components that do not naturally fit into the other categories where physical properties are a common denominator, e.g. sources or samples. The most notable Components for
Contrib
The Sources: ISIS_moderator and ViewModISIS are the legacy and new component implementations of the TS1 and TS2 target-stations at the ISIS facility in UK. SNS_source and SNS_source_analytic are components for modelling the SNS source at ORNL in Tennessee, USA. Source_gen4 is developed at PSI, Switzerland, derived from the Source_gen component, with addition of a high-energy tail describing special features of the SINQ spallation source at PSI. Source_multi_surfaces is also a PSI development and allows a ‘pixelated’ source with localised intensity and spectrum differences. Optics: Many guides and benders: Guide_anyshape_r from TUM/MLZ, Guide_four_side, Guide_four_side_2_shells, Guide_four_side_10_shells. Allows flexible-geometry definitions of guides with four-sided guides, optionally with semi-transparent walls. There are three versions of the guide type, each with 1, 2 and 10 layers of nested guide walls. Guide_honeycomb, can be used to model a guide with honeycomb geometry as seen e.g. in the ILL BRISP spectrometer. Guide_multichannel, multichannel neutron guide with semi-transparent blades. Allows to simulate bi-spectral extraction optics. Guide_curved, curved neutron guide. Guide_gravity_psd, guide-monitor hybrid that allows to monitor lost neutron intensity along the guide. Guide_m, similar to the usual Guide, but allows specification of reflectivity pr. surface. Vertical_Bender, a vertical bender that correctly takes gravity into account. Choppers: Two different Fermi choppers, FermiChopper_ILL and Fermi_chop2a. MultiDiskChopper a diskchopper that allows non-equidistant slits of varying size with just one component instance (with DiskChopper this must be done with a GROUP of components). StatisticalChopper chopper for describing a chopper with pseudostatistical pulsing as described in [26]. Vertical_T0a models a vertical-rotation-axis Collimators: Two different radial collimators, Collimator_ROC, an ideal radial oscillating collimator and Exact_radial_coll which is made of many trapezium shaped neutron-slits stacked radially. Filters and windows: Al_window, models Al-windows typically found at the ends of evacuated flight-tubes/guides. Filter_graphite and Saphire_Filter model graphite- and saphire neutron filters. Lenses: Lens and Lens_simple are two different implementations of refractive neutron lenses [8]. Crystal monochromators/analyzers: Monochromator_2foc is a doubly-focusing monochromator, PerfectCrystal and Spherical_Backscattering_Analyser are two different implementations for backscattering analyzers. Slits and apertures: CavitiesIn and CavitiesOut together form a 2-dimensional set of input and output apertures. The multi_pipe component allowes to define a 2-dimensional grid of slits. Mirror_Elliptic models an elliptic mirror, Mirror_Parabolic models a parabolic mirror, Mirror_Curved_Bispectral Mirror_Elliptic_Bispectral are circular and elliptical mirrors intended for bispectral beam-extraction. Polarisation-oriented components: Foil_flipper_magnet models a TU Delft type [14] foil-flipper with an inclined, magnetised foil, Pol_bender_tapering models a tapered polarising bender, Pol_triafield models a triangular field for e.g. SEMSANS, He3_cell models a 3He cell, Pol_pi_2_rotator models a field-device to rotate the neutron beam polarisation by Samples have been contributed in various scientific areas Single crystal models: Single_crystal_inelastic, elastic and inelastic scattering from a single crystal. Single_magnetic_crystal: magnetic diffraction from a single crystal. Single crystal/powder models: NCrystal_sample, elastic and inelastic scattering models from the NCrystal model framework [5]. NCrystal models elastic and ineleastic single crystals, powders and to some extent also liquids based on material scattering kernels. Powders/polyscrystalline: Sample_nxs, provides general powder/polycrystalline scattering with neutron-matter interaction based on neutron cross section calculations of a unit cell. SiC models scattering from nanocrystalline silicon-carbide. SANS: 16 contributions, 4 from FZ Jülich and 12 from the Niels Bohr Institute. Reflectometry: Multilayer_Sample that allows constructing a multilayer and performs dynamical scattering theory. Samples for studying resolution: Spot_sample defines discrete Dirac-δ functions in Q, ω. Monitors: E_4PI is a spherical energy-monitor. NPI_tof_theta_monitor is a cylindrical ToF-angle monitor. NPI_tof_dhkl_detector is a cylindrical detector which converts time-of-flight data (x,y,z,time) to a 1D diffractogram in dhkl. PSD_monitor_4PI_spin measures parallel- and antiparallel spin-directions in a spherical geometry. Radial_div is a radial divergence sensitive monitor with wavelength restrictions. StatisticalChopper_Monitor is a monitor intended for combination with the StatisticalChopper component. PSD_Detector models an n times m pixel Position Sensitive Detector (PSD), box, cylinder or banana filled with a mixture of thermal-neutron converter gas and stopping gas. PSD_monitor_rad is a PSD monitor that allows for radial averaging, intended for SANS settings. SANSQMonitor is a circular detector measuring the radial average of intensity as a function of the momentum transform in the sample, intended for SANS settings. TOFSANSdet is a SANS detector for ToF-SANS. Union: The Shielding_logger: The shielding_logger components are a tool to estimate γ-production arising in and around neutron supermirror guides. The components correspond to a recently published model [11–13], and are implemented similarly to the so-called scatter-logger [10].
Two simple example instruments
We will here present two instruments created to exemplify (most of) the components highlighted in Section 3. For each instrument, we present the instrument, display the TRACE section of the instrument file, and show example output from the resulting simulations.
A two-axis diffractometer on a continuous source

The McStas instrument file describing a simple two-axis diffractometer on a continuous source.
As the first example, we have assembled a very simple two-axis diffractometer on a continuous source, see Fig. 6. The instrument consists of a Source_simple() that feeds a neutron beam into a 20 m long,
Typical results of simulations with this test instrument are shown in Fig. 7. The simulation is run with its default parameters: A2 value of 74.17° (corresponding to scattering of 5 meV neutrons on a PG monochromator), A1 being the half of this. Finally, we use as scattering angle, A4, a (somewhat arbitrary) value of 60°. The L_monitor shows a clear peak at

The simulation results obtained from the simple two-axis diffractometer in Fig. 6. (left) the wavelength distribution on the sample position as measured by L_monitor(). (right) The beam profile on the detector, measured by PSD_monitor().
The second example illustrates a very simple powder diffractometer at a pulsed source, as shown in Fig. 8. This instrument starts with a Progress_bar() that does nothing but generate information on the progress of the simulation. The neutron source is Moderator(), which is set to emit neutrons with energies between 2.5 meV and 6 meV. This is pulsed source, set to a pulse length of 100 μs. the neutron rays emitted from Moderator() are focused on a
After the source is placed a 50 Hz DiskChopper(), whose phase and opening angle can be controlled by external parameters, in this case PHASE and THETA. Next, the divergence of the beam is controlled by a Collimator_linear(), set to a maximum divergence of 60′ (60 arc minutes
Figure 9 shows the outcome of this simple virtual experiment. A peak in intensity is seen close to a time of 28.7 ms. With a total flight path of

The McStas code for a simple powder diffractometer on a pulsed source.

The simulation results obtained from the simple pulsed-neutron powder diffractometer in Fig. 8: the time dependence of the Braggdiffracted pulse on the detector position, as seen by a TOF_monitor().
For a component to become a user contribution in McStas, the list of formal requirements or ‘need-to-haves’ is relatively short:
Have a correctly filled-in documentation header with full author information. Contain a readable and informative description of what the component can do. Have a well-described set of input parameters with physical dimension, preferably in “SI-units Describe how the given component differs from similar models already available in McStas. The component should further come with an example instrument, documented just as well as the component and demonstrating one or two typical settings and use-cases. Where applicable, parameter names should be chosen in line with the McStas nomenclature description [24]. The component code has lots of explanatory comments for complicated or compact code, referencing relevant formulae from literature where needed. Algorithms have generally been written aiming for clarity rather than having a complete physical description. For cases where accurate physical description is necessary, rather a dedicated component is written. The related example instrument contains an Where applicable, the component has been tested in relevant asymptotic conditions, thereby reproducing either relevant theory or a given experimental condition.
The component contributions that become popular among other McStas users and survive for long periods of time in the McStas distribution were typically also written with the following ‘nice-to-have’ principles in mind:
When McStas releases contain new user contributions, the McStas team include a summary of each new component in the so-called
The McStas review series
This article is the second in a series of McStas review papers. Planned themes in this series cover the main uses of McStas:
Guide systems
Instrument simulations and virtual experiments
Modeling of scattering from samples
Simulation of polarized neutrons
Footnotes
Acknowledgements
It is a pleasure to thank everyone involved in the core McStas project over the decades. In chronological order: K. N. Clausen, K. Nielsen, H. M. Rønnow, E. Farhi, P.-O. Åstrand, K. Lieutenant, P. Christiansen, E. B. Knudsen, U. Filges, J. Garde, and M. Bertelsen.
