quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/peakshapes.py

@@ -0,0 +1,85 @@
+"""Peak-shape profiles for XRD/spectroscopy fitting. Ports of MATLAB +utilities.
+
+Pure functions: positions in, profile out. Used by the fitting model library.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["pseudo_voigt", "split_pearson_vii", "tch_pseudo_voigt"]
+
+# Parameter vector: a plain sequence or a float ndarray (e.g. straight from an
+# optimizer) — both are unpacked via float(...) so either works at runtime.
+Params = Sequence[float] | NDArray[np.float64]
+
+_LN2 = math.log(2)
+_EPS = float(np.finfo(float).eps)
+
+
+def pseudo_voigt(
+    x: NDArray[np.float64],
+    x0: float,
+    fwhm: float,
+    height: float,
+    eta: float,
+    bg: float = 0.0,
+) -> NDArray[np.float64]:
+    """Linear pseudo-Voigt: H·(eta·L + (1-eta)·G) + bg. Port of utilities.pseudoVoigt."""
+    if fwhm <= 0:
+        raise ValueError("fwhm must be positive")
+    if not 0.0 <= eta <= 1.0:
+        raise ValueError("eta must be in [0, 1]")
+    xv = np.asarray(x, dtype=float)
+    u = (xv - x0) / fwhm
+    lorentz = 1.0 / (1.0 + 4.0 * u**2)
+    gauss = np.exp(-4.0 * _LN2 * u**2)
+    return height * (eta * lorentz + (1.0 - eta) * gauss) + bg
+
+
+def split_pearson_vii(x: NDArray[np.float64], params: Params) -> NDArray[np.float64]:
+    """Asymmetric split Pearson VII. params = [H, center, wL, wR, mL, mR, baseline]."""
+    height, center, w_l, w_r, m_l, m_r, baseline = (float(p) for p in params)
+    if w_l <= 0 or w_r <= 0:
+        raise ValueError("half-widths wL, wR must be positive")
+    if m_l < 0.5 or m_r < 0.5:
+        raise ValueError("shape exponents mL, mR must be >= 0.5")
+    xv = np.asarray(x, dtype=float)
+    y = np.zeros_like(xv)
+    mask_l = xv < center
+    mask_r = ~mask_l
+    k_l = 2.0 ** (1.0 / m_l) - 1.0
+    k_r = 2.0 ** (1.0 / m_r) - 1.0
+    y[mask_l] = height * (1.0 + k_l * ((xv[mask_l] - center) / w_l) ** 2) ** (-m_l)
+    y[mask_r] = height * (1.0 + k_r * ((xv[mask_r] - center) / w_r) ** 2) ** (-m_r)
+    return y + baseline
+
+
+def tch_pseudo_voigt(x: NDArray[np.float64], params: Params) -> NDArray[np.float64]:
+    """Thompson-Cox-Hastings pseudo-Voigt. params = [H, x0, fG, fL, bg]."""
+    height, x0, f_g, f_l, bg = (float(p) for p in params)
+    f_g, f_l = abs(f_g), abs(f_l)
+    if f_g < _EPS and f_l < _EPS:
+        raise ValueError("at least one of fG, fL must be > 0")
+    f5 = (
+        f_g**5
+        + 2.69269 * f_g**4 * f_l
+        + 2.42843 * f_g**3 * f_l**2
+        + 4.47163 * f_g**2 * f_l**3
+        + 0.07842 * f_g * f_l**4
+        + f_l**5
+    )
+    f = f5 ** (1.0 / 5.0)
+    r = f_l / f
+    eta = 1.36603 * r - 0.47719 * r**2 + 0.11116 * r**3
+    eta = max(0.0, min(1.0, eta))
+    xv = np.asarray(x, dtype=float)
+    u = (xv - x0) / f
+    lorentz = 1.0 / (1.0 + 4.0 * u**2)
+    gauss = np.exp(-4.0 * _LN2 * u**2)
+    result = height * (eta * lorentz + (1.0 - eta) * gauss) + bg
+    return np.asarray(result, dtype=float)

quantized/calc/plotting.py

@@ -0,0 +1,147 @@
+"""Pure plot-series builder: DataStruct + PlotState -> arrays ready for uPlot.
+
+Pure layer — returns ndarrays; the wire (NaN -> null, column packing) is the
+routes layer's job. No fastapi/pydantic imports.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["PlotData", "PlotSeries", "PlotState", "build_series", "resolve_style_channels"]
+
+
+@dataclass(frozen=True, slots=True)
+class PlotState:
+    """Minimal plot selection/config (M1 subset of the full W6 model).
+
+    ``y2_keys`` names the channels drawn against a secondary (right) Y axis —
+    the dual-Y feature. Channels not listed there default to the primary axis.
+    """
+
+    x_key: int | str | None = None
+    y_keys: tuple[int | str, ...] | None = None
+    y2_keys: tuple[int | str, ...] | None = None
+    x_log: bool = False
+    y_log: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class PlotSeries:
+    label: str
+    unit: str
+    values: NDArray[np.float64]
+    axis: int = 0  # 0 = primary (left) Y axis, 1 = secondary (right)
+
+
+@dataclass(frozen=True, slots=True)
+class PlotData:
+    x: NDArray[np.float64]
+    x_label: str
+    x_unit: str
+    series: tuple[PlotSeries, ...]
+    x_log: bool
+    y_log: bool
+
+
+def _resolve(ds: DataStruct, key: int | str) -> int:
+    return key if isinstance(key, int) else ds.labels.index(key)
+
+
+def build_series(ds: DataStruct, state: PlotState | None = None) -> PlotData:
+    """Select x + y channels per ``state``; default x = ds.time, y = all channels."""
+    state = state or PlotState()
+
+    if state.x_key is None:
+        x = ds.time
+        x_label = str(ds.metadata.get("x_column_name", "x"))
+        x_unit = str(ds.metadata.get("x_column_unit", ""))
+    else:
+        xi = _resolve(ds, state.x_key)
+        x = ds.values[:, xi]
+        x_label = ds.labels[xi]
+        x_unit = ds.units[xi]
+
+    if state.y_keys is None:
+        y_indices = list(range(ds.n_channels))
+    else:
+        y_indices = [_resolve(ds, k) for k in state.y_keys]
+
+    y2 = {_resolve(ds, k) for k in state.y2_keys} if state.y2_keys is not None else set()
+    series = tuple(
+        PlotSeries(
+            label=ds.labels[i],
+            unit=ds.units[i],
+            values=ds.values[:, i],
+            axis=1 if i in y2 else 0,
+        )
+        for i in y_indices
+    )
+    return PlotData(
+        x=x,
+        x_label=x_label,
+        x_unit=x_unit,
+        series=series,
+        x_log=state.x_log,
+        y_log=state.y_log,
+    )
+
+
+def resolve_style_channels(
+    ds: DataStruct,
+    y_keys: Sequence[int | str] | None,
+    series_styles: Sequence[Mapping[str, Any] | None] | None,
+) -> list[dict[str, Any] | None] | None:
+    """Resolve per-series style CHANNEL REFERENCES (MAIN #13's ``fill: {"vs":
+    <channel>}`` and MAIN #14's ``color_by: <channel>``) against ``ds`` and
+    the actual plotted channel order -- so ``calc.figure`` (and
+    ``calc.figure_page``) never touch the raw ``DataStruct``, only resolved
+    values (they stay format-only: numbers in, bytes out).
+
+    ``fill.vs`` (a dataset channel index -- the SAME semantic the frontend's
+    ``SeriesStyle.fill`` uses) resolves to the DISPLAY POSITION of that
+    channel among the plotted series -- dropped silently (no band) when the
+    channel isn't currently plotted, mirroring uPlot's own band mechanism,
+    which can only fill between two DRAWN series (see the frontend's
+    ``lib/uplotFill.ts``).
+
+    ``color_by`` (a dataset channel index) resolves to that channel's
+    concrete value array -- any channel, not required to be otherwise
+    plotted, since it's an auxiliary z-column, not an x/y series pick.
+
+    ``None`` (no styles requested) passes through unchanged; a malformed
+    style dict entry is left as-is (rendering degrades gracefully -- an
+    export must never 500 on a bad style hint).
+    """
+    if series_styles is None:
+        return None
+    plotted = list(range(ds.n_channels)) if y_keys is None else [_resolve(ds, k) for k in y_keys]
+    out: list[dict[str, Any] | None] = []
+    for spec in series_styles:
+        if not spec:
+            out.append(None)
+            continue
+        resolved: dict[str, Any] = dict(spec)  # shallow copy -- never mutate the caller's dict
+        fill = resolved.get("fill")
+        if isinstance(fill, Mapping) and "vs" in fill:
+            try:
+                vs_pos = plotted.index(int(fill["vs"]))
+            except (ValueError, TypeError):
+                resolved.pop("fill", None)
+            else:
+                resolved["fill"] = {"vs": vs_pos}
+        color_by = resolved.get("color_by")
+        if isinstance(color_by, int) and not isinstance(color_by, bool):
+            if 0 <= color_by < ds.n_channels:
+                resolved["color_by"] = ds.values[:, color_by].tolist()
+            else:
+                resolved.pop("color_by", None)
+        out.append(resolved)
+    return out

