resona 0.4.0__tar.gz

resona-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Sierikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

resona-0.4.0/PKG-INFO

@@ -0,0 +1,168 @@
+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`.

resona-0.4.0/README.md

@@ -0,0 +1,143 @@
+# 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`.

resona-0.4.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "resona"
+version = "0.4.0"
+description = "The FFT of operators: probe, compose, read — matrix-free spectral computation with a built-in cost law."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Dmitry Sierikov" }]
+keywords = [
+    "spectral", "operator", "matrix-free", "stochastic-lanczos-quadrature",
+    "free-probability", "density-of-states", "log-determinant", "trace-estimation",
+    "krylov", "numerical-linear-algebra",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=1.20", "scipy>=1.7"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+exact = ["mpmath>=1.2"]   # resona.solve.catastrophe_solve (extended-precision roots)
+
+[project.urls]
+Homepage = "https://github.com/dimaq12/resona"
+Source = "https://github.com/dimaq12/resona"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["resona*"]

resona-0.4.0/resona/__init__.py

@@ -0,0 +1,29 @@
+"""
+resona — the resonance of an operator.  Probe it, hear its spectrum.
+
+The FFT of operators: `fft(x)` takes a signal to the basis where convolution
+becomes pointwise multiply.  `resona.of(A)` takes an operator (black-box matvec)
+to the representation where composition becomes addition (free convolution) —
+matrix-free — and from which every spectral functional is read.
+
+    import resona
+    s = resona.of(matvec, N)       # PROBE   — ring the operator, read its modes
+    s + t ; s @ t                  # COMPOSE — A+B, A·B  (never formed, never eig'd)
+    s.trace(f) ; s.density(x) ; s.extreme() ; s.moment(p)   # READ
+    s.boxplus(t) ; s.cauchy(z) ; s.r(w) ; s.s(w)   # free convolution & lifted coords
+    s.flow(t, xs) ; s.levels(N)    # heat flow / disorder; Beta spectrum closure
+    s.effective_rank() ; s.condition()             # the honest cost dials (Φ₁, κ)
+
+    resona.apply(matvec, f, v)     # APPLY   — f(A)·v: solve, evolve, filter
+    resona.solve.rayleigh_polish   # PRECISION — spend effort only on the defect
+"""
+from .spectral import Spectral, apply, local_spectrum, local_density, from_measure, from_eigenbasis
+from . import wkernel, lift, beta, defect, free, subordination, cost, flow, solve
+
+#: convenience: ``resona.of(matvec, N)`` == ``Spectral.of(matvec, N)``
+of = Spectral.of
+
+__version__ = "0.4.0"
+__all__ = ["Spectral", "of", "apply", "local_spectrum", "local_density",
+           "from_measure", "from_eigenbasis", "wkernel", "lift", "beta", "defect", "free",
+           "subordination", "cost", "flow", "solve"]

resona-0.4.0/resona/beta.py

@@ -0,0 +1,40 @@
+"""
+resona.beta — the Beta-law spectral closure: support + 2 moments → full spectrum.
+
+A local / structured operator's eigenvalue density is SMOOTH (a central-limit
+effect over its many local terms).  On a bounded support [E0, Emax] the
+MAXIMUM-ENTROPY density with a prescribed mean and variance is a BETA
+distribution.  So the entire spectrum is fixed by FOUR numbers — the support
+endpoints E0, Emax and the first two moments μ1 = Tr(A)/N, μ2 = Tr(A²)/N — every
+one of them read matrix-free by resona.  The inverse-CDF unfolds all N levels in
+O(N), one and two factors of N below dense eig (O(N²)) and diagonalization
+(O(N³)).
+"""
+import numpy as np
+from scipy.stats import beta as _beta
+
+
+def beta_spectrum(E0, Emax, mu1, mu2, N, return_params=False):
+    """Support [E0,Emax] + per-dimension moments (μ1,μ2) → the N Beta levels.
+
+    μ1 = Tr(A)/N, μ2 = Tr(A²)/N.  Maximum-entropy closure on a bounded support.
+    """
+    span = Emax - E0
+    if span <= 0:
+        levels = np.full(N, float(E0))
+        return (levels, (1.0, 1.0)) if return_params else levels
+    m1 = (mu1 - E0) / span                                  # mean on [0,1]
+    m2 = (mu2 - 2 * E0 * mu1 + E0 ** 2) / span ** 2          # 2nd moment on [0,1]
+    var = max(m2 - m1 ** 2, 1e-12)
+    c = m1 * (1 - m1) / var - 1                              # Beta concentration
+    a, b = max(m1 * c, 1e-3), max((1 - m1) * c, 1e-3)
+    levels = E0 + span * _beta.ppf((np.arange(N) + 0.5) / N, a, b)
+    return (levels, (a, b)) if return_params else levels
+
+
+def beta_from(spectral, N=None, return_params=False):
+    """Beta spectrum straight from a Spectral object: pulls extreme() + moment(1,2)."""
+    N = N or spectral.N
+    E0, Emax = spectral.extreme()
+    mu1, mu2 = spectral.moment(1) / spectral.N, spectral.moment(2) / spectral.N
+    return beta_spectrum(E0, Emax, mu1, mu2, N, return_params)

resona-0.4.0/resona/cost.py

@@ -0,0 +1,84 @@
+"""
+resona.cost — the Extraction Law: how hard is the answer to extract?
+
+The answer pre-exists in the resolvent field G(z)=(z−A)⁻¹; a solver only EXTRACTS
+from it.  The cost of extracting to accuracy ε near a query z follows
+
+        Cost(ε, z)  ~  ε^{-a} · dist(z, Σ*)^{-b},
+
+where Σ* is the NON-removable singular set (edges / branch points / shocks /
+continua — NOT isolated poles, which deflate away).  Φ₁ = Tr(A)²/Tr(A²) is the
+GLOBAL summary (low ⇒ structured/cheap, high ⇒ genuine frontier).
+
+The operational test — REMOVABLE vs GENUINE — is lift-rank SATURATION: lift a
+signal to its trajectory (Hankel) operator at growing window k.  If the effective
+rank SATURATES, the singularity is removable → a finite chart linearizes it →
+EXTRACTABLE.  If the rank keeps GROWING with k, there is no finite chart →
+a genuine wall (structureless, e.g. aˣ mod N).  This is the dial that says
+dequantizable-vs-quantum, easy-vs-hard, from the signal itself.
+"""
+import numpy as np
+from scipy.linalg import hankel, svdvals
+
+
+def phi1(spectral):
+    """Φ₁ = Tr(A)²/Tr(A²) — the global cost summary (participation ratio)."""
+    return spectral.effective_rank()
+
+
+def lift_rank(signal, k=60):
+    """Effective rank of the trajectory (Hankel) operator of a signal at window k.
+    = (Σσ²)²/Σσ⁴ of the Hankel singular values — the size of the linearizing chart."""
+    s = np.asarray(signal, float)
+    s = (s - s.mean()) / (s.std() + 1e-12)
+    H = hankel(s[:k], s[k - 1:2 * k - 1])
+    s2 = svdvals(H) ** 2
+    return float(s2.sum() ** 2 / (s2 ** 2).sum())
+
+
+def is_extractable(signal, windows=(20, 40, 80, 120), grow=0.25):
+    """Removable-vs-genuine test by lift-rank SATURATION.
+
+    Returns (extractable: bool, ranks: list).  Saturates (rank flattens, stays a
+    small fraction of the window) ⇒ removable ⇒ extractable.  Keeps growing ~k ⇒
+    no finite chart ⇒ genuine wall.
+    """
+    ranks = [lift_rank(signal, k) for k in windows]
+    # genuine if the rank is still climbing with the window (chart never closes)
+    growth = (ranks[-1] - ranks[-2]) / (windows[-1] - windows[-2])
+    extractable = growth < grow and ranks[-1] < 0.4 * windows[-1]
+    return bool(extractable), ranks
+
+
+def level_spacing_ratio(eigenvalues, eps=1e-9):
+    """The integrability detector: mean consecutive level-spacing ratio
+    ⟨r⟩ = ⟨min(s_i, s_{i+1}) / max(s_i, s_{i+1})⟩ of a spectrum.
+
+        ⟨r⟩ ≈ 0.386  → Poisson statistics → integrable (a lift EXISTS)
+        ⟨r⟩ ≈ 0.531  → GOE level repulsion → chaotic (no lift)
+        (GUE 0.600, GSE 0.676; rigid picket-fence → 1.)
+
+    Unfolding-free (ratios cancel the local density), 3 lines, O(N log N).
+
+    LOUD CAVEAT (a real numerics trap): RESOLVE ALL SYMMETRY SECTORS FIRST.
+    Levels from different sectors do not repel; mixing sectors overlays
+    independent series and FAKES Poisson — an un-projected chaotic Hamiltonian
+    will read "integrable".  Project H into one sector (one reflection /
+    momentum / magnetization sector) before calling this.
+    """
+    s = np.diff(np.sort(np.asarray(eigenvalues, float)))
+    s = s[s > eps]
+    return float(np.mean(np.minimum(s[:-1], s[1:]) / np.maximum(s[:-1], s[1:])))
+
+
+def extraction_cost(eps, dist, a=1.0, b=1.0, c=1.0):
+    """The law value  Cost = c · ε^{-a} · dist^{-b}."""
+    return c * np.asarray(eps, float) ** (-a) * np.asarray(dist, float) ** (-b)
+
+
+def fit_law(costs, eps, dist):
+    """Fit (a, b, c) of Cost ~ c·ε^{-a}·dist^{-b} by log-log least squares."""
+    L = np.log(np.asarray(costs, float))
+    A = np.column_stack([-np.log(eps), -np.log(dist), np.ones_like(L)])
+    a, b, logc = np.linalg.lstsq(A, L, rcond=None)[0]
+    return float(a), float(b), float(np.exp(logc))