Component Manual for the Neutron Ray-Tracing Package McStas, version 3.8.6
PIC
Physics Physics Department,
Technical University of Denmark
2800 Kongens Lyngby, Denmark
PIC

Component Manual for the Neutron Ray-Tracing Package McStas, version 3.8.6

P. Willendrup, E. Farhi, E. Knudsen, K. Lefmann

September, 2026

The software package McStas is a tool for carrying out Monte Carlo ray-tracing simulations of neutron scattering instruments with high complexity and precision. The simulations can compute all aspects of the performance of instruments and can thus be used to optimize the use of existing equipment, design new instrumentation, and carry out virtual experiments for e.g. training, experimental planning or data analysis. McStas is based on a unique design where an automatic compilation process translates high-level textual instrument descriptions into efficient ISO-C code. This design makes it simple to set up typical simulations and also gives essentially unlimited freedom to handle more unusual cases.

This report constitutes the reference manual for McStas, and, together with the manual for the McStas components, it contains documentation of most aspects of the program. It covers the various ways to compile and run simulations, a description of the meta-language used to define simulations, and some example simulations performed with the program.

This report documents McStas version 3.8.6, released September, 2026

The authors are:

Peter Kjær Willendrup <pkwi@fysik.dtu.dk>
Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark

Emmanuel Farhi <emmanuel.farhi@synchrotron-soleil.fr>
Synchrotron SOLEIL, Saint-Aubin, France

Kim Lefmann <lefmann@nbi.dk>
Niels Bohr Institute, University of Copenhagen, Denmark

as well as authors who left the project:

Erik Knudsen <erkn@fysik.dtu.dk>
Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark Jakob Garde <jaga@fysik.dtu.dk>
Physics Department, Technical University of Denmark, Kongens Lyngby, Denmark Peter Christiansen <pchristi@hep.lu.se>
Materials Research Department, Risø National Laboratory, Roskilde, Denmark
Present address: University of Lund, Lund, Sweden
Klaus Lieutenant <k.lieutenant@fz-juelich.dee>
Institut Laue-Langevin, Grenoble, France
Present address: Forschungs-Zentrum Jülich, Germany
Kristian Nielsen <kristian-nielsen@mail.tele.dk>
Materials Research Department, Risø National Laboratory, Roskilde, Denmark
Presently associated with: MySQL AB, Sweden

ISBN 978–87–550–3680–2

ISSN 0106–2840

Physics Department \(\cdot \) DTU \(\cdot \) 2026

Contents
   Preface and acknowledgements
Preface and acknowledgements
1  About the component library
 1.1  Authorship
 1.2  Symbols for neutron scattering and simulation
 1.3  Component coordinate system
 1.4  About data files
 1.5  Component source code
 1.6  Documentation
 1.7  Component validation
 1.8  Disclaimer, bugs
2  Monte Carlo Techniques and simulation strategy
 2.1  Neutron spectrometer simulations
 2.2  The neutron weight
 2.3  Weight factor transformations during a Monte Carlo choice
 2.4  Adaptive and Stratified sampling
 2.5  Accuracy of Monte Carlo simulations
3  Source components
 3.1  The Source_simple McStas Component
 3.2  The Source_div McStas Component
 3.3  The Source_Maxwell_3 McStas Component
 3.4  The Source_gen McStas Component
 3.5  The Moderator McStas Component
 3.6  The Source_adapt McStas Component
 3.7  The Adapt_check McStas Component
 3.8  The Source_Optimizer McStas Component
 3.9  The Monitor_Optimizer McStas Component
 3.10  Other sources components: contributed pulsed sources, virtual sources (event files)
4  Beam optical components: Arms, slits, collimators, and filters
 4.1  The Arm McStas Component
 4.2  The Slit McStas Component
 4.3  The Beamstop McStas Component
 4.4  The Filter_gen McStas Component
 4.5  The Collimator_linear McStas Component
 4.6  The Collimator_radial McStas Component
5  Reflecting optical components: mirrors, and guides
 5.1  The Guide McStas Component
6  Moving optical components: Choppers and velocity selectors
 6.1  The DiskChopper McStas Component
 6.2  The FermiChopper McStas Component
 6.3  The Vitess_ChopperFermi McStas Component
 6.4  The V_selector McStas Component
 6.5  The Selector McStas Component
