optixstuff 1.4.0__tar.gz → 2.0.0__tar.gz

{optixstuff-1.4.0 → optixstuff-2.0.0}/.pre-commit-config.yaml

@@ -1,4 +1,12 @@
 repos:
+  - repo: local
+    hooks:
+      - id: no-internal-refs
+        name: no internal research references
+        entry: python3 tools/check_internal_refs.py
+        language: system
+        types: [text]
+        exclude: ^(CHANGELOG\.md|tools/check_internal_refs\.py)$
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: "v6.0.0"
     hooks:

{optixstuff-1.4.0 → optixstuff-2.0.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [2.0.0](https://github.com/CoreySpohn/optixstuff/compare/v1.5.0...v2.0.0) (2026-07-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* **disperser:** sky_pitch_arcsec replaces sky_pitch_lod -- the cube grid is fixed-angle, so the pitch is a plain angle
+
+### Features
+
+* **disperser:** sky_pitch_lod + psflet_pack_path descriptor fields ([d2ae639](https://github.com/CoreySpohn/optixstuff/commit/d2ae6392a5f24a2c3b43413149dd7e89b7125600))
+* **primary:** exact segment geometry -- optional segment_point_to_point_m and inscribed_diameter_m, segment_pitch_m, flat-top segment_centres_m matching the HWO EAC baseline pupils ([4c5b4b7](https://github.com/CoreySpohn/optixstuff/commit/4c5b4b71843450339c2a330d74833a5b53a5431d))
+* **speckle:** add AbstractSpeckleField interface and OpticalPath.speckle ([fb7b501](https://github.com/CoreySpohn/optixstuff/commit/fb7b501a2b105350786f757c7c5c761f8bfef2b0))
+
+
+### Code Refactoring
+
+* **disperser:** sky_pitch_arcsec replaces sky_pitch_lod -- the cube grid is fixed-angle, so the pitch is a plain angle ([31041e2](https://github.com/CoreySpohn/optixstuff/commit/31041e2b85402b083ce2e7913100cfc2919452f3))
+
+## [1.5.0](https://github.com/CoreySpohn/optixstuff/compare/v1.4.0...v1.5.0) (2026-06-27)
+
+
+### Features
+
+* **detector:** wavelength-dependent QE via optional qe_curve ([bf7bc6f](https://github.com/CoreySpohn/optixstuff/commit/bf7bc6f8272ff2d011551f3b1b78243c8ada5572))
+* **primary:** add SegmentedPrimary carrying hex segment geometry ([fe7cab9](https://github.com/CoreySpohn/optixstuff/commit/fe7cab9bb6153874b029ead7d2cc888ca9e8709b))
+
 ## [1.4.0](https://github.com/CoreySpohn/optixstuff/compare/v1.3.0...v1.4.0) (2026-06-23)
 
 

{optixstuff-1.4.0 → optixstuff-2.0.0}/CITATION.cff

@@ -10,4 +10,4 @@ authors:
     affiliation: "NASA Goddard Space Flight Center"
 repository-code: "https://github.com/CoreySpohn/optixstuff"
 license: MIT
-# doi: add the Zenodo concept ("all versions") DOI here after the first archived release
+doi: "10.5281/zenodo.20819379"

{optixstuff-1.4.0 → optixstuff-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optixstuff
-Version: 1.4.0
+Version: 2.0.0
 Summary: Hardware abstractions for the HWO direct imaging simulation suite
 Project-URL: Homepage, https://github.com/CoreySpohn/optixstuff
 Project-URL: Issues, https://github.com/CoreySpohn/optixstuff/issues
@@ -94,8 +94,10 @@ Built on [JAX](https://github.com/google/jax) and
 
 - **Abstract interfaces** — `AbstractPrimary`, `AbstractOpticalElement`,
   `AbstractCoronagraph`, `AbstractDetector`, `AbstractDisperser`
-- **Concrete implementations** — `SimplePrimary`, `ConstantThroughput`,
-  `IdealDetector`, `Detector`, `LensletDisperser`
+- **Concrete implementations** — `SimplePrimary`, `SegmentedPrimary` (carries
+  hex segment geometry for a diffraction backend), `ConstantThroughput`,
+  `IdealDetector`, `Detector` (with optional wavelength-dependent QE),
+  `LensletDisperser`
 - **Container** — `OpticalPath`, a composable hardware configuration passed to all
   simulators
 

{optixstuff-1.4.0 → optixstuff-2.0.0}/README.md

@@ -36,8 +36,10 @@ Built on [JAX](https://github.com/google/jax) and
 
 - **Abstract interfaces** — `AbstractPrimary`, `AbstractOpticalElement`,
   `AbstractCoronagraph`, `AbstractDetector`, `AbstractDisperser`
-- **Concrete implementations** — `SimplePrimary`, `ConstantThroughput`,
-  `IdealDetector`, `Detector`, `LensletDisperser`
+- **Concrete implementations** — `SimplePrimary`, `SegmentedPrimary` (carries
+  hex segment geometry for a diffraction backend), `ConstantThroughput`,
+  `IdealDetector`, `Detector` (with optional wavelength-dependent QE),
+  `LensletDisperser`
 - **Container** — `OpticalPath`, a composable hardware configuration passed to all
   simulators
 

{optixstuff-1.4.0 → optixstuff-2.0.0}/src/optixstuff/__init__.py

@@ -19,7 +19,8 @@ from optixstuff.optical_elements import (
     SpectralThroughput,
 )
 from optixstuff.optical_path import OpticalPath
-from optixstuff.primary import AbstractPrimary, SimplePrimary
+from optixstuff.primary import AbstractPrimary, SegmentedPrimary, SimplePrimary
+from optixstuff.speckle import AbstractSpeckleField
 from optixstuff.yippy_coronagraph import YippyCoronagraph
 
 __all__ = [
@@ -29,6 +30,7 @@ __all__ = [
     "AbstractOpticalElement",
     "AbstractPrimary",
     "AbstractScalarCoronagraph",
+    "AbstractSpeckleField",
     "AbstractUniformElement",
     "ConstantThroughput",
     "Detector",
@@ -36,6 +38,7 @@ __all__ = [
     "IdealDetector",
     "LensletDisperser",
     "OpticalPath",
+    "SegmentedPrimary",
     "SimplePrimary",
     "SpectralThroughput",
     "YippyCoronagraph",

{optixstuff-1.4.0 → optixstuff-2.0.0}/src/optixstuff/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.0'
-__version_tuple__ = version_tuple = (1, 4, 0)
+__version__ = version = '2.0.0'
+__version_tuple__ = version_tuple = (2, 0, 0)
 
 __commit_id__ = commit_id = None

{optixstuff-1.4.0 → optixstuff-2.0.0}/src/optixstuff/detector.py

@@ -4,6 +4,7 @@ import abc
 from typing import final
 
 import equinox as eqx
+import interpax
 import jax
 import jax.numpy as jnp
 from equinox import AbstractVar
@@ -392,6 +393,7 @@ class Detector(AbstractDetector):
     read_time_s: float
     dqe: float
     shape: tuple[int, int] = eqx.field(static=True)
+    _qe_interp: interpax.Interpolator1D | None
 
     def __init__(
         self,
@@ -404,8 +406,16 @@ class Detector(AbstractDetector):
         frame_time_s: float = 1.0,
         read_time_s: float = 0.05,
         dqe: float = 0.0,
+        qe_curve: tuple[ArrayLike, ArrayLike] | None = None,
     ) -> None:
-        """Create a full detector with all noise sources."""
+        """Create a full detector with all noise sources.
+
+        Supplying ``qe_curve`` as a ``(wavelengths_nm, qe)`` pair makes
+        :meth:`get_qe` interpolate it (linear, zero outside the measured range)
+        for wavelength-dependent throughput/ETC use; the scalar
+        ``quantum_efficiency`` remains the operating-point QE used by the
+        per-call (monochromatic) readout path.
+        """
         self.pixel_scale_arcsec = pixel_scale_arcsec
         self.shape = shape
         self.quantum_efficiency = quantum_efficiency
@@ -417,10 +427,26 @@ class Detector(AbstractDetector):
         self.frame_time_s = frame_time_s
         self.read_time_s = read_time_s
         self.dqe = dqe
+        if qe_curve is None:
+            self._qe_interp = None
+        else:
+            wavelengths_nm, qe = qe_curve
+            self._qe_interp = interpax.Interpolator1D(
+                jnp.asarray(wavelengths_nm),
+                jnp.asarray(qe),
+                method="linear",
+                extrap=jnp.array([0.0, 0.0]),
+            )
 
     def get_qe(self, wavelength_nm: ArrayLike) -> ArrayLike:
-        """Return constant QE, ignoring wavelength."""
-        return self.quantum_efficiency
+        """Quantum efficiency at a wavelength.
+
+        Interpolates the ``qe_curve`` if one was supplied (linear, zero outside
+        the measured range); otherwise returns the scalar ``quantum_efficiency``.
+        """
+        if self._qe_interp is None:
+            return self.quantum_efficiency
+        return self._qe_interp(wavelength_nm)
 
     def scalar_noise_rate(self, n_pix: ArrayLike, t_photon: ArrayLike) -> ArrayLike:
         """Combined dark + CIC noise variance rate."""
@@ -463,9 +489,14 @@ class Detector(AbstractDetector):
     def __repr__(self) -> str:
         """One-line summary of shape, plate scale, QE, and noise sources."""
         ny, nx = self.shape
+        qe_str = (
+            "spectral"
+            if self._qe_interp is not None
+            else f"{self.quantum_efficiency:.2f}"
+        )
         return (
             f"Detector({ny}x{nx} @ {self.pixel_scale_arcsec:.3g} arcsec/px, "
-            f"QE={self.quantum_efficiency:.2f}, "
+            f"QE={qe_str}, "
             f"dark={self.dark_current_rate_e_per_s:.2g} e-/s/px, "
             f"RN={self.read_noise_e:.2g} e-/read, "
             f"CIC={self.clock_induced_charge_rate_e_per_frame:.2g} e-/frame, "

{optixstuff-1.4.0 → optixstuff-2.0.0}/src/optixstuff/disperser.py

@@ -63,6 +63,18 @@ class LensletDisperser(AbstractDisperser):
     ``lambda f / D``, so at fixed pixel scale coronachrome scales the core width
     by ``lambda / psflet_ref_nm`` per wavelength (the shape parameters do not
     scale).
+
+    ``sky_pitch_arcsec`` is the lenslet pitch projected on sky, a plain angle
+    in arcseconds (the focal-plane cube a render layer consumes lives on a
+    fixed angular grid, so no reference wavelength is involved). It makes the
+    spatial sampling an instrument property: the render layer derives
+    focal-plane pixels per lenslet as the ratio of this pitch to the cube's
+    angular plate scale instead of taking a free knob. ``None`` means
+    unspecified.
+
+    ``psflet_pack_path`` is a reference to a frozen PSFlet template pack file
+    (used with ``psflet_kind="template"``), the way ``throughput_element``
+    carries the blaze curve: config only, the render layer loads it.
     """
 
     pitch_m: float
@@ -78,6 +90,8 @@ class LensletDisperser(AbstractDisperser):
     psflet_kind: str = eqx.field(static=True)
     detector_shape: tuple[int, int] = eqx.field(static=True)
     throughput_element: AbstractOpticalElement = ConstantThroughput(1.0)
+    sky_pitch_arcsec: float | None = None
+    psflet_pack_path: str | None = eqx.field(static=True, default=None)
 
     def _dispersion_px(self, wavelength_nm):
         """Spectral-axis detector offset [px] for the wavelength(s)."""

{optixstuff-1.4.0 → optixstuff-2.0.0}/src/optixstuff/optical_path.py

@@ -16,6 +16,7 @@ from optixstuff.optical_elements import (
     ConstantThroughput,
 )
 from optixstuff.primary import AbstractPrimary, SimplePrimary
+from optixstuff.speckle import AbstractSpeckleField
 
 
 class OpticalPath(eqx.Module):
@@ -38,6 +39,9 @@ class OpticalPath(eqx.Module):
             not a spectral channel count). Default 1.0.
         npix_multiplier: IFS signal-spread multiplier on detector pixel
             counts. Default 1.0.
+        speckle: Optional time-varying speckle field (the stochastic
+            wavefront-error residual on top of the deterministic
+            coronagraph leakage floor); None for a perfect-wavefront path.
     """
 
     primary: AbstractPrimary
@@ -47,6 +51,7 @@ class OpticalPath(eqx.Module):
     disperser: AbstractDisperser | None = None
     n_channels: float = 1.0
     npix_multiplier: float = 1.0
+    speckle: AbstractSpeckleField | None = None
 
     @classmethod
     def from_default_setup(
@@ -62,6 +67,7 @@ class OpticalPath(eqx.Module):
         dark_current_rate_e_per_s: float = 0.0,
         n_channels: float = 1.0,
         npix_multiplier: float = 1.0,
+        speckle: AbstractSpeckleField | None = None,
     ) -> OpticalPath:
         """Build an OpticalPath with reasonable HWO-like defaults.
 
@@ -92,6 +98,8 @@ class OpticalPath(eqx.Module):
                 callers add realistic noise when needed).
             n_channels: AYO parallel-path multiplier. Default ``1.0``.
             npix_multiplier: IFS signal-spread multiplier. Default ``1.0``.
+            speckle: Optional speckle field attached to the path. Default
+                ``None`` -- a perfect-wavefront path.
 
         Returns:
             A ready-to-use :class:`OpticalPath`.
@@ -124,6 +132,7 @@ class OpticalPath(eqx.Module):
             ),
             n_channels=n_channels,
             npix_multiplier=npix_multiplier,
+            speckle=speckle,
         )
 
     def system_throughput(self, wavelength_nm: float) -> float:
@@ -158,4 +167,6 @@ class OpticalPath(eqx.Module):
             lines.append("  attenuating_elements: ()")
         lines.append(indent("coronagraph: " + repr(self.coronagraph)))
         lines.append(indent("detector: " + repr(self.detector)))
+        if self.speckle is not None:
+            lines.append(indent("speckle: " + repr(self.speckle)))
         return "\n".join(lines)

optixstuff-2.0.0/src/optixstuff/primary.py

@@ -0,0 +1,183 @@
+"""Primary mirror abstractions."""
+
+import equinox as eqx
+import jax.numpy as jnp
+from equinox import AbstractVar
+
+
+class AbstractPrimary(eqx.Module):
+    """Abstract interface for a primary aperture.
+
+    Any concrete implementation must provide the diameter and collecting
+    area of the primary mirror as scalar values in SI units. These are
+    consumed by exposure time calculators and simulation tools alike.
+    """
+
+    diameter_m: AbstractVar[float]
+    """Primary mirror diameter in metres."""
+
+    area_m2: AbstractVar[float]
+    """Effective collecting area in square metres."""
+
+
+class SimplePrimary(AbstractPrimary):
+    """A simple circular primary mirror with a central obscuration.
+
+    Args:
+        diameter_m: Primary mirror diameter in metres.
+        obscuration: Linear obscuration fraction (0 = no obscuration).
+        shape_factor: Fraction of unobscured area that is collecting
+            (accounts for struts, segment gaps, etc.). Default 1.0.
+    """
+
+    _diameter_m: float
+    obscuration: float
+    shape_factor: float
+
+    def __init__(
+        self,
+        diameter_m: float,
+        obscuration: float = 0.0,
+        shape_factor: float = 1.0,
+    ) -> None:
+        """Create a simple circular primary mirror."""
+        self._diameter_m = diameter_m
+        self.obscuration = obscuration
+        self.shape_factor = shape_factor
+
+    @property
+    def diameter_m(self) -> float:
+        """Primary mirror diameter in metres."""
+        return self._diameter_m
+
+    @property
+    def area_m2(self) -> float:
+        """Effective collecting area in square metres."""
+        r = self._diameter_m / 2.0
+        gross_area = jnp.pi * r**2
+        return gross_area * (1.0 - self.obscuration**2) * self.shape_factor
+
+    def __repr__(self) -> str:
+        """One-line summary of diameter, obscuration, and effective area."""
+        return (
+            f"SimplePrimary(D={self._diameter_m:.3g} m, "
+            f"obs={self.obscuration:.3g}, "
+            f"shape_factor={self.shape_factor:.3g}, "
+            f"area={float(self.area_m2):.3g} m^2)"
+        )
+
+
+def _hex_axial_coords(n_rings: int) -> list[tuple[int, int]]:
+    """Axial (q, r) centres of a hex-packed n-ring layout.
+
+    Yields ``1 + 3 n (n + 1)`` coordinates, centre first.
+    """
+    coords = [(0, 0)]
+    for q in range(-n_rings, n_rings + 1):
+        for r in range(-n_rings, n_rings + 1):
+            if max(abs(q), abs(r), abs(q + r)) <= n_rings and not (q == 0 and r == 0):
+                coords.append((q, r))
+    return coords
+
+
+class SegmentedPrimary(AbstractPrimary):
+    """A segmented hex primary that carries pupil geometry, not just scalars.
+
+    Beyond the diameter and collecting area every primary provides, this
+    describes the segment layout -- ring count, segment count, gap, shape -- so a
+    diffraction backend (e.g. dLux) can build the pupil from it. optixstuff only
+    DESCRIBES the geometry; it does not propagate wavefronts.
+
+    Args:
+        diameter_m: Circumscribing diameter in metres.
+        area_m2: Effective collecting area in square metres (gap/fill corrected).
+        n_rings: Number of segment rings around the centre segment.
+        n_segments: Total segment count (``1 + 3 n (n + 1)`` for a full layout).
+        segment_gap_m: Inter-segment optical gap in metres.
+        segment_shape: Segment shape; only ``"hexagon"`` is supported today.
+    """
+
+    _diameter_m: float
+    _area_m2: float
+    segment_gap_m: float
+    segment_point_to_point_m: float | None
+    inscribed_diameter_m: float | None
+    n_rings: int = eqx.field(static=True)
+    n_segments: int = eqx.field(static=True)
+    segment_shape: str = eqx.field(static=True)
+
+    def __init__(
+        self,
+        diameter_m: float,
+        area_m2: float,
+        n_rings: int,
+        n_segments: int,
+        segment_gap_m: float,
+        segment_shape: str = "hexagon",
+        segment_point_to_point_m: float | None = None,
+        inscribed_diameter_m: float | None = None,
+    ) -> None:
+        """Create a segmented hex primary from its geometry."""
+        self._diameter_m = diameter_m
+        self._area_m2 = area_m2
+        self.segment_gap_m = segment_gap_m
+        self.segment_point_to_point_m = segment_point_to_point_m
+        self.inscribed_diameter_m = inscribed_diameter_m
+        self.n_rings = n_rings
+        self.n_segments = n_segments
+        self.segment_shape = segment_shape
+
+    @property
+    def diameter_m(self) -> float:
+        """Circumscribing diameter in metres."""
+        return self._diameter_m
+
+    @property
+    def area_m2(self) -> float:
+        """Effective collecting area in square metres."""
+        return self._area_m2
+
+    @property
+    def segment_flat_to_flat_m(self) -> float:
+        """Segment flat-to-flat size in metres.
+
+        Exact (``point_to_point * sqrt(3) / 2``) when the segment size is
+        given; otherwise the legacy circumscribing approximation
+        ``diameter / (2 n_rings + 1)``.
+        """
+        if self.segment_point_to_point_m is not None:
+            return self.segment_point_to_point_m * jnp.sqrt(3.0) / 2.0
+        return self._diameter_m / (2 * self.n_rings + 1)
+
+    @property
+    def segment_pitch_m(self) -> float:
+        """Centre-to-centre distance of adjacent segments (flat-to-flat + gap)."""
+        return self.segment_flat_to_flat_m + self.segment_gap_m
+
+    @property
+    def segment_centres_m(self):
+        """``(n_segments, 2)`` segment centre (x, y) positions in metres.
+
+        A flat-top hexagonal lattice (flats up, points along x), the
+        convention of the HWO EAC baseline pupils: the centre segment is
+        first, and adjacent centres are one ``segment_pitch_m`` apart.
+        """
+        if self.segment_shape != "hexagon":
+            msg = f"segment_centres_m undefined for shape {self.segment_shape!r}"
+            raise NotImplementedError(msg)
+        axial = _hex_axial_coords(self.n_rings)
+        pitch = self.segment_pitch_m
+        qs = jnp.array([q for q, _ in axial])
+        rs = jnp.array([r for _, r in axial])
+        xs = pitch * (jnp.sqrt(3.0) / 2.0) * (qs + rs)
+        ys = pitch * (rs - qs) / 2.0
+        return jnp.stack([xs, ys], axis=-1)
+
+    def __repr__(self) -> str:
+        """One-line summary of diameter, segment layout, and effective area."""
+        return (
+            f"SegmentedPrimary(D={self._diameter_m:.3g} m, "
+            f"{self.n_segments} {self.segment_shape} segs, "
+            f"{self.n_rings} rings, gap={self.segment_gap_m * 1e3:.3g} mm, "
+            f"area={float(self._area_m2):.3g} m^2)"
+        )

optixstuff-2.0.0/src/optixstuff/speckle.py

@@ -0,0 +1,85 @@
+"""Speckle field abstractions.
+
+A speckle field is the stochastic, time-varying residual-starlight pattern
+left by wavefront errors that wavefront control does not null. It sits *on
+top of* the deterministic coronagraphic leakage floor (the YIP
+``stellar_intens`` map already applied in ``coronagraphoto.star_rate``), so
+it is an instrument effect, not an astrophysical scene source -- it lives on
+:class:`optixstuff.OpticalPath`, next to the coronagraph, rather than in the
+skyscapes scene.
+
+The standard linear speckle model is ``I(t) = |E_nom + G eps(t)|^2``, where
+``E_nom`` is the static coherent residual field (``|E_nom|^2`` is the
+deterministic floor), ``G`` maps wavefront-error modes to the focal-plane
+field, and ``eps(t)`` are the drifting mode coefficients. Concrete fields
+differ only in how they source ``G`` and ``eps`` (analytic, replayed
+intensity cubes, fitted reduced-order, or learned); they share the
+:class:`AbstractSpeckleField` contract below.
+"""
+
+import abc
+
+import equinox as eqx
+from equinox import AbstractVar
+from jax.typing import ArrayLike
+from jaxtyping import Array
+
+
+class AbstractSpeckleField(eqx.Module):
+    """Abstract interface for time-varying speckle fields.
+
+    Implementations can be backed by an analytic generator (physicaloptix),
+    replayed designer/testbed intensity cubes, a fitted reduced-order model,
+    or a learned generator. All produce a coronagraph-plane contrast map
+    through :meth:`realize`.
+
+    All wavelength arguments are in nanometres; ``time_s`` is seconds since
+    mission start. The returned map is on the field's native coronagraph
+    plane at :attr:`pixel_scale_lod`; the caller resamples it to the
+    detector grid (as for the coronagraph ``stellar_intens`` map).
+    """
+
+    pixel_scale_lod: AbstractVar[float]
+    """Native pixel scale in lambda/D per pixel."""
+
+    epoch_jd: AbstractVar[float]
+    """Julian Date that maps to ``time_s = 0`` -- the realization's clock
+    origin. Consumers (e.g. ``coronagraphoto.speckle_rate``) convert an
+    observation's absolute JD to the elapsed seconds :meth:`realize` expects
+    via ``(start_time_jd - epoch_jd)``; anchoring the clock here keeps the
+    physical interface in elapsed seconds and avoids feeding large absolute
+    JDs into the temporal synthesis."""
+
+    @abc.abstractmethod
+    def realize(
+        self,
+        *,
+        wavelength_nm: ArrayLike,
+        time_s: ArrayLike = 0.0,
+    ) -> Array:
+        """Speckle contrast *delta* at a given time and wavelength.
+
+        Returns the wavefront-error-induced excess over the deterministic
+        coronagraphic floor -- i.e. ``I(t) - |E_nom|^2``, expanded as
+        ``2 Re(E_nom* . G eps(t)) + |G eps(t)|^2``, in contrast units
+        (fraction of the host-star flux per pixel). It must not include the
+        ``|E_nom|^2`` floor itself: ``star_rate`` already applies that via
+        the YIP ``stellar_intens`` map, so re-emitting it here would double
+        count. An incoherent-halo implementation returns only the strictly
+        positive ``|G eps(t)|^2`` term (no speckle pinning); a coherent
+        implementation adds the cross term, which carries the bright-tail
+        pinning and requires the complex ``E_nom``.
+
+        Evolution is driven by ``time_s``, not a per-call PRNG key: the
+        realization is fixed at construction so the map is deterministic and
+        differentiable, and temporal correlation survives across an exposure
+        / roll sequence.
+
+        Args:
+            wavelength_nm: Wavelength in nanometres.
+            time_s: Time since mission start in seconds.
+
+        Returns:
+            2D float contrast-delta array on the native coronagraph plane.
+        """
+        ...

optixstuff-2.0.0/tools/check_internal_refs.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Commit guard: block internal research references in library files.
+
+Library code is public and self-contained; pointers into the private research
+workspace (project brain documents, decision-history vocabulary, working-note
+paths) do not belong in it. This script scans the given files line by line
+against a small pattern list and exits nonzero on any hit, so it can run as a
+pre-commit hook (see .pre-commit-config.yaml) and as a pytest.
+
+A line that must legitimately contain such a string (e.g. a development-only
+data fallback path in test fixtures) can be waived by appending the comment
+``internal-ref-ok`` to that line.
+
+Usage: check_internal_refs.py FILE [FILE ...]
+"""
+
+import re
+import sys
+from pathlib import Path
+
+WAIVER = "internal-ref-ok"
+
+PATTERNS = [
+    # Research-workspace paths and project homes.
+    r"mission-control",
+    r"research-brain",
+    r"physicaloptix-setup",
+    r"\bbrain/",
+    r"deep-thoughts",
+    # Underscored ALL-CAPS markdown names are internal working documents.
+    r"\b[A-Z0-9]+(?:_[A-Z0-9]+)+\.md\b",
+    # Project spike/script homes and decision-history vocabulary.
+    r"eac1_dlux",
+    r"Tier-G",
+    r"(?i)\bgreenfield\b",
+]
+
+COMPILED = [(pattern, re.compile(pattern)) for pattern in PATTERNS]
+
+
+def scan_file(path):
+    """Return (lineno, pattern, line) hits for one file."""
+    hits = []
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError as err:
+        print(f"{path}: unreadable ({err})")
+        return [(0, "<unreadable>", "")]
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if WAIVER in line:
+            continue
+        for pattern, regex in COMPILED:
+            if regex.search(line):
+                hits.append((lineno, pattern, line.strip()))
+    return hits
+
+
+def main(argv):
+    """Scan every argument path; report hits; exit 1 on any."""
+    self_path = Path(__file__).resolve()
+    failed = False
+    for arg in argv:
+        path = Path(arg)
+        if path.resolve() == self_path:
+            continue
+        for lineno, pattern, line in scan_file(path):
+            failed = True
+            print(f"{path}:{lineno}: matches {pattern!r}: {line}")
+    if failed:
+        print(
+            "\nInternal research references do not belong in library code. "
+            f"Rephrase self-contained, or append '{WAIVER}' to a "
+            "deliberately functional line."
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

optixstuff-1.4.0/src/optixstuff/primary.py

@@ -1,67 +0,0 @@
-"""Primary mirror abstractions."""
-
-import equinox as eqx
-import jax.numpy as jnp
-from equinox import AbstractVar
-
-
-class AbstractPrimary(eqx.Module):
-    """Abstract interface for a primary aperture.
-
-    Any concrete implementation must provide the diameter and collecting
-    area of the primary mirror as scalar values in SI units. These are
-    consumed by exposure time calculators and simulation tools alike.
-    """
-
-    diameter_m: AbstractVar[float]
-    """Primary mirror diameter in metres."""
-
-    area_m2: AbstractVar[float]
-    """Effective collecting area in square metres."""
-
-
-class SimplePrimary(AbstractPrimary):
-    """A simple circular primary mirror with a central obscuration.
-
-    Args:
-        diameter_m: Primary mirror diameter in metres.
-        obscuration: Linear obscuration fraction (0 = no obscuration).
-        shape_factor: Fraction of unobscured area that is collecting
-            (accounts for struts, segment gaps, etc.). Default 1.0.
-    """
-
-    _diameter_m: float
-    obscuration: float
-    shape_factor: float
-
-    def __init__(
-        self,
-        diameter_m: float,
-        obscuration: float = 0.0,
-        shape_factor: float = 1.0,
-    ) -> None:
-        """Create a simple circular primary mirror."""
-        self._diameter_m = diameter_m
-        self.obscuration = obscuration
-        self.shape_factor = shape_factor
-
-    @property
-    def diameter_m(self) -> float:
-        """Primary mirror diameter in metres."""
-        return self._diameter_m
-
-    @property
-    def area_m2(self) -> float:
-        """Effective collecting area in square metres."""
-        r = self._diameter_m / 2.0
-        gross_area = jnp.pi * r**2
-        return gross_area * (1.0 - self.obscuration**2) * self.shape_factor
-
-    def __repr__(self) -> str:
-        """One-line summary of diameter, obscuration, and effective area."""
-        return (
-            f"SimplePrimary(D={self._diameter_m:.3g} m, "
-            f"obs={self.obscuration:.3g}, "
-            f"shape_factor={self.shape_factor:.3g}, "
-            f"area={float(self.area_m2):.3g} m^2)"
-        )