croak 0.1.0__tar.gz

croak-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+# The workflow name is the label on the README's badge.
+name: Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-type-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      # The optional extras ('ridb', 'evo') are deliberately not installed: the
+      # refractiveindex.info database is a hundreds-of-megabyte download on first
+      # use. Their import sites are guarded, so this only skips their tests.
+      - name: Type check
+        run: uv run pyright
+
+      # PyQt6 needs system libraries and a virtual display.
+      - name: Install Qt system libraries
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libegl1 libgl1 libxkbcommon-x11-0 libdbus-1-3 \
+            libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
+            libxcb-randr0 libxcb-render-util0 libxcb-shape0 \
+            libxcb-xinerama0 libxcb-cursor0 xvfb
+
+      - name: Run tests with coverage
+        run: xvfb-run -a uv run pytest --cov-report=xml
+
+      # Tokenless upload works for public repos; set CODECOV_TOKEN in the repo
+      # secrets to avoid rate limits (see the release checklist).
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

croak-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+# Publishes to PyPI via trusted publishing (OIDC) — no token stored anywhere.
+# Triggered by publishing a GitHub Release whose tag is v<version> (e.g. v0.1.0).
+# One-time setup: a "pending publisher" on PyPI pointing at this repo/workflow/
+# environment, and a GitHub environment named "pypi" (see the release checklist).
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # the OIDC token PyPI trusted publishing exchanges
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install
+
+      # A tag that disagrees with pyproject.toml would publish a version under
+      # the wrong name; fail fast instead.
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # Smoke-test the built wheel in a clean environment before publishing.
+      - name: Check the wheel imports
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import croak; print(croak.__version__)"
+
+      - name: Publish to PyPI
+        run: uv publish

croak-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv*/
+
+# example outputs (regenerate by running the scripts in examples/)
+retrieval.png
+retrieval.h5
+defringe_check.png
+baseline_check.png
+geometric_smearing.png
+thickness_uncertainty.png
+paper_thickness.png
+paper_rdw.png
+
+# local agent state
+.claude/
+
+# documentation build artifacts
+docs/_build/
+.jupyter_cache/
+*.ipynb_checkpoints/
+
+# tool caches
+.pytest_cache/
+.ruff_cache/
+
+.coverage
+.DS_Store
+qfile_*

croak-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

croak-0.1.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration for the croak documentation.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+sphinx:
+  configuration: docs/conf.py
+  # The build is warning-free, so treat warnings as errors. This is the only
+  # gate on documentation drift: CI does not build the docs, and a broken
+  # autodoc/cross-reference degrades to a warning rather than a failure, so
+  # without this a silently-broken API reference would publish.
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

croak-0.1.0/.zenodo.json

@@ -0,0 +1,29 @@
+{
+    "title": "croak: complete retrieval of ultrashort laser pulses from FROG traces",
+    "version": "0.1.0",
+    "upload_type": "software",
+    "license": "MIT",
+    "description": "croak reconstructs the full complex electric field of an ultrashort laser pulse — spectral amplitude and phase — from a delay-scanned nonlinear-process spectrum. It is a general retrieval package for the PNPS class of measurements, currently focused on FROG (SHG, SD and PG/transient-grating), with a differentiable forward model that includes dispersive propagation in the nonlinear medium, geometric delay smearing of the crossed-beam geometry, and the chromatic collection aperture — the physics needed for quantitative retrieval of few-femtosecond deep-ultraviolet pulses. Companion code to: J. C. Travers and C. Brahms, \"Extreme ultrashort pulse retrieval with differentiable physical forward models\" (to be published).",
+    "creators": [
+        {
+            "name": "Travers, John C.",
+            "affiliation": "Heriot-Watt University",
+            "orcid": "0000-0003-0350-9104"
+        },
+        {
+            "name": "Brahms, Christian",
+            "affiliation": "Heriot-Watt University",
+            "orcid": "0000-0002-8009-3547"
+        }
+    ],
+    "keywords": [
+        "ultrafast",
+        "FROG",
+        "pulse retrieval",
+        "frequency-resolved optical gating",
+        "transient grating",
+        "PNPS",
+        "ultrashort pulses",
+        "nonlinear optics"
+    ]
+}