7  Polarising optics and magnetic field components
 7.1  Setting and analysing polarisation
 7.2  The Set_pol McStas Component
 7.3  The PolAnalyser_ideal McStas Component
 7.4  The Pol_SF_ideal McStas Component
 7.5  Polarising mirrors and guides
 7.6  The Pol_mirror McStas Component
 7.7  The Pol_bender McStas Component
 7.8  The Pol_guide_mirror McStas Component
 7.9  The Pol_guide_vmirror McStas Component
 7.10  Magnetic field components
 7.11  The Pol_Bfield McStas Component
 7.12  The Pol_Bfield_stop McStas Component
 7.13  The Pol_FieldBox McStas Component
 7.14  The Pol_constBfield McStas Component
 7.15  The Pol_tabled_field McStas Component
8  Monochromators
 8.1  The Monochromator_flat McStas Component
 8.2  The Monochromator_curved McStas Component
 8.3  Monochromator_pol: A polarizing monochromator
 8.4  The Monochromator_pol McStas Component
 8.5  Single_crystal: Thick single crystal monochromator plate with multiple scattering
 8.6  Phase space transformer - moving monochromator
9  Samples
 9.1  The Incoherent McStas Component
 9.2  The Tunneling_sample McStas Component
 9.3  The PowderN McStas Component
 9.4  The Single_crystal McStas Component
 9.5  The Sans_spheres McStas Component
 9.6  The Phonon_simple McStas Component
 9.7  The Isotropic_Sqw McStas Component
 9.8  Samples for resolution-function calculations
 9.9  The Res_sample McStas Component
 9.10  The TOFRes_sample McStas Component
10  Monitors and detectors
 10.1  The TOF_monitor McStas Component
 10.2  The TOF2E_monitor McStas Component
 10.3  The E_monitor McStas Component
 10.4  The L_monitor McStas Component
 10.5  The PSD_monitor McStas Component
 10.6  The Divergence_monitor McStas Component
 10.7  The DivPos_monitor McStas Component
 10.8  The Monitor_nD McStas Component
 10.9  The Res_monitor McStas Component
 10.10  Polarisation-sensitive monitors
 10.11  The Pol_monitor McStas Component
 10.12  The PolLambda_monitor McStas Component
 10.13  The MeanPolLambda_monitor McStas Component
 10.14  The PSD_monitor_4PI_spin McStas Component
11  Special-purpose components
 11.1  MCPL: splitting simulations via portable neutron event files
 11.2  The MCPL_input McStas Component
 11.3  The MCPL_output McStas Component
 11.4  Progress_bar: Simulation progress and automatic saving
 11.5  Beam_spy: A beam analyzer
12  The Union framework: sample environments and multiple scattering
 12.1  Union framework core: initialization, master, and termination
 12.2  The Union_init McStas Component
 12.3  The Union_master McStas Component
 12.4  The Union_master_GPU McStas Component
 12.5  The Union_stop McStas Component
 12.6  Union geometry components
 12.7  The Union_box McStas Component
 12.8  The Union_cylinder McStas Component
 12.9  The Union_sphere McStas Component
 12.10  The Union_cone McStas Component
 12.11  The Union_mesh McStas Component
 12.12  Union material definition
 12.13  The Union_make_material McStas Component
 12.14  Union scattering process components
 12.15  The Non_process McStas Component
 12.16  The Incoherent_process McStas Component
 12.17  The IncoherentPhonon_process McStas Component
 12.18  The PhononSimple_process McStas Component
 12.19  The Powder_process McStas Component
 12.20  The Single_crystal_process McStas Component
 12.21  The AF_HB_1D_process McStas Component
 12.22  The Texture_process McStas Component
 12.23  The NCrystal_process McStas Component
 12.24  The Template_process McStas Component
 12.25  The Template_surface McStas Component
 12.26  The Mirror_surface McStas Component
 12.27  Union loggers (event/history recording)
 12.28  The Union_logger_1D McStas Component
 12.29  The Union_logger_2DQ McStas Component
 12.30  The Union_logger_2D_kf McStas Component
 12.31  The Union_logger_2D_kf_time McStas Component
 12.32  The Union_logger_2D_space McStas Component
 12.33  The Union_logger_2D_space_time McStas Component
 12.34  The Union_logger_3D_space McStas Component
 12.35  Union absorption loggers
 12.36  The Union_abs_logger_1D_space McStas Component
 12.37  The Union_abs_logger_1D_space_event McStas Component
 12.38  The Union_abs_logger_1D_space_tof McStas Component
 12.39  The Union_abs_logger_1D_space_tof_to_lambda McStas Component
 12.40  The Union_abs_logger_1D_time McStas Component
 12.41  The Union_abs_logger_2D_space McStas Component
 12.42  The Union_abs_logger_event McStas Component
 12.43  The Union_abs_logger_nD McStas Component
 12.44  Union conditionals
 12.45  The Union_conditional_PSD McStas Component
 12.46  The Union_conditional_standard McStas Component
