makewfs 2.0.0__tar.gz → 2.1.0__tar.gz

{makewfs-2.0.0 → makewfs-2.1.0}/AGENTS.md

@@ -172,8 +172,10 @@ Follow the target layout in `ROADMAP.md`:
   only) does not cover.
 - `sensors/` contains deterministic ideal optical engines and no camera noise.
   `_shack_hartmann_cuda.py` is a private first-use-JIT execution plan for exact
-  compatible CUDA geometries; `shack_hartmann.py` remains the readable physics
-  reference and must stay as the automatic feature-complete fallback.
+  compatible CUDA geometries (sampled-DFT and integer-FFT spot grids alike);
+  `shack_hartmann.py` remains the readable physics reference and must stay as
+  the automatic feature-complete fallback. `_cuda_graph.py` replays the
+  pyramid's fixed-shape GPU propagation from a captured CUDA graph.
 - `radiometry.py` produces source photon budgets using public `getframes` tools.
 - `detector.py` is a narrow adapter to `getframes.Camera.expose` and the
   optional public `expose_spectral` cube API, plus the
@@ -236,6 +238,33 @@ python benchmarks/check_regression.py /tmp/makewfs-benchmark.json
 MPLBACKEND=Agg python examples/gallery.py
 ```
 
+## Performance gotchas
+
+- `ArrayBackend.pruned_fft2` skips all-zero input lines and cropped output
+  lines of a 2-D FFT. Keep its `axes` equal to the pass order of the transform
+  it replaces: SciPy's `fft2` runs the listed axes in order when
+  `overwrite_x=True` but the last axis first when it allocates its output, and
+  the two orders round differently. SciPy also transforms lines in SIMD groups
+  whose short remainder group rounds differently, so a pruned transform can
+  differ from the full one by an ulp where the line counts differ. Check
+  candidate changes with a saved before/after render matrix, not only tests.
+- The pyramid applies its mask on the unshifted FFT grid (the stored mask is
+  `ifftshift`-ed) and turns the outer shifts into wrapped start indices. Do not
+  reintroduce `fftshift`/`ifftshift` copies there; they are pure permutations.
+- `PyramidEngine._propagate` is captured as a CUDA graph on a GPU. It must keep
+  fixed shapes and never synchronize with the host (no `scalar`, `.item()`,
+  `to_host`, or data-dependent shapes). A failed capture silently falls back to
+  eager execution and records why in `engine._graph.failure`; check it after
+  changing that method.
+- The compiled SH kernel reads the OPD as float64; `_CompiledShackHartmannExecutor.render`
+  widens a float32 lenslet-grid resample (exact). Its static thread and
+  shared-memory checks cannot see register pressure, so construction also
+  checks the compiled kernel's `max_threads_per_block` and falls back.
+- `ArrayBackend.next_fast_length` uses SciPy on the CPU and CuPy on the GPU,
+  which disagree when SciPy picks a factor of 11 (for example 33, 66, 99). The
+  pyramid's FFT size, and therefore its result, can then differ between
+  devices; parity tests use geometries where they agree.
+
 ## Documentation and examples
 
 - Every public feature lands with its API docstring and the relevant user guide.

{makewfs-2.0.0 → makewfs-2.1.0}/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to `makewfs` are documented here.
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-07
+
+### Performance
+
+- **Pruned FFTs on CPU and GPU.** Shack-Hartmann spots and the pyramid
+  transform only the FFT lines that hold data and keep only the cropped
+  output lines; the pyramid applies its mask on the unshifted grid instead of
+  shifting four full grids per state. CPU results are unchanged (bit-identical
+  in 451 of 468 arrays of a before/after matrix, otherwise within 2.5e-7
+  relative in float32).
+- **CUDA-graph replay of the pyramid.** On a GPU the pyramid's fixed-shape
+  propagation is captured once and replayed with one launch.
+- **Compiled CUDA executor for integer-FFT Shack-Hartmann grids**, which
+  previously ran the array path. Results agree to float rounding.
+- End-to-end frames/s on an Ampere Neoverse-N1 (12 cores) and an RTX 4060,
+  2.0.0 -> now: SH 20x20 float32 CPU 38.5 -> 126.1 (3.3x), GPU 496 -> 813
+  (1.6x); SH 60x60 float64 CPU 10.4 -> 29.8 (2.9x), GPU 199 -> 640 (3.2x);
+  nine-sample SH CPU 52.0 -> 96.3 (1.9x), GPU 189 -> 764 (4.1x); pyramid 40
+  CPU 923 -> 1,101 (1.2x), GPU 397 -> 759 (1.9x); pyramid 60 mod-8 CPU 173 ->
+  272 (1.6x), GPU 408 -> 762 (1.9x); pyramid 80 mod-32 float64 CPU 11.4 ->
+  20.9 (1.8x), GPU 204 -> 277 (1.4x). See `docs/performance.md`.
+
+### Fixed
+
+- **Compiled CUDA Shack-Hartmann executor misread float32 rotated or offset
+  lenslet grids.** Such grids resample the OPD in float32, but the kernel read
+  it as float64, so the GPU spot pattern was wrong (82-96% error). The OPD is
+  now widened (exactly) before the launch.
+- **Compiled CUDA Shack-Hartmann executor failed to launch for large
+  lenslet sampling** (e.g. 32x32 samples, 1024 threads) when register use left
+  fewer threads per block. Such geometries now fall back to the array path.
+
+- **Benchmark artifacts named the wrong GPU on multi-GPU hosts.**
+  `benchmarks/run.py` recorded the first line of `nvidia-smi`, which ignores
+  `CUDA_VISIBLE_DEVICES`. It now asks CuPy for the device the run used. On
+  Arm hosts, whose `/proc/cpuinfo` has no model name, it reads the CPU model
+  from `lscpu` (e.g. `Neoverse-N1`) instead of reporting `aarch64`.
+
+### Added
+
+- **Arm benchmark data point** (`benchmarks/device-results-neoverse-n1.*`): the
+  device table on an Ampere Neoverse-N1 host (16 pinned cores) with an RTX
+  4060 and an RTX A400.
+
 ## [2.0.0] - 2026-10-07
 
 ### Breaking

{makewfs-2.0.0 → makewfs-2.1.0}/CITATION.cff

@@ -5,7 +5,7 @@ type: software
 authors:
   - family-names: Taylor
     given-names: Jacob
-version: 2.0.0
+version: 2.1.0
 date-released: 2026-10-07
 license: MIT
 repository-code: "https://github.com/jacotay7/makewfs"

{makewfs-2.0.0 → makewfs-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: makewfs
-Version: 2.0.0
+Version: 2.1.0
 Summary: Configuration-driven adaptive-optics wavefront sensor image simulation.
 Project-URL: Homepage, https://github.com/jacotay7/makewfs
 Project-URL: Documentation, https://jacotay7.github.io/makewfs/
@@ -137,9 +137,9 @@ LGS is monochromatic at the 589 nm D2 line, broadened by only ~0.003 nm, so its
 spectral axis exists there purely to exercise the polychromatic path. The
 showcase clip above instead runs a physically correct narrowband beacon sampled
 across the sodium layer's depth, which is where spot elongation actually comes
-from. Compatible sampled-DFT Shack–Hartmann geometries are compiled
-on first use, so warm each fixed sensor before measuring or entering a real-time
-loop. Reproduce the table with
+from. On a GPU, compatible Shack–Hartmann geometries are compiled and
+pyramid frames are captured as a CUDA graph on first use, so warm each fixed
+sensor before measuring or entering a real-time loop. Reproduce the table with
 
 ```bash
 python benchmarks/run.py --device both --frames 100 \

