Initial docs

Author: Tom-Willemsen

doc/plans/reflectometry/psi_scan_linear/psi_eq_0.png

@@ -0,0 +1,40 @@
+# Psi scanning
+
+On a reflectometer, the Psi parameter is a rotation of the sample, side-to-side as viewed from a neutron's perspective.
+The Psi parameter causes the reflected beam profile, which can be approximated as an elongated ellipse, to be rotated
+when viewed at the detector. Reflectometers want to align the beam such that the beam profile is parallel to detector
+pixels (or, in other words, a horizontal line as seen on the detector).
+
+Psi does not get _redefined_ to zero when the beam is level, but reflectometers do need to know what value of Psi
+_causes_ the beam to be level. The value of Psi which causes the beam to be level will be different for each sample,
+because of differences in how each sample is mounted.
+
+## Linear detectors
+
+This section applies to instruments like OFFSPEC and POLREF, which have a 1-D bank of detectors. These pixels are much
+wider than they are tall; representative pixel sizes are `0.5 x 50mm` on OFFSPEC or `0.5 x 30mm` on POLREF.
+
+A linear pixel configuration means that as Psi is varied, the beam profile (dark blue) hits a different number of 
+detector pixels (light orange):
+
+![Psi not equal to zero - broad peak](psi_scan_linear/psi_neq_0.png)
+
+![Psi equal to zero - narrow peak](psi_scan_linear/psi_eq_0.png)
+
+For a linear detector, the optimum value of Psi occurs when the beam profile is focused onto the smallest number of
+pixels (when the beam profile is parallel to the pixels).
+
+A Psi scan on a linear detector is therefore implemented using the following steps:
+- Physically scan over Psi
+- At each scan point:
+  - Count & acquire a spectrum-data map describing the counts in all detector pixels
+  - Filter to a range of interesting pixels (for example using {py:obj}`~ibex_bluesky_core.utils.centred_pixel`)
+  - Map those pixels to relative angle (to account for pixel spacing which may not be exactly even between all pixels)
+  - Optionally divide counts in each pixel by a flood map, to account for different pixel efficiencies
+  - Fit angle against counts using a Gaussian curve
+  - Return the 'width' parameter of the Gaussian fit as the data from each scan point
+- Plotting the returned 'width' parameter at each scan point against the scanned variable, Psi, the optimum value of Psi
+occurs when the width is minimised.
+  - This is performed using an 'outer' {py:obj}`~ibex_bluesky_core.fitting.Gaussian` fit, using standard
+[callbacks and fitting](../../callbacks/fitting/fitting) infrastructure. This is expected to give a negative
+{py:obj}`~ibex_bluesky_core.fitting.Gaussian` curve, where the `x0` parameter describes the optimum value of Psi.

doc/plans/reflectometry/psi_scan_linear/psi_neq_0.png

@@ -3,6 +3,9 @@
 import asyncio
 import logging
 
+import numpy as np
+import numpy.typing as npt
+import scipp as sc
 from bluesky.protocols import NamedMovable
 from ophyd_async.core import (
     AsyncStatus,
@@ -15,11 +18,12 @@
 from ophyd_async.epics.core import epics_signal_r, epics_signal_rw, epics_signal_w
 
 from ibex_bluesky_core.devices import NoYesChoice
+from ibex_bluesky_core.devices.simpledae import Reducer
 from ibex_bluesky_core.utils import get_pv_prefix
 
 logger = logging.getLogger(__name__)
 
-__all__ = ["ReflParameter", "ReflParameterRedefine", "refl_parameter"]
+__all__ = ["AngleMappingReducer", "ReflParameter", "ReflParameterRedefine", "refl_parameter"]
 
 
 class ReflParameter(StandardReadable, NamedMovable[float]):
@@ -125,3 +129,22 @@ def refl_parameter(
     return ReflParameter(
         prefix=prefix, name=name, changing_timeout_s=changing_timeout_s, has_redefine=has_redefine
     )
+
+
+class AngleMappingReducer(Reducer, StandardReadable):
+    """Reflectometry angle-mapping reducer."""
+
+    def __init__(
+        self,
+        *,
+        prefix: str,
+        detectors: npt.NDArray[np.int32],
+        angle_map: npt.NDArray[np.float64],
+        flood: sc.Variable | None = None,
+    ) -> None:
+        """Angle-mapping :py:obj:`Reducer` for use by reflectometers.
+
+        This :py:obj:`Reducer` fits the counts on each pixel of a detector,
+        against the relative angular positions of those pixels.
+        """
+        super().__init__()