Metadata-Version: 2.4
Name: resona
Version: 0.4.0
Summary: The FFT of operators: probe, compose, read — matrix-free spectral computation with a built-in cost law.
Author: Dmitry Sierikov
License: MIT
Project-URL: Homepage, https://github.com/dimaq12/resona
Project-URL: Source, https://github.com/dimaq12/resona
Keywords: spectral,operator,matrix-free,stochastic-lanczos-quadrature,free-probability,density-of-states,log-determinant,trace-estimation,krylov,numerical-linear-algebra
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: exact
Requires-Dist: mpmath>=1.2; extra == "exact"
Dynamic: license-file

# 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.

```python
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](docs/README.md)**: find your task in the
"I want to…" table, copy the recipe, follow the guide. The [`examples/`](examples/)
are the full, verified reference implementations.

## Install

```bash
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`](examples/killer_tasks.py):

| task | what | metric |
|------|------|--------|
| **GP log-determinant** | `log|K|` for hyperparameter learning at scale | 0.84% rel.err, no Cholesky |
| **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`](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`](THEORY.md), with reproducible verification scripts in
[`theory/`](theory/). The intellectual claims are stated honestly in
[`NOVELTY.md`](NOVELTY.md); what building it revealed — the open conjectures and a
research log that records the **failures** too — is in [`FRONTIER.md`](FRONTIER.md).
The cost (big-O, matrix-free vs dense, measured slopes) of every method is in
[`COMPLEXITY.md`](COMPLEXITY.md).

## License

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