croak-0.1.0/AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+## Guiding principles
+
+- There should be one obvious way to do each thing. Prefer the existing pattern over inventing a new one; if you find two ways to do the same thing, consolidate them.
+- Optimise for the reader. Clear beats clever — code is read far more often than it is written.
+- Small, single-purpose functions with explicit inputs and outputs. Prefer pure functions; push side effects (I/O, global state, mutation) to the edges.
+- Make the implicit explicit: explicit arguments over hidden state, explicit types on interfaces, explicit errors over silent fallbacks.
+- Fail loudly and early with a clear exception. Never swallow errors or return a sentinel where raising is correct.
+
+## Environment and tooling
+
+- Python is managed with **uv**. Dependencies are declared in `pyproject.toml`; the resolved lockfile is `uv.lock`. Never `pip install` into the environment by hand.
+- Add dependencies with `uv add <pkg>` (and `uv add --dev <pkg>` for dev/test tools). Sync the environment with `uv sync`.
+- Run everything through the project environment by prefixing commands with `uv run`.
+- Target Python [3.14]; keep it consistent with `requires-python` in `pyproject.toml`.
+
+## Commands
+
+- Sync environment: `uv sync`
+- Format: `uv run ruff format .`
+- Lint (with autofix): `uv run ruff check --fix .`
+- Type-check: `uv run pyright`
+- Test: `uv run pytest`
+- Build docs: `uv run sphinx-build -b html docs docs/_build/html`
+
+## Definition of done
+
+Before treating any change as complete, run these in order and ensure each passes with no new warnings:
+
+1. `uv run ruff format .`
+2. `uv run ruff check --fix .`
+3. `uv run pyright`
+4. `uv run pytest`
+
+Do not declare work finished while any step fails. If a check genuinely cannot pass for a justified reason, say so explicitly rather than suppressing it.
+
+Furthermore, ensure all added functionality is documented both in docstrings *and* in the manual under docs.
+
+## Code style
+
+- Formatting is owned by `ruff format`; do not hand-format or fight the formatter. Line length is the ruff default (88) unless `pyproject.toml` overrides it.
+- Linting is owned by `ruff check`. Fix the cause rather than silencing the warning. A suppression must be rule-specific with a reason (`# noqa: E501 — URL must stay on one line`), never a blanket `# noqa`.
+- Imports are absolute and sorted by ruff. No wildcard (`from x import *`) imports.
+- Naming: `snake_case` for functions and variables, `PascalCase` for classes, `UPPER_SNAKE` for constants. Names state what a thing is or does; avoid abbreviations beyond well-established domain ones.
+- Use f-strings for interpolation and `pathlib.Path` for filesystem paths. Reach for the standard-library idiom before adding a dependency.
+
+## Types
+
+- Annotate every public function signature and class attribute. Add types where they clarify intent or catch mistakes; do not annotate obvious locals just to fill space.
+- Code must pass `pyright` in the project's configured mode with no new errors.
+- Prefer precise types: `Sequence`/`Mapping` over `list`/`dict` for read-only parameters, `X | None` over `Optional[X]`, and built-in generics (`list[int]`). Avoid `Any`; if it is unavoidable, confine it to one place and comment why.
+- Use a `@dataclass` (frozen where it can be) for structured data instead of passing loose tuples or dicts around.
+
+## Docstrings
+
+- Every public module, class, and function has a **NumPy-style** docstring (rendered by Sphinx via the napoleon extension). Private helpers get a one-line docstring when the name is not fully self-explanatory.
+- The first line is an imperative one-sentence summary. Then include, as applicable: `Parameters`, `Returns`, `Raises`, and `Examples`.
+- For numerical quantities, state units and valid ranges in the parameter descriptions.
+- Make `Examples` runnable (doctest style) where practical. Describe behaviour and contracts, not implementation details that will drift.
+
+## Comments
+
+- Code comments should be comprehensive. They should explain both the maths and physics as well as coding details.
+- Comments cover: rationale, assumptions, references (a paper, an issue link), and non-obvious trade-offs.
+- Keep each comment next to what it describes and update it when the code changes. Delete commented-out code — version history is the archive.
+- Mark deliberate follow-ups as `# TODO(context): ...` so they are greppable.
+
+## Functions and modules
+
+- One function, one responsibility. If a function needs a paragraph to explain, or has many nested branches, split it.
+- Keep parameter lists short. Group related parameters into a small dataclass or config object rather than passing many positional arguments.
+- Prefer returning new values over mutating arguments in place. Keep the core logic pure and testable; isolate I/O at the boundaries.
+- Organise modules by domain concept, not by a catch-all `utils`. Each module should have a clear, nameable purpose. Declare the public surface explicitly with `__all__` where it helps.
+
+## Tests
+
+- Tests use **pytest** and live in `tests/`, mirroring the package layout. Name them `test_<unit>_<behaviour>`.
+- Every public function has tests for the normal case, the edge cases, and the error paths. Add a regression test with every bug fix.
+- Tests are deterministic, isolated, and fast: use fixtures for setup, `pytest.mark.parametrize` instead of copy-pasted cases, and no network access or hidden global state.
+- For numerical code, assert with explicit tolerances (`numpy.testing.assert_allclose`, `pytest.approx`) and test invariants and conservation laws, not only point values.
+- Write the test alongside the code; a feature is not done until it is tested.
+
+## Documentation
+
+- Docs are built with **Sphinx**, and the API reference is generated from docstrings — so the docstring is the source of truth. Keep the `README.md` and any usage guide current with behaviour changes.
+- Record notable changes in `CHANGELOG.md` (Keep a Changelog style).
+- All functionality of this package must be described in the user manual under the docs/ folder. This should include background explanations and context, how the functionality works, and examples
+- When adding functionality, always add documentation.
+- When working on something that does not appear to be documented, check this and add appropriate documentation.
+
+## Git
+
+- Make clean, logical git commits with descriptive but not overly verbose commit messages.
+- Prefer more frequenct clean commits over large big ones.
+- *Never* push.
+- You can fetch, pull, branch when instructed to do so. If you want to do this, ask.
+- Do not make releases or change release versions

