physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/tests/test_jacobi_wachter.py

@@ -0,0 +1,136 @@
+"""Tests for JOE, JUE and the Wachter distribution benchmark.
+
+The Wachter formula and its parametrization (a=m1/n, b=m2/n, inverse
+aspect ratios) were NOT taken from memory -- an initial guess at the
+formula (with a,b as the more familiar n/m aspect ratios) gave support
+edges outside [0, 1], which is impossible for this ensemble, immediately
+flagging the error. The correct formula and parametrization were found
+via a targeted search and then verified numerically against both real
+(beta=1) and complex (beta=2) simulations before being used here -- see
+``physicskit.rmt/stats/wachter.py`` and the design notes.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy.stats import linregress
+
+import physicskit.rmt as rmt
+
+JACOBI = [
+    ("JOE", rmt.ensembles.JOE, 1),
+    ("JUE", rmt.ensembles.JUE, 2),
+    ("JSE", rmt.ensembles.JSE, 4),
+]
+
+
+@pytest.mark.parametrize("name,cls,beta", JACOBI)
+def test_beta_is_correct(name, cls, beta):
+    ens = cls(n=50, m1=150, m2=200, seed=0)
+    assert ens.beta == beta
+
+
+@pytest.mark.parametrize("name,cls,beta", JACOBI)
+def test_a_b_properties(name, cls, beta):
+    ens = cls(n=100, m1=200, m2=300, seed=0)
+    assert ens.a == pytest.approx(2.0)
+    assert ens.b == pytest.approx(3.0)
+
+
+@pytest.mark.parametrize("name,cls,beta", JACOBI)
+def test_eigenvalues_in_unit_interval(name, cls, beta):
+    ens = cls(n=200, m1=400, m2=600, seed=1)
+    spectrum = cached_sample(ens, n_samples=10)
+    assert np.all(spectrum.eigenvalues >= -1e-9)
+    assert np.all(spectrum.eigenvalues <= 1.0 + 1e-9)
+
+
+@pytest.mark.parametrize("name,cls,beta", JACOBI)
+def test_reproducibility(name, cls, beta):
+    ens_a = cls(n=80, m1=160, m2=240, seed=42)
+    ens_b = cls(n=80, m1=160, m2=240, 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("name,cls,beta", JACOBI)
+def test_support_matches_wachter_edges(name, cls, beta):
+    n, m1, m2 = 2000, 4000, 6000
+    ens = cls(n=n, m1=m1, m2=m2, seed=2)
+    spectrum = cached_sample(ens, n_samples=1)
+    lo, hi = rmt.stats.wachter_support(m1 / n, m2 / n)
+    eigs = spectrum.eigenvalues.ravel()
+    assert eigs.min() > lo - 0.05
+    assert eigs.max() < hi + 0.05
+    assert eigs.min() < lo + 0.08
+    assert eigs.max() > hi - 0.08
+
+
+@pytest.mark.parametrize("name,cls,beta", JACOBI)
+def test_wachter_convergence_shrinks_with_n(name, cls, beta):
+    # Looped manually (rather than via benchmark.convergence_curve) so
+    # each N's sample can be disk-cached individually.
+    m1_ratio, m2_ratio = 2.0, 3.0  # fixed inverse aspect ratios as n scales
+    n_values = [50, 150, 450]
+
+    benchmark = rmt.validation.Wachter(a=m1_ratio, b=m2_ratio)
+    results = []
+    for n in n_values:
+        ens = cls(n=n, m1=int(n * m1_ratio), m2=int(n * m2_ratio), seed=9)
+        spectrum = cached_sample(ens, n_samples=20)
+        results.append(benchmark.validate(spectrum, seed=9))
+
+    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.01
+
+
+def test_invalid_parameters_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.JOE(n=100, m1=50, m2=200, seed=0)  # m1 < n
+    with pytest.raises(ValueError):
+        rmt.ensembles.JacobiBetaEnsemble(n=100, m1=200, m2=200, beta=3, seed=0)
+    with pytest.raises(ValueError):
+        rmt.validation.Wachter(a=0.5, b=2.0)  # a < 1 invalid
+
+
+def test_jse_eigenvalue_count_is_n_not_2n():
+    # JSE's quaternion embedding internally builds 2n x 2n matrices; only
+    # the n distinct (post-Kramers-deduplication) eigenvalues should be
+    # returned, matching GSE/CSE/EffGSE's convention -- see module
+    # docstring in physicskit.rmt/ensembles/jacobi.py.
+    n = 40
+    ens = rmt.ensembles.JSE(n=n, m1=80, m2=120, seed=0)
+    spectrum = ens.sample(n_samples=2)
+    assert spectrum.eigenvalues.shape[1] == n
+
+
+def test_wachter_pdf_zero_outside_support():
+    a, b = 2.0, 3.0
+    lo, hi = rmt.stats.wachter_support(a, b)
+    assert rmt.stats.wachter_pdf(np.array([lo - 0.1, hi + 0.1]), a, b)[0] == 0.0
+    assert rmt.stats.wachter_pdf(np.array([lo - 0.1, hi + 0.1]), a, b)[1] == 0.0
+
+
+def test_wachter_pdf_scalar_integrand_is_zero_outside_support():
+    """quad() integrates _wachter_pdf_scalar directly (not the vectorized
+    wachter_pdf above) to build wachter_cdf; it needs the same
+    zero-outside-support guard."""
+    from physicskit.rmt.stats.wachter import _wachter_pdf_scalar
+
+    a, b = 2.0, 3.0
+    lo, hi = rmt.stats.wachter_support(a, b)
+    assert _wachter_pdf_scalar(lo - 0.1, a, b, lo, hi) == 0.0
+    assert _wachter_pdf_scalar(hi + 0.1, a, b, lo, hi) == 0.0
+
+
+def test_wachter_cdf_is_zero_below_and_one_above_support_and_monotonic():
+    a, b = 2.0, 3.0
+    lo, hi = rmt.stats.wachter_support(a, b)
+    x = np.linspace(lo - 0.1, hi + 0.1, 20)
+    cdf = rmt.stats.wachter_cdf(x, a, b)
+    assert cdf[0] == 0.0
+    assert cdf[-1] == 1.0
+    assert np.all(np.diff(cdf) >= -1e-12)

physicskit/rmt/tests/test_localization.py

@@ -0,0 +1,240 @@
+"""Tests for eigenvector-based localization statistics (inverse
+participation ratio) and the ``sample(return_eigenvectors=True)`` API.
+
+``ipr_theory``'s Dirichlet-moment formula was verified during
+development against direct Haar-random-vector Monte Carlo at beta=1, 2,
+4 before being trusted (see ``physicskit.rmt.stats.localization``). The
+tridiagonal-model ensembles (GOE/GUE/GSE via the fast
+Dumitriu-Edelman sampler) do NOT get eigenvector support from that
+formula for free: their raw eigenvectors were checked during development
+and found to be more localized than a true Haar vector (IPR ~2-3x too
+large, growing with n) -- only a genuinely dense diagonalization gives
+Haar-distributed eigenvectors, which is why
+``HermiteBetaEnsemble._sample_eigenvalues_and_vectors`` uses a separate
+dense construction for beta in (1, 2, 4). GSE (beta=4) eigenvectors are
+naturally 2n-dimensional complex vectors (n quaternionic "sites"), so
+they need the dedicated ``inverse_participation_ratio_quaternionic``
+(folding pairs of components first) rather than the plain
+``inverse_participation_ratio`` -- verified during development that the
+folded IPR matches ``ipr_theory(n, beta=4)`` to four significant figures.
+"""
+
+import numpy as np
+import pytest
+
+import physicskit.rmt as rmt
+
+
+def test_ensemble_without_eigenvector_support_raises():
+    ens = rmt.ensembles.LOE(n=20, m=25, seed=0)
+    with pytest.raises(NotImplementedError):
+        ens.sample(return_eigenvectors=True)
+
+
+def test_gse_eigenvectors_are_normalized_and_shaped_2n_by_n():
+    n = 20
+    ens = rmt.ensembles.GSE(n=n, seed=0)
+    spectrum = ens.sample(n_samples=2, return_eigenvectors=True)
+    assert spectrum.eigenvectors is not None
+    assert spectrum.eigenvalues.shape == (2, n)
+    assert spectrum.eigenvectors.shape == (2, 2 * n, n)
+    norms = np.sum(np.abs(spectrum.eigenvectors) ** 2, axis=1)
+    np.testing.assert_allclose(norms, 1.0, atol=1e-8)
+
+
+def test_gse_quaternionic_ipr_matches_haar_theory():
+    n = 200
+    ens = rmt.ensembles.GSE(n=n, seed=1)
+    spectrum = ens.sample(n_samples=20, return_eigenvectors=True)
+    ipr = rmt.stats.inverse_participation_ratio_quaternionic(spectrum.eigenvectors)
+    theory = rmt.stats.ipr_theory(n, beta=4)
+    assert ipr.mean() == pytest.approx(theory, rel=0.15)
+
+
+def test_naive_ipr_on_gse_eigenvectors_does_not_match_theory():
+    # Documents the pitfall: calling the plain (non-quaternionic) IPR
+    # function directly on GSE eigenvectors treats all 2n complex
+    # components as independent sites, which does NOT match
+    # ipr_theory(n, beta=4) -- inverse_participation_ratio_quaternionic
+    # must be used instead (see module docstring).
+    n = 200
+    ens = rmt.ensembles.GSE(n=n, seed=1)
+    spectrum = ens.sample(n_samples=20, return_eigenvectors=True)
+    naive_ipr = rmt.stats.inverse_participation_ratio(spectrum.eigenvectors)
+    theory = rmt.stats.ipr_theory(n, beta=4)
+    assert naive_ipr.mean() != pytest.approx(theory, rel=0.15)
+
+
+@pytest.mark.parametrize("cls", [rmt.ensembles.GOE, rmt.ensembles.GUE])
+def test_dense_gaussian_ensemble_eigenvectors_are_normalized(cls):
+    ens = cls(n=30, seed=0)
+    spectrum = ens.sample(n_samples=2, return_eigenvectors=True)
+    assert spectrum.eigenvectors is not None
+    assert spectrum.eigenvectors.shape == (2, 30, 30)
+    norms = np.sum(np.abs(spectrum.eigenvectors) ** 2, axis=1)
+    np.testing.assert_allclose(norms, 1.0, atol=1e-8)
+
+
+@pytest.mark.parametrize("cls,beta", [(rmt.ensembles.GOE, 1), (rmt.ensembles.GUE, 2)])
+def test_dense_gaussian_ensemble_ipr_matches_haar_theory(cls, beta):
+    n = 250
+    ens = cls(n=n, seed=1)
+    spectrum = ens.sample(n_samples=30, return_eigenvectors=True)
+    ipr = rmt.stats.inverse_participation_ratio(spectrum.eigenvectors)
+    theory = rmt.stats.ipr_theory(n, beta)
+    assert ipr.mean() == pytest.approx(theory, rel=0.15)
+
+
+def test_ipr_theory_matches_direct_haar_vector_simulation():
+    # Independent check of the closed-form formula itself, bypassing any
+    # ensemble machinery: a Haar-random (Gaussian, then normalized) real
+    # vector's mean IPR should match ipr_theory(n, beta=1) directly.
+    rng = np.random.default_rng(7)
+    n = 100
+    x = rng.standard_normal((20_000, n))
+    x /= np.linalg.norm(x, axis=1, keepdims=True)
+    empirical = np.mean(np.sum(x**4, axis=1))
+    assert empirical == pytest.approx(rmt.stats.ipr_theory(n, beta=1), rel=0.05)
+
+
+def test_participation_ratio_is_reciprocal_of_ipr():
+    rng = np.random.default_rng(3)
+    vecs = rng.standard_normal((5, 10, 4))
+    ipr = rmt.stats.inverse_participation_ratio(vecs)
+    pr = rmt.stats.participation_ratio(vecs)
+    np.testing.assert_allclose(pr, 1.0 / ipr)
+
+
+def test_pbrm_localization_transition_via_ipr():
+    # The defining physics of PowerLawBandedEnsemble (see its module
+    # docstring): small b (narrow band) -> localized eigenvectors (IPR
+    # much larger than the delocalized/GOE-like baseline); large b
+    # (effectively unbanded) -> delocalized eigenvectors, IPR approaching
+    # the Haar-vector theory value.
+    n = 300
+    localized = rmt.ensembles.PowerLawBandedEnsemble(n=n, b=0.5, alpha=2.0, seed=10)
+    delocalized = rmt.ensembles.PowerLawBandedEnsemble(n=n, b=50.0, alpha=2.0, seed=11)
+
+    # cache_utils.cached_sample never requests eigenvectors, so sample directly.
+    spec_localized = localized.sample(n_samples=10, return_eigenvectors=True)
+    spec_delocalized = delocalized.sample(n_samples=10, return_eigenvectors=True)
+
+    ipr_localized = rmt.stats.inverse_participation_ratio(spec_localized.eigenvectors).mean()
+    ipr_delocalized = rmt.stats.inverse_participation_ratio(spec_delocalized.eigenvectors).mean()
+    theory_delocalized = rmt.stats.ipr_theory(n, beta=1)
+
+    assert ipr_localized > 10 * ipr_delocalized
+    assert ipr_delocalized == pytest.approx(theory_delocalized, rel=0.3)
+
+
+def test_eigenvectors_absent_by_default():
+    ens = rmt.ensembles.GOE(n=20, seed=0)
+    spectrum = ens.sample(n_samples=2)
+    assert spectrum.eigenvectors is None
+
+
+# --- multifractal dimension spectrum ---
+
+
+def test_generalized_ipr_matches_plain_ipr_at_q_2():
+    rng = np.random.default_rng(4)
+    vecs = rng.standard_normal((5, 10, 4))
+    np.testing.assert_allclose(rmt.stats.generalized_ipr(vecs, q=2.0), rmt.stats.inverse_participation_ratio(vecs))
+
+
+def test_generalized_ipr_rejects_q_equals_1():
+    rng = np.random.default_rng(4)
+    vecs = rng.standard_normal((5, 4))
+    with pytest.raises(ValueError):
+        rmt.stats.generalized_ipr(vecs, q=1.0)
+
+
+def test_multifractal_dimension_is_one_for_delocalized_pbrm():
+    # Large, fixed band-width b -> effectively GOE-like/delocalized, so
+    # D_2 should be close to 1 (E[I_2] ~ 1/n exactly).
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1000.0, alpha=2.0, seed=seed)
+
+    d_2, r_squared = rmt.stats.multifractal_dimension(factory, n_values=[100, 200, 400, 800], q=2.0, n_samples=10, seed=0)
+    assert d_2 == pytest.approx(1.0, abs=0.1)
+    assert r_squared > 0.99
+
+
+def test_multifractal_dimension_is_zero_for_localized_pbrm():
+    # Small, fixed band-width b -> strongly localized, so E[I_2] stays
+    # roughly n-independent, giving D_2 close to 0.
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=0.3, alpha=2.0, seed=seed)
+
+    d_2, _ = rmt.stats.multifractal_dimension(factory, n_values=[100, 200, 400, 800], q=2.0, n_samples=10, seed=1)
+    assert d_2 == pytest.approx(0.0, abs=0.2)
+
+
+# --- f(alpha) singularity spectrum ---
+
+
+def test_mass_exponent_is_exactly_zero_at_q_1():
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1.0, alpha=1.0, seed=seed)
+
+    tau_1, r_squared = rmt.stats.mass_exponent(factory, n_values=[100, 200, 400], q=1.0, n_samples=5, seed=0)
+    assert tau_1 == 0.0
+    assert r_squared == 1.0
+
+
+def test_multifractal_dimension_rejects_q_1():
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1.0, alpha=1.0, seed=seed)
+
+    with pytest.raises(ValueError):
+        rmt.stats.multifractal_dimension(factory, n_values=[100, 200], q=1.0, n_samples=5, seed=0)
+
+
+@pytest.mark.slow
+def test_mass_exponent_matches_multifractal_dimension_relation():
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1000.0, alpha=2.0, seed=seed)
+
+    n_values = [50, 100, 200, 400]
+    tau_2, _ = rmt.stats.mass_exponent(factory, n_values, q=2.0, n_samples=10, seed=0)
+    d_2, _ = rmt.stats.multifractal_dimension(factory, n_values, q=2.0, n_samples=10, seed=0)
+    assert tau_2 / (2.0 - 1.0) == pytest.approx(d_2)
+
+
+@pytest.mark.slow
+def test_singularity_spectrum_is_a_single_point_for_delocalized_system():
+    # Fully delocalized (D_q=1 for all q) means tau(q)=q-1 exactly, so
+    # alpha(q)=1 and f(alpha)=1 for every q -- the degenerate
+    # "monofractal" limit of the singularity spectrum.
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1000.0, alpha=2.0, seed=seed)
+
+    alpha, f_alpha = rmt.stats.singularity_spectrum(
+        factory,
+        n_values=[100, 200, 400, 800],
+        q_values=np.array([0.5, 1.0, 1.5, 2.0]),
+        n_samples=10,
+        seed=0,
+    )
+    np.testing.assert_allclose(alpha, 1.0, atol=0.15)
+    np.testing.assert_allclose(f_alpha, 1.0, atol=0.15)
+
+
+@pytest.mark.slow
+def test_singularity_spectrum_is_positive_and_concave_at_small_q_for_critical_pbrm():
+    # At PBRM's multifractal critical point, the moderate-|q| portion of
+    # f(alpha) should be positive (a genuine fractal dimension) and
+    # concave (f(alpha) decreasing in |q-1|) -- see module/function
+    # docstring for why larger |q| is not asserted here (harder
+    # convergence, possible legitimate negative-dimension branch).
+    def factory(n, seed):
+        return rmt.ensembles.PowerLawBandedEnsemble(n=n, b=1.0, alpha=1.0, seed=seed)
+
+    q_values = np.array([0.5, 1.0, 1.5])
+    _, f_alpha = rmt.stats.singularity_spectrum(factory, n_values=[75, 150, 300, 600], q_values=q_values, n_samples=12, seed=2)
+    assert np.all(f_alpha > 0.0)
+    # Standard multifractal shape: f(alpha(q)) decreases monotonically as
+    # q increases (alpha(q) itself decreases with q, with the global max
+    # of f at q=0 -- not asserted here since q=0 needs even larger n for
+    # reliable convergence); over this q range it should be decreasing.
+    assert f_alpha[0] > f_alpha[1] > f_alpha[2]

physicskit/rmt/tests/test_poisson.py

@@ -0,0 +1,149 @@
+"""Tests for the Poisson ensemble -- the integrable-system (Berry-Tabor)
+null model that RMT level-repulsion statistics are always contrasted
+against.
+
+Unlike GOE/GUE/GSE, whose spacing and ratio distributions are only
+approximated by a surmise (exact for a reduced few-level model), the
+Poisson process's spacing and ratio laws are exactly known in closed
+form -- so tests here check against exact theory throughout, not a
+surmise. The ratio-statistic law (2/(1+r)**2 for the min/max-normalized
+r used by ``physicskit.rmt.stats.ratios.ratio_statistics``) is derived directly
+in the module docstring from the ratio of two i.i.d. Exponential(1)
+variables; ``test_ratio_statistic_matches_derived_exact_formula`` checks
+that derivation numerically before it is used anywhere else.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy.stats import expon, kstest
+
+import physicskit.rmt as rmt
+
+
+def test_beta_is_none():
+    ens = rmt.ensembles.PoissonEnsemble(n=30, seed=0)
+    assert ens.beta is None
+
+
+def test_shape_and_reproducibility():
+    ens_a = rmt.ensembles.PoissonEnsemble(n=50, seed=42)
+    ens_b = rmt.ensembles.PoissonEnsemble(n=50, seed=42)
+    spec_a = ens_a.sample(n_samples=5)
+    spec_b = ens_b.sample(n_samples=5)
+    assert spec_a.eigenvalues.shape == (5, 50)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+def test_levels_are_strictly_increasing():
+    # Partial sums of strictly positive Exponential draws.
+    ens = rmt.ensembles.PoissonEnsemble(n=100, seed=1)
+    spectrum = cached_sample(ens, n_samples=5)
+    for row in spectrum.eigenvalues:
+        assert np.all(np.diff(row) > 0)
+
+
+def test_mean_spacing_is_one():
+    ens = rmt.ensembles.PoissonEnsemble(n=2000, seed=2)
+    spectrum = cached_sample(ens, n_samples=10)
+    spacings = np.concatenate([np.diff(row) for row in spectrum.eigenvalues])
+    assert spacings.mean() == pytest.approx(1.0, abs=0.03)
+
+
+def test_spacing_distribution_matches_exact_exponential_law():
+    # No unfolding needed (see module docstring) -- raw spacings are
+    # already Exponential(1) by construction, checked directly against
+    # theory rather than a surmise.
+    ens = rmt.ensembles.PoissonEnsemble(n=2000, seed=3)
+    spectrum = cached_sample(ens, n_samples=20)
+    spacings = np.concatenate([np.diff(row) for row in spectrum.eigenvalues])
+    ks = kstest(spacings, expon(scale=1.0).cdf)
+    assert ks.statistic < 0.01
+
+
+def test_ratio_statistic_matches_derived_exact_formula():
+    # Verify 2/(1+r)**2 (module docstring derivation) directly against
+    # Monte Carlo ratios of independent Exponential(1) pairs, before
+    # trusting it against the ensemble itself.
+    rng = np.random.default_rng(4)
+    x = rng.exponential(1.0, size=2_000_000)
+    y = rng.exponential(1.0, size=2_000_000)
+    r = np.minimum(x, y) / np.maximum(x, y)
+
+    def poisson_ratio_cdf(r):
+        return 2.0 * r / (1.0 + r)
+
+    ks = kstest(r, poisson_ratio_cdf)
+    assert ks.statistic < 0.002
+
+
+def test_ensemble_ratio_statistic_matches_exact_poisson_law():
+    ens = rmt.ensembles.PoissonEnsemble(n=2000, seed=5)
+    spectrum = cached_sample(ens, n_samples=20)
+    ratios = rmt.stats.ratio_statistics(spectrum)
+
+    def poisson_ratio_cdf(r):
+        return 2.0 * r / (1.0 + r)
+
+    ks = kstest(ratios, poisson_ratio_cdf)
+    assert ks.statistic < 0.01
+
+
+def test_number_variance_grows_linearly_like_poisson_theory():
+    # No unfolding needed -- raw levels already have unit mean density,
+    # so window-counting is done directly rather than via
+    # ``number_variance_empirical`` (which expects a fixed-shape
+    # theoretical CDF to unfold against, the wrong abstraction for an
+    # unbounded, already-uniform-density process -- see module
+    # docstring).
+    ens = rmt.ensembles.PoissonEnsemble(n=4000, seed=6)
+    spectrum = cached_sample(ens, n_samples=15)
+    l_values = [2, 5, 10, 20]
+    rng = np.random.default_rng(7)
+
+    empirical = []
+    for length in l_values:
+        counts = []
+        for row in spectrum.eigenvalues:
+            lo, hi = row[0], row[-1]
+            starts = rng.uniform(lo, hi - length, size=200)
+            counts.extend(np.sum((row >= s) & (row < s + length)) for s in starts)
+        empirical.append(np.var(counts))
+    empirical = np.array(empirical)
+
+    theory = rmt.stats.number_variance_poisson(l_values)
+    np.testing.assert_allclose(empirical, theory, atol=0.6)
+
+
+def test_poisson_number_variance_is_much_larger_than_sampled_gue():
+    # The defining qualitative contrast this whole ensemble exists to
+    # provide: GUE's number variance grows logarithmically (level
+    # repulsion/rigidity), Poisson's grows linearly -- checked here
+    # against an actually-sampled GUE spectrum, not just GUE's theory
+    # curve (already covered by test_rigidity_universality.py).
+    l_values = [10, 20]
+    poisson_theory = rmt.stats.number_variance_poisson(l_values)
+
+    gue_ens = rmt.ensembles.GUE(n=4000, seed=8)
+    gue_spectrum = cached_sample(gue_ens, n_samples=15)
+    gue_empirical = rmt.stats.number_variance_empirical(
+        gue_spectrum,
+        rmt.stats.semicircle_cdf,
+        l_values,
+        n_windows=200,
+        seed=9,
+    )
+    assert np.all(gue_empirical < poisson_theory / 3)
+
+
+def test_generalized_wigner_surmise_at_beta_zero_is_not_poisson():
+    # Documents the important distinction from the module docstring: the
+    # Gaussian-tailed generalized Wigner surmise does NOT reduce to the
+    # exponential Poisson spacing law at beta=0 -- it gives a
+    # half-Gaussian instead. Concretely, both densities are normalized
+    # (integrate to 1) but disagree sharply at s=0: Poisson's exact
+    # density there is exp(0)=1, the beta=0 surmise's is 2/pi.
+    poisson_density_at_zero = 1.0
+    surmise_density_at_zero = rmt.stats.wigner_surmise_pdf(0.0, beta=0)
+    assert surmise_density_at_zero == pytest.approx(2.0 / np.pi)
+    assert abs(surmise_density_at_zero - poisson_density_at_zero) > 0.3

