resona 0.4.0

The FFT of operators: probe, compose, read — matrix-free spectral computation with a built-in cost law.

resona — the FFT of operators

fft(x) takes a signal to the basis where convolution becomes pointwise multiply. Spectral.of(A) takes an operator (black-box matvec) to the representation where composition becomes addition — matrix-free — and from which every spectral functional is read.

One object. Three verbs. No matrix is ever formed; eig is never called.

import numpy as np, resona

s = resona.of(matvec, N)        # PROBE   — harvest the operator's response
t = resona.of(matvec2, N)
(s + t).extreme()               # COMPOSE — eig(A+B), A+B never formed
(s @ t)                         #           A·B
s.trace(np.log)                 # READ    — log|A|  (any spectral functional)
s.density(x) ; s.moment(2) ; s.extreme()
s.effective_rank()              # the honest cost dial (Φ₁)

resona.apply(matvec, f, v)      # APPLY   — f(A)·v  (exp(tA)·v, A⁻¹·v, …): evolve PDEs

New here? → the how-to cookbook: find your task in the "I want to…" table, copy the recipe, follow the guide. The examples/ are the full, verified reference implementations.

Install

pip install -e .            # from source
pip install -e ".[test]"   # with pytest

What it solves (matrix-free, one primitive)

Verified against dense ground truth in examples/killer_tasks.py:

