pyRadMC 0.2.0__py3-none-any.whl

pyradmc/__init__.py

@@ -0,0 +1,308 @@
+"""pyradmc: fast photon Monte Carlo for beamlet-resolved treatment planning.
+
+See AGENTS.md for the development contract.
+
+This module is the public API: everything named in ``__all__`` is supported and
+versioned, and everything else is an implementation detail that may move between
+releases. Physical constants and defaults that are accuracy-defining live here too,
+so that there is exactly one place to change them and so that a change is visible in
+a diff. They are not tuning knobs; see AGENTS.md section 2.8.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.2.0"
+
+# --- accuracy-defining defaults ------------------------------------------------
+# Changing any of these requires a test demonstrating the dosimetric effect.
+
+ECUT_MEV: float = 0.200
+"""Electron transport and production cutoff, kinetic energy in MeV (DPM default)."""
+
+PCUT_MEV: float = 0.050
+"""Photon transport cutoff in MeV. Below this, energy is deposited locally."""
+
+DIJ_TRUNCATION_RELATIVE: float = 1.0e-3
+"""Dij column truncation, relative to that beamlet column's maximum.
+
+This biases the low-dose tail, which is where NTCP and LET-guided objectives operate.
+It is tested against DVH endpoints, never against a matrix norm.
+"""
+
+# --- variance-reduction parameters -------------------------------------
+# Russian roulette on low-energy photons (see pyradmc.physics.roulette and the
+# transport loops). Unbiased by construction — these change realizations and
+# efficiency, never expectations; unbiasedness is test-pinned against a
+# roulette-free run. They are still fixed project-wide values, not per-run options
+# (AGENTS.md 2.10): one configuration is what the validation tier certifies.
+
+PHOTON_ROULETTE_MEV: float = 0.5
+"""Photons below this energy play Russian roulette at their creation or scatter.
+
+Chosen just below the 511 keV annihilation line so annihilation photons are exempt
+and positron energy accounting stays analog.
+"""
+
+PHOTON_ROULETTE_SURVIVAL: float = 0.5
+"""Survival probability per game; a survivor's weight is boosted by its inverse."""
+
+PHOTON_ROULETTE_WEIGHT_CAP: float = 4.0
+"""No roulette at or above this weight (the weight-window ceiling).
+
+Caps the boost cascade at two consecutive survivals (1 -> 2 -> 4), bounding the
+graininess a single high-weight deposit can leave in the low-dose tail.
+"""
+
+PHOTON_SPLIT_N: int = 1
+"""Compton splitting multiplicity at a *primary* photon's first Compton scatter.
+
+``N = 1`` is **splitting off — the shipped configuration.** At N == 1 the
+primary Comptons into a single full-weight copy, i.e. exactly analog transport.
+For ``N > 1`` the primary's Compton final state is sampled N times, each copy
+(scattered photon + recoil electron) carrying weight ``1 / N``: N independent
+samples of the dominant scatter source, exactly unbiased and energy-conserving
+per realization, with cost growing about linearly in N. Only the primary
+splits, so the population is bounded and the soft-photon roulette culls the
+degraded copies.
+
+This is a variance-reduction efficiency knob, not accuracy-defining: it changes
+realizations and cost, never expectations. Correctness of the ``N > 1`` path
+(unbiasedness, energy books, N-fold fair copies, variance reduction) is
+test-pinned with N = 2 as the instrument, so the mechanism stays validated
+though it is dormant.
+
+**Why it ships off (measured).** For the analytic-water
+Dij, splitting does not earn its keep: the figure of merit ``1/(sigma^2*time)``
+is < 1 on the reference CPU (variance falls to ~0.67 in the high/mid-dose
+region but cost rises ~1.7x) and roughly neutral on the GPU (a warp retires
+with its longest thread). Worse, it does **not** help the low-dose tail — the
+Dij's NTCP/LET region — because that tail is fed by rare wide-angle multiple
+scatters that uniform primary splitting cannot target; splitting deeper only
+degrades the FOM further (measured).
+
+**Re-measured on a phase-space source, it still ships off.** On
+now-stable-power hardware the FOM ratio split/no-split was 0.75, 0.48, 0.28 at
+N = 2, 4, 8 — worse, monotonically. First-Compton splitting decorrelates copies
+only after that scatter (variance saturates far below 1/N) while cost grows
+~linearly, and emitting a phase-space primary is as cheap as an analytic beam,
+so the cost structure matches. The N > 1 path stays retained and N=2-pinned. See
+docs/decisions.md for the full record and the emission-time-splitting alternative.
+"""
+
+# --- physical constants --------------------------------------------------------
+
+ELECTRON_MASS_MEV: float = 0.510_998_950_69
+"""Electron rest mass energy in MeV (CODATA 2022)."""
+
+GY_PER_MEV_PER_G: float = 1.602_176_634e-10
+"""Absolute-dose calibration: 1 MeV/g = this many gray.
+
+Exact by SI definition: 1 MeV = e x 1e6 J with the elementary charge fixed at
+1.602176634e-19 C (SI 2019), and per gram -> per kilogram is 1e3. The engines
+score dose in MeV/g per emitted history; a planning consumer multiplies by this
+constant for Gy per history and applies its own particles-per-MU scaling on top
+(see :meth:`pyradmc.scoring.dij.DijResult.dose_csc`)."""
+
+RAYLEIGH_MOMENTUM_TRANSFER_PER_MEV: float = 80.65543
+"""Coherent-scattering momentum-transfer coefficient: the tabulated form-factor abscissa
+is ``x [1/angstrom] = this * E[MeV] * sin(theta/2)``, i.e. ``1/hc`` with
+``hc = 0.012_398_42 MeV*angstrom`` (CODATA 2022). EPDL MF=27 tabulates ``F`` against ``x``."""
+
+# --- public API ----------------------------------------------------------------
+# Re-exported lazily (PEP 562). ``import pyradmc`` must stay cheap and dependency-free:
+# a consumer that wants only the constants must not pay for NumPy, and a core-only
+# install (no ``warp`` extra) must not fail at import merely because ``WarpEngine`` is
+# a public name. The ``TYPE_CHECKING`` block below is what mypy and IDEs resolve
+# against; ``_LAZY_EXPORTS`` is what actually runs.
+#
+# Names NOT promoted here are still importable from their modules, but they are not
+# the public API: beam-limiting devices (``pyradmc.geometry.collimation``), the
+# treatment-head pre-solve (``pyradmc.geometry.head``), the CT adapter
+# (``pyradmc.adapters.ct``), the tabulated-table precompiler
+# (``pyradmc.data.tabulated``) and the toy optimizer (``pyradmc.study``) are
+# documented at subpackage level because each is a coherent subsystem with its own
+# vocabulary, not a name a first script reaches for.
+
+if TYPE_CHECKING:
+    from pyradmc.backends.ref.engine import ReferenceEngine
+    from pyradmc.backends.results import TransportResult
+    from pyradmc.backends.warp.engine import WarpEngine
+    from pyradmc.data.analytic import AnalyticCrossSections
+    from pyradmc.data.interface import CrossSectionSource, PhotonProcess
+    from pyradmc.data.materials import (
+        ADIPOSE,
+        AIR,
+        CORTICAL_BONE,
+        LUNG,
+        MATERIALS,
+        TUNGSTEN,
+        WATER,
+        MaterialData,
+    )
+    from pyradmc.data.tabulated.source import TabulatedCrossSections
+    from pyradmc.geometry.fluence import RadialFluence
+    from pyradmc.geometry.grid import VoxelGrid
+    from pyradmc.geometry.phasespace import InMemoryPhaseSpaceSource, PhaseSpaceSource
+    from pyradmc.geometry.source import (
+        BeamletGridSource,
+        BeamletSource,
+        CompositeBeamletSource,
+        CompositeSource,
+        GaussianSpotBeamletSource,
+        GaussianSpotBeamSource,
+        ParallelBeamSource,
+        PencilBeamSource,
+        Primary,
+        PrimaryFluenceBeamletSource,
+        PrimaryFluenceBeamSource,
+        Source,
+        SpectralBeamletSource,
+        SpectralBeamSource,
+    )
+    from pyradmc.geometry.spectrum import ALI_ROGERS_BEAMS, Spectrum, ali_rogers_mv
+    from pyradmc.rng.host import HostRNG
+    from pyradmc.scoring.cylinder import (
+        CylindricalScoringGrid,
+        geometric_edges,
+        graded_edges,
+        uniform_edges,
+    )
+    from pyradmc.scoring.dij import DijResult
+    from pyradmc.scoring.grid import ScoringGrid
+
+_LAZY_EXPORTS: dict[str, str] = {
+    "ADIPOSE": "pyradmc.data.materials",
+    "AIR": "pyradmc.data.materials",
+    "ALI_ROGERS_BEAMS": "pyradmc.geometry.spectrum",
+    "AnalyticCrossSections": "pyradmc.data.analytic",
+    "BeamletGridSource": "pyradmc.geometry.source",
+    "BeamletSource": "pyradmc.geometry.source",
+    "CORTICAL_BONE": "pyradmc.data.materials",
+    "CompositeBeamletSource": "pyradmc.geometry.source",
+    "CompositeSource": "pyradmc.geometry.source",
+    "CrossSectionSource": "pyradmc.data.interface",
+    "CylindricalScoringGrid": "pyradmc.scoring.cylinder",
+    "DijResult": "pyradmc.scoring.dij",
+    "GaussianSpotBeamSource": "pyradmc.geometry.source",
+    "GaussianSpotBeamletSource": "pyradmc.geometry.source",
+    "HostRNG": "pyradmc.rng.host",
+    "InMemoryPhaseSpaceSource": "pyradmc.geometry.phasespace",
+    "LUNG": "pyradmc.data.materials",
+    "MATERIALS": "pyradmc.data.materials",
+    "MaterialData": "pyradmc.data.materials",
+    "ParallelBeamSource": "pyradmc.geometry.source",
+    "PencilBeamSource": "pyradmc.geometry.source",
+    "PhaseSpaceSource": "pyradmc.geometry.phasespace",
+    "PhotonProcess": "pyradmc.data.interface",
+    "Primary": "pyradmc.geometry.source",
+    "PrimaryFluenceBeamSource": "pyradmc.geometry.source",
+    "PrimaryFluenceBeamletSource": "pyradmc.geometry.source",
+    "RadialFluence": "pyradmc.geometry.fluence",
+    "ReferenceEngine": "pyradmc.backends.ref.engine",
+    "ScoringGrid": "pyradmc.scoring.grid",
+    "Source": "pyradmc.geometry.source",
+    "Spectrum": "pyradmc.geometry.spectrum",
+    "SpectralBeamSource": "pyradmc.geometry.source",
+    "SpectralBeamletSource": "pyradmc.geometry.source",
+    "TUNGSTEN": "pyradmc.data.materials",
+    "TabulatedCrossSections": "pyradmc.data.tabulated.source",
+    "TransportResult": "pyradmc.backends.results",
+    "VoxelGrid": "pyradmc.geometry.grid",
+    "WATER": "pyradmc.data.materials",
+    "WarpEngine": "pyradmc.backends.warp.engine",
+    "ali_rogers_mv": "pyradmc.geometry.spectrum",
+    "geometric_edges": "pyradmc.scoring.cylinder",
+    "graded_edges": "pyradmc.scoring.cylinder",
+    "uniform_edges": "pyradmc.scoring.cylinder",
+}
+
+# Third-party module whose absence means an optional extra is not installed -> the
+# extra that provides it. Only consulted when the import actually failed on that
+# module, so a genuine ImportError from inside our own code still propagates as-is.
+_EXTRA_FOR_MISSING_MODULE: dict[str, str] = {"warp": "warp", "SimpleITK": "ct"}
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a public name on first access, then cache it in the module globals."""
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        missing = (getattr(exc, "name", "") or "").split(".")[0]
+        extra = _EXTRA_FOR_MISSING_MODULE.get(missing)
+        if extra is None:
+            raise
+        raise ImportError(
+            f"pyradmc.{name} needs the optional {extra!r} extra: pip install 'pyradmc[{extra}]'"
+        ) from exc
+    value = getattr(module, name)
+    globals()[name] = value  # later lookups find it directly and skip __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    """List the public API, so tab-completion sees names not yet imported."""
+    return sorted(__all__)
+
+
+__all__ = [
+    "ADIPOSE",
+    "AIR",
+    "ALI_ROGERS_BEAMS",
+    "CORTICAL_BONE",
+    "DIJ_TRUNCATION_RELATIVE",
+    "ECUT_MEV",
+    "ELECTRON_MASS_MEV",
+    "GY_PER_MEV_PER_G",
+    "LUNG",
+    "MATERIALS",
+    "PCUT_MEV",
+    "PHOTON_ROULETTE_MEV",
+    "PHOTON_ROULETTE_SURVIVAL",
+    "PHOTON_ROULETTE_WEIGHT_CAP",
+    "PHOTON_SPLIT_N",
+    "RAYLEIGH_MOMENTUM_TRANSFER_PER_MEV",
+    "TUNGSTEN",
+    "WATER",
+    "AnalyticCrossSections",
+    "BeamletGridSource",
+    "BeamletSource",
+    "CompositeBeamletSource",
+    "CompositeSource",
+    "CrossSectionSource",
+    "CylindricalScoringGrid",
+    "DijResult",
+    "GaussianSpotBeamSource",
+    "GaussianSpotBeamletSource",
+    "HostRNG",
+    "InMemoryPhaseSpaceSource",
+    "MaterialData",
+    "ParallelBeamSource",
+    "PencilBeamSource",
+    "PhaseSpaceSource",
+    "PhotonProcess",
+    "Primary",
+    "PrimaryFluenceBeamSource",
+    "PrimaryFluenceBeamletSource",
+    "RadialFluence",
+    "ReferenceEngine",
+    "ScoringGrid",
+    "Source",
+    "SpectralBeamSource",
+    "SpectralBeamletSource",
+    "Spectrum",
+    "TabulatedCrossSections",
+    "TransportResult",
+    "VoxelGrid",
+    "WarpEngine",
+    "__version__",
+    "ali_rogers_mv",
+    "geometric_edges",
+    "graded_edges",
+    "uniform_edges",
+]

pyradmc/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Optional adapters that bridge external inputs to the engine's core types.
+
+Adapters live outside the core (AGENTS.md 6): each may carry its own optional
+dependency, declared as an extra in ``pyproject.toml``, and the core never imports one.
+The CT adapter (:mod:`pyradmc.adapters.ct`) turns a patient CT into a
+:class:`~pyradmc.geometry.grid.VoxelGrid`; the pyRadPlan adapter is planned to follow.
+"""
+
+from __future__ import annotations

