getframes 2.2.0__tar.gz → 2.4.0__tar.gz

{getframes-2.2.0 → getframes-2.4.0}/CHANGELOG.md

@@ -6,6 +6,94 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-10-07
+
+### Added
+
+- **`device="gpu:N"` and `device="auto"`.** Every `device` argument (`Camera`,
+  `get_backend`, and the CLI's `[camera]` table) now speaks the AO stack's
+  vocabulary (aocore CONVENTIONS 8.1): `"cpu"`, `"gpu"`, `"gpu:N"` for CUDA
+  device `N`, and `"auto"`, which picks the GPU when CuPy is installed and sees
+  a device and the CPU otherwise. A `"gpu:N"` beyond the devices CuPy sees
+  raises a `ValueError` naming the count. The old spellings (`"numpy"`,
+  `"cuda"`, `"cupy"`) still work, now case-insensitively. A GPU camera is
+  pinned to its card: the fixed-pattern maps and the cuRAND streams are created
+  on it and every camera method runs with it current, so a `"gpu:1"` camera
+  works whichever device is current at the call, and `with_config` keeps it.
+  New: `Camera.device_id`, `ArrayBackend.device_id`, `ArrayBackend.spec`
+  (`"cpu"` or `"gpu:N"`) and `ArrayBackend.activate()` (the device context,
+  for calling the low-level `noise` functions on another card).
+- **`precision="single"` / `"double"`.** The working precision takes the
+  shared names (aocore CONVENTIONS 8.2), with `"float32"`/`"float64"` kept as
+  aliases: on `Camera`, as a new `precision` keyword on
+  `Scene.photon_rate_map`/`photoelectron_rate_map` (beside `dtype`), and on the
+  `noise` functions that take a `float_dtype` (`simulate_frame`,
+  `fixed_pattern_maps`, `dark_signal_map`, `photo_signal_map`). A `dtype` and a
+  `precision` that disagree raise `ValueError`. `getframes.resolve_precision`
+  maps any of these names to the NumPy dtype. `Camera.precision` still reports
+  the dtype name (`"float32"`/`"float64"`) whichever spelling was passed.
+  `dataset.pairs(dtype=...)` is unchanged: it is the host *storage* type of the
+  finished arrays, not a working precision.
+- The CLI's `[camera]` table takes a `device` key.
+- **Conformance tests** for the device and precision vocabulary, including that
+  each precision name selects the same dtype as in aocore.
+- **Edge-flux conformance for every PSF model.** `tests/test_conformance.py`
+  now uses aocore 0.1.3's image-builder checks (`check_point_source_centring`,
+  `check_point_source_flux`) instead of feeding analytic PSFs through the
+  OPD-driven checks with a dummy OPD, and adds `check_edge_flux_loss` for
+  Gaussian, Moffat, elliptical Gaussian, Airy and array PSFs, guarding the
+  2.3.0 fix. The `dev` extra pins `aocore>=0.1.3,<0.2`; the runtime
+  requirement is unchanged.
+
+### Changed
+
+- An unknown `device` string now raises `ValueError` listing the accepted words
+  (`'cpu', 'gpu', 'gpu:N' ... or 'auto'`), and a non-string `device` a
+  `TypeError`. `device="gpu"` with CuPy installed but no CUDA device raises
+  `RuntimeError` at construction rather than failing at the first frame.
+- `Camera.__repr__` shows the GPU number (`device='gpu:0'`).
+- The noise functions' `float_dtype` default is now `None` (still float64).
+
+### Fixed
+
+- `dataset.pairs` with a GPU camera failed on an implicit CuPy-to-NumPy
+  conversion; it now copies each frame to the host through `to_numpy`, as do
+  the CLI's `.npy`/`.npz` writers now that the CLI can select a GPU.
+
+## [2.3.0] - 2026-10-07
+
+### Fixed
+
+- **`MoffatPSF`, `EllipticalGaussianPSF` and `AiryPSF` no longer put light that
+  falls off the frame back onto it.** They normalised their stamp *after*
+  clipping it to the frame, so a source on the edge column deposited its full
+  flux instead of the part that lands on the detector (a Moffat star centred on
+  column 0 kept 100% of its light, where `GaussianPSF` correctly keeps about
+  half). The stamp is now normalised before clipping, which follows the AO stack
+  convention that light lost at a detector edge is lost, not renormalised
+  (aocore CONVENTIONS 3.3). Sources wholly inside the frame are unchanged.
+
+### Changed
+
+- **Generic primitives now come from `aocore`.** getframes is part of an
+  adaptive-optics stack whose shared conventions and primitives live in
+  [`aocore`](https://github.com/jacotay7/aocore), now a core dependency
+  (`aocore>=0.1.2,<0.2`). `noise.block_sum` is `aocore.block_sum`, re-exported
+  so existing imports keep working; it accepts everything it did before and now
+  also takes a `(fy, fx)` factor and leading batch axes, and raises a clear
+  `ValueError` for a factor below 1 or a shape that does not divide (previously
+  a bare reshape error, or a `ZeroDivisionError` for a factor of 0).
+  `Frame.binned` sums through it. `AiryPSF` and `Thermal` take their radians per
+  arcsecond from `aocore.ARCSEC_TO_RAD`, and `Vignetting` its centred grid from
+  `aocore.coordinate_grid`. Every output is bit-for-bit unchanged.
+
+### Added
+
+- **Conformance tests** (`tests/test_conformance.py`) run the
+  `aocore.conformance` checks that apply to a detector package: every PSF model
+  deposits unit flux, a source at `(n - 1) / 2` and the vignetting pattern are
+  centred on the optical axis for odd and even windows.
+
 ## [2.2.0] - 2026-08-24
 
 ### Added
@@ -558,7 +646,9 @@ together in 1.0.
 - Documentation, runnable examples, and CI (lint, type-check, test matrix, PyPI
   release via Trusted Publishing).
 
-[Unreleased]: https://github.com/jacotay7/getframes/compare/2.2.0...HEAD
+[Unreleased]: https://github.com/jacotay7/getframes/compare/2.4.0...HEAD
+[2.4.0]: https://github.com/jacotay7/getframes/compare/2.3.0...2.4.0
+[2.3.0]: https://github.com/jacotay7/getframes/compare/2.2.0...2.3.0
 [2.2.0]: https://github.com/jacotay7/getframes/compare/2.1.1...2.2.0
 [2.1.1]: https://github.com/jacotay7/getframes/compare/2.1.0...2.1.1
 [2.1.0]: https://github.com/jacotay7/getframes/compare/2.0.0...2.1.0

{getframes-2.2.0 → getframes-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getframes
-Version: 2.2.0
+Version: 2.4.0
 Summary: Generate physically realistic synthetic camera frames (CCD/CMOS/EMCCD/eAPD/sCMOS) — dark, bias, flat, and rendered star fields — with auditable noise physics for scientific imaging pipelines.
 Project-URL: Homepage, https://github.com/jacotay7/getframes
 Project-URL: Documentation, https://jacotay7.github.io/getframes/
@@ -23,11 +23,13 @@ Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: aocore<0.2,>=0.1.2
 Requires-Dist: astropy>=5.0
 Requires-Dist: numpy>=1.23
 Requires-Dist: scipy>=1.10
 Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: dev
+Requires-Dist: aocore<0.2,>=0.1.3; extra == 'dev'
 Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
@@ -72,7 +74,7 @@ switches to CUDA (via CuPy) with a single argument.
 ## Install
 
 ```bash
-pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install getframes            # CPU (NumPy + SciPy + astropy + aocore)
 pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
 pip install -e '.[dev]'          # from a clone, for development
 ```
@@ -105,7 +107,7 @@ frame = cam.with_config(resolution=(256, 256)).observe(scene, exposure=300.0, se
 
 import cupy as cp  # and the same path on a GPU
 
-cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="single")
 rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
 frame = cam.expose(rate, exposure=1.0e-3, seed=0)  # CuPy ADU, no host copy
 ```
@@ -185,8 +187,8 @@ for the methodology.
 - **Scale & datasets** — a float32 fast path, vectorised multi-source rendering,
   a streaming raw+truth `dataset` generator and a `getframes` CLI; see
   **[Scale & datasets](https://jacotay7.github.io/getframes/guides/datasets/)**.
-- **GPU-optional** — every camera takes `device="gpu"` (CuPy) and keeps the
-  detector path and truth arrays device-resident. CPU and GPU have independent
+- **GPU-optional** — every camera takes `device="gpu"`, `"gpu:N"` or `"auto"`
+  (CuPy) and keeps the detector path and truth arrays device-resident. CPU and GPU have independent
   RNG streams, so a `seed` repeats exactly on a fixed backend while parity across
   backends means matching statistics, not identical pixels.
 - **Reproducible and typed** — all randomness flows through a camera-owned seeded

{getframes-2.2.0 → getframes-2.4.0}/README.md

@@ -27,7 +27,7 @@ switches to CUDA (via CuPy) with a single argument.
 ## Install
 
 ```bash
-pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install getframes            # CPU (NumPy + SciPy + astropy + aocore)
 pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
 pip install -e '.[dev]'          # from a clone, for development
 ```
@@ -60,7 +60,7 @@ frame = cam.with_config(resolution=(256, 256)).observe(scene, exposure=300.0, se
 
 import cupy as cp  # and the same path on a GPU
 
-cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="single")
 rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
 frame = cam.expose(rate, exposure=1.0e-3, seed=0)  # CuPy ADU, no host copy
 ```
@@ -140,8 +140,8 @@ for the methodology.
 - **Scale & datasets** — a float32 fast path, vectorised multi-source rendering,
   a streaming raw+truth `dataset` generator and a `getframes` CLI; see
   **[Scale & datasets](https://jacotay7.github.io/getframes/guides/datasets/)**.
-- **GPU-optional** — every camera takes `device="gpu"` (CuPy) and keeps the
-  detector path and truth arrays device-resident. CPU and GPU have independent
+- **GPU-optional** — every camera takes `device="gpu"`, `"gpu:N"` or `"auto"`
+  (CuPy) and keeps the detector path and truth arrays device-resident. CPU and GPU have independent
   RNG streams, so a `seed` repeats exactly on a fixed backend while parity across
   backends means matching statistics, not identical pixels.
 - **Reproducible and typed** — all randomness flows through a camera-owned seeded

{getframes-2.2.0 → getframes-2.4.0}/pyproject.toml

@@ -36,6 +36,7 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
+    "aocore>=0.1.2,<0.2",
     "numpy>=1.23",
     "scipy>=1.10",
     "astropy>=5.0",
@@ -44,6 +45,8 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+    # The test suite runs aocore's image-builder conformance checks (0.1.3+).
+    "aocore>=0.1.3,<0.2",
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "ruff>=0.6",

{getframes-2.2.0 → getframes-2.4.0}/src/getframes/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: MIT
 """Single source of truth for the package version."""
 
-__version__ = "2.2.0"
+__version__ = "2.4.0"

{getframes-2.2.0 → getframes-2.4.0}/src/getframes/__init__.py

@@ -21,7 +21,7 @@ from .analysis import (
     nondestructive_stack_statistics,
     ramp_photon_transfer,
 )
-from .backend import ArrayBackend, get_array_module, get_backend, to_numpy
+from .backend import ArrayBackend, get_array_module, get_backend, resolve_precision, to_numpy
 from .calibrate import calibrate, combine
 from .camera import Camera
 from .config import CameraConfig, SensorType
@@ -108,5 +108,6 @@ __all__ = [
     "load_preset",
     "nondestructive_stack_statistics",
     "ramp_photon_transfer",
+    "resolve_precision",
     "to_numpy",
 ]

getframes-2.4.0/src/getframes/backend.py

@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: MIT
+"""Optional array backends for detector simulation.
+
+NumPy remains the reference implementation.  The CuPy backend is imported only
+when requested, so installing and importing :mod:`getframes` stays CPU-only by
+default.  Detector physics receives an :class:`ArrayBackend` explicitly; this
+keeps photon-rate, electron, truth, and ADU arrays on one device for the complete
+signal chain.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Generator, Iterator
+from dataclasses import dataclass
+from functools import wraps
+from inspect import isgeneratorfunction
+from typing import Any, ParamSpec, TypeVar, cast
+
+import numpy as np
+from numpy.typing import DTypeLike
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+_CPU_NAMES = frozenset({"cpu", "numpy"})
+_GPU_NAMES = frozenset({"gpu", "cuda", "cupy"})
+_DEVICE_HELP = (
+    "expected 'cpu', 'gpu', 'gpu:N' (CUDA device N) or 'auto' "
+    "(aliases: 'numpy' for 'cpu'; 'cuda'/'cupy' for 'gpu')"
+)
+
+# Working-precision vocabulary (aocore CONVENTIONS 8.2): the canonical names are
+# "single"/"double"; "float32"/"float64" are aliases.
+_PRECISIONS: dict[str, type[np.floating[Any]]] = {
+    "single": np.float32,
+    "double": np.float64,
+    "float32": np.float32,
+    "float64": np.float64,
+}
+
+
+def _cupy_seed(seed: Any) -> int | None:
+    """Map NumPy-compatible seed input onto CuPy RandomState's uint32 seed."""
+    if seed is None:
+        return None
+    return int(np.random.SeedSequence(int(seed)).generate_state(1, dtype=np.uint32)[0])
+
+
+class _CuPyGenerator:
+    """Expose the NumPy Generator spellings over a fast CuPy RandomState."""
+
+    def __init__(self, generator: Any, xp: Any, float_dtype: Any) -> None:
+        self._generator = generator
+        self._xp = xp
+        self._float_dtype = float_dtype
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._generator, name)
+
+    def normal(self, loc: Any = 0.0, scale: Any = 1.0, size: Any = None) -> Any:
+        """Draw a scaled normal variate directly in the working precision."""
+        return self._generator.normal(loc=loc, scale=scale, size=size, dtype=self._float_dtype)
+
+    def standard_normal(self, size: Any = None, dtype: Any = None) -> Any:
+        """Draw a standard normal variate in the working precision."""
+        selected_dtype = self._float_dtype if dtype is None else dtype
+        return self._generator.standard_normal(size=size, dtype=selected_dtype)
+
+    def lognormal(self, mean: Any = 0.0, sigma: Any = 1.0, size: Any = None) -> Any:
+        """Draw a log-normal variate without falling back to global RNG state."""
+        return self._xp.exp(self.normal(mean, sigma, size))
+
+    def gamma(self, shape: Any, scale: Any = 1.0, size: Any = None) -> Any:
+        """Draw Gamma variates directly in the detector working precision."""
+        return self._generator.gamma(shape=shape, scale=scale, size=size, dtype=self._float_dtype)
+
+    def integers(self, low: Any, high: Any = None, size: Any = None) -> Any:
+        """NumPy-Generator spelling for CuPy RandomState's ``randint``."""
+        return self._generator.randint(low, high=high, size=size)
+
+    def random(self, size: Any = None) -> Any:
+        """NumPy-Generator spelling for CuPy RandomState's uniform sampler."""
+        return self._generator.random_sample(size=size)
+
+    def seed(self, seed: Any) -> None:
+        """Reset this private per-call stream without rebuilding cuRAND state."""
+        self._generator.seed(_cupy_seed(seed))
+
+
+@dataclass(frozen=True)
+class ArrayBackend:
+    """Array namespace and RNG factory for one detector execution device.
+
+    Attributes
+    ----------
+    xp:
+        The array module, :mod:`numpy` or :mod:`cupy`.
+    device:
+        Device kind, ``"cpu"`` or ``"gpu"``.
+    device_id:
+        CUDA device number the GPU backend allocates on and launches kernels on
+        (``None`` for the CPU backend). :func:`get_backend` always fills it in for
+        a GPU backend, so a camera stays on one card whatever device is current
+        when it is later called.
+    """
+
+    xp: Any
+    device: str
+    device_id: int | None = None
+
+    @property
+    def is_cpu(self) -> bool:
+        """Whether arrays live in host NumPy storage."""
+        return self.device == "cpu"
+
+    @property
+    def spec(self) -> str:
+        """The ``device`` string that selects this backend again (``"cpu"`` or ``"gpu:N"``)."""
+        if self.is_cpu or self.device_id is None:
+            return self.device
+        return f"{self.device}:{self.device_id}"
+
+    def activate(self) -> contextlib.AbstractContextManager[Any]:
+        """Context that makes this backend's CUDA device current.
+
+        A no-op on the CPU backend. Camera methods enter it themselves; wrap direct
+        calls to the low-level :mod:`getframes.noise` functions in it when using a
+        GPU other than the current one.
+        """
+        if self.is_cpu or self.device_id is None:
+            return contextlib.nullcontext()
+        return cast(contextlib.AbstractContextManager[Any], self.xp.cuda.Device(self.device_id))
+
+    def asarray(self, value: Any, *, dtype: Any | None = None) -> Any:
+        """Convert ``value`` to an array on this backend."""
+        if self.is_cpu:
+            return self.xp.asarray(value, dtype=dtype)
+        with self.activate():
+            return self.xp.asarray(value, dtype=dtype)
+
+    def default_rng(self, seed: Any = None, *, float_dtype: Any = np.float64) -> Any:
+        """Create a backend-native random generator (on this backend's device)."""
+        if self.is_cpu:
+            return self.xp.random.default_rng(seed)
+        # CuPy's Generator construction initializes device-side state and is much
+        # slower than RandomState for the per-exposure seed contract. RandomState
+        # still owns an independent, backend-native cuRAND stream and exposes all
+        # distributions used by the detector chain. The cuRAND state is created on
+        # the selected device, so it must be built inside the device context.
+        with self.activate():
+            state = self.xp.random.RandomState(_cupy_seed(seed))
+        return _CuPyGenerator(state, self.xp, float_dtype)
+
+    def convolve(self, array: Any, kernel: Any) -> Any:
+        """Convolve with constant-zero boundary conditions on this backend."""
+        if self.is_cpu:
+            from scipy import ndimage
+
+            return ndimage.convolve(array, kernel, mode="constant", cval=0.0)
+        from cupyx.scipy import ndimage  # pragma: no cover - optional CUDA dependency
+
+        with self.activate():
+            return ndimage.convolve(array, kernel, mode="constant", cval=0.0)
+
+    def scalar(self, value: Any) -> float:
+        """Transfer one scalar to the host for validation or metadata."""
+        item = value.item() if hasattr(value, "item") else value
+        return float(item)
+
+    def to_numpy(self, value: Any) -> np.ndarray[Any, Any]:
+        """Copy an array to host NumPy storage at an explicit boundary."""
+        if self.is_cpu:
+            return np.asarray(value)
+        return cast(np.ndarray[Any, Any], self.xp.asnumpy(value))
+
+
+_CPU_BACKEND = ArrayBackend(np, "cpu")
+
+
+def _import_cupy() -> Any:
+    """Import CuPy lazily (raises :class:`ImportError` when it is not installed)."""
+    import cupy
+
+    return cupy
+
+
+def _gpu_device_count(cupy: Any) -> int:
+    """Number of CUDA devices CuPy can use (``0`` when the runtime is unusable)."""
+    try:
+        return int(cupy.cuda.runtime.getDeviceCount())
+    except Exception:  # pragma: no cover - depends on the local CUDA driver/runtime
+        return 0
+
+
+def _parse_device(device: str) -> tuple[str, int | None]:
+    """Split a device string into ``("cpu" | "gpu" | "auto", index or None)``."""
+    if not isinstance(device, str):
+        raise TypeError(f"device must be a string, got {type(device).__name__}; {_DEVICE_HELP}.")
+    name = device.strip().lower()
+    base, sep, index = name.partition(":")
+    if base == "auto" and not sep:
+        return "auto", None
+    if base in _CPU_NAMES and not sep:
+        return "cpu", None
+    if base in _GPU_NAMES:
+        if not sep:
+            return "gpu", None
+        if index.isdigit():
+            return "gpu", int(index)
+    raise ValueError(f"unknown device {device!r}; {_DEVICE_HELP}.")
+
+
+def _gpu_backend(device: str, index: int | None) -> ArrayBackend:
+    try:
+        cupy = _import_cupy()
+    except ImportError as exc:
+        raise ImportError(
+            f"device={device!r} requires CuPy; install getframes[gpu], "
+            "or use device='auto' to fall back to the CPU."
+        ) from exc
+    count = _gpu_device_count(cupy)
+    if count < 1:
+        raise RuntimeError(
+            f"device={device!r} needs a CUDA device, but CuPy sees none; "
+            "use device='auto' to fall back to the CPU."
+        )
+    if index is None:
+        index = int(cupy.cuda.runtime.getDevice())
+    elif index >= count:
+        raise ValueError(
+            f"device={device!r} asks for CUDA device {index}, but CuPy sees {count} "
+            f"device(s) (numbered 0-{count - 1}; CUDA_VISIBLE_DEVICES controls the numbering)."
+        )
+    return ArrayBackend(cupy, "gpu", index)
+
+
+def get_backend(device: str = "cpu") -> ArrayBackend:
+    """Return the backend for ``device``.
+
+    Parameters
+    ----------
+    device:
+        ``"cpu"`` (NumPy, the reference), ``"gpu"`` (CuPy on the current CUDA
+        device), ``"gpu:N"`` (CuPy on CUDA device ``N``), or ``"auto"`` (the
+        current CUDA device when CuPy is installed and sees one, else the CPU).
+        Matching is case-insensitive; ``"numpy"`` is an alias of ``"cpu"`` and
+        ``"cuda"``/``"cupy"`` of ``"gpu"`` (including ``"cuda:N"``).
+
+    Raises
+    ------
+    ValueError
+        For an unknown device string, or a GPU number CuPy does not see.
+    ImportError
+        For ``"gpu"``/``"gpu:N"`` without CuPy installed.
+    RuntimeError
+        For ``"gpu"``/``"gpu:N"`` when CuPy is installed but sees no CUDA device.
+
+    Notes
+    -----
+    CuPy is an optional dependency and is imported lazily, only for a GPU (or
+    ``"auto"``) device.
+    """
+    kind, index = _parse_device(device)
+    if kind == "cpu":
+        return _CPU_BACKEND
+    if kind == "auto":
+        try:
+            cupy = _import_cupy()
+        except ImportError:
+            return _CPU_BACKEND
+        if _gpu_device_count(cupy) < 1:
+            return _CPU_BACKEND
+    return _gpu_backend(device, index)
+
+
+def resolve_precision(precision: str | DTypeLike) -> np.dtype[Any]:
+    """Return the floating-point working dtype named by ``precision``.
+
+    Parameters
+    ----------
+    precision:
+        ``"single"`` or ``"double"`` (the shared AO-stack vocabulary), their
+        aliases ``"float32"``/``"float64"`` (case-insensitive), or a NumPy
+        ``float32``/``float64`` dtype.
+
+    Raises
+    ------
+    ValueError
+        For any other precision.
+    """
+    if isinstance(precision, str):
+        selected = _PRECISIONS.get(precision.strip().lower())
+        if selected is not None:
+            return np.dtype(selected)
+    elif precision is not None:  # np.dtype(None) would silently mean float64
+        try:
+            dtype = np.dtype(precision)
+        except TypeError:
+            dtype = None
+        if dtype is not None and dtype in (np.dtype(np.float32), np.dtype(np.float64)):
+            return dtype
+    raise ValueError(
+        f"precision must be 'single' or 'double' (aliases 'float32'/'float64'), got {precision!r}."
+    )
+
+
+def _working_dtype(
+    dtype: DTypeLike | None, precision: str | None, *, name: str = "dtype"
+) -> np.dtype[Any]:
+    """Merge a legacy ``dtype`` argument with the ``precision`` vocabulary.
+
+    ``None`` for both gives ``float64``. Both may be given only when they agree.
+    """
+    from_dtype = None if dtype is None else np.dtype(dtype)
+    if precision is None:
+        return np.dtype(np.float64) if from_dtype is None else from_dtype
+    from_precision = resolve_precision(precision)
+    if from_dtype is not None and from_dtype != from_precision:
+        raise ValueError(
+            f"{name}={from_dtype.name!r} conflicts with precision={precision!r}; pass one of them."
+        )
+    return from_precision
+
+
+def _on_device(method: Callable[_P, _R]) -> Callable[_P, _R]:
+    """Run a method of an object with a ``_backend`` inside that backend's device context.
+
+    Generator methods enter the context for every step, so lazily produced frames
+    are also computed on the object's device.
+    """
+    if isgeneratorfunction(method):
+
+        @wraps(method)
+        def generator_wrapper(*args: _P.args, **kwargs: _P.kwargs) -> Any:
+            backend: ArrayBackend = args[0]._backend  # type: ignore[attr-defined]
+            iterator = cast(Generator[Any, None, Any], method(*args, **kwargs))
+            return _stepped_on(backend, iterator)
+
+        return cast(Callable[_P, _R], generator_wrapper)
+
+    @wraps(method)
+    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
+        backend: ArrayBackend = args[0]._backend  # type: ignore[attr-defined]
+        with backend.activate():
+            return method(*args, **kwargs)
+
+    return wrapper
+
+
+def _stepped_on(backend: ArrayBackend, iterator: Generator[Any, None, Any]) -> Iterator[Any]:
+    """Advance ``iterator`` one item at a time inside ``backend``'s device context."""
+    while True:
+        with backend.activate():
+            try:
+                item = next(iterator)
+            except StopIteration:
+                return
+        yield item
+
+
+def _array_device(value: Any) -> contextlib.AbstractContextManager[Any]:
+    """Context that makes ``value``'s CUDA device current (a no-op for host arrays)."""
+    if type(value).__module__.split(".", 1)[0] == "cupy":
+        return cast(contextlib.AbstractContextManager[Any], value.device)
+    return contextlib.nullcontext()
+
+
+def get_array_module(value: Any) -> Any:
+    """Return NumPy or CuPy for an existing array without copying it."""
+    module = type(value).__module__.split(".", 1)[0]
+    if module == "cupy":
+        return _import_cupy()
+    return np
+
+
+def to_numpy(value: Any) -> np.ndarray[Any, Any]:
+    """Return ``value`` in host NumPy storage, copying device arrays explicitly."""
+    module = type(value).__module__.split(".", 1)[0]
+    if module == "cupy":
+        return cast(np.ndarray[Any, Any], _import_cupy().asnumpy(value))
+    return np.asarray(value)
+
+
+__all__ = [
+    "ArrayBackend",
+    "get_array_module",
+    "get_backend",
+    "resolve_precision",
+    "to_numpy",
+]