13  SasView/sasmodels form factors: small-angle scattering
 13.1  SasView form-factor components
 13.2  The SasView_adsorbed_layer McStas Component
 13.3  The SasView_barbell McStas Component
 13.4  The SasView_barbell_aniso McStas Component
 13.5  The SasView_bcc_paracrystal McStas Component
 13.6  The SasView_bcc_paracrystal_aniso McStas Component
 13.7  The SasView_binary_hard_sphere McStas Component
 13.8  The SasView_broad_peak McStas Component
 13.9  The SasView_capped_cylinder McStas Component
 13.10  The SasView_capped_cylinder_aniso McStas Component
 13.11  The SasView_core_multi_shell McStas Component
 13.12  The SasView_core_shell_bicelle McStas Component
 13.13  The SasView_core_shell_bicelle_aniso McStas Component
 13.14  The SasView_core_shell_bicelle_elliptical McStas Component
 13.15  The SasView_core_shell_bicelle_elliptical_aniso McStas Component
 13.16  The SasView_core_shell_bicelle_elliptical_belt_rough McStas Component
 13.17  The SasView_core_shell_bicelle_elliptical_belt_rough_aniso McStas Component
 13.18  The SasView_core_shell_cylinder McStas Component
 13.19  The SasView_core_shell_cylinder_aniso McStas Component
 13.20  The SasView_core_shell_ellipsoid McStas Component
 13.21  The SasView_core_shell_ellipsoid_aniso McStas Component
 13.22  The SasView_core_shell_parallelepiped McStas Component
 13.23  The SasView_core_shell_parallelepiped_aniso McStas Component
 13.24  The SasView_core_shell_sphere McStas Component
 13.25  The SasView_correlation_length McStas Component
 13.26  The SasView_cylinder McStas Component
 13.27  The SasView_cylinder_aniso McStas Component
 13.28  The SasView_dab McStas Component
 13.29  The SasView_ellipsoid McStas Component
 13.30  The SasView_ellipsoid_aniso McStas Component
 13.31  The SasView_elliptical_cylinder McStas Component
 13.32  The SasView_elliptical_cylinder_aniso McStas Component
 13.33  The SasView_fcc_paracrystal McStas Component
 13.34  The SasView_fcc_paracrystal_aniso McStas Component
 13.35  The SasView_flexible_cylinder McStas Component
 13.36  The SasView_flexible_cylinder_elliptical McStas Component
 13.37  The SasView_fractal McStas Component
 13.38  The SasView_fractal_core_shell McStas Component
 13.39  The SasView_fuzzy_sphere McStas Component
 13.40  The SasView_gauss_lorentz_gel McStas Component
 13.41  The SasView_gaussian_peak McStas Component
 13.42  The SasView_gel_fit McStas Component
 13.43  The SasView_guinier McStas Component
 13.44  The SasView_guinier_porod McStas Component
 13.45  The SasView_hardsphere McStas Component
 13.46  The SasView_hayter_msa McStas Component
 13.47  The SasView_hollow_cylinder McStas Component
 13.48  The SasView_hollow_cylinder_aniso McStas Component
 13.49  The SasView_hollow_rectangular_prism McStas Component
 13.50  The SasView_hollow_rectangular_prism_aniso McStas Component
 13.51  The SasView_hollow_rectangular_prism_thin_walls McStas Component
 13.52  The SasView_lamellar_hg McStas Component
 13.53  The SasView_lamellar_hg_stack_caille McStas Component
 13.54  The SasView_lamellar_stack_caille McStas Component
 13.55  The SasView_lamellar_stack_paracrystal McStas Component
 13.56  The SasView_line McStas Component
 13.57  The SasView_linear_pearls McStas Component
 13.58  The SasView_lorentz McStas Component
 13.59  The SasView_mass_fractal McStas Component
 13.60  The SasView_mass_surface_fractal McStas Component
 13.61  The SasView_mono_gauss_coil McStas Component
 13.62  The SasView_multilayer_vesicle McStas Component
 13.63  The SasView_onion McStas Component
 13.64  The SasView_parallelepiped McStas Component
 13.65  The SasView_parallelepiped_aniso McStas Component
 13.66  The SasView_peak_lorentz McStas Component
 13.67  The SasView_pearl_necklace McStas Component
 13.68  The SasView_poly_gauss_coil McStas Component
 13.69  The SasView_polymer_excl_volume McStas Component
 13.70  The SasView_polymer_micelle McStas Component
 13.71  The SasView_porod McStas Component
 13.72  The SasView_power_law McStas Component
 13.73  The SasView_pringle McStas Component
 13.74  The SasView_raspberry McStas Component
 13.75  The SasView_rectangular_prism McStas Component
 13.76  The SasView_rectangular_prism_aniso McStas Component
 13.77  The SasView_rpa McStas Component
 13.78  The SasView_sc_paracrystal McStas Component
 13.79  The SasView_sc_paracrystal_aniso McStas Component
 13.80  The SasView_sphere McStas Component
 13.81  The SasView_spinodal McStas Component
 13.82  The SasView_squarewell McStas Component
 13.83  The SasView_stacked_disks McStas Component
 13.84  The SasView_stacked_disks_aniso McStas Component
 13.85  The SasView_star_polymer McStas Component
 13.86  The SasView_stickyhardsphere McStas Component
 13.87  The SasView_superball McStas Component
 13.88  The SasView_superball_aniso McStas Component
 13.89  The SasView_surface_fractal McStas Component
 13.90  The SasView_teubner_strey McStas Component
 13.91  The SasView_triaxial_ellipsoid McStas Component
 13.92  The SasView_triaxial_ellipsoid_aniso McStas Component
 13.93  The SasView_two_lorentzian McStas Component
 13.94  The SasView_two_power_law McStas Component
 13.95  The SasView_vesicle McStas Component
