optixstuff 1.5.0__tar.gz → 2.0.0__tar.gz

{optixstuff-1.5.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.5.0 → optixstuff-2.0.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optixstuff
-Version: 1.5.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.5.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.5.0 → optixstuff-2.0.0}/src/optixstuff/__init__.py

@@ -20,6 +20,7 @@ from optixstuff.optical_elements import (
 )
 from optixstuff.optical_path import OpticalPath
 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",

{optixstuff-1.5.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.5.0'
-__version_tuple__ = version_tuple = (1, 5, 0)
+__version__ = version = '2.0.0'
+__version_tuple__ = version_tuple = (2, 0, 0)
 
 __commit_id__ = commit_id = None

{optixstuff-1.5.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.5.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-1.5.0 → optixstuff-2.0.0}/src/optixstuff/primary.py

@@ -100,6 +100,8 @@ class SegmentedPrimary(AbstractPrimary):
     _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)
@@ -112,11 +114,15 @@ class SegmentedPrimary(AbstractPrimary):
         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
@@ -133,21 +139,38 @@ class SegmentedPrimary(AbstractPrimary):
 
     @property
     def segment_flat_to_flat_m(self) -> float:
-        """Segment flat-to-flat size in metres for the circumscribing layout."""
+        """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)`` array of segment centre (x, y) positions in metres."""
+        """``(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)
-        spacing = self.segment_flat_to_flat_m + self.segment_gap_m
+        pitch = self.segment_pitch_m
         qs = jnp.array([q for q, _ in axial])
         rs = jnp.array([r for _, r in axial])
-        xs = spacing * (qs + rs / 2.0)
-        ys = spacing * (jnp.sqrt(3.0) / 2.0) * rs
+        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:

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:]))