physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/tests/test_wishart_marchenko_pastur.py

@@ -0,0 +1,120 @@
+"""Tests for LOE/LUE/LSE and the Marchenko-Pastur law benchmark.
+
+The bidiagonal beta-Laguerre construction (see
+``physicskit.rmt.utils.tridiagonal.sample_laguerre_beta_eigenvalues``) was
+verified during development against dense X^T X / m constructions at
+beta=1, 2 (two-sample KS test between pooled eigenvalues, matching to
+within Monte Carlo noise) and against the exact Marchenko-Pastur law
+directly (including support edges) at beta=1, 2, 4. Like the semicircle
+law, Marchenko-Pastur is an *exact* N -> infinity limit (unlike the
+Wigner/Atas surmises), so convergence-rate assertions here follow the
+same "shrinks as N grows" philosophy as the semicircle tests.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+CLASSICAL_WISHART = [
+    ("LOE", rmt.ensembles.LOE, 1.0),
+    ("LUE", rmt.ensembles.LUE, 2.0),
+    ("LSE", rmt.ensembles.LSE, 4.0),
+]
+
+GAMMA = 0.3  # aspect ratio n/m used across most tests
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_WISHART)
+def test_beta_is_correct(name, cls, expected_beta):
+    ens = cls(n=50, m=200, seed=0)
+    assert ens.beta == expected_beta
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_WISHART)
+def test_gamma_property(name, cls, expected_beta):
+    ens = cls(n=100, m=400, seed=0)
+    assert ens.gamma == pytest.approx(0.25)
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_WISHART)
+def test_sample_shape_reproducibility_and_nonnegativity(name, cls, expected_beta):
+    ens_a = cls(n=200, m=int(200 / GAMMA), seed=123)
+    ens_b = cls(n=200, m=int(200 / GAMMA), seed=123)
+    spec_a = ens_a.sample(n_samples=5)
+    spec_b = ens_b.sample(n_samples=5)
+
+    assert spec_a.eigenvalues.shape == (5, 200)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+    # Wishart matrices are positive semi-definite -- eigenvalues >= 0.
+    assert np.all(spec_a.eigenvalues >= -1e-10)
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_WISHART)
+def test_support_matches_marchenko_pastur_edges(name, cls, expected_beta):
+    n = 3000
+    m = int(n / GAMMA)
+    ens = cls(n=n, m=m, seed=2)
+    spectrum = cached_sample(ens, n_samples=1)
+    lo, hi = rmt.stats.mp_support(ens.gamma)
+    eigs = spectrum.rescaled.ravel()
+    # small finite-size tolerance around the exact edges
+    assert eigs.min() > lo - 0.15
+    assert eigs.max() < hi + 0.15
+    assert eigs.min() < lo + 0.2
+    assert eigs.max() > hi - 0.2
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_WISHART)
+def test_marchenko_pastur_convergence_shrinks_with_n(name, cls, expected_beta):
+    # MP is an exact limit (like the semicircle law), so -- unlike the
+    # Wigner/Atas surmises -- convergence-to-zero across N is the right
+    # thing to check, via the same robust log-log trend as
+    # test_gaussian_semicircle.test_semicircle_convergence_rate_decreases_with_n.
+    # Looped manually (rather than via benchmark.convergence_curve) so
+    # each N's sample can be disk-cached individually.
+    from scipy.stats import linregress
+
+    benchmark = rmt.validation.MarchenkoPastur(gamma=GAMMA)
+    n_values = [50, 150, 450, 1350]
+
+    results = []
+    for n in n_values:
+        ens = cls(n=n, m=int(n / GAMMA), seed=17)
+        spectrum = cached_sample(ens, n_samples=25)
+        results.append(benchmark.validate(spectrum, seed=17))
+
+    ks_stats = np.array([r.ks_statistic for r in results])
+    slope = linregress(np.log(n_values), np.log(ks_stats)).slope
+    assert slope < -0.3, f"{name}: expected shrinking KS distance, slope={slope}"
+    assert ks_stats[-1] < 0.005
+
+
+def test_continuum_beta_also_matches_marchenko_pastur():
+    ens = rmt.ensembles.LaguerreBetaEnsemble(n=800, m=int(800 / GAMMA), beta=1.7, seed=3)
+    spectrum = cached_sample(ens, n_samples=25)
+    benchmark = rmt.validation.MarchenkoPastur(gamma=GAMMA)
+    result = benchmark.validate(spectrum, seed=3)
+    assert result.ks_statistic < 0.01
+
+
+def test_invalid_parameters_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.LOE(n=100, m=50, seed=0)  # m < n
+    with pytest.raises(ValueError):
+        rmt.ensembles.LaguerreBetaEnsemble(n=100, m=200, beta=0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.validation.MarchenkoPastur(gamma=1.5)  # only (0, 1] supported
+    with pytest.raises(ValueError):
+        rmt.validation.MarchenkoPastur(gamma=0.0)
+
+
+def test_mp_cdf_is_zero_below_and_one_above_support_and_monotonic():
+    gamma = 0.5
+    lo, hi = rmt.stats.mp_support(gamma)
+    x = np.linspace(lo - 0.5, hi + 0.5, 20)
+    cdf = rmt.stats.mp_cdf(x, gamma)
+    assert cdf[0] == 0.0
+    assert cdf[-1] == 1.0
+    assert np.all(np.diff(cdf) >= -1e-12)

physicskit/rmt/utils/haar.py

@@ -0,0 +1,128 @@
+"""Generate Haar-distributed random unitary matrices via the corrected
+QR decomposition trick.
+
+Reference: F. Mezzadri, "How to generate random matrices from the
+classical compact groups", Notices of the AMS 54 (2007) 592
+(arXiv:math-ph/0609050).
+
+A naive QR decomposition of a complex Ginibre matrix does NOT produce a
+Haar-distributed unitary matrix: the QR decomposition is not unique (Q can
+be multiplied by any unitary diagonal matrix while R is adjusted to
+compensate), and standard LAPACK routines resolve that ambiguity in a way
+that is not rotation-invariant. Fixing the phases of R's diagonal so they
+are all real and positive removes the ambiguity and makes Q exactly
+Haar-distributed (Mezzadri's Theorem 1). Verified empirically: the
+resulting matrix is unitary to machine precision, and eigenvalue phases
+are uniform on the circle (see physicskit.rmt.ensembles.circular.CUE and
+tests/test_circular.py).
+"""
+
+import numpy as np
+
+
+def haar_unitary(n: int, rng: np.random.Generator) -> np.ndarray:
+    """A single n x n Haar-distributed random unitary matrix.
+
+    Parameters
+    ----------
+    n : int
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    numpy.ndarray, shape (n, n), complex
+    """
+    z = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+    q, r = np.linalg.qr(z)
+    d = np.diagonal(r)
+    ph = d / np.abs(d)
+    return q * ph  # broadcasts the phase correction over columns of q
+
+
+def symplectic_form(n: int) -> np.ndarray:
+    """The n x n (n even) symplectic form Z = I_(n/2) kron [[0, 1], [-1, 0]],
+    used to build the "dual" of a unitary matrix for the Circular
+    Symplectic Ensemble (see physicskit.rmt.ensembles.circular.CSE). Satisfies
+    Z^2 = -I, so Z^{-1} = -Z.
+
+    Parameters
+    ----------
+    n : int
+        Dimension; must be even.
+
+    Returns
+    -------
+    numpy.ndarray, shape (n, n), complex
+    """
+    if n % 2 != 0:
+        raise ValueError("symplectic_form requires an even dimension")
+    block = np.array([[0.0, 1.0], [-1.0, 0.0]], dtype=complex)
+    return np.kron(np.eye(n // 2, dtype=complex), block)
+
+
+def haar_orthogonal(n: int, rng: np.random.Generator) -> np.ndarray:
+    """A single n x n Haar-distributed random orthogonal matrix (O(n),
+    both determinant signs -- not restricted to SO(n)).
+
+    Same corrected-QR-decomposition trick as ``haar_unitary`` (Mezzadri
+    2007 covers O(n) via the identical construction), with the
+    diagonal-sign correction (real case) in place of the phase
+    correction (complex case): naive QR is non-unique up to
+    multiplying Q's columns by +-1 while adjusting R to compensate, and
+    LAPACK's default resolution of that ambiguity is not rotation-
+    invariant. Verified empirically during development: the resulting
+    matrix is orthogonal to machine precision, its first column is
+    uniformly distributed on the unit sphere (mean 0, second moment
+    1/n per component), and its determinant is +1 or -1 with equal
+    probability -- see ``tests/test_haar.py``.
+
+    Parameters
+    ----------
+    n : int
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    numpy.ndarray, shape (n, n), real
+    """
+    z = rng.standard_normal((n, n))
+    q, r = np.linalg.qr(z)
+    d = np.diagonal(r)
+    sign = np.sign(d)
+    sign[sign == 0.0] = 1.0
+    return q * sign
+
+
+def haar_symplectic(n_quaternionic: int, rng: np.random.Generator) -> np.ndarray:
+    """A single Haar-distributed random element of the compact
+    symplectic group Sp(n_quaternionic), embedded as a
+    2*n_quaternionic x 2*n_quaternionic unitary matrix.
+
+    Construction: U = V^R @ V, where V is Haar-unitary on
+    U(2*n_quaternionic) and V^R = Z @ V^T @ Z^{-1} is its symplectic
+    dual (Z the symplectic form) -- the same construction already used
+    to sample the Circular Symplectic Ensemble
+    (``physicskit.rmt.ensembles.circular.CSE``), exposed here directly as a
+    reusable raw-matrix generator rather than only as an eigenvalue
+    intermediate. Verified directly (not merely inherited from CSE's
+    validated spacing statistics): U is unitary to machine precision,
+    satisfies the defining self-duality condition U^R == U exactly, and
+    its eigenvalues come in exact double-degenerate pairs -- see
+    ``tests/test_haar.py``.
+
+    Parameters
+    ----------
+    n_quaternionic : int
+        The quaternionic dimension; the returned matrix has shape
+        (2*n_quaternionic, 2*n_quaternionic).
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    numpy.ndarray, shape (2*n_quaternionic, 2*n_quaternionic), complex
+    """
+    n = 2 * n_quaternionic
+    v = haar_unitary(n, rng)
+    z = symplectic_form(n)
+    v_dual = (-z) @ v.T @ z  # Z^{-1} = -Z since Z^2 = -I
+    return v_dual @ v

physicskit/rmt/utils/random_state.py

@@ -0,0 +1,24 @@
+"""Centralized RNG handling so every ensemble and benchmark in physicskit.rmt
+is exactly reproducible from a seed."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def as_generator(seed: int | np.random.Generator | None) -> np.random.Generator:
+    """Coerce ``seed`` into a numpy Generator.
+
+    Parameters
+    ----------
+    seed : int, numpy.random.Generator, or None
+        An existing Generator (returned as-is), an integer seed, or
+        None (fresh, non-reproducible entropy).
+
+    Returns
+    -------
+    numpy.random.Generator
+    """
+    if isinstance(seed, np.random.Generator):
+        return seed
+    return np.random.default_rng(seed)

physicskit/rmt/utils/tridiagonal.py

@@ -0,0 +1,167 @@
+"""Dumitriu & Edelman (2002) tridiagonal model for the Gaussian beta-ensemble.
+
+Reference: I. Dumitriu and A. Edelman, "Matrix Models for Beta Ensembles",
+J. Math. Phys. 43, 5830 (2002).
+
+The eigenvalues of the tridiagonal matrix
+
+    H_beta = tridiag( off_diag, diag, off_diag )
+
+with
+
+    diag[i]      ~ N(0, 2)                       i.i.d., i = 1..n
+    off_diag[i]  ~ chi(df = beta * (n - i))       independent, i = 1..n-1
+
+have exactly the joint eigenvalue density of the Gaussian beta-ensemble
+
+    f(x_1, ..., x_n) ~ exp(-beta/4 * sum_i x_i^2) * prod_{i<j} ``|x_i - x_j|^beta``
+
+for beta = 1, 2, 4 this recovers GOE, GUE, GSE eigenvalue statistics exactly
+(not just asymptotically), and for any beta > 0 it gives the continuum
+Dyson-index generalization -- without ever forming or diagonalizing a dense
+N x N matrix. Diagonalizing a tridiagonal matrix is O(n^2) rather than the
+O(n^3) required for a general dense Hermitian eigensolve, which is what
+makes it practical to push n high enough for the asymptotic theorems
+(semicircle law, Tracy-Widom edge statistics, etc.) to actually apply.
+
+Raw eigenvalues from this construction have empirical spread that grows
+like sqrt(n * beta); divide by that factor to reach the standard semicircle
+normalization with support [-2, 2]. See ``natural_scale`` on
+``HermiteBetaEnsemble`` in ``physicskit.rmt.ensembles.gaussian``.
+"""
+
+import numpy as np
+from scipy.linalg import eigh_tridiagonal
+from scipy.stats import chi
+
+
+def sample_hermite_beta_eigenvalues(n: int, beta: float, rng: np.random.Generator) -> np.ndarray:
+    """Draw one realization of eigenvalues from the beta-Hermite ensemble.
+
+    Parameters
+    ----------
+    n : int
+        Matrix dimension.
+    beta : float
+        Dyson index. beta=1 -> GOE, beta=2 -> GUE, beta=4 -> GSE; any
+        beta > 0 is a valid continuum generalization.
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    numpy.ndarray, shape (n,)
+        Raw (unnormalized) eigenvalues, ascending order.
+    """
+    if n < 2:
+        raise ValueError("n must be at least 2 for the tridiagonal model")
+    diag = rng.normal(loc=0.0, scale=np.sqrt(2.0), size=n)
+    dof = beta * np.arange(n - 1, 0, -1)  # (n-1)*beta, (n-2)*beta, ..., beta
+    off_diag = chi.rvs(dof, random_state=rng)
+    return eigh_tridiagonal(diag, off_diag, eigvals_only=True)
+
+
+def sample_hermite_beta_eigenvalues_and_vectors(n: int, beta: float, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """Draw one realization of eigenvalues AND eigenvectors from the
+    beta-Hermite ensemble.
+
+    The tridiagonal model preserves not only the exact beta-Hermite
+    eigenVALUE density but also the ensemble's rotationally/unitarily-
+    invariant eigenVECTOR distribution (Dumitriu-Edelman 2002; also
+    Edelman-Sutton): since GOE/GUE/GSE (and their continuum-beta
+    generalization) are invariant under conjugation by an orthogonal/
+    unitary/symplectic change of basis, the tridiagonal model's
+    eigenvectors are a faithful stand-in for a dense-matrix
+    diagonalization's eigenvectors, not merely a computational
+    convenience for the eigenvalues alone. This makes them usable, e.g.,
+    as the delocalized reference case for inverse-participation-ratio
+    statistics (see ``physicskit.rmt.stats.localization``) -- verified
+    numerically here: the mean IPR of the columns returned matches the
+    exact Haar/Gaussian-vector result ``(beta/2+1)/(n*beta/2+1)`` (see
+    ``physicskit.rmt.stats.localization.ipr_theory`` and
+    ``tests/test_localization.py``).
+
+    Parameters
+    ----------
+    n : int
+        Matrix dimension.
+    beta : float
+        Dyson index. beta=1 -> GOE, beta=2 -> GUE, beta=4 -> GSE; any
+        beta > 0 is a valid continuum generalization.
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    eigenvalues : numpy.ndarray, shape (n,)
+        Raw (unnormalized) eigenvalues, ascending order.
+    eigenvectors : numpy.ndarray, shape (n, n)
+        Column ``i`` is the eigenvector for ``eigenvalues[i]``.
+    """
+    if n < 2:
+        raise ValueError("n must be at least 2 for the tridiagonal model")
+    diag = rng.normal(loc=0.0, scale=np.sqrt(2.0), size=n)
+    dof = beta * np.arange(n - 1, 0, -1)
+    off_diag = chi.rvs(dof, random_state=rng)
+    return eigh_tridiagonal(diag, off_diag, eigvals_only=False)
+
+
+def sample_laguerre_beta_eigenvalues(m: int, n: int, beta: float, rng: np.random.Generator) -> np.ndarray:
+    """Draw one realization of eigenvalues from the beta-Laguerre
+    (Wishart) ensemble, corresponding to an m x n rectangular Gaussian
+    data matrix (m "samples", n "variables", m >= n) with i.i.d.
+    unit-variance entries -- real for beta=1, complex for beta=2,
+    quaternionic for beta=4; any beta > 0 is a valid continuum
+    generalization.
+
+    Construction: a classical fact (Householder-bidiagonalization of a
+    Gaussian matrix yields independent chi-distributed bidiagonal
+    entries) generalized to arbitrary beta following the same pattern as
+    the Dumitriu-Edelman tridiagonal Hermite model. The n x n bidiagonal
+    matrix
+
+        B = bidiag( diagonal: chi(beta*m), chi(beta*(m-1)), ..., chi(beta*(m-n+1));
+                    subdiagonal: chi(beta*(n-1)), chi(beta*(n-2)), ..., chi(beta) )
+
+    gives W = B B^T / (beta * m) eigenvalues matching the standard
+    Marchenko-Pastur normalization (support [(1-sqrt(gamma))^2,
+    (1+sqrt(gamma))^2] with gamma = n/m as m, n -> infinity).
+
+    Verified numerically at beta=1, 2 against dense X^T X / m
+    constructions (real and complex Ginibre-type X respectively): pooled
+    eigenvalue samples agree via two-sample KS test to within Monte Carlo
+    noise. All three classical beta (1, 2, 4) converge to the exact
+    Marchenko-Pastur law with correctly located support edges.
+
+    Parameters
+    ----------
+    m : int
+        Number of samples (rows) of the underlying data matrix, m >= n.
+    n : int
+        Number of variables (columns) of the underlying data matrix.
+    beta : float
+        Dyson index. beta=1 -> real, beta=2 -> complex, beta=4 ->
+        quaternionic; any beta > 0 is a valid continuum generalization.
+    rng : numpy.random.Generator
+
+    Returns
+    -------
+    numpy.ndarray, shape (n,)
+        Raw eigenvalues (already in Marchenko-Pastur normalization,
+        i.e. natural_scale = 1 for this ensemble), ascending order.
+    """
+    if n < 2:
+        raise ValueError("n must be at least 2 for the bidiagonal model")
+    if m < n:
+        raise ValueError("m (samples) must be >= n (variables)")
+    diag_dof = beta * (m - np.arange(n))
+    sub_dof = beta * (n - 1 - np.arange(n - 1))
+    diag = chi.rvs(diag_dof, random_state=rng)
+    sub = chi.rvs(sub_dof, random_state=rng) if n > 1 else np.array([])
+    B = np.diag(diag)
+    if n > 1:
+        B += np.diag(sub, -1)
+    W = (B @ B.T) / (beta * m)
+    # Real advantage over dense X^T X: no m x n matrix (and no O(m*n^2)
+    # matrix product) is ever formed regardless of how large m is --
+    # generating B costs O(n) chi draws, independent of m. The final
+    # eigenvalue solve on the n x n matrix W is O(n^3) either way.
+    return np.linalg.eigvalsh(W)

physicskit/rmt/validation/__init__.py

@@ -0,0 +1,36 @@
+from .base import Benchmark, ValidationResult
+from .circular_law import CircularLaw
+from .marchenko_pastur import MarchenkoPastur
+from .ratio_distribution import RatioDistribution
+from .real_ginibre import RealEigenvalueCountResult, RealGinibreEigenvalueCount
+from .sine_kernel import CorrelationValidationResult, SineKernel
+from .single_ring import SingleRingTheorem
+from .tracy_widom import TracyWidom
+from .universality import (
+    DEFAULT_ENTRY_DISTRIBUTIONS,
+    UniversalityResult,
+    check_universality,
+)
+from .wachter import Wachter
+from .wigner_semicircle import WignerSemicircle
+from .wigner_surmise import WignerSurmise
+
+__all__ = [
+    "Benchmark",
+    "ValidationResult",
+    "WignerSemicircle",
+    "WignerSurmise",
+    "RatioDistribution",
+    "MarchenkoPastur",
+    "SineKernel",
+    "CorrelationValidationResult",
+    "CircularLaw",
+    "TracyWidom",
+    "Wachter",
+    "check_universality",
+    "UniversalityResult",
+    "DEFAULT_ENTRY_DISTRIBUTIONS",
+    "RealGinibreEigenvalueCount",
+    "RealEigenvalueCountResult",
+    "SingleRingTheorem",
+]

physicskit/rmt/validation/base.py

@@ -0,0 +1,126 @@
+"""Base class for paper-replication benchmarks.
+
+A single fixed-N Kolmogorov-Smirnov test with a p > 0.05 pass criterion is
+*not* a reliable way to validate convergence to an asymptotic law: KS test
+power grows with N, so real, expected finite-size deviations become more
+likely to trigger rejection as N grows, not less. Instead, every Benchmark
+here supports ``convergence_curve``, which tracks a distance-to-theory
+metric across a sequence of N values and expects it to *shrink* as N grows
+-- that is the statistically meaningful way to demonstrate asymptotic
+convergence.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.stats import kstest, wasserstein_distance
+
+from ..ensembles.base import MatrixEnsemble
+from ..spectrum import Spectrum
+
+
+@dataclass
+class ValidationResult:
+    """Result of comparing one Spectrum against a benchmark's theoretical
+    distribution."""
+
+    ks_statistic: float
+    ks_pvalue: float
+    wasserstein_distance: float
+    n_eigenvalues: int
+
+    def __repr__(self) -> str:
+        return (
+            f"ValidationResult(ks_statistic={self.ks_statistic:.5f}, "
+            f"ks_pvalue={self.ks_pvalue:.3g}, "
+            f"wasserstein_distance={self.wasserstein_distance:.5f}, "
+            f"n_eigenvalues={self.n_eigenvalues})"
+        )
+
+
+class Benchmark(ABC):
+    """Ties one theoretical distribution to a validation procedure.
+
+    Subclasses implement ``theoretical_cdf`` (for the one-sample KS test,
+    which needs no simulated reference sample) and ``reference_samples``
+    (for the Wasserstein-distance comparison, which does).
+    """
+
+    @abstractmethod
+    def theoretical_cdf(self, x: np.ndarray) -> np.ndarray:
+        """Exact theoretical CDF, vectorized over x."""
+        raise NotImplementedError  # pragma: no cover -- unreachable, see MatrixEnsemble._sample_eigenvalues
+
+    @abstractmethod
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        """Draw ``size`` i.i.d. samples from the theoretical distribution."""
+        raise NotImplementedError  # pragma: no cover -- unreachable, see MatrixEnsemble._sample_eigenvalues
+
+    #: Reference-sample size used for the Wasserstein comparison. Kept
+    #: large and fixed (rather than tied to len(data)) so the reference
+    #: sample's own Monte Carlo noise stays well below the eigenvalue-side
+    #: signal even once the ensemble has converged tightly to theory --
+    #: otherwise the noise floor from a same-size reference sample can
+    #: swamp the (small, real) improvement between two already-close N
+    #: values and make the distance non-monotonic by chance.
+    reference_size: int = 200_000
+
+    def validate(self, spectrum: Spectrum, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        """Compare a Spectrum's rescaled eigenvalues against theory.
+
+        Returns a ValidationResult with both a one-sample KS statistic
+        (against the exact theoretical CDF) and a Wasserstein distance
+        (against simulated reference samples) -- report both rather than
+        gating on a single p-value threshold.
+        """
+        data = spectrum.rescaled.ravel()
+        ks = kstest(data, self.theoretical_cdf)
+        rng = np.random.default_rng(seed)
+        reference = self.reference_samples(self.reference_size, rng)
+        wd = wasserstein_distance(data, reference)
+        return ValidationResult(
+            ks_statistic=float(ks.statistic),
+            ks_pvalue=float(ks.pvalue),
+            wasserstein_distance=float(wd),
+            n_eigenvalues=len(data),
+        )
+
+    def convergence_curve(
+        self,
+        ensemble_factory: Callable[..., MatrixEnsemble],
+        n_values: list[int],
+        n_samples: int = 20,
+        seed: int | np.random.Generator | None = None,
+    ) -> list[tuple[int, ValidationResult]]:
+        """Track distance-to-theory across increasing matrix size N.
+
+        Parameters
+        ----------
+        ensemble_factory : callable
+            ``ensemble_factory(n, seed=...)`` returning a fresh
+            ``MatrixEnsemble`` instance of size n.
+        n_values : sequence of int
+            Matrix sizes to test, in increasing order.
+        n_samples : int
+            Independent matrix draws to pool at each N.
+        seed : int or None
+
+        Returns
+        -------
+        list of (n, ValidationResult)
+            The KS statistic (and Wasserstein distance) in each result is
+            expected to shrink as n increases; this is the check to make,
+            not a single p > 0.05 threshold at one N.
+        """
+        rng = np.random.default_rng(seed)
+        results = []
+        for n in n_values:
+            ensemble = ensemble_factory(n, seed=int(rng.integers(1 << 31)))
+            spectrum = ensemble.sample(n_samples=n_samples)
+            result = self.validate(spectrum, seed=int(rng.integers(1 << 31)))
+            results.append((n, result))
+        return results

physicskit/rmt/validation/circular_law.py

@@ -0,0 +1,80 @@
+"""Circular law benchmark for the Ginibre ensembles.
+
+Reference: J. Ginibre, J. Math. Phys. 6 (1965) 440.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+from ..ensembles.base import MatrixEnsemble
+from ..spectrum import Spectrum
+from ..stats.circular_law import circular_law_radial_cdf, circular_law_radial_pdf
+from .base import Benchmark, ValidationResult
+
+
+class CircularLaw(Benchmark):
+    """Validates a Ginibre-type Spectrum's eigenvalue *radii* against the
+    circular law's radial marginal (F(r) = r^2 on [0, 1]).
+
+    Overrides ``validate`` (rather than just ``theoretical_cdf`` /
+    ``reference_samples``) because the base class compares
+    ``spectrum.rescaled`` directly, but here it's the eigenvalue
+    *magnitudes* -- not the (complex) rescaled eigenvalues themselves --
+    that are compared to a 1-D theoretical distribution.
+    """
+
+    def theoretical_pdf(self, r: np.ndarray) -> np.ndarray:
+        return circular_law_radial_pdf(r)
+
+    def theoretical_cdf(self, r: np.ndarray) -> np.ndarray:
+        return circular_law_radial_cdf(r)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        # Inverse-CDF sampling: F(r) = r^2 => r = sqrt(U), U ~ Uniform(0,1)
+        u = rng.uniform(0.0, 1.0, size=size)
+        return np.sqrt(u)
+
+    def validate(self, spectrum: Spectrum, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        radii = np.abs(spectrum.rescaled.ravel())
+        ks_result = self._ks_and_wasserstein(radii, seed)
+        return ks_result
+
+    def _ks_and_wasserstein(self, radii: np.ndarray, seed: int | np.random.Generator | None) -> ValidationResult:
+        from scipy.stats import kstest, wasserstein_distance
+
+        ks = kstest(radii, self.theoretical_cdf)
+        rng = np.random.default_rng(seed)
+        reference = self.reference_samples(self.reference_size, rng)
+        wd = wasserstein_distance(radii, reference)
+        return ValidationResult(
+            ks_statistic=float(ks.statistic),
+            ks_pvalue=float(ks.pvalue),
+            wasserstein_distance=float(wd),
+            n_eigenvalues=len(radii),
+        )
+
+    def convergence_curve(
+        self,
+        ensemble_factory: Callable[..., MatrixEnsemble],
+        n_values: list[int],
+        n_samples: int = 20,
+        seed: int | np.random.Generator | None = None,
+    ) -> list[tuple[int, ValidationResult]]:
+        """Same convergence-rate philosophy as the other exact-limit
+        benchmarks (semicircle, Marchenko-Pastur): track KS distance to
+        the circular law as N grows. Convergence here is known to be
+        slower than the Hermitian ensembles' (weaker eigenvalue rigidity
+        for non-Hermitian matrices), so expect a shallower log-log slope
+        -- verified during development to be reliably negative but
+        smaller in magnitude than the semicircle/MP cases."""
+        rng = np.random.default_rng(seed)
+        results = []
+        for n in n_values:
+            ensemble = ensemble_factory(n, seed=int(rng.integers(1 << 31)))
+            spectrum = ensemble.sample(n_samples=n_samples)
+            result = self.validate(spectrum, seed=int(rng.integers(1 << 31)))
+            results.append((n, result))
+        return results