Vector-polarisation mode ======================== .. image:: /_generated/screenshots/vector_polarization_emu.png :alt: Three EMU vector-polarisation projections P_x, P_y, P_z overlaid :width: 100% *Synthetic EMU-style three-axis polarisation projections overlaid in the* *central plot. The* P_z *trace carries the dominant slow exponential decay,* P_x *carries a weak transverse oscillation, and* P_y *is centred near* *zero with statistical noise — the standard signature of a sample whose* *local field is aligned along the* z *axis of the spectrometer.* Vector-polarisation mode treats the muon-spin polarisation as a three-component vector, exposing the :math:`P_x`, :math:`P_y`, and :math:`P_z` projections separately rather than collapsing the detector counts onto a single forward/backward asymmetry. This is the right analysis path for anisotropic single crystals — where the precession axis is set by the crystallography rather than by the spectrometer geometry — and for any measurement where the local field at the muon site is canted away from :math:`\hat{z}`, since the off-axis precession is then carried by the :math:`P_x` and :math:`P_y` components and is lost in a one-dimensional asymmetry. Powder samples have an orientational average that already collapses onto a single non-trivial component along :math:`\hat{z}`, so the ordinary F-B asymmetry workflow is sufficient there. EMU's octant geometry is the canonical example; vector mode is activated automatically when grouping names contain the canonical vector pairs: * ``Pz Forward`` / ``Pz Backward`` from forward/backward detector groups * ``Py Top`` / ``Py Bottom`` (or ``Py Up`` / ``Py Down``) from top/bottom detector groups * ``Px Left`` / ``Px Right`` from left/right detector groups so the same vector workflow can be applied to any instrument whose detector layout supports the same six-group naming convention. Setup ----- 1. Open Grouping and choose (or create) a profile for EMU. 2. Open Detector Layout... 3. Select instrument ``EMU``. 4. Apply the ``Vector Polarization`` preset. 5. Return to Grouping and calibrate each axis's alpha (see below). Per-axis alpha -------------- When vector mode is active, the Grouping window switches to a vector table with separate alpha values for each axis: * ``alpha_x`` * ``alpha_y`` * ``alpha_z`` Each axis is its own asymmetry projection (see :doc:`detector_grouping`, "Per-projection alpha"), so each calibrates independently through the same alpha calibration dialog used for an ordinary two-group run — open it per axis with that row's **Calibrate…** button, or calibrate all three in one action with **Estimate All alpha**. Because each axis's alpha and provenance are stored on its own projection, switching between axes never mixes up which value came from which calibration run. Backwards compatibility: * Existing scalar ``alpha`` is still supported. * Older projects are migrated so vector groupings initialise ``alpha_x``, ``alpha_y``, and ``alpha_z`` from scalar ``alpha``. Display in the main plot ------------------------ The Polarization selector in the plot header provides: * ``x`` (``P_x``) * ``y`` (``P_y``) * ``z`` (``P_z``) * ``All`` Alpha display behaviour: * Single-axis views show the alpha for the selected axis. * ``All`` mode hides alpha in the header. Persistence ----------- Per-axis alpha values are persisted in: * project files (schema v4+) * dataset grouping state This preserves axis-specific alpha values across save/load cycles and across axis switching in vector mode. Transverse-field dual grouping ------------------------------ The same projection workflow generalises beyond EMU's three-axis vector mode. A forward/backward asymmetry *is* the muon polarisation projected onto the axis joining that detector pair, so any preset that exposes more than one such pair is a set of projections. MuSR and HiFi each ship a combined ``Transverse (Vector)`` preset that exposes **two** transverse projections of the same run: * MuSR — ``Top-Bottom`` and ``Fwd-Back`` * HiFi — ``Left-Right`` and ``Top-Bottom`` Apply it from Detector Layout exactly as for EMU vector mode (select the instrument, apply the ``Transverse (Vector)`` preset). The projection chip bar then shows one chip per transverse projection; selecting two stacks them as subplots, and clicking a subplot makes it the fit target with its own per-projection single fit — identical behaviour to the EMU :math:`P_x`/ :math:`P_y`/:math:`P_z` projections, including the tinted ``Fitting: