doc

Author: Tom-Willemsen

doc/devices/dae.md

@@ -285,42 +285,43 @@ as a list, and `units` (μs/microseconds for time of flight bounding, and angstr
 
 If you don't specify either of these options, they will default to summing over the entire spectrum.
 
-### Polarisation/Asymmetry
+{#polarisationasymmetry}
+### Polarisation & Asymmetry
 
-ibex_bluesky_core provides a helper method,
-{py:obj}`ibex_bluesky_core.utils.calculate_polarisation`, for calculating the quantity (a-b)/(a+b). This quantity is used, for example, in neutron polarisation measurements, and in calculating asymmetry for muon measurements.
+A helper method, {py:obj}`calculate_polarisation <ibex_bluesky_core.utils.calculate_polarisation>`, is provided
+for calculating the quantity {math}`\frac{a-\alpha b}{a+\alpha b}`, where {math}`\alpha` is a scalar constant which is
+assumed not to have a variance. 
+This quantity is used, for example, in neutron polarisation measurements, and in calculating asymmetry for muon measurements.
 
-For this expression, scipp's default uncertainty propagation rules cannot be used as the uncertainties on (a-b) are correlated with those of (a+b) in the division step - but scipp assumes uncorrelated data. This helper method calculates the uncertainties following linear error propagation theory, using the partial derivatives of the above expression.
+For this expression, scipp's default uncertainty propagation rules cannot be used as the uncertainties on
+{math}`(a-\alpha b)` are correlated with those of {math}`(a+\alpha b)` in the division step - but 
+{external+scipp:doc}`scipp's uncertainty propagation mechanism <reference/error-propagation>` assumes
+uncorrelated data. This helper method calculates
+the uncertainties following linear error propagation theory, using the partial derivatives of the above expression:
 
-The partial derivatives are:
+```{math}
+\frac{\delta}{\delta a}(\frac{a - \alpha b}{a + \alpha b}) = \frac{2b\alpha}{(a+b\alpha)^2}
 
-$ \frac{\delta}{\delta a}\Big(\frac{a - b}{a + b}) = \frac{2b}{(a+b)^2} $
+\frac{\delta}{\delta b}(\frac{a - \alpha b}{a + \alpha b}) = -\frac{2a\alpha}{(a+b\alpha)^2}
 
-$ \frac{\delta}{\delta b}\Big(\frac{a - b}{a + b}) = -\frac{2a}{(a+b)^2} $
-
-
-Which then means the variances computed by this helper function are:
-
-$ Variance = (\frac{\delta}{\delta a}^2 * variance_a) + (\frac{\delta}{\delta b}^2 * variance_b)  $ 
-
-
-The polarisation function provided will calculate the polarisation between two values, A and B, which 
-have different definitions based on the instrument context.
+\sigma^2_f = (\frac{\delta f}{\delta a})^2 \sigma^2_a + (\frac{\delta f}{\delta b})^2 \sigma^2_b
+```
 
-Instrument-Specific Interpretations
-SANS Instruments (e.g., LARMOR)
-A: Intensity in DAE period before switching a flipper.
-B: Intensity in DAE period after switching a flipper.
+The polarisation function provided will calculate the polarisation between two values, {math}`a` and {math}`b`, which 
+have different interpretations based on the instrument context:
 
-Reflectometry Instruments (e.g., POLREF)
-Similar to LARMOR, A and B represent intensities before and after flipper switching.
+**SANS Instruments (e.g., LARMOR) & Reflectometry Instruments (e.g. POLREF)**
 
-Muon Instruments
-A and B refer to Measurements from different detector banks.
+{math}`a` & {math}`b` represent intensity (detector counts over monitor counts) before and after switching a
+spin-flipper device. This is implemented by 
+{py:obj}`PolarisationReducer <ibex_bluesky_core.devices.polarisingdae.PolarisationReducer>`.
+For this use case, {math}`\alpha` is always equal to {math}`1`.
 
-{py:obj}`ibex_bluesky_core.utils.calculate_polarisation`
+**Muon Instruments**
 
-See [`PolarisationReducer`](#PolarisationReducer) for how this is integrated into DAE behaviour. 
+A and B refer to Measurements from different detector banks. Muon instruments use the additional {math}`\alpha`
+term, which might not be equal to {math}`1`. A reducer which exposes muon spin asymmetry as a measured quantity
+is implemented by the {py:obj}`MuonAsymmetryReducer <ibex_bluesky_core.devices.muon.MuonAsymmetryReducer>` class.
 
 ## Waiters
 

src/ibex_bluesky_core/devices/muon.py

@@ -23,6 +23,12 @@
 
 logger = logging.getLogger(__name__)
 
+__all__ = [
+    "MuonAsymmetryReducer",
+    "damped_oscillator",
+    "double_damped_oscillator",
+]
+
 
 def damped_oscillator(
     t: NDArray[np.floating],
@@ -31,8 +37,13 @@ def damped_oscillator(
     omega_0: float,
     phi_0: float,
     lambda_0: float,
-) -> NDArray[np.float64]:
-    r"""Equation for a damped oscillations with an offset (B)."""
+) -> NDArray[np.floating]:
+    r"""Equation for a damped oscillator with an offset, as a function of time :math:`t`.
+
+    .. math::
+
+        B + A_0 \cos(\omega_0 t + \phi_0) e^{-\lambda_0 t}
+    """
     return B + A_0 * np.cos(omega_0 * t + phi_0) * np.exp(-t * lambda_0)
 
 
@@ -47,8 +58,14 @@ def double_damped_oscillator(  # noqa: PLR0913 PLR0917 (model is just this compl
     omega_1: float,
     phi_1: float,
     lambda_1: float,
-) -> NDArray[np.float64]:
-    r"""Equation for multiple component damped oscillations with an offset (B)."""
+) -> NDArray[np.floating]:
+    r"""Equation for two damped oscillators with an offset, as a function of time :math:`t`.
+
+    .. math::
+
+        B + A_0 \cos(\omega_0 t + \phi_0) e^{-\lambda_0 t}
+            + A_1 \cos(\omega_1 t + \phi_1) e^{-\lambda_1 t}
+    """
     return (
         B
         + A_0 * np.cos(omega_0 * t + phi_0) * np.exp(-t * lambda_0)
@@ -57,7 +74,7 @@ def double_damped_oscillator(  # noqa: PLR0913 PLR0917 (model is just this compl
 
 
 class MuonAsymmetryReducer(Reducer, StandardReadable):
-    r"""DAE reducer which exposes a computed asymmetry quantity.
+    r"""DAE reducer which exposes a fitted asymmetry quantity.
 
     This reducer takes two lists of detectors; a forward scattering set of detectors,
     :math:`F`, and a backward scattering set, :math:`B`.