getframes 2.0.0__tar.gz → 2.1.1__tar.gz

{getframes-2.0.0 → getframes-2.1.1}/.gitignore

@@ -222,3 +222,5 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+keck_ttf
+*.png

{getframes-2.0.0 → getframes-2.1.1}/CHANGELOG.md

@@ -6,6 +6,104 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.1.1] - 2026-07-26
+
+### Added
+
+- Exact multi-amplifier ROI geometry and measured row-major gain/offset response
+  fields. The OCAM2K preset now declares its eight-output 4x2 layout; cropped
+  configurations can preserve their true split pixels.
+- Optional CuPy detector execution via `Camera(..., device="gpu")`. Photon-rate,
+  electron, `FrameTruth`, and digitised ADU arrays remain device-resident through
+  scalar and spectral exposure paths, including all detector artifact models and
+  both binning modes. `Frame.device`, `get_backend`, `get_array_module`, and
+  `to_numpy` make the execution and host-copy boundaries explicit.
+- CUDA parity tests cover seeded reproducibility, CPU/GPU statistics, spectral
+  truth, CCD/CMOS/sCMOS/EMCCD/eAPD paths, fixed structure, gain, and detector
+  artifacts. The benchmark runner accepts `--device gpu|both`.
+- Added a reproducible paired-device bulk-throughput suite, self-describing JSON
+  artifact, rendered reference table, and README/GPU-guide CPU-versus-GPU results
+  for representative WFS, EMCCD, eAPD, and large science-frame workflows.
+
+### Changed
+
+- Re-characterized the OCAM2K preset from the Keck unit report and supplied
+  detector studies: approximately 28 output e-/ADU (21.43 ADU per input electron
+  at EM gain 600), 0.360 e- input-referred read noise, 1.579 e-/pixel/s dark
+  current, and a separately derived 0.004912 e-/pixel/frame CIC term. The output
+  saturation charge and representative Keck bias now use the same conversion
+  convention.
+- Fixed PRNU/DSNU/hot-pixel, amplifier, bias-structure, and defect maps are built
+  once on persistent `Camera` construction rather than regenerated for every
+  frame. This preserves the fixed-pattern contract and materially improves both
+  CPU and GPU warm exposure throughput.
+- Optimized warm detector execution with in-place signal construction and
+  digitization, direct full-array Gamma sampling, working-precision CPU/GPU
+  Gaussian and Gamma draws, and a reusable per-call GPU seed stream. The RTX
+  5090 reference improves GPU CMOS throughput by 1.36x–1.42x and GPU EMCCD/eAPD
+  throughput by 2.35x–2.41x over the initial implementation without changing the
+  detector distributions.
+
+### Fixed
+
+- Separated image-area and post-multiplication saturation with the optional,
+  backwards-compatible `CameraConfig.output_full_well_e`. Gain-stage input charge
+  now clips at `full_well_e` before multiplication. The OCAM2K preset uses Andor's
+  published 270,000 e- image well and Keck's measured 10,000-count output ceiling,
+  instead of incorrectly clipping multiplied signal at 250 e- (25 ADU).
+
+## [2.1.0] - 2026-07-19
+
+### Added
+
+- `Camera.expose_spectral`, a single-pass wavelength-resolved photon-cube
+  detector entry point. It applies the configured QE curve exactly once and
+  preserves integrated and spectral photon-rate truth arrays.
+- Five scientific-camera presets used by the Keck tip/tilt and low-bandwidth WFS
+  detector trade example: KURO 1200B, Prime 95B, Marana 4.2B-11, QHY530 Pro II,
+  and Aries 6504 Pro. All five now include a wavelength-resolved `qe_curve`:
+  Marana and Aries from Andor's/Gpixel's published data (the Aries
+  `QE x fill factor` trace is digitized from Gpixel's graph); KURO 1200B,
+  Prime 95B, and QHY530 Pro II are digitized from published manufacturer QE
+  plots.
+- A `quantum_efficiency` override on `Camera.expose_series`, matching
+  `Camera.expose` and supporting pre-integrated spectral electron-rate series.
+- A Keck/SciMeasure Little Joe CCD39 preset with the manufacturer CCD39-01
+  standard-AR/no-window spectral-response curve.
+- `getframes.analysis.matched_filter_centroid`, a background-insensitive
+  cross-correlation centroid with sub-pixel peak refinement.
+- `Frame.binned(factor, method=...)`, post-read digital binning of a frame into
+  `factor x factor` super-pixels (sum or mean).
+- `CameraConfig.supported_binnings` and `CameraConfig.binning_method` — binning is
+  now a first-class config parameter. The Keck-trade presets set these directly and
+  drop the `extra.detector_modes` per-binning tables; cameras with more than one
+  read-noise operating point keep a slim `extra.read_modes` list instead.
+- Native pixel binning in the signal chain: `Camera.expose`, `Camera.expose_series`,
+  and `noise.simulate_frame` accept `binning` and `binning_mode`. `"digital"`
+  (post-read, the default) reads each native pixel with its own read noise then sums,
+  so binned read noise grows as `binning`; `"on_chip"` (pre-read charge-domain /
+  hardware binning) sums the charge before the amplifier, so a single read noise is
+  applied per super-pixel. Exposed `noise.block_sum` for the super-pixel summation.
+- `getframes.analysis.centroid` now accepts a per-pixel array `background` (e.g. a
+  master sky+dark frame) and an optional `threshold` (scalar or per-pixel noise
+  map), making it a calibrated thresholded centre-of-gravity estimator suitable
+  for a real-time controller. Both additions are backwards compatible.
+- A Keck LGS tip/tilt and low-bandwidth wavefront-sensor detector trade-study
+  example, including physically sampled AO/sub-aperture PSFs, complete detector
+  Monte Carlo simulations, blackbody NGS weighting of each camera's QE curve
+  (`--ngs-teff`), the 600–950 nm TTS/LBWFS arm bandpass folded into the zero-point
+  bands, Monte Carlo standard errors on every point, a per-camera closed-loop
+  cadence optimisation (a physical `a·f + b·f²` noise model fitted to the Monte
+  Carlo data, saturation-aware, against a Tyler tilt-lag disturbance model), and
+  a best/worst-performer frame gallery figure beside the trade curves.
+
+### Fixed
+
+- Type-checking compatibility with newer NumPy (2.2): tightened stub types for
+  `_stamp_bounds`/`_radial_grid` shape arguments, pinned `float64` on a few
+  `np.linspace` constructions, and dropped now-unused `type: ignore` comments
+  around the `trapz`/`trapezoid` shim. No behavioural change.
+
 ## [2.0.0] - 2026-06-29
 
 The 2.0 cut promotes the full surface grown across 1.1–1.6 to **stable** and lands
@@ -248,6 +346,9 @@ together in 1.0.
 - Documentation, runnable examples, and CI (lint, type-check, test matrix, PyPI
   release via Trusted Publishing).
 
-[Unreleased]: https://github.com/jacotay7/getframes/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/jacotay7/getframes/compare/v0.1.0...v1.0.0
-[0.1.0]: https://github.com/jacotay7/getframes/releases/tag/v0.1.0
+[Unreleased]: https://github.com/jacotay7/getframes/compare/2.1.1...HEAD
+[2.1.1]: https://github.com/jacotay7/getframes/compare/2.1.0...2.1.1
+[2.1.0]: https://github.com/jacotay7/getframes/compare/2.0.0...2.1.0
+[2.0.0]: https://github.com/jacotay7/getframes/compare/1.0.0...2.0.0
+[1.0.0]: https://github.com/jacotay7/getframes/compare/0.1.0...1.0.0
+[0.1.0]: https://github.com/jacotay7/getframes/releases/tag/0.1.0

{getframes-2.0.0 → getframes-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getframes
-Version: 2.0.0
+Version: 2.1.1
 Summary: Generate physically realistic synthetic camera frames (CCD/CMOS/EMCCD/eAPD/sCMOS) — dark, bias, flat, and rendered star fields — with auditable noise physics for scientific imaging pipelines.
 Project-URL: Homepage, https://github.com/jacotay7/getframes
 Project-URL: Documentation, https://jacotay7.github.io/getframes/
@@ -40,6 +40,8 @@ Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: examples
 Requires-Dist: matplotlib>=3.7; extra == 'examples'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=13.0; extra == 'gpu'
 Description-Content-Type: text/markdown
 
 # getframes
@@ -65,12 +67,14 @@ photon → electron → ADU signal path, with optional opt-in spectral mode.
 > **Status:** stable. `getframes` 2.0 freezes the full public surface — the
 > detector, scene, calibration, observation, radiometry, and dataset APIs — under
 > [Semantic Versioning](https://semver.org/spec/v2.0.0.html); see
-> [API stability](docs/stability.md).
+> [API stability](docs/stability.md). An optional CuPy backend now keeps the
+> photon → electron → ADU detector path and truth arrays on NVIDIA GPUs.
 
 ## Install
 
 ```bash
 pip install getframes
+pip install 'getframes[gpu]'  # optional CUDA 12.x / CuPy detector backend
 ```
 
 From source (for development):
@@ -92,15 +96,16 @@ cam = gf.Camera.from_preset("andor_ikon_m934")
 # ...and generate a reproducible dark frame.
 frame = cam.dark_frame(exposure=60.0, temperature=-60.0, seed=0)
 
-frame.data            # 2-D numpy array of ADU, shape (1024, 1024)
-frame.stats()         # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
-frame.metadata        # camera/exposure/temperature provenance
+frame.data  # 2-D numpy array of ADU, shape (1024, 1024)
+frame.stats()  # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
+frame.metadata  # camera/exposure/temperature provenance
 ```
 
 `Frame` is array-like, so it drops straight into NumPy:
 
 ```python
 import numpy as np
+
 master_dark = np.mean([np.asarray(f) for f in cam.dark_series(60.0, n_frames=20, seed=1)], axis=0)
 ```
 
@@ -111,7 +116,7 @@ cam = gf.Camera(
     gf.CameraConfig(
         name="My Lab CMOS",
         sensor_type="CMOS",
-        resolution=(2048, 2048),       # (height, width)
+        resolution=(2048, 2048),  # (height, width)
         pixel_size_um=6.5,
         quantum_efficiency=0.82,
         full_well_e=30_000,
@@ -119,7 +124,7 @@ cam = gf.Camera(
         gain_e_per_adu=0.8,
         bias_offset_adu=300,
         read_noise_e=1.8,
-        dark_current_e_per_s=0.5,      # at the reference temperature
+        dark_current_e_per_s=0.5,  # at the reference temperature
         dark_current_ref_temp_c=20.0,
         dark_current_doubling_temp_c=6.0,
     )
@@ -127,6 +132,45 @@ cam = gf.Camera(
 frame = cam.dark_frame(exposure=30.0, temperature=-10.0)
 ```
 
+### Run the detector on a GPU
+
+```python
+import cupy as cp
+import getframes as gf
+
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
+frame = cam.expose(rate, exposure=1.0e-3, seed=0)
+
+frame.data  # CuPy uint32 ADU array; no host copy
+frame.truth.mean_electrons  # CuPy truth array
+host_adu = gf.to_numpy(frame.data)  # explicit device-to-host boundary
+```
+
+CPU and GPU use independent random-number streams: a seed repeats exactly on a
+fixed backend, while parity across backends means matching detector statistics,
+not identical pixels. See the [GPU guide](docs/guides/gpu.md).
+
+## CPU/GPU throughput
+
+Warm bulk-frame throughput on an AMD Ryzen 9 9950X3D and NVIDIA RTX 5090
+(`float32`, truth enabled, persistent camera, device-resident input/output, no
+host transfers) is:
+
+| Workflow | Native shape | CPU (frames/s) | GPU (frames/s) | Speedup |
+| --- | ---: | ---: | ---: | ---: |
+| Pyramid WFS CMOS | 80x80 | 5,264.9 | 10,565.4 | 2.01x |
+| Shack-Hartmann WFS CMOS | 160x160 | 1,372.0 | 10,538.1 | 7.68x |
+| OCAM2K EMCCD | 240x240 | 347.7 | 8,057.1 | 23.17x |
+| SAPHIRA eAPD | 256x320 | 283.2 | 7,481.8 | 26.42x |
+| Large science CMOS | 1024x1024 | 31.5 | 1,431.9 | 45.39x |
+
+Higher is better. CUDA was synchronized around every timed region; construction
+was excluded. Even the smallest case reaches about 2x, while larger arrays and
+gain-stage detectors expose much more parallel work. See the
+[full snapshot](benchmarks/device-results.md), [raw JSON](benchmarks/device-results.json),
+and [GPU benchmark methodology](docs/guides/gpu.md#reference-throughput).
+
 ### Observe a simulated star field
 
 Render astronomical sources through a PSF and telescope, then expose them on a
@@ -135,14 +179,18 @@ detector — the full photon → electron → ADU path:
 ```python
 scene = gf.Scene(
     shape=(256, 256),
-    optics=gf.Telescope(aperture_diameter_m=2.5, throughput=0.3,
-                        plate_scale_arcsec_per_pixel=0.4, band=gf.Bandpass.johnson("V")),
+    optics=gf.Telescope(
+        aperture_diameter_m=2.5,
+        throughput=0.3,
+        plate_scale_arcsec_per_pixel=0.4,
+        band=gf.Bandpass.johnson("V"),
+    ),
     psf=gf.MoffatPSF(fwhm_arcsec=1.1, beta=3.0),
     sources=[gf.PointSource(x=128, y=128, magnitude=20.0)],
     sky=gf.Sky(surface_brightness_mag_arcsec2=21.0),
 )
 cam = gf.Camera.from_preset("zwo_asi2600mm").with_config(resolution=(256, 256))
-frame = cam.observe(scene, exposure=300.0, seed=0)   # a realistic science frame
+frame = cam.observe(scene, exposure=300.0, seed=0)  # a realistic science frame
 ```
 
 You can also drive the detector directly with a photon-rate map (a scalar for a
@@ -154,8 +202,8 @@ uniform flat, or a per-pixel array): `cam.expose(photon_rate, exposure)`.
 from getframes import available_presets
 from getframes.presets import preset_info
 
-available_presets()   # ['andor_ikon_m934', 'andor_ixon_ultra_888', 'generic_ccd', ...]
-preset_info()         # rich descriptors for each preset
+available_presets()  # ['andor_ikon_m934', 'andor_ixon_ultra_888', 'generic_ccd', ...]
+preset_info()  # rich descriptors for each preset
 ```
 
 | Preset | Sensor | Notes |
@@ -165,6 +213,11 @@ preset_info()         # rich descriptors for each preset
 | `leonardo_saphira` | EAPD | HgCdTe avalanche IR array (AO wavefront sensing) |
 | `zwo_asi2600mm` | CMOS | Sony IMX571 cooled CMOS |
 | `hamamatsu_orca_fusion` | sCMOS | Back-thinned sCMOS with per-pixel read noise |
+| `andor_marana_4_2b_11` | sCMOS | 11 µm-pixel, back-illuminated scientific CMOS |
+| `photometrics_prime_95b` | sCMOS | 11 µm-pixel, 95% peak-QE scientific CMOS |
+| `princeton_instruments_kuro_1200b` | sCMOS | Back-illuminated scientific CMOS |
+| `qhy530_pro_ii` | CMOS | Global-shutter Sony IMX530 scientific camera |
+| `tucsen_aries_6504_pro` | sCMOS | Sub-electron sensitive-mode read noise |
 | `generic_ccd` / `generic_cmos` / `generic_emccd` / `generic_eapd` / `generic_scmos` | — | Idealised references for teaching/testing |
 
 ## How the dark-frame model works

{getframes-2.0.0 → getframes-2.1.1}/README.md

@@ -21,12 +21,14 @@ photon → electron → ADU signal path, with optional opt-in spectral mode.
 > **Status:** stable. `getframes` 2.0 freezes the full public surface — the
 > detector, scene, calibration, observation, radiometry, and dataset APIs — under
 > [Semantic Versioning](https://semver.org/spec/v2.0.0.html); see
-> [API stability](docs/stability.md).
+> [API stability](docs/stability.md). An optional CuPy backend now keeps the
+> photon → electron → ADU detector path and truth arrays on NVIDIA GPUs.
 
 ## Install
 
 ```bash
 pip install getframes
+pip install 'getframes[gpu]'  # optional CUDA 12.x / CuPy detector backend
 ```
 
 From source (for development):
@@ -48,15 +50,16 @@ cam = gf.Camera.from_preset("andor_ikon_m934")
 # ...and generate a reproducible dark frame.
 frame = cam.dark_frame(exposure=60.0, temperature=-60.0, seed=0)
 
-frame.data            # 2-D numpy array of ADU, shape (1024, 1024)
-frame.stats()         # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
-frame.metadata        # camera/exposure/temperature provenance
+frame.data  # 2-D numpy array of ADU, shape (1024, 1024)
+frame.stats()  # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
+frame.metadata  # camera/exposure/temperature provenance
 ```
 
 `Frame` is array-like, so it drops straight into NumPy:
 
 ```python
 import numpy as np
+
 master_dark = np.mean([np.asarray(f) for f in cam.dark_series(60.0, n_frames=20, seed=1)], axis=0)
 ```
 
@@ -67,7 +70,7 @@ cam = gf.Camera(
     gf.CameraConfig(
         name="My Lab CMOS",
         sensor_type="CMOS",
-        resolution=(2048, 2048),       # (height, width)
+        resolution=(2048, 2048),  # (height, width)
         pixel_size_um=6.5,
         quantum_efficiency=0.82,
         full_well_e=30_000,
@@ -75,7 +78,7 @@ cam = gf.Camera(
         gain_e_per_adu=0.8,
         bias_offset_adu=300,
         read_noise_e=1.8,
-        dark_current_e_per_s=0.5,      # at the reference temperature
+        dark_current_e_per_s=0.5,  # at the reference temperature
         dark_current_ref_temp_c=20.0,
         dark_current_doubling_temp_c=6.0,
     )
@@ -83,6 +86,45 @@ cam = gf.Camera(
 frame = cam.dark_frame(exposure=30.0, temperature=-10.0)
 ```
 
+### Run the detector on a GPU
+
+```python
+import cupy as cp
+import getframes as gf
+
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
+frame = cam.expose(rate, exposure=1.0e-3, seed=0)
+
+frame.data  # CuPy uint32 ADU array; no host copy
+frame.truth.mean_electrons  # CuPy truth array
+host_adu = gf.to_numpy(frame.data)  # explicit device-to-host boundary
+```
+
+CPU and GPU use independent random-number streams: a seed repeats exactly on a
+fixed backend, while parity across backends means matching detector statistics,
+not identical pixels. See the [GPU guide](docs/guides/gpu.md).
+
+## CPU/GPU throughput
+
+Warm bulk-frame throughput on an AMD Ryzen 9 9950X3D and NVIDIA RTX 5090
+(`float32`, truth enabled, persistent camera, device-resident input/output, no
+host transfers) is:
+
+| Workflow | Native shape | CPU (frames/s) | GPU (frames/s) | Speedup |
+| --- | ---: | ---: | ---: | ---: |
+| Pyramid WFS CMOS | 80x80 | 5,264.9 | 10,565.4 | 2.01x |
+| Shack-Hartmann WFS CMOS | 160x160 | 1,372.0 | 10,538.1 | 7.68x |
+| OCAM2K EMCCD | 240x240 | 347.7 | 8,057.1 | 23.17x |
+| SAPHIRA eAPD | 256x320 | 283.2 | 7,481.8 | 26.42x |
+| Large science CMOS | 1024x1024 | 31.5 | 1,431.9 | 45.39x |
+
+Higher is better. CUDA was synchronized around every timed region; construction
+was excluded. Even the smallest case reaches about 2x, while larger arrays and
+gain-stage detectors expose much more parallel work. See the
+[full snapshot](benchmarks/device-results.md), [raw JSON](benchmarks/device-results.json),
+and [GPU benchmark methodology](docs/guides/gpu.md#reference-throughput).
+
 ### Observe a simulated star field
 
 Render astronomical sources through a PSF and telescope, then expose them on a
@@ -91,14 +133,18 @@ detector — the full photon → electron → ADU path:
 ```python
 scene = gf.Scene(
     shape=(256, 256),
-    optics=gf.Telescope(aperture_diameter_m=2.5, throughput=0.3,
-                        plate_scale_arcsec_per_pixel=0.4, band=gf.Bandpass.johnson("V")),
+    optics=gf.Telescope(
+        aperture_diameter_m=2.5,
+        throughput=0.3,
+        plate_scale_arcsec_per_pixel=0.4,
+        band=gf.Bandpass.johnson("V"),
+    ),
     psf=gf.MoffatPSF(fwhm_arcsec=1.1, beta=3.0),
     sources=[gf.PointSource(x=128, y=128, magnitude=20.0)],
     sky=gf.Sky(surface_brightness_mag_arcsec2=21.0),
 )
 cam = gf.Camera.from_preset("zwo_asi2600mm").with_config(resolution=(256, 256))
-frame = cam.observe(scene, exposure=300.0, seed=0)   # a realistic science frame
+frame = cam.observe(scene, exposure=300.0, seed=0)  # a realistic science frame
 ```
 
 You can also drive the detector directly with a photon-rate map (a scalar for a
@@ -110,8 +156,8 @@ uniform flat, or a per-pixel array): `cam.expose(photon_rate, exposure)`.
 from getframes import available_presets
 from getframes.presets import preset_info
 
-available_presets()   # ['andor_ikon_m934', 'andor_ixon_ultra_888', 'generic_ccd', ...]
-preset_info()         # rich descriptors for each preset
+available_presets()  # ['andor_ikon_m934', 'andor_ixon_ultra_888', 'generic_ccd', ...]
+preset_info()  # rich descriptors for each preset
 ```
 
 | Preset | Sensor | Notes |
@@ -121,6 +167,11 @@ preset_info()         # rich descriptors for each preset
 | `leonardo_saphira` | EAPD | HgCdTe avalanche IR array (AO wavefront sensing) |
 | `zwo_asi2600mm` | CMOS | Sony IMX571 cooled CMOS |
 | `hamamatsu_orca_fusion` | sCMOS | Back-thinned sCMOS with per-pixel read noise |
+| `andor_marana_4_2b_11` | sCMOS | 11 µm-pixel, back-illuminated scientific CMOS |
+| `photometrics_prime_95b` | sCMOS | 11 µm-pixel, 95% peak-QE scientific CMOS |
+| `princeton_instruments_kuro_1200b` | sCMOS | Back-illuminated scientific CMOS |
+| `qhy530_pro_ii` | CMOS | Global-shutter Sony IMX530 scientific camera |
+| `tucsen_aries_6504_pro` | sCMOS | Sub-electron sensitive-mode read noise |
 | `generic_ccd` / `generic_cmos` / `generic_emccd` / `generic_eapd` / `generic_scmos` | — | Idealised references for teaching/testing |
 
 ## How the dark-frame model works

getframes-2.1.1/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark helpers; not part of the public getframes API."""

getframes-2.1.1/benchmarks/bench_devices.py

@@ -0,0 +1,212 @@
+"""Record warm CPU/GPU detector throughput for representative frame workloads."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import json
+import platform
+import shlex
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import getframes as gf
+
+
+@dataclass(frozen=True)
+class Workflow:
+    """One representative persistent-camera workload."""
+
+    key: str
+    label: str
+    preset: str
+    shape: tuple[int, int]
+    exposure_s: float
+    photon_rate_per_s: float
+
+
+WORKFLOWS = (
+    Workflow("pyramid_cmos_80", "Pyramid WFS CMOS", "generic_cmos", (80, 80), 1e-3, 2e6),
+    Workflow(
+        "shack_hartmann_cmos_160",
+        "Shack-Hartmann WFS CMOS",
+        "generic_cmos",
+        (160, 160),
+        1e-3,
+        2e6,
+    ),
+    Workflow("ocam2k_emccd_240", "OCAM2K EMCCD", "andor_ocam2k", (240, 240), 1e-3, 2e6),
+    Workflow(
+        "saphira_eapd_256x320",
+        "SAPHIRA eAPD",
+        "leonardo_saphira",
+        (256, 320),
+        1e-3,
+        2e6,
+    ),
+    Workflow(
+        "science_cmos_1024",
+        "Large science CMOS",
+        "generic_cmos",
+        (1024, 1024),
+        5.0,
+        200.0,
+    ),
+)
+
+
+def _installed_version(name: str) -> str | None:
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _git_state(root: Path) -> tuple[str | None, bool | None]:
+    try:
+        revision = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=root,
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        dirty = bool(
+            subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+                text=True,
+            ).stdout.strip()
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None, None
+    return revision, dirty
+
+
+def _gpu_name() -> str | None:
+    try:
+        properties = gf.get_backend("gpu").xp.cuda.runtime.getDeviceProperties(0)
+    except (ImportError, RuntimeError):
+        return None
+    name = properties.get("name", "unknown GPU")
+    return name.decode() if isinstance(name, bytes) else str(name)
+
+
+def _cpu_model() -> str:
+    try:
+        for line in Path("/proc/cpuinfo").read_text(encoding="utf-8").splitlines():
+            if line.startswith("model name"):
+                return line.split(":", 1)[1].strip()
+    except OSError:
+        pass
+    return platform.processor() or "unknown CPU"
+
+
+def _sync(device: str) -> None:
+    if device == "gpu":
+        gf.get_backend("gpu").xp.cuda.Stream.null.synchronize()
+
+
+def _measure(workflow: Workflow, device: str, *, seconds: float, warmup: int) -> dict[str, Any]:
+    backend = gf.get_backend(device)
+    config = gf.load_preset(workflow.preset).replace(resolution=workflow.shape)
+    camera = gf.Camera(config, seed=0, precision="float32", device=device)
+    photon_rate = backend.xp.full(
+        workflow.shape,
+        workflow.photon_rate_per_s,
+        dtype=backend.xp.float32,
+    )
+    for _ in range(warmup):
+        camera.expose(photon_rate, workflow.exposure_s)
+    _sync(device)
+
+    frames = 0
+    start = time.perf_counter()
+    while True:
+        camera.expose(photon_rate, workflow.exposure_s)
+        frames += 1
+        if time.perf_counter() - start >= seconds:
+            break
+    _sync(device)
+    elapsed = time.perf_counter() - start
+    return {
+        "workflow": workflow.key,
+        "label": workflow.label,
+        "preset": workflow.preset,
+        "sensor": config.sensor_type.value,
+        "shape": list(workflow.shape),
+        "precision": "float32",
+        "exposure_s": workflow.exposure_s,
+        "photon_rate_per_s": workflow.photon_rate_per_s,
+        "device": device,
+        "frames": frames,
+        "elapsed_s": elapsed,
+        "frame_s": elapsed / frames,
+        "frames_per_s": frames / elapsed,
+        "megapixels_per_s": frames * workflow.shape[0] * workflow.shape[1] / elapsed / 1e6,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--seconds", type=float, default=1.0, help="minimum seconds per cell")
+    parser.add_argument("--warmup", type=int, default=10, help="untimed frames per cell")
+    parser.add_argument("--device", choices=("cpu", "gpu", "both"), default="both")
+    parser.add_argument("--workflow", action="append", choices=[item.key for item in WORKFLOWS])
+    parser.add_argument("--output", type=Path, default=Path("benchmarks/device-results.json"))
+    args = parser.parse_args(argv)
+    if args.seconds <= 0:
+        parser.error("--seconds must be positive")
+    if args.warmup < 0:
+        parser.error("--warmup must be non-negative")
+
+    selected = [item for item in WORKFLOWS if not args.workflow or item.key in args.workflow]
+    devices = ("cpu", "gpu") if args.device == "both" else (args.device,)
+    root = Path(__file__).parents[1]
+    revision, source_dirty = _git_state(root)
+    report: dict[str, Any] = {
+        "schema_version": 1,
+        "generated_at_utc": datetime.now(UTC).isoformat(),
+        "command": shlex.join([sys.executable, *sys.argv]),
+        "revision": revision,
+        "source_dirty": source_dirty,
+        "python": sys.version,
+        "platform": platform.platform(),
+        "processor": platform.processor(),
+        "cpu": _cpu_model(),
+        "gpu": _gpu_name() if "gpu" in devices else None,
+        "dependencies": {
+            name: _installed_version(name) for name in ("getframes", "numpy", "scipy", "cupy")
+        },
+        "methodology": {
+            "seconds_per_cell": args.seconds,
+            "warmup_frames": args.warmup,
+            "persistent_camera": True,
+            "device_resident_rate_and_output": True,
+            "include_truth": True,
+            "rng": "one generator seeded at camera construction and advanced per frame",
+            "cuda_synchronization": "before and after each timed region",
+            "construction_included": False,
+            "host_transfers_included": False,
+        },
+        "results": [
+            _measure(item, device, seconds=args.seconds, warmup=args.warmup)
+            for item in selected
+            for device in devices
+        ],
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())