5.4  Polarisation components in McStas

The components below can be grouped by role:

• Setting and analysing polarisation (unphysical, for testing/idealised use).

• Polarising monochromators, mirrors and guides (physical, reflectivity-based).

• Magnetic field regions (precession, using the framework of section 5.3).

• Polarisation-sensitive monitors.

• Samples affecting polarisation.

As of McStas 3.x these are found in the optics and monitors component categories (not a dedicated “polarisation” category); a component is polarisation-aware precisely when its TRACE section reads and/or writes the particle’s spin state \((s_x,s_y,s_z)\).

5.4.1  Setting and analysing polarisation

• Set_pol: An unphysical, zero-size component (drawn like an Arm) used to impose a polarisation state, in one of four modes selected by randomOn and normalize: (i) hard-code the polarisation to \((p_x,p_y,p_z)\); (ii) set it to a random vector on the unit sphere (fully polarised, random direction); (iii) set it to a random vector within the unit sphere (random direction and degree of polarisation); (iv) hard-code the direction of \((p_x,p_y,p_z)\) but normalise it to unit polarisation.

• PolAnalyser_ideal: An unphysical, ideal polarisation analyser. Given an analysis direction \(\mathbf {m}=(m_x,m_y,m_z)\) (\(|\mathbf {m}|\le 1\) for an imperfect analyser), it reduces the neutron weight by the projection probability \(\tfrac 12\bigl (1+\mathbf {S}\cdot \mathbf {m}\bigr )\) and collapses the outgoing spin to \(\mathbf {m}\), or absorbs the ray if that probability is zero or negative.

