Bench suite + Stable mode

.github/workflows/Benchmark.yml

@@ -0,0 +1,51 @@
+name: Benchmark
+
+# Runs the benchmark suite (benchmark/benchmarks.jl, the global `SUITE`) on each
+# relevant pull request and writes a comparison table to the job summary.
+#
+# How the comparison works (AirspeedVelocity.jl):
+#   * It benchmarks TWO git revisions — the base branch (`main`) and this PR's
+#     head commit — NOT a stored historical baseline.
+#   * Both revisions are checked out into separate temp environments and run in
+#     separate Julia processes, back-to-back on the SAME runner within this one
+#     job. The reported `ratio` is head/base (<1 faster, >1 slower).
+#   * Running both on the same machine cancels systematic hardware differences,
+#     but shared GitHub runners are still noisy (~±10–30% on microbenchmarks):
+#     trust this for order-of-magnitude / large regressions, not 5% wobble.
+#
+# Security: this uses the `pull_request` event (not `pull_request_target`), so a
+# fork's PR code runs with a read-only token and no secrets. Output goes to the
+# Actions job summary (`job-summary: "true"`) instead of a PR comment, so no
+# write token is ever needed — nothing is posted to fork (or same-repo) PRs.
+# View results under the workflow run's "Summary" tab.
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "src/**"
+      - "benchmark/**"
+      - "Project.toml"
+      - ".github/workflows/Benchmark.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    name: Benchmark PR vs main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: MilesCranmer/AirspeedVelocity.jl@action-v1
+        with:
+          julia-version: "1"
+          job-summary: "true"
+          # Default compares `main` against this PR's head SHA. Uncomment to
+          # restrict to a fast, low-noise subset of the suite in CI:
+          # filter: "special_functions,ebcm,linearization,postprocessing"

.github/workflows/README.md

@@ -21,6 +21,20 @@ It is split into:
 The local `just ci` command mirrors the core local checks: package tests,
 doctests, and documentation build.
 
