makewfs 1.2.0__tar.gz → 2.0.0__tar.gz

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

@@ -87,6 +87,16 @@ write a failing integration test/design note, use the conditional gates in
 - Intensities, not fields, are summed over incoherent wavelengths, modulation
   points, finite-source samples, and sodium slices.
 - Cropping reports lost flux; it does not renormalize it away.
+- Wavefront metrics follow aocore CONVENTIONS 4.1. Frame metadata
+  `wfs_input_opd_rms_m` is the pupil-intensity-weighted, piston-removed RMS of
+  the input OPD on the input grid (weights from `WavefrontSensor._rms_weights`:
+  the analytic pupil evaluated on `input.shape`, or a custom mask area-averaged
+  from the engine's `configured_pupil`); `wfs_input_opd_rms_unweighted_m` is the
+  whole-grid quadratic mean with piston kept. Both are reduced on the device and
+  cross in the one `backend.scalars` batch, so do not swap in `aocore.rms` or
+  `aocore.rms_unweighted` there: they return host floats and would add a
+  synchronization each. Any other RMS-like key must say its variant in its
+  name (`_unweighted`, `_tiptilt_removed`).
 - The intended top-level API is `load_config`, `WavefrontSensor`, and `simulate`.
   Keep other implementation objects out of `makewfs.__init__` unless an API review
   explicitly accepts them.
@@ -153,8 +163,13 @@ Follow the target layout in `ROADMAP.md`:
   rotation and rectangular grids on the selected backend, none of which
   `aocore.Pupil` models. `backend.ArrayBackend` takes a dtype per array, explicit
   FFT workers and `ndimage` helpers, which `aocore.Backend` does not, and its
-  centred FFTs keep the `fftshift` convention. `sampling.block_sum` wraps
-  `aocore.block_sum` but keeps its own factor-two fast path.
+  centred FFTs keep the `fftshift` convention; `ArrayBackend.centered_coordinates`
+  builds aocore's coordinates directly on the device. `sampling.block_sum` is a
+  thin wrapper over `aocore.block_sum` (no local fast path since aocore 0.1.3,
+  which measured at least as fast at the SH call sites).
+  `sampling.area_rebin` is exact-overlap area averaging between grids of the
+  same extent and any shape ratio, which `aocore.block_sum` (integer factors
+  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

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

@@ -4,6 +4,65 @@ All notable changes to `makewfs` are documented here.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-07
+
+### Breaking
+
+- **`wfs_input_opd_rms_m` is now the pupil-weighted, piston-removed RMS.**
+  It follows aocore CONVENTIONS.md 4.1: the RMS of the input OPD in metres,
+  weighted by the intensity of the pupil the optics use and with the
+  intensity-weighted mean (piston) removed. Before 2.0 it was the quadratic
+  mean over the whole input grid, with every pixel counted equally, pixels
+  outside the pupil included and piston kept. For the same wavefront the new
+  value is usually smaller; a pure piston now reports 0. The weights are the
+  configured pupil's intensity (the amplitude the engines use, squared) on the
+  input grid: an analytic pupil is evaluated on `input.shape` with the
+  configured `numerics.pupil_supersampling`, the same map
+  `WavefrontSensor.pupil_illumination()` returns; a custom mask, which exists
+  only on the engine's pupil grid, is area-averaged onto the input grid.
+  Phase input is converted to OPD first, and `expose_integrated` reports the
+  RMS of the mean OPD, as before. The value is still reduced on the device and
+  crosses to the host in the same single batched transfer as the captured
+  photon rate. A pupil with no transmission on the input grid is now rejected
+  when the sensor is built.
+- **`makewfs.provenance.metadata`**, an internal helper, takes the two
+  reduced RMS values as required `opd_rms_m` and `opd_rms_unweighted_m`
+  arguments and no longer accepts `opd_m`.
+
+See "Migrating to 2.0" in the stability guide.
+
+### Added
+
+- **`wfs_input_opd_rms_unweighted_m`** frame metadata keeps the 1.x quantity,
+  the unweighted RMS over the whole input grid with piston included, so no
+  information is lost. Read it wherever the old number is still wanted.
+- Both sensor engines expose `configured_pupil`, the pupil amplitude on their
+  own pupil grid, and `makewfs.sampling.area_rebin` area-averages a map onto
+  another grid of the same extent, for any shape ratio.
+
+### Changed
+
+- The `closed_loop_injection.py` and `showcase.py` examples take the residual
+  RMS they plot from each frame's `wfs_input_opd_rms_m` instead of a
+  whole-grid `np.std`, so the numbers they print are pupil-weighted. The
+  checked-in `makewfs_showcase.webp` was not regenerated.
+- **Requires `aocore>=0.1.3,<0.2`.** `makewfs.sampling.block_sum` drops its
+  own factor-two shortcut and delegates every factor to `aocore.block_sum`,
+  whose strided CPU adds and single CuPy kernel measured at least as fast on
+  the spot stacks the Shack-Hartmann actually bins (for example
+  `(400, 16, 16)` float32: CPU 112 vs 173 us, Quadro P620 65 vs 94 us;
+  `(3600, 12, 12)` float64: CPU 0.90 vs 1.27 ms, GPU 98 vs 173 us). The
+  additions happen in a different order, so Shack-Hartmann float32 images
+  differ from 1.2.0 by float32 rounding (at most about 1e-7 relative) and
+  float64 ones by about 2e-16; pyramid images are bit-for-bit unchanged.
+  Pixel-centre coordinates for the input, pupil and DFT detector grids are
+  now built on the selected device by `aocore.centered_coordinates`
+  (`ArrayBackend.centered_coordinates`), with identical values.
+- The input-RMS tests check the unweighted key against
+  `aocore.rms_unweighted`. The per-frame path keeps its own device reduction,
+  because the aocore functions return host floats and would each add a
+  synchronization.
+
 ## [1.2.0] - 2026-10-07
 
 - **Fixed: phase input was reported as metres.** With

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: makewfs
-Version: 1.2.0
+Version: 2.0.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/
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: aocore<0.2,>=0.1.2
+Requires-Dist: aocore<0.2,>=0.1.3
 Requires-Dist: getframes>=2.2.0
 Requires-Dist: numpy>=1.23
 Requires-Dist: scipy>=1.10

makewfs-2.0.0/docs/concepts.md

@@ -0,0 +1,67 @@
+# Concepts and conventions
+
+## Wavefront units
+
+OPD is the canonical internal quantity and is measured in metres. A phase input
+must declare `quantity = "phase"`, `unit = "rad"`, and
+`reference_wavelength_m`; it is converted to OPD before propagation. Units are
+never inferred from array magnitude.
+
+The input array uses `(y, x)` order. Its physical extent and shape come from the
+`[input]` table. The pupil amplitude is configured separately, so a per-frame
+input contains only the phase/OPD map.
+
+## Image domains
+
+The optical engines are deterministic and return an incident photon-rate map in
+photons/s/native detector pixel. `getframes.Camera.expose()` performs the
+scalar photon-to-electron-to-ADU chain, while the optional
+`Camera.expose_spectral()` path applies wavelength-dependent QE exactly once
+and preserves the incident cube in detector truth. Optical intensities are
+summed over incoherent wavelength, source, modulation, and sodium-range samples;
+complex fields are never added across incoherent states.
+
+## Piston and sampling
+
+A constant piston changes only the global complex phase and therefore cannot
+change intensity. The numerical implementation removes the weighted global
+piston before evaluating the complex exponential to keep this invariant stable
+in single precision.
+
+When an input grid does not divide into the configured lenslets, OPD is
+resampled on physical coordinates. Wrapped phase is never interpolated.
+
+## Input wavefront RMS in frame metadata
+
+Every frame records two RMS values of the input wavefront, both in OPD metres
+(phase input is converted at `input.reference_wavelength_m` first). Both
+describe the input array as given, without `input.static_opd_path`; for
+`expose_integrated` they describe the mean of the temporal samples.
+
+| Key | Definition |
+| --- | --- |
+| `wfs_input_opd_rms_m` | Pupil-weighted, piston-removed RMS, the `rms` of aocore CONVENTIONS 4.1: `sqrt(sum a^2 (opd - <opd>_a)^2 / sum a^2)`, where `<opd>_a` is the intensity-weighted mean. |
+| `wfs_input_opd_rms_unweighted_m` | `sqrt(mean(opd^2))` over every pixel of the input grid, with piston included and pixels outside the pupil counted. This was `wfs_input_opd_rms_m` before 2.0. |
+
+The weight `a^2` is the intensity of the pupil the optics use, on the input
+grid. The engines use the configured pupil as a field amplitude, so the
+intensity is its square. An analytic pupil (diameter, obscuration, spiders,
+segment gaps, rotation) is evaluated on `input.shape` with the same
+`numerics.pupil_supersampling`; this is the map
+`WavefrontSensor.pupil_illumination()` returns, computed in float64. A
+`telescope.custom_mask_path` mask exists only on the engine's own pupil grid
+(`lenslets_across_pupil` times the pupil samples per lenslet for a
+Shack-Hartmann, `pixels_across_pupil` for a pyramid), so its intensity is
+area-averaged onto the input grid: each input
+pixel takes the mean over the mask cells it overlaps, which is exact when the
+two shapes match. A piston, or OPD outside the pupil, therefore changes only
+the unweighted value.
+
+Both values are reduced on the selected device and cross to the host together
+with the captured photon rate in one transfer.
+
+## Closed-loop use
+
+The package intentionally stops at the detector image. A downstream controller
+may turn that image into slopes, a reconstruction, and a deformable-mirror
+command, then feed the resulting residual OPD back into `expose()`.

{makewfs-1.2.0 → makewfs-2.0.0}/docs/stability.md

@@ -25,3 +25,20 @@ The physical per-frame contract is a wavefront array plus configuration (and an
 optional detector seed). `out` controls storage lifetime only and cannot change
 the simulated result. Atmosphere, reconstruction, controllers, and detector
 physics remain outside the package boundary.
+
+## Migrating to 2.0
+
+makewfs 2.0 changes the meaning of one frame-metadata key; the API and the
+configuration schema are unchanged.
+
+- `wfs_input_opd_rms_m` is now the pupil-weighted, piston-removed RMS of
+  aocore CONVENTIONS 4.1 (see
+  [Concepts](concepts.md#input-wavefront-rms-in-frame-metadata)). For the same
+  wavefront it is usually smaller than before: it no longer includes piston or
+  any OPD outside the pupil.
+- The old quantity, the unweighted RMS over the whole input grid with piston
+  included, is still recorded as `wfs_input_opd_rms_unweighted_m`. Code that
+  needs the 1.x number reads that key instead.
+- `makewfs.provenance.metadata`, an internal helper, now takes both RMS values
+  as required `opd_rms_m` and `opd_rms_unweighted_m` arguments and no longer
+  accepts `opd_m`.

{makewfs-1.2.0 → makewfs-2.0.0}/examples/closed_loop_injection.py

@@ -5,7 +5,9 @@ external AO loop that measures the frame, estimates a correction, and hands the
 next *residual* wavefront back to ``WavefrontSensor.expose``. The residual is a
 low-order aberration (defocus + astigmatism) so the Shack-Hartmann spots shift
 differently across the pupil and the relaxation toward the flat reference is
-visible, and a convergence panel tracks the residual RMS.
+visible, and a convergence panel tracks the residual RMS that each frame
+records in its ``wfs_input_opd_rms_m`` metadata: pupil-weighted with piston
+removed, as aocore CONVENTIONS 4.1 defines ``rms``.
 """
 
 from __future__ import annotations
@@ -19,7 +21,7 @@ import makewfs
 
 
 def _low_order_residual(shape: tuple[int, int], amplitude_m: float) -> np.ndarray:
-    """Return a defocus + astigmatism OPD normalized to ``amplitude_m`` RMS."""
+    """Return a defocus + astigmatism OPD with ``amplitude_m`` RMS over the grid."""
     yy, xx = np.mgrid[: shape[0], : shape[1]]
     x = (xx - (shape[1] - 1) / 2) / (shape[1] / 2)
     y = (yy - (shape[0] - 1) / 2) / (shape[0] / 2)
@@ -56,8 +58,9 @@ def main() -> None:
     residual_rms_nm: list[float] = []
     for step in range(args.steps):
         residual = _low_order_residual(shape, amplitude_m=200e-9) * (0.6**step)
-        residual_rms_nm.append(float(np.std(residual) * 1e9))
-        frames.append(np.asarray(sensor.expose(residual, seed=0)).astype(np.float64))
+        frame = sensor.expose(residual, seed=0)
+        residual_rms_nm.append(frame.metadata["wfs_input_opd_rms_m"] * 1e9)
+        frames.append(np.asarray(frame).astype(np.float64))
 
     columns = min(4, args.steps)
     shown = sorted({0, 1, args.steps // 2, args.steps - 1})[:columns]
@@ -91,7 +94,7 @@ def main() -> None:
     convergence.plot(range(args.steps), residual_rms_nm, "o-")
     convergence.set_title("external loop convergence")
     convergence.set_xlabel("loop step")
-    convergence.set_ylabel("residual OPD RMS (nm)")
+    convergence.set_ylabel("residual OPD RMS over the pupil (nm)")
     convergence.grid(True, alpha=0.3)
 
     frame_rms = [float(np.sqrt(np.mean(diff**2))) for diff in diffs]

{makewfs-1.2.0 → makewfs-2.0.0}/examples/showcase.py

@@ -263,7 +263,6 @@ def benchmark_panel(panel: Panel, sync: Callable[[], None]) -> float:
 def collect_frames(panel: Panel) -> np.ndarray:
     """``(N_FRAMES, *output_shape)`` detector ADU on the host, plus the OPD rms."""
     import getframes
-    import pyturb
 
     sensor = panel.build_sensor()
     atmosphere = panel.build_atmosphere()
@@ -271,8 +270,10 @@ def collect_frames(panel: Panel) -> np.ndarray:
     rms = []
     for index in range(N_FRAMES):
         residual = panel.residual(atmosphere, index)
-        rms.append(float(np.std(pyturb.to_numpy(residual))) * 1e9)
         frame = sensor.expose(residual, seed=index)
+        # Pupil-weighted, piston-removed (aocore CONVENTIONS 4.1), reduced on
+        # the sensor's device.
+        rms.append(frame.metadata["wfs_input_opd_rms_m"] * 1e9)
         out[index] = getframes.to_numpy(frame.data).astype(np.float32)
     panel.badge_extra = f"residual {np.mean(rms):.0f} nm rms"
     return np.clip(out - panel.bias_adu, 0.0, None)

{makewfs-1.2.0 → makewfs-2.0.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "aocore>=0.1.2,<0.2",
+    "aocore>=0.1.3,<0.2",
     "numpy>=1.23",
     "scipy>=1.10",
     "getframes>=2.2.0",

{makewfs-1.2.0 → makewfs-2.0.0}/src/makewfs/__about__.py

@@ -1,3 +1,3 @@
 """Package version metadata."""
 
-__version__ = "1.2.0"
+__version__ = "2.0.0"

{makewfs-1.2.0 → makewfs-2.0.0}/src/makewfs/api.py

@@ -16,10 +16,11 @@ from .config import WFSConfig, load_config
 from .detector import DetectorAdapter
 from .provenance import metadata as build_metadata
 from .pupil import make_pupil
+from .sampling import area_rebin
 from .sensors.base import OpticalResult, SensorEngine
 from .sensors.pyramid import PyramidEngine
 from .sensors.shack_hartmann import ShackHartmannEngine
-from .wavefront import iter_phase_samples
+from .wavefront import grid_rms, iter_phase_samples, pupil_rms, pupil_weights
 
 
 class WavefrontSensor:
@@ -53,10 +54,12 @@ class WavefrontSensor:
             launched_rate=0.0,
             captured_rate=0.0,
             opd_rms_m=0.0,
+            opd_rms_unweighted_m=0.0,
             seed=None,
             source_states=self.engine.source_states,
             file_digests=self.engine.file_digests,
         )
+        self._rms_weights = pupil_weights(self._input_pupil_intensity(), backend=self.backend)
 
     @classmethod
     def from_toml(cls, path: str | Path) -> WavefrontSensor:
@@ -66,9 +69,42 @@ class WavefrontSensor:
     def _render(self, wavefront: ArrayLike) -> OpticalResult:
         return self.engine.render(cast(NDArray[np.float64], wavefront))
 
-    def _opd_rms(self, opd: Any) -> Any:
-        """Reduce OPD RMS on-device before the batched metadata crossing."""
-        return self.backend.sqrt(self.backend.mean(opd**2))
+    def _input_pupil_intensity(self) -> Any:
+        """Return the pupil intensity the optics use, on the input grid.
+
+        An analytic pupil is evaluated on ``input.shape`` from the same
+        telescope model and ``numerics.pupil_supersampling`` the engine uses on
+        its own grid, as :meth:`pupil_illumination` does; both grids span
+        ``input.grid_extent_m``. A custom mask exists only on the engine's
+        configured pupil grid, so its intensity is area-averaged from there
+        onto the input grid, which is exact when the two shapes match. The
+        engines use the pupil as a field amplitude, so the intensity is its
+        square.
+        """
+        if self.config.telescope.custom_mask_path is None:
+            amplitude = make_pupil(
+                self.config.telescope,
+                self.config.input.shape,
+                self.config.input.grid_extent_m,
+                supersampling=self.config.numerics.pupil_supersampling,
+                backend=self.backend,
+                dtype=np.float64,
+            )
+            return amplitude * amplitude
+        amplitude = self.backend.asarray(self.engine.configured_pupil, dtype=np.float64)
+        return area_rebin(amplitude * amplitude, self.config.input.shape, backend=self.backend)
+
+    def _opd_rms(self, opd: Any) -> tuple[Any, Any]:
+        """Reduce both input-OPD RMS values on the device.
+
+        Returns the pupil-weighted, piston-removed RMS and the unweighted
+        whole-grid RMS as device scalars, for the one batched metadata
+        crossing in ``backend.scalars``.
+        """
+        return (
+            pupil_rms(opd, self._rms_weights, backend=self.backend),
+            grid_rms(opd, backend=self.backend),
+        )
 
     def _frame_metadata(
         self,
@@ -76,6 +112,7 @@ class WavefrontSensor:
         launched_rate: float,
         captured_rate: float,
         opd_rms_m: float,
+        opd_rms_unweighted_m: float,
         seed: int | None,
     ) -> dict[str, Any]:
         """Copy cached static provenance and fill the per-frame values."""
@@ -85,6 +122,7 @@ class WavefrontSensor:
                 "wfs_launched_photons_s": float(launched_rate),
                 "wfs_captured_photons_s": float(captured_rate),
                 "wfs_input_opd_rms_m": float(opd_rms_m),
+                "wfs_input_opd_rms_unweighted_m": float(opd_rms_unweighted_m),
                 "wfs_seed": seed if seed is not None else "internal",
             }
         )
@@ -182,18 +220,26 @@ class WavefrontSensor:
         seed: int | None = None,
         out: Any | None = None,
     ) -> Any:
-        """Render one wavefront into optional caller-owned detector storage."""
+        """Render one wavefront into optional caller-owned detector storage.
+
+        Besides provenance and timings, the frame metadata records the input
+        wavefront's ``wfs_input_opd_rms_m``, its RMS in OPD metres weighted by
+        the pupil intensity with piston removed (aocore CONVENTIONS 4.1), and
+        ``wfs_input_opd_rms_unweighted_m``, its RMS over the whole input grid
+        with piston kept.
+        """
         total_start = perf_counter()
         optical_start = total_start
         result = self._render(wavefront)
-        captured_rate, opd_rms = self.backend.scalars(
-            result.captured_rate_per_s, self._opd_rms(result.opd_m)
+        captured_rate, opd_rms, opd_rms_unweighted = self.backend.scalars(
+            result.captured_rate_per_s, *self._opd_rms(result.opd_m)
         )
         optical_elapsed = perf_counter() - optical_start
         frame_metadata = self._frame_metadata(
             launched_rate=result.launched_rate_per_s,
             captured_rate=captured_rate,
             opd_rms_m=opd_rms,
+            opd_rms_unweighted_m=opd_rms_unweighted,
             seed=seed,
         )
         detector_start = perf_counter()
@@ -244,13 +290,14 @@ class WavefrontSensor:
             if not samples:
                 raise ValueError("phase_samples must contain at least one sample")
             result = batched(samples)
-            captured_rate, opd_rms = self.backend.scalars(
-                result.captured_rate_per_s, self._opd_rms(result.opd_m)
+            captured_rate, opd_rms, opd_rms_unweighted = self.backend.scalars(
+                result.captured_rate_per_s, *self._opd_rms(result.opd_m)
             )
             frame_metadata = self._frame_metadata(
                 launched_rate=result.launched_rate_per_s,
                 captured_rate=captured_rate,
                 opd_rms_m=opd_rms,
+                opd_rms_unweighted_m=opd_rms_unweighted,
                 seed=seed,
             )
             frame_metadata["wfs_temporal_samples"] = len(samples)
@@ -305,13 +352,14 @@ class WavefrontSensor:
             None if spectral_rate_sum is None else spectral_rate_sum / sample_count
         )
         average_opd = opd_sum / sample_count
-        captured_rate, opd_rms = self.backend.scalars(
-            captured / sample_count, self._opd_rms(average_opd)
+        captured_rate, opd_rms, opd_rms_unweighted = self.backend.scalars(
+            captured / sample_count, *self._opd_rms(average_opd)
         )
         frame_metadata = self._frame_metadata(
             launched_rate=launched,
             captured_rate=captured_rate,
             opd_rms_m=opd_rms,
+            opd_rms_unweighted_m=opd_rms_unweighted,
             seed=seed,
         )
         frame_metadata["wfs_temporal_samples"] = sample_count

{makewfs-1.2.0 → makewfs-2.0.0}/src/makewfs/backend.py

@@ -21,6 +21,7 @@ from dataclasses import dataclass
 from typing import Any, cast
 
 import numpy as np
+from aocore import centered_coordinates as _aocore_centered_coordinates
 from numpy.typing import NDArray
 
 
@@ -48,6 +49,18 @@ class ArrayBackend:
         """Convert a value using this backend's array namespace."""
         return self.xp.asarray(value, dtype=dtype)
 
+    def centered_coordinates(self, n: int, *, dtype: Any) -> Any:
+        """Unit-pitch pixel-centre coordinates (CONVENTIONS 1.2) on this device.
+
+        ``aocore.centered_coordinates`` builds them in float64 and casts to
+        ``dtype`` directly on the GPU, so no host array is copied over. The
+        CPU path still passes through :meth:`asarray`, which keeps an injected
+        namespace in the loop.
+        """
+        if self.is_cpu:
+            return self.asarray(_aocore_centered_coordinates(n, dtype=dtype), dtype=dtype)
+        return _aocore_centered_coordinates(n, dtype=dtype, backend="gpu")
+
     def zeros(self, shape: Any, *, dtype: Any) -> Any:
         """Allocate a zero-filled array on this backend."""
         return self.xp.zeros(shape, dtype=dtype)

{makewfs-1.2.0 → makewfs-2.0.0}/src/makewfs/provenance.py

@@ -7,9 +7,6 @@ import importlib.metadata
 from pathlib import Path
 from typing import Any
 
-import numpy as np
-from numpy.typing import NDArray
-
 from .config import WFSConfig
 from .source import SourceState, iter_source_states
 
@@ -44,28 +41,24 @@ def referenced_file_digests(config: WFSConfig) -> dict[str, str]:
     }
 
 
-def _opd_rms(opd_m: NDArray[Any] | None, opd_rms_m: float | None) -> float:
-    """Resolve a host OPD RMS, accepting a backend-reduced value."""
-    if opd_rms_m is not None:
-        return float(opd_rms_m)
-    if opd_m is None:
-        raise ValueError("metadata requires opd_m or opd_rms_m")
-    return float(np.sqrt(np.mean(np.asarray(opd_m) ** 2)))
-
-
 def metadata(
     config: WFSConfig,
     *,
     sensor_kind: str,
     launched_rate: float,
     captured_rate: float,
-    opd_m: NDArray[Any] | None = None,
-    opd_rms_m: float | None = None,
+    opd_rms_m: float,
+    opd_rms_unweighted_m: float,
     seed: int | None,
     source_states: tuple[SourceState, ...] | None = None,
     file_digests: dict[str, str] | None = None,
 ) -> dict[str, Any]:
-    """Build serializable metadata for an ideal or detector frame."""
+    """Build serializable metadata for an ideal or detector frame.
+
+    ``opd_rms_m`` is the input OPD's pupil-weighted, piston-removed RMS and
+    ``opd_rms_unweighted_m`` its unweighted whole-grid RMS with piston
+    included, both already reduced by the caller (aocore CONVENTIONS 4.1).
+    """
     states = iter_source_states(config) if source_states is None else source_states
     result: dict[str, Any] = {
         "frame_type": "wfs",
@@ -74,7 +67,8 @@ def metadata(
         "wfs_wavelength_m": config.sensor.wavelength_m,
         "wfs_launched_photons_s": float(launched_rate),
         "wfs_captured_photons_s": float(captured_rate),
-        "wfs_input_opd_rms_m": _opd_rms(opd_m, opd_rms_m),
+        "wfs_input_opd_rms_m": float(opd_rms_m),
+        "wfs_input_opd_rms_unweighted_m": float(opd_rms_unweighted_m),
         "wfs_seed": seed if seed is not None else "internal",
         "wfs_source_kind": config.source.kind,
         "wfs_source_state_count": len(states),

{makewfs-1.2.0 → makewfs-2.0.0}/src/makewfs/sampling.py

@@ -9,7 +9,6 @@ from typing import Any, cast
 
 import numpy as np
 from aocore import block_sum as _aocore_block_sum
-from aocore import centered_coordinates
 from numpy.typing import NDArray
 
 from .backend import ArrayBackend, centered_fft_intensity, cpu_backend
@@ -147,9 +146,11 @@ def block_sum(
     """Sum square pixel blocks while preserving total flux.
 
     A thin wrapper over ``aocore.block_sum``, which owns flux-conserving
-    binning (CONVENTIONS 9). It keeps this module's error messages and a
-    factor-two fast path. ``backend`` is accepted for compatibility; the
-    reduction runs on the array's own namespace.
+    binning (CONVENTIONS 9); it keeps this module's error messages.
+    ``backend`` is accepted for compatibility; the reduction runs on the
+    array's own namespace. Since aocore 0.1.3 its strided CPU adds and
+    single-kernel CuPy path are at least as fast as the factor-two shortcut
+    this module used to keep, on the spot stacks the Shack-Hartmann bins.
     """
     if factor < 1:
         raise ValueError("factor must be positive")
@@ -158,20 +159,65 @@ def block_sum(
     height, width = array.shape[-2:]
     if height % factor or width % factor:
         raise ValueError(f"shape {array.shape[-2:]} is not divisible by factor {factor}")
-    if factor == 2:
-        # Two-times oversampling is the common SH path. Direct strided sums
-        # avoid NumPy's disproportionately expensive multi-axis reduction over
-        # thousands of tiny spot images and work unchanged with CuPy arrays.
-        return cast(
-            NDArray[Any],
-            array[..., 0::2, 0::2]
-            + array[..., 0::2, 1::2]
-            + array[..., 1::2, 0::2]
-            + array[..., 1::2, 1::2],
-        )
     return cast(NDArray[Any], _aocore_block_sum(array, factor))
 
 
+def _area_overlap(target: int, source: int, *, backend: ArrayBackend, dtype: Any) -> NDArray[Any]:
+    """Return the ``(target, source)`` fractions of each target cell's length.
+
+    Both grids tile the same interval. Edges are compared in integer units of
+    ``1 / (target * source)``, so the overlaps are exact and every row sums to
+    one.
+    """
+    rows = backend.arange(target)[:, None]
+    columns = backend.arange(source)[None, :]
+    upper = backend.where(
+        (rows + 1) * source < (columns + 1) * target,
+        (rows + 1) * source,
+        (columns + 1) * target,
+    )
+    lower = backend.where(rows * source > columns * target, rows * source, columns * target)
+    overlap = backend.where(upper > lower, upper - lower, 0)
+    return cast(NDArray[Any], backend.asarray(overlap, dtype=dtype) / source)
+
+
+def area_rebin(
+    array: NDArray[Any],
+    shape: tuple[int, int],
+    *,
+    backend: ArrayBackend | None = None,
+) -> NDArray[Any]:
+    """Area-average a map onto another grid spanning the same extent.
+
+    Each target pixel takes the mean of the source map over its own area,
+    weighting every source pixel by the exact fraction it overlaps, so any
+    integer or non-integer ratio, up or down, is handled without
+    interpolation. A uniform map stays uniform and the area integral of the map
+    is preserved. Equal shapes return the map unchanged.
+
+    Parameters
+    ----------
+    array
+        Two-dimensional ``(y, x)`` map on the source grid.
+    shape
+        Target ``(height, width)``.
+    backend
+        Array backend holding ``array``.
+
+    Returns
+    -------
+    numpy.ndarray or cupy.ndarray
+        The area-averaged map on the target grid, in ``array``'s dtype.
+    """
+    resolved = backend or cpu_backend()
+    height, width = array.shape
+    if (height, width) == tuple(shape):
+        return array
+    rows = _area_overlap(shape[0], height, backend=resolved, dtype=array.dtype)
+    columns = _area_overlap(shape[1], width, backend=resolved, dtype=array.dtype)
+    return cast(NDArray[Any], resolved.matmul(resolved.matmul(rows, array), columns.T))
+
+
 @dataclass
 class _SpotPropagationPlan:
     """Cached backend-resident geometry for repeated spot propagation.
@@ -250,8 +296,8 @@ class _SpotPropagationPlan:
                 coordinate = backend.arange(nfft, dtype=np.float64)
                 plan.half_sample = backend.exp(-1j * math.pi * coordinate / nfft)
         else:
-            detector_coordinate = backend.asarray(
-                centered_coordinates(high_resolution_pixels), dtype=np.float64
+            detector_coordinate = backend.centered_coordinates(
+                high_resolution_pixels, dtype=np.float64
             ) / (sampling * oversampling)
             pupil_coordinate = backend.arange(samples_per_lenslet, dtype=np.float64)
             kernel = backend.exp(
@@ -263,9 +309,7 @@ class _SpotPropagationPlan:
             )
             plan.dft_kernel = backend.astype(kernel, plan.field_dtype)
         if field_stop_radius_lambda_over_d is not None:
-            coordinates = backend.asarray(
-                centered_coordinates(high_resolution_pixels), dtype=np.float64
-            )
+            coordinates = backend.centered_coordinates(high_resolution_pixels, dtype=np.float64)
             y, x = backend.meshgrid(coordinates, coordinates, indexing="ij")
             radius_lambda_over_d = backend.hypot(x, y) / (oversampling * sampling)
             plan.field_stop_mask = radius_lambda_over_d <= field_stop_radius_lambda_over_d
@@ -439,6 +483,7 @@ def spot_intensity(
 
 
 __all__ = [
+    "area_rebin",
     "block_sum",
     "crop_center",
     "lenslet_field_upsampling",