quantized/calc/processing.py

@@ -0,0 +1,232 @@
+"""Pure data-processing utilities. Ports of MATLAB +utilities functions.
+
+Column-wise operations on 1-D vectors or 2-D (samples x channels) arrays.
+Pure layer — no fastapi/pydantic imports.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import integrate
+
+__all__ = [
+    "cumulative_integral",
+    "derivative",
+    "log_derivative",
+    "normalize",
+    "smooth_data",
+]
+
+
+def _as_columns(y: NDArray[np.float64]) -> tuple[NDArray[np.float64], bool]:
+    arr = np.asarray(y, dtype=float)
+    if arr.ndim == 1:
+        return arr.reshape(-1, 1), True
+    return arr, False
+
+
+def normalize(
+    y: NDArray[np.float64],
+    *,
+    method: str = "range",
+    out_range: tuple[float, float] = (0.0, 1.0),
+) -> NDArray[np.float64]:
+    """Per-column normalization. method = 'range' | 'peak' | 'zscore'.
+
+    Port of utilities.normalize (zscore uses sample std, ddof=1).
+    """
+    if method not in ("range", "peak", "zscore"):
+        raise ValueError(f"method must be range/peak/zscore, got {method!r}")
+    mat, was_1d = _as_columns(y)
+    out = np.full(mat.shape, np.nan)
+    lo_out, hi_out = out_range
+    for c in range(mat.shape[1]):
+        col = mat[:, c]
+        if col.size == 0:  # empty column: nothing to normalize (np.nanmin would raise)
+            out[:, c] = col
+            continue
+        if method == "range":
+            lo = np.nanmin(col)
+            hi = np.nanmax(col)
+            span = hi - lo
+            out[:, c] = lo_out if span == 0 else lo_out + (col - lo) / span * (hi_out - lo_out)
+        elif method == "peak":
+            pk = np.nanmax(np.abs(col))
+            out[:, c] = col if pk == 0 else col / pk
+        else:  # zscore
+            mu = np.nanmean(col)
+            sg = np.nanstd(col, ddof=1)
+            out[:, c] = (col - mu) if sg == 0 else (col - mu) / sg
+    return out.ravel() if was_1d else out
+
+
+def _matlab_gradient(f: NDArray[np.float64], x: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Replicate MATLAB ``gradient(F, X)`` exactly (simple central differences).
+
+    Interior: (f[i+1]-f[i-1])/(x[i+1]-x[i-1]); ends: one-sided. (numpy.gradient
+    uses a different non-uniform formula, so it is NOT used here.)
+    """
+    n = f.size
+    g = np.empty(n)
+    if n == 0:
+        return g
+    if n == 1:
+        g[0] = 0.0
+        return g
+    g[0] = (f[1] - f[0]) / (x[1] - x[0])
+    g[-1] = (f[-1] - f[-2]) / (x[-1] - x[-2])
+    if n > 2:
+        g[1:-1] = (f[2:] - f[:-2]) / (x[2:] - x[:-2])
+    return g
+
+
+def derivative(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    *,
+    order: int = 1,
+    pre_smooth: int = 0,
+) -> NDArray[np.float64]:
+    """Numerical derivative dy/dx (order 1 or 2). Port of utilities.derivative.
+
+    With ``pre_smooth > 0`` the signal is gaussian-smoothed (window = pre_smooth)
+    before differentiating, matching the MATLAB ``PreSmooth`` option.
+    """
+    if order not in (1, 2):
+        raise ValueError("order must be 1 or 2")
+    xv = np.asarray(x, dtype=float).ravel()
+    mat, was_1d = _as_columns(y)
+    if xv.size != mat.shape[0]:
+        raise ValueError(f"x length ({xv.size}) must match y rows ({mat.shape[0]})")
+    if pre_smooth > 0:
+        smoothed = smooth_data(mat, method="gaussian", window=pre_smooth)
+        mat = smoothed if smoothed.ndim == 2 else smoothed.reshape(-1, 1)
+    out = np.zeros(mat.shape)
+    for c in range(mat.shape[1]):
+        d = _matlab_gradient(mat[:, c], xv)
+        if order == 2:
+            d = _matlab_gradient(d, xv)
+        out[:, c] = d
+    return out.ravel() if was_1d else out
+
+
+def cumulative_integral(
+    x: NDArray[np.float64], y: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    """Cumulative trapezoidal integral (leading 0). Port of utilities.cumulativeIntegral.
+
+    NaNs are treated as 0 during integration and restored as NaN in the output.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    mat, was_1d = _as_columns(y)
+    if xv.size != mat.shape[0]:
+        raise ValueError(f"x length ({xv.size}) must match y rows ({mat.shape[0]})")
+    out = np.zeros(mat.shape)
+    for c in range(mat.shape[1]):
+        col = mat[:, c].copy()
+        nan_mask = np.isnan(col)
+        col[nan_mask] = 0.0
+        out[:, c] = integrate.cumulative_trapezoid(col, xv, initial=0.0)
+        out[nan_mask, c] = np.nan
+    return out.ravel() if was_1d else out
+
+
+def log_derivative(
+    x: NDArray[np.float64], y: NDArray[np.float64]
+) -> NDArray[np.float64]:
+    """Logarithmic derivative (x/y)·dy/dx. Port of utilities.logDerivative.
+
+    NaN where x<=0 or y<=0 (log undefined). PreSmooth not yet supported.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    mat, was_1d = _as_columns(y)
+    if xv.size != mat.shape[0]:
+        raise ValueError(f"x length ({xv.size}) must match y rows ({mat.shape[0]})")
+    out = np.full(mat.shape, np.nan)
+    for c in range(mat.shape[1]):
+        col = mat[:, c]
+        dydx = _matlab_gradient(col, xv)
+        valid = (xv > 0) & (col > 0)
+        out[valid, c] = (xv[valid] / col[valid]) * dydx[valid]
+    return out.ravel() if was_1d else out
+
+
+def smooth_data(
+    y: NDArray[np.float64],
+    *,
+    method: str = "moving",
+    window: int = 5,
+    poly_order: int = 2,
+) -> NDArray[np.float64]:
+    """Column-wise smoothing. Port of utilities.smoothData.
+
+    ``window`` is the half-width (full window = ``2*window + 1``). Methods:
+
+    - ``'moving'``: boxcar average, reflect-padded at the edges.
+    - ``'gaussian'``: Gaussian kernel (sigma = hw/2), reflect-padded.
+    - ``'savitzky-golay'``: SG convolution interior + per-point polynomial fits
+      over the boundary window at each edge (matches MATLAB's edge handling).
+
+    The half-width is clamped to ``n-1`` per column; columns shorter than 2 are
+    returned unchanged.
+    """
+    if method not in ("moving", "gaussian", "savitzky-golay"):
+        raise ValueError("method must be moving/gaussian/savitzky-golay")
+    hw = window
+    if method == "savitzky-golay" and poly_order >= 2 * hw + 1:
+        raise ValueError(f"poly_order ({poly_order}) must be < window width ({2 * hw + 1})")
+
+    mat, was_1d = _as_columns(y)
+    out = np.full(mat.shape, np.nan)
+    for c in range(mat.shape[1]):
+        col = mat[:, c]
+        n = col.size
+        hwc = min(hw, n - 1)
+        if hwc < 1:
+            out[:, c] = col
+            continue
+
+        if method == "savitzky-golay":
+            out[:, c] = _savgol_column(col, hwc, min(poly_order, 2 * hwc))
+        else:
+            w_len = 2 * hwc + 1
+            if method == "moving":
+                kernel = np.ones(w_len) / w_len
+            else:  # gaussian
+                sigma = hwc / 2.0
+                t = np.arange(-hwc, hwc + 1, dtype=float)
+                kernel = np.exp(-(t**2) / (2.0 * sigma**2))
+                kernel = kernel / kernel.sum()
+            left = col[1 : hwc + 1][::-1]
+            right = col[n - 1 - hwc : n - 1][::-1]
+            padded = np.concatenate([left, col, right])
+            out[:, c] = np.convolve(padded, kernel, mode="valid")[:n]
+    return out.ravel() if was_1d else out
+
+
+def _savgol_column(col: NDArray[np.float64], hwc: int, poly_ord: int) -> NDArray[np.float64]:
+    """One column of Savitzky-Golay smoothing (interior kernel + polynomial edges)."""
+    n = col.size
+    w_len = 2 * hwc + 1
+    t = np.arange(-hwc, hwc + 1, dtype=float)
+    vand = np.vander(t, poly_ord + 1, increasing=True)
+    # SG smoothing kernel = first row of the normal-equations pseudoinverse.
+    coeff_mat = np.linalg.solve(vand.T @ vand, vand.T)
+    int_kernel = coeff_mat[0, :]
+
+    out = col.copy()
+    if n > 2 * hwc:
+        out = np.convolve(col, int_kernel[::-1], mode="same")
+
+    # Edges: one polynomial fit over the boundary window, evaluated per point.
+    n_pts = min(w_len, n)
+    t_local = np.arange(n_pts, dtype=float)
+    vand_local = np.vander(t_local, poly_ord + 1, increasing=True)
+    powers = np.arange(poly_ord + 1)
+    left_coeffs = np.linalg.lstsq(vand_local, col[:n_pts], rcond=None)[0]
+    right_coeffs = np.linalg.lstsq(vand_local, col[n - n_pts : n], rcond=None)[0]
+    for i in range(1, hwc + 1):
+        out[i - 1] = float(np.sum(left_coeffs * (i - 1.0) ** powers))
+        out[n - i] = float(np.sum(right_coeffs * float(n_pts - 1 - (i - 1)) ** powers))
+    return out

quantized/calc/qspace.py

@@ -0,0 +1,48 @@
+"""Reciprocal-space coordinates for XRD reciprocal-space maps (RSM).
+
+Port of the coplanar Q-space formula documented in MATLAB
+``parser.importXRDML`` (angular area-detector data -> reciprocal space):
+
+    theta = 2theta / 2
+    Qx = (4*pi/lambda) * sin(theta) * sin(omega - theta)      [Ang^-1]
+    Qz = (4*pi/lambda) * sin(theta) * cos(omega - theta)      [Ang^-1]
+
+where ``2theta`` is the detector angle, ``omega`` the incident (sample-tilt)
+angle, and ``lambda`` the X-ray wavelength (Angstrom). Standard coplanar
+geometry: Qx is the in-plane, Qz the out-of-plane reciprocal-lattice
+coordinate. At the symmetric condition ``omega == theta`` the in-plane term
+``sin(omega - theta)`` vanishes, so ``Qx == 0`` (the scan runs straight up the
+specular Qz axis) — a useful sanity check.
+
+Pure calc layer (ndarray in -> ndarray out); no fastapi/pydantic.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = ["compute_qspace"]
+
+
+def compute_qspace(
+    two_theta_deg: ArrayLike,
+    omega_deg: ArrayLike,
+    wavelength_a: float,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Angular ``(2theta, omega)`` in degrees -> reciprocal-space ``(Qx, Qz)``.
+
+    Inputs broadcast together (numpy rules), so the common RSM-grid call passes
+    ``two_theta`` as a row ``(1, M)`` and ``omega`` as a column ``(N, 1)`` to get
+    ``(N, M)`` grids; equal-shaped arrays are handled element-wise. ``Qx``/``Qz``
+    are returned in ``Ang^-1``.
+    """
+    if not (np.isfinite(wavelength_a) and wavelength_a > 0):
+        raise ValueError(f"wavelength_a must be positive and finite, got {wavelength_a!r}")
+    theta = np.deg2rad(np.asarray(two_theta_deg, dtype=float)) / 2.0
+    omega = np.deg2rad(np.asarray(omega_deg, dtype=float))
+    k = 4.0 * np.pi / wavelength_a
+    sin_theta = np.sin(theta)
+    qx = np.asarray(k * sin_theta * np.sin(omega - theta), dtype=float)
+    qz = np.asarray(k * sin_theta * np.cos(omega - theta), dtype=float)
+    return qx, qz

quantized/calc/reductions.py

@@ -0,0 +1,155 @@
+"""Data reductions ported from quantized_matlab (PORT_PLAN #19).
+
+Four reductions, each replicating the MATLAB *algorithm* (not just the
+answer — per the replicate-vs-delegate rule these are idiosyncratic local
+implementations, so window functions, zero-padding, peak search bounds and
+the superlattice heuristics are ported step-for-step):
+
+- ``williamson_hall``   — ``+calc/+crystal/williamsonHall.m``
+- ``fft_thickness``     — ``+bosonPlotter/peakTools.m`` ``fftThickness/doFFT``
+  (the math inside the dialog; the uifigure chrome is not part of the port)
+- ``reflectivity_fft``  — ``peakTools.m`` ``reflectivityFFT/doReflFFT``
+- ``spin_asymmetry``    — ``+bosonPlotter/computeAsymmetryForExport.m``
+  (the (R++ − R−−)/(R++ + R−−) formula + exact error propagation; the
+  polarization-pair discovery is GUI bookkeeping and stays in the caller)
+
+pchip interpolation delegates to scipy (documented equivalent of MATLAB
+``interp1(..., 'pchip')``); everything else is explicit.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.calc.reductions_fft import fft_thickness, reflectivity_fft
+
+__all__ = [
+    "fft_thickness",
+    "reflectivity_fft",
+    "spin_asymmetry",
+    "williamson_hall",
+]
+
+_FloatArray = NDArray[np.float64]
+
+
+def williamson_hall(
+    two_theta_deg: Any,
+    fwhm_deg: Any,
+    *,
+    wavelength_a: float = 1.5406,
+    k_factor: float = 0.9,
+    instrumental_broadening_deg: float = 0.0,
+) -> dict[str, Any]:
+    """Separate crystallite size and microstrain from XRD peak widths.
+
+    Williamson-Hall (uniform strain model): ``beta*cos(theta) = K*lambda/D
+    + 4*eps*sin(theta)``; a linear fit of beta*cos(theta) vs 4*sin(theta)
+    gives slope = microstrain and intercept = K*lambda/D. Instrumental
+    broadening is subtracted in quadrature (clamped at 1e-16 like MATLAB
+    when a peak is narrower than the instrument).
+    """
+    tt = np.asarray(two_theta_deg, dtype=float).ravel()
+    fw = np.asarray(fwhm_deg, dtype=float).ravel()
+    n = tt.size
+    if n != fw.size:
+        raise ValueError(
+            f"two_theta and fwhm must have the same length (got {n} vs {fw.size})"
+        )
+    if n < 2:
+        raise ValueError(f"at least 2 peaks are required for the Williamson-Hall fit (got {n})")
+    if not np.all((tt > 0) & (tt < 180)):
+        raise ValueError("all 2-theta values must be in the range (0, 180) degrees")
+    if not np.all(fw > 0):
+        raise ValueError("all FWHM values must be positive")
+    if wavelength_a <= 0:
+        raise ValueError("wavelength_a must be positive")
+    if k_factor <= 0:
+        raise ValueError("k_factor must be positive")
+    if instrumental_broadening_deg < 0:
+        raise ValueError("instrumental_broadening_deg must be non-negative")
+
+    theta = np.asarray((tt / 2.0) * (math.pi / 180.0), dtype=float)
+    beta_meas = np.asarray(fw * (math.pi / 180.0), dtype=float)
+
+    beta_inst = instrumental_broadening_deg * (math.pi / 180.0)
+    if beta_inst > 0:
+        beta_sq = np.asarray(beta_meas**2 - beta_inst**2, dtype=float)
+        # MATLAB warns and clamps when the instrument is broader than a peak.
+        beta_sq = np.asarray(np.maximum(beta_sq, 1e-16), dtype=float)
+        beta = np.asarray(np.sqrt(beta_sq), dtype=float)
+    else:
+        beta = beta_meas
+
+    x = np.asarray(4.0 * np.sin(theta), dtype=float)
+    y = np.asarray(beta * np.cos(theta), dtype=float)
+
+    design = np.column_stack([x, np.ones(n)])
+    coeffs, _, _, _ = np.linalg.lstsq(design, y, rcond=None)
+    slope = float(coeffs[0])
+    intercept = float(coeffs[1])
+
+    if intercept <= 0:
+        grain_size_nm = float("nan")  # undefined; peaks likely span phases
+    else:
+        grain_size_nm = (k_factor * wavelength_a) / intercept / 10.0
+
+    y_fit = design @ coeffs
+    ss_res = float(np.sum((y - y_fit) ** 2))
+    ss_tot = float(np.sum((y - np.mean(y)) ** 2))
+    r2 = 1.0 if ss_tot < np.finfo(float).eps else 1.0 - ss_res / ss_tot
+
+    return {
+        "grain_size_nm": grain_size_nm,
+        "microstrain": slope,
+        "r2": r2,
+        "plot_x": x.tolist(),
+        "plot_y": y.tolist(),
+        "fit_line": [slope, intercept],
+    }
+
+
+def spin_asymmetry(
+    r_pp: Any,
+    r_mm: Any,
+    dr_pp: Any = None,
+    dr_mm: Any = None,
+) -> dict[str, Any]:
+    """Neutron spin asymmetry ``(R++ - R--) / (R++ + R--)``.
+
+    Points where either channel is non-positive or NaN yield NaN (matching
+    MATLAB's validity mask). The propagated error uses the exact partials
+    ``dA/dR++ = 2 R-- / (R++ + R--)^2`` and ``dA/dR-- = -2 R++ / (...)^2``;
+    absent uncertainties are treated as zero (so ``d_asymmetry`` is 0 on
+    valid points, NaN on invalid ones — same as the MATLAB export path).
+    """
+    rpp = np.asarray(r_pp, dtype=float).ravel()
+    rmm = np.asarray(r_mm, dtype=float).ravel()
+    if rpp.size != rmm.size:
+        raise ValueError(
+            "spin channels must share one Q grid (interpolate first); "
+            f"got {rpp.size} vs {rmm.size} points"
+        )
+    dpp = np.zeros_like(rpp) if dr_pp is None else np.asarray(dr_pp, dtype=float).ravel()
+    dmm = np.zeros_like(rmm) if dr_mm is None else np.asarray(dr_mm, dtype=float).ravel()
+    if dpp.size != rpp.size or dmm.size != rmm.size:
+        raise ValueError("uncertainty arrays must match the reflectivity length")
+
+    valid = (rpp > 0) & (rmm > 0) & ~np.isnan(rpp) & ~np.isnan(rmm)
+    asym = np.full(rpp.shape, np.nan)
+    err = np.full(rpp.shape, np.nan)
+    total = rpp + rmm
+    asym[valid] = (rpp[valid] - rmm[valid]) / total[valid]
+    da_dpp = 2.0 * rmm[valid] / total[valid] ** 2
+    da_dmm = -2.0 * rpp[valid] / total[valid] ** 2
+    err[valid] = np.sqrt((da_dpp * dpp[valid]) ** 2 + (da_dmm * dmm[valid]) ** 2)
+
+    return {
+        "asymmetry": asym.tolist(),
+        "d_asymmetry": err.tolist(),
+        "n_valid": int(valid.sum()),
+    }