feat: symbolic superposition — learn the shift law that collapses a curve family

[jkitchin]

Closes #14.

Adds jaxsr.superposition, which discovers a symbolic transform collapsing a family of curves indexed by a condition (time–temperature superposition and its relatives), instead of returning a table of per-curve shift factors that cannot extrapolate to a condition never measured.

Built on all five supporting issues, now in main: #15 (SurfaceDerivatives), #16 (basis-identity keying), #17 (pipeline-level resampling), #18 (add_block), #19 (sample_weight).

Mechanism

The differential strategy from the issue. Fit one smoothed surface per channel, use

y_q = σ·s'(q)·y_x + v'(q)

to eliminate the unknown master curve entirely, sparse-regress s' and v' against structured Θ(q) ⊙ y_x | Θ(q) blocks, then integrate back analytically with the anchor s(c_ref) = 0.

Candidate families are arrhenius, wlf (denominator constant fitted by profile likelihood) and polynomial. Each term carries an exact antiderivative, so the recovered law is symbolic rather than a quadrature table — and a test numerically integrates every derivative term and checks it against its antiderivative.

The two findings are load-bearing, not documentation

The transform is identifiable; the equation is not. shift_expression_'s own docstring says it is not the headline result. The reported quantities are shift_factors() and effective_activation_energy(), which are stable across structural variants.

The quick-start output in the guide is a real run, deliberately kept because it is unflattering: on data generated from a pure Arrhenius law, with the Arrhenius basis available, the search picked the WLF term with c2 = 1.070 instead. Arrhenius is WLF at c2 = 1, so they are the same function and no information criterion can separate them. The transform is right to 0.02 decades; the named family is wrong.

Expression stability is anti-correlated with validity. So the verdict comes from leave-one-condition-out collapse against a noise floor measured from the raw data before any surface is fitted, graded supported / weakly_supported / not_supported. A test pair reproduces the separation:

	held-out collapse
genuine superposition	1.0× the noise floor
thermorheologically complex control	7.9× the noise floor

A companion test asserts the control's in-sample collapse still looks respectable — that is the whole reason the module exists.

Each withheld condition also records the shift that would have aligned it best, so a bad collapse can be attributed either to the law extrapolating wrongly or to the curve not collapsing under any shift at all.

Using #19

The issue filed sample_weight as a dependency, so the module uses it. Rows are weighted by 1/σ² of the estimated target, since derivative standard errors blow up at the edges of the condition range — exactly where a shift law is most tempted to bend. Measured over six noise realizations at 3% noise:

weighting	median shift error	worst	E_eff (true 55.9)
"none"	0.023 decades	0.038	52.9 ± 1.8 kJ/mol
"derivative_se" (default)	0.013 decades	0.023	54.1 ± 1.2 kJ/mol

That lands on the 54.2 ± 1.3 reported in the issue's Phase 0 study.

Conventions checked rather than assumed

• Domain sign. It names the transform rather than changing it — the collapse is identical either way, so getting it wrong flips every shift factor and E_eff while the plots still look perfect. No guessing from data; there is a test asserting exactly this.
• Kelvin. Non-positive values rejected; a column topping out below 150 warns. Reciprocal-condition families are refused outright for a non-temperature condition.
• Dimensionless q, so design columns stay order-one instead of mixing T⁻² against polynomials.
• The master-curve smoother is fitted separately from the derivative surface, so the discovery does not certify itself.

Scope note

Strategy 2 (direct collapse) is not implemented — the issue ranked it as worth doing only after strategy 1 establishes baselines. Its known bias is documented rather than hidden: over-smoothing in the condition direction flattens s' and biases E_eff a few percent low, which is visible in the table above.

Verification

• Full suite 886 passed, 10 skipped (78 new tests)
• Green on the NumPy backend (scripts/test_under_numpy.py, 28 s) — no new JAX API surface needed shim additions
• black --check and ruff check clean
• Both guides' worked examples executed verbatim; the guide's sample output is a real run
• src/jaxsr/skill/ re-synced from .claude/skills/jaxsr/

Also adds docs/guides/superposition.md, the matching skill guide with a SKILL.md routing entry, an API reference page, and CHANGELOG/README entries.

---

Generated by Claude Code