quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/interp2d.py

@@ -0,0 +1,260 @@
+"""Scattered 2-D interpolation + regridding. Ports of MATLAB +utilities.
+
+Pure calc layer. ``interpolate2d`` interpolates scattered (x, y, z) onto query
+points; ``regrid2d`` builds a regular grid and calls it.
+
+Parity notes:
+  * ``linear`` / ``nearest`` delegate to ``scipy.interpolate.griddata`` (Qhull
+    Delaunay) and match MATLAB ``scatteredInterpolant`` inside the convex hull.
+  * ``idw`` and ``thinplate`` are hand-rolled (inverse-distance weighting and
+    thin-plate-spline linear systems) and match MATLAB exactly.
+  * ``natural`` (the MATLAB default) and ``cubic`` (which MATLAB aliases to
+    ``natural``) use Sibson natural-neighbour interpolation, hand-rolled in
+    ``_natural_neighbor`` from the Delaunay triangulation. Sibson coordinates
+    are geometrically unique, so this matches MATLAB's 'natural' to ~1e-9 at
+    interior points and reproduces affine fields exactly (linear precision).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.interpolate import griddata
+from scipy.spatial import Delaunay
+from scipy.spatial._qhull import QhullError
+
+from quantized.calc._natural_neighbor import sibson_interpolate
+
+__all__ = ["interpolate2d", "regrid2d"]
+
+_SCATTERED = ("linear", "natural", "nearest", "cubic")
+
+
+def _unique_rows(
+    xv: NDArray[np.float64], yv: NDArray[np.float64], zv: NDArray[np.float64]
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Drop duplicate (x, y) rows keeping first occurrence (MATLAB unique 'stable')."""
+    seen: set[tuple[float, float]] = set()
+    keep: list[int] = []
+    for i in range(xv.size):
+        key = (float(xv[i]), float(yv[i]))
+        if key not in seen:
+            seen.add(key)
+            keep.append(i)
+    if len(keep) < xv.size:
+        return xv[keep], yv[keep], zv[keep]
+    return xv, yv, zv
+
+
+def _hull_mask(
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    qpts: NDArray[np.float64],
+    zqv: NDArray[np.float64],
+) -> NDArray[np.float64]:
+    """Set query points outside the data convex hull to NaN (extrapolation='none')."""
+    if xv.size < 3:
+        return zqv
+    try:
+        tri = Delaunay(np.column_stack([xv, yv]))
+    except QhullError:
+        return zqv
+    out = zqv.copy()
+    out[tri.find_simplex(qpts) < 0] = np.nan
+    return out
+
+
+def _interp_scattered(
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    zv: NDArray[np.float64],
+    xqv: NDArray[np.float64],
+    yqv: NDArray[np.float64],
+    method: str,
+    extrapolation: str,
+) -> NDArray[np.float64]:
+    pts = np.column_stack([xv, yv])
+    qpts = np.column_stack([xqv, yqv])
+    if method in ("natural", "cubic"):
+        # Sibson natural-neighbour (MATLAB aliases 'cubic' to 'natural'); already
+        # NaN outside the convex hull.
+        zqv = sibson_interpolate(xv, yv, zv, xqv, yqv)
+    elif method == "nearest":
+        zqv = np.asarray(griddata(pts, zv, qpts, method="nearest"), dtype=float)
+        if extrapolation == "none":
+            zqv = _hull_mask(xv, yv, qpts, zqv)
+        return zqv
+    else:  # linear
+        try:
+            zqv = np.asarray(griddata(pts, zv, qpts, method="linear"), dtype=float)
+        except QhullError:
+            # Degenerate (collinear / coincident) cloud — Qhull can't triangulate,
+            # so linear interpolation is undefined. Degrade to NaN (as for points
+            # outside the convex hull) rather than let QhullError escape as a 500;
+            # mirrors the QhullError guards already used by _hull_mask and natural.
+            zqv = np.full(qpts.shape[0], np.nan)
+    if extrapolation == "nearest":
+        nan_mask = np.isnan(zqv)
+        if nan_mask.any():
+            zqv[nan_mask] = griddata(pts, zv, qpts[nan_mask], method="nearest")
+    return zqv
+
+
+def _interp_idw(
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    zv: NDArray[np.float64],
+    xqv: NDArray[np.float64],
+    yqv: NDArray[np.float64],
+    power: float,
+) -> NDArray[np.float64]:
+    zqv = np.empty(xqv.size)
+    for k in range(xqv.size):
+        d = np.sqrt((xqv[k] - xv) ** 2 + (yqv[k] - yv) ** 2)
+        exact = np.flatnonzero(d == 0)
+        if exact.size:
+            zqv[k] = zv[exact[0]]
+            continue
+        w = 1.0 / (d**power)
+        zqv[k] = float(np.sum(w * zv) / np.sum(w))
+    return zqv
+
+
+def _interp_thinplate(
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    zv: NDArray[np.float64],
+    xqv: NDArray[np.float64],
+    yqv: NDArray[np.float64],
+    lam: float,
+    extrapolation: str,
+) -> NDArray[np.float64]:
+    n = xv.size
+    r2 = (xv[:, None] - xv[None, :]) ** 2 + (yv[:, None] - yv[None, :]) ** 2
+    r = np.sqrt(r2)
+    phi = np.zeros((n, n))
+    mask = r > 0
+    phi[mask] = r2[mask] * np.log(r[mask])
+    pmat = np.column_stack([np.ones(n), xv, yv])
+    amat = np.block([[phi + lam * np.eye(n), pmat], [pmat.T, np.zeros((3, 3))]])
+    try:
+        coeff = np.linalg.solve(amat, np.concatenate([zv, np.zeros(3)]))
+    except np.linalg.LinAlgError as exc:
+        raise ValueError(
+            "thin-plate spline: data matrix is singular — points are collinear or "
+            "coincident; use a coarser grid or a different interpolation method"
+        ) from exc
+    w, a = coeff[:n], coeff[n : n + 3]
+
+    zqv = np.empty(xqv.size)
+    for qi in range(xqv.size):
+        r2q = (xqv[qi] - xv) ** 2 + (yqv[qi] - yv) ** 2
+        rq = np.sqrt(r2q)
+        phiq = np.zeros(n)
+        mk = rq > 0
+        phiq[mk] = r2q[mk] * np.log(rq[mk])
+        zqv[qi] = float(w @ phiq + a[0] + a[1] * xqv[qi] + a[2] * yqv[qi])
+    if extrapolation == "none":
+        zqv = _hull_mask(xv, yv, np.column_stack([xqv, yqv]), zqv)
+    return zqv
+
+
+def interpolate2d(
+    x: ArrayLike,
+    y: ArrayLike,
+    z: ArrayLike,
+    xq: ArrayLike,
+    yq: ArrayLike,
+    *,
+    method: str = "natural",
+    idw_power: float = 2.0,
+    extrapolation: str = "none",
+    smoothing: float = 0.0,
+) -> dict[str, Any]:
+    """Interpolate scattered (x, y, z) onto query points. Port of utilities.interpolate2D.
+
+    Returns ``{"zq", "method", "stats": {"nPoints", "rmse"}}`` (rmse is NaN — the
+    expensive leave-one-out estimate is not computed). See module docstring for
+    per-method parity. ``extrapolation='none'`` yields NaN outside the convex hull.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    zv = np.asarray(z, dtype=float).ravel()
+    if not (xv.size == yv.size == zv.size):
+        raise ValueError("x, y, and z must have the same number of elements")
+    if xv.size < 3:
+        raise ValueError("at least 3 data points are required for 2-D interpolation")
+    xv, yv, zv = _unique_rows(xv, yv, zv)
+
+    query_shape = np.asarray(xq, dtype=float).shape
+    xqv = np.asarray(xq, dtype=float).ravel()
+    yqv = np.asarray(yq, dtype=float).ravel()
+
+    if method in _SCATTERED:
+        zqv = _interp_scattered(xv, yv, zv, xqv, yqv, method, extrapolation)
+    elif method == "thinplate":
+        zqv = _interp_thinplate(xv, yv, zv, xqv, yqv, smoothing, extrapolation)
+    elif method == "idw":
+        zqv = _interp_idw(xv, yv, zv, xqv, yqv, idw_power)
+        if extrapolation == "none":
+            zqv = _hull_mask(xv, yv, np.column_stack([xqv, yqv]), zqv)
+    else:
+        raise ValueError(f"unknown method {method!r}")
+
+    return {
+        "zq": zqv.reshape(query_shape),
+        "method": method,
+        "stats": {"nPoints": int(xv.size), "rmse": float("nan")},
+    }
+
+
+def regrid2d(
+    x: ArrayLike,
+    y: ArrayLike,
+    z: ArrayLike,
+    *,
+    nx: int = 100,
+    ny: int = 100,
+    method: str = "natural",
+    xlim: tuple[float, float] | None = None,
+    ylim: tuple[float, float] | None = None,
+    extrapolation: str = "none",
+    smoothing: float = 0.0,
+    idw_power: float = 2.0,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    """Resample scattered data onto a regular grid. Port of utilities.regrid2D.
+
+    Returns ``(Xq, Yq, Zq)`` meshgrids (shape ``ny x nx``). Limits default to the
+    data extent. See ``interpolate2d`` for per-method parity caveats.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    zv = np.asarray(z, dtype=float).ravel()
+    # Scattered interpolation (scatteredInterpolant/griddata) needs finite points;
+    # drop any non-finite (x, y, z) triple so real data with NaN gaps still grids.
+    # No-op on clean data, so golden parity holds.
+    finite = np.isfinite(xv) & np.isfinite(yv) & np.isfinite(zv)
+    if not bool(finite.all()):
+        xv, yv, zv = xv[finite], yv[finite], zv[finite]
+    xl = (float(xv.min()), float(xv.max())) if xlim is None else (float(xlim[0]), float(xlim[1]))
+    yl = (float(yv.min()), float(yv.max())) if ylim is None else (float(ylim[0]), float(ylim[1]))
+    if xl[0] >= xl[1]:
+        raise ValueError(
+            "cannot build a 2-D grid: the x axis has no range "
+            f"(min == max == {xl[0]:g}); it is constant or single-valued"
+        )
+    if yl[0] >= yl[1]:
+        raise ValueError(
+            "cannot build a 2-D grid: the y axis has no range "
+            f"(min == max == {yl[0]:g}); it is constant or single-valued"
+        )
+    x_grid = np.linspace(xl[0], xl[1], nx)
+    y_grid = np.linspace(yl[0], yl[1], ny)
+    xq, yq = np.meshgrid(x_grid, y_grid)
+    result = interpolate2d(
+        xv, yv, zv, xq, yq,
+        method=method, extrapolation=extrapolation, smoothing=smoothing, idw_power=idw_power,
+    )
+    return xq, yq, np.asarray(result["zq"], dtype=float)

