solvephase 0.1.0__tar.gz

solvephase-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+site/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.ipynb_checkpoints/
+validation-artifacts/
+benchmark-smoke.json
+*.npz
+.vscode/
+.idea/
+example-output/
+solvephase-result.npz

solvephase-0.1.0/AGENTS.md

@@ -0,0 +1,216 @@
+# AGENTS.md
+
+Operating guide for AI agents (and humans) working in `solvephase`. Keep it
+accurate: update it in the same change that alters the layout, commands,
+contracts or conventions below, and add a Gotchas entry whenever something led
+you astray.
+
+## What this repository is
+
+`solvephase` is a phase-retrieval library: given intensity measurements, it
+recovers the phase (wavefront) that produced them. It covers
+
+- **focal-plane wavefront sensing** for adaptive optics and optical metrology:
+  Gerchberg-Saxton/Misell, nonlinear (gradient / Gauss-Newton) retrieval with
+  Gaussian, Poisson or amplitude likelihoods, phase diversity (point source
+  and extended object), LIFT, Fast & Furious;
+- **coherent diffraction imaging**: ER, HIO, DM, RAAR, RRR, ASR, HPR, OSS,
+  shrinkwrap, batched multi-start;
+- **generic measurement models**: Wirtinger flow family with spectral
+  initialization;
+- **transport of intensity** (TIE).
+
+It runs on NumPy/SciPy, or on CUDA through CuPy with the same code.
+
+The generic optics primitives (backend, propagators, pupils, metrics,
+unwrapping) and the cross-package conventions live in
+[`aocore`](https://github.com/jacotay7/aocore): change them there, not here,
+and keep `tests/test_conformance.py` passing (aocore CONVENTIONS.md).
+
+It belongs to an AO simulation family and reuses rather than copies it:
+[`aobasis`](https://github.com/jacotay7/aobasis) supplies modal bases (a core
+dependency); [`pyturb`](https://github.com/jacotay7/pyturb) (atmospheric OPD)
+and [`getframes`](https://github.com/jacotay7/getframes) (detector noise) are
+optional `interop` dependencies used for realistic data; HCIPy is an optional
+independent reference for validation only. Never hard-code a filesystem path
+to a sibling repository.
+
+## Layout
+
+```text
+src/solvephase/
+  backend.py        re-exports aocore.backend (Backend, get_backend, to_numpy, ...)
+  propagation.py    re-exports aocore.propagation (FFT/MFT/focal/angular-spectrum propagators)
+  pupil.py          re-exports aocore.pupil (Pupil)
+  basis.py          Basis: Zernike/KL/Fourier (via aobasis), zonal, segments, DM
+  focal.py          FocalPlaneModel: forward, vjp (reverse mode), jvp (forward mode)
+  losses.py         Gaussian, Poisson (deviance), amplitude losses with curvature
+  optimize.py       device-resident L-BFGS (strong Wolfe), Levenberg-Marquardt, Adam
+  retrieval.py      FocalPlaneProblem + solve(): the nonlinear focal-plane solver
+  unwrap.py         re-exports aocore.unwrap (unwrap_phase, wrap)
+  metrics.py        re-exports aocore.metrics (rms, wavefront_error, strehl_from_rms)
+  result.py         Result returned by every focal-plane solver
+  algorithms/       one module per algorithm family (gerchberg_saxton, cdi, ...)
+  api.py            retrieve(): the one-call high-level entry point
+tests/              pytest; mirrors the module names
+benchmarks/         speed suite (run.py), head-to-head baselines (compare.py), method
+                    comparison feeding docs/choosing.md (methods.py), JSON artifacts
+validation/         physics/statistics evidence (Cramer-Rao, independent references)
+docs/               mkdocs-material site
+examples/           headless, deterministic scripts
+```
+
+## Quality gate (run before handing off)
+
+```bash
+ruff check .
+ruff format --check .
+python -m mypy
+python -m pytest -q --cov=solvephase --cov-report=term-missing
+python -m pytest -q --run-slow -m slow          # convergence/statistics tests
+python -m pytest -q --run-gpu -m gpu            # needs CuPy + a CUDA device
+mkdocs build --strict
+python -m build
+```
+
+CI has no GPU, so `--run-gpu` locally is the only check of the CuPy paths;
+note the GPU and CuPy version when you report GPU results.
+
+## Conventions (stable contracts)
+
+- **Arrays are `(y, x)`**; coordinates sit on pixel centres, centred:
+  `(i - (n - 1) / 2) * pitch` (`propagation.centered_coordinates`). The image
+  of an on-axis point source is centred in the window (between pixels for
+  even sizes).
+- **Sign:** Fraunhofer kernel `exp(-2 pi i x.alpha / lambda)`; a pupil OPD ramp
+  `a * x` moves the image to angle `+a` (towards larger column index). Any
+  sign/transpose fix needs an analytic ramp test, never trial and error.
+- **Units:** SI. OPD in metres is the user-facing wavefront; modal
+  coefficients are RMS OPD in metres (modes are unit RMS). Internally,
+  solvers work in radians at the reference wavelength. Pixel scales are
+  radians, or `sampling` in pixels per lambda/D (2 = Nyquist).
+- **Normalization:** propagators are unitary (Parseval holds when the window
+  captures all light). `FocalPlaneModel` images sum to 1 per channel for an
+  unbounded detector; a finite window loses light and is never renormalized.
+- **Adjoints are exact.** Every linear operator ships `forward` and
+  `adjoint`, and has an adjoint test `<A x, y> == <x, A^H y>`. Every analytic
+  gradient has a finite-difference test.
+- **Backends:** write numerical code against `backend.xp` and `Backend`
+  methods (`fft2`, `asarray`, `to_numpy`, ...). Never call NumPy allocation or
+  FFT directly in a hot path. Host transfers happen only at named boundaries
+  (`to_numpy`, scalar convergence checks every `check_every` iterations).
+  GPU results stay on the GPU.
+- **Precision:** double on CPU and single on GPU by default; float32 and
+  float64 must both work. Don't silently promote float32 hot paths to float64.
+- **Randomness:** draw on the host from a `numpy.random.Generator`
+  (`Backend.random(seed)`) and move to the device, so one seed gives the same
+  starts on CPU and GPU. Never use global `np.random` state.
+- **Results:** focal-plane solvers return `result.Result`; other families
+  return `Result` too when they produce a pupil wavefront, otherwise a small
+  dataclass documented in their module. Every result records `history`,
+  `n_iter`, `converged`, `message` and `elapsed`.
+- **Public API:** export from `solvephase/__init__.py` only what users need;
+  internal helpers start with `_`.
+
+## Writing code here
+
+- Start from a primary reference; cite it in the module docstring and the
+  docs page.
+- A test that only checks "it ran" is not a test. Assert recovery accuracy
+  against a known truth, adjointness, gradients, invariants (piston, flux,
+  shift), or statistics against theory with ensemble tolerances.
+- Mark tests over ~2 s `@pytest.mark.slow`, GPU tests `@pytest.mark.gpu`
+  (parametrize devices with `tests/conftest.py::devices()`).
+- Public functions have type hints and NumPy-style docstrings with units.
+- Error messages say why, and what to do instead.
+- Comments and docstrings describe current behaviour; history goes in
+  `CHANGELOG.md` (under Unreleased).
+- Every user-visible feature lands with its docs page section and a
+  CHANGELOG entry.
+- Docs code fenced as ` ```python ` is executed by `tests/test_docs.py`
+  (each page's blocks in order, as one script). Fence illustrative fragments
+  that cannot run alone as ` ```py `.
+
+## Maintainer rules
+
+- Minor issues worked around rather than fixed get a GitHub issue in the
+  affected repository (when credentials allow), linked from a comment at the
+  workaround. Bugs in the maintainer's own repos (aobasis, pyturb, getframes,
+  makewfs) are fixed at the source, not worked around here. Never file issues
+  on third-party repositories; record them in a solvephase issue instead.
+- No planning or status-tracker files in the repo (ROADMAP.md is the one
+  forward-looking document).
+- Everything must be usable under the MIT license: never copy code from
+  GPL/LGPL/non-commercial/CeCILL sources, and never add patent-encumbered
+  algorithms. PIE-family ptychography (Phase Focus patents) is excluded on
+  these grounds; other ptychography only if it is clearly unencumbered.
+
+## Gotchas
+
+- `aobasis` modes are columns of an `(n_points, n_modes)` matrix;
+  `Basis.modes` stores the transpose `(n_modes, n_valid)`.
+- aobasis warns when points lie outside `pupil_radius`; anti-aliased rim
+  pixels always do, so `Basis.zernike` silences that warning on purpose.
+- The Poisson loss is evaluated as a deviance (non-negative). The raw
+  negative log-likelihood carries a huge data constant that made relative
+  `ftol` stops fire after a few iterations.
+- Unweighted Gaussian least squares on raw PSFs is badly conditioned for
+  zonal retrieval (the core dominates); prefer Poisson or amplitude losses.
+- Spider vanes split a pupil into disconnected regions; `unwrap_phase`
+  bridges their 2 pi multiples with a smooth-surface fit (`bridge=True`).
+- The angular-spectrum propagator removes evanescent waves; with a pitch
+  below the wavelength most of the spectrum is evanescent and the field is
+  not preserved at zero distance.
+- `offset` on `FocalPlaneModel`/propagators shifts the detector *window*:
+  pixel `j` samples angle `(j - (m-1)/2 + offset) * pixel_scale`, so the
+  optical axis lands on pixel `(m-1)/2 - offset`. `offset=-0.5` reproduces
+  HCIPy / `fftshift` centring.
+- CPU threading traps: threaded OpenBLAS level-1 calls (`np.vdot`,
+  `np.dot`, `np.linalg.norm` on >10k elements) stall ~1 ms each when the
+  cores are busy - use `Backend.dot`; and many-thread SciPy FFTs are slower
+  than one thread for small transforms - `backend._cpu_workers(size)` scales
+  the thread count with the transform size.
+- Float32 losses: evaluate data terms and accumulate normal equations in
+  float64 (`FocalPlaneProblem` does). Float32 loss values are too noisy for
+  line-search and LM acceptance and stall solvers above ~1e5 counts/pixel.
+- The Poisson and amplitude losses continue quadratically below a small
+  positive floor; clamping instead gave gradients inconsistent with the
+  value whenever a line search probed negative model values.
+- Background parameters are scaled by robust border noise, not the image
+  standard deviation (a bright PSF core inflates it by orders of magnitude).
+- Simulated data must exercise what you fit: tests once failed because data
+  had a background the problem did not fit, or modes the basis lacked.
+- Extended-scene phase diversity needs compact scenes (blurred scene inside
+  the field); apodization subtracts the edge level, not the mean; the
+  reduced metric's regularization must be tiny (~1/peak SNR^2).
+- CDI: a square or symmetric support invites twin/translation stagnation in
+  single-start tests (use irregular outlines or several starts); RAAR needs
+  beta close to 1 on noise-free data.
+- TIE: masked/Neumann CG in float32 must project the per-region constant out
+  of the preconditioned residual and make right-hand sides consistent;
+  samples must vanish well inside the window (periodic propagation edges
+  otherwise corrupt dI/dz).
+- LIFT: an astigmatism coefficient in the basis produces an exact twin
+  `a' = -a - 2d`; this is physics, not a solver bug (`LIFT` reports the
+  smaller one).
+- Fast & Furious needs an integer FFT size and a centro-symmetric pupil, and
+  its first step must apply even diversity (`first_even=True`).
+- OpenBLAS level-2/3 calls (`matmul`, gemv) on small operands stall like
+  level-1 under load (~3 ms vs 80 us for `np.einsum`); `MatrixOperator`
+  uses einsum on the CPU for small products.
+- Octanary coded-diffraction spectral initializations need `diag(A^H A)`
+  whitening beyond ~1e4 pixels, otherwise the leading eigenvector locks onto
+  single pixels. Wirtinger flow with the paper's `mu_max = 0.2` diverges for
+  n >= 128 (default 0.1). Stop slowly contracting first-order methods on
+  residual stagnation, not on iterate change.
+- Fourier magnitudes alone defeat the Wirtinger family (shift and twin
+  ambiguities); that model belongs to the CDI projection solvers.
+- Always pass `encoding="utf-8"` to `read_text`/`write_text`/`open` for text:
+  Windows defaults to cp1252 and the docs contain non-ASCII characters.
+- Chaotic projection algorithms (DM, RAAR, HIO) land in platform-dependent
+  places after a fixed number of iterations (FFT rounding differs across
+  OS/BLAS builds); assert robust reductions, not tight ratios.
+- Tests import shared helpers as `from conftest import devices` (`tests/`
+  is not a package).
+- GPU timings on a shared device (or CPU timings under load) vary 2-5x;
+  record the load and hardware with any performance claim.

solvephase-0.1.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to `solvephase` are documented here. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-07
+
+First release.
+
+### Focal-plane phase retrieval
+
+- `FocalPlaneModel`: pupil-to-detector image formation for any number of
+  diversity channels.
+  - Broadband light (exact per-wavelength sampling).
+  - Any detector sampling, including undersampled, with pixel integration
+    (`oversample`).
+  - Reverse-mode (`vjp`) and forward-mode (`jvp`) derivatives, verified
+    against finite differences.
+- Propagators with exact adjoints:
+  - zero-padded FFT;
+  - matrix Fourier transform, stacked over wavelengths;
+  - angular spectrum (Fresnel).
+
+  An automatic engine choice picks FFT or MFT per model. The model matches
+  HCIPy to machine precision.
+- `FocalPlaneProblem` + `solve`: maximum-likelihood retrieval.
+  - Losses: Poisson deviance with read noise, weighted Gaussian, or the
+    amplitude metric.
+  - Nuisance fits: per-image flux, background and registration tilt, and an
+    optional zonal pupil amplitude.
+  - Regularization: Tikhonov, a KL-turbulence prior (MAP), and zonal
+    smoothness.
+  - Optimizers: Levenberg-Marquardt with an exact Gauss-Newton/Fisher
+    matrix, L-BFGS with a strong-Wolfe line search, or Adam. All are
+    device-resident.
+  - Single precision reaches the double-precision noise floor, because
+    likelihoods and normal equations accumulate in float64.
+- `gerchberg_saxton`: Gerchberg-Saxton and the multi-plane Misell algorithm,
+  with exact modulus projection on the full FFT grid.
+- `unwrap_phase`: weighted least-squares unwrapping over obscured, spidered
+  and segmented pupils (DCT-preconditioned CG), with 2π bridging of
+  disconnected regions.
+- `retrieve`: one-call retrieval with a robust default strategy.
+  - Amplitude-metric Levenberg-Marquardt from a flat start and from
+    Gerchberg-Saxton; the better fit is kept.
+  - Then a Poisson maximum-likelihood polish and optional zonal refinement.
+
+### Algorithm families
+
+- Phase diversity with an unknown extended object
+  (`phase_diversity`, `PhaseDiversityProblem`).
+  - Gonsalves/Paxman reduced metric with an exact gradient.
+  - Apodization and a diffraction-cutoff frequency mask.
+  - Automatic noise and regularization estimates.
+  - Wiener object estimate.
+- LIFT (`lift`, `LIFT`, `lift_crlb`): maximum-likelihood low-order sensing
+  from one astigmatic image, with a twin check and Cramér-Rao bounds.
+- Fast & Furious (`FastAndFurious`, `simulate_closed_loop`): sequential
+  weak-phase focal-plane sensing with the Korkiakoski et al. (2014)
+  modifications. It takes one FFT pair per step.
+- Coherent diffraction imaging (`cdi`).
+  - Algorithms: ER, HIO, DM, RAAR, RRR, ASR/Douglas-Rachford, HPR and OSS.
+  - Constraints: real, positive, amplitude bounds; beamstop masks.
+  - Chainable schedules, shrinkwrap, and batched multi-start (one batched
+    FFT per iteration).
+  - Helpers: `autocorrelation_support`, `align_object` (ambiguity-aware) and
+    `simulate_cdi`.
+- Generic measurement models (`solvephase.algorithms.wirtinger`,
+  `solvephase.operators`).
+  - Algorithms: Wirtinger flow, truncated Wirtinger flow, truncated and
+    reweighted amplitude flows, and an L-BFGS solver.
+  - Initializations: spectral, truncated, orthogonality-promoting and
+    optimal-preprocessing spectral.
+  - Operators: Gaussian matrix, coded diffraction and oversampled Fourier,
+    each with an exact adjoint.
+- Transport of intensity (`tie`, `simulate_defocus_stack`).
+  - Solvers: FFT and DCT Poisson, uniform intensity and Teague's non-uniform
+    solution, and an exact masked conjugate-gradient solver.
+  - Axial derivative: central differences or a multi-plane polynomial fit.
+
+### Optics and integration
+
+- `Pupil`: anti-aliased circular, annular and spidered pupils; segmented
+  hexagonal apertures with segment labels; Keck, JWST, VLT and Hubble
+  presets.
+- `Basis`:
+  - Zernike (annular), KL (with prior variances), Fourier and any other
+    aobasis generator;
+  - segment piston/tip/tilt;
+  - Gaussian and measured DM influence functions;
+  - zonal.
+- `solvephase.interop`: pyturb turbulence (`turbulence_opd`) and getframes
+  detector frames (`expose`). `expose` converts ADU to electrons and masks
+  saturated pixels.
+- Ambiguity-aware metrics: `rms`, `wavefront_error` (with twin handling) and
+  `strehl_from_rms`.
+- A `solvephase` command line with `info` and `retrieve`.
+- CPU threading tuned for contended and hyper-threaded machines:
+  - FFT worker counts scale with the transform size.
+  - BLAS threads are limited, per call, for matrix Fourier transforms and
+    Gauss-Newton products (via threadpoolctl). This made broadband
+    gradients up to 10x faster.
+  - Scalar products avoid threaded level-1 BLAS.
+
+### Comparison
+
+- `benchmarks/methods.py` runs every method on one reference problem. All
+  focal-plane methods see the same wavefront. It reports:
+  - the data each method needs;
+  - accuracy at a standard SNR;
+  - warm CPU and GPU time;
+  - capture range.
+
+  Its output feeds the comparison tables on the "Choosing an algorithm" docs
+  page, which also has a decision flowchart.
+- The README showcase races every focal-plane method on one clock, with a
+  live error-versus-time chart, plus a gallery of CDI, coded diffraction and
+  TIE.
+- The Keck preset now follows the documented geometry: 10.95 m across the
+  corners, pointy-top segments, six 26 mm support arms, and a 2.57 m central
+  obscuration.
+
+### Shared core
+
+- The backend, pupils, propagators, wavefront metrics and phase unwrapping
+  now live in [aocore](https://github.com/jacotay7/aocore), the AO stack's
+  shared core, and solvephase re-exports them unchanged.
+- `tests/test_conformance.py` runs aocore's convention checks against
+  solvephase: image centring, tilt direction, unit flux and the RMS
+  definition.
+
+### Quality
+
+- More than 280 tests: adjoints, gradients, recovery accuracy, Cramér-Rao
+  efficiency, and CPU/GPU parity.
+- A validation suite against theory and HCIPy.
+- Benchmark and comparison suites with versioned artifacts.
+- An mkdocs documentation site whose code examples are executed in CI.

solvephase-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to solvephase
+
+solvephase is a numerical optics library. A contribution is complete when its
+behaviour, units, tests, documentation and performance implications are all
+clear. Read [AGENTS.md](https://github.com/jacotay7/solvephase/blob/main/AGENTS.md)
+for the conventions and contracts; they apply to human contributors too.
+
+## Development setup
+
+```bash
+git clone https://github.com/jacotay7/solvephase
+cd solvephase
+python -m pip install -e ".[dev,docs,interop,validation]"
+```
+
+For GPU work, also install the CuPy extra that matches your driver
+(`.[cuda12]` or `.[cuda13]`).
+
+## Quality gate
+
+```bash
+ruff check .
+ruff format --check .
+python -m mypy
+python -m pytest -q --cov=solvephase
+python -m pytest -q --run-slow -m slow
+python -m pytest -q --run-gpu -m gpu        # needs a CUDA device
+python -m pytest -q -m interop              # needs pyturb, getframes, hcipy
+python validation/validate.py --quick --output /tmp/validation
+python benchmarks/run.py --quick
+mkdocs build --strict
+python -m build
+```
+
+## What a change needs
+
+- **New algorithm:** a module under `src/solvephase/algorithms/`, primary
+  references in its docstring, tests that assert recovery accuracy (not just
+  that it runs), a GPU parity test, a guide page, a benchmark case and a
+  CHANGELOG entry.
+- **New operator:** an exact adjoint and an adjoint test.
+- **New gradient:** a finite-difference test.
+- **Performance change:** before/after numbers from `benchmarks/run.py`,
+  with the hardware.
+
+## Releases
+
+1. Bump `src/solvephase/__about__.py`.
+2. Date the CHANGELOG section.
+3. Merge to `main`.
+4. Publish a GitHub release whose tag is the bare version (e.g. `0.2.0`).
+
+The release workflow builds the distributions and uploads them to PyPI with
+trusted publishing.

solvephase-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

solvephase-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: solvephase
+Version: 0.1.0
+Summary: Fast, GPU-optional phase retrieval for adaptive optics, optical metrology and coherent imaging.
+Project-URL: Homepage, https://github.com/jacotay7/solvephase
+Project-URL: Documentation, https://jacotay7.github.io/solvephase/
+Project-URL: Repository, https://github.com/jacotay7/solvephase
+Project-URL: Issues, https://github.com/jacotay7/solvephase/issues
+Project-URL: Changelog, https://github.com/jacotay7/solvephase/blob/main/CHANGELOG.md
+Author-email: Jacob Taylor <jacobataylor7@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adaptive-optics,coherent-diffraction-imaging,gerchberg-saxton,gpu,phase-diversity,phase-retrieval,wavefront-sensing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aobasis>=2.0
+Requires-Dist: aocore>=0.1
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: threadpoolctl>=3.0
+Provides-Extra: cuda12
+Requires-Dist: cupy-cuda12x[ctk]>=13.0; extra == 'cuda12'
+Provides-Extra: cuda13
+Requires-Dist: cupy-cuda13x[ctk]>=13.6; extra == 'cuda13'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: fits
+Requires-Dist: astropy>=5.0; extra == 'fits'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x[ctk]>=13.0; extra == 'gpu'
+Provides-Extra: interop
+Requires-Dist: getframes>=2.2; extra == 'interop'
+Requires-Dist: pyturb>=1.2; extra == 'interop'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest-timeout>=2.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Provides-Extra: validation
+Requires-Dist: hcipy>=0.6; extra == 'validation'
+Requires-Dist: matplotlib>=3.7; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# solvephase
+
+[![CI](https://github.com/jacotay7/solvephase/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/solvephase/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/solvephase.svg)](https://pypi.org/project/solvephase/)
+[![Python](https://img.shields.io/pypi/pyversions/solvephase.svg)](https://pypi.org/project/solvephase/)
+[![Docs](https://img.shields.io/badge/docs-jacotay7.github.io%2Fsolvephase-indigo.svg)](https://jacotay7.github.io/solvephase/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Documentation: [jacotay7.github.io/solvephase](https://jacotay7.github.io/solvephase/)**
+
+**Fast, GPU-optional phase retrieval for adaptive optics, optical metrology and
+coherent imaging.**
+
+<p align="center">
+  <img src="examples/solvephase_showcase.webp" width="900" alt="A race between every solvephase focal-plane method on the same aberrated VLT-like wavefront (Gerchberg-Saxton/Misell, modal and zonal maximum likelihood, retrieve(), extended-scene phase diversity, LIFT and Fast &amp; Furious) on one clock, with a live error-versus-time chart and a gallery of CDI, coded-diffraction and TIE reconstructions.">
+</p>
+
+`solvephase` recovers phase from intensity. It covers focal-plane wavefront
+sensing (Gerchberg–Saxton/Misell, maximum-likelihood modal and zonal
+retrieval, phase diversity with unknown extended objects, LIFT, Fast &
+Furious), coherent diffraction imaging (ER, HIO, DM, RAAR, RRR, ASR, HPR,
+OSS, shrinkwrap), generic measurement models (Wirtinger, truncated,
+amplitude and reweighted flows) and the transport-of-intensity equation, all
+behind one API. It runs on NumPy by default and on CUDA (CuPy) with one
+argument.
+
+## Install
+
+```bash
+pip install solvephase                 # CPU
+pip install "solvephase[cuda12]"       # + CuPy for CUDA 12.x
+pip install "solvephase[cuda13]"       # + CuPy for CUDA 13.x
+pip install "solvephase[interop]"      # + pyturb atmospheres and getframes detectors
+```
+
+## Quickstart
+
+```python
+import solvephase as sp
+
+pupil = sp.Pupil.vlt(128)  # 8 m, obscured, four vanes
+model = sp.FocalPlaneModel(
+    pupil, 1.65e-6, 64, sampling=2.0, diversity=sp.zernike_diversity(pupil, 4, [0.0, 0.4e-6])
+)
+truth = sp.random_aberration(pupil, 100e-9, n_modes=40, start=4, seed=1)
+images = sp.simulate_images(model, truth, photons=1e6, background=10, read_noise=3, seed=2)
+
+result = sp.retrieve(
+    images, pupil, 1.65e-6, sampling=2.0, diversity=[0.0, 0.4e-6], read_noise=3.0, device="auto"
+)
+print(result.summary())  # converged in a handful of LM steps
+result.opd, result.coefficients  # wavefront [m], Zernike [m RMS]
+```
+
+`retrieve` is robust by default. It explores with Levenberg–Marquardt on the
+amplitude metric from a flat start and from Gerchberg–Saxton, keeps the
+better fit, and polishes with the Poisson likelihood. For full control, use
+`FocalPlaneProblem` and `solve` (choose the basis, likelihood, nuisance
+parameters and optimizer). The other families are one call each:
+
+```python
+sp.phase_diversity(model, images_of_extended_scene)  # unknown object
+sp.LIFT(pupil, wavelength, 32, sampling=2.0).estimate(img)  # one astigmatic image
+sp.FastAndFurious(pupil, wavelength, 64, sampling=2.0).step(img, dm_change)
+sp.cdi(magnitudes, support, schedule="hio:500,er:100", starts=16, device="gpu")
+sp.tie(stack, [-dz, 0, dz], pitch=pitch, wavelength=wavelength)
+```
+
+See **[Choosing an algorithm](https://jacotay7.github.io/solvephase/choosing/)**
+for a side-by-side comparison: images needed, requirements, measured speed,
+accuracy and capture range of every method.
+
+## Highlights
+
+- **Exact derivatives everywhere.** Every propagator (FFT, matrix Fourier
+  transform, angular spectrum, coded diffraction) has an exact adjoint.
+  Gradients and Gauss–Newton Jacobians are analytic, with no autodiff tape.
+  Levenberg–Marquardt typically converges in 5–10 iterations.
+- **Statistically efficient.** Poisson + read-noise likelihoods, fitted
+  flux, background and registration, masks for bad and saturated pixels.
+  The estimator reaches the Cramér–Rao bound in the validation suite.
+- **Physically complete.** Broadband light, any sampling (including
+  undersampled detectors), pixel integration, segmented apertures, KL
+  priors, and DM influence-function bases.
+- **Fast on CPU and GPU.** Batched FFTs, matrix Fourier transforms on BLAS,
+  batched multi-start CDI, and device-resident optimizers. Single precision
+  reaches the same noise floor as double.
+- **Validated.** It matches HCIPy to machine precision and the analytic
+  Airy normalization, and the validation suite checks its Cramér–Rao
+  efficiency and capture range on every CI run.
+- **Part of an AO toolchain.** Modal bases come from
+  [aobasis](https://github.com/jacotay7/aobasis), realistic aberrations from
+  [pyturb](https://github.com/jacotay7/pyturb), and detector frames from
+  [getframes](https://github.com/jacotay7/getframes).
+
+## Benchmarks
+
+See the [benchmarks page](https://jacotay7.github.io/solvephase/benchmarks/)
+and the versioned artifacts in [`benchmarks/artifacts`](benchmarks/artifacts).
+
+Same problem, same data, on an Intel i7-10700 and an entry-level NVIDIA
+Quadro P620 ([artifacts](benchmarks/artifacts)):
+
+| Task | Baseline | solvephase CPU | solvephase GPU |
+|---|---|---|---|
+| Focal-plane retrieval, 128², 36 modes, 2 images (time to solution) | HCIPy + SciPy L-BFGS-B: 8.5 s; `least_squares`: 5.3 s | **0.46 s** | **0.14 s** |
+| Misell/GS, 128², iterations/s | textbook NumPy: 156 | 268 | **1,493** |
+| CDI HIO, 256², iterations/s | textbook NumPy: 252 | 794 | **2,957** (3,492 per start with 16 batched starts) |
+| Broadband (5 λ) gradient, 256² | — | 67 ms | **9 ms** |
+| TIE, 2048², 3 planes | — | 253 ms | **33 ms** |
+
+On the focal-plane problem every method reaches 0.12–0.19 nm RMS; solvephase
+gets there 11–18x faster on the CPU and 38–61x faster on the GPU.
+
+## Validation
+
+`python validation/validate.py` checks solvephase against theory and an
+independent code and writes a report; see the
+[validation page](https://jacotay7.github.io/solvephase/validation/).
+
+## Development
+
+```bash
+pip install -e ".[dev,docs,interop,validation]"
+python -m pytest -q                       # fast suite
+python -m pytest -q --run-slow --run-gpu  # everything
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+## License
+
+MIT; see [LICENSE](LICENSE).