14  Contributed components
 14.1  Contributed sources
 14.2  The ISIS_moderator McStas Component
 14.3  The ViewModISIS McStas Component
 14.4  The SNS_source McStas Component
 14.5  The SNS_source_analytic McStas Component
 14.6  The Source_gen4 McStas Component
 14.7  The Source_multi_surfaces McStas Component
 14.8  The Source_custom McStas Component
 14.9  The Source_pulsed McStas Component
 14.10  Contributed guides and benders
 14.11  The Guide_anyshape_r McStas Component
 14.12  The Guide_curved McStas Component
 14.13  The Guide_four_side McStas Component
 14.14  The Guide_gravity_psd McStas Component
 14.15  The Guide_honeycomb McStas Component
 14.16  The Guide_m McStas Component
 14.17  The Guide_multichannel McStas Component
 14.18  The Vertical_Bender McStas Component
 14.19  The NMO McStas Component
 14.20  The Conics_EH McStas Component
 14.21  The Conics_HE McStas Component
 14.22  The Conics_PH McStas Component
 14.23  The Conics_PP McStas Component
 14.24  The FlatEllipse_finite_mirror McStas Component
 14.25  The Commodus_I3 McStas Component
 14.26  Contributed choppers and collimators
 14.27  The FermiChopper_ILL McStas Component
 14.28  The Fermi_chop2a McStas Component
 14.29  The MultiDiskChopper McStas Component
 14.30  The StatisticalChopper McStas Component
 14.31  The StatisticalChopper_Monitor McStas Component
 14.32  The Vertical_T0a McStas Component
 14.33  The Collimator_ROC McStas Component
 14.34  The Exact_radial_coll McStas Component
 14.35  The CavitiesIn McStas Component
 14.36  The CavitiesOut McStas Component
 14.37  The multi_pipe McStas Component
 14.38  Contributed filters and windows
 14.39  The Al_window McStas Component
 14.40  The Filter_graphite McStas Component
 14.41  The Sapphire_Filter McStas Component
 14.42  Contributed lenses and mirrors
 14.43  The Lens McStas Component
 14.44  The Lens_simple McStas Component
 14.45  The Mirror_Curved_Bispectral McStas Component
 14.46  The Mirror_Elliptic McStas Component
 14.47  The Mirror_Elliptic_Bispectral McStas Component
 14.48  The Mirror_Parabolic McStas Component
 14.49  The SupermirrorFlat McStas Component
 14.50  Contributed monochromators and analysers
 14.51  The Monochromator_2foc McStas Component
 14.52  The Monochromator_bent McStas Component
 14.53  The Monochromator_bent_complex McStas Component
 14.54  The PerfectCrystal McStas Component
 14.55  The Spherical_Backscattering_Analyser McStas Component
 14.56  Contributed polarisation components
 14.57  The Foil_flipper_magnet McStas Component
 14.58  The Pol_bender_tapering McStas Component
 14.59  The Pol_triafield McStas Component
 14.60  The Pol_pi_2_rotator McStas Component
 14.61  The Transmission_polarisatorABSnT McStas Component
 14.62  The Transmission_V_polarisator McStas Component
 14.63  The Spin_random McStas Component
 14.64  The PSD_Pol_monitor McStas Component
 14.65  The PSD_spinDmon McStas Component
 14.66  The PSD_spinUmon McStas Component
 14.67  Contributed single-crystal and powder/polycrystalline samples
 14.68  The Single_crystal_inelastic McStas Component
 14.69  The SiC McStas Component
 14.70  The Spot_sample McStas Component
 14.71  The GISANS_sample McStas Component
 14.72  Contributed SANS samples
 14.73  The SANSCurve McStas Component
 14.74  The SANSCylinders McStas Component
 14.75  The SANSEllipticCylinders McStas Component
 14.76  The SANSLiposomes McStas Component
 14.77  The SANSNanodiscs McStas Component
 14.78  The SANSNanodiscsFast McStas Component
 14.79  The SANSNanodiscsWithTags McStas Component
 14.80  The SANSNanodiscsWithTagsFast McStas Component
 14.81  The SANSPDB McStas Component
 14.82  The SANSPDBFast McStas Component
 14.83  The SANSShells McStas Component
 14.84  The SANSSpheres McStas Component
 14.85  The SANSSpheresPolydisperse McStas Component
 14.86  The SANS_AnySamp McStas Component
 14.87  The SANS_DebyeS McStas Component
 14.88  The SANS_Guinier McStas Component
 14.89  The SANS_Liposomes_Abs McStas Component
 14.90  The SANS_benchmark2 McStas Component
 14.91  The Sans_liposomes_new McStas Component
 14.92  The Multilayer_Sample McStas Component
 14.93  Contributed monitors and detectors
 14.94  The E_4PI McStas Component
 14.95  The NPI_tof_dhkl_detector McStas Component
 14.96  The NPI_tof_theta_monitor McStas Component
 14.97  The PSD_Detector McStas Component
 14.98  The PSD_monitor_rad McStas Component
 14.99  The Radial_div McStas Component
 14.100  The SANSQMonitor McStas Component
 14.101  The TOFSANSdet McStas Component
 14.102  The TOF2Q_cyl_monitor McStas Component
 14.103  The TOF_PSDmonitor McStas Component
 14.104  The TOF_PSDmonitor_toQ McStas Component