{makewfs-2.0.0 → makewfs-2.1.0}/README.md

@@ -88,9 +88,9 @@ LGS is monochromatic at the 589 nm D2 line, broadened by only ~0.003 nm, so its
 spectral axis exists there purely to exercise the polychromatic path. The
 showcase clip above instead runs a physically correct narrowband beacon sampled
 across the sodium layer's depth, which is where spot elongation actually comes
-from. Compatible sampled-DFT Shack–Hartmann geometries are compiled
-on first use, so warm each fixed sensor before measuring or entering a real-time
-loop. Reproduce the table with
+from. On a GPU, compatible Shack–Hartmann geometries are compiled and
+pyramid frames are captured as a CUDA graph on first use, so warm each fixed
+sensor before measuring or entering a real-time loop. Reproduce the table with
 
 ```bash
 python benchmarks/run.py --device both --frames 100 \

makewfs-2.1.0/benchmarks/device-results-neoverse-n1-rtx4060.json

@@ -0,0 +1,357 @@
+{
+  "schema_version": 2,
+  "generated_at_utc": "2026-10-07T07:11:47.632479+00:00",
+  "command": "/home/jtaylor/miniforge3/envs/aosim-bench/bin/python benchmarks/run.py --device both --frames 100 --config benchmarks/configs/pyramid_40_float32.toml --config benchmarks/configs/pyramid_60_mod8_float32.toml --config benchmarks/configs/pyramid_80_mod32_float64.toml --config benchmarks/configs/shack_hartmann_20x20_float32.toml --config benchmarks/configs/shack_hartmann_60x60_float64.toml --config benchmarks/configs/shack_hartmann_quadrature_9sample.toml --output /home/jtaylor/aosim-bench-logs/artifacts/makewfs-device-table-rtx4060.json",
+  "revision": "74b53697569dc8b2b5ce93f0b66e39a1de3b303d",
+  "source_dirty": true,
+  "python": "3.13.15 | packaged by conda-forge | (main, Sep  2 2026, 22:02:03) [GCC 15.3.0]",
+  "platform": "Linux-6.17.9-76061709-generic-aarch64-with-glibc2.39",
+  "processor": "aarch64",
+  "cpu": "Neoverse-N1",
+  "gpu": "NVIDIA GeForce RTX 4060",
+  "dependencies": {
+    "makewfs": "2.0.0",
+    "numpy": "2.5.3",
+    "scipy": "1.18.1",
+    "cupy": "14.2.0",
+    "getframes": "2.4.0",
+    "pyturb": "2.2.0"
+  },
+  "methodology": {
+    "frames_per_cell": 100,
+    "persistent_sensor": true,
+    "warmup_frames": 1,
+    "device_resident_opd_rate_and_output": true,
+    "include_detector_truth": true,
+    "rng": "a distinct deterministic per-frame seed",
+    "cuda_synchronization": "before and after each timed region",
+    "construction_included_in_throughput": false,
+    "host_transfers_included": false
+  },
+  "results": [
+    {
+      "config": "benchmarks/configs/pyramid_40_float32.toml",
+      "sensor": "pyramid",
+      "device": "cpu",
+      "shape": [
+        54,
+        54
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.7629785779863596,
+      "warm_optical_total_s": 0.06306239901459776,
+      "warm_optical_frame_s": 0.0006306239901459775,
+      "warm_detector_total_s": 0.10588375400402583,
+      "warm_detector_frame_s": 0.0010588375400402584,
+      "warm_optical_frames_per_s": 1585.7309833210102,
+      "warm_detector_frames_per_s": 944.4319474751327,
+      "warm_detector_only_frame_s": 0.00022277187992585822,
+      "warm_detector_only_frames_per_s": 4488.896894584786,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/pyramid_40_float32.toml",
+      "sensor": "pyramid",
+      "device": "gpu",
+      "shape": [
+        54,
+        54
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.2768877709750086,
+      "warm_optical_total_s": 0.13808018100098707,
+      "warm_optical_frame_s": 0.0013808018100098707,
+      "warm_detector_total_s": 0.24444962001871318,
+      "warm_detector_frame_s": 0.0024444962001871316,
+      "warm_optical_frames_per_s": 724.2168953941706,
+      "warm_detector_frames_per_s": 409.08224767273015,
+      "warm_detector_only_frame_s": 0.0006185778399230912,
+      "warm_detector_only_frames_per_s": 1616.6114197112713,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/pyramid_60_mod8_float32.toml",
+      "sensor": "pyramid",
+      "device": "cpu",
+      "shape": [
+        80,
+        80
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 8,
+      "modulation_radius_lambda_over_d": 2.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.07376596701215021,
+      "warm_optical_total_s": 0.5042883460118901,
+      "warm_optical_frame_s": 0.005042883460118901,
+      "warm_detector_total_s": 0.5606069839850534,
+      "warm_detector_frame_s": 0.005606069839850534,
+      "warm_optical_frames_per_s": 198.29924841777367,
+      "warm_detector_frames_per_s": 178.37808457032378,
+      "warm_detector_only_frame_s": 0.00035893032007152216,
+      "warm_detector_only_frames_per_s": 2786.056078518904,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/pyramid_60_mod8_float32.toml",
+      "sensor": "pyramid",
+      "device": "gpu",
+      "shape": [
+        80,
+        80
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 8,
+      "modulation_radius_lambda_over_d": 2.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.012662593013374135,
+      "warm_optical_total_s": 0.1342540149926208,
+      "warm_optical_frame_s": 0.0013425401499262079,
+      "warm_detector_total_s": 0.2391750770038925,
+      "warm_detector_frame_s": 0.002391750770038925,
+      "warm_optical_frames_per_s": 744.8566808634844,
+      "warm_detector_frames_per_s": 418.10376420772525,
+      "warm_detector_only_frame_s": 0.0006130585700157099,
+      "warm_detector_only_frames_per_s": 1631.1655181239448,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/pyramid_80_mod32_float64.toml",
+      "sensor": "pyramid",
+      "device": "cpu",
+      "shape": [
+        108,
+        108
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 32,
+      "modulation_radius_lambda_over_d": 3.0,
+      "dtype": "float64",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.08048216797760688,
+      "warm_optical_total_s": 8.533555491012521,
+      "warm_optical_frame_s": 0.0853355549101252,
+      "warm_detector_total_s": 8.6366516520211,
+      "warm_detector_frame_s": 0.086366516520211,
+      "warm_optical_frames_per_s": 11.718444920797582,
+      "warm_detector_frames_per_s": 11.578561232882254,
+      "warm_detector_only_frame_s": 0.0006370968700502999,
+      "warm_detector_only_frames_per_s": 1569.620017001572,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/pyramid_80_mod32_float64.toml",
+      "sensor": "pyramid",
+      "device": "gpu",
+      "shape": [
+        108,
+        108
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 32,
+      "modulation_radius_lambda_over_d": 3.0,
+      "dtype": "float64",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.025755188980838284,
+      "warm_optical_total_s": 0.4056679999921471,
+      "warm_optical_frame_s": 0.004056679999921471,
+      "warm_detector_total_s": 0.4848081910167821,
+      "warm_detector_frame_s": 0.004848081910167821,
+      "warm_optical_frames_per_s": 246.50699587331462,
+      "warm_detector_frames_per_s": 206.26714204285878,
+      "warm_detector_only_frame_s": 0.0005712536702048964,
+      "warm_detector_only_frames_per_s": 1750.5357989933289,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_20x20_float32.toml",
+      "sensor": "shack_hartmann",
+      "device": "cpu",
+      "shape": [
+        160,
+        160
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.08199134599999525,
+      "warm_optical_total_s": 2.28855264998856,
+      "warm_optical_frame_s": 0.0228855264998856,
+      "warm_detector_total_s": 2.4490860599908046,
+      "warm_detector_frame_s": 0.024490860599908047,
+      "warm_optical_frames_per_s": 43.695739313884644,
+      "warm_detector_frames_per_s": 40.831558201909594,
+      "warm_detector_only_frame_s": 0.0010764133499469608,
+      "warm_detector_only_frames_per_s": 929.0111461821558,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_20x20_float32.toml",
+      "sensor": "shack_hartmann",
+      "device": "gpu",
+      "shape": [
+        160,
+        160
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.01180534201557748,
+      "warm_optical_total_s": 0.08716972899856046,
+      "warm_optical_frame_s": 0.0008716972899856046,
+      "warm_detector_total_s": 0.19479694298934191,
+      "warm_detector_frame_s": 0.0019479694298934192,
+      "warm_optical_frames_per_s": 1147.187230576929,
+      "warm_detector_frames_per_s": 513.3550787060933,
+      "warm_detector_only_frame_s": 0.0006126053698244505,
+      "warm_detector_only_frames_per_s": 1632.372240365053,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_60x60_float64.toml",
+      "sensor": "shack_hartmann",
+      "device": "cpu",
+      "shape": [
+        360,
+        360
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float64",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.08440429499023594,
+      "warm_optical_total_s": 8.684691948990803,
+      "warm_optical_frame_s": 0.08684691948990803,
+      "warm_detector_total_s": 9.488772381999297,
+      "warm_detector_frame_s": 0.09488772381999297,
+      "warm_optical_frames_per_s": 11.514513190260066,
+      "warm_detector_frames_per_s": 10.538771083781636,
+      "warm_detector_only_frame_s": 0.005910381099965889,
+      "warm_detector_only_frames_per_s": 169.19382745146018,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_60x60_float64.toml",
+      "sensor": "shack_hartmann",
+      "device": "gpu",
+      "shape": [
+        360,
+        360
+      ],
+      "source_states": 1,
+      "wavelength_samples": 1,
+      "range_samples": 1,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float64",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.026143675000639632,
+      "warm_optical_total_s": 0.4227883660059888,
+      "warm_optical_frame_s": 0.004227883660059888,
+      "warm_detector_total_s": 0.4985939179896377,
+      "warm_detector_frame_s": 0.004985939179896377,
+      "warm_optical_frames_per_s": 236.52495678791573,
+      "warm_detector_frames_per_s": 200.5640189178527,
+      "warm_detector_only_frame_s": 0.0005747833198984153,
+      "warm_detector_only_frames_per_s": 1739.7860469867767,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_quadrature_9sample.toml",
+      "sensor": "shack_hartmann",
+      "device": "cpu",
+      "shape": [
+        64,
+        64
+      ],
+      "source_states": 9,
+      "wavelength_samples": 3,
+      "range_samples": 3,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.06993808099650778,
+      "warm_optical_total_s": 1.8203168570180424,
+      "warm_optical_frame_s": 0.018203168570180422,
+      "warm_detector_total_s": 1.8593171660031658,
+      "warm_detector_frame_s": 0.018593171660031656,
+      "warm_optical_frames_per_s": 54.93549082647914,
+      "warm_detector_frames_per_s": 53.78318547715153,
+      "warm_detector_only_frame_s": 0.00024450053984764964,
+      "warm_detector_only_frames_per_s": 4089.9705195870265,
+      "python_peak_memory_mib": null
+    },
+    {
+      "config": "benchmarks/configs/shack_hartmann_quadrature_9sample.toml",
+      "sensor": "shack_hartmann",
+      "device": "gpu",
+      "shape": [
+        64,
+        64
+      ],
+      "source_states": 9,
+      "wavelength_samples": 3,
+      "range_samples": 3,
+      "modulation_samples": 1,
+      "modulation_radius_lambda_over_d": 0.0,
+      "dtype": "float32",
+      "fft_workers": 1,
+      "frames": 100,
+      "construction_s": 0.014552935026586056,
+      "warm_optical_total_s": 0.4028777669882402,
+      "warm_optical_frame_s": 0.004028777669882402,
+      "warm_detector_total_s": 0.5134580160083715,
+      "warm_detector_frame_s": 0.005134580160083715,
+      "warm_optical_frames_per_s": 248.2142431128967,
+      "warm_detector_frames_per_s": 194.75789038683465,
+      "warm_detector_only_frame_s": 0.0006140789898927323,
+      "warm_detector_only_frames_per_s": 1628.4549975804912,
+      "python_peak_memory_mib": null
+    }
+  ]
+}