physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/validation/marchenko_pastur.py

@@ -0,0 +1,53 @@
+"""Marchenko-Pastur law benchmark for the Wishart (Laguerre) ensembles.
+
+Reference: V. A. Marchenko, L. A. Pastur, Mat. Sb. 72 (1967) 507.
+"""
+
+import numpy as np
+from scipy.interpolate import interp1d
+
+from ..stats.marchenko_pastur import mp_pdf, mp_support
+from .base import Benchmark
+
+
+class MarchenkoPastur(Benchmark):
+    """Validates the empirical spectral density of a Wishart ensemble
+    (LOE/LUE/LSE, or general beta-Laguerre) against the exact
+    Marchenko-Pastur law for a given aspect ratio gamma = n/m.
+
+    CDF and its inverse are built once per (gamma, sigma2) via a fine-grid
+    cumulative trapezoidal integration and cached as interpolators, for
+    the same reason as ``physicskit.rmt.stats.ratios.RatioSurmise``: a KS test
+    evaluates the CDF at every data point, so per-point ``quad`` calls
+    would be far too slow.
+    """
+
+    def __init__(self, gamma: float, sigma2: float = 1.0, grid_size: int = 4000) -> None:
+        if not (0 < gamma <= 1):
+            raise ValueError("gamma must be in (0, 1] for this ensemble convention (m >= n samples/variables, no point mass at zero)")
+        self.gamma = gamma
+        self.sigma2 = sigma2
+        self._lo, self._hi = mp_support(gamma, sigma2)
+
+        from scipy.integrate import cumulative_trapezoid
+
+        grid = np.linspace(self._lo, self._hi, grid_size)
+        pdf_vals = mp_pdf(grid, gamma, sigma2)
+        cdf_vals = cumulative_trapezoid(pdf_vals, grid, initial=0.0)
+        cdf_vals /= cdf_vals[-1]  # correct for edge-integrable-singularity discretization error
+        self._grid = grid
+        self._pdf_vals = pdf_vals
+        self._cdf_interp = interp1d(grid, cdf_vals, bounds_error=False, fill_value=(0.0, 1.0))
+        self._inv_cdf_interp = interp1d(cdf_vals, grid, bounds_error=False, fill_value=(self._lo, self._hi))
+
+    def theoretical_pdf(self, x: np.ndarray) -> np.ndarray:
+        return mp_pdf(x, self.gamma, self.sigma2)
+
+    def theoretical_cdf(self, x: np.ndarray) -> np.ndarray:
+        x = np.asarray(x, dtype=float)
+        out = np.where(x <= self._lo, 0.0, np.where(x >= self._hi, 1.0, self._cdf_interp(x)))
+        return out
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        u = rng.uniform(0.0, 1.0, size=size)
+        return self._inv_cdf_interp(u)

physicskit/rmt/validation/ratio_distribution.py

