optixstuff 0.2.0__tar.gz → 1.0.0__tar.gz

{optixstuff-0.2.0 → optixstuff-1.0.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.0.0](https://github.com/CoreySpohn/optixstuff/compare/v0.2.0...v1.0.0) (2026-05-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* Docs and refactor to standardize function calls
+* SimpleDetector -> IdealDetector (clarifies that the class ignores wavelength-dependent QE and noise contributions); ConstantThroughputElement -> ConstantThroughput and LinearThroughputElement -> LinearThroughput (the Element suffix was redundant with the inheritance from AbstractUniformElement); AbstractScalarOnlyCoronagraph -> AbstractScalarCoronagraph (the Only qualifier was redundant); Exposure -> ExposureConfig (settings-struct role explicit). README ecosystem diagram replaced with Mermaid and sphinxcontrib-mermaid added to the docs build.
+
+### Features
+
+* Docs and refactor to standardize function calls ([5e5ab2c](https://github.com/CoreySpohn/optixstuff/commit/5e5ab2c28ac3d4dc387ba7eee7407740f95648c3))
+* rename detector/throughput classes and Exposure for naming consistency ([10beac7](https://github.com/CoreySpohn/optixstuff/commit/10beac7755e38c1743aa91931739453c9a5f50ed))
+
 ## [0.2.0](https://github.com/CoreySpohn/optixstuff/compare/v0.1.0...v0.2.0) (2026-05-24)
 
 

{optixstuff-0.2.0 → optixstuff-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optixstuff
-Version: 0.2.0
+Version: 1.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
@@ -48,6 +48,7 @@ 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'
 Provides-Extra: test
 Requires-Dist: hypothesis; extra == 'test'
 Requires-Dist: nox; extra == 'test'
@@ -57,29 +58,32 @@ Description-Content-Type: text/markdown
 
 # optixstuff
 
-Flux-level optical system abstractions for the HWO direct imaging simulation suite.
+Shared hardware objects — with standard values — for the HWO direct-imaging
+simulation suite.
 
 ## What optixstuff is
 
-`optixstuff` is the **radiometric hardware layer** for HWO simulations. It operates on
-**flux** — photon rates, throughput fractions, and detector-level noise — providing the
-shared interfaces that simulation tools and exposure time calculators build on top of.
+`optixstuff` is a **thin shared dependency** that defines the observatory's
+hardware as composable JAX modules: primary aperture, throughput-affecting
+elements, coronagraph backend, detector. Its job is to be the single source of
+truth for the hardware configuration that downstream tools consume.
 
-The same `OpticalPath` object drives both scalar ETC calculations (`jaxEDITH`) and full
-2D image generation (`coronagraphoto`), ensuring that the hardware model is consistent
-across all downstream science products.
+Both [coronagraphoto](https://github.com/CoreySpohn/coronagraphoto)
+(2D image simulation) and [jaxEDITH](https://github.com/CoreySpohn/jaxedith)
+(exposure-time and yield calculations) import the same `OpticalPath` class and
+the same detector / throughput / primary types from optixstuff. Change a value
+here and both downstream tools pick it up on the next import.
 
 ## What optixstuff is *not*
 
-`optixstuff` does not model diffraction, wavefront propagation, or E-field interference.
-That level of physical optics belongs to tools like [dLux](https://github.com/LouisDesdoigts/dLux)
-and [HCIPy](https://github.com/ehpor/hcipy), which generate PSFs from first principles.
-
-`optixstuff` and these wavefront tools are **complementary**: dLux/HCIPy compute the PSFs,
-which are delivered as yield input packages (YIPs). `optixstuff` consumes those PSFs as
-flux patterns (via [yippy](https://github.com/CoreySpohn/yippy)) and composes them with
-the rest of the observatory — throughput chain, detector QE, noise — to produce
-science-level outputs.
+- **Not a wavefront tool.** Diffraction, E-field propagation, and PSFs-from-first-principles
+  belong to [dLux](https://github.com/LouisDesdoigts/dLux) and [HCIPy](https://github.com/ehpor/hcipy).
+- **Not a PSF interpolator.** That's [yippy](https://github.com/CoreySpohn/yippy)'s job;
+  optixstuff wraps a PSF backend via `YippyCoronagraph` but does not compute PSFs.
+- **Not a scene model.** Stars, planets, disks, and zodi live in
+  [skyscapes](https://github.com/CoreySpohn/skyscapes).
+- **Not a simulator.** Downstream tools (coronagraphoto, jaxEDITH) consume an
+  `OpticalPath` to produce images or count rates.
 
 ## Architecture
 
@@ -88,8 +92,8 @@ Built on [JAX](https://github.com/google/jax) and
 
 - **Abstract interfaces** — `AbstractPrimary`, `AbstractOpticalElement`,
   `AbstractCoronagraph`, `AbstractDetector`
-- **Concrete implementations** — `SimplePrimary`, `ConstantThroughputElement`,
-  `SimpleDetector`
+- **Concrete implementations** — `SimplePrimary`, `ConstantThroughput`,
+  `IdealDetector`
 - **Container** — `OpticalPath`, a composable hardware configuration passed to all
   simulators
 
@@ -100,29 +104,18 @@ time-dependent detector degradation) can use them without breaking the interface
 
 ### Ecosystem position
 
-```
-                          ┌───────────────────────────┐
-                          │  Physical optics           │
-                          │  (dLux, HCIPy, PROPER)     │
-                          │  E-fields → PSFs           │
-                          └──────────┬────────────────┘
-                                     │ YIP
-                          ┌──────────▼────────────────┐
-                          │  yippy                     │
-                          │  PSF interpolation         │
-                          └──────────┬────────────────┘
-                                     │ flux patterns
-              ┌──────────────────────▼────────────────────────┐
-              │                  optixstuff                    │
-              │  Telescope • Coronagraph • Detector • OpticalPath │
-              │  Throughput chains • QE • Noise rates          │
-              └────────┬──────────────────────┬───────────────┘
-                       │                      │
-            ┌──────────▼──────────┐ ┌────────▼───────────────┐
-            │  jaxEDITH           │ │  coronagraphoto         │
-            │  Scalar count rates │ │  2D image simulation    │
-            │  Exposure times     │ │  Multi-epoch scenes     │
-            └─────────────────────┘ └────────────────────────┘
+```mermaid
+flowchart TB
+    physopt["<b>Physical optics</b><br/>dLux · HCIPy · PROPER<br/>E-fields → PSFs"]
+    yippy["<b>yippy</b><br/>PSF interpolation"]
+    optix["<b>optixstuff</b><br/>Telescope · Coronagraph · Detector · OpticalPath<br/>Throughput chains · QE · Noise rates"]
+    jaxedith["<b>jaxEDITH</b><br/>Scalar count rates<br/>Exposure-time calculations"]
+    corono["<b>coronagraphoto</b><br/>2D image simulation<br/>Multi-epoch scenes"]
+
+    physopt -- YIP --> yippy
+    yippy -- flux patterns --> optix
+    optix --> jaxedith
+    optix --> corono
 ```
 
 ## Installation

optixstuff-1.0.0/README.md

@@ -0,0 +1,71 @@
+# optixstuff
+
+Shared hardware objects — with standard values — for the HWO direct-imaging
+simulation suite.
+
+## What optixstuff is
+
+`optixstuff` is a **thin shared dependency** that defines the observatory's
+hardware as composable JAX modules: primary aperture, throughput-affecting
+elements, coronagraph backend, detector. Its job is to be the single source of
+truth for the hardware configuration that downstream tools consume.
+
+Both [coronagraphoto](https://github.com/CoreySpohn/coronagraphoto)
+(2D image simulation) and [jaxEDITH](https://github.com/CoreySpohn/jaxedith)
+(exposure-time and yield calculations) import the same `OpticalPath` class and
+the same detector / throughput / primary types from optixstuff. Change a value
+here and both downstream tools pick it up on the next import.
+
+## What optixstuff is *not*
+
+- **Not a wavefront tool.** Diffraction, E-field propagation, and PSFs-from-first-principles
+  belong to [dLux](https://github.com/LouisDesdoigts/dLux) and [HCIPy](https://github.com/ehpor/hcipy).
+- **Not a PSF interpolator.** That's [yippy](https://github.com/CoreySpohn/yippy)'s job;
+  optixstuff wraps a PSF backend via `YippyCoronagraph` but does not compute PSFs.
+- **Not a scene model.** Stars, planets, disks, and zodi live in
+  [skyscapes](https://github.com/CoreySpohn/skyscapes).
+- **Not a simulator.** Downstream tools (coronagraphoto, jaxEDITH) consume an
+  `OpticalPath` to produce images or count rates.
+
+## Architecture
+
+Built on [JAX](https://github.com/google/jax) and
+[Equinox](https://github.com/patrick-kidger/equinox), `optixstuff` provides:
+
+- **Abstract interfaces** — `AbstractPrimary`, `AbstractOpticalElement`,
+  `AbstractCoronagraph`, `AbstractDetector`
+- **Concrete implementations** — `SimplePrimary`, `ConstantThroughput`,
+  `IdealDetector`
+- **Container** — `OpticalPath`, a composable hardware configuration passed to all
+  simulators
+
+Every abstract method accepts three fidelity axes — **wavelength**, **position**, and
+**time** — with defaults so that simple implementations can ignore unused axes while
+future high-fidelity models (wavelength-dependent coatings, position-dependent vignetting,
+time-dependent detector degradation) can use them without breaking the interface.
+
+### Ecosystem position
+
+```mermaid
+flowchart TB
+    physopt["<b>Physical optics</b><br/>dLux · HCIPy · PROPER<br/>E-fields → PSFs"]
+    yippy["<b>yippy</b><br/>PSF interpolation"]
+    optix["<b>optixstuff</b><br/>Telescope · Coronagraph · Detector · OpticalPath<br/>Throughput chains · QE · Noise rates"]
+    jaxedith["<b>jaxEDITH</b><br/>Scalar count rates<br/>Exposure-time calculations"]
+    corono["<b>coronagraphoto</b><br/>2D image simulation<br/>Multi-epoch scenes"]
+
+    physopt -- YIP --> yippy
+    yippy -- flux patterns --> optix
+    optix --> jaxedith
+    optix --> corono
+```
+
+## Installation
+
+```bash
+pip install optixstuff
+```
+
+## Status
+
+This package is in early development (pre-v0.1.0).

{optixstuff-0.2.0 → optixstuff-1.0.0}/pyproject.toml

@@ -26,6 +26,7 @@ docs = [
     "sphinx-book-theme",
     "sphinx-autoapi",
     "sphinx_autodoc_typehints",
+    "sphinxcontrib-mermaid",
     "ipython",
     "matplotlib",
 ]

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/__init__.py

@@ -1,22 +1,21 @@
 """optixstuff -- Hardware abstractions for the HWO simulation suite."""
 
 from optixstuff._version import __version__
-from optixstuff.coronagraph import AbstractCoronagraph, AbstractScalarOnlyCoronagraph
+from optixstuff.coronagraph import AbstractCoronagraph, AbstractScalarCoronagraph
 from optixstuff.detector import (
     AbstractDetector,
     Detector,
-    SimpleDetector,
-    simulate_cic,
-    simulate_dark_current,
-    simulate_read_noise,
+    IdealDetector,
+    clock_induced_charge,
+    dark_current,
+    read_noise,
 )
-from optixstuff.exposure import Exposure
+from optixstuff.exposure import ExposureConfig
 from optixstuff.optical_elements import (
     AbstractOpticalElement,
     AbstractUniformElement,
-    ConstantThroughputElement,
-    LinearThroughputElement,
-    OpticalFilter,
+    ConstantThroughput,
+    SpectralThroughput,
 )
 from optixstuff.optical_path import OpticalPath
 from optixstuff.primary import AbstractPrimary, SimplePrimary
@@ -27,19 +26,18 @@ __all__ = [
     "AbstractDetector",
     "AbstractOpticalElement",
     "AbstractPrimary",
-    "AbstractScalarOnlyCoronagraph",
+    "AbstractScalarCoronagraph",
     "AbstractUniformElement",
-    "ConstantThroughputElement",
+    "ConstantThroughput",
     "Detector",
-    "Exposure",
-    "LinearThroughputElement",
-    "OpticalFilter",
+    "ExposureConfig",
+    "IdealDetector",
     "OpticalPath",
-    "SimpleDetector",
     "SimplePrimary",
+    "SpectralThroughput",
     "YippyCoronagraph",
     "__version__",
-    "simulate_cic",
-    "simulate_dark_current",
-    "simulate_read_noise",
+    "clock_induced_charge",
+    "dark_current",
+    "read_noise",
 ]

{optixstuff-0.2.0 → optixstuff-1.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 = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
 
 __commit_id__ = commit_id = None

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/coronagraph.py

@@ -166,7 +166,7 @@ class AbstractCoronagraph(eqx.Module):
         ...
 
 
-class AbstractScalarOnlyCoronagraph(AbstractCoronagraph):
+class AbstractScalarCoronagraph(AbstractCoronagraph):
     """Base for ETC-only coronagraph models that lack 2D PSF generation.
 
     Stubs out the image interface with zero arrays so the class satisfies

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/detector.py

@@ -20,25 +20,25 @@ class AbstractDetector(eqx.Module):
     must define the hardware parameters listed as ``AbstractVar`` fields.
     """
 
-    pixel_scale: AbstractVar[float]
+    pixel_scale_arcsec: AbstractVar[float]
     """Detector plate scale in arcsec/pixel."""
 
     quantum_efficiency: AbstractVar[float]
     """Baseline quantum efficiency as a fraction in [0, 1]."""
 
-    dark_current_rate: AbstractVar[float]
+    dark_current_rate_e_per_s: AbstractVar[float]
     """Dark current rate in electrons/pixel/second."""
 
-    read_noise_electrons: AbstractVar[float]
+    read_noise_e: AbstractVar[float]
     """Read noise in electrons RMS per pixel per read."""
 
-    cic_rate: AbstractVar[float]
+    clock_induced_charge_rate_e_per_frame: AbstractVar[float]
     """Clock-induced charge in electrons/pixel/frame."""
 
-    frame_time: AbstractVar[float]
+    frame_time_s: AbstractVar[float]
     """Integration time per frame/read in seconds."""
 
-    read_time: AbstractVar[float]
+    read_time_s: AbstractVar[float]
     """Time per read cycle in seconds (for RN^2/t_read in ETC)."""
 
     dqe: AbstractVar[float]
@@ -79,7 +79,7 @@ class AbstractDetector(eqx.Module):
     def readout(
         self,
         image_rate: Array,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Apply stochastic noise realization to a photon rate image.
@@ -89,7 +89,7 @@ class AbstractDetector(eqx.Module):
 
         Args:
             image_rate: Incident photon rate array in ph/s/pixel.
-            exposure_time: Exposure time in seconds.
+            exposure_time_s: ExposureConfig time in seconds.
             prng_key: JAX PRNG key (required, no default).
 
         Returns:
@@ -100,7 +100,7 @@ class AbstractDetector(eqx.Module):
     def readout_source_electrons(
         self,
         image_rate: Array,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Poisson-sample incident photons and convert to electrons via QE.
@@ -113,20 +113,20 @@ class AbstractDetector(eqx.Module):
 
         Args:
             image_rate: Incident photon rate array in ph/s/pixel.
-            exposure_time: Exposure time in seconds.
+            exposure_time_s: ExposureConfig time in seconds.
             prng_key: JAX PRNG key.
 
         Returns:
             Photo-electron counts, same shape as image_rate.
         """
         key_phot, key_qe = jax.random.split(prng_key, 2)
-        inc_photons = jax.random.poisson(key_phot, image_rate * exposure_time)
+        inc_photons = jax.random.poisson(key_phot, image_rate * exposure_time_s)
         return jax.random.binomial(key_qe, inc_photons, self.quantum_efficiency)
 
     def readout_source_electrons_thinned(
         self,
         image_rate: Array,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Fast equivalent of :meth:`readout_source_electrons` via Poisson thinning.
@@ -144,20 +144,20 @@ class AbstractDetector(eqx.Module):
 
         Args:
             image_rate: Incident photon rate array in ph/s/pixel.
-            exposure_time: Exposure time in seconds.
+            exposure_time_s: ExposureConfig time in seconds.
             prng_key: JAX PRNG key.
 
         Returns:
             Photo-electron counts, same shape as image_rate.
         """
         return jax.random.poisson(
-            prng_key, image_rate * exposure_time * self.quantum_efficiency
+            prng_key, image_rate * exposure_time_s * self.quantum_efficiency
         )
 
     @abc.abstractmethod
     def readout_noise_electrons(
         self,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Source-independent detector noise (dark + CIC + read).
@@ -167,7 +167,7 @@ class AbstractDetector(eqx.Module):
         how many sources were co-added via :meth:`readout_source_electrons`.
 
         Args:
-            exposure_time: Exposure time in seconds.
+            exposure_time_s: ExposureConfig time in seconds.
             prng_key: JAX PRNG key.
 
         Returns:
@@ -179,28 +179,28 @@ class AbstractDetector(eqx.Module):
 # -- Pure noise simulation functions -----------------------------------------
 
 
-def simulate_dark_current(
-    dark_current_rate: float,
-    exposure_time: ArrayLike,
+def dark_current(
+    dark_current_rate_e_per_s: float,
+    exposure_time_s: ArrayLike,
     shape: tuple[int, int],
     prng_key: Array,
 ) -> Array:
     """Draw dark current electrons from a Poisson distribution.
 
     Args:
-        dark_current_rate: Dark current rate in electrons/s/pixel.
-        exposure_time: Exposure time in seconds.
+        dark_current_rate_e_per_s: Dark current rate in electrons/s/pixel.
+        exposure_time_s: ExposureConfig time in seconds.
         shape: Detector shape (ny, nx).
         prng_key: PRNG key.
 
     Returns:
         Dark current electrons, shape (ny, nx).
     """
-    return jax.random.poisson(prng_key, dark_current_rate * exposure_time, shape=shape)
+    return jax.random.poisson(prng_key, dark_current_rate_e_per_s * exposure_time_s, shape=shape)
 
 
-def simulate_cic(
-    cic_rate: float,
+def clock_induced_charge(
+    clock_induced_charge_rate_e_per_frame: float,
     num_frames: ArrayLike,
     shape: tuple[int, int],
     prng_key: Array,
@@ -208,7 +208,7 @@ def simulate_cic(
     """Draw clock-induced charge electrons from a Poisson distribution.
 
     Args:
-        cic_rate: CIC rate in electrons/pixel/frame.
+        clock_induced_charge_rate_e_per_frame: CIC rate in electrons/pixel/frame.
         num_frames: Number of frames (kept as float for JIT safety).
         shape: Detector shape (ny, nx).
         prng_key: PRNG key.
@@ -216,11 +216,11 @@ def simulate_cic(
     Returns:
         CIC electrons, shape (ny, nx).
     """
-    return jax.random.poisson(prng_key, cic_rate * num_frames, shape=shape)
+    return jax.random.poisson(prng_key, clock_induced_charge_rate_e_per_frame * num_frames, shape=shape)
 
 
-def simulate_read_noise(
-    read_noise: float,
+def read_noise(
+    read_noise_e: float,
     num_frames: ArrayLike,
     shape: tuple[int, int],
     prng_key: Array,
@@ -230,7 +230,7 @@ def simulate_read_noise(
     Total read noise sigma = sqrt(num_frames) * read_noise_per_read.
 
     Args:
-        read_noise: Read noise in electrons/pixel/read.
+        read_noise_e: Read noise in electrons/pixel/read.
         num_frames: Number of frames.
         shape: Detector shape (ny, nx).
         prng_key: PRNG key.
@@ -238,7 +238,7 @@ def simulate_read_noise(
     Returns:
         Read noise electrons, shape (ny, nx).
     """
-    sigma = read_noise * jnp.sqrt(num_frames)
+    sigma = read_noise_e * jnp.sqrt(num_frames)
     return sigma * jax.random.normal(prng_key, shape=shape)
 
 
@@ -246,44 +246,44 @@ def simulate_read_noise(
 
 
 @final
-class SimpleDetector(AbstractDetector):
+class IdealDetector(AbstractDetector):
     """Detector with constant QE and minimal noise sources.
 
     Suitable for broadband imager studies where wavelength-dependent
     QE variation is not important and CIC/read noise are negligible.
     """
 
-    pixel_scale: float
+    pixel_scale_arcsec: float
     quantum_efficiency: float
-    dark_current_rate: float
-    read_noise_electrons: float
-    cic_rate: float
-    frame_time: float
-    read_time: float
+    dark_current_rate_e_per_s: float
+    read_noise_e: float
+    clock_induced_charge_rate_e_per_frame: float
+    frame_time_s: float
+    read_time_s: float
     dqe: float
     shape: tuple[int, int] = eqx.field(static=True)
 
     def __init__(
         self,
-        pixel_scale: float,
+        pixel_scale_arcsec: float,
         shape: tuple[int, int],
         quantum_efficiency: float = 1.0,
-        dark_current_rate: float = 0.0,
-        read_noise_electrons: float = 0.0,
-        cic_rate: float = 0.0,
-        frame_time: float = 1.0,
-        read_time: float = 0.05,
+        dark_current_rate_e_per_s: float = 0.0,
+        read_noise_e: float = 0.0,
+        clock_induced_charge_rate_e_per_frame: float = 0.0,
+        frame_time_s: float = 1.0,
+        read_time_s: float = 0.05,
         dqe: float = 0.0,
     ) -> None:
         """Create a simple constant-QE detector."""
-        self.pixel_scale = pixel_scale
+        self.pixel_scale_arcsec = pixel_scale_arcsec
         self.shape = shape
         self.quantum_efficiency = quantum_efficiency
-        self.dark_current_rate = dark_current_rate
-        self.read_noise_electrons = read_noise_electrons
-        self.cic_rate = cic_rate
-        self.frame_time = frame_time
-        self.read_time = read_time
+        self.dark_current_rate_e_per_s = dark_current_rate_e_per_s
+        self.read_noise_e = read_noise_e
+        self.clock_induced_charge_rate_e_per_frame = clock_induced_charge_rate_e_per_frame
+        self.frame_time_s = frame_time_s
+        self.read_time_s = read_time_s
         self.dqe = dqe
 
     def get_qe(self, wavelength_nm: ArrayLike) -> ArrayLike:
@@ -294,41 +294,41 @@ class SimpleDetector(AbstractDetector):
         """Combined dark + CIC noise variance rate.
 
         Read noise is not included here as it scales per-read, not per-second.
-        Callers add (read_noise^2 * n_reads) / t_exp separately.
+        Callers add (read_noise_e^2 * n_reads) / t_exp separately.
         """
-        dark_variance_rate = self.dark_current_rate * n_pix
-        cic_variance_rate = self.cic_rate * n_pix / t_photon
+        dark_variance_rate = self.dark_current_rate_e_per_s * n_pix
+        cic_variance_rate = self.clock_induced_charge_rate_e_per_frame * n_pix / t_photon
         return dark_variance_rate + cic_variance_rate
 
     def readout_noise_electrons(
         self,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
-        """Dark current only -- SimpleDetector has no CIC or read noise."""
-        return simulate_dark_current(
-            self.dark_current_rate, exposure_time, self.shape, prng_key
+        """Dark current only -- IdealDetector has no CIC or read noise."""
+        return dark_current(
+            self.dark_current_rate_e_per_s, exposure_time_s, self.shape, prng_key
         )
 
     def readout(
         self,
         image_rate: Array,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Full detector readout: source electrons + dark current."""
         key_src, key_noise = jax.random.split(prng_key, 2)
-        source = self.readout_source_electrons(image_rate, exposure_time, key_src)
-        noise = self.readout_noise_electrons(exposure_time, key_noise)
+        source = self.readout_source_electrons(image_rate, exposure_time_s, key_src)
+        noise = self.readout_noise_electrons(exposure_time_s, key_noise)
         return source + noise
 
     def __repr__(self) -> str:
         """One-line summary of shape, plate scale, QE, and dark current."""
         ny, nx = self.shape
         return (
-            f"SimpleDetector({ny}x{nx} @ {self.pixel_scale:.3g} arcsec/px, "
+            f"IdealDetector({ny}x{nx} @ {self.pixel_scale_arcsec:.3g} arcsec/px, "
             f"QE={self.quantum_efficiency:.2f}, "
-            f"dark={self.dark_current_rate:.2g} e-/s/px)"
+            f"dark={self.dark_current_rate_e_per_s:.2g} e-/s/px)"
         )
 
 
@@ -340,42 +340,42 @@ class Detector(AbstractDetector):
     sources matter.  Uses Poisson statistics for dark/CIC and Gaussian
     for read noise, matching the coronagraphoto convention.
 
-    Warning: ``num_frames = jnp.ceil(exposure_time / frame_time)`` is
+    Warning: ``num_frames = jnp.ceil(exposure_time_s / frame_time_s)`` is
     kept as a float. Never cast it to int inside JIT -- that triggers a
-    ConcretizationTypeError when exposure_time is traced.
+    ConcretizationTypeError when exposure_time_s is traced.
     """
 
-    pixel_scale: float
+    pixel_scale_arcsec: float
     quantum_efficiency: float
-    dark_current_rate: float
-    read_noise_electrons: float
-    cic_rate: float
-    frame_time: float
-    read_time: float
+    dark_current_rate_e_per_s: float
+    read_noise_e: float
+    clock_induced_charge_rate_e_per_frame: float
+    frame_time_s: float
+    read_time_s: float
     dqe: float
     shape: tuple[int, int] = eqx.field(static=True)
 
     def __init__(
         self,
-        pixel_scale: float,
+        pixel_scale_arcsec: float,
         shape: tuple[int, int],
         quantum_efficiency: float = 1.0,
-        dark_current_rate: float = 0.0,
-        read_noise_electrons: float = 0.0,
-        cic_rate: float = 0.0,
-        frame_time: float = 1.0,
-        read_time: float = 0.05,
+        dark_current_rate_e_per_s: float = 0.0,
+        read_noise_e: float = 0.0,
+        clock_induced_charge_rate_e_per_frame: float = 0.0,
+        frame_time_s: float = 1.0,
+        read_time_s: float = 0.05,
         dqe: float = 0.0,
     ) -> None:
         """Create a full detector with all noise sources."""
-        self.pixel_scale = pixel_scale
+        self.pixel_scale_arcsec = pixel_scale_arcsec
         self.shape = shape
         self.quantum_efficiency = quantum_efficiency
-        self.dark_current_rate = dark_current_rate
-        self.read_noise_electrons = read_noise_electrons
-        self.cic_rate = cic_rate
-        self.frame_time = frame_time
-        self.read_time = read_time
+        self.dark_current_rate_e_per_s = dark_current_rate_e_per_s
+        self.read_noise_e = read_noise_e
+        self.clock_induced_charge_rate_e_per_frame = clock_induced_charge_rate_e_per_frame
+        self.frame_time_s = frame_time_s
+        self.read_time_s = read_time_s
         self.dqe = dqe
 
     def get_qe(self, wavelength_nm: ArrayLike) -> ArrayLike:
@@ -384,48 +384,50 @@ class Detector(AbstractDetector):
 
     def scalar_noise_rate(self, n_pix: ArrayLike, t_photon: ArrayLike) -> ArrayLike:
         """Combined dark + CIC noise variance rate."""
-        dark_variance_rate = self.dark_current_rate * n_pix
-        cic_variance_rate = self.cic_rate * n_pix / t_photon
+        dark_variance_rate = self.dark_current_rate_e_per_s * n_pix
+        cic_variance_rate = self.clock_induced_charge_rate_e_per_frame * n_pix / t_photon
         return dark_variance_rate + cic_variance_rate
 
     def readout_noise_electrons(
         self,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Dark current + CIC + read noise (source-independent)."""
         key_dark, key_cic, key_read = jax.random.split(prng_key, 3)
-        dark = simulate_dark_current(
-            self.dark_current_rate, exposure_time, self.shape, key_dark
+        dark_e = dark_current(
+            self.dark_current_rate_e_per_s, exposure_time_s, self.shape, key_dark
         )
         # num_frames stays as a traced float -- never cast to int
-        num_frames = jnp.ceil(exposure_time / self.frame_time)
-        cic = simulate_cic(self.cic_rate, num_frames, self.shape, key_cic)
-        read = simulate_read_noise(
-            self.read_noise_electrons, num_frames, self.shape, key_read
+        num_frames = jnp.ceil(exposure_time_s / self.frame_time_s)
+        cic_e = clock_induced_charge(
+            self.clock_induced_charge_rate_e_per_frame, num_frames, self.shape, key_cic
         )
-        return dark + cic + read
+        read_e = read_noise(
+            self.read_noise_e, num_frames, self.shape, key_read
+        )
+        return dark_e + cic_e + read_e
 
     def readout(
         self,
         image_rate: Array,
-        exposure_time: ArrayLike,
+        exposure_time_s: ArrayLike,
         prng_key: Array,
     ) -> Array:
         """Full detector readout: source electrons + all noise sources."""
         key_src, key_noise = jax.random.split(prng_key, 2)
-        source = self.readout_source_electrons(image_rate, exposure_time, key_src)
-        noise = self.readout_noise_electrons(exposure_time, key_noise)
+        source = self.readout_source_electrons(image_rate, exposure_time_s, key_src)
+        noise = self.readout_noise_electrons(exposure_time_s, key_noise)
         return source + noise
 
     def __repr__(self) -> str:
         """One-line summary of shape, plate scale, QE, and noise sources."""
         ny, nx = self.shape
         return (
-            f"Detector({ny}x{nx} @ {self.pixel_scale:.3g} arcsec/px, "
+            f"Detector({ny}x{nx} @ {self.pixel_scale_arcsec:.3g} arcsec/px, "
             f"QE={self.quantum_efficiency:.2f}, "
-            f"dark={self.dark_current_rate:.2g} e-/s/px, "
-            f"RN={self.read_noise_electrons:.2g} e-/read, "
-            f"CIC={self.cic_rate:.2g} e-/frame, "
-            f"frame_time={self.frame_time:.3g} s)"
+            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, "
+            f"frame_time_s={self.frame_time_s:.3g} s)"
         )

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/exposure.py

@@ -1,4 +1,4 @@
-"""Exposure: physical parameters defining a single detector integration.
+"""ExposureConfig: physical parameters defining a single detector integration.
 
 Relocated from coronagraphoto so the same object can be consumed by
 both image-level (coronagraphoto) and analytic (jaxedith) code paths.
@@ -10,7 +10,7 @@ import equinox as eqx
 import jax.numpy as jnp
 
 
-class Exposure(eqx.Module):
+class ExposureConfig(eqx.Module):
     """The physical parameters defining a single detector integration.
 
     All fields can be scalars (for a single event) or vectors (for a
@@ -25,11 +25,11 @@ class Exposure(eqx.Module):
 
     @classmethod
     def in_axes(cls, **vectorized_axes):
-        """Helper to generate in_axes structure for JAX vmap over an Exposure.
+        """Helper to generate in_axes structure for JAX vmap over an ExposureConfig.
 
         Usage:
             # Vectorize over wavelength (axis 0), keep time constant
-            in_axes = Exposure.in_axes(central_wavelength_nm=0, bin_width_nm=0)
+            in_axes = ExposureConfig.in_axes(central_wavelength_nm=0, bin_width_nm=0)
         """
         spec_dict = {f.name: None for f in fields(cls)}
         spec_dict.update(vectorized_axes)

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/optical_elements.py

@@ -62,7 +62,7 @@ class AbstractUniformElement(AbstractOpticalElement):
 
 
 @final
-class ConstantThroughputElement(AbstractUniformElement):
+class ConstantThroughput(AbstractUniformElement):
     """An optical element with wavelength-independent throughput.
 
     Useful for modeling simple attenuators, beamsplitters, or as a
@@ -79,18 +79,21 @@ class ConstantThroughputElement(AbstractUniformElement):
     def __repr__(self) -> str:
         """One-line summary of throughput value."""
         return (
-            f"ConstantThroughputElement(name={self.name!r}, "
+            f"ConstantThroughput(name={self.name!r}, "
             f"throughput={self.throughput:.3g})"
         )
 
 
 @final
-class LinearThroughputElement(AbstractUniformElement):
-    """An optical element with linearly interpolated wavelength-dependent throughput.
+class SpectralThroughput(AbstractUniformElement):
+    """Wavelength-dependent throughput defined by sampled (wavelength, throughput) pairs.
 
-    Throughput is specified at a set of wavelengths and linearly
-    interpolated between them. Extrapolation returns zero outside the
-    defined wavelength range.
+    Linear interpolation between samples; throughput is zero outside
+    the defined wavelength range.
+
+    Represents any tabulated wavelength-dependent throughput in the
+    optical path: bandpass filters, dichroics, mirror reflectivity,
+    coating losses, ADCs, blocking filters, etc.
     """
 
     wavelengths_nm: Array
@@ -98,7 +101,7 @@ class LinearThroughputElement(AbstractUniformElement):
     interp: interpax.Interpolator1D
 
     def __init__(self, wavelengths_nm: Array, throughputs: Array) -> None:
-        """Create a throughput element from sampled wavelength/throughput pairs."""
+        """Create a spectral throughput element from sampled pairs."""
         self.wavelengths_nm = wavelengths_nm
         self.throughputs = throughputs
         self.interp = interpax.Interpolator1D(
@@ -117,46 +120,6 @@ class LinearThroughputElement(AbstractUniformElement):
         t_min = float(self.throughputs.min())
         t_max = float(self.throughputs.max())
         return (
-            f"LinearThroughputElement(wl={wl_min:.0f}-{wl_max:.0f} nm, "
+            f"SpectralThroughput(wl={wl_min:.0f}-{wl_max:.0f} nm, "
             f"n={n}, throughput={t_min:.3g}-{t_max:.3g})"
         )
-
-
-@final
-class OpticalFilter(AbstractUniformElement):
-    """A bandpass filter with linearly interpolated transmittance.
-
-    Structurally identical to LinearThroughputElement but semantically
-    distinct -- represents a spectral bandpass selection rather than a
-    reflective coating or attenuator.
-    """
-
-    wavelengths_nm: Array
-    transmittances: Array
-    interp: interpax.Interpolator1D
-
-    def __init__(self, wavelengths_nm: Array, transmittances: Array) -> None:
-        """Create an optical filter from sampled wavelength/transmittance pairs."""
-        self.wavelengths_nm = wavelengths_nm
-        self.transmittances = transmittances
-        self.interp = interpax.Interpolator1D(
-            wavelengths_nm,
-            transmittances,
-            method="linear",
-            extrap=jnp.array([0.0, 0.0]),
-        )
-
-    def get_throughput(self, wavelength_nm: ArrayLike) -> ArrayLike:
-        """Interpolate filter transmittance at the requested wavelength."""
-        return self.interp(wavelength_nm)
-
-    def __repr__(self) -> str:
-        """One-line summary of filter passband and peak transmittance."""
-        n = int(self.wavelengths_nm.shape[0])
-        wl_min = float(self.wavelengths_nm.min())
-        wl_max = float(self.wavelengths_nm.max())
-        t_peak = float(self.transmittances.max())
-        return (
-            f"OpticalFilter(wl={wl_min:.0f}-{wl_max:.0f} nm, "
-            f"n={n}, peak T={t_peak:.3g})"
-        )

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/optical_path.py

@@ -9,10 +9,10 @@ import equinox as eqx
 
 from optixstuff._repr import indent
 from optixstuff.coronagraph import AbstractCoronagraph
-from optixstuff.detector import AbstractDetector, SimpleDetector
+from optixstuff.detector import AbstractDetector, IdealDetector
 from optixstuff.optical_elements import (
     AbstractOpticalElement,
-    ConstantThroughputElement,
+    ConstantThroughput,
 )
 from optixstuff.primary import AbstractPrimary, SimplePrimary
 
@@ -56,7 +56,7 @@ class OpticalPath(eqx.Module):
         detector_shape: tuple[int, int] = (512, 512),
         pixel_scale_arcsec: float = 0.01,
         quantum_efficiency: float = 0.9,
-        dark_current_rate: float = 0.0,
+        dark_current_rate_e_per_s: float = 0.0,
         n_channels: float = 1.0,
         npix_multiplier: float = 1.0,
     ) -> OpticalPath:
@@ -78,14 +78,14 @@ class OpticalPath(eqx.Module):
                 EAC1 baseline).
             obscuration: Linear central-obscuration fraction. Default 0.
             attenuating_throughput: Combined throughput of the optical
-                chain (one :class:`ConstantThroughputElement`). Default
+                chain (one :class:`ConstantThroughput`). Default
                 ``1.0`` -- a perfect path; override for realistic studies.
             detector_shape: Detector ``(ny, nx)`` in pixels. Default
                 ``(512, 512)``.
             pixel_scale_arcsec: Detector plate scale [arcsec/px]. Default
                 ``0.01``.
             quantum_efficiency: Default ``0.9``.
-            dark_current_rate: Default ``0.0`` e-/s/px (perfect detector;
+            dark_current_rate_e_per_s: Default ``0.0`` e-/s/px (perfect detector;
                 callers add realistic noise when needed).
             n_channels: AYO parallel-path multiplier. Default ``1.0``.
             npix_multiplier: IFS signal-spread multiplier. Default ``1.0``.
@@ -110,16 +110,16 @@ class OpticalPath(eqx.Module):
         return cls(
             primary=SimplePrimary(diameter_m=diameter_m, obscuration=obscuration),
             attenuating_elements=(
-                ConstantThroughputElement(
+                ConstantThroughput(
                     throughput=attenuating_throughput, name="optics"
                 ),
             ),
             coronagraph=coro,
-            detector=SimpleDetector(
-                pixel_scale=pixel_scale_arcsec,
+            detector=IdealDetector(
+                pixel_scale_arcsec=pixel_scale_arcsec,
                 shape=detector_shape,
                 quantum_efficiency=quantum_efficiency,
-                dark_current_rate=dark_current_rate,
+                dark_current_rate_e_per_s=dark_current_rate_e_per_s,
             ),
             n_channels=n_channels,
             npix_multiplier=npix_multiplier,

{optixstuff-0.2.0 → optixstuff-1.0.0}/src/optixstuff/yippy_coronagraph.py

@@ -197,6 +197,6 @@ class YippyCoronagraph(AbstractCoronagraph):
         return (
             f"YippyCoronagraph(IWA={float(self.IWA):.3g}, "
             f"OWA={float(self.OWA):.3g} lambda/D, "
-            f"pixel_scale={float(self.pixel_scale_lod):.3g} lambda/D/px, "
+            f"pixel_scale_arcsec={float(self.pixel_scale_lod):.3g} lambda/D/px, "
             f"PSF {ny}x{nx})"
         )

optixstuff-0.2.0/README.md

@@ -1,79 +0,0 @@
-# optixstuff
-
-Flux-level optical system abstractions for the HWO direct imaging simulation suite.
-
-## What optixstuff is
-
-`optixstuff` is the **radiometric hardware layer** for HWO simulations. It operates on
-**flux** — photon rates, throughput fractions, and detector-level noise — providing the
-shared interfaces that simulation tools and exposure time calculators build on top of.
-
-The same `OpticalPath` object drives both scalar ETC calculations (`jaxEDITH`) and full
-2D image generation (`coronagraphoto`), ensuring that the hardware model is consistent
-across all downstream science products.
-
-## What optixstuff is *not*
-
-`optixstuff` does not model diffraction, wavefront propagation, or E-field interference.
-That level of physical optics belongs to tools like [dLux](https://github.com/LouisDesdoigts/dLux)
-and [HCIPy](https://github.com/ehpor/hcipy), which generate PSFs from first principles.
-
-`optixstuff` and these wavefront tools are **complementary**: dLux/HCIPy compute the PSFs,
-which are delivered as yield input packages (YIPs). `optixstuff` consumes those PSFs as
-flux patterns (via [yippy](https://github.com/CoreySpohn/yippy)) and composes them with
-the rest of the observatory — throughput chain, detector QE, noise — to produce
-science-level outputs.
-
-## Architecture
-
-Built on [JAX](https://github.com/google/jax) and
-[Equinox](https://github.com/patrick-kidger/equinox), `optixstuff` provides:
-
-- **Abstract interfaces** — `AbstractPrimary`, `AbstractOpticalElement`,
-  `AbstractCoronagraph`, `AbstractDetector`
-- **Concrete implementations** — `SimplePrimary`, `ConstantThroughputElement`,
-  `SimpleDetector`
-- **Container** — `OpticalPath`, a composable hardware configuration passed to all
-  simulators
-
-Every abstract method accepts three fidelity axes — **wavelength**, **position**, and
-**time** — with defaults so that simple implementations can ignore unused axes while
-future high-fidelity models (wavelength-dependent coatings, position-dependent vignetting,
-time-dependent detector degradation) can use them without breaking the interface.
-
-### Ecosystem position
-
-```
-                          ┌───────────────────────────┐
-                          │  Physical optics           │
-                          │  (dLux, HCIPy, PROPER)     │
-                          │  E-fields → PSFs           │
-                          └──────────┬────────────────┘
-                                     │ YIP
-                          ┌──────────▼────────────────┐
-                          │  yippy                     │
-                          │  PSF interpolation         │
-                          └──────────┬────────────────┘
-                                     │ flux patterns
-              ┌──────────────────────▼────────────────────────┐
-              │                  optixstuff                    │
-              │  Telescope • Coronagraph • Detector • OpticalPath │
-              │  Throughput chains • QE • Noise rates          │
-              └────────┬──────────────────────┬───────────────┘
-                       │                      │
-            ┌──────────▼──────────┐ ┌────────▼───────────────┐
-            │  jaxEDITH           │ │  coronagraphoto         │
-            │  Scalar count rates │ │  2D image simulation    │
-            │  Exposure times     │ │  Multi-epoch scenes     │
-            └─────────────────────┘ └────────────────────────┘
-```
-
-## Installation
-
-```bash
-pip install optixstuff
-```
-
-## Status
-
-This package is in early development (pre-v0.1.0).