optixstuff 3.0.0__tar.gz → 4.0.1__tar.gz

optixstuff-4.0.1/.codespellrc

@@ -0,0 +1,4 @@
+[codespell]
+skip = .git,*.ipynb,uv.lock,*/_build,*.fits
+# add domain words only if codespell flags them (clean on the libraries sampled)
+# ignore-words-list =

optixstuff-4.0.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

optixstuff-4.0.1/.gitattributes

@@ -0,0 +1,10 @@
+* text=auto eol=lf
+*.ipynb  text eol=lf linguist-documentation
+docs/**  linguist-documentation
+*.fits   binary
+*.npy    binary
+*.npz    binary
+*.png    binary
+*.pdf    binary
+uv.lock  linguist-generated -diff
+CHANGELOG.md linguist-generated

{optixstuff-3.0.0 → optixstuff-4.0.1}/.gitignore

@@ -163,4 +163,9 @@ cython_debug/
 input/
 output/
 scripts/
+!.github/scripts/
 *.png
+
+.claude/
+.jax_cache/
+.ruff_cache/

{optixstuff-3.0.0 → optixstuff-4.0.1}/.pre-commit-config.yaml

@@ -15,13 +15,17 @@ repos:
         args: [--pytest-test-first]
       - id: end-of-file-fixer
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.2
+    rev: v0.17.3
     hooks:
       - id: ruff-check
         args: [--fix]
       - id: ruff-format
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.3
+    hooks:
+      - id: codespell
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]

{optixstuff-3.0.0 → optixstuff-4.0.1}/.zenodo.json

@@ -3,7 +3,7 @@
   "creators": [
     {
       "orcid": "0000-0002-3138-0240",
-      "affiliation": "NASA Goddard Space Flight Center, Greenbelt, MD",
+      "affiliation": "University of Maryland, Baltimore County; NASA Goddard Space Flight Center; CRESST II",
       "name": "Spohn, Corey"
     }
   ],

{optixstuff-3.0.0 → optixstuff-4.0.1}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [4.0.1](https://github.com/CoreySpohn/optixstuff/compare/v4.0.0...v4.0.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* route yippy stellar and sky products through their own frame ([b9a029b](https://github.com/CoreySpohn/optixstuff/commit/b9a029b2b03a96564b443ad14aacfe3fdbb9b62b))
+
+## [4.0.0](https://github.com/CoreySpohn/optixstuff/compare/v3.0.0...v4.0.0) (2026-11-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **coronagraph:** AbstractCoronagraph.core_mean_intensity implementations must accept the keyword-only stellar_diam_lod argument.
+* **coronagraph:** YippyCoronagraph.core_mean_intensity and noise_floor_ayo now return values per (lambda/D)^2, the AbstractCoronagraph contract, instead of yippy's per-pixel fraction of the star's light; both grow by 1/pixel_scale_lod**2 (16x at 0.25 lambda/D pixels). Multiply either by core_area for the fraction in the aperture, and stop dividing by pixel_scale_lod**2 downstream.
+* American spelling throughout, rename segment_centres_m to segment_centers_m
+
+### Features
+
+* **coronagraph:** add stellar_diam_lod to core_mean_intensity and noise floor ([8cd9749](https://github.com/CoreySpohn/optixstuff/commit/8cd97496c3434ea7bd4effaf2b6f2f1fb095a294))
+* **speckle:** exposure-averaged realization on the speckle-field contract ([d163bf6](https://github.com/CoreySpohn/optixstuff/commit/d163bf6a0a821b1d31bed46925ef63a4c19145de))
+
+
+### Bug Fixes
+
+* American spelling throughout, rename segment_centres_m to segment_centers_m ([ccf79e1](https://github.com/CoreySpohn/optixstuff/commit/ccf79e14d8aee487d1dcabd2cf08b4a3893b2a36))
+* **coronagraph:** report the yippy AYO noise floor per (lambda/D)^2 ([3add7c7](https://github.com/CoreySpohn/optixstuff/commit/3add7c7c79f8153cfafa0a7409b0ed497c001ee4))
+* **coronagraph:** report yippy core mean intensity per (lambda/D)^2 ([dc55aaa](https://github.com/CoreySpohn/optixstuff/commit/dc55aaaca375bb5e45b34d93df0ff9ad5c16fbd5))
+
 ## [3.0.0](https://github.com/CoreySpohn/optixstuff/compare/v2.0.0...v3.0.0) (2026-07-20)
 
 

{optixstuff-3.0.0 → optixstuff-4.0.1}/CITATION.cff

@@ -7,7 +7,7 @@ authors:
   - family-names: Spohn
     given-names: Corey
     orcid: "https://orcid.org/0000-0002-3138-0240"
-    affiliation: "NASA Goddard Space Flight Center"
+    affiliation: "University of Maryland, Baltimore County; NASA Goddard Space Flight Center; CRESST II"
 repository-code: "https://github.com/CoreySpohn/optixstuff"
 license: MIT
 doi: "10.5281/zenodo.20819379"

{optixstuff-3.0.0 → optixstuff-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: optixstuff
-Version: 3.0.0
+Version: 4.0.1
 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
@@ -32,33 +32,47 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Astronomy
-Requires-Python: >=3.11
-Requires-Dist: equinox>=0.12.0
-Requires-Dist: hwoutils
-Requires-Dist: interpax
-Requires-Dist: jax>=0.4.1
-Requires-Dist: jaxlib>=0.4.1
-Requires-Dist: yippy
+Requires-Python: >=3.12
+Requires-Dist: equinox>=0.13.2
+Requires-Dist: hwoutils>=1.10.0
+Requires-Dist: interpax>=0.3.12
+Requires-Dist: jax>=0.8.1
+Requires-Dist: jaxlib>=0.8.1
+Requires-Dist: jaxtyping>=0.3.3
+Requires-Dist: yippy>=2.10.6
 Provides-Extra: dev
-Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: ipython; extra == 'docs'
-Requires-Dist: matplotlib; extra == 'docs'
-Requires-Dist: myst-nb; extra == 'docs'
-Requires-Dist: sphinx; extra == 'docs'
-Requires-Dist: sphinx-autoapi; extra == 'docs'
-Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
-Requires-Dist: sphinx-book-theme; extra == 'docs'
-Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
+Requires-Dist: ipython>=8.18; extra == 'docs'
+Requires-Dist: matplotlib>=3.10.7; extra == 'docs'
+Requires-Dist: myst-nb>=1.0; extra == 'docs'
+Requires-Dist: sphinx-autoapi>=3.0; extra == 'docs'
+Requires-Dist: sphinx-book-theme>=1.1; extra == 'docs'
+Requires-Dist: sphinx>=7.2; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == 'docs'
 Provides-Extra: test
-Requires-Dist: hypothesis; extra == 'test'
-Requires-Dist: nox; extra == 'test'
-Requires-Dist: pytest; extra == 'test'
-Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: hypothesis>=6.79.1; extra == 'test'
+Requires-Dist: numpy>=2.0; extra == 'test'
+Requires-Dist: psutil>=5.9.4; extra == 'test'
+Requires-Dist: pytest-fail-slow>=0.1.0; extra == 'test'
+Requires-Dist: pytest-markdown-docs>=0.5.0; extra == 'test'
+Requires-Dist: pytest-testmon>=2.0.7; extra == 'test'
+Requires-Dist: pytest-timeout>=1.3.1; extra == 'test'
+Requires-Dist: pytest-xdist>=2.5; extra == 'test'
+Requires-Dist: pytest>=7.3.2; extra == 'test'
 Description-Content-Type: text/markdown
 
 # optixstuff
 
+<p align="center">
+  <a href="https://pypi.org/project/optixstuff/"><img src="https://img.shields.io/pypi/v/optixstuff.svg?style=flat-square&logo=pypi" alt="PyPI"/></a>
+  <a href="https://optixstuff.readthedocs.io"><img src="https://readthedocs.org/projects/optixstuff/badge/?version=latest&style=flat-square" alt="Documentation Status"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/optixstuff/ci.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square&logo=python" alt="Python 3.12+"/></a>
+  <a href="https://doi.org/10.5281/zenodo.20819379"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20819379-blue?style=flat-square" alt="DOI"/></a>
+</p>
+
 Shared hardware objects — with standard values — for the HWO direct-imaging
 simulation suite.
 

{optixstuff-3.0.0 → optixstuff-4.0.1}/README.md

@@ -1,5 +1,14 @@
 # optixstuff
 
+<p align="center">
+  <a href="https://pypi.org/project/optixstuff/"><img src="https://img.shields.io/pypi/v/optixstuff.svg?style=flat-square&logo=pypi" alt="PyPI"/></a>
+  <a href="https://optixstuff.readthedocs.io"><img src="https://readthedocs.org/projects/optixstuff/badge/?version=latest&style=flat-square" alt="Documentation Status"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/optixstuff/ci.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"/></a>
+  <a href="https://github.com/CoreySpohn/optixstuff/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square&logo=python" alt="Python 3.12+"/></a>
+  <a href="https://doi.org/10.5281/zenodo.20819379"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.20819379-blue?style=flat-square" alt="DOI"/></a>
+</p>
+
 Shared hardware objects — with standard values — for the HWO direct-imaging
 simulation suite.
 

optixstuff-4.0.1/SECURITY.md

@@ -0,0 +1,9 @@
+# Security policy
+
+This is research software maintained by one person. Please report a vulnerability, for
+example a leaked credential, a malicious dependency, or a workflow that could be abused, through
+GitHub private vulnerability reporting: use "Report a vulnerability" on the Security tab of this
+repository. If that is unavailable, email corey.a.spohn@nasa.gov with "SECURITY" in the subject.
+
+Expect an acknowledgement within a week. Only the latest release receives fixes. Incorrect
+numerical results are not security issues; please open an ordinary issue for those.

optixstuff-4.0.1/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ['hatchling>=1.26.3', "hatch-fancy-pypi-readme>=24.1.0", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "optixstuff"
+description = "Hardware abstractions for the HWO direct imaging simulation suite"
+authors = [{ name = "Corey Spohn", email = "corey.a.spohn@nasa.gov" }]
+dynamic = ['readme', 'version']
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+    "equinox>=0.13.2",
+    "hwoutils>=1.10.0",
+    "interpax>=0.3.12",
+    "jax>=0.8.1",
+    "jaxlib>=0.8.1",
+    "jaxtyping>=0.3.3",
+    "yippy>=2.10.6",
+]
+
+[project.optional-dependencies]
+dev = ["pre-commit>=3.5"]
+docs = [
+    "sphinx>=7.2",
+    "myst-nb>=1.0",
+    "sphinx-book-theme>=1.1",
+    "sphinx-autoapi>=3.0",
+    "sphinxcontrib-mermaid>=0.9",
+    "ipython>=8.18",
+    "matplotlib>=3.10.7",
+]
+test = [
+    "pytest>=7.3.2",
+    "hypothesis>=6.79.1",
+    "pytest-xdist>=2.5",
+    "pytest-testmon>=2.0.7",
+    "pytest-markdown-docs>=0.5.0",
+    "pytest-timeout>=1.3.1",
+    "pytest-fail-slow>=0.1.0",
+    # The optional hwoutils budget plugin uses psutil for portable RSS sampling.
+    "psutil>=5.9.4",
+    "numpy>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/CoreySpohn/optixstuff"
+Issues = "https://github.com/CoreySpohn/optixstuff/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/optixstuff/_version.py"
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[tool.ruff.lint]
+select = ["B", "D", "E", "F", "I", "UP", "RUF"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/optixstuff"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/scripts", "/docs", "/tests", "/.github"]
+
+[tool.pytest.ini_options]
+filterwarnings = ["error"]
+markers = [
+    "medium: tests with a 30-second default time budget",
+    "slow: tests with a 300-second default time budget, run nightly",
+]
+
+[tool.testbudget]
+library = "optixstuff"
+mode = "report"
+unit_s = 5
+medium_s = 30
+slow_s = 300
+
+[tool.deptry]
+known_first_party = ["optixstuff"]
+optional_dependencies_dev_groups = ["dev", "docs", "test"]
+
+[tool.deptry.per_rule_ignores]
+# JAX loads its compiled backend; keep the explicit minimum version constraint.
+DEP002 = ["jaxlib"]
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.src]
+include = ["src/optixstuff"]

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/_version.py

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

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/coronagraph.py

@@ -67,7 +67,7 @@ class AbstractCoronagraph(eqx.Module):
     which serves the image contract from native-grid tables), physical
     wavefront propagation, or analytical models.
 
-    All wavelength arguments are in nanometres throughout.
+    All wavelength arguments are in nanometers throughout.
     All separations and pixel scales are in lambda/D units -- the
     contract is dimensionless optics; angle conversions are the
     telescope primary's business.
@@ -98,7 +98,7 @@ class AbstractCoronagraph(eqx.Module):
 
         Args:
             separation_lod: Angular separation in lambda/D.
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             time_s: Time since mission start in seconds.
 
         Returns:
@@ -118,7 +118,7 @@ class AbstractCoronagraph(eqx.Module):
 
         Args:
             separation_lod: Angular separation in lambda/D.
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             time_s: Time since mission start in seconds.
 
         Returns:
@@ -133,13 +133,24 @@ class AbstractCoronagraph(eqx.Module):
         wavelength_nm: ArrayLike,
         *,
         time_s: ArrayLike = 0.0,
+        stellar_diam_lod: ArrayLike = 0.0,
     ) -> ArrayLike:
         """Mean stellar intensity within the photometric aperture.
 
+        The fraction of the star's incident light per unit solid angle, in
+        (lambda/D)^-2, averaged over the aperture (azimuthally, for a
+        tabulated curve). It does not depend on any pixel grid: multiplied by
+        :meth:`core_area` it is the fraction of the star's light that leaks
+        into the photometric aperture. A backend that tabulates the fraction
+        per pixel divides by the pixel's solid angle in (lambda/D)^2.
+
         Args:
             separation_lod: Angular separation in lambda/D.
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             time_s: Time since mission start in seconds.
+            stellar_diam_lod: Stellar angular diameter in lambda/D at the
+                queried wavelength; 0 means a point star. Implementations
+                without a diameter model accept and ignore it.
 
         Returns:
             Mean stellar leakage intensity in (lambda/D)^-2.
@@ -158,7 +169,7 @@ class AbstractCoronagraph(eqx.Module):
 
         Args:
             separation_lod: Angular separation in lambda/D.
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             time_s: Time since mission start in seconds.
 
         Returns:
@@ -189,7 +200,7 @@ class AbstractCoronagraph(eqx.Module):
         the diameter axis this signature lacks.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             pixel_scale_rad: Output pixel scale in radians/pixel.
             npixels: Output array side length in pixels. Must be a
                 Python int (not a JAX array) as it determines the
@@ -211,7 +222,7 @@ class AbstractCoronagraph(eqx.Module):
         """Off-axis PSF at a given angular separation.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             separation_lod: Source separation in lambda/D.
             pixel_scale_rad: Output pixel scale in radians/pixel.
             npixels: Output array side length in pixels. Must be a
@@ -242,7 +253,7 @@ class AbstractCoronagraph(eqx.Module):
         """On-axis stellar leakage map at the requested sampling.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             stellar_diam_lod: Stellar angular diameter in lambda/D.
             pixel_scale_lod: Target pixel scale in lambda/D per pixel.
             shape: Target array shape (ny, nx).
@@ -266,7 +277,7 @@ class AbstractCoronagraph(eqx.Module):
         """Off-axis point-source PSFs at the requested sampling.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             x_lod: Source x-coordinates in lambda/D, shape (K,).
             y_lod: Source y-coordinates in lambda/D, shape (K,).
             pixel_scale_lod: Target pixel scale in lambda/D per pixel.
@@ -289,7 +300,7 @@ class AbstractCoronagraph(eqx.Module):
         """Per-pixel transmission map for a spatially uniform background.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             pixel_scale_lod: Target pixel scale in lambda/D per pixel.
             shape: Target array shape (ny, nx).
 
@@ -317,7 +328,7 @@ class AbstractCoronagraph(eqx.Module):
                 output carries the same units per target pixel.
             map_pixel_scale_lod: Pixel scale of ``scene_map`` in
                 lambda/D per pixel.
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             pixel_scale_lod: Target pixel scale in lambda/D per pixel.
             shape: Target array shape (ny, nx).
             rotation_deg: CCW rotation applied when mapping the scene
@@ -338,7 +349,10 @@ class AbstractTableCoronagraph(AbstractCoronagraph):
     ``psf_datacube``) -- and serves the sampling-explicit image contract
     from it with flux-conserving resamples to the requested target grid.
     Scalar performance curves remain the subclass's business (a table
-    backend interpolates its own curve tables).
+    backend interpolates its own curve tables). Subclasses implementing
+    ``core_mean_intensity`` use ``stellar_diam_lod`` when their curve
+    tables provide a diameter axis; otherwise they accept and ignore it.
+    The image-map SPI does not prescribe a scalar curve table format.
 
     The tables are monochromatic by construction (a YIP is a per-band
     file), so the served maps ignore ``wavelength_nm`` beyond the
@@ -524,6 +538,9 @@ class AbstractScalarCoronagraph(AbstractCoronagraph):
     model that carries native-grid tables -- subclass
     :class:`AbstractTableCoronagraph` instead, or the image pipeline
     will silently render zeros.
+
+    Subclasses implementing ``core_mean_intensity`` accept and ignore
+    ``stellar_diam_lod`` unless they provide a stellar diameter model.
     """
 
     def on_axis_psf(
@@ -626,7 +643,7 @@ class MultiBandCoronagraph(AbstractCoronagraph):
         """Build a multi-band stack.
 
         Args:
-            band_centers_nm: Band center wavelengths in nanometres, one
+            band_centers_nm: Band center wavelengths in nanometers, one
                 per band.
             bands: The per-band ``AbstractCoronagraph`` models, aligned
                 with ``band_centers_nm``.
@@ -687,10 +704,15 @@ class MultiBandCoronagraph(AbstractCoronagraph):
             separation_lod, wavelength_nm, time_s=time_s
         )
 
-    def core_mean_intensity(self, separation_lod, wavelength_nm, *, time_s=0.0):
-        """Mean stellar leakage from the nearest band."""
+    def core_mean_intensity(
+        self, separation_lod, wavelength_nm, *, time_s=0.0, stellar_diam_lod=0.0
+    ):
+        """Mean stellar leakage from the nearest band at the given diameter."""
         return self.band(wavelength_nm).core_mean_intensity(
-            separation_lod, wavelength_nm, time_s=time_s
+            separation_lod,
+            wavelength_nm,
+            time_s=time_s,
+            stellar_diam_lod=stellar_diam_lod,
         )
 
     def occulter_transmission(self, separation_lod, wavelength_nm, *, time_s=0.0):

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/detector.py

@@ -52,7 +52,7 @@ class AbstractDetector(eqx.Module):
         """Quantum efficiency at a given wavelength.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
 
         Returns:
             QE as a fraction in [0, 1].
@@ -140,7 +140,7 @@ class AbstractDetector(eqx.Module):
 
         The marginal distribution of returned electrons is identical to
         :meth:`readout_source_electrons`. The two methods produce
-        different specific realisations even with the same key.
+        different specific realizations even with the same key.
 
         Args:
             image_rate: Incident photon rate array in ph/s/pixel.

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/optical_elements.py

@@ -1,6 +1,5 @@
 """Optical element abstractions (throughput, filters, field stops)."""
 
-
 import abc
 from typing import final
 
@@ -27,7 +26,7 @@ class AbstractOpticalElement(eqx.Module):
         """Fractional throughput at a given wavelength.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
 
         Returns:
             Scalar throughput in [0, 1].
@@ -40,7 +39,7 @@ class AbstractOpticalElement(eqx.Module):
 
         Args:
             arr: Input photon rate array [ph/s/pixel].
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
 
         Returns:
             Attenuated photon rate array, same shape as arr.
@@ -79,14 +78,13 @@ class ConstantThroughput(AbstractUniformElement):
     def __repr__(self) -> str:
         """One-line summary of throughput value."""
         return (
-            f"ConstantThroughput(name={self.name!r}, "
-            f"throughput={self.throughput:.3g})"
+            f"ConstantThroughput(name={self.name!r}, throughput={self.throughput:.3g})"
         )
 
 
 @final
 class SpectralThroughput(AbstractUniformElement):
-    """Wavelength-dependent throughput defined by sampled (wavelength, throughput) pairs.
+    """Wavelength-dependent throughput from sampled (wavelength, throughput) pairs.
 
     Linear interpolation between samples; throughput is zero outside
     the defined wavelength range.

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/optical_path.py

@@ -77,6 +77,7 @@ class OpticalPath(eqx.Module):
 
         Args:
             coronagraph: One of:
+
                 - an :class:`AbstractCoronagraph` instance (used as-is),
                 - a YIP path (str or :class:`pathlib.Path`, wrapped with
                   :class:`YippyCoronagraph`),
@@ -139,7 +140,7 @@ class OpticalPath(eqx.Module):
         """Total throughput of all attenuating elements.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
 
         Returns:
             Combined fractional throughput in [0, 1].

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/primary.py

@@ -14,17 +14,17 @@ class AbstractPrimary(eqx.Module):
     """
 
     diameter_m: AbstractVar[float]
-    """Primary mirror diameter in metres."""
+    """Primary mirror diameter in meters."""
 
     area_m2: AbstractVar[float]
-    """Effective collecting area in square metres."""
+    """Effective collecting area in square meters."""
 
 
 class SimplePrimary(AbstractPrimary):
     """A simple circular primary mirror with a central obscuration.
 
     Args:
-        diameter_m: Primary mirror diameter in metres.
+        diameter_m: Primary mirror diameter in meters.
         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.
@@ -47,12 +47,12 @@ class SimplePrimary(AbstractPrimary):
 
     @property
     def diameter_m(self) -> float:
-        """Primary mirror diameter in metres."""
+        """Primary mirror diameter in meters."""
         return self._diameter_m
 
     @property
     def area_m2(self) -> float:
-        """Effective collecting area in square metres."""
+        """Effective collecting area in square meters."""
         r = self._diameter_m / 2.0
         gross_area = jnp.pi * r**2
         return gross_area * (1.0 - self.obscuration**2) * self.shape_factor
@@ -68,9 +68,9 @@ class SimplePrimary(AbstractPrimary):
 
 
 def _hex_axial_coords(n_rings: int) -> list[tuple[int, int]]:
-    """Axial (q, r) centres of a hex-packed n-ring layout.
+    """Axial (q, r) centers of a hex-packed n-ring layout.
 
-    Yields ``1 + 3 n (n + 1)`` coordinates, centre first.
+    Yields ``1 + 3 n (n + 1)`` coordinates, center first.
     """
     coords = [(0, 0)]
     for q in range(-n_rings, n_rings + 1):
@@ -89,11 +89,11 @@ class SegmentedPrimary(AbstractPrimary):
     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.
+        diameter_m: Circumscribing diameter in meters.
+        area_m2: Effective collecting area in square meters (gap/fill corrected).
+        n_rings: Number of segment rings around the center 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_gap_m: Inter-segment optical gap in meters.
         segment_shape: Segment shape; only ``"hexagon"`` is supported today.
     """
 
@@ -129,17 +129,17 @@ class SegmentedPrimary(AbstractPrimary):
 
     @property
     def diameter_m(self) -> float:
-        """Circumscribing diameter in metres."""
+        """Circumscribing diameter in meters."""
         return self._diameter_m
 
     @property
     def area_m2(self) -> float:
-        """Effective collecting area in square metres."""
+        """Effective collecting area in square meters."""
         return self._area_m2
 
     @property
     def segment_flat_to_flat_m(self) -> float:
-        """Segment flat-to-flat size in metres.
+        """Segment flat-to-flat size in meters.
 
         Exact (``point_to_point * sqrt(3) / 2``) when the segment size is
         given; otherwise the legacy circumscribing approximation
@@ -151,19 +151,19 @@ class SegmentedPrimary(AbstractPrimary):
 
     @property
     def segment_pitch_m(self) -> float:
-        """Centre-to-centre distance of adjacent segments (flat-to-flat + gap)."""
+        """Center-to-center 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.
+    def segment_centers_m(self):
+        """``(n_segments, 2)`` segment center (x, y) positions in meters.
 
         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.
+        convention of the HWO EAC baseline pupils: the center segment is
+        first, and adjacent centers are one ``segment_pitch_m`` apart.
         """
         if self.segment_shape != "hexagon":
-            msg = f"segment_centres_m undefined for shape {self.segment_shape!r}"
+            msg = f"segment_centers_m undefined for shape {self.segment_shape!r}"
             raise NotImplementedError(msg)
         axial = _hex_axial_coords(self.n_rings)
         pitch = self.segment_pitch_m

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/speckle.py

@@ -20,6 +20,8 @@ intensity cubes, fitted reduced-order, or learned); they share the
 import abc
 
 import equinox as eqx
+import jax
+import jax.numpy as jnp
 from equinox import AbstractVar
 from jax.typing import ArrayLike
 from jaxtyping import Array
@@ -33,7 +35,7 @@ class AbstractSpeckleField(eqx.Module):
     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
+    All wavelength arguments are in nanometers; ``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).
@@ -57,12 +59,14 @@ class AbstractSpeckleField(eqx.Module):
         wavelength_nm: ArrayLike,
         time_s: ArrayLike = 0.0,
     ) -> Array:
-        """Speckle contrast *delta* at a given time and wavelength.
+        """Speckle flux-fraction *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
+        ``2 Re(E_nom* . G eps(t)) + |G eps(t)|^2``, as per-pixel flux
+        fractions (the fraction of pre-coronagraph host-star flux landing in
+        each pixel, the same units a YIP ``stellar_intens`` map carries --
+        NOT peak-referenced contrast). 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
@@ -76,10 +80,67 @@ class AbstractSpeckleField(eqx.Module):
         / roll sequence.
 
         Args:
-            wavelength_nm: Wavelength in nanometres.
+            wavelength_nm: Wavelength in nanometers.
             time_s: Time since mission start in seconds.
 
         Returns:
             2D float contrast-delta array on the native coronagraph plane.
         """
         ...
+
+    def realize_average(
+        self,
+        *,
+        wavelength_nm: ArrayLike,
+        exposure_s: ArrayLike,
+        start_time_s: ArrayLike = 0.0,
+        n_sub: int = 8,
+    ) -> Array:
+        """Speckle contrast delta averaged over an exposure.
+
+        :meth:`realize` is instantaneous, but a detector integrates. Averaging
+        matters because the map is QUADRATIC in the drifting coefficients:
+        the mean of the realized maps is not the map of the mean coefficients,
+        so an instantaneous sample is a biased stand-in for an exposure
+        whenever the field decorrelates on the exposure timescale. This
+        evaluates :meth:`realize` at ``n_sub`` sub-exposure midpoints and
+        averages, which is exact in the limit of many sub-steps and
+        second-order accurate at finite ``n_sub``.
+
+        How many sub-steps are enough, and how much the average suppresses
+        the speckle variance relative to a snapshot, are both set by how many
+        independent realizations the exposure spans. A generator that knows
+        its own temporal statistics can say so in closed form (see
+        ``physicaloptix.SpeckleProcess.exposure_neff``); when the exposure is
+        short against the decorrelation time, one sub-step is already right
+        and this reduces to :meth:`realize` at the exposure midpoint.
+
+        Args:
+            wavelength_nm: Wavelength in nanometers.
+            exposure_s: Exposure length in seconds.
+            start_time_s: Exposure start, in seconds since ``epoch_jd``.
+            n_sub: Number of sub-exposure samples. Must be at least 1.
+
+        Returns:
+            2D float contrast-delta array, averaged over the exposure.
+
+        Raises:
+            ValueError: If ``n_sub`` is not a positive integer.
+        """
+        if int(n_sub) < 1 or int(n_sub) != n_sub:
+            raise ValueError(f"n_sub must be a positive integer, got {n_sub}")
+        n_sub = int(n_sub)
+        start = jnp.asarray(start_time_s, dtype=float)
+        step = jnp.asarray(exposure_s, dtype=float) / n_sub
+
+        def sample(index):
+            return self.realize(
+                wavelength_nm=wavelength_nm, time_s=start + (index + 0.5) * step
+            )
+
+        # Accumulate rather than stacking: one map is held at a time, so a
+        # large native grid does not cost n_sub copies.
+        def accumulate(index, total):
+            return total + sample(index)
+
+        return jax.lax.fori_loop(1, n_sub, accumulate, sample(0)) / n_sub

{optixstuff-3.0.0 → optixstuff-4.0.1}/src/optixstuff/yippy_coronagraph.py

@@ -98,9 +98,31 @@ class YippyCoronagraph(AbstractTableCoronagraph):
         wavelength_nm: ArrayLike,
         *,
         time_s: ArrayLike = 0.0,
+        stellar_diam_lod: ArrayLike = 0.0,
     ) -> ArrayLike:
-        """Mean stellar leakage from the YIP interpolation table."""
-        return self._backend.core_mean_intensity(separation_lod)
+        """Mean stellar leakage per (lambda/D)^2 from the YIP interpolation table.
+
+        yippy tabulates the fraction of the star's light per pixel, so the
+        value is divided by the stellar pixel's solid angle,
+        to meet the contract of :meth:`AbstractCoronagraph.core_mean_intensity`.
+        The backend interpolates over the stellar diameter axis when present;
+        otherwise it accepts and ignores the diameter.
+
+        Args:
+            separation_lod: Angular separation in lambda/D.
+            wavelength_nm: Wavelength in nanometers (accepted and ignored).
+            time_s: Time since mission start in seconds (accepted and ignored).
+            stellar_diam_lod: Stellar angular diameter in lambda/D at the
+                queried wavelength; 0 means a point star.
+        """
+        per_pixel = self._backend.core_mean_intensity(separation_lod, stellar_diam_lod)
+        return (
+            per_pixel
+            / getattr(
+                self._backend, "stellar_pixel_scale_lod", self._backend.pixel_scale_lod
+            )
+            ** 2
+        )
 
     def occulter_transmission(
         self,
@@ -123,6 +145,68 @@ class YippyCoronagraph(AbstractTableCoronagraph):
         """Stellar leakage PSF from the YIP stellar intensity model."""
         return self._backend.stellar_intens(0.0)
 
+    def stellar_map(
+        self,
+        wavelength_nm: ArrayLike,
+        stellar_diam_lod: ArrayLike,
+        *,
+        pixel_scale_lod: ArrayLike,
+        shape: tuple[int, int],
+    ) -> Array:
+        """Resample stellar flux in the backend's stellar reference frame."""
+        method = getattr(self._backend, "stellar_map", None)
+        if method is None:
+            return super().stellar_map(
+                wavelength_nm,
+                stellar_diam_lod,
+                pixel_scale_lod=pixel_scale_lod,
+                shape=shape,
+            )
+        return method(
+            wavelength_nm,
+            stellar_diam_lod,
+            pixel_scale_lod=pixel_scale_lod,
+            shape=shape,
+        )
+
+    def source_psfs(
+        self,
+        wavelength_nm: ArrayLike,
+        x_lod: ArrayLike,
+        y_lod: ArrayLike,
+        *,
+        pixel_scale_lod: ArrayLike,
+        shape: tuple[int, int],
+    ) -> Array:
+        """Resample source flux in the backend's off-axis reference frame."""
+        method = getattr(self._backend, "source_psfs", None)
+        if method is None:
+            return super().source_psfs(
+                wavelength_nm,
+                x_lod,
+                y_lod,
+                pixel_scale_lod=pixel_scale_lod,
+                shape=shape,
+            )
+        return method(
+            wavelength_nm, x_lod, y_lod, pixel_scale_lod=pixel_scale_lod, shape=shape
+        )
+
+    def background_transmission(
+        self,
+        wavelength_nm: ArrayLike,
+        *,
+        pixel_scale_lod: ArrayLike,
+        shape: tuple[int, int],
+    ) -> Array:
+        """Resample sky values in the backend's sky reference frame."""
+        method = getattr(self._backend, "background_transmission", None)
+        if method is None:
+            return super().background_transmission(
+                wavelength_nm, pixel_scale_lod=pixel_scale_lod, shape=shape
+            )
+        return method(wavelength_nm, pixel_scale_lod=pixel_scale_lod, shape=shape)
+
     def off_axis_psf(
         self,
         wavelength_nm: ArrayLike,
@@ -142,14 +226,38 @@ class YippyCoronagraph(AbstractTableCoronagraph):
         self,
         separation_lod: ArrayLike,
         ppf: float = 30.0,
+        *,
+        stellar_diam_lod: ArrayLike = 0.0,
     ) -> ArrayLike:
-        """AYO noise floor: core_mean_intensity / ppf.
+        """AYO noise floor per (lambda/D)^2: ``core_mean_intensity / ppf``.
 
-        This is a convenience passthrough to the backend. Not part of the
+        Same units as :meth:`core_mean_intensity`, so multiplying by
+        :meth:`core_area` gives the floor as a fraction of the star's light.
+        yippy's own ``noise_floor_ayo`` is per pixel and is divided by the
+        stellar pixel's solid angle. Not part of the
         AbstractCoronagraph contract -- downstream ETCs should compute
         noise floors as pure functions.
+
+        Division by ``ppf`` precedes the pixel-area conversion to preserve
+        point-source rounding exactly.
+
+        Args:
+            separation_lod: Angular separation in lambda/D.
+            ppf: Post-processing noise suppression factor.
+            stellar_diam_lod: Stellar angular diameter in lambda/D at the
+                queried wavelength; 0 means a point star. Accepted and ignored
+                when the backend has no diameter model.
         """
-        return self._backend.noise_floor_ayo(separation_lod, ppf)
+        per_pixel = (
+            self._backend.core_mean_intensity(separation_lod, stellar_diam_lod) / ppf
+        )
+        return (
+            per_pixel
+            / getattr(
+                self._backend, "stellar_pixel_scale_lod", self._backend.pixel_scale_lod
+            )
+            ** 2
+        )
 
     def raw_contrast(self, separation_lod: ArrayLike) -> ArrayLike:
         """Raw contrast from the YIP interpolation table."""

optixstuff-3.0.0/pyproject.toml

@@ -1,64 +0,0 @@
-[build-system]
-requires = ['hatchling', "hatch-fancy-pypi-readme", "hatch-vcs"]
-build-backend = "hatchling.build"
-
-[project]
-name = "optixstuff"
-description = "Hardware abstractions for the HWO direct imaging simulation suite"
-authors = [{ name = "Corey Spohn", email = "corey.a.spohn@nasa.gov" }]
-dynamic = ['readme', 'version']
-requires-python = ">=3.11"
-license = { file = "LICENSE" }
-classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
-    "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Topic :: Scientific/Engineering :: Astronomy",
-]
-dependencies = ["equinox>=0.12.0", "hwoutils", "interpax", "jax>=0.4.1", "jaxlib>=0.4.1", "yippy"]
-
-[project.optional-dependencies]
-dev = ["pre-commit"]
-docs = [
-    "sphinx",
-    "myst-nb",
-    "sphinx-book-theme",
-    "sphinx-autoapi",
-    "sphinx_autodoc_typehints",
-    "sphinxcontrib-mermaid",
-    "ipython",
-    "matplotlib",
-]
-test = ["nox", "pytest", "hypothesis", "pytest-cov"]
-
-[project.urls]
-Homepage = "https://github.com/CoreySpohn/optixstuff"
-Issues = "https://github.com/CoreySpohn/optixstuff/issues"
-
-[tool.hatch.version]
-source = "vcs"
-
-[tool.hatch.build.hooks.vcs]
-version-file = "src/optixstuff/_version.py"
-
-[tool.hatch.metadata.hooks.fancy-pypi-readme]
-content-type = "text/markdown"
-
-[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
-path = "README.md"
-
-[tool.ruff.lint]
-select = ["B", "D", "E", "F", "I", "UP", "RUF"]
-
-[tool.ruff.lint.pydocstyle]
-convention = "google"
-
-[tool.ruff.lint.per-file-ignores]
-"tests/**" = ["D"]
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/optixstuff"]
-
-[tool.hatch.build.targets.sdist]
-exclude = ["/scripts", "/docs", "/tests", "/.github"]