@@ -0,0 +1,53 @@
+"""Benchmark for the consecutive-spacing ratio distribution.
+
+Reference: Y. Y. Atas, E. Bogomolny, O. Giraud, G. Roux, "Distribution of
+the Ratio of Consecutive Level Spacings in Random Matrix Ensembles",
+Phys. Rev. Lett. 110, 084101 (2013).
+
+Deliberately structured as an independent check from ``WignerSurmise``:
+the ratio statistic needs no unfolding, so agreement here rules out
+unfolding artifacts as the explanation for agreement with the
+(unfolding-dependent) spacing distribution.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import kstest, wasserstein_distance
+
+from ..stats.ratios import RatioSurmise as _RatioSurmiseModel
+from .base import ValidationResult
+
+
+class RatioDistribution:
+    """Validates a ratio-statistic sample against the Atas et al. (2013)
+    surmise at a given Dyson index beta."""
+
+    reference_size: int = 200_000
+
+    def __init__(self, beta: float) -> None:
+        self.beta = beta
+        self._model = _RatioSurmiseModel(beta)
+
+    def theoretical_pdf(self, r: np.ndarray) -> np.ndarray:
+        return self._model.pdf(r)
+
+    def theoretical_cdf(self, r: np.ndarray) -> np.ndarray:
+        return self._model.cdf(r)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        return self._model.rvs(size, rng)
+
+    def validate(self, ratios: np.ndarray, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        """Compare an array of ratio statistics (each in [0, 1], from
+        ``physicskit.rmt.stats.ratios.ratio_statistics``) against the surmise."""
+        ks = kstest(ratios, self.theoretical_cdf)
+        rng = np.random.default_rng(seed)
+        reference = self.reference_samples(self.reference_size, rng)
+        wd = wasserstein_distance(ratios, reference)
+        return ValidationResult(
+            ks_statistic=float(ks.statistic),
+            ks_pvalue=float(ks.pvalue),
+            wasserstein_distance=float(wd),
+            n_eigenvalues=len(ratios),
+        )

physicskit/rmt/validation/real_ginibre.py

@@ -0,0 +1,60 @@
+"""Real-Ginibre real-eigenvalue-count benchmark.
+
+Like ``physicskit.rmt.validation.sine_kernel.SineKernel``, this doesn't fit the
+KS/Wasserstein ``Benchmark`` interface: it compares a scalar expected
+COUNT (of real eigenvalues), not a sample against a 1-D distribution. It
+gets its own lightweight result type instead.
+
+Reference: A. Edelman, E. Kostlan, S. Shub, J. Amer. Math. Soc. 7 (1994)
+247. See ``physicskit.rmt.stats.real_ginibre`` for the precision caveat: the
+theoretical value used here is the verified large-n asymptotic
+expansion, not the exact finite-n Edelman-Kostlan-Shub closed form.
+"""
+
+from dataclasses import dataclass
+
+from ..spectrum import Spectrum
+from ..stats.real_ginibre import real_eigenvalue_count_asymptotic, real_eigenvalue_count_empirical
+
+
+@dataclass
+class RealEigenvalueCountResult:
+    """Result of comparing a GinOE Spectrum's empirical mean real-
+    eigenvalue count against the asymptotic theoretical value."""
+
+    empirical_mean: float
+    theoretical: float
+    n: int
+
+    @property
+    def relative_error(self) -> float:
+        return abs(self.empirical_mean - self.theoretical) / self.theoretical
+
+    def __repr__(self) -> str:
+        return (
+            f"RealEigenvalueCountResult(empirical_mean={self.empirical_mean:.4f}, "
+            f"theoretical={self.theoretical:.4f}, n={self.n}, "
+            f"relative_error={self.relative_error:.4f})"
+        )
+
+
+class RealGinibreEigenvalueCount:
+    """Validates a real-Ginibre (``GinOE``) Spectrum's mean number of
+    real eigenvalues per sample against the asymptotic expected count
+    sqrt(2n/pi) + 1/2 (see ``physicskit.rmt.stats.real_ginibre`` for the
+    asymptotic-vs-exact precision caveat)."""
+
+    def __init__(self, tol: float = 1e-8) -> None:
+        """
+        Parameters
+        ----------
+        tol : float, optional
+            Passed to ``real_eigenvalue_count_empirical``: an eigenvalue
+            counts as real if ``abs(Im(lambda))`` is below this.
+        """
+        self.tol = tol
+
+    def validate(self, spectrum: Spectrum) -> RealEigenvalueCountResult:
+        counts = real_eigenvalue_count_empirical(spectrum.eigenvalues, tol=self.tol)
+        theoretical = real_eigenvalue_count_asymptotic(spectrum.n)
+        return RealEigenvalueCountResult(empirical_mean=float(counts.mean()), theoretical=theoretical, n=spectrum.n)

physicskit/rmt/validation/sine_kernel.py

@@ -0,0 +1,57 @@
+"""Sine-kernel benchmark for the Circular Unitary Ensemble's bulk
+two-point correlation function.
+
+This does not fit the KS/Wasserstein ``Benchmark`` interface used
+elsewhere in the package: it validates a *correlation function* (a
+density estimated by pair-counting), not a sample from a 1-D
+distribution. It gets its own lightweight result type instead.
+
+Reference: F. J. Dyson, J. Math. Phys. 3 (1962) 140, 157, 166.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..spectrum import Spectrum
+from ..stats.correlations import pair_correlation_estimate, sine_kernel_r2
+
+
+@dataclass
+class CorrelationValidationResult:
+    rmse: float
+    r_max: float
+    n_bins: int
+
+    def __repr__(self) -> str:
+        return f"CorrelationValidationResult(rmse={self.rmse:.5f}, r_max={self.r_max}, n_bins={self.n_bins})"
+
+
+class SineKernel:
+    """Validates a CUE (beta=2) Spectrum's bulk two-point correlation
+    function against the exact determinantal sine-kernel result.
+
+    Only beta=2 is implemented -- see module docstring in
+    ``physicskit.rmt.stats.correlations`` for why the beta=1, 4 cases (COE, CSE)
+    are deferred rather than guessed at.
+    """
+
+    def __init__(self, r_max: float = 4.0, n_bins: int = 60) -> None:
+        self.r_max = r_max
+        self.n_bins = n_bins
+
+    def theoretical_r2(self, r: np.ndarray) -> np.ndarray:
+        return sine_kernel_r2(r)
+
+    def validate(self, spectrum: Spectrum) -> CorrelationValidationResult:
+        if spectrum.beta != 2:
+            raise ValueError(
+                "SineKernel currently only validates beta=2 (CUE) spectra; "
+                "the beta=1 (COE) and beta=4 (CSE) correlation kernels "
+                "require the fuller Pfaffian point-process machinery, "
+                "not yet implemented (see physicskit.rmt.stats.correlations)."
+            )
+        centers, estimate = pair_correlation_estimate(spectrum, r_max=self.r_max, n_bins=self.n_bins)
+        theory = self.theoretical_r2(centers)
+        rmse = float(np.sqrt(np.mean((estimate - theory) ** 2)))
+        return CorrelationValidationResult(rmse=rmse, r_max=self.r_max, n_bins=self.n_bins)