pyradmc/adapters/ct.py

@@ -0,0 +1,244 @@
+"""CT image -> :class:`~pyradmc.geometry.grid.VoxelGrid` adapter.
+
+Turns a patient CT into the engine's geometry: a Hounsfield-unit calibration maps each
+voxel's CT number to a mass density (a piecewise-linear ramp) and to a registry
+material index (HU threshold bins into the ICRP media the materials task added), and
+:func:`grid_from_hu` assembles the grid. :func:`read_ct` reads an image file through
+SimpleITK; everything above it is pure NumPy and needs no optional dependency, so the
+calibration is testable and reusable on its own.
+
+Segmentation and density are deliberately independent, which is the whole point of the
+multi-material design: the material index selects the elemental composition (the
+compiled cross-section row) and the per-voxel density scales it. A voxel at -500 HU is
+*lung tissue* (composition) at ~0.5 g/cm^3 (density), not a fixed reference-density
+material.
+
+The default calibration is illustrative, in Schneider's spirit (Schneider, Bortfeld &
+Schlegel, Phys. Med. Biol. 45, 459 (2000), doi:10.1088/0031-9155/45/2/314; bilinear
+density ramp after Schneider, Pedroni & Lomax, Phys. Med. Biol. 41, 111 (1996),
+doi:10.1088/0031-9155/41/1/009). CT calibration is scanner-specific: a real plan passes
+its own :class:`HounsfieldCalibration`, and these defaults are a runnable starting
+point, not a clinical curve.
+
+This adapter is out of the core (AGENTS.md 6); ``read_ct`` needs the optional
+``pyradmc[ct]`` extra (SimpleITK, Apache-2.0).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+from pyradmc.data.materials import ADIPOSE, AIR, CORTICAL_BONE, LUNG, MATERIALS, WATER
+from pyradmc.geometry.grid import VoxelGrid
+
+if TYPE_CHECKING:
+    import SimpleITK as sitk
+
+__all__ = [
+    "DEFAULT_CALIBRATION",
+    "HounsfieldCalibration",
+    "grid_from_hu",
+    "grid_from_image",
+    "read_ct",
+]
+
+_MM_PER_CM = 10.0
+
+
+# Default HU -> mass density ramp (g/cm^3), linearly interpolated and clamped at the
+# ends. Air and water are the fixed physical anchors; the bone segment reaches liquid
+# water's cortical-bone reference density (~1.85 g/cm^3) near 1400 HU and continues to
+# dense mineral above. Nodes ascending in HU.
+_DEFAULT_DENSITY_HU: tuple[float, ...] = (-1000.0, 0.0, 1000.0, 3000.0)
+_DEFAULT_DENSITY_VALUES: tuple[float, ...] = (0.00121, 1.000, 1.600, 2.800)
+
+# Default HU -> material bins. n thresholds cut the HU axis into n+1 bins; bin i (HU in
+# [thresholds[i-1], thresholds[i])) takes material_indices[i]. Illustrative Schneider-
+# style cut points into the ICRP registry media.
+_DEFAULT_MATERIAL_THRESHOLDS: tuple[float, ...] = (-950.0, -120.0, -20.0, 125.0)
+_DEFAULT_MATERIAL_INDICES: tuple[int, ...] = (AIR, LUNG, ADIPOSE, WATER, CORTICAL_BONE)
+
+
+@dataclass(frozen=True)
+class HounsfieldCalibration:
+    """A CT-number calibration: HU -> mass density and HU -> registry material.
+
+    Attributes
+    ----------
+    density_hu, density_values
+        The density ramp: HU control points (strictly ascending) and the mass density
+        in g/cm^3 at each. Interpolated linearly, clamped flat beyond the ends. All
+        densities must be positive — the grid rejects non-positive density.
+    material_thresholds
+        Ascending HU cut points. ``n`` thresholds define ``n + 1`` bins.
+    material_indices
+        The registry material index for each bin, low-HU to high-HU; length must be
+        ``len(material_thresholds) + 1``. Each must be a valid index into
+        :data:`pyradmc.data.materials.MATERIALS`.
+    """
+
+    density_hu: tuple[float, ...]
+    density_values: tuple[float, ...]
+    material_thresholds: tuple[float, ...]
+    material_indices: tuple[int, ...]
+    _density_hu_arr: npt.NDArray[np.float64] = field(init=False, repr=False, compare=False)
+    _density_val_arr: npt.NDArray[np.float64] = field(init=False, repr=False, compare=False)
+    _threshold_arr: npt.NDArray[np.float64] = field(init=False, repr=False, compare=False)
+    _index_arr: npt.NDArray[np.int32] = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validate the ramp and the bins, then cache their array forms."""
+        hu = np.asarray(self.density_hu, dtype=np.float64)
+        values = np.asarray(self.density_values, dtype=np.float64)
+        if hu.shape != values.shape or hu.size < 2:
+            raise ValueError("density_hu and density_values must be equal-length (>=2)")
+        if not np.all(np.diff(hu) > 0.0):
+            raise ValueError("density_hu must be strictly ascending")
+        if not np.all(values > 0.0):
+            raise ValueError("density_values must all be positive (g/cm^3)")
+
+        thresholds = np.asarray(self.material_thresholds, dtype=np.float64)
+        indices = np.asarray(self.material_indices, dtype=np.int32)
+        if thresholds.size and not np.all(np.diff(thresholds) > 0.0):
+            raise ValueError("material_thresholds must be strictly ascending")
+        if indices.size != thresholds.size + 1:
+            raise ValueError(
+                f"{thresholds.size} thresholds define {thresholds.size + 1} bins, "
+                f"but got {indices.size} material_indices"
+            )
+        if np.any((indices < 0) | (indices >= len(MATERIALS))):
+            raise ValueError("material_indices must all be valid registry indices")
+
+        object.__setattr__(self, "_density_hu_arr", hu)
+        object.__setattr__(self, "_density_val_arr", values)
+        object.__setattr__(self, "_threshold_arr", thresholds)
+        object.__setattr__(self, "_index_arr", indices)
+
+    def density(self, hu: npt.ArrayLike) -> npt.NDArray[np.float64]:
+        """Mass density in g/cm^3 for the given HU (scalar or array), clamped at the ends."""
+        return np.interp(
+            np.asarray(hu, dtype=np.float64), self._density_hu_arr, self._density_val_arr
+        )
+
+    def material(self, hu: npt.ArrayLike) -> npt.NDArray[np.int32]:
+        """Registry material index for the given HU (scalar or array).
+
+        ``np.digitize`` places each HU in its bin (left-closed, ``x < threshold``);
+        the bin index gathers the material index.
+        """
+        bins = np.digitize(np.asarray(hu, dtype=np.float64), self._threshold_arr)
+        return self._index_arr[bins]
+
+
+DEFAULT_CALIBRATION = HounsfieldCalibration(
+    density_hu=_DEFAULT_DENSITY_HU,
+    density_values=_DEFAULT_DENSITY_VALUES,
+    material_thresholds=_DEFAULT_MATERIAL_THRESHOLDS,
+    material_indices=_DEFAULT_MATERIAL_INDICES,
+)
+"""A runnable, scanner-independent default calibration; see the module docstring."""
+
+
+def grid_from_hu(
+    hu: npt.NDArray[np.float64],
+    spacing: tuple[float, float, float],
+    *,
+    calibration: HounsfieldCalibration = DEFAULT_CALIBRATION,
+    origin: tuple[float, float, float] = (0.0, 0.0, 0.0),
+) -> VoxelGrid:
+    """Assemble a :class:`VoxelGrid` from a HU volume and a voxel ``spacing`` (cm).
+
+    Pure NumPy: ``hu`` is a ``(nx, ny, nz)`` array of CT numbers already in the engine's
+    axis order. The calibration maps it to per-voxel density and material; the grid
+    validates the result (positive density, in-registry material).
+    """
+    hu = np.asarray(hu, dtype=np.float64)
+    nx, ny, nz = hu.shape
+    return VoxelGrid(
+        shape=(nx, ny, nz),
+        spacing=spacing,
+        origin=origin,
+        density=calibration.density(hu),
+        material=calibration.material(hu).astype(np.int32),
+    )
+
+
+def grid_from_image(
+    image: sitk.Image,
+    *,
+    calibration: HounsfieldCalibration = DEFAULT_CALIBRATION,
+) -> VoxelGrid:
+    """Convert a 3D SimpleITK CT image into a :class:`VoxelGrid`.
+
+    Handles the frame mismatch between ITK and the engine: SimpleITK indexes ``(z, y, x)``
+    and works in mm with the physical origin at voxel (0,0,0)'s *centre*, while the grid
+    is ``(x, y, z)`` in cm with the origin at that voxel's lower *corner*. The image's
+    intensities are taken to be Hounsfield units already (true for NIfTI/NRRD and for a
+    rescale-applied DICOM series).
+
+    Only axis-aligned CTs are supported: the direction cosine matrix must be diagonal.
+    A negative diagonal entry (an LPS/RAS sign flip, common clinically) means that axis's
+    physical coordinate decreases with index; the array is flipped and the origin
+    recomputed so the grid is stored in increasing-coordinate order. An oblique
+    (off-diagonal) orientation raises — resample to an axis-aligned grid first.
+    """
+    import SimpleITK as sitk
+
+    if image.GetDimension() != 3:
+        raise ValueError(f"expected a 3D CT image, got {image.GetDimension()}D")
+
+    direction = np.asarray(image.GetDirection(), dtype=np.float64).reshape(3, 3)
+    if not np.allclose(direction - np.diag(np.diagonal(direction)), 0.0, atol=1.0e-6):
+        raise ValueError(
+            "oblique CT orientation is not supported; resample to an axis-aligned grid first"
+        )
+
+    # SimpleITK array is (z, y, x); transpose to the engine's (x, y, z). Spacing, origin
+    # and the direction diagonal are all in image (x, y, z) order, so they line up.
+    hu = np.transpose(sitk.GetArrayFromImage(image).astype(np.float64), (2, 1, 0))
+    spacing_mm = np.asarray(image.GetSpacing(), dtype=np.float64)
+    origin_mm = np.asarray(image.GetOrigin(), dtype=np.float64)
+    signs = np.sign(np.diagonal(direction))
+
+    first_center_mm = origin_mm.copy()
+    for axis in range(3):
+        if signs[axis] < 0.0:
+            hu = np.flip(hu, axis=axis)
+            # Physical coordinate fell with index, so the minimum-coordinate voxel was
+            # the last one; after the flip it is index 0.
+            first_center_mm[axis] = origin_mm[axis] - spacing_mm[axis] * (hu.shape[axis] - 1)
+
+    lower_corner_mm = first_center_mm - 0.5 * spacing_mm
+    ox, oy, oz = (lower_corner_mm / _MM_PER_CM).tolist()
+    sx, sy, sz = (spacing_mm / _MM_PER_CM).tolist()
+    return grid_from_hu(
+        np.ascontiguousarray(hu),
+        spacing=(sx, sy, sz),
+        calibration=calibration,
+        origin=(ox, oy, oz),
+    )
+
+
+def read_ct(
+    path: str,
+    *,
+    calibration: HounsfieldCalibration = DEFAULT_CALIBRATION,
+) -> VoxelGrid:
+    """Read a CT image file into a :class:`VoxelGrid` (needs the ``pyradmc[ct]`` extra).
+
+    Accepts anything SimpleITK reads as a single volume — NIfTI, NRRD, MetaImage, a
+    single multi-frame DICOM. For a DICOM *series* (a directory of slices), read it with
+    ``SimpleITK.ImageSeriesReader`` yourself and pass the image to :func:`grid_from_image`,
+    so slice ordering and the rescale slope/intercept are handled explicitly. See
+    :func:`grid_from_image` for the frame and orientation handling.
+    """
+    try:
+        import SimpleITK as sitk
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError("read_ct needs the optional CT extra: pip install 'pyradmc[ct]'") from exc
+
+    return grid_from_image(sitk.ReadImage(path), calibration=calibration)

pyradmc/backends/__init__.py

@@ -0,0 +1 @@
+"""Subpackage placeholder; see AGENTS.md before adding code."""

pyradmc/backends/ref/__init__.py

@@ -0,0 +1,5 @@
+"""The pure-NumPy reference backend: the oracle. Never optimized (AGENTS.md 2.2)."""
+
+from pyradmc.backends.ref.engine import ReferenceEngine, TransportResult
+
+__all__ = ["ReferenceEngine", "TransportResult"]