15  Obsolete components
 15.1  The V_sample McStas Component
 15.2  The Virtual_input McStas Component
 15.3  The Virtual_output McStas Component
 15.4  The Virtual_mcnp_input McStas Component
 15.5  The Virtual_mcnp_output McStas Component
 15.6  The Virtual_mcnp_ss_input McStas Component
 15.7  The Virtual_mcnp_ss_output McStas Component
 15.8  The Virtual_mcnp_ss_Guide McStas Component
 15.9  The Virtual_tripoli4_input McStas Component
 15.10  The Virtual_tripoli4_output McStas Component
 15.11  The Vitess_input McStas Component
 15.12  The Vitess_output McStas Component
 15.13  The ESS_moderator_short McStas Component
 15.14  The Beam_spy McStas Component
A  Polarisation in McStas
 A.1  The Polarization Vector
 A.2  Polarized Neutron Scattering
 A.3  Magnetic fields: the precession algorithm and field framework
 A.4  Polarisation components in McStas
 A.5  Test and example instruments
B  Libraries and constants
 B.1  Run-time calls and functions (mcstas-r)
 B.2  Reading a data file into a vector/matrix (Table input, read_table-lib)
 B.3  Monitor_nD Library
 B.4  Adaptive importance sampling Library
 B.5  Vitess import/export Library
 B.6  Constants for unit conversion etc.
C  The McStas terminology
   Bibliography
Bibliography
   Index and keywords
Index