physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/tests/test_gaussian_semicircle.py

@@ -0,0 +1,127 @@
+"""Tests for the Gaussian ensembles (GOE/GUE/GSE) and the Wigner semicircle
+benchmark.
+
+Per the design plan (see ``physicskit.rmt.validation.base``), we do NOT gate on a
+single p > 0.05 KS test at one fixed N -- KS power grows with N, so that
+criterion becomes *less* likely to pass as N grows, which is backwards for
+demonstrating asymptotic convergence. Instead we assert that the distance
+to the theoretical semicircle law shrinks as N increases.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy.stats import linregress
+
+import physicskit.rmt as rmt
+
+CLASSICAL_ENSEMBLES = [
+    ("GOE", rmt.ensembles.GOE, 1.0),
+    ("GUE", rmt.ensembles.GUE, 2.0),
+    ("GSE", rmt.ensembles.GSE, 4.0),
+]
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_ENSEMBLES)
+def test_beta_is_correct(name, cls, expected_beta):
+    ens = cls(n=50, seed=0)
+    assert ens.beta == expected_beta
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_ENSEMBLES)
+def test_sample_shape_and_reproducibility(name, cls, expected_beta):
+    ens_a = cls(n=200, seed=123)
+    ens_b = cls(n=200, 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)
+    # same seed -> identical draws
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_ENSEMBLES)
+def test_eigenvalues_are_sorted_and_real(name, cls, expected_beta):
+    ens = cls(n=100, seed=1)
+    spectrum = cached_sample(ens, n_samples=3)
+    for row in spectrum.eigenvalues:
+        assert np.all(np.isfinite(row))
+        assert np.all(np.diff(row) >= 0)  # eigh_tridiagonal returns ascending order
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_ENSEMBLES)
+def test_rescaled_support_approaches_semicircle_radius(name, cls, expected_beta):
+    # At large n, essentially all rescaled eigenvalues should fall within
+    # [-2, 2] (+ small finite-size overshoot), and the extremes should be
+    # close to +/-2 (Tracy-Widom edge fluctuations are O(n^{-2/3}), much
+    # smaller than the bulk scale checked here).
+    ens = cls(n=3000, seed=2)
+    spectrum = cached_sample(ens, n_samples=1)
+    rescaled = spectrum.rescaled.ravel()
+    assert rescaled.max() < 2.5
+    assert rescaled.min() > -2.5
+    assert rescaled.max() > 1.8
+    assert rescaled.min() < -1.8
+
+
+@pytest.mark.parametrize("name,cls,expected_beta", CLASSICAL_ENSEMBLES)
+def test_semicircle_convergence_rate_decreases_with_n(name, cls, expected_beta):
+    # NOTE on methodology: eigenvalues within a single sampled matrix are
+    # NOT independent (level repulsion correlates them), so the
+    # distance-to-theory at any *single* N is a noisy statistic -- a
+    # strict pairwise decrease across only 2-3 N values is not a
+    # statistically robust thing to assert (it can fail by chance even
+    # when the ensemble is implemented correctly). Instead, fit the
+    # log-log trend across five N values and require a clearly negative
+    # slope; this is the same "convergence curve, not a single p > 0.05
+    # gate" philosophy from the design plan, made robust to per-point noise.
+    #
+    # Looped manually here (rather than via benchmark.convergence_curve)
+    # so each N's sample can be disk-cached individually.
+    benchmark = rmt.validation.WignerSemicircle()
+    n_values = [100, 300, 900, 2700, 8100]
+    results = []
+    for n in n_values:
+        ens = cls(n=n, seed=42)
+        spectrum = cached_sample(ens, n_samples=30)
+        results.append(benchmark.validate(spectrum, seed=42))
+
+    ks_stats = np.array([r.ks_statistic for r in results])
+    wasserstein = np.array([r.wasserstein_distance for r in results])
+
+    ks_slope = linregress(np.log(n_values), np.log(ks_stats)).slope
+    # KS convergence is the clean, low-noise signal here: theory predicts
+    # roughly -1/2 to -1; require a clearly negative trend well short of
+    # that range to keep the test robust to run-to-run noise.
+    assert ks_slope < -0.3, f"{name}: expected shrinking KS distance, slope={ks_slope}"
+
+    # Wasserstein distance (vs a large fixed reference sample) is a noisier
+    # signal at this sample budget -- use it as a coarser sanity check
+    # (final smaller than initial) rather than a strict per-step trend.
+    assert wasserstein[-1] < wasserstein[0]
+
+    # By the largest N tested, agreement should already be tight in
+    # absolute terms. The Wasserstein floor here is set by residual
+    # Monte Carlo noise (correlated eigenvalues within a sample reduce
+    # the effective sample size below n * n_samples), not by any
+    # remaining bias -- verified empirically to sit around 0.002-0.003
+    # at n=8100 with n_samples=30 for GOE/GUE/GSE.
+    assert ks_stats[-1] < 0.001
+    assert wasserstein[-1] < 0.005
+
+
+def test_continuum_beta_also_matches_semicircle():
+    # beta need not be 1, 2, or 4 -- the semicircle law (and this
+    # construction) holds for any beta > 0.
+    ens = rmt.ensembles.HermiteBetaEnsemble(n=2000, beta=1.7, seed=3)
+    spectrum = cached_sample(ens, n_samples=25)
+    benchmark = rmt.validation.WignerSemicircle()
+    result = benchmark.validate(spectrum, seed=3)
+    assert result.ks_statistic < 0.01
+
+
+def test_invalid_beta_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.HermiteBetaEnsemble(n=100, beta=0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.HermiteBetaEnsemble(n=100, beta=-1, seed=0)

physicskit/rmt/tests/test_ginibre_circular_law.py

@@ -0,0 +1,131 @@
+"""Tests for GinOE, GinUE, GinSE and the circular law benchmark.
+
+Circular law convergence is known to be slower than the Hermitian
+ensembles' semicircle/Marchenko-Pastur convergence (non-Hermitian
+matrices have weaker eigenvalue rigidity) -- confirmed during
+development (log-log KS slope ~ -0.37 vs ~ -0.85 to -0.97 for the
+semicircle law at comparable N). Thresholds here are calibrated to that
+genuinely slower rate, not loosened arbitrarily.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy.stats import linregress
+
+import physicskit.rmt as rmt
+
+GINIBRE = [
+    ("GinOE", rmt.ensembles.GinOE, 1),
+    ("GinUE", rmt.ensembles.GinUE, 2),
+    ("GinSE", rmt.ensembles.GinSE, 4),
+]
+
+
+@pytest.mark.parametrize("name,cls,beta", GINIBRE)
+def test_beta_is_correct(name, cls, beta):
+    ens = cls(n=30, seed=0)
+    assert ens.beta == beta
+
+
+@pytest.mark.parametrize("name,cls,beta", GINIBRE)
+def test_eigenvalues_are_complex(name, cls, beta):
+    ens = cls(n=50, seed=1)
+    spectrum = cached_sample(ens, n_samples=3)
+    assert np.iscomplexobj(spectrum.eigenvalues)
+
+
+def test_ginse_produces_2n_eigenvalues():
+    # Quaternion Ginibre: n x n quaternion matrix -> 2n complex
+    # eigenvalues per sample (genuinely distinct conjugate pairs, NOT
+    # deduplicated -- see ensembles/ginibre.py docstring for why this
+    # differs from GSE/CSE's true degeneracy).
+    ens = rmt.ensembles.GinSE(n=40, seed=2)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert spectrum.eigenvalues.shape == (5, 80)
+
+
+def test_ginse_eigenvalues_form_conjugate_pairs_but_are_distinct():
+    ens = rmt.ensembles.GinSE(n=30, seed=3)
+    spectrum = cached_sample(ens, n_samples=1)
+    eigs = spectrum.eigenvalues[0]
+    # sort by real then imaginary part; conjugate pairs should be
+    # adjacent, with matching real parts and opposite imaginary parts
+    order = np.lexsort((eigs.imag, eigs.real))
+    sorted_eigs = eigs[order]
+    # Rough structural check: for each non-real eigenvalue, its conjugate
+    # should also be present in the spectrum.
+    non_real = sorted_eigs[np.abs(sorted_eigs.imag) > 1e-6]
+    conjugates_present = 0
+    for z in non_real:
+        if np.any(np.abs(sorted_eigs - np.conj(z)) < 1e-8):
+            conjugates_present += 1
+    assert conjugates_present == len(non_real)
+    # And distinct: no exact duplicate values (unlike GSE/CSE degeneracy)
+    assert len(np.unique(np.round(eigs, 10))) == len(eigs)
+
+
+@pytest.mark.parametrize("name,cls,beta", GINIBRE)
+def test_reproducibility(name, cls, beta):
+    ens_a = cls(n=60, seed=42)
+    ens_b = cls(n=60, 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", GINIBRE)
+def test_radii_approach_unit_disk_at_large_n(name, cls, beta):
+    # NOTE: GinSE embeds an n x n quaternion matrix as a 2n x 2n complex
+    # matrix, so its dense eigensolve cost is ~8x that of GinOE/GinUE at
+    # the same n -- keep n modest here rather than reusing a size tuned
+    # for the real/complex cases.
+    n = 400
+    ens = cls(n=n, seed=4)
+    spectrum = cached_sample(ens, n_samples=1)
+    radii = np.abs(spectrum.rescaled.ravel())
+    assert radii.max() < 1.35
+    assert radii.mean() == pytest.approx(2.0 / 3.0, abs=0.06)  # E[r] for uniform disk = 2/3
+
+
+@pytest.mark.parametrize("name,cls,beta", GINIBRE)
+def test_circular_law_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 -- this is the
+    # single slowest test in the suite (GinSE's dense 2n x 2n eigensolve
+    # dominates), so caching it matters most here.
+    benchmark = rmt.validation.CircularLaw()
+    n_values = [40, 90, 200, 400]
+    results = []
+    for n in n_values:
+        ens = cls(n=n, seed=17)
+        spectrum = cached_sample(ens, n_samples=12)
+        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
+    # Genuinely shallower than the Hermitian ensembles' convergence
+    # (see module docstring) -- require a real negative trend, not the
+    # steeper threshold used for the semicircle/MP tests.
+    assert slope < -0.1, f"{name}: expected shrinking KS distance, slope={slope}"
+    assert ks_stats[-1] < 0.04
+
+
+def test_real_ginibre_has_real_eigenvalues_edelman_kostlan_shub():
+    # Edelman, Kostlan, Shub (1994): E[# real eigenvalues] ~ sqrt(2n/pi).
+    # Checked as an order-of-magnitude sanity check, not a tight
+    # quantitative match (this is an expectation over the ensemble, and
+    # we only average over a modest number of samples here).
+    n = 500
+    ens = rmt.ensembles.GinOE(n=n, seed=5)
+    spectrum = cached_sample(ens, n_samples=15)
+    real_counts = np.sum(np.abs(spectrum.eigenvalues.imag) < 1e-8, axis=1)
+    expected = np.sqrt(2 * n / np.pi)
+    assert real_counts.mean() == pytest.approx(expected, rel=0.5)
+
+
+def test_complex_ginibre_has_no_real_eigenvalues_generically():
+    ens = rmt.ensembles.GinUE(n=200, seed=6)
+    spectrum = cached_sample(ens, n_samples=5)
+    real_fraction = np.mean(np.abs(spectrum.eigenvalues.imag) < 1e-8)
+    assert real_fraction < 0.02  # essentially none, unlike GinOE

physicskit/rmt/tests/test_girko.py

@@ -0,0 +1,178 @@
+"""Tests for the Girko ensembles (IIDEnsemble, GirkoElliptic) --
+universality generalizations of the Ginibre ensembles: the circular and
+elliptic laws hold for any i.i.d. entry distribution with the right
+first two moments, not just Gaussian.
+
+IIDEnsemble is validated against the SAME ``CircularLaw`` benchmark
+already used for Ginibre in ``tests/test_ginibre_circular_law.py`` --
+that reuse is itself the point: Girko's theorem says non-Gaussian iid
+matrices obey the identical limiting law, so no new theoretical machinery
+is needed. GirkoElliptic has no existing benchmark (the general 2-D
+elliptic density isn't wired into the KS/Wasserstein ``Benchmark`` base
+class), so it is checked via its known exact structural limits
+(rho=+-1) and the known ellipse semi-axes (1+rho, 1-rho) at general rho.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy.stats import linregress
+
+import physicskit.rmt as rmt
+
+
+def test_iid_ensemble_beta_is_none():
+    ens = rmt.ensembles.IIDEnsemble(n=30, entry_sampler=rmt.ensembles.rademacher, seed=0)
+    assert ens.beta is None
+
+
+def test_iid_ensemble_real_entries_branch_produces_finite_eigenvalues():
+    # A fresh (uncached) direct .sample() call, to actually exercise the
+    # complex_entries=False code path rather than risk a disk-cache hit
+    # from a previous run with these same parameters.
+    ens = rmt.ensembles.IIDEnsemble(n=8, entry_sampler=rmt.ensembles.rademacher, complex_entries=False, seed=99)
+    spectrum = ens.sample(n_samples=2)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+@pytest.mark.parametrize(
+    "name,entry_sampler,complex_entries",
+    [
+        ("uniform-complex", rmt.ensembles.uniform_unit_variance, True),
+        ("rademacher-complex", rmt.ensembles.rademacher, True),
+        ("exponential-real", rmt.ensembles.exponential_centered_unit_variance, False),
+    ],
+)
+def test_iid_ensemble_eigenvalues_are_complex(name, entry_sampler, complex_entries):
+    ens = rmt.ensembles.IIDEnsemble(
+        n=50,
+        entry_sampler=entry_sampler,
+        complex_entries=complex_entries,
+        seed=1,
+    )
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.iscomplexobj(spectrum.eigenvalues)
+    assert spectrum.eigenvalues.shape == (5, 50)
+
+
+def test_iid_ensemble_reproducibility():
+    ens_a = rmt.ensembles.IIDEnsemble(n=40, entry_sampler=rmt.ensembles.rademacher, seed=42)
+    ens_b = rmt.ensembles.IIDEnsemble(n=40, entry_sampler=rmt.ensembles.rademacher, 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,entry_sampler,complex_entries,seed",
+    [
+        ("uniform", rmt.ensembles.uniform_unit_variance, True, 10),
+        ("rademacher", rmt.ensembles.rademacher, True, 11),
+        ("exponential", rmt.ensembles.exponential_centered_unit_variance, True, 12),
+    ],
+)
+def test_circular_law_convergence_shrinks_with_n_non_gaussian(name, entry_sampler, complex_entries, seed):
+    # Same benchmark, same convergence-rate philosophy, and (per the
+    # module docstring) the same expected shallower log-log slope as
+    # Ginibre's own non-Hermitian convergence -- as this is meant to be
+    # the identical limiting law reached from a non-Gaussian starting
+    # point, not a distinct, looser standard.
+    benchmark = rmt.validation.CircularLaw()
+    n_values = [40, 90, 200, 400]
+    results = []
+    for n in n_values:
+        ens = rmt.ensembles.IIDEnsemble(
+            n=n,
+            entry_sampler=entry_sampler,
+            complex_entries=complex_entries,
+            seed=seed,
+        )
+        spectrum = cached_sample(ens, n_samples=12)
+        results.append(benchmark.validate(spectrum, seed=seed))
+
+    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.1, f"{name}: expected shrinking KS distance, slope={slope}"
+    assert ks_stats[-1] < 0.04
+
+
+def test_girko_elliptic_rho_out_of_range_raises():
+    with pytest.raises(ValueError):
+        rmt.ensembles.GirkoElliptic(n=10, rho=1.5, seed=0)
+
+
+def test_girko_elliptic_beta_is_none():
+    ens = rmt.ensembles.GirkoElliptic(n=20, rho=0.5, seed=0)
+    assert ens.beta is None
+
+
+def test_girko_elliptic_reproducibility():
+    ens_a = rmt.ensembles.GirkoElliptic(n=40, rho=0.3, seed=42)
+    ens_b = rmt.ensembles.GirkoElliptic(n=40, rho=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)
+
+
+def test_girko_elliptic_rho_zero_matches_circular_law():
+    # rho=0 -> plain i.i.d. real entries -> same limiting law as
+    # IIDEnsemble(complex_entries=False) / GinOE (circular law).
+    benchmark = rmt.validation.CircularLaw()
+    ens = rmt.ensembles.GirkoElliptic(n=300, rho=0.0, seed=2)
+    spectrum = cached_sample(ens, n_samples=15)
+    result = benchmark.validate(spectrum, seed=2)
+    assert result.ks_statistic < 0.05
+
+
+def test_girko_elliptic_rho_plus_one_gives_exactly_real_eigenvalues():
+    # rho=1 -> X exactly symmetric -> eigenvalues exactly real (Wigner).
+    ens = rmt.ensembles.GirkoElliptic(n=60, rho=1.0, seed=3)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.abs(spectrum.eigenvalues.imag).max() < 1e-8
+
+
+def test_girko_elliptic_rho_minus_one_gives_exactly_imaginary_eigenvalues():
+    # rho=-1 -> X exactly antisymmetric -> eigenvalues exactly purely
+    # imaginary (real antisymmetric matrices have eigenvalues 0 or
+    # imaginary conjugate pairs).
+    ens = rmt.ensembles.GirkoElliptic(n=60, rho=-1.0, seed=4)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.abs(spectrum.eigenvalues.real).max() < 1e-8
+
+
+def test_correlated_pair_matrix_has_correct_variance_and_correlation():
+    # Direct, un-cached check of the raw construction's second moments
+    # (not just the downstream eigenvalue law) against the values
+    # asserted in the module docstring, pooled over many independent
+    # matrices for statistical accuracy.
+    from physicskit.rmt.ensembles.girko import _correlated_pair_matrix, standard_normal
+
+    rng = np.random.default_rng(5)
+    n = 8
+    rho = 0.6
+    upper_vals, lower_vals = [], []
+    for _ in range(4000):
+        x = _correlated_pair_matrix(n, rho, standard_normal, rng)
+        upper_vals.append(x[0, 1])
+        lower_vals.append(x[1, 0])
+    upper_vals = np.array(upper_vals)
+    lower_vals = np.array(lower_vals)
+    assert upper_vals.var() == pytest.approx(1.0, abs=0.1)
+    assert lower_vals.var() == pytest.approx(1.0, abs=0.1)
+    corr = np.corrcoef(upper_vals, lower_vals)[0, 1]
+    assert corr == pytest.approx(rho, abs=0.05)
+
+
+@pytest.mark.parametrize("rho", [-0.5, 0.0, 0.5, 0.8])
+def test_girko_elliptic_semi_axes_bound_the_spectrum_at_large_n(rho):
+    # Eigenvalues should (asymptotically) stay within the ellipse of
+    # semi-axes (1+rho, 1-rho); allow a modest finite-n margin rather
+    # than a tight asymptotic bound.
+    n = 800
+    ens = rmt.ensembles.GirkoElliptic(n=n, rho=rho, seed=6)
+    spectrum = cached_sample(ens, n_samples=3)
+    z = spectrum.rescaled.ravel()
+    a, b = 1.0 + rho, max(1.0 - rho, 1e-6)
+    elliptic_radius = np.sqrt((z.real / a) ** 2 + (z.imag / b) ** 2)
+    frac_outside = np.mean(elliptic_radius > 1.15)
+    assert frac_outside < 0.03, f"rho={rho}: {frac_outside:.3f} of mass outside the ellipse"

physicskit/rmt/tests/test_graph_laplacian.py

@@ -0,0 +1,102 @@
+"""Tests for GraphLaplacianEnsemble (Erdos-Renyi combinatorial and
+normalized Laplacians)."""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+
+def test_beta_is_none():
+    ens = rmt.ensembles.GraphLaplacianEnsemble(n=30, p=0.3, seed=0)
+    assert ens.beta is None
+
+
+def test_invalid_p_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.GraphLaplacianEnsemble(n=10, p=0.0, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.GraphLaplacianEnsemble(n=10, p=1.5, seed=0)
+
+
+def test_normalized_laplacian_fresh_sample_produces_finite_eigenvalues():
+    # A fresh (uncached) direct .sample() call, to actually exercise the
+    # normalized=True code path rather than risk a disk-cache hit from a
+    # previous run with these same parameters.
+    ens = rmt.ensembles.GraphLaplacianEnsemble(n=15, p=0.5, normalized=True, seed=123)
+    spectrum = ens.sample(n_samples=2)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+def test_reproducibility():
+    ens_a = rmt.ensembles.GraphLaplacianEnsemble(n=40, p=0.2, seed=42)
+    ens_b = rmt.ensembles.GraphLaplacianEnsemble(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_combinatorial_laplacian_is_positive_semidefinite_with_zero_mode():
+    # L = D - A is always PSD with smallest eigenvalue exactly 0 (the
+    # constant vector is always in its kernel, connected or not).
+    ens = rmt.ensembles.GraphLaplacianEnsemble(n=50, p=0.3, seed=1)
+    spectrum = cached_sample(ens, n_samples=10)
+    assert np.all(spectrum.eigenvalues >= -1e-8)
+    assert np.abs(spectrum.eigenvalues.min(axis=1)).max() < 1e-8
+
+
+def test_normalized_laplacian_eigenvalues_bounded_in_zero_two():
+    # Exact graph-independent bound (Chung 1997), checked directly.
+    ens = rmt.ensembles.GraphLaplacianEnsemble(n=60, p=0.4, normalized=True, seed=2)
+    spectrum = cached_sample(ens, n_samples=10)
+    assert np.all(spectrum.eigenvalues >= -1e-8)
+    assert np.all(spectrum.eigenvalues <= 2.0 + 1e-8)
+
+
+def test_normalized_laplacian_handles_isolated_vertices():
+    # Very small p on a modest n makes isolated vertices likely; should
+    # not raise (division-by-zero for degree-0 rows is handled by
+    # convention -- see module docstring) and eigenvalues must stay
+    # finite and within [0, 2].
+    ens = rmt.ensembles.GraphLaplacianEnsemble(n=30, p=0.02, normalized=True, seed=3)
+    spectrum = cached_sample(ens, n_samples=10)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+    assert np.all(spectrum.eigenvalues >= -1e-8)
+    assert np.all(spectrum.eigenvalues <= 2.0 + 1e-8)
+
+
+def test_combinatorial_laplacian_zero_multiplicity_matches_component_count():
+    # Well-known spectral graph theory fact: the multiplicity of the
+    # zero eigenvalue equals the number of connected components. Force
+    # a disconnected graph (very small p, small n) and check directly
+    # via a graph-free connectivity computation (BFS/union-find on the
+    # same adjacency matrix used to build L).
+    from physicskit.rmt.ensembles.graph_laplacian import _erdos_renyi_adjacency
+
+    rng = np.random.default_rng(4)
+    n, p = 25, 0.03
+    a = _erdos_renyi_adjacency(n, p, rng)
+    degree = a.sum(axis=1)
+    laplacian = np.diag(degree) - a
+    eigs = np.linalg.eigvalsh(laplacian)
+    zero_multiplicity = np.sum(np.abs(eigs) < 1e-8)
+
+    # union-find to count connected components independently
+    parent = list(range(n))
+
+    def find(x):
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if a[i, j] > 0:
+                ri, rj = find(i), find(j)
+                if ri != rj:
+                    parent[ri] = rj
+    n_components = len({find(i) for i in range(n)})
+
+    assert zero_multiplicity == n_components

physicskit/rmt/tests/test_haar.py

@@ -0,0 +1,118 @@
+"""Tests for the Haar-random matrix generators (physicskit.rmt.utils.haar) and
+the HaarOrthogonalEnsemble.
+
+``haar_unitary`` is already indirectly validated via CUE's passing
+spacing statistics (see tests/test_circular.py); ``haar_orthogonal`` and
+``haar_symplectic`` are checked directly here since they are new.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+from physicskit.rmt.utils.haar import haar_orthogonal, haar_symplectic, haar_unitary, symplectic_form
+
+
+def test_haar_orthogonal_is_orthogonal():
+    rng = np.random.default_rng(0)
+    o = haar_orthogonal(20, rng)
+    assert np.abs(o.T @ o - np.eye(20)).max() < 1e-10
+
+
+@pytest.mark.slow
+def test_haar_orthogonal_first_column_is_uniform_on_sphere():
+    # Hallmark of Haar invariance: any fixed unit vector rotated by a
+    # Haar-random O(n) is uniform on the sphere -- mean 0, second
+    # moment 1/n per component.
+    rng = np.random.default_rng(1)
+    n = 5
+    first_columns = np.array([haar_orthogonal(n, rng)[:, 0] for _ in range(20_000)])
+    np.testing.assert_allclose(first_columns.mean(axis=0), 0.0, atol=0.03)
+    np.testing.assert_allclose((first_columns**2).mean(axis=0), 1.0 / n, atol=0.03)
+
+
+def test_haar_orthogonal_determinant_is_balanced():
+    rng = np.random.default_rng(2)
+    dets = [np.linalg.det(haar_orthogonal(6, rng)) for _ in range(4000)]
+    dets = np.array(dets)
+    np.testing.assert_allclose(np.abs(dets), 1.0, atol=1e-8)
+    frac_positive = np.mean(dets > 0)
+    assert frac_positive == pytest.approx(0.5, abs=0.05)
+
+
+def test_haar_symplectic_is_unitary_and_self_dual():
+    rng = np.random.default_rng(3)
+    n_quaternionic = 6
+    u = haar_symplectic(n_quaternionic, rng)
+    n = 2 * n_quaternionic
+    assert u.shape == (n, n)
+    assert np.abs(u.conj().T @ u - np.eye(n)).max() < 1e-10
+
+    z = symplectic_form(n)
+    u_dual = (-z) @ u.T @ z
+    assert np.abs(u_dual - u).max() < 1e-10
+
+
+def test_haar_symplectic_eigenvalues_are_doubly_degenerate():
+    rng = np.random.default_rng(4)
+    u = haar_symplectic(5, rng)
+    eigs = np.linalg.eigvals(u)
+    order = np.lexsort((eigs.imag, eigs.real))
+    sorted_eigs = eigs[order]
+    pair_diffs = np.abs(sorted_eigs[0::2] - sorted_eigs[1::2])
+    assert pair_diffs.max() < 1e-8
+
+
+def test_haar_unitary_still_exactly_unitary():
+    # Regression check: existing helper unaffected by the new additions.
+    rng = np.random.default_rng(5)
+    u = haar_unitary(10, rng)
+    assert np.abs(u.conj().T @ u - np.eye(10)).max() < 1e-10
+
+
+# --- HaarOrthogonalEnsemble ---
+
+
+def test_haar_orthogonal_ensemble_beta_is_none():
+    ens = rmt.ensembles.HaarOrthogonalEnsemble(n=20, seed=0)
+    assert ens.beta is None
+
+
+def test_haar_orthogonal_ensemble_eigenvalues_on_unit_circle():
+    ens = rmt.ensembles.HaarOrthogonalEnsemble(n=30, seed=1)
+    spectrum = cached_sample(ens, n_samples=10)
+    radii = np.abs(spectrum.eigenvalues)
+    np.testing.assert_allclose(radii, 1.0, atol=1e-8)
+
+
+def test_haar_orthogonal_ensemble_reproducibility():
+    ens_a = rmt.ensembles.HaarOrthogonalEnsemble(n=20, seed=42)
+    ens_b = rmt.ensembles.HaarOrthogonalEnsemble(n=20, 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_haar_orthogonal_ensemble_has_real_eigenvalues_unlike_coe():
+    # The core structural distinction from COE (module docstring):
+    # a raw Haar-O(n) matrix genuinely has real (+-1) eigenvalues with
+    # non-negligible probability; COE/CUE generically do not.
+    ens = rmt.ensembles.HaarOrthogonalEnsemble(n=40, seed=2)
+    spectrum = cached_sample(ens, n_samples=200)
+    real_fraction_of_samples = np.mean(np.any(np.abs(spectrum.eigenvalues.imag) < 1e-8, axis=1))
+    assert real_fraction_of_samples > 0.5
+
+    # COE stores eigenvalue PHASES (theta in [0, 2*pi)), not e^{i*theta}
+    # directly -- convert back to compare on the same "is this real"
+    # footing as HaarOrthogonalEnsemble's complex output above.
+    coe = rmt.ensembles.COE(n=40, seed=3)
+    coe_spectrum = cached_sample(coe, n_samples=200)
+    coe_eigs = np.exp(1j * coe_spectrum.eigenvalues)
+    coe_real_fraction = np.mean(np.abs(coe_eigs.imag) < 1e-8)
+    assert coe_real_fraction < 0.01
+
+
+def test_symplectic_form_rejects_odd_dimension():
+    with pytest.raises(ValueError):
+        symplectic_form(3)