+## Benchmarks
+
+`Benchmark.yml` runs the benchmark suite (`benchmark/benchmarks.jl`, the global
+`SUITE`) via [AirspeedVelocity.jl](https://github.com/MilesCranmer/AirspeedVelocity.jl)
+on pull requests that touch `src/`, `benchmark/`, or `Project.toml`. It
+benchmarks the PR head commit against `main` — both revisions are run
+back-to-back on the same runner (not against a stored baseline) — and writes a
+`ratio` comparison table to the workflow run's **Summary** tab. It uses the
+`pull_request` event with a read-only token and `job-summary: "true"`, so fork
+PR code never runs with a write token and nothing is posted as a comment.
+Shared CI runners are noisy, so treat the results as a guard for large
+regressions rather than sub-10% changes. Run the same suite locally with
+`just bench`.
+
 ## Maintenance
 
 - `CompatHelper.yml` opens compatibility-bound update pull requests.

.gitignore

@@ -8,9 +8,19 @@
 Manifest.toml
 .CondaPkg/
 
+# Benchmark result artifacts (benchmark/params.json is committed; raw run
+# outputs are machine-specific and stay local)
+/results*.json
+/benchmark/results*.json
+
 # Documentation artifacts
 /docs/build/
 
+# Intermediate Pluto render output (the committed copies live in
+# docs/src/examples/, which is tracked).
+/examples/*.md
+!/examples/README.md
+
 # Editor and OS metadata
 .DS_Store
 .idea/

CHANGELOG.md

@@ -0,0 +1,84 @@
+# 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 this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Work on top of `v0.4.0`. Includes a breaking change to solver selection, so the
+next release is expected to be `v0.5.0`.
+
+### Added
+
+- **Sh-matrix moment-separation method** for fast parameter sweeps:
+  `prepare_sh`, `transition_matrix(prep, λ, mᵣ)`, and `transition_matrix_spectrum`.
+  The geometry quadrature is computed once and reused, so wavelength /
+  refractive-index sweeps are cheap; for spheroids it also reproduces the
+  high-aspect stabilization analytically. Works for any axisymmetric shape.
+- **Two-layer solver API**: fixed-discretization solvers `EBCM`, `IITM`,
+  `ShMatrix`, and the `Iterative` convergence wrapper (with `ConvergencePolicy`),
+  selected via `transition_matrix(s, λ, solver)`.
+- **Stabilized high-aspect-ratio spheroids** (`stable = true`): the
+  cancellation-free `F⁺` formulation of Somerville, Auguié & Le Ru (2013),
+  available as `EBCM(nₘₐₓ, Ng; stable = true)` and, auto-converged, as
+  `Iterative(EBCM; stable = true)`.
+- **Performance benchmark suite** and a PR benchmark CI workflow
+  (AirspeedVelocity).
+- **`examples/` folder** with five runnable Pluto notebooks — shapes gallery,
+  angular scattering & polarization, orientation averaging, solver landscape, and
+  spectral sensitivity — rendered into the documentation site.
+
+### Changed
+
+- **(Breaking)** Solver selection moves to solver objects passed to
+  `transition_matrix(s, λ, solver)`. The keyword-based auto-converge
+  `transition_matrix(s, λ; threshold, …)` is replaced by
+  `Iterative(EBCM; threshold, …)`. The bare `transition_matrix(s, λ)` /
+  `calc_T(s, λ)` is unchanged (auto-converged classic EBCM).
+- Performance: factor `𝐐` once and reuse it across Jacobian slices instead of an
+  explicit `inv`; the IITM radial recursion solves `M \ X` instead of forming
+  `inv(M)`; the Sh-matrix precompute is optimized (coefficient precompute, folded
+  convolution, precision split, and an analytic-zeroing fast path for spheroids).
+- Documentation: the API reference now filters internal (underscore-prefixed)
+  docstrings and uses `checkdocs = :exported`.
+
+### Fixed
+
+- `prepare_sh` requires an even `Ng` only for shapes with an equatorial symmetry
+  plane (non-symmetric shapes accept odd `Ng`).
+- `transition_matrix_spectrum` validates that `λs` and `mᵣs` have matching lengths
+  instead of silently truncating to the shorter one.
+- `ricattibessely` handles `nₘₐₓ = 1`.
+- `cbrt` on `Double64` (DoubleFloats v1.9 returns a tuple).
+
+## [0.4.0] - 2026-06-04
+
+- Performance optimizations and the analytical linearization framework
+  (`LinearizationProblem`, `linearize_transition_matrix`, with Mie / EBCM / IITM
+  backends). See [#7](https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/pull/7).
+
+## [0.3.1] - 2026-01-18
+
+- Raise the `Wigxjpf` compatibility bound to v0.2; CI configuration updates.
+
+## [0.3.0] - 2025-04-03
+
+- Compatible with Julia 1.13.
+- Removed `ArbNumerics` from the dependencies; its types are no longer
+  re-exported (use `Arblib`'s `Arb`/`Acb`).
+
+## [0.2.0] - 2023-04-02
+
+- Early development release.
+
+## [0.1.0] - 2023-03-17
+
+- Initial release.
+
+[Unreleased]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/JuliaRemoteSensing/TransitionMatrices.jl/releases/tag/v0.1.0

benchmark/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+TransitionMatrices = "057c4241-e127-4181-840e-6b4b92e6eef5"
+
+[compat]
+BenchmarkTools = "1"
+julia = "1.10"

benchmark/README.md

@@ -0,0 +1,70 @@
+# Benchmarks
+
+Performance benchmark suite for `TransitionMatrices.jl`, built on
+[BenchmarkTools.jl](https://github.com/JuliaCI/BenchmarkTools.jl). The suite
+follows the standard Julia convention — `benchmark/benchmarks.jl` defines a
+single global `const SUITE::BenchmarkGroup` — so it works unchanged with both
+[PkgBenchmark.jl](https://github.com/JuliaCI/PkgBenchmark.jl) and
+[AirspeedVelocity.jl](https://github.com/MilesCranmer/AirspeedVelocity.jl).
+
+## Layout
+
+| File | Purpose |
+| --- | --- |
+| `benchmarks.jl` | Defines `SUITE` (consumed by every tool below). |
+| `runbenchmarks.jl` | Local runner: tune once, cache params, save results JSON. |
+| `Project.toml` | Isolated environment; dev-depends on the parent package. |
+| `params.json` | Cached `tune!` parameters (created on first run). |
+
+## Groups
+
+- `special_functions` — Riccati-Bessel and Wigner-d recursions (inner kernels).
+- `ebcm` — EBCM blocks, fixed-order solves, and end-to-end auto-convergence.
+- `iitm` — Invariant Imbedding T-Matrix (axisymmetric and N-fold).
+- `postprocessing` — far-field observables from a precomputed T-matrix.
+- `linearization` — analytical EBCM Jacobian (baseline for the `inv` → `lu` work).
+- `precision` — Float64 vs Double64 on the same EBCM block.
+
+## Running
+
+The simplest path uses the parent `justfile`:
+
+```sh
+just bench            # instantiate the env and run the whole suite
+```
+
+Or directly:
+
+```sh
+julia --project=benchmark -e 'using Pkg; Pkg.develop(path="."); Pkg.instantiate()'
+julia --project=benchmark benchmark/runbenchmarks.jl results-baseline.json
+```
+
+Run a single group while iterating:
+
+```julia
+julia --project=benchmark
+julia> include("benchmark/benchmarks.jl");
+julia> run(SUITE["ebcm"]; verbose = true)
+```
+
+## Comparing two revisions
+
+Capture a baseline, make your change, capture again, then judge:
+
+```julia
+using BenchmarkTools
+old = BenchmarkTools.load("results-baseline.json")[1]
+new = BenchmarkTools.load("results.json")[1]
+judge(minimum(new), minimum(old))   # :improvement / :regression / :invariant
+```
+
+`minimum` is used because it is the most noise-robust statistic for these
+deterministic numerical kernels.
+
+For automated cross-revision runs (and PR comments), AirspeedVelocity.jl reads
+the same `SUITE`:
+
+```sh
+benchpkg TransitionMatrices --rev=main,HEAD --bench-on=HEAD
+```