task	what	metric
GP log-determinant	`log	K
Loss-Hessian spectrum	sharpness & curvature from HVPs, no Hessian formed	λ_max 0.00%, Tr 0.30%
Spectrum of A+B	composed, matrix-free (Horn's problem in practice)	extreme eig to 1e-9
Deep-net trainability	cond(W_L…W_1) predicted from init, no fwd/bwd	Gaussian explodes, orthogonal ≈1
Effective rank Φ₁	the cost dial: structured/cheap vs full/frontier	14 vs 466
Nonlinear PDE (Burgers)	lift to linear (Cole–Hopf) → exp(tK)·v via resona.apply	residual 5e-9, matrix-free
35 operators → spectra	matrix-free Ritz seed → Rayleigh polish (the sft35 pipeline)	seed 1e-4 → 1e-16, 99% machine-zero
Signal in noise (BBP)	the detection threshold — does a spike detach from the bulk?	extreme() tracks λ=θ+1/θ above θ_c=1
Anderson localization	metal→insulator transition from disorder, matrix-free	Λ=∫typ/∫mean LDOS, 0.97→0.15 in 3.4s
Tracy–Widom edge	the universal fluctuation law of extreme() (λ_max)	std·N^⅔→1.27, exponent −0.65 (target −⅔)

More broadly: density of states, Tr f(A) (log-det, Tr A⁻¹, partition functions, Schatten norms), extreme eigenvalues & spectral gaps, disorder-averaged spectra, phase-transition detection, spectral clustering — anything that is a spectral functional of a (possibly composed) operator you can only matvec.

The three verbs

• PROBE — Spectral.of(matvec, N): stochastic Lanczos quadrature → Ritz nodes (the "frequencies") + weights (the "amplitudes"). Cost O(probes·k) matvecs. (local_density(matvec, v) probes from a chosen vector instead of random ones — the LDOS / vector-resolved response. from_measure(nodes, weights) and from_eigenbasis(λ, V) are the inverses — a spectral measure / full eigenbasis → the operator (the inverse spectral problem, machine-precise from the full eigenbasis).)
• COMPOSE — s + t, s @ t: A+B, A·B without forming or diagonalizing them (the free-convolution theorem; exact closure (A+B)x = Ax + Bx).
• READ — trace, moment, density, extreme: any spectral functional.

Plus the cost dials effective_rank() (Φ₁) and condition() — low ⇒ structured/cheap; high ⇒ near the genuine frontier — and the Extraction Law they come from.

Everything else reads off the same object (the Spectral hub): s.boxplus(t) (⊞ at the measure level), s.cauchy(z), s.r(w), s.s(w), s.cumulants() (the lifted coordinates), s.flow(t, xs), s.shock_time() (free heat flow / disorder averaging), s.levels(N) (the Beta closure). When the matvec also maps blocks (A @ X), probing switches to one BLAS-3 block-Lanczos automatically — ~2–4× faster, bit-compatible.

The theory, as first-class modules

The spectral core above is one pillar. The rest of the program is promoted to tested library modules (not re-derived in each script):

• resona.wkernel — the spectral Jacobian W[i,j] = ∂λ_i/∂k_j (Hellmann– Feynman) + inverse spectral design (choose parameters to hit a target spectrum).
• resona.lift — the LIFT, "a shock is a sum of linearities": r_transform / s_transform (free ⊞/⊠ linearizers), carleman_scalar (nonlinear ODE → one matrix exponential), carleman_gf (exact GF(p) logic → linear polynomial).
• resona.beta — Beta-law closure: spectral support + 2 moments → the whole spectrum.
• resona.defect — error-as-information: defect, richardson, defect_jump (D_{2n}=Jⁿ·D_n exact), and the pseudospectrum (pseudospectrum_radius, sigma_min): the ε^{1/q} bloom law of non-normal defects — where the spectrum lies and GMRES actually lives.
• resona.solve — precision on the defect's minimal support: catastrophe_solve (order-q cluster detected → exactly q×target digits spent), rayleigh_polish (one eigenvalue, Ritz seed → machine precision, cubic).
• resona.free — free_cumulants, the freeness criterion (mixed cumulants vanish ⇔ composition closes), cross_moment — the response algebra's coordinates.
• resona.subordination — disorder averaging / free addition with a semicircle in CLOSED FORM (the Pastur fixed point g = G_A(z − σ²g)), no realizations, no eig.
• resona.lift.free_convolution — compose two spectra without a joint matvec (κ_n(A⊞B)=κ_n(A)+κ_n(B)), the measure-level version of s + t.
• resona.cost — the Extraction Law Cost ~ ε^{-a}·dist(z,Σ*)^{-b}, phi1 (Φ₁), the removable-vs-genuine classifier (is_extractable, lift-rank saturation), and level_spacing_ratio (⟨r⟩: 0.386 Poisson/integrable vs 0.531 GOE/chaotic — the 3-line is-there-a-lift detector; resolve symmetry sectors first).
• resona.lift.conserved_charge — the constructive side of the lift: a blind commutator-Gram search that FINDS the conserved charges of an integrable H (and honestly reports none for a chaotic one).
• resona.flow — free convolution as the complex Burgers flow; shock_time finds the band-merger (defect = shock = spectral edge).

Each is verified against dense ground truth in tests/ (R-transform additivity to 0.5%, freeness defect 0.004 vs 2.0, Carleman/logic exact, W-kernel vs finite-diff 2e-7, Pastur m₂ matches Monte-Carlo, extractable-vs-genuine classifier, shock t_c≈1).

Honesty

The underlying algorithms (SLQ, Lanczos, free probability) are classical and credited in NOVELTY.md. resona's contribution is the single primitive + matrix-free composition algebra + the built-in cost law as one object — the way FFT organizes signal processing. The unifying claims (the Extraction Law, Φ₁-as-boundary) are research hypotheses, labelled as such; the computations are verified.

Theory

The unified picture behind the library — the response measure as a conjugate pair, free probability (closure, the freeness boundary, the semicircle attractor), the defect = shock = edge identity, and the Extraction Law — is in THEORY.md, with reproducible verification scripts in theory/. The intellectual claims are stated honestly in NOVELTY.md; what building it revealed — the open conjectures and a research log that records the failures too — is in FRONTIER.md. The cost (big-O, matrix-free vs dense, measured slopes) of every method is in COMPLEXITY.md.

License

MIT © 2026 Dmitry Sierikov. Attribution requested for the research contributions in NOVELTY.md.