physicskit/rmt/validation/single_ring.py

@@ -0,0 +1,68 @@
+"""Single ring theorem benchmark for bi-unitarily-invariant non-Hermitian
+ensembles.
+
+References: Feinberg-Zee (1997); Guionnet-Krishnapur-Zeitouni (2011) --
+see ``physicskit.rmt.ensembles.single_ring`` for the full construction and
+precision notes.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..spectrum import Spectrum
+from ..stats.single_ring import annulus_radial_cdf, annulus_radial_pdf
+from .base import Benchmark, ValidationResult
+
+
+class SingleRingTheorem(Benchmark):
+    """Validates a bi-unitarily-invariant non-Hermitian Spectrum's
+    eigenvalue *radii* against the single ring theorem's radial marginal
+    (uniform on the annulus ``r_in <= |z| <= r_out``).
+
+    Like ``CircularLaw`` (its r_in=0 special case), overrides
+    ``validate`` because the base class compares ``spectrum.rescaled``
+    directly, but here it's the eigenvalue *magnitudes* that are
+    compared to a 1-D theoretical distribution.
+
+    Parameters
+    ----------
+    r_in : float
+    r_out : float
+        The theoretical ring radii (see
+        ``physicskit.rmt.stats.single_ring.single_ring_radii`` /
+        ``single_ring_radii_wishart_theory``).
+    """
+
+    def __init__(self, r_in: float, r_out: float) -> None:
+        if not 0.0 <= r_in < r_out:
+            raise ValueError(f"require 0 <= r_in < r_out, got r_in={r_in}, r_out={r_out}")
+        self.r_in = r_in
+        self.r_out = r_out
+
+    def theoretical_pdf(self, r: np.ndarray) -> np.ndarray:
+        return annulus_radial_pdf(r, self.r_in, self.r_out)
+
+    def theoretical_cdf(self, r: np.ndarray) -> np.ndarray:
+        return annulus_radial_cdf(r, self.r_in, self.r_out)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        # Inverse-CDF sampling: F(r) = (r^2-r_in^2)/(r_out^2-r_in^2)
+        # => r = sqrt(r_in^2 + U*(r_out^2-r_in^2)), U ~ Uniform(0,1)
+        u = rng.uniform(0.0, 1.0, size=size)
+        return np.sqrt(self.r_in**2 + u * (self.r_out**2 - self.r_in**2))
+
+    def validate(self, spectrum: Spectrum, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        from scipy.stats import kstest, wasserstein_distance
+
+        radii = np.abs(spectrum.rescaled.ravel())
+        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),
+        )

physicskit/rmt/validation/tracy_widom.py

@@ -0,0 +1,89 @@
+"""Tracy-Widom soft-edge benchmark for the Gaussian ensembles.
+
+References: C. A. Tracy, H. Widom, Commun. Math. Phys. 159 (1994) 151;
+Commun. Math. Phys. 177 (1996) 727.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from scipy.stats import kstest, wasserstein_distance
+
+from ..ensembles.base import MatrixEnsemble
+from ..spectrum import Spectrum
+from ..stats.tracy_widom import (
+    largest_eigenvalues,
+    tracy_widom_cdf,
+    tracy_widom_edge_scale,
+    tracy_widom_rvs,
+)
+from .base import ValidationResult
+
+
+class TracyWidom:
+    """Validates the largest-eigenvalue statistic of a Gaussian-ensemble
+    Spectrum against the Tracy-Widom soft-edge law at the matching beta.
+
+    Only beta in {1, 2, 4} are supported (F_1, F_2, F_4 have closed
+    forms; general beta does not -- see ``physicskit.rmt.stats.tracy_widom``).
+    Overrides ``validate`` (rather than just providing
+    ``theoretical_cdf``/``reference_samples``) because the relevant
+    statistic is the *largest* eigenvalue after a beta-dependent edge
+    rescaling -- not the full ``spectrum.rescaled`` array the base class
+    compares directly.
+    """
+
+    reference_size: int = 200_000
+
+    def __init__(self, beta: int) -> None:
+        if beta not in (1, 2, 4):
+            raise ValueError(f"TracyWidom only supports beta in (1, 2, 4), got {beta}")
+        self.beta = beta
+
+    def theoretical_cdf(self, s: np.ndarray) -> np.ndarray:
+        return tracy_widom_cdf(s, self.beta)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        return tracy_widom_rvs(size, self.beta, rng)
+
+    def validate(self, spectrum: Spectrum, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        if spectrum.beta != self.beta:
+            raise ValueError(f"Spectrum beta ({spectrum.beta}) does not match TracyWidom benchmark beta ({self.beta})")
+        lam_max = largest_eigenvalues(spectrum)
+        scale = tracy_widom_edge_scale(spectrum.n, self.beta)
+        edge_stat = scale * (lam_max - 2.0)
+
+        ks = kstest(edge_stat, self.theoretical_cdf)
+        rng = np.random.default_rng(seed)
+        reference = self.reference_samples(self.reference_size, rng)
+        wd = wasserstein_distance(edge_stat, reference)
+        return ValidationResult(
+            ks_statistic=float(ks.statistic),
+            ks_pvalue=float(ks.pvalue),
+            wasserstein_distance=float(wd),
+            n_eigenvalues=len(edge_stat),
+        )
+
+    def convergence_curve(
+        self,
+        ensemble_factory: Callable[..., MatrixEnsemble],
+        n_values: list[int],
+        n_samples: int = 200,
+        seed: int | np.random.Generator | None = None,
+    ) -> list[tuple[int, ValidationResult]]:
+        """Convergence to Tracy-Widom is notoriously slow (the largest
+        eigenvalue is a single extreme-value statistic per sample, so
+        each matrix contributes only one data point -- n_samples needs
+        to be much larger than in the bulk-statistic benchmarks to get
+        a stable KS estimate at all). Expect a shallower, noisier trend
+        than the semicircle/Marchenko-Pastur convergence curves."""
+        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/universality.py

@@ -0,0 +1,100 @@
+"""Universality benchmark: confirms that the semicircle law (and,
+optionally, the Wigner surmise) hold across several different entry
+distributions, not just Gaussian ones -- a stronger validation of "the
+theory is implemented correctly" than fitting a single Gaussian case
+ever could be, since it tests the actual universality *claim* of RMT
+rather than one specific realization of it.
+
+This module ties together ``physicskit.rmt.ensembles.universality`` (the
+entry-distribution-agnostic ensemble) and the already-existing
+``WignerSemicircle`` / ``WignerSurmise`` benchmarks -- no new
+theoretical curve is needed here, since universality means the SAME
+curve applies regardless of entry distribution.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from ..ensembles.universality import (
+    GeneralWignerEnsemble,
+    exponential_centered_unit_variance,
+    rademacher,
+    uniform_unit_variance,
+)
+from .base import ValidationResult
+from .wigner_semicircle import WignerSemicircle
+
+EntrySampler = Callable[[np.random.Generator, tuple[int, ...]], np.ndarray]
+
+#: A representative, deliberately varied set of entry distributions:
+#: symmetric-bounded (uniform), symmetric-discrete (Rademacher), and
+#: asymmetric-unbounded (centered exponential) -- if universality holds
+#: across all three, entry-distribution shape/boundedness/symmetry are
+#: all ruled out as confounds.
+DEFAULT_ENTRY_DISTRIBUTIONS: dict[str, EntrySampler] = {
+    "uniform": uniform_unit_variance,
+    "rademacher": rademacher,
+    "exponential": exponential_centered_unit_variance,
+}
+
+
+@dataclass
+class UniversalityResult:
+    """Per-distribution validation results plus a summary judgment."""
+
+    per_distribution: dict[str, ValidationResult] = field(default_factory=dict)
+    max_ks_statistic: float = 0.0
+
+    def __repr__(self):
+        lines = [f"  {name}: {result}" for name, result in self.per_distribution.items()]
+        return "UniversalityResult(\n" + "\n".join(lines) + f"\n  max_ks={self.max_ks_statistic:.5f}\n)"
+
+
+def check_universality(
+    n: int,
+    beta: int,
+    n_samples: int = 25,
+    seed: int | None = None,
+    entry_distributions: dict[str, EntrySampler] | None = None,
+    ks_threshold: float = 0.02,
+) -> UniversalityResult:
+    """Sample ``GeneralWignerEnsemble`` with several entry distributions
+    at the given n and beta, validate each against the Wigner semicircle
+    law, and return per-distribution results plus a pass/fail summary.
+
+    Parameters
+    ----------
+    n : int
+    beta : int
+        1 or 2 (see ``GeneralWignerEnsemble``).
+    n_samples : int
+    seed : int or None
+    entry_distributions : dict or None
+        name -> entry_sampler callable; defaults to
+        ``DEFAULT_ENTRY_DISTRIBUTIONS``.
+    ks_threshold : float
+        Each distribution's KS statistic against the semicircle law
+        must be below this for the overall check to pass.
+
+    Returns
+    -------
+    UniversalityResult
+    """
+    if entry_distributions is None:
+        entry_distributions = DEFAULT_ENTRY_DISTRIBUTIONS
+
+    benchmark = WignerSemicircle()
+    per_distribution = {}
+    for i, (name, sampler) in enumerate(entry_distributions.items()):
+        ensemble_seed = None if seed is None else seed + i
+        ensemble = GeneralWignerEnsemble(n=n, entry_sampler=sampler, beta=beta, seed=ensemble_seed)
+        spectrum = ensemble.sample(n_samples=n_samples)
+        result = benchmark.validate(spectrum, seed=ensemble_seed)
+        per_distribution[name] = result
+
+    max_ks = max(r.ks_statistic for r in per_distribution.values())
+    return UniversalityResult(per_distribution=per_distribution, max_ks_statistic=max_ks)

physicskit/rmt/validation/wachter.py

@@ -0,0 +1,52 @@
+"""Wachter distribution benchmark for the Jacobi (MANOVA) ensembles.
+
+Reference: K. W. Wachter, Ann. Statist. 8 (1980) 937.
+"""
+
+import numpy as np
+from scipy.integrate import cumulative_trapezoid
+from scipy.interpolate import interp1d
+
+from ..stats.wachter import wachter_pdf, wachter_support
+from .base import Benchmark
+
+
+class Wachter(Benchmark):
+    """Validates the empirical spectral density of a Jacobi ensemble
+    (JOE/JUE) against the exact Wachter law for given inverse aspect
+    ratios a = m1/n, b = m2/n.
+
+    CDF and its inverse are built once via a fine-grid cumulative
+    trapezoidal integration and cached as interpolators, for the same
+    reason as ``physicskit.rmt.validation.marchenko_pastur.MarchenkoPastur``: a
+    KS test evaluates the CDF at every data point, so per-point
+    ``quad`` calls (as in ``physicskit.rmt.stats.wachter.wachter_cdf``) would be
+    far too slow.
+    """
+
+    def __init__(self, a: float, b: float, grid_size: int = 4000) -> None:
+        if a < 1 or b < 1:
+            raise ValueError(f"a and b are inverse aspect ratios (m/n) and must be >= 1; got a={a}, b={b}")
+        self.a = a
+        self.b = b
+        self._lo, self._hi = wachter_support(a, b)
+
+        grid = np.linspace(self._lo, self._hi, grid_size)
+        pdf_vals = wachter_pdf(grid, a, b)
+        cdf_vals = cumulative_trapezoid(pdf_vals, grid, initial=0.0)
+        cdf_vals /= cdf_vals[-1]
+        self._grid = grid
+        self._pdf_vals = pdf_vals
+        self._cdf_interp = interp1d(grid, cdf_vals, bounds_error=False, fill_value=(0.0, 1.0))
+        self._inv_cdf_interp = interp1d(cdf_vals, grid, bounds_error=False, fill_value=(self._lo, self._hi))
+
+    def theoretical_pdf(self, x: np.ndarray) -> np.ndarray:
+        return wachter_pdf(x, self.a, self.b)
+
+    def theoretical_cdf(self, x: np.ndarray) -> np.ndarray:
+        x = np.asarray(x, dtype=float)
+        return np.where(x <= self._lo, 0.0, np.where(x >= self._hi, 1.0, self._cdf_interp(x)))
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        u = rng.uniform(0.0, 1.0, size=size)
+        return self._inv_cdf_interp(u)

physicskit/rmt/validation/wigner_semicircle.py

@@ -0,0 +1,40 @@
+"""Wigner semicircle law benchmark.
+
+References
+----------
+E. Wigner, "Characteristic Vectors of Bordered Matrices With Infinite
+Dimensions", Ann. Math. 62 (1955) 548.
+E. Wigner, "On the Distribution of the Roots of Certain Symmetric
+Matrices", Ann. Math. 67 (1958) 325.
+"""
+
+import numpy as np
+from scipy.stats import beta as beta_dist
+
+from ..stats.density import semicircle_cdf, semicircle_pdf
+from .base import Benchmark
+
+
+class WignerSemicircle(Benchmark):
+    """Validates the empirical spectral density of a Gaussian
+    beta-ensemble (GOE/GUE/GSE, or general beta-Hermite) against the
+    exact Wigner semicircle law.
+
+    The semicircle distribution on [-radius, radius] is an affine
+    transform of Beta(3/2, 3/2): if U ~ Beta(3/2, 3/2), then
+    X = radius * (2U - 1) has semicircle density, which is how
+    ``reference_samples`` draws from the theoretical law.
+    """
+
+    def __init__(self, radius: float = 2.0) -> None:
+        self.radius = radius
+
+    def theoretical_cdf(self, x: np.ndarray) -> np.ndarray:
+        return semicircle_cdf(x, radius=self.radius)
+
+    def theoretical_pdf(self, x: np.ndarray) -> np.ndarray:
+        return semicircle_pdf(x, radius=self.radius)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        u = beta_dist.rvs(1.5, 1.5, size=size, random_state=rng)
+        return self.radius * (2.0 * u - 1.0)

physicskit/rmt/validation/wigner_surmise.py

@@ -0,0 +1,58 @@
+"""Benchmark for the (generalized) Wigner surmise -- the nearest-neighbor
+spacing distribution of the Gaussian ensembles.
+
+Unlike ``WignerSemicircle``, this benchmark validates a *derived*
+statistic (unfolded spacings), so ``validate`` here expects pre-computed
+spacings (from ``physicskit.rmt.stats.spacing.nearest_neighbor_spacings``), not a
+raw Spectrum -- unfolding and edge-trimming choices belong to the caller,
+not baked into the benchmark.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import kstest, wasserstein_distance
+
+from ..stats.spacing import (
+    wigner_surmise_cdf,
+    wigner_surmise_pdf,
+    wigner_surmise_samples,
+)
+from .base import ValidationResult
+
+
+class WignerSurmise:
+    """Validates a spacing sample against the generalized Wigner surmise
+    at a given Dyson index beta.
+
+    References: Wigner's original surmise (beta=1); Mehta, *Random
+    Matrices* (3rd ed.), 2004, for the beta=2, 4 cases.
+    """
+
+    reference_size: int = 200_000
+
+    def __init__(self, beta: float) -> None:
+        self.beta = beta
+
+    def theoretical_pdf(self, s: np.ndarray) -> np.ndarray:
+        return wigner_surmise_pdf(s, self.beta)
+
+    def theoretical_cdf(self, s: np.ndarray) -> np.ndarray:
+        return wigner_surmise_cdf(s, self.beta)
+
+    def reference_samples(self, size: int, rng: np.random.Generator) -> np.ndarray:
+        return wigner_surmise_samples(size, self.beta, rng)
+
+    def validate(self, spacings: np.ndarray, seed: int | np.random.Generator | None = None) -> ValidationResult:
+        """Compare an array of (already unfolded, already edge-trimmed)
+        spacings against the surmise."""
+        ks = kstest(spacings, self.theoretical_cdf)
+        rng = np.random.default_rng(seed)
+        reference = self.reference_samples(self.reference_size, rng)
+        wd = wasserstein_distance(spacings, reference)
+        return ValidationResult(
+            ks_statistic=float(ks.statistic),
+            ks_pvalue=float(ks.pvalue),
+            wasserstein_distance=float(wd),
+            n_eigenvalues=len(spacings),
+        )