quantized/calc/linecut.py

@@ -0,0 +1,269 @@
+"""Line cuts + projections from 2-D RSM DataStructs (ORIGIN_GAP_PLAN #18/#46).
+
+Port + extension of MATLAB ``+bosonPlotter/extract2DLineCut.m``. The MATLAB
+reference offered single nearest-row/column cuts (Shift/Ctrl+click) in angular
+or Q space. Extended here:
+
+- **width-averaged cuts** (``width > 0`` averages every row/column whose axis
+  value falls within ±width/2 — a swath, not one detector line);
+- **arbitrary segment cuts** (:func:`cut_segment` — any angle through the
+  cloud, distance-parametrized, with optional perpendicular averaging);
+- **integrated projections** (:func:`projection` — the full-map sum onto
+  either axis; the "pixels" direction reproduces MATLAB's integrated 1-D
+  fallback ``sum(intensityMap, 1)``).
+
+Cuts work on the (frames × pixels) index grid via ``metadata.map_shape``, so
+they are exact detector-line extractions for all three mesh kinds (mesh /
+snapshot / coupled). Segment cuts interpolate the scattered cloud directly
+and need no grid. Every function returns a 1-D ``DataStruct`` ready for the
+library (plot, fit, export like any scan).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.calc.interp2d import interpolate2d
+from quantized.datastruct import DataStruct
+
+__all__ = ["cut_segment", "line_cut", "projection"]
+
+_SPACES = ("angular", "q")
+
+
+def _full_grids(ds: DataStruct) -> dict[str, Any]:
+    """Reshape the scattered 2-D DataStruct to full (N, M) per-point grids."""
+    if not ds.metadata.get("is2D"):
+        raise ValueError("dataset is not a 2-D map (metadata.is2D not set)")
+    shape = ds.metadata.get("map_shape")
+    if not shape or len(shape) != 2:
+        raise ValueError(
+            "dataset has no regular (frames x pixels) grid (map_shape missing) — "
+            "use cut_segment, which works on the scattered cloud"
+        )
+    n, m = int(shape[0]), int(shape[1])
+    axis1_name = str(ds.metadata.get("axis1_name", "Omega"))
+    out: dict[str, Any] = {
+        "tt": ds.column("2Theta").reshape(n, m),
+        "sec": ds.column(axis1_name).reshape(n, m),
+        "i": ds.column("Intensity").reshape(n, m),
+        "qx": None,
+        "qz": None,
+        "sec_name": axis1_name,
+        "unit": ds.units[list(ds.labels).index("Intensity")],
+    }
+    if "Qx" in ds.labels and "Qz" in ds.labels:
+        out["qx"] = ds.column("Qx").reshape(n, m)
+        out["qz"] = ds.column("Qz").reshape(n, m)
+    return out
+
+
+def _require_q(g: dict[str, Any]) -> None:
+    if g["qx"] is None:
+        raise ValueError("dataset has no Qx/Qz columns — Q-space cut unavailable")
+
+
+def _cut_result(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    *,
+    label: str,
+    x_name: str,
+    x_unit: str,
+    unit: str,
+    ds: DataStruct,
+    extra: dict[str, Any] | None = None,
+) -> DataStruct:
+    """Assemble the 1-D cut DataStruct (ascending x for the plot stage)."""
+    order = np.argsort(x, kind="stable")
+    metadata: dict[str, Any] = {
+        "source": ds.metadata.get("source", ""),
+        "parser_name": "line_cut",
+        "x_column_name": x_name,
+        "x_column_unit": x_unit,
+        "cut_label": label,
+        "is2D": False,
+        **(extra or {}),
+    }
+    return DataStruct.create(
+        np.asarray(x, dtype=float)[order],
+        np.asarray(y, dtype=float)[order],
+        labels=["Intensity"],
+        units=[unit],
+        metadata=metadata,
+    )
+
+
+def line_cut(
+    ds: DataStruct,
+    *,
+    direction: str,
+    value: float,
+    space: str = "angular",
+    width: float = 0.0,
+) -> DataStruct:
+    """Horizontal / vertical cut through the map at a fixed axis value.
+
+    ``direction='h'``: intensity vs the horizontal axis (2Theta, or Qx in
+    Q-space) at the frame(s) nearest ``value`` on the vertical axis.
+    ``direction='v'``: intensity vs the vertical axis (secondary motor, or Qz)
+    at the pixel column(s) nearest ``value`` on the horizontal axis.
+
+    ``width=0`` reproduces MATLAB's single nearest-line cut; ``width>0``
+    averages every line whose axis value lies within ±width/2 of ``value``
+    (falls back to the nearest single line when none do).
+    """
+    if direction not in ("h", "v"):
+        raise ValueError(f'direction must be "h" or "v", got "{direction}"')
+    if space not in _SPACES:
+        raise ValueError(f"space must be one of {_SPACES}, got {space!r}")
+    if width < 0:
+        raise ValueError("width must be >= 0")
+    g = _full_grids(ds)
+    if space == "q":
+        _require_q(g)
+
+    if direction == "h":
+        sel = np.mean(g["sec"] if space == "angular" else g["qz"], axis=1)
+        x_grid = g["tt"] if space == "angular" else g["qx"]
+        pick = np.abs(sel - value) <= width / 2.0
+        if not pick.any():
+            pick = np.zeros(sel.size, dtype=bool)
+            pick[int(np.argmin(np.abs(sel - value)))] = True
+        x = np.mean(x_grid[pick, :], axis=0)
+        y = np.mean(g["i"][pick, :], axis=0)
+        fixed_name = g["sec_name"] if space == "angular" else "Qz"
+        x_name = "2Theta" if space == "angular" else "Qx"
+    else:
+        sel = np.mean(g["tt"] if space == "angular" else g["qx"], axis=0)
+        x_grid = g["sec"] if space == "angular" else g["qz"]
+        pick = np.abs(sel - value) <= width / 2.0
+        if not pick.any():
+            pick = np.zeros(sel.size, dtype=bool)
+            pick[int(np.argmin(np.abs(sel - value)))] = True
+        x = np.mean(x_grid[:, pick], axis=1)
+        y = np.mean(g["i"][:, pick], axis=1)
+        fixed_name = "2Theta" if space == "angular" else "Qx"
+        x_name = g["sec_name"] if space == "angular" else "Qz"
+
+    unit_ax = "deg" if space == "angular" else "Ang^-1"
+    centre = float(np.mean(sel[pick]))
+    tag = "H-cut" if direction == "h" else "V-cut"
+    label = f"{tag} {fixed_name}≈{centre:.6g} {unit_ax}"
+    if width > 0:
+        label += f" ±{width / 2:.4g}"
+    return _cut_result(
+        x, y, label=label, x_name=x_name, x_unit=unit_ax, unit=g["unit"], ds=ds,
+        extra={"cut_direction": direction, "cut_value": centre,
+               "cut_width": width, "cut_space": space, "n_lines": int(pick.sum())},
+    )
+
+
+def cut_segment(
+    ds: DataStruct,
+    *,
+    p0: tuple[float, float],
+    p1: tuple[float, float],
+    n: int = 200,
+    width: float = 0.0,
+    space: str = "angular",
+) -> DataStruct:
+    """Arbitrary straight cut from ``p0`` to ``p1`` through the scattered cloud.
+
+    Coordinates are ``(2Theta, <axis1>)`` for ``space='angular'`` or
+    ``(Qx, Qz)`` for ``space='q'``. Samples ``n`` points along the segment by
+    linear scattered interpolation; ``width>0`` additionally averages 7
+    parallel lines spread over ±width/2 perpendicular to the cut (NaN outside
+    the data hull is ignored). x = distance from ``p0``.
+    """
+    if space not in _SPACES:
+        raise ValueError(f"space must be one of {_SPACES}, got {space!r}")
+    if not ds.metadata.get("is2D"):
+        raise ValueError("dataset is not a 2-D map (metadata.is2D not set)")
+    if n < 2:
+        raise ValueError("n must be >= 2")
+    if width < 0:
+        raise ValueError("width must be >= 0")
+    axis1_name = str(ds.metadata.get("axis1_name", "Omega"))
+    if space == "q":
+        if "Qx" not in ds.labels:
+            raise ValueError("dataset has no Qx/Qz columns — Q-space cut unavailable")
+        xs, ys = ds.column("Qx"), ds.column("Qz")
+        unit_ax = "Ang^-1"
+    else:
+        xs, ys = ds.column("2Theta"), ds.column(axis1_name)
+        unit_ax = "deg"
+    iv = ds.column("Intensity")
+
+    d = np.asarray([p1[0] - p0[0], p1[1] - p0[1]], dtype=float)
+    length = float(np.hypot(*d))
+    if length <= 0:
+        raise ValueError("p0 and p1 must be distinct points")
+    d /= length
+    perp = np.asarray([-d[1], d[0]])
+    t = np.linspace(0.0, length, n)
+    base_x = p0[0] + t * d[0]
+    base_y = p0[1] + t * d[1]
+
+    offsets = np.linspace(-width / 2.0, width / 2.0, 7) if width > 0 else np.asarray([0.0])
+    xq = (base_x[None, :] + offsets[:, None] * perp[0]).ravel()
+    yq = (base_y[None, :] + offsets[:, None] * perp[1]).ravel()
+    zq = np.asarray(
+        interpolate2d(xs, ys, iv, xq, yq, method="linear")["zq"], dtype=float
+    ).reshape(offsets.size, n)
+    with np.errstate(invalid="ignore"):
+        y = np.nanmean(zq, axis=0)
+
+    unit = ds.units[list(ds.labels).index("Intensity")]
+    label = (
+        f"Cut ({p0[0]:.5g}, {p0[1]:.5g})→({p1[0]:.5g}, {p1[1]:.5g}) "
+        f"[{'Q' if space == 'q' else 'angular'}]"
+    )
+    if width > 0:
+        label += f" ±{width / 2:.4g}"
+    return _cut_result(
+        t, y, label=label, x_name="Distance", x_unit=unit_ax, unit=unit, ds=ds,
+        extra={"cut_p0": list(p0), "cut_p1": list(p1), "cut_width": width,
+               "cut_space": space, "cut_samples": int(n)},
+    )
+
+
+def projection(
+    ds: DataStruct,
+    *,
+    axis: str = "pixels",
+    space: str = "angular",
+) -> DataStruct:
+    """Integrate the whole map onto one axis.
+
+    ``axis='pixels'``: sum over frames → intensity vs 2Theta (or Qx) — exactly
+    MATLAB importXRDML's integrated 1-D fallback for a mesh.
+    ``axis='frames'``: sum over pixels → intensity vs the secondary motor
+    (or Qz) — a rocking-curve-like profile.
+    """
+    if axis not in ("pixels", "frames"):
+        raise ValueError(f'axis must be "pixels" or "frames", got "{axis}"')
+    if space not in _SPACES:
+        raise ValueError(f"space must be one of {_SPACES}, got {space!r}")
+    g = _full_grids(ds)
+    if space == "q":
+        _require_q(g)
+
+    if axis == "pixels":
+        x = np.mean(g["tt"] if space == "angular" else g["qx"], axis=0)
+        y = np.sum(g["i"], axis=0)
+        x_name = "2Theta" if space == "angular" else "Qx"
+    else:
+        x = np.mean(g["sec"] if space == "angular" else g["qz"], axis=1)
+        y = np.sum(g["i"], axis=1)
+        x_name = g["sec_name"] if space == "angular" else "Qz"
+
+    unit_ax = "deg" if space == "angular" else "Ang^-1"
+    label = f"Projection Σ{'frames' if axis == 'pixels' else 'pixels'} → I vs {x_name}"
+    return _cut_result(
+        x, y, label=label, x_name=x_name, x_unit=unit_ax, unit=g["unit"], ds=ds,
+        extra={"cut_axis": axis, "cut_space": space},
+    )