physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/tests/test_spacing_and_ratios.py

@@ -0,0 +1,122 @@
+"""Tests for the nearest-neighbor spacing distribution, the ratio
+statistic, and their respective surmises.
+
+Important methodological distinction from ``test_gaussian_semicircle.py``:
+the Wigner semicircle law is the *exact* N -> infinity limit, so its KS
+distance to a sampled ensemble should shrink toward zero as N grows. The
+Wigner surmise (spacing) and the Atas et al. (2013) surmise (ratio) are
+NOT exact limits -- they are known, very good, but imperfect
+approximations (a fixed ~0.1-1% level discrepancy from the true limiting
+distribution, which involves Fredholm-determinant sine-kernel statistics
+with no elementary closed form). That gap does not vanish as N grows, so
+these tests check "already small at moderate N" rather than "shrinks to
+zero" -- asserting the latter would eventually fail once N is large
+enough for the surmise's own approximation error to dominate over
+finite-size noise, which is expected behavior, not a defect.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+CLASSICAL = [
+    ("GOE", rmt.ensembles.GOE, 1),
+    ("GUE", rmt.ensembles.GUE, 2),
+    ("GSE", rmt.ensembles.GSE, 4),
+]
+
+# Exact surmise-mean reference values (Atas et al. 2013), NOT the
+# numerically-exact full-ensemble means (which differ at the ~1% level --
+# see docstring in physicskit.rmt/stats/ratios.py).
+RATIO_SURMISE_EXACT_MEANS = {
+    1: 4 - 2 * np.sqrt(3),  # 0.535898...
+}
+
+
+@pytest.mark.parametrize("name,cls,beta", CLASSICAL)
+def test_unfolded_mean_spacing_is_unity(name, cls, beta):
+    ens = cls(n=1000, seed=10)
+    spectrum = cached_sample(ens, n_samples=30)
+    spacings = rmt.stats.nearest_neighbor_spacings(spectrum, rmt.stats.semicircle_cdf)
+    assert spacings.mean() == pytest.approx(1.0, abs=0.01)
+
+
+@pytest.mark.parametrize("name,cls,beta", CLASSICAL)
+def test_spacing_distribution_matches_surmise_at_moderate_n(name, cls, beta):
+    # Moderate N and sample count deliberately: pooling an enormous number
+    # of spacings would give the KS test enough power to reject on the
+    # surmise's own known small approximation error rather than anything
+    # wrong with the implementation (see module docstring).
+    ens = cls(n=1000, seed=20)
+    spectrum = cached_sample(ens, n_samples=20)
+    spacings = rmt.stats.nearest_neighbor_spacings(spectrum, rmt.stats.semicircle_cdf)
+
+    benchmark = rmt.validation.WignerSurmise(beta=beta)
+    result = benchmark.validate(spacings, seed=20)
+    assert result.ks_statistic < 0.015
+    assert result.wasserstein_distance < 0.01
+
+
+@pytest.mark.parametrize("name,cls,beta", CLASSICAL)
+def test_ratio_statistics_in_unit_interval(name, cls, beta):
+    ens = cls(n=500, seed=30)
+    spectrum = cached_sample(ens, n_samples=10)
+    ratios = rmt.stats.ratio_statistics(spectrum)
+    assert np.all(ratios >= 0.0)
+    assert np.all(ratios <= 1.0)
+
+
+@pytest.mark.parametrize("name,cls,beta", CLASSICAL)
+def test_ratio_distribution_matches_surmise_at_moderate_n(name, cls, beta):
+    ens = cls(n=1000, seed=40)
+    spectrum = cached_sample(ens, n_samples=20)
+    ratios = rmt.stats.ratio_statistics(spectrum)
+
+    benchmark = rmt.validation.RatioDistribution(beta=beta)
+    result = benchmark.validate(ratios, seed=40)
+    assert result.ks_statistic < 0.02
+    assert result.wasserstein_distance < 0.01
+
+
+def test_ratio_surmise_exact_mean_matches_atas_et_al():
+    # The surmise's OWN mean (not the full-ensemble numerical mean) has a
+    # known closed form at beta=1: 4 - 2*sqrt(3). This checks the surmise
+    # model itself, independent of any sampling.
+    model = rmt.stats.RatioSurmise(beta=1)
+    grid = np.linspace(0, 1, 200_000)
+    mean_r = np.trapezoid(grid * model.pdf(grid), grid)
+    assert mean_r == pytest.approx(RATIO_SURMISE_EXACT_MEANS[1], abs=1e-3)
+
+
+@pytest.mark.parametrize("name,cls,beta", CLASSICAL)
+def test_spacing_and_ratio_agree_independently(name, cls, beta):
+    # The spacing distribution requires unfolding; the ratio statistic
+    # does not. If an unfolding bug were inflating apparent agreement (or
+    # disagreement) in the spacing test, the ratio test -- computed on
+    # raw eigenvalues -- would not be affected the same way. Checking
+    # both pass together (loosely) guards against that class of bug.
+    ens = cls(n=1200, seed=50)
+    spectrum = cached_sample(ens, n_samples=20)
+
+    spacings = rmt.stats.nearest_neighbor_spacings(spectrum, rmt.stats.semicircle_cdf)
+    spacing_result = rmt.validation.WignerSurmise(beta=beta).validate(spacings, seed=50)
+
+    ratios = rmt.stats.ratio_statistics(spectrum)
+    ratio_result = rmt.validation.RatioDistribution(beta=beta).validate(ratios, seed=50)
+
+    assert spacing_result.ks_statistic < 0.02
+    assert ratio_result.ks_statistic < 0.02
+
+
+def test_ratio_statistics_and_spacings_skip_rows_too_short_after_edge_trim():
+    # edge_trim=0.5 on a small n leaves fewer than the required minimum
+    # eigenvalues per row, so every row is skipped (the "continue" guard)
+    # and pooling across zero surviving rows raises downstream.
+    ens = rmt.ensembles.GOE(n=5, seed=0)
+    spectrum = ens.sample(n_samples=3)
+    with pytest.raises(ValueError):
+        rmt.stats.ratio_statistics(spectrum, edge_trim=0.5)
+    with pytest.raises(ValueError):
+        rmt.stats.nearest_neighbor_spacings(spectrum, rmt.stats.semicircle_cdf, edge_trim=0.5)

physicskit/rmt/tests/test_sparse.py

@@ -0,0 +1,71 @@
+"""Tests for the sparse random matrix ensembles (ErdosRenyiEnsemble,
+BernoulliWignerEnsemble).
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+
+def test_invalid_p_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.ErdosRenyiEnsemble(n=10, p=0.0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.BernoulliWignerEnsemble(n=10, p=1.5, seed=0)
+
+
+def test_erdos_renyi_reproducibility():
+    ens_a = rmt.ensembles.ErdosRenyiEnsemble(n=40, p=0.2, seed=42)
+    ens_b = rmt.ensembles.ErdosRenyiEnsemble(n=40, p=0.2, seed=42)
+    spec_a = ens_a.sample(n_samples=3)
+    spec_b = ens_b.sample(n_samples=3)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+def test_erdos_renyi_has_furedi_komlos_outlier():
+    # The largest eigenvalue should sit near the mean degree n*p,
+    # well separated from the sqrt(n*p*(1-p))-scale bulk.
+    n, p = 1500, 0.05
+    ens = rmt.ensembles.ErdosRenyiEnsemble(n=n, p=p, seed=1)
+    spectrum = cached_sample(ens, n_samples=3)
+    mean_degree = n * p
+    largest = spectrum.eigenvalues.max(axis=1)
+    assert np.all(np.abs(largest - mean_degree) < 0.15 * mean_degree)
+
+
+def test_erdos_renyi_bulk_approaches_semicircle_scale_when_dense():
+    # In the crossover regime (n*p large), the BULK (all but the top
+    # outlier) should stay within the semicircle radius
+    # 2*sqrt(n*p*(1-p)) up to a modest finite-size margin.
+    n, p = 2000, 0.1
+    ens = rmt.ensembles.ErdosRenyiEnsemble(n=n, p=p, seed=2)
+    spectrum = cached_sample(ens, n_samples=3)
+    scale = ens.natural_scale()
+    for row in spectrum.eigenvalues:
+        bulk = np.sort(row)[:-1]  # drop the single largest (outlier)
+        assert bulk.max() < 2.2 * scale
+        assert bulk.min() > -2.2 * scale
+
+
+def test_bernoulli_wigner_reproducibility():
+    ens_a = rmt.ensembles.BernoulliWignerEnsemble(n=40, p=0.3, seed=42)
+    ens_b = rmt.ensembles.BernoulliWignerEnsemble(n=40, p=0.3, seed=42)
+    spec_a = ens_a.sample(n_samples=3)
+    spec_b = ens_b.sample(n_samples=3)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+@pytest.mark.parametrize("p", [0.3, 0.05, 0.01])
+def test_bernoulli_wigner_matches_semicircle_even_when_sparse(p):
+    # No Furedi-Komlos outlier here (mean-zero entries) -- the bulk
+    # should match the semicircle law directly, validated against the
+    # already-implemented WignerSemicircle benchmark, even at
+    # substantial sparsity (as long as n*p stays reasonably large).
+    n = 2000
+    ens = rmt.ensembles.BernoulliWignerEnsemble(n=n, p=p, seed=3)
+    spectrum = cached_sample(ens, n_samples=10)
+    benchmark = rmt.validation.WignerSemicircle()
+    result = benchmark.validate(spectrum, seed=3)
+    assert result.ks_statistic < 0.03

physicskit/rmt/tests/test_spectrum.py

@@ -0,0 +1,27 @@
+"""Coverage for physicskit.rmt.spectrum.Spectrum's simple derived properties
+and __repr__ (previously never exercised directly)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+import physicskit.rmt as rmt
+
+
+def test_flat_ravels_all_samples():
+    ens = rmt.ensembles.GOE(n=5, seed=0)
+    spectrum = ens.sample(n_samples=3)
+    assert spectrum.flat.shape == (15,)
+    np.testing.assert_allclose(spectrum.flat, spectrum.eigenvalues.ravel())
+
+
+def test_n_samples_matches_first_axis():
+    ens = rmt.ensembles.GOE(n=5, seed=0)
+    spectrum = ens.sample(n_samples=4)
+    assert spectrum.n_samples == 4
+
+
+def test_repr_contains_ensemble_name_and_n_samples():
+    ens = rmt.ensembles.GOE(n=5, seed=0)
+    spectrum = ens.sample(n_samples=2)
+    assert repr(spectrum) == f"Spectrum(ensemble='GOE', n=5, beta={spectrum.beta}, n_samples=2)"

physicskit/rmt/tests/test_syk.py

@@ -0,0 +1,136 @@
+"""Tests for the Sachdev-Ye-Kitaev (SYK) ensemble.
+
+Unlike every other ensemble in this package, SYK is not built from
+i.i.d. matrix entries -- it's an explicit many-body Hamiltonian on an
+exponentially large (2**(N/2)-dimensional) Hilbert space. Validation
+here is therefore structural (Clifford algebra, Hermiticity, the exact
+algebraic reason q=4 needs no phase but q=2 needs a factor of i) rather
+than against a closed-form limiting spectral density, which -- unlike
+the semicircle/Marchenko-Pastur/circular laws elsewhere in this package
+-- has no simple exact form for general q at finite N. Kept to small N
+throughout (cost is exponential in N, not polynomial -- see the module
+docstring).
+"""
+
+import math
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+from physicskit.rmt.ensembles.syk import _sample_syk_hamiltonian, majorana_operators
+
+
+@pytest.mark.parametrize("n", [4, 6, 8])
+def test_majorana_operators_are_hermitian(n):
+    for gamma in majorana_operators(n):
+        assert np.abs(gamma - gamma.conj().T).max() < 1e-12
+
+
+@pytest.mark.parametrize("n", [4, 6, 8])
+def test_majorana_operators_satisfy_clifford_algebra(n):
+    gammas = majorana_operators(n)
+    dim = gammas[0].shape[0]
+    identity = np.eye(dim)
+    for a in range(n):
+        for b in range(n):
+            anticommutator = gammas[a] @ gammas[b] + gammas[b] @ gammas[a]
+            target = 2.0 * identity if a == b else np.zeros((dim, dim))
+            assert np.abs(anticommutator - target).max() < 1e-10
+
+
+def test_majorana_operators_reject_odd_n():
+    with pytest.raises(ValueError):
+        majorana_operators(5)
+
+
+@pytest.mark.parametrize("q,should_need_phase", [(2, True), (4, False), (6, True), (8, False)])
+def test_raw_q_body_product_hermiticity_matches_derivation(q, should_need_phase):
+    # Reversing q distinct anticommuting Majoranas picks up sign
+    # (-1)**(q*(q-1)/2) -- the raw (no i**(q/2) prefactor) product should
+    # be Hermitian exactly when that sign is +1, i.e. exactly when
+    # should_need_phase is False. This is the algebraic fact the
+    # i**(q/2) prefactor in the module docstring is derived from;
+    # checked directly here rather than only trusted from the derivation.
+    n = 8
+    gammas = majorana_operators(n)
+    idx = list(range(q))
+    term = gammas[idx[0]]
+    for i in idx[1:]:
+        term = term @ gammas[i]
+    is_hermitian = np.abs(term - term.conj().T).max() < 1e-10
+    assert is_hermitian == (not should_need_phase)
+    # With the i**(q/2) prefactor applied, it should always be Hermitian.
+    phased = (1j ** (q // 2)) * term
+    assert np.abs(phased - phased.conj().T).max() < 1e-10
+
+
+def test_beta_is_none():
+    ens = rmt.ensembles.SYKEnsemble(n=8, seed=0)
+    assert ens.beta is None
+
+
+def test_default_q_is_four():
+    ens = rmt.ensembles.SYKEnsemble(n=8, seed=0)
+    assert ens.q == 4
+
+
+@pytest.mark.parametrize("n", [4, 6, 8, 10])
+def test_produces_2_pow_n_over_2_real_eigenvalues(n):
+    ens = rmt.ensembles.SYKEnsemble(n=n, seed=1)
+    spectrum = cached_sample(ens, n_samples=3)
+    assert spectrum.eigenvalues.shape == (3, 2 ** (n // 2))
+    assert not np.iscomplexobj(spectrum.eigenvalues)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+def test_reproducibility():
+    ens_a = rmt.ensembles.SYKEnsemble(n=8, seed=42)
+    ens_b = rmt.ensembles.SYKEnsemble(n=8, seed=42)
+    spec_a = ens_a.sample(n_samples=3)
+    spec_b = ens_b.sample(n_samples=3)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+def test_invalid_parameters_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.SYKEnsemble(n=7, seed=0)  # odd n
+    with pytest.raises(ValueError):
+        rmt.ensembles.SYKEnsemble(n=8, q=3, seed=0)  # odd q
+    with pytest.raises(ValueError):
+        rmt.ensembles.SYKEnsemble(n=8, q=10, seed=0)  # q > n
+
+
+def test_q_two_produces_a_finite_nondegenerate_free_fermion_spectrum():
+    # q=2 is the (non-chaotic) free-fermion special case: H is built
+    # from a single random N x N antisymmetric coupling matrix rather
+    # than C(N,4) independent ones. Just check it produces a sane,
+    # genuinely nonzero-scale spectrum -- not a specific numeric target,
+    # since the exact eigenvalue scale for q=2 (checked empirically
+    # during development to grow roughly like sqrt(N), not stay O(1) the
+    # way q=4's does) isn't asserted here.
+    ens = rmt.ensembles.SYKEnsemble(n=10, q=2, coupling=1.0, seed=3)
+    spectrum = cached_sample(ens, n_samples=20)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+    assert spectrum.eigenvalues.std() > 0.1
+
+
+def test_coupling_scales_hamiltonian_linearly():
+    n, q = 8, 4
+    gammas = majorana_operators(n)
+    h1 = _sample_syk_hamiltonian(n, q, 1.0, np.random.default_rng(5), gammas)
+    h2 = _sample_syk_hamiltonian(n, q, 2.0, np.random.default_rng(5), gammas)
+    np.testing.assert_allclose(h2, 2.0 * h1)
+
+
+def test_variance_normalization_matches_maldacena_stanford():
+    # <J_{i1...iq}^2> = (q-1)! * J^2 / N^(q-1) -- checked directly against
+    # the empirical variance of many independently drawn couplings,
+    # rather than only trusted from the module docstring's citation.
+    n, q, coupling = 12, 4, 1.5
+    rng = np.random.default_rng(6)
+    expected_variance = math.factorial(q - 1) * coupling**2 / n ** (q - 1)
+    std = math.sqrt(expected_variance)
+    draws = rng.normal(0.0, std, size=200_000)
+    assert draws.var() == pytest.approx(expected_variance, rel=0.05)

physicskit/rmt/tests/test_tracy_widom.py

@@ -0,0 +1,113 @@
+"""Tests for the Painleve II solution and the Tracy-Widom soft-edge
+benchmark.
+
+Two things were determined empirically during development, not assumed
+from memory, and are worth testing explicitly here rather than only in
+the module docstring: (1) q(x)'s known asymptotic tail
+q(x) ~ sqrt(-x/2) as x -> -infinity, and (2) the beta=4 (GSE) edge
+scaling requires (2n)^(2/3), not n^(2/3) -- confirmed by direct
+comparison against Monte Carlo GSE samples via a KS test, since the
+half-remembered formula did NOT match without this factor.
+
+Note on statistical power: the largest eigenvalue is a single
+extreme-value statistic per matrix sample, so pooling matters much less
+than the bulk-statistic benchmarks (each sample of GOE/GUE/GSE
+contributes exactly one data point to the edge-statistic distribution).
+n_samples in these tests is correspondingly large (hundreds), unlike
+elsewhere in the test suite.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+
+def test_painleve_ii_matches_known_asymptotic_tail():
+    # Re-derive q via the same ODE construction used internally, at a
+    # couple of points in the asymptotic regime, and compare to the
+    # known analytic tail sqrt(-x/2).
+    from scipy.integrate import solve_ivp
+    from scipy.special import airy
+
+    def rhs(x, y):
+        qv, qp = y
+        return [qp, x * qv + 2.0 * qv**3]
+
+    x0 = 6.0
+    ai, aip, _, _ = airy(x0)
+    ivp = solve_ivp(rhs, [x0, -6.0], [ai, aip], dense_output=True, rtol=1e-12, atol=1e-14, max_step=0.005)
+    for x in [-6.0, -5.0, -4.0]:
+        q_val = ivp.sol(x)[0]
+        asymptotic = np.sqrt(-x / 2.0)
+        assert q_val == pytest.approx(asymptotic, rel=0.01)
+
+
+def test_cdfs_are_monotonic_and_span_zero_to_one():
+    grid = np.linspace(-6, 6, 200)
+    for beta in (1, 2, 4):
+        cdf = rmt.stats.tracy_widom_cdf(grid, beta)
+        assert np.all(np.diff(cdf) >= -1e-10)  # monotone non-decreasing
+        assert cdf[0] < 0.01
+        assert cdf[-1] > 0.99
+
+
+def test_unsupported_beta_rejected():
+    with pytest.raises(ValueError):
+        rmt.stats.tracy_widom_cdf(0.0, beta=1.7)
+    with pytest.raises(ValueError):
+        rmt.validation.TracyWidom(beta=3)
+
+
+def test_edge_scale_beta4_has_extra_factor_of_two():
+    n = 500
+    scale_1 = rmt.stats.tracy_widom_edge_scale(n, beta=1)
+    scale_2 = rmt.stats.tracy_widom_edge_scale(n, beta=2)
+    scale_4 = rmt.stats.tracy_widom_edge_scale(n, beta=4)
+    assert scale_1 == pytest.approx(n ** (2 / 3))
+    assert scale_2 == pytest.approx(n ** (2 / 3))
+    assert scale_4 == pytest.approx((2 * n) ** (2 / 3))
+    assert scale_4 != pytest.approx(scale_1)  # the easy-to-miss distinction
+
+
+def test_edge_scale_and_rvs_reject_unsupported_beta():
+    with pytest.raises(ValueError):
+        rmt.stats.tracy_widom_edge_scale(100, beta=3)
+    with pytest.raises(ValueError):
+        rmt.stats.tracy_widom_rvs(5, beta=3, rng=np.random.default_rng(0))
+
+
+GAUSSIAN_TW = [
+    ("GOE", rmt.ensembles.GOE, 1),
+    ("GUE", rmt.ensembles.GUE, 2),
+    ("GSE", rmt.ensembles.GSE, 4),
+]
+
+
+@pytest.mark.parametrize("name,cls,beta", GAUSSIAN_TW)
+def test_largest_eigenvalue_matches_tracy_widom(name, cls, beta):
+    ens = cls(n=500, seed=10)
+    spectrum = cached_sample(ens, n_samples=400)
+    benchmark = rmt.validation.TracyWidom(beta=beta)
+    result = benchmark.validate(spectrum, seed=10)
+    assert result.ks_statistic < 0.08
+    assert result.ks_pvalue > 0.05
+
+
+@pytest.mark.parametrize("name,cls,beta", GAUSSIAN_TW)
+def test_beta_mismatch_rejected(name, cls, beta):
+    other_beta = {1: 2, 2: 4, 4: 1}[beta]
+    ens = cls(n=100, seed=0)
+    spectrum = cached_sample(ens, n_samples=20)
+    benchmark = rmt.validation.TracyWidom(beta=other_beta)
+    with pytest.raises(ValueError):
+        benchmark.validate(spectrum)
+
+
+def test_largest_eigenvalues_helper():
+    ens = rmt.ensembles.GUE(n=200, seed=0)
+    spectrum = cached_sample(ens, n_samples=10)
+    lam_max = rmt.stats.largest_eigenvalues(spectrum)
+    assert lam_max.shape == (10,)
+    np.testing.assert_allclose(lam_max, spectrum.rescaled.max(axis=1))

physicskit/rmt/tests/test_tridiagonal.py

@@ -0,0 +1,41 @@
+"""Coverage for physicskit.rmt.utils.tridiagonal's input-validation branches
+(each function is exercised through the ensembles that call it, but never
+with an invalid n/m that should raise)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from physicskit.rmt.utils.tridiagonal import (
+    sample_hermite_beta_eigenvalues,
+    sample_hermite_beta_eigenvalues_and_vectors,
+    sample_laguerre_beta_eigenvalues,
+)
+
+
+def test_sample_hermite_beta_eigenvalues_rejects_n_below_2():
+    with pytest.raises(ValueError):
+        sample_hermite_beta_eigenvalues(1, beta=1, rng=np.random.default_rng(0))
+
+
+def test_sample_hermite_beta_eigenvalues_and_vectors_rejects_n_below_2():
+    with pytest.raises(ValueError):
+        sample_hermite_beta_eigenvalues_and_vectors(1, beta=1, rng=np.random.default_rng(0))
+
+
+def test_sample_hermite_beta_eigenvalues_and_vectors_returns_matching_shapes():
+    n = 12
+    eigenvalues, eigenvectors = sample_hermite_beta_eigenvalues_and_vectors(n, beta=1, rng=np.random.default_rng(1))
+    assert eigenvalues.shape == (n,)
+    assert eigenvectors.shape == (n, n)
+    assert np.all(np.diff(eigenvalues) >= 0)  # ascending
+    # eigenvectors should be orthonormal columns
+    np.testing.assert_allclose(eigenvectors.T @ eigenvectors, np.eye(n), atol=1e-8)
+
+
+def test_sample_laguerre_beta_eigenvalues_rejects_n_below_2_and_m_below_n():
+    with pytest.raises(ValueError):
+        sample_laguerre_beta_eigenvalues(m=10, n=1, beta=2, rng=np.random.default_rng(0))
+    with pytest.raises(ValueError):
+        sample_laguerre_beta_eigenvalues(m=5, n=10, beta=2, rng=np.random.default_rng(0))

physicskit/rmt/tests/test_truncated_unitary.py

@@ -0,0 +1,80 @@
+"""Tests for TruncatedUnitaryEnsemble and its support-radius formula.
+
+The support radius sqrt(alpha) was NOT assumed from memory -- an initial
+guess of sqrt(1-alpha) had exactly the wrong alpha-dependence (shrinking
+as more of the unitary matrix is kept, contradicting the alpha=1 exact-
+unit-circle limit), caught by checking the direction of the trend before
+committing to a formula. The correct formula was then confirmed via the
+99th-percentile empirical eigenvalue radius converging cleanly to it as
+n grows at fixed alpha -- see
+``physicskit.rmt/ensembles/truncated_unitary.py`` module docstring.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+
+def test_invalid_alpha_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.TruncatedUnitaryEnsemble(m=10, alpha=0.0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.TruncatedUnitaryEnsemble(m=10, alpha=1.5, seed=0)
+    with pytest.raises(ValueError):
+        rmt.stats.truncated_unitary_edge_radius(0.0)
+
+
+def test_alpha_1_recovers_unit_circle():
+    # A full (untruncated) Haar-unitary matrix's eigenvalues lie exactly
+    # on the unit circle.
+    ens = rmt.ensembles.TruncatedUnitaryEnsemble(m=100, alpha=1.0, seed=0)
+    spectrum = cached_sample(ens, n_samples=5)
+    radii = np.abs(spectrum.eigenvalues.ravel())
+    np.testing.assert_allclose(radii, 1.0, atol=1e-8)
+
+
+def test_edge_radius_matches_formula():
+    for alpha in [0.2, 0.5, 0.8]:
+        assert rmt.stats.truncated_unitary_edge_radius(alpha) == pytest.approx(np.sqrt(alpha))
+
+
+def test_reproducibility():
+    ens_a = rmt.ensembles.TruncatedUnitaryEnsemble(m=40, alpha=0.5, seed=42)
+    ens_b = rmt.ensembles.TruncatedUnitaryEnsemble(m=40, alpha=0.5, seed=42)
+    spec_a = ens_a.sample(n_samples=3)
+    spec_b = ens_b.sample(n_samples=3)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+def test_edge_radius_converges_with_increasing_m():
+    # The 99th-percentile RESCALED radius (spectrum.rescaled already
+    # divides by natural_scale() = sqrt(alpha), so the target here is
+    # 1.0, not sqrt(alpha) again) should approach 1 as the truncated
+    # block size (and hence the full unitary dimension, at fixed alpha)
+    # grows -- checked here via a shrinking overshoot rather than a
+    # fixed tolerance at one size.
+    alpha = 0.5
+    overshoots = []
+    for m in [50, 100, 200, 400]:
+        ens = rmt.ensembles.TruncatedUnitaryEnsemble(m=m, alpha=alpha, seed=1)
+        spectrum = cached_sample(ens, n_samples=30)
+        radii = np.abs(spectrum.rescaled.ravel())
+        p99 = np.percentile(radii, 99)
+        overshoots.append(p99 - 1.0)
+    assert overshoots[0] > overshoots[-1] > -0.05
+    assert overshoots[-1] < 0.05
+
+
+def test_bulk_density_is_not_uniform_like_ginibre():
+    # Qualitative check of the module docstring's claim: mean radius
+    # should exceed a uniform disk's (2/3)*edge prediction, i.e. the
+    # density is weighted toward the edge, unlike the circular law's
+    # flat disk.
+    alpha = 0.5
+    ens = rmt.ensembles.TruncatedUnitaryEnsemble(m=300, alpha=alpha, seed=2)
+    spectrum = cached_sample(ens, n_samples=30)
+    radii = np.abs(spectrum.rescaled.ravel())
+    uniform_disk_mean = (2.0 / 3.0) * rmt.stats.truncated_unitary_edge_radius(alpha)
+    assert radii.mean() > uniform_disk_mean

physicskit/rmt/tests/test_validation_base.py

@@ -0,0 +1,25 @@
+"""Coverage for physicskit.rmt.validation.base: Benchmark.convergence_curve's
+generic (non-overridden) implementation and ValidationResult.__repr__ --
+every existing test that mentions convergence_curve deliberately loops
+manually instead, so the base implementation itself was never called."""
+
+from __future__ import annotations
+
+import numpy as np
+
+import physicskit.rmt as rmt
+
+
+def test_convergence_curve_generic_implementation_runs_and_shrinks():
+    benchmark = rmt.validation.WignerSemicircle()
+    results = benchmark.convergence_curve(lambda n, seed: rmt.ensembles.GOE(n=n, seed=seed), n_values=[20, 60], n_samples=5, seed=0)
+    assert [n for n, _ in results] == [20, 60]
+    ks_20 = results[0][1].ks_statistic
+    ks_60 = results[1][1].ks_statistic
+    assert ks_60 < ks_20
+
+
+def test_validation_result_repr():
+    result = rmt.validation.base.ValidationResult(ks_statistic=0.01234, ks_pvalue=0.5, wasserstein_distance=0.005, n_eigenvalues=100)
+    assert repr(result) == "ValidationResult(ks_statistic=0.01234, ks_pvalue=0.5, wasserstein_distance=0.00500, n_eigenvalues=100)"
+    assert np.isfinite(result.ks_statistic)

physicskit/rmt/tests/test_validation_misc.py

@@ -0,0 +1,67 @@
+"""Coverage for a handful of never-exercised convenience methods across
+physicskit.rmt.validation.*: each Benchmark subclass's theoretical_pdf
+(only theoretical_cdf is used internally elsewhere), the sine_kernel and
+real_ginibre result types' __repr__, UniversalityResult.__repr__, and the
+circular_law/tracy_widom convergence_curve overrides (every existing test
+that mentions them deliberately loops manually instead)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+import physicskit.rmt as rmt
+from physicskit.rmt.validation.real_ginibre import RealEigenvalueCountResult
+from physicskit.rmt.validation.sine_kernel import CorrelationValidationResult
+from physicskit.rmt.validation.universality import UniversalityResult
+
+
+def test_theoretical_pdf_methods_are_finite_and_nonnegative():
+    cases = [
+        (rmt.validation.MarchenkoPastur(gamma=0.5), np.linspace(0.1, 2.0, 10)),
+        (rmt.validation.Wachter(a=1.0, b=1.0), np.linspace(0.1, 0.9, 10)),
+        (rmt.validation.WignerSemicircle(), np.linspace(-1.5, 1.5, 10)),
+        (rmt.validation.SingleRingTheorem(r_in=0.5, r_out=1.0), np.linspace(0.5, 1.0, 10)),
+        (rmt.validation.CircularLaw(), np.linspace(0.1, 0.9, 10)),
+    ]
+    for benchmark, x in cases:
+        pdf = benchmark.theoretical_pdf(x)
+        assert np.all(np.isfinite(pdf))
+        assert np.all(pdf >= 0.0)
+
+
+def test_ratio_distribution_and_wigner_surmise_theoretical_pdf():
+    ratio = rmt.validation.RatioDistribution(beta=2)
+    r = np.linspace(0.0, 5.0, 10)
+    assert np.all(np.isfinite(ratio.theoretical_pdf(r)))
+
+    surmise = rmt.validation.WignerSurmise(beta=2)
+    s = np.linspace(0.0, 3.0, 10)
+    assert np.all(np.isfinite(surmise.theoretical_pdf(s)))
+
+
+def test_correlation_validation_result_repr():
+    result = CorrelationValidationResult(rmse=0.01234, r_max=4.0, n_bins=60)
+    assert repr(result) == "CorrelationValidationResult(rmse=0.01234, r_max=4.0, n_bins=60)"
+
+
+def test_real_eigenvalue_count_result_repr_and_relative_error():
+    result = RealEigenvalueCountResult(empirical_mean=8.0, theoretical=10.0, n=100)
+    assert result.relative_error == 0.2
+    assert repr(result) == "RealEigenvalueCountResult(empirical_mean=8.0000, theoretical=10.0000, n=100, relative_error=0.2000)"
+
+
+def test_universality_result_repr():
+    result = UniversalityResult(per_distribution={"uniform": rmt.validation.base.ValidationResult(0.01, 0.5, 0.02, 50)}, max_ks_statistic=0.01)
+    text = repr(result)
+    assert text.startswith("UniversalityResult(\n")
+    assert "max_ks=0.01000" in text
+
+
+def test_circular_law_and_tracy_widom_convergence_curve_overrides():
+    circ = rmt.validation.CircularLaw()
+    results_c = circ.convergence_curve(lambda n, seed: rmt.ensembles.GinUE(n=n, seed=seed), n_values=[20, 40], n_samples=5, seed=0)
+    assert [n for n, _ in results_c] == [20, 40]
+
+    tw = rmt.validation.TracyWidom(beta=2)
+    results_tw = tw.convergence_curve(lambda n, seed: rmt.ensembles.GUE(n=n, seed=seed), n_values=[20, 40], n_samples=10, seed=0)
+    assert [n for n, _ in results_tw] == [20, 40]