• Pol_SF_ideal: An idealised spin flipper: within an absorbing box, the polarisation vector is mirrored through the plane through the origin with normal \((n_x,n_y,n_z)\) (\(\mathbf {S}' = \mathbf {S} - 2(\mathbf {S}\cdot \hat {\mathbf {n}})\hat {\mathbf {n}}\)); rays missing the box pass through untouched. This is the natural building block for a spin-echo instrument’s \(\pi \)-flip coils (section 5.5.4) when an idealised, 100%-efficient flipper is sufficient.

5.4.2  Polarising monochromators, mirrors and guides

These all implement the physics of section 5.2.2 (Eqs. 5.24–5.30): given reflectivities for spin up and down (\(R_\uparrow \), \(R_\downarrow \), either as {R0,Qc,alpha,m,W} parametrised curves via ref-lib’s StdReflecFunc, or as tabulated reflectivity files), the shared helper functions GetMonoPolFNFM, GetMonoPolRefProb, SetMonoPolRefOut and SetMonoPolTransOut (all in pol-lib) compute \(F_N\), \(F_M\), the reflection probability, and the outgoing polarisation for both the reflected and transmitted branches. Since a 2024 revision (E.B. Knudsen, P. Willendrup, H. Lee), all of these components treat a polarising reflection/transmission event as a projective quantum measurement along the mirror’s quantisation axis: the in-plane spin components are explicitly zeroed (\(s_x=s_z=0\)) at the point of interaction, before the new \(s_y\) is set by SetMonoPolRefOut/ SetMonoPolTransOut – reflecting that only the component of polarisation along the mirror’s up direction survives a measurement-like interaction of this kind.

• Monochromator_pol: A flat, infinitely thin mosaic monochromator/analyser crystal (Gaussian mosaic and \(d\)-spread, billiard-ball reflection), the direct polarising analogue of Monochromator_flat, parametrised by Rup/Rdown (or Q/DM for the lattice spacing).

• Pol_mirror: A flat, infinitely thin, non-absorbing polarising mirror in the \(y\)-\(z\) plane, reflecting and/or transmitting according to p_reflect (use \(-1\) to sample physically from the mirror’s own reflectivity, or a fixed value to force a chosen reflect/transmit statistics split while re-weighting correctly).

• Pol_bender: A curved, multi-slit polarising bender (based on Guide_curved), with independently specifiable reflectivities for each of the four walls (top/bottom/left/right) and gravity support.

• Pol_guide_mirror / Pol_guide_vmirror: Straight rectangular guides with one (_mirror) or two, V-shaped (_vmirror) polarising supermirrors sitting on the diagonal(s) inside an otherwise ordinary (optionally non-polarising) guide. Setting the up and down reflectivities of the diagonal mirror equal turns either component into an unpolarised frame-overlap mirror instead – a deliberate dual use of the same geometry.

5.4.3  Magnetic field components

See section 5.3 for the shared precession algorithm and field functions used by these.

• Pol_Bfield / Pol_Bfield_stop: The general-purpose field region, supporting all of the field functions of section 5.3.3 and a box, cylindrical, spherical, or window-shaped extent. Used together as a concentric pair (Pol_Bfield pushes the field, other components may be placed freely inside, Pol_Bfield_stop pops it), or standalone as a closed region (concentric=0) that nothing else may be placed inside.

• Pol_FieldBox: A simple, self-contained, non-nestable box with a single uniform field \((B_x,B_y,B_z)\), evaluated with a direct, single-step closed-form precession (Eq. 5.12) rather than the general stack/integrator – the lightest-weight choice for a plain guide field or spin-flip coil.

• Pol_tabled_field: A field region (box/cylinder/sphere, or an arbitrary OFF/PLY-geometry volume) whose field is interpolated from an externally supplied point-cloud file, using the same adaptive-step precession algorithm re-implemented internally (section 5.3.2). The interpolation backend (kdtree or regular-grid) can be chosen explicitly or left to an automatic CPU/GPU-appropriate default.

• Pol_constBfield: A rectangular, closed (non-nestable) box with a constant field along its local \(y\)-axis, evaluated with the closed-form solution of Eq. 5.12 directly (no field stack). Convenient for guide fields and simple spin flippers: rather than specifying \(B\) directly, fliplambda/flipangle let the field be specified as “the field that flips a neutron of this wavelength by this angle over this component’s length” – exactly the GetConstantField() helper of pol-lib.

5.4.4  Polarisation-sensitive monitors

• Pol_monitor: Measures the projection of the polarisation onto a user-defined direction \(\mathbf {m}=(m_x,m_y,m_z)\), i.e. \(\mathbf {m}\cdot \mathbf {S}\), integrated over all detected rays.

• PolLambda_monitor: As Pol_monitor, resolved as a function of wavelength \(\lambda \).

• MeanPolLambda_monitor: As PolLambda_monitor, but reporting the mean polarisation projection per wavelength bin (rather than the summed/integrated signal) – the natural monitor for a spin-echo polarisation-vs.-parameter scan (section 5.5.4).

• PSD_monitor_4PI_spin: A spherical, \(4\pi \) position-sensitive monitor that additionally records the mean polarisation projection per pixel, for mapping how polarisation varies with scattering angle.

5.4.5  Samples and polarisation

Few McStas sample components currently propagate polarisation explicitly. The generic Incoherent component (the modern, general-purpose replacement for the historical, now-obsolete V_sample) can be parametrised to reproduce the classic depolarising-incoherent-scatterer result of section 5.2’s nuclear-scattering example (\(\mathbf {P}' = -\tfrac 13\mathbf {P}\) per single incoherent scattering event, from the random projection of nuclear spin onto \(\hat \sigma _x\) and \(\hat \sigma _y\)); as noted there, this simple factor is only exact for a single scattering event, and multiple scattering must be handled with some care (consecutive depolarisation by \((-\tfrac 13)^n\) is only valid if each scattering order can be isolated). Magnetic (Bragg) scattering from an ordered magnetic structure, using the magnetic structure factor \(F_M\) of section 5.1, is not yet implemented as a general sample component; Single_crystal and PowderN presently model only nuclear scattering and do not read or write the spin state.