physicskit/rmt/tests/test_polynomial.py

@@ -0,0 +1,107 @@
+"""Tests for the polynomial/biorthogonal ensemble (products of Ginibre
+matrices).
+
+L=1 is checked directly against the already-validated
+``MarchenkoPastur`` benchmark (reused, not reimplemented -- it's the
+exact same theoretical object). L >= 2 has no simple closed-form
+density implemented here, so it is validated against the one thing that
+*is* known in exact closed form for general L: the Fuss-Catalan moments
+(Penson-Zyczkowski 2011), themselves checked against Monte Carlo before
+being trusted (see ``test_fuss_catalan_moment_matches_monte_carlo``).
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+from physicskit.rmt.ensembles.polynomial import fuss_catalan_moment
+
+
+def test_default_num_factors_is_two():
+    ens = rmt.ensembles.PolynomialEnsemble(n=30, seed=0)
+    assert ens.num_factors == 2
+
+
+def test_beta_1_real_factors_produce_finite_eigenvalues():
+    ens = rmt.ensembles.PolynomialEnsemble(n=8, num_factors=2, beta=1, seed=7)
+    spectrum = ens.sample(n_samples=2)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+def test_eigenvalues_are_nonnegative():
+    ens = rmt.ensembles.PolynomialEnsemble(n=50, num_factors=3, seed=1)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.all(spectrum.eigenvalues >= -1e-8)
+
+
+def test_reproducibility():
+    ens_a = rmt.ensembles.PolynomialEnsemble(n=40, num_factors=2, seed=42)
+    ens_b = rmt.ensembles.PolynomialEnsemble(n=40, num_factors=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_invalid_parameters_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.PolynomialEnsemble(n=10, num_factors=0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.PolynomialEnsemble(n=10, beta=4, seed=0)
+
+
+@pytest.mark.parametrize("beta", [1, 2])
+def test_num_factors_one_matches_marchenko_pastur_exactly(beta):
+    # L=1 is, EXACTLY (not approximately), the classical Wishart/LUE-LOE
+    # ensemble -- reusing the already-validated MarchenkoPastur
+    # benchmark directly, rather than a separate implementation, is
+    # itself part of the point (see module docstring).
+    n = 2000
+    ens = rmt.ensembles.PolynomialEnsemble(n=n, num_factors=1, beta=beta, seed=2)
+    spectrum = cached_sample(ens, n_samples=15)
+    benchmark = rmt.validation.MarchenkoPastur(gamma=1.0)
+    result = benchmark.validate(spectrum, seed=2)
+    assert result.ks_statistic < 0.02
+
+
+def test_fuss_catalan_moment_matches_monte_carlo():
+    # Verify the exact moment formula itself (not assumed from the
+    # literature citation) via a large, independent Monte Carlo
+    # generalized-Ginibre-product simulation, for L=1..4.
+    rng = np.random.default_rng(3)
+    for num_factors in [1, 2, 3, 4]:
+        n = 400
+        x = np.eye(n, dtype=complex)
+        for _ in range(num_factors):
+            factor = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+            x = x @ factor
+        eigs = np.linalg.eigvalsh(x.conj().T @ x) / n**num_factors
+        for k in [1, 2]:
+            empirical = np.mean(eigs**k)
+            theory = fuss_catalan_moment(k, num_factors)
+            assert empirical == pytest.approx(theory, rel=0.1)
+
+
+@pytest.mark.parametrize("num_factors", [1, 2, 3, 4])
+def test_ensemble_moments_match_fuss_catalan(num_factors):
+    n = 300
+    ens = rmt.ensembles.PolynomialEnsemble(n=n, num_factors=num_factors, beta=2, seed=4)
+    spectrum = cached_sample(ens, n_samples=10)
+    eigs = spectrum.rescaled.ravel()
+    for k in [1, 2]:
+        empirical = np.mean(eigs**k)
+        theory = fuss_catalan_moment(k, num_factors)
+        assert empirical == pytest.approx(theory, rel=0.1)
+
+
+@pytest.mark.parametrize("num_factors", [1, 2, 3])
+def test_spectrum_stays_near_fuss_catalan_support_edge(num_factors):
+    # Largest rescaled eigenvalue should approach, but not meaningfully
+    # exceed, the exact Fuss-Catalan support edge (L+1)**(L+1) / L**L.
+    n = 400
+    ens = rmt.ensembles.PolynomialEnsemble(n=n, num_factors=num_factors, beta=2, seed=5)
+    spectrum = cached_sample(ens, n_samples=5)
+    edge = (num_factors + 1) ** (num_factors + 1) / num_factors**num_factors
+    max_eig = spectrum.rescaled.max()
+    assert max_eig < edge * 1.1
+    assert max_eig > edge * 0.7