croak-0.1.0/CHANGELOG.md

@@ -0,0 +1,347 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
+semantic versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-31
+
+### Changed
+
+- **`warm-lbfgs` is now the default solver everywhere.** `croak.retrieve`
+  (previously `"copra"`), `retrieve_from_tracedata` (previously `"lbfgs"`) and
+  the coverage-calibration harness (previously `"copra"`) now default to
+  `"warm-lbfgs"`, matching the session pipeline, the GUI and the companion
+  paper's production protocol. Pass `algorithm=` explicitly to keep the old
+  behaviour.
+
+### Added
+
+- **Companion-paper validation data and examples.** Two reduced datasets from
+  the paper's first-principles 3D instrument simulations ship in
+  `examples/data/` (the 1 fs fused-silica thickness series and the single-cycle
+  RDW pulse), with worked retrievals in `examples/example_paper_thickness.py`
+  and `examples/example_paper_rdw.py`, and `tools/reduce_scansave.py` to cut
+  such datasets from full `scansave` scans. The documentation's
+  [Validation](docs/explanation/validation.md) page now summarises the paper's
+  study — model hierarchy, thickness series, geometry and collection results,
+  solver protocol and metrics guidance — with its figures.
+
+- **GUI-only install guide.** `docs/getting_started/gui.md` walks a non-Python
+  user from nothing to a running wizard, linked from the top of the README.
+
+- **Release metadata.** README badges (tests, coverage, docs, ruff, pyright,
+  Python, licence), a `CITATION.cff`, and Codecov upload in CI.
+
+- **Known-truth pulse errors.** New `croak.truth_metrics` scores a retrieval
+  against a *known* pulse rather than against the measured trace: `eps_It`
+  (temporal intensity), `eps_Iw` (spectral intensity) and `eps_Ew` (Geib's
+  complex-field epsilon). Each removes exactly the gauge freedoms a PNPS
+  measurement cannot determine — energy scale, absolute phase, delay — and no
+  others. The Retrieve stage's numeric read-out shows all three beside the FROG
+  error whenever a known pulse is loaded. Read together they localise a failure a
+  trace error hides: `eps_Iw` small with `eps_Ew` large is a correct amplitude
+  with a wrong phase.
+
+- **Live preview during COPRA.** `copra` and `copra-jax` now hand the GUI an
+  in-progress result each iteration, so the full 12-panel preview redraws during
+  their sweeps instead of only showing a convergence curve. This matters most
+  for `warm-lbfgs`, whose 300-iteration COPRA warm-up previously left the
+  preview blank for most of the run. The snapshot reuses the iterate the sweep
+  already computed, so it costs no extra forward pass.
+
+- **Complex ModelPNPS truth as a retrieval seed.** Complex source/beamlet fields
+  are retained on `TruthPulse`; `initial_guess(..., mode="truth")`,
+  `retrieve_from_tracedata(..., guess="truth", truth=...)`, and
+  `RetrieveParams(truth_init=True)` route the known solution into the solver for
+  direct forward-model residual checks. The Retrieve GUI now has one mutually
+  exclusive initial-guess selector (including **Truth** and **Reuse previous**),
+  replacing the conflicting independent checkboxes. Known temporal and spectral
+  phases are dotted, named in both legends, and saved with the complex truth.
+
+- **Headless install: the GUI is now an extra.** `pyqt6`/`superqt` moved from
+  the core dependencies to `croak[gui]`; everything except the wizard —
+  retrieval, preprocessing, processing, uncertainty, plotting, the `croak`
+  CLI — runs without Qt, so compute nodes install without it (`uv sync
+  --no-dev`, or plain `pip install croak`). Launching `croak-gui` without the
+  extra raises a message saying how to get it. The dev group still carries Qt
+  (the suite includes the GUI tests), so `uv sync` in a checkout is unchanged.
+
+- **Multi-aperture scans: every stored window is selectable.**
+  `io.read_simulated_window_keys` now discovers all trace windows in the
+  file — the canonical trio first, then the numbered windows of an
+  aperture-series scan (`Iω_win_2` … with their `_reimaged` partners, one
+  propagation reduced through several collection holes) — so the GUI's
+  trace-window selector offers them all.
+
+- **Aperture selection for multi-window scans** (`window=` on
+  `aperture_from_scan` / `read_simulated_mask_window`, plus
+  `io.window_def_prefix`). An aperture-series scan records one
+  `window_def_N_*` record per collection hole; the selector (the trace-window
+  dataset name, `_reimaged` accepted, or the bare index) rebuilds that hole's
+  aperture, so the focal+collection model can retrieve any window of the
+  series against its own recorded geometry.
+
+- **Uniform-delay-core selection at load** (`SimulatedLoadParams.
+  uniform_delay_core`, a checkbox on the simulated-load stage, and
+  `preprocess.uniform_core_indices`). Campaign scans often extend a uniform
+  delay core with coarser wing points (e.g. 1 fs-step wings to ±40 fs for the
+  Raman wake); the smearing kernel's delay-axis convolution needs a uniform
+  grid, so such scans could not previously be retrieved with the kernel
+  modelled. The option keeps the longest uniformly spaced contiguous stretch
+  of the axis (off by default — the wings are real data for every
+  kernel-free model).
+
+- **`focal=` now reaches the high-level pipeline.** `retrieve_from_tracedata`
+  (and therefore `croak.session.pipeline.run_retrieval`, via a new keyword)
+  accepts a `FocalMixture`, forwarding it to the solvers that can model it and
+  raising for those that cannot — closing the gap where the solver
+  constructors accepted a mixture but every session-level entry point silently
+  could not pass one.
+
+- **The focal mixture in `RetrieveParams` and the GUI.** New scalar fields
+  (`focal`, `focal_n_radial`/`focal_n_azimuth`/`focal_rmax_units`,
+  `focal_f_mm`, `collection`, `collection_mode`, `collection_diam_mm`,
+  `spectrum_frame_p`) plus `session.pipeline.focal_mixture_from_params` — the
+  focal counterpart of `smearing_kernel` — which `run_retrieval` invokes
+  automatically when `focal` is set (pass `scan_path` for
+  `collection="file"`, which rebuilds the aperture from the scan's own
+  `window_def_*` record; `"manual"` builds a hard-edged pinhole at the
+  phase-matched corner). `apply_spectrum_frame` reweights the measured
+  spectrum (initial guess and `reg_spectrum` target together) by
+  `(ω/ω₀)^{2p}` into the mixture's on-axis frame. The GUI's retrieve stage
+  gains a *Chromatic focal mixture (advanced)* group, mutually exclusive with
+  the reduced kernel, with the focusing focal length adopted from simulated
+  scans' geometry records (`io.SimulatedScan` now reads `f_foc`).
+
+- **Finite collection aperture for the focal mixture** (new `croak.collection`,
+  reached through `focal_mixture(..., collection=...)`). `croak.focal` sums
+  *incoherently* over focal position, which by Parseval is exact only if the
+  detector collects the whole signal beam. Most non-collinear instruments pick the
+  signal out of the BOXCARS pattern with a hole — a filter in transverse
+  wavevector — and a typical DUV instrument's hole is **six times narrower
+  than the signal's own k content**, so it sits far closer to the coherent limit
+  than to the incoherent one. The new path transforms the focal field to
+  transverse k, applies the aperture there and integrates, in either the
+  `"integrated"` (spectrometer behind the hole) or `"reimaged"` (on-axis re-imaged
+  pixel, the fully coherent limit) model.
+
+  The `(p, theta)` reduction survives intact: croak's per-node build and the exact
+  focal-plane signal differ by a rigid time shift, so the incoherent sum discards
+  exactly one phase, and after the signal's phase-matched carrier is removed that
+  phase is `exp(+i w p)` — *w times one of the two reduced smearing parameters*
+  (`-w theta` for SD, which is not yet implemented). Validated against a dense 2-D
+  FFT of the focal field built directly from the arm tilts: 3.5e-7 of peak with no
+  fitted scale, plus an exact Parseval test on a Cartesian grid. Costs +5 % of
+  runtime at production shape, stays differentiable, and reaches every solver that
+  already accepted `focal=`. `collection=None` (the default) leaves the existing
+  incoherent sum untouched.
+
+- **`aperture_from_scan` / `croak.io.MaskWindowSpec`.** Simulated scans record the
+  collection window they were taken through as flattened `/grid/window_def_*`
+  scalars; these read it back and rebuild the aperture, resolving the simulator's
+  `"default"` apodisation width from the file's own transverse k-grid. That matters:
+  for the reference instrument it is a 96.9 µm `tanh` edge on a 500 µm hole — 19 %
+  of the diameter — which a top hat does not approximate.
+
+- **`croak.focal.mixture_from_nodes`** builds a mixture on arbitrary focal-plane
+  nodes, and `FocalMixture` now records the mask hole positions it was built from
+  (`arms`, plus a `signal_position` property). The incoherent sum needed only the
+  arm *differences* that make `(p, theta)`; the aperture needs to know where the
+  signal actually goes.
+
+- **Faster `lm-optx` linear solve** (`linear_solver` on
+  `croak.optimistix_lm.OptxLM`). Each Levenberg–Marquardt iteration solves
+  `[J; sqrt(lambda) I] d = [r; 0]`; the new default `"normal"` forms
+  `J^T J + lambda I` and takes its Cholesky factor instead of running
+  Optimistix's QR on the stacked operator (still available as `"qr"`). The Gram
+  matrix is one BLAS `gemm` at near-peak throughput while a tall-skinny
+  Householder QR is panel-bound, so a 512-point PG retrieval drops from 2.9 s to
+  1.2 s per iteration at an identical final error. Both routes rely on
+  `lambda > 0` — the FROG Jacobian is strongly rank-deficient either way — but
+  the normal equations square the condition number, so `"qr"` is kept as an
+  escape hatch.
+
+- **Complex simulated-scan truth spectra.** `read_simulated_scan` now loads
+  the complex vignetted-beamlet spectrum (`Eω_beamlet_re`/`_im`, written by
+  newer ModelPNPS runs) and the complex source spectrum onto
+  `SimulatedScan.Eomega_beamlet` / `.Eomega` (both `None` for
+  intensity-only legacy files). The beamlet phase carries any input chirp
+  exactly, enabling complex-field retrieval-error metrics and direct
+  truth-GDD measurement instead of intensity-only comparisons.
+
+- **Generation-envelope weights** (`depth_weight` on
+  `croak.forward_jax.make_param_trace_fn`, the `lbfgs-ad` solver and
+  `retrieve_from_tracedata`, which raises rather than silently dropping it on
+  unsupported solvers): optional complex per-node weights multiplying the
+  depth quadrature, modelling the transverse geometry a 1D depth integral
+  cannot see (focal-spot evolution across the slab, beamlet walk-through, Gouy
+  phase). The session layer exposes the analytic Gaussian-crossing form via
+  `RetrieveParams.envelope*` and `croak.session.pipeline.generation_envelope`.
+  Uniform weights are a verified no-op; the envelope matters only when the
+  slab is not much thinner than the beams' effective depth of focus
+  (`docs/explanation/forward_model.md`) — note that for aperture-masked
+  beamlets that scale is set by diffraction (`~lambda (f/D)^2`), not by the
+  imaged-source Rayleigh range.
+
+- **Split-channel smearing fit** (`fit_smearing_split`, AD solvers): fit the
+  gate-shape (`p`) and delay (`delta`) widths of the geometric-smearing kernel
+  as two independent multipliers instead of the single joint one — the
+  diagnostic for *which* channel deviates from the geometric prediction. The
+  split is exact (the bivariate kernel scales channel-wise at fixed `rho`);
+  the fitted values land in `RetrievalResult.smear_scale` (p) and the new
+  `smear_scale_delta` (delta), are saved/reloaded by `croak.save`, and
+  `parameter_covariance` reports `sigma_smear_delta` alongside `sigma_smear`.
+  Note the `p` multiplier is only identifiable for a chirped gate (a
+  transform-limited gate's `p` response is absorbed by the intensity scale).
+
+- **`croak.save.save_result(..., group=…)`** writes the unchanged flat result
+  schema into a named HDF5 group instead of the file root, appending rather than
+  truncating, so a parameter study (a thickness series, a solver comparison) can
+  keep every run in one file — one group each, nesting with `"full/z00"`-style
+  names. `force=True` then replaces only that group. `load_result` already
+  recurses into subgroups, so such a file reads back as a nested dict.
+- **Retrieval-quality diagnostics for spectral energy at the band edges.** The
+  outermost frequency bins of the retrieval grid carry no measurement (`regrid`
+  tapers them to zero), so the field there is nearly unconstrained and — since
+  intensity is bounded below by zero — can only drift upward. Two new measures
+  catch it:
+  - {func}`croak.processing.edge_energy_fraction`, also carried on
+    `ProcessedResult.edge_energy` and printed in the `plot_retrieval` spectrum
+    panel (red above `croak.plotting.EDGE_ENERGY_WARN`, 1 %).
+  - `TraceData.taper_loss`, the fraction of the measured trace the edge taper
+    removed. `load_and_clean`/`regrid` now warn above 1 % (`taper_warn_level`),
+    which is the load-time signature of a `lam_min`/`lam_max` band that clips.
+- `croak.preprocess.TAPER_COLLAR_BINS` names the taper width, previously an
+  unexplained literal `10` in two places.
+
+### Changed
+
+- **Simulated-scan delay convention is now auto-detected.**
+  `SimulatedLoadParams.reverse_trace` defaults to `None` (auto): scansave
+  files that carry the new `/grid/delay_convention = "gate"` marker (written
+  by ModelPNPS runs that store the trace directly in the gate-delay/paper
+  frame) load without delay-axis reversal, while legacy marker-less files are
+  negated exactly as before. An explicit `True`/`False` still overrides.
+  `SimulatedScan` gained the `delay_convention` attribute.
+
+- `regrid` returns a seventh element, the taper loss.
+- **Renamed `ProcessedResult.Iw_photon` to `ProcessedResult.Ilam`.** The
+  quantity is the spectral intensity as a *wavelength density* (`|Ẽ(ω)|²ω²`,
+  the λ→ω Jacobian applied), not a photon-flux weighting; the new name pairs it
+  with `ProcessedResult.wavelength` and matches the saved `Ilam_retr` dataset.
+- Documented that `R_omega=True` must not be used without `reg_spectrum` or
+  `phase_only`: per-frequency scaling discards the frequency marginal, which is
+  what pins the retrieved spectral amplitude, and it *lowers* the reported trace
+  error while doing so. On a perfect synthetic PG trace it raises the edge energy
+  from 0.02 % to 5.4 %.
+
+### Fixed
+
+- **Three-argument progress callbacks work with every solver.** The documented
+  signature is `callback(iteration, R, best_R, snapshot=None)`, but the shorter
+  form worked with `copra`/`copra-jax` (which never passed a snapshot) and failed
+  with `lbfgs-ad` — so which forms were legal depended on the solver, and giving
+  COPRA a snapshot to offer would have broken existing code. `Retriever.run` now
+  adapts a callback that cannot receive a snapshot instead of raising.
+
+- **`warm-lbfgs` reported only half of its own convergence.** The COPRA warm-up's
+  error log was discarded, so the curve began partway down with no account of the
+  work that got it there, and progress restarted from iteration 1 at the
+  handover. Both stages are now spliced into one history, with the join recorded
+  in the new `RetrievalResult.stage_boundaries` and drawn as a dashed rule —
+  necessary because the halves do not count the same unit of work (a COPRA
+  iteration is a full local sweep; an L-BFGS step is one function evaluation).
+  Its results also identify themselves as `warm-lbfgs` instead of inheriting
+  `lbfgs-ad`, which had sent an uncertainty bootstrap off to re-run replicates
+  with the cold solver.
+
+- **Native-grid simulated loads quantised time zero to a delay bin.**
+  `assemble_simulated_tracedata` located the delay marginal's peak by taking its
+  largest *sample*, so a scan whose true zero delay falls between two bins — an
+  even, symmetric delay axis does exactly that — was modelled up to half a delay
+  step away from where it was measured. It now uses
+  `preprocess.marginal_peak_delay`, the sub-sample helper `regrid` already used
+  and which its own docstring describes this defect in. A retrieval absorbed the
+  shift into a linear spectral phase, so retrieved pulses were unaffected beyond
+  a time translation, but any comparison against an un-translated known field
+  paid for it in full: the truth-seeded forward-model check floored at `R ~ 5e-3`
+  and now reaches `~1e-16`.
+
+- **`make_trace_fn(focal=...)` was silently ignored** when no `smearing` kernel was
+  also passed: the single-delay entry point fell through to the unsmeared model and
+  said nothing. Retrievals were unaffected (they go through
+  `make_param_trace_fn`), but a forward-model call was.
+
+- **NLopt failures no longer abort retrievals.** The `lbfgs` and `lbfgs-ad`
+  solvers previously died with a bare `nlopt.runtime_error` when NLopt's
+  internal line search failed (observed for roughly one in six random starts
+  on large dispersive grids). They now return the best iterate found, with a
+  one-time warning; a non-finite objective or gradient is additionally trapped
+  and replaced by a large finite penalty (`croak.solver.guard_nonfinite`) so
+  the line search backtracks.
+
+- Two docstring examples that did not match their own output
+  (`peak_wavelength`, `marginal_peak_delay`).
+- A batch of docstring/docs statements that had drifted from the code:
+  `croak.processing.edge_energy_fraction` cited a function that does not exist
+  (`taper_collar_signal`; the real load-time guard is `regrid`'s
+  `taper_warn_level` warning plus `TraceData.taper_loss`); the `croak.lm` module
+  docstring opened by claiming the MINPACK `method="lm"` default that the rest
+  of the docstring and the code contradict (the default is `"trf"` with the JAX
+  Jacobian); `retrieve_from_tracedata` omitted `"copra-jax"` and `"cma-es"`
+  from its documented algorithm set and described `R_omega` as L-BFGS-only (all
+  solvers support it, as `docs/explanation/retrieval_theory.md` now also
+  says); `compute_mu_per_freq`/`mu_per_freq` now document that the weights
+  cancel identically (the per-frequency factors are weight-independent; a
+  zero-weight row falls back to `1.0`); `croak/__init__.py` and the README
+  claimed all three geometries propagate dispersively (dispersive SHG raises —
+  PG/SD only); `docs/explanation/forward_model.md` listed only the Sellmeier
+  materials (missing `SiO2-Franta`); and `croak.solver`'s docstring described
+  `Retriever` as the base of two solvers rather than of all of them.
+
+## [0.1.0] — unreleased
+
+First public release.
+
+croak was developed privately before being open-sourced, and that history was
+squashed for release, so this changelog starts here. The design rationale worth
+keeping lives in the documentation: see [Explanation](docs/explanation/) for
+the physics and algorithms, and the [how-to guides](docs/howto/) for the
+practical trade-offs.
+
+### Added
+
+Everything. The initial release provides:
+
+- **Retrieval.** Nine solvers over one forward model, selected by an `algorithm=`
+  string: `copra`, `copra-jax`, `lbfgs`, `lbfgs-hand`, `lbfgs-ad`, `lbfgs-optx`,
+  `lm`, `lm-optx` and `cma-es`. Four algorithm families — COPRA, L-BFGS,
+  Levenberg–Marquardt and a derivative-free CMA-ES global search — with the rest
+  on-device JAX reimplementations.
+- **Forward model.** SHG, SD and PG (transient-grating) interactions, thin or
+  propagated through a dispersive medium by Gauss–Legendre depth quadrature.
+- **Gradients both ways.** A JAX model differentiable end to end, plus a
+  hand-derived Wirtinger adjoint for the core model, cross-checked against each
+  other to ~1e-6.
+- **Geometric time smearing.** The pulse-front-tilt instrument response of a
+  non-collinear BOXCARS geometry, as a two-parameter kernel that can be computed
+  from the mask or fitted from the data.
+- **Materials and dispersion.** Built-in Sellmeier materials, tabulated measured
+  index, pressure-scaled gases, seven chirped-mirror designs and five beam-path
+  coatings, plus an optional bridge to refractiveindex.info.
+- **Workflow.** Loading (HDF5/NPZ/CSV, unit and axis detection, simulated scans),
+  preprocessing (fringe and DC filtering, Takeda de-fringing, arPLS baseline
+  removal, regridding), marginal consistency checks, post-processing, dispersion
+  tuning, plotting and saving.
+- **Uncertainty.** Parametric and resampling bootstraps, a substrate-thickness
+  systematic, fast Laplace covariance, coverage calibration, and propagation of
+  an interval to another point in the beamline.
+- **Interfaces.** A library-first API, a PyQt6 wizard GUI, a headless session
+  replay engine, and a `croak` CLI that replays a saved session or generates a
+  standalone script from it.
+
+[Unreleased]: https://github.com/LupoLab/croak/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/LupoLab/croak/releases/tag/v0.1.0