spacecore 0.4.0__tar.gz → 0.4.2__tar.gz

{spacecore-0.4.0 → spacecore-0.4.2}/CHANGELOG.md

@@ -7,8 +7,70 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.2] — 2026-07-01
+
 ### Added
 
+- **Jordan spectral primitives** on every Jordan-algebra space: `trace`,
+  `determinant`, and the algebra identity `unit()`, derived from the spectrum and
+  batch-axis preserving. Hermitian `trace` reads the diagonal (no eigendecomposition);
+  tree/stacked spaces are direct sums, so `trace` is additive and `determinant`
+  multiplicative (#56).
+- **Lazy functional algebra** mirroring `LinOp`: `SumFunctional`, `ScaledFunctional`,
+  `ShiftedFunctional` (affine `F + c`), and `ZeroFunctional`, wired to
+  `Functional.__add__` / `__sub__` / `__neg__` / `__mul__` / `__rmul__` and the
+  `make_functional_sum` / `make_scaled_functional` / `make_shifted_functional`
+  factories. Gradients combine through the domain's `add`/`scale` (metric-correct on
+  tree/stacked/weighted domains), and a complex scalar conjugates on the gradient
+  side (#60).
+- **`Functional.value_and_grad`** — a fused evaluator (base default returns
+  `(value, grad)`; subclasses may override with a single-pass AD) — and
+  `value`/`grad` now accept auxiliary `*args, **kwargs` (#51).
+- **Structure-preserving tree spectra**: `TreeSpace.spectrum(x, structured=True)`
+  returns a `treedef`-shaped tree of per-leaf eigenvalues, and
+  `TreeSpectralDecomposition` carries the `treedef` with a `to_tree()` view. The
+  flat `spectrum(x)` is unchanged (#58).
+
+### Changed
+
+- **`minimize_optax` is now a compiled, convergence-aware driver** (breaking): the
+  whole loop runs inside `jax.jit(jax.lax.while_loop(...))` with the fused
+  `value_and_grad` cached once per iteration; on-device `grad_norm <= tol` and
+  finiteness stopping; four-column progress logging (iteration · value · ΔF ·
+  grad norm) + a preallocated history buffer with post-hoc `progress_callback`
+  replay; an optional `project` retraction hook; and a rich `OptaxResult`
+  (success/status/message/iters/`nfev`/`njev`/`n_linesearch_steps`/history/timing/
+  `x_element`). The old fixed-`steps` eager loop is removed (#54).
+
+## [0.4.1] — 2026-06-28
+
+### Added
+
+- The **`bench` benchmark submodule** is brought under version control and
+  aligned to the agreed 0.4.1 micro-surface (ADR-023,
+  `docs/dev/0.4.1-bench-surface.md`): probes measure per-call SpaceCore overhead
+  against a hand-optimal pure-array-library bare, across `space` / `linop` /
+  `functional` only (linalg, the synthetic kernel-comparison probes,
+  `check_member`, tree-space, and generated-linop probes removed). New
+  **configuration-regime axis** (`baseline` / `dispatch` / `dispatch_cache` /
+  `verify`) times the same probe under the ADR-016 dispatch and ADR-022 caching
+  toggles, recording a within-run `regime_speedup`; block operators are measured
+  uniform **and** ragged. The interactive HTML dashboard gains a problem-size
+  range slider, a backend/family/status/size/check/search/speedup filter set
+  that drives a fully **filter-reactive** summary and diagnosis section, a
+  bottom-of-page tag legend, and zero-count-status hiding. Every backend runs in
+  float64 for a fair comparison against the NumPy reference (JAX via
+  `enable_jax_x64`, Torch via `enable_torch_x64`); the sole exception is Apple
+  MPS (float32-only hardware), where the device probe builds a float32 case and
+  the correctness gate widens accordingly. The float64-aware tolerance is shared
+  by the verdict and diagnosis layers. **JAX is benchmarked only at
+  `check_level="none"`** and **jits both the SpaceCore call and the bare
+  reference**, comparing their post-compile steady state (the warmup absorbs
+  compilation, so the speedup is jitted-vs-jitted with compilation excluded);
+  each side's compile latency is recorded and reported separately (two
+  `sc compile` / `bare compile` columns). The pair is resolved **symmetrically** —
+  if either side is not jittable, both are timed eagerly, so a comparison is never
+  eager-vs-jitted. Tooling only — `spacecore` never imports `bench`.
 - ADR-016 optimized-kernel **dispatch** is accepted and implemented (off by
   default). `KernelSpec` gains `dispatch_key`, `priority`, and an optional
   shape-only `cost` estimator (`KernelCost`); a spec that names a `dispatch_key`
@@ -36,10 +98,64 @@ and the project adheres to [Semantic Versioning](https://semver.org/).
   shape-only `KernelCost` and the dispatcher gates it on the memory budget. All
   three route only under `dispatch_mode("on"/"verify")`; dispatch stays off by
   default. Each has a correctness reference and a `python -m bench` probe.
-- `NumpyOps.free_memory_bytes()` reports available system RAM via the optional
-  `psutil` dependency (returns `None` — "no fuse" — when `psutil` is absent), so
-  the dispatcher's memory gate can size materializing fast paths on the CPU
-  backend.
+- `NumpyOps.free_memory_bytes()` reports available system RAM via `psutil` (now a
+  required core dependency), so the dispatcher's memory gate can size
+  materializing fast paths on the CPU backend.
+- Five more dispatch-eligible batched-matmul kernels (exact, `rtol=atol=0`,
+  NumPy-only until cross-backend bit-exactness is verified) extend the catalog to
+  the adjoint and batched directions, each wired through `dispatch` at its own new
+  key with a shape-only `KernelCost` and a `Class::method` correctness reference:
+  `block-diagonal-uniform-dense-batched-rapply` / `-vapply` / `-rvapply` (under
+  `linop.block_diagonal.rapply` / `.vapply` / `.rvapply`) and the broadcast-no-sum
+  folds `stacked-uniform-dense-batched-apply` /
+  `sum-to-single-uniform-dense-batched-rapply` (under `linop.stacked.apply` /
+  `linop.sum_to_single.rapply`). The adjoint folds exploit the Euclidean-flat
+  adjoint and so guard on `EUCLIDEAN_FLAT`; the batched folds use the dense core's
+  transpose-on-right orientation. All five reuse one shared
+  `spacecore.kernels.specs._batched` helper (stack uniform flat-dense matrices into
+  a single batched `matmul`) instead of duplicating the fold. The
+  `BlockDiagonalLinOp` (`rapply`/`vapply`/`rvapply`), `StackedLinOp` (`apply`) and
+  `SumToSingleLinOp` (`rapply`) call sites are wired through `dispatch`;
+  dispatch-off is result-identical to the prior inline paths. Off by default.
+- `SparseLinOp` is confirmed to need no dispatch spec: every direction is already a
+  single optimal backend call — one SpMV for `apply`/`rapply` and one batched SpMV
+  over the stacked right-hand side for `vapply`/`rvapply` — so the reserved
+  `linop.matvec.sparse` key stays inert (a spec would add only dispatch overhead).
+- ADR-021 **lazy-operator-algebra `fuse()`** (Tier-2 explicit simplification):
+  `LinOp.fuse(*, materialize=False)` collapses each maximal subtree of dense
+  operators into a single materialized `DenseLinOp` — a composition becomes the
+  matrix product `M_A @ M_B`, a scalar folds into the matrix, a sum of dense terms
+  is added into one matrix, an adjoint fuses its operand, and block/tree operators
+  fuse each component (so a composed-dense block becomes foldable by the
+  block-diagonal dispatch spec). It is mathematically equal to the original up to
+  floating-point rounding (fusion reassociates the arithmetic) and is
+  adjoint-consistent on any geometry — the shared middle-space Riesz maps cancel,
+  so fusion is not restricted to Euclidean spaces. A matrix-free operand is
+  **never** densified by the default `fuse()`; `fuse(materialize=True)` is the
+  explicit opt-in that densifies it (via the `to_dense` basis probe) so an
+  enclosing expression can collapse. Lives in `spacecore.linop`, separate from the
+  ADR-016 dispatch layer.
+- ADR-022 **materialized-form cache** for the uniform batched folds: the
+  input-independent stacked block-matrix array `ops.stack([matrix(p) for p in
+  parts])` is now built once and reused across applies instead of re-stacked every
+  call. `BlockDiagonalLinOp`, `StackedLinOp`, and `SumToSingleLinOp` carry their
+  `parts` in a `spacecore.kernels.CachedStackParts` tuple that memoizes the stack
+  per matrix accessor (`_A2` apply, `_A2H` adjoint, `_A2T`/`_A2H.T` batched), so a
+  routed fold pays one `matmul` with no re-stack. The memo is built lazily on first
+  optimized use (NumPy-only, and only while dispatch is `on`/`verify`), so the
+  default `off` path is untouched. It is a derived value: excluded from operator
+  identity (`__eq__`/`__hash__`) and from the pytree (`tree_flatten` re-normalizes
+  `parts` to a plain tuple, so a round-trip rebuilds an empty cache), and a
+  matrix-free operand is never cache-materialized (the fold is inapplicable). The
+  dispatcher stays stateless. Dispatch-decision caching remains out of scope
+  (ADR-022 §"Decision caching").
+
+### Fixed
+
+- Corrected stale `correctness_ref` node ids on two shipped `KernelSpec`s
+  (`composed-chain-apply`, `block-diagonal-dense-apply`) that named non-existent
+  module-level test nodes instead of the real `Class::method` ids (ADR-016
+  requires the reference pin an existing test).
 
 ## [0.4.0] — 2026-06-24
 

{spacecore-0.4.0 → spacecore-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spacecore
-Version: 0.4.0
+Version: 0.4.2
 Summary: Backend-agnostic vector spaces and linear operators.
 Author: Pavlo Pelikh
 License-Expression: Apache-2.0
@@ -17,6 +17,7 @@ License-File: LICENSE
 Requires-Dist: array-api-compat>=1.14.0
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: optree>=0.17.0
+Requires-Dist: psutil>=5.9.0
 Requires-Dist: scipy>=1.17
 Provides-Extra: jax
 Requires-Dist: jax>=0.9.1; extra == "jax"
@@ -35,6 +36,7 @@ Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
 Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
 Requires-Dist: sphinx-design>=0.6; extra == "docs"
 Requires-Dist: numpydoc>=1.8; extra == "docs"
+Requires-Dist: ipython>=8.0; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"

spacecore-0.4.2/docs/dev/0.4.1-bench-surface.md

@@ -0,0 +1,159 @@
+# 0.4.1 Benchmark surface
+
+Implementation checklist for the microbenchmark surface specified by
+[ADR-023](adr/023_benchmark_framework.md). This is the **agreed scope** of *what
+gets measured* and *what each operation is compared against*. Once an operation
+is listed here it gets a probe whose `bare` callable is the **hand-optimal
+pure-array-library** implementation (see ADR-023 "The pure-array-library
+baseline").
+
+## Scope decisions
+
+Settled in review:
+
+- **`linalg` module — out.** Iterative solvers are not in the micro surface.
+- **`kernel` probe family — out as a *family*.** The optimized folds are not
+  probed directly. They are still exercised: the `linop.block_diagonal` /
+  `composed` / `stacked` / `sum_to_single` probes route through them under the
+  `dispatch` / `dispatch+cache` regimes (below), so the kernel payoff is measured
+  on the *real operator*, not a synthetic kernel probe.
+- **`check_member` and similar — out.** Operations with no real array-library
+  counterpart (the bare floor is a no-op) are not measured; they would report
+  "pure abstraction overhead" with nothing to compare against.
+- **Tree operations — out.** `space.tree.*` is composition of leaf methods: if
+  the leaf methods are efficient, the tree op is efficient modulo `optree`
+  traversal time. Measuring it adds no information beyond the leaf probes plus a
+  fixed `optree` cost.
+- **Block-structured operators — uniform AND ragged.** `block_diagonal`,
+  `stacked`, and `sum_to_single` each get a **uniform-blocks** variant (where a
+  batched-`matmul` fold exists) and a **ragged-blocks** variant (where it does
+  not). The pair is the point: uniform shows the fold's win; ragged shows the
+  abstraction adds ~nothing when no fast path applies.
+
+Author rulings on the three open items (revise if disagreed):
+
+- **`generated_{dense,diagonal}` — drop.** They duplicate `dense`/`diagonal`
+  built via a generator; generator-construction is not a per-call hot path.
+- **Elementwise-Jordan ops — keep, low priority.** `spectrum` /
+  `spectral_decompose` / `star` / `from_spectrum` are mathematically thin on an
+  elementwise algebra but exercise the real Jordan API path; kept, flagged P2.
+- **Bare for ragged blocks** = idiomatic per-block Python loop (or
+  `scipy.linalg.block_diag @ x` where assembling is the honest user choice), not
+  a forced batched form.
+
+## Configuration regimes
+
+Every `linop` probe is timed under each regime so the ADR-016 dispatch and
+ADR-022 caching wins are *measured*, not assumed. Regimes are driven by the real
+API (`spacecore.kernels.dispatch_mode`, `set_memory_budget_fraction`):
+
+| Regime | Dispatch | Materialized-form cache | How |
+|---|---|---|---|
+| `baseline` | off | inert | `dispatch_mode("off")` — today's default path |
+| `dispatch` | on | cold each timed call | `dispatch_mode("on")` + per-call cache reset |
+| `dispatch+cache` | on | warm (reused) | `dispatch_mode("on")`, operator reused across calls |
+| `verify` | verify | warm | `dispatch_mode("verify")` — correctness, not headline speed |
+
+**Cache reality (important).** SpaceCore has *no* cache on/off flag: the ADR-022
+memo (`CachedStackParts`) builds lazily on first optimized use and lives on the
+operator instance. Because `bench.harness.time_op` reuses one operator across all
+repeats, the steady-state dispatch-on measurement *already* includes the cache.
+To isolate the cache's contribution we therefore need two regimes:
+
+- `dispatch+cache` is the natural reuse path (memo warm) — the full optimized
+  result.
+- `dispatch` forces a **cold cache each timed call**. ADR-022 documents that a
+  pytree round-trip re-normalizes `parts` to a plain tuple and rebuilds an empty
+  cache, so the runner resets the memo via that round-trip before each sample.
+  This requires the probe to **expose its routed operator** to the runner (a
+  small `ProbeCase` extension), so the cache can be reset without rebuilding the
+  whole operator.
+
+`space` and `functional` probes have no dispatch path and run `baseline` only.
+The regime is part of every result row's coordinate and a group-by / pivot axis
+in the dashboard.
+
+## Operation surface
+
+`Obvious bare?`: ✅ one idiomatic library expression · 🟡 idiomatic but
+multi-line / per-backend divergence · P-tier = build priority.
+
+### Family: `space`
+
+| Operation | Bare (idiomatic, per backend) | Obvious? | Tier | Notes |
+|---|---|---|---|---|
+| `space.add` | `x + y` | ✅ | P0 | |
+| `space.scale` | `a * x` | ✅ | P0 | |
+| `space.inner` | `np.vdot(x, y)`; weighted `vdot(x, w*y)` | ✅ | P0 | weighted metric folds weight in |
+| `space.norm` | `np.linalg.norm(x)`; weighted `sqrt(vdot(x, w*x))` | ✅ | P0 | |
+| `space.zeros` | `np.zeros(shape, dtype)` | ✅ | P1 | |
+| `space.flatten` / `unflatten` | `x.ravel()` / `x.reshape(shape)` | ✅ | P1 | |
+| `space.convert.self` | `np.asarray` / `jnp.asarray` / `torch.as_tensor` | ✅ | P1 | cross-backend conversion |
+| `space.stacked.{add,inner,zeros}` | vectorized op over leading batch axis | ✅ | P1 | |
+| `space.hermitian.inner` | `np.vdot(A, B).real` (Frobenius) | ✅ | P1 | |
+| `space.hermitian.symmetrize` | `(A + A.conj().T) / 2` | ✅ | P1 | |
+| `space.hermitian.spectral_decompose` | `np.linalg.eigh` | ✅ | P1 | `spectrum` dropped — `spectrum`=`eigh(x)[0]`, same `eigh` |
+| `space.hermitian.from_spectrum` | `(U * λ) @ U.conj().T` | ✅ | P1 | |
+| `space.elementwise_jordan.{spectral_decompose,star,from_spectrum}` | identity / `x.conj()` | 🟡 | P2 | thin; `spectrum` dropped (== `spectral_decompose` minus the `None`) |
+
+### Family: `linop` (each run under all four regimes)
+
+| Operation | Bare (idiomatic, per backend) | Obvious? | Tier | Notes |
+|---|---|---|---|---|
+| `linop.dense.{apply,rapply}` | `A @ x` / `A.conj().T @ y` | ✅ | P0 | rapply = conj-transpose on Euclidean |
+| `linop.dense.{vapply,rvapply}` | `A @ X` (batched matmul) | ✅ | P0 | |
+| `linop.dense.to_dense` | return `A` | ✅ | P2 | trivial |
+| `linop.diagonal.{apply,rapply,vapply,rvapply}` | `d * x` / `d.conj() * y` | ✅ | P0 | |
+| `linop.sparse.{apply,rapply}` | `scipy.sparse` SpMV; jax `BCOO`; `torch.sparse` | 🟡 | P1 | numpy obvious; jax/torch sparse less standard |
+| `linop.identity.apply` | `x` | ✅ | P2 | |
+| `linop.zero.{apply,rapply}` | `np.zeros_like(codomain)` | ✅ | P2 | |
+| `linop.scaled.apply` | `a * (A @ x)` | ✅ | P1 | |
+| `linop.composed.{apply,rapply}` | `A @ (B @ x)` | ✅ | P0 | dispatch: zero/identity elision |
+| `linop.summed.apply` | `A @ x + B @ x` | ✅ | P1 | |
+| `linop.block_diagonal.{apply,rapply}` — **uniform** | one batched `matmul` over stacked blocks | ✅ | P0 | dispatch fold target |
+| `linop.block_diagonal.{apply,rapply}` — **ragged** | per-block loop / `block_diag @ x` | 🟡 | P0 | no fold → loop is honest floor |
+| `linop.stacked.apply` — **uniform** / **ragged** | batched matmul / loop + concat | ✅ / 🟡 | P1 | |
+| `linop.sum_to_single.apply` — **uniform** / **ragged** | batched matmul + reduce / loop + sum | ✅ / 🟡 | P1 | |
+| `linop.matrix_free.diagonal_action.{apply,rapply}` | `d * x` | ✅ | P1 | |
+| `linop.matrix_free.fft_action.apply` | `np.fft.fft(x)` (`jnp.fft`, `torch.fft`) | ✅ | P1 | |
+| `linop.matrix_free.shift_action.apply` | `np.roll(x, k)` | ✅ | P1 | |
+
+### Family: `functional`
+
+| Operation | Bare (idiomatic, per backend) | Obvious? | Tier | Notes |
+|---|---|---|---|---|
+| `functional.inner_product.value` | `np.vdot(a, x)` | ✅ | P0 | |
+| `functional.inner_product.grad` | return `a` (Riesz rep) | ✅ | P0 | metric maps coordinate↔Riesz on weighted spaces |
+| `functional.quadratic.value` | `0.5*vdot(x, A@x)` or `0.5*‖Ax−b‖²` | ✅ | P1 | |
+| `functional.matrix_free.value` | `np.vdot(a, x)` | ✅ | P1 | |
+| `functional.generated_linear.value` | `np.vdot(a, x)` | ✅ | P2 | |
+
+## Implementation phases
+
+1. **Regime infrastructure** — `bench/_regimes.py` (regime enum + per-regime
+   context), `regime` field on `ProbeResult` (+ `_io` round-trip), runner sweep
+   (`regimes=("baseline",)` default, non-baseline only for dispatch-eligible
+   families), `regime_speedup` derived metric, smoke test. *Non-destructive.*
+2. **Cache regime** — extend `ProbeCase` to expose the routed operator; runner
+   resets the memo (pytree round-trip) before each timed sample for the
+   `dispatch` regime; `dispatch+cache` reuses. Test the cold/warm distinction
+   actually moves on a uniform block fold.
+3. **Ragged block probes** — add ragged variants for `block_diagonal` /
+   `stacked` / `sum_to_single` with per-block-loop bares.
+4. **Bare-baseline audit** — verify every `bare` is hand-optimal per backend and
+   matches the reference value (runner already records `bare` error); fix any
+   strawman bares.
+5. **HTML aggregation** — embed raw cells + client-side group-by/pivot
+   (size / module / operation / backend / device / check_level / **regime**),
+   geometric-mean speedup, worst-case min, correctness gate.
+6. **Comparison / track** — `bench/_compare.py` join-then-diff at the group
+   level (regime in the join key), seed-jitter noise band, environment guard;
+   `track` for release-over-release trend.
+
+Phases 1–4 are the measurement core; 5–6 are reporting. The out-of-scope
+families have been removed from the suite to match this table: `linalg` probes,
+the synthetic `kernel`-comparison probes (folds still measured via `linop` under
+the dispatch regimes), `space.check_member`, the `space.tree.*` probes, and the
+`linop.generated_{dense,diagonal}` probes are deleted; `functional.generated_linear.value`
+and the elementwise-Jordan probes are kept. Final surface: `space` / `linop` /
+`functional` only.

spacecore-0.4.2/docs/dev/adr/021_lazy_operator_algebra_and_simplification.md

@@ -0,0 +1,131 @@
+# ADR-021: Lazy operator algebra and simplification
+
+## Status
+
+Accepted
+
+## Context
+
+SpaceCore builds operator expressions lazily: `A @ B`, `A + B`, `c * A`, `A.H`
+construct `ComposedLinOp` / `SumLinOp` / `ScaledLinOp` / `_AdjointViewLinOp`
+nodes rather than evaluating anything. Two distinct concerns have been
+conflated:
+
+1. **Dispatch** — mapping an *operation* to its most efficient *array*
+   implementation at apply time (one batched `matmul` vs a per-block loop, an
+   SpMV, etc.). This is [ADR-016](016_kernel_layers.md), now scoped to dense and
+   sparse array execution, and held to a strict per-call rail: a routed spec
+   must be **bit-exact** to the inline path (`rtol == atol == 0`).
+
+2. **Lazy algebra** — simplifying the operator *expression* itself and
+   *multiplying operators where possible*: collapse `A @ I @ B` to `A @ B`, fold
+   `c · (d · A)` to `(c·d) · A`, multiply two dense operators into one matrix,
+   combine like terms. This rewrites the operator *once*, at construction or an
+   explicit step — not per call.
+
+These are different mechanisms at different times, and the dispatch exactness
+rail is the wrong constraint for the second: multiplying two dense operators and
+then applying is not bit-identical to applying them in sequence (floating-point
+addition is not associative), so under the ADR-016 rail "multiply operators
+where possible" could never fire automatically. Yet a one-time build is not a
+per-call equivalence contract — the user who asks to fuse `A @ B` into one
+matrix has accepted that single reassociation.
+
+Today the `make_composed` / `make_sum` / `make_scaled` factories already perform
+cheap local rewrites at construction (`A @ I → A`, `A @ 0 → 0`,
+`c · (d · A) → (c·d) · A`, flatten nested sums and drop zero terms, `(A*)* → A`
+via the cached adjoint view). There is no operator *multiplication*
+(`dense ∘ dense → one matrix`), no like-term combination, no composition-chain
+flattening into a single operator, and no user-facing control over fusion.
+
+## Proposed design
+
+Operator-expression simplification lives in `spacecore.linop` (the `make_*`
+factories plus a `fuse` API), **not** in `spacecore.kernels`, and splits into two
+tiers.
+
+**Tier 1 — automatic at construction.** Cheap, local, non-materializing rewrites
+run inside the `make_*` factories with no caller action. A rewrite is automatic
+iff it is `O(1)`-local in the expression and allocates no array proportional to
+operand size: identity elision, zero annihilation, scalar folding, sum
+flattening + zero-term removal, the adjoint involution. These already largely
+exist; this ADR names them a tier and fixes the boundary.
+
+**Tier 2 — explicit, opt-in fusion.** Materializing or contract-changing
+rewrites the caller must *request*, through a dedicated method / argument whose
+arguments decide what is fused: multiply `dense ∘ dense` into one matrix, form a
+Gram product `A.H @ A` as one materialized operator, flatten a composition chain
+into a single fused operator, combine like terms (`2A + 3A → 5A`). Surface:
+`expr.fuse(...)` and/or a `fuse=` argument on the algebra constructors (e.g.
+`fuse="dense"`, `materialize=True`). The materialization itself is the subject of
+[ADR-022](022_caching.md) (build it once, amortize over many applies).
+
+**The auto/opt-in boundary is cost and locality, not strict bit-exactness.**
+Tier-1 rewrites are cheap and local even when they reassociate at the ulp level
+(scalar folding computes `c·d` first, which can differ from `c·(d·…)` by one
+rounding); that is acceptable because the user invoking lazy algebra has accepted
+construction-time reassociation. Tier-2 fusion is gated on *materialization /
+contract change*, not on exactness.
+
+**Matrix-free is a hard rail in both tiers** ([ADR-008](008_linop_subclasses.md)):
+a matrix-free operand is never silently densified. Tier-1 rules never materialize
+it; Tier-2 fusion of a matrix-free operand requires the caller to explicitly opt
+into densification and thereby give up the matrix-free contract.
+
+## Decision
+
+1. Operator-expression simplification is a concern distinct from kernel dispatch
+   ([ADR-016](016_kernel_layers.md)); it lives in `spacecore.linop` (the `make_*`
+   factories and a `fuse` API), never in `spacecore.kernels`, and is not gated on
+   the ADR-016 bit-exact rail.
+2. Two tiers: cheap, local, non-materializing rewrites run automatically at
+   construction; materializing or contract-changing fusion is explicit and
+   argument-driven.
+3. The auto/opt-in line is cost and locality. Tier-1 rewrites may reassociate at
+   the ulp level; using lazy algebra accepts that.
+4. A matrix-free operand is never silently materialized in either tier.
+
+## Rationale
+
+Keeping the runtime dispatch rail strict and exact while giving the user a way to
+*buy* operator multiplication when they want it puts each kind of work where it
+belongs: construction-time tree rewriting for the algebra, runtime kernel
+selection for execution. It also resolves the contradiction that the dispatch
+exactness rail otherwise forbids the very "multiply operators where possible"
+the lazy algebra is meant to provide.
+
+## Alternatives considered
+
+- **Route operator multiplication through ADR-016 dispatch with `rtol=atol=0`.**
+  Rejected: the exact rail forbids the floating-point reassociation operator
+  multiplication inevitably introduces, so it would never auto-fire; and a
+  one-time build is not a per-call equivalence contract.
+- **Always-on eager fusion** (multiply operators at construction). Rejected:
+  surprising memory blowups (Gram, `dense ∘ dense`) and silent densification of
+  matrix-free operands. Materialization must be opt-in.
+- **No fusion at all** (keep only the existing cheap rewrites). Rejected: it
+  leaves "multiply operators where possible" — an explicit goal — unaddressed.
+
+## Consequences
+
+- New public API surface: a `fuse` method / argument with documented options;
+  each fusion documents what it materializes and what it costs.
+- The existing `make_*` cheap rewrites are retroactively framed as Tier 1.
+- Tests pin Tier-1 rewrites as result-equivalent (within ulp where they
+  reassociate) and Tier-2 fusion as opt-in and matrix-free-safe.
+- This ADR is the prerequisite framing for [ADR-022](022_caching.md): the cached
+  thing is the Tier-2 materialized form.
+
+## Contributor invariants
+
+- Cheap, local, non-materializing operator rewrites go in the `make_*` factories
+  (Tier 1). Materializing or contract-changing fusion is explicit, argument-
+  driven, and never automatic (Tier 2).
+- A matrix-free operand ([ADR-008](008_linop_subclasses.md)) is never densified
+  without explicit caller opt-in.
+- Expression simplification is not kernel dispatch: do not add operator-algebra
+  rewrites to `spacecore.kernels`, and do not gate them on the ADR-016 exact
+  rail.
+- A construction-time rewrite must preserve the operator's mathematical action
+  (within ulp where it reassociates) and its declared domain/codomain and
+  scalar-field/dtype identity.

spacecore-0.4.2/docs/dev/adr/022_caching.md

@@ -0,0 +1,156 @@
+# ADR-022: Caching of materialized and fused operator forms
+
+## Status
+
+Accepted
+
+## Context
+
+Two parts of SpaceCore materialize an array from operands:
+
+- The [ADR-016](016_kernel_layers.md) dispatch folds (uniform block-diagonal and
+  stacked / sum-to-single batched `matmul`) stack `K` cached matrices into one
+  `(K, m, n)` array per call.
+- The [ADR-021](021_lazy_operator_algebra_and_simplification.md) explicit fusions
+  (`dense ∘ dense → one matrix`, Gram `A.H @ A`, a flattened composition chain)
+  build a fused matrix.
+
+Done per call, this materialization is repeated work. The 0.4.1 dispatch
+measurements showed the per-call stacking allocation is a meaningful fraction of
+the optimized path and a reason the dense folds do **not** beat the per-block
+generic loop on the NumPy/CPU backend: NumPy's small-matmul loop is already
+cheap, and re-stacking every apply only adds cost.
+
+ADR-016 already states the principle — a super-linear materialization is a
+*build-time* decision amortized over many applies, not a per-call one — but no
+caching mechanism exists yet. Two cache candidates surfaced during the 0.4.1
+work:
+
+1. caching the **materialized array** (the stacked / fused matrix) on the
+   operator, so each apply skips the re-stack; and
+2. caching the **dispatch decision** (which spec applies for a fixed operator),
+   so each apply skips the `applicable()` re-scan.
+
+The maintainer scoped (2) out for now. This ADR therefore decides (1) — the
+build-time materialized form — and records (2) as considered and deferred.
+
+## Proposed design
+
+**What is cached (precisely).** The cache target is the **input-independent
+factor** of a batched fold: the stacked operand-matrix array
+
+```python
+ops.stack([matrix(p) for p in parts])   # shape (K, r, c)
+```
+
+built today on every apply in `batched_matvec` / `batched_right_matmul`
+(`spacecore/kernels/specs/_batched.py`). It depends only on the operator's fixed
+blocks, so it is identical across applies — yet a uniform block-diagonal /
+stacked / sum-to-single operator rebuilds it each call because it has no field to
+keep it in. That, and only that, is what gets cached. Explicitly:
+
+- **Cached:** the stacked operand matrices, *per matrix accessor exercised* —
+  `_A2` for the forward action (apply), `_A2H` for the Euclidean-adjoint action
+  (rapply), and the right-matmul stack. An operator applied in more than one
+  direction therefore holds more than one cached stack.
+- **Not cached:** the stacked *input* vectors (`ops.stack(list(vecs))`) and the
+  `matmul` result — both depend on the call argument and differ every apply.
+- **Not new mechanism:** the [ADR-021](021_lazy_operator_algebra_and_simplification.md)
+  fusions (`dense ∘ dense`, Gram `A.H @ A`, a flattened chain) already persist
+  their materialized matrix in the `DenseLinOp` that `fuse()` returns. They need
+  no cache field; they appear here only as the explicit opt-in amortization
+  branch below. The genuinely uncached case is the dispatch fold, which
+  materializes transiently on the per-call path and returns a result rather than
+  an operator.
+
+**Build-time materialized-form cache.** An operator that benefits from a
+materialized fast path (uniform block-diagonal, stacked / sum-to-single) caches
+the stacked operand-matrix array(s) above once — at construction or first use —
+behind two gates:
+
+- the ADR-016 **memory gate**: the predicted `peak_bytes` fits the context's
+  memory budget, and a matrix-free operand is never materialized; and
+- an **amortization check**: the form is cached only when the operator is
+  expected to be applied enough times to repay the materialization, or when the
+  caller explicitly opts in via [ADR-021](021_lazy_operator_algebra_and_simplification.md)
+  fusion.
+
+Subsequent applies route to the already-materialized array at `O(1)` extra, so
+the per-apply cost is one `matmul` with no re-stacking. This is the lever that
+makes a materializing fold competitive once it routes — most importantly on
+accelerators, where the batched call is the win and the one-time stack is
+negligible against many applies.
+
+**Pytree hazard (mandatory).** `BlockDiagonalLinOp` / `StackedLinOp` /
+`SumToSingleLinOp` and the dense operators are `@jax_pytree_class`. A cached
+array must not corrupt `tree_flatten` / `tree_unflatten`: the cache is a derived,
+reconstructable value, so it is either excluded from the pytree (recomputed
+lazily after `tree_unflatten`) or carried consistently as aux — never silently
+turned into an extra differentiable/transformable leaf. For the same reason the
+cache is **excluded from the operator's mathematical identity** (`__eq__` /
+`__hash__`), exactly as raw array values are.
+
+**Decision caching (deferred).** Caching the applicable-spec selection per
+operator instance — to remove the per-call `applicable()` re-scan over the `K`
+blocks — was considered. It is deferred: the maintainer scoped it out, and the
+0.4.1 measurement showed the dispatcher's per-call overhead (≈6–7 µs, including a
+`psutil` free-memory query) is dominated by the public method's boundary
+validation, so decision caching is not the first lever. If it is revisited, the
+cache key is the operator's structural signature (invariant for a fixed
+operator), the memo lives in the **dispatcher** (not operator/functional class
+bodies, per ADR-016), and it must respect the dynamic `dispatch_mode` (cache only
+the `"on"` selection; `"verify"` must always run both; the cheap mode check still
+runs each call).
+
+## Decision
+
+1. The stacked operand-matrix array(s) of a batched fold — the input-independent
+   `ops.stack([matrix(p) for p in parts])`, per accessor (`_A2`, `_A2H`,
+   right-matmul) — may be cached on the operator as a derived value, gated by the
+   ADR-016 memory gate **plus** an amortization check, and excluded from operator
+   identity and (pytree-safely) from `tree_flatten`. The input-vector stack and
+   the result are never cached. ADR-021 fusions already persist their matrix in
+   the returned `DenseLinOp` and need no new field.
+2. Caching never materializes a matrix-free operand ([ADR-008](008_linop_subclasses.md)).
+3. Dispatch-decision caching is out of scope for now. If added later, it lives in
+   the dispatcher, is keyed by structural signature, and respects `dispatch_mode`.
+
+## Rationale
+
+Turning a repeated per-call materialization into a one-time build amortized over
+many applies is the ADR-016 intent made concrete, and the measured way to make a
+materializing fold pay for itself once it routes. Keeping the cache a property of
+the operator (not the per-call path) preserves the matrix-free rail and the
+operator's mathematical identity, and keeps the dispatcher stateless.
+
+## Alternatives considered
+
+- **Per-call materialization (status quo).** Correct but re-stacks every apply —
+  the measured reason the dense folds lose on CPU.
+- **Eager, always-on materialization at construction.** Rejected: memory blowups
+  and silent densification of matrix-free operands; must be gated, amortized, and
+  opt-in.
+- **Decision caching as the primary lever.** Deferred: not the dominant cost per
+  the 0.4.1 measurement, and explicitly scoped out by the maintainer.
+
+## Consequences
+
+- A cache field (one slot per stacked accessor — `_A2`, `_A2H`, right-matmul) on
+  the block-diagonal / stacked / sum-to-single operators, with pytree-safe
+  handling and identity exclusion.
+- An amortization heuristic or explicit opt-in, tied to ADR-021 fusion.
+- Tests pin: cached stack == the per-call `ops.stack(...)` and cached apply
+  result == uncached result; the cache is excluded from `__eq__` / `__hash__` and
+  survives a pytree round-trip; a fold containing a matrix-free operand is never
+  cache-materialized.
+
+## Contributor invariants
+
+- A cached materialized form is derived and reconstructable: it is excluded from
+  `__eq__` / `__hash__` and from the operator's mathematical identity, and a
+  pytree round-trip must not depend on it.
+- Materialization caching obeys the ADR-016 memory gate and never densifies a
+  matrix-free operand ([ADR-008](008_linop_subclasses.md)).
+- Decision caching, if ever added, lives in the dispatcher (not operator /
+  functional class bodies, per [ADR-016](016_kernel_layers.md)) and respects the
+  active `dispatch_mode`.