physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/tests/test_density_matrix.py

@@ -0,0 +1,181 @@
+"""Tests for the random density matrix ensembles (InducedMeasureEnsemble,
+HilbertSchmidtEnsemble, BuresHallEnsemble) and the Page-curve entropy
+helpers.
+
+Every formula used for validation here (mean purity for both measures,
+Page's average-entropy formula, and -- most importantly -- the
+Bures-Hall construction itself) was independently checked against exact
+theory or independent numerical integration during development, not
+assumed from a remembered citation; see the module docstrings in
+``physicskit.rmt/ensembles/density_matrix.py`` and
+``physicskit.rmt/stats/entanglement.py``.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+from scipy import integrate
+
+import physicskit.rmt as rmt
+
+
+def _mean_purity(spectrum):
+    return np.mean(np.sum(spectrum.eigenvalues**2, axis=1))
+
+
+# --- structural checks common to all three ensembles ---
+
+ALL_DM_ENSEMBLES = [
+    (
+        "InducedMeasure",
+        lambda n, seed: rmt.ensembles.InducedMeasureEnsemble(n=n, k=n + 2, seed=seed),
+    ),
+    ("HilbertSchmidt", lambda n, seed: rmt.ensembles.HilbertSchmidtEnsemble(n=n, seed=seed)),
+    ("BuresHall", lambda n, seed: rmt.ensembles.BuresHallEnsemble(n=n, seed=seed)),
+]
+
+
+@pytest.mark.parametrize("name,factory", ALL_DM_ENSEMBLES)
+def test_eigenvalues_are_valid_probability_distribution(name, factory):
+    ens = factory(8, 0)
+    spectrum = cached_sample(ens, n_samples=20)
+    assert np.all(spectrum.eigenvalues >= -1e-10)
+    assert np.all(spectrum.eigenvalues <= 1.0 + 1e-10)
+    np.testing.assert_allclose(spectrum.eigenvalues.sum(axis=1), 1.0, atol=1e-8)
+
+
+@pytest.mark.parametrize("name,factory", ALL_DM_ENSEMBLES)
+def test_reproducibility(name, factory):
+    ens_a = factory(6, 42)
+    ens_b = factory(6, 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_induced_measure_rejects_invalid_k():
+    with pytest.raises(ValueError):
+        rmt.ensembles.InducedMeasureEnsemble(n=5, k=0, seed=0)
+
+
+def test_hilbert_schmidt_beta_is_two():
+    ens = rmt.ensembles.HilbertSchmidtEnsemble(n=5, seed=0)
+    assert ens.beta == 2
+
+
+def test_bures_hall_beta_is_none():
+    # Not one of Dyson's classical beta-ensembles -- extra 1/(li+lj)
+    # factor in the joint density beyond a pure Vandermonde power.
+    ens = rmt.ensembles.BuresHallEnsemble(n=5, seed=0)
+    assert ens.beta is None
+
+
+def test_k_equals_one_gives_pure_states():
+    # k=1 forces rank-1 rho: exactly one eigenvalue = 1, rest = 0.
+    ens = rmt.ensembles.InducedMeasureEnsemble(n=6, k=1, seed=1)
+    spectrum = cached_sample(ens, n_samples=10)
+    for row in spectrum.eigenvalues:
+        assert np.sum(row > 1e-8) == 1
+        assert np.max(row) == pytest.approx(1.0, abs=1e-8)
+
+
+# --- exact mean-purity formulas (Zyczkowski-Sommers 2001) ---
+
+
+@pytest.mark.parametrize("n", [2, 3, 5, 10])
+def test_hilbert_schmidt_mean_purity_matches_exact_formula(n):
+    ens = rmt.ensembles.HilbertSchmidtEnsemble(n=n, seed=2)
+    spectrum = cached_sample(ens, n_samples=20000)
+    theory = 2.0 * n / (n**2 + 1)
+    assert _mean_purity(spectrum) == pytest.approx(theory, rel=0.03)
+
+
+@pytest.mark.parametrize("n,k", [(3, 3), (3, 6), (3, 2), (4, 10)])
+def test_induced_measure_mean_purity_matches_exact_formula(n, k):
+    ens = rmt.ensembles.InducedMeasureEnsemble(n=n, k=k, seed=3)
+    spectrum = cached_sample(ens, n_samples=20000)
+    theory = (n + k) / (n * k + 1)
+    assert _mean_purity(spectrum) == pytest.approx(theory, rel=0.03)
+
+
+# --- Bures-Hall: verified directly against its own joint eigenvalue
+# density (not merely against a remembered matrix-model recipe) ---
+
+
+@pytest.mark.slow
+def test_bures_hall_matches_exact_n2_marginal_density():
+    # For n=2, the exact Bures-Hall joint density on the simplex
+    # lambda1+lambda2=1 gives a closed-form 1-D density for the smaller
+    # eigenvalue: f(x) ~ (2x-1)^2 / sqrt(x(1-x)) on (0, 1), restricted
+    # to (0, 0.5] and doubled (by exchange symmetry) for the SMALLER
+    # eigenvalue's marginal CDF.
+    def unnorm_pdf(x):
+        return (2 * x - 1) ** 2 / np.sqrt(x * (1 - x))
+
+    z, _ = integrate.quad(unnorm_pdf, 0, 1)
+
+    def cdf_full(x):
+        val, _ = integrate.quad(unnorm_pdf, 0, x)
+        return val / z
+
+    def smaller_eig_cdf(x):
+        return np.clip(2.0 * np.vectorize(cdf_full)(np.clip(x, 0, 0.5)), 0.0, 1.0)
+
+    ens = rmt.ensembles.BuresHallEnsemble(n=2, seed=4)
+    spectrum = cached_sample(ens, n_samples=5000)
+    smaller_eigs = spectrum.eigenvalues[:, 0]  # eigvalsh ascending -> smaller first
+
+    from scipy.stats import kstest
+
+    # kstest's per-sample smaller_eig_cdf evaluation (a scipy.integrate.quad
+    # call each) dominates runtime, hence the smaller n_samples here vs. the
+    # 50000 used elsewhere in this file; the KS threshold is loosened by the
+    # matching ~sqrt(10) factor for the noisier statistic at this sample size.
+    ks = kstest(smaller_eigs, smaller_eig_cdf)
+    assert ks.statistic < 0.06
+
+
+def test_bures_hall_matches_exact_n3_mean_purity_via_joint_density_integration():
+    # For n=3, integrate the exact joint density over the 2-D simplex
+    # directly (independent of the matrix construction) to get the
+    # theoretical mean purity, and compare to Monte Carlo.
+    def unnorm_density(l1, l2):
+        l3 = 1.0 - l1 - l2
+        if l3 <= 0 or l1 <= 0 or l2 <= 0:
+            return 0.0
+        vand = (l1 - l2) ** 2 * (l1 - l3) ** 2 * (l2 - l3) ** 2
+        denom = (l1 + l2) * (l1 + l3) * (l2 + l3)
+        weight = (l1 * l2 * l3) ** (-0.5)
+        return vand / denom * weight
+
+    def integrand_z(l2, l1):
+        return unnorm_density(l1, l2)
+
+    def integrand_purity(l2, l1):
+        l3 = 1.0 - l1 - l2
+        return unnorm_density(l1, l2) * (l1**2 + l2**2 + l3**2)
+
+    z, _ = integrate.dblquad(integrand_z, 0, 1, lambda l1: 0, lambda l1: 1 - l1)
+    p, _ = integrate.dblquad(integrand_purity, 0, 1, lambda l1: 0, lambda l1: 1 - l1)
+    theory_mean_purity = p / z
+
+    ens = rmt.ensembles.BuresHallEnsemble(n=3, seed=5)
+    spectrum = cached_sample(ens, n_samples=40000)
+    assert _mean_purity(spectrum) == pytest.approx(theory_mean_purity, rel=0.02)
+
+
+# --- Page curve (bipartite / entanglement) ---
+
+
+def test_von_neumann_entropy_handles_zero_eigenvalues():
+    assert rmt.stats.von_neumann_entropy([1.0, 0.0, 0.0]) == pytest.approx(0.0)
+    assert rmt.stats.von_neumann_entropy([0.5, 0.5]) == pytest.approx(np.log(2.0))
+
+
+@pytest.mark.parametrize("n,k", [(2, 2), (2, 8), (3, 3), (3, 10)])
+def test_page_curve_matches_induced_measure_ensemble(n, k):
+    ens = rmt.ensembles.InducedMeasureEnsemble(n=n, k=k, seed=6)
+    spectrum = cached_sample(ens, n_samples=15000)
+    empirical = np.mean([rmt.stats.von_neumann_entropy(row) for row in spectrum.eigenvalues])
+    theory = rmt.stats.page_curve_average_entropy(n, k)
+    assert empirical == pytest.approx(theory, rel=0.02)

physicskit/rmt/tests/test_effective_hamiltonian.py

@@ -0,0 +1,140 @@
+"""Tests for the non-Hermitian effective Hamiltonian ensembles (EffGOE,
+EffGUE, EffGSE) -- Feshbach-projection/chaotic-scattering resonance
+ensembles built on GOE/GUE/GSE.
+
+Like BdG (see ``tests/test_bdg.py``), there is no simple closed-form
+bulk density to benchmark here, so validation is structural: causality
+(widths never negative -- a property proved directly from Hermiticity
+and positive semi-definiteness in the module docstring, not merely
+observed), the m=0 Hermitian limit, and beta=4's Kramers degeneracy.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+
+EFFECTIVE = [
+    ("EffGOE", rmt.ensembles.EffGOE, 1),
+    ("EffGUE", rmt.ensembles.EffGUE, 2),
+    ("EffGSE", rmt.ensembles.EffGSE, 4),
+]
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_beta_is_correct(name, cls, beta):
+    ens = cls(n=30, m=5, seed=0)
+    assert ens.beta == beta
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_eigenvalues_are_complex(name, cls, beta):
+    ens = cls(n=40, m=5, seed=1)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.iscomplexobj(spectrum.eigenvalues)
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_produces_n_eigenvalues(name, cls, beta):
+    # beta=4 internally builds a 2n x 2n embedding but de-duplicates the
+    # exact Kramers pairs, so all three classes return exactly n
+    # eigenvalues per sample -- see module docstring.
+    ens = cls(n=25, m=4, seed=2)
+    spectrum = cached_sample(ens, n_samples=6)
+    assert spectrum.eigenvalues.shape == (6, 25)
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_reproducibility(name, cls, beta):
+    ens_a = cls(n=30, m=5, seed=42)
+    ens_b = cls(n=30, m=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)
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_widths_are_never_positive_causality(name, cls, beta):
+    # Gamma_k = -2*Im(lambda_k) >= 0 for every eigenvalue of every
+    # realization -- proved directly (not just observed) in the module
+    # docstring from H Hermitian + Gamma Hermitian PSD.
+    ens = cls(n=35, m=6, coupling=1.3, seed=3)
+    spectrum = cached_sample(ens, n_samples=20)
+    assert np.all(spectrum.eigenvalues.imag <= 1e-9)
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_zero_channels_recovers_hermitian_limit(name, cls, beta):
+    # m=0 -> Gamma=0 -> H_eff=H exactly -> real eigenvalues to machine
+    # precision, regardless of beta.
+    ens = cls(n=30, m=0, seed=4)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.abs(spectrum.eigenvalues.imag).max() < 1e-9
+
+
+@pytest.mark.parametrize("name,cls,beta", EFFECTIVE)
+def test_more_channels_increase_total_width(name, cls, beta):
+    # More open channels -> more total decay -> larger mean |Im(lambda)|
+    # (monotonic on average, not realization-by-realization).
+    total_widths = []
+    for m in (1, 4, 10):
+        ens = cls(n=40, m=m, seed=5)
+        spectrum = cached_sample(ens, n_samples=15)
+        total_widths.append(np.mean(-spectrum.eigenvalues.imag))
+    assert total_widths[0] < total_widths[1] < total_widths[2]
+
+
+def test_effgse_eigenvalues_form_exact_kramers_pairs():
+    # Direct, un-cached check against the raw (non-deduplicated) 2n
+    # eigenvalues: EffGSE's Kramers degeneracy should be exact (machine
+    # precision), unlike GinSE's merely-conjugate (distinct) pairs.
+    from physicskit.rmt.ensembles.effective_hamiltonian import (
+        _sample_coupling,
+        _sample_hamiltonian,
+    )
+
+    rng = np.random.default_rng(6)
+    n, m = 15, 3
+    h = _sample_hamiltonian(n, rng, beta=4)
+    v = _sample_coupling(n, m, rng, beta=4)
+    gamma = v @ v.conj().T
+    h_eff = h - 0.5j * gamma
+
+    eigs = np.linalg.eigvals(h_eff)
+    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_zero_coupling_is_equivalent_to_zero_channels():
+    # coupling=0 with m>0 should give the same Hermitian-limit behavior
+    # as m=0 (Gamma=0 either way).
+    ens = rmt.ensembles.EffGUE(n=25, m=6, coupling=0.0, seed=7)
+    spectrum = cached_sample(ens, n_samples=5)
+    assert np.abs(spectrum.eigenvalues.imag).max() < 1e-9
+
+
+def test_zero_channels_fresh_sample_recovers_hermitian_limit():
+    # A fresh (uncached) direct .sample() call, so the m=0 -> Gamma=0
+    # branch is actually exercised rather than risking a disk-cache hit.
+    ens = rmt.ensembles.EffGOE(n=6, m=0, seed=555)
+    spectrum = ens.sample(n_samples=2)
+    assert np.abs(spectrum.eigenvalues.imag).max() < 1e-9
+
+
+def test_sample_hamiltonian_and_coupling_reject_invalid_beta():
+    from physicskit.rmt.ensembles.effective_hamiltonian import _sample_coupling, _sample_hamiltonian
+
+    with pytest.raises(ValueError):
+        _sample_hamiltonian(5, np.random.default_rng(0), beta=3)
+    with pytest.raises(ValueError):
+        _sample_coupling(5, 3, np.random.default_rng(0), beta=3)
+
+
+def test_effective_hamiltonian_ensemble_rejects_invalid_beta_and_negative_m():
+    with pytest.raises(ValueError):
+        rmt.ensembles.EffectiveHamiltonianEnsemble(n=5, m=1, beta=3, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.EffectiveHamiltonianEnsemble(n=5, m=-1, beta=2, seed=0)

physicskit/rmt/tests/test_embedded.py

@@ -0,0 +1,169 @@
+"""Tests for the embedded Gaussian ensembles (EmbeddedGaussianEnsemble,
+TwoBodyRandomEnsemble).
+
+Unlike every classical ensemble in this package, the many-body
+Hamiltonian here is built by embedding a k-body random interaction into
+a Fock space, via hand-rolled Jordan-Wigner fermionic operators -- a
+genuinely new piece of machinery with real correctness risk (an initial
+implementation had the raising/lowering matrices swapped, caught only
+by the k=m exact-match check below, not by the Hermiticity or particle-
+number-conservation checks, which both silently passed anyway). These
+tests reproduce that verification chain directly rather than only
+trusting the module docstring's account of it.
+"""
+
+import numpy as np
+import pytest
+from cache_utils import cached_sample
+
+import physicskit.rmt as rmt
+from physicskit.rmt.ensembles.embedded import _fermion_ladder_operators
+
+
+def test_ladder_operators_satisfy_fermionic_algebra():
+    n = 5
+    creators = _fermion_ladder_operators(n)
+    annihilators = [c.conj().T for c in creators]
+    dim = 2**n
+    identity = np.eye(dim, dtype=complex)
+    for i in range(n):
+        for j in range(n):
+            anticomm_ac = annihilators[i] @ creators[j] + creators[j] @ annihilators[i]
+            target = identity if i == j else np.zeros((dim, dim))
+            assert np.abs(anticomm_ac - target).max() < 1e-10
+
+            anticomm_aa = annihilators[i] @ annihilators[j] + annihilators[j] @ annihilators[i]
+            assert np.abs(anticomm_aa).max() < 1e-10
+
+
+@pytest.mark.parametrize("k,m,n_levels", [(2, 2, 4), (3, 3, 6)])
+def test_k_equals_m_reduces_exactly_to_the_interaction_matrix(k, m, n_levels):
+    # The construction's most important structural check: with only m=k
+    # particles present, the embedding is trivial and H, restricted to
+    # the m-particle sector, must equal the k-body interaction matrix V
+    # EXACTLY (not merely statistically) -- this is precisely the check
+    # that caught an operator-ordering sign bug during development.
+    from itertools import combinations
+
+    from physicskit.rmt.ensembles.embedded import _fermion_ladder_operators
+
+    creators = _fermion_ladder_operators(n_levels)
+    tuples = list(combinations(range(n_levels), k))
+    n_tuples = len(tuples)
+    rng = np.random.default_rng(0)
+    x = rng.standard_normal((n_tuples, n_tuples))
+    v = (x + x.T) / np.sqrt(2.0)
+
+    def multi_create(idxs):
+        op = creators[idxs[0]]
+        for idx in idxs[1:]:
+            op = op @ creators[idx]
+        return op
+
+    p_ops = [multi_create(t) for t in tuples]
+    dim = p_ops[0].shape[0]
+    h = np.zeros((dim, dim), dtype=complex)
+    for a_idx in range(n_tuples):
+        q = sum(v[a_idx, b_idx] * p_ops[b_idx].conj().T for b_idx in range(n_tuples))
+        h += p_ops[a_idx] @ q
+
+    def occ_to_index(occ, n):
+        idx = 0
+        for site in occ:
+            idx |= 1 << (n - 1 - site)
+        return idx
+
+    basis = [occ_to_index(t, n_levels) for t in tuples]
+    h_sub = h[np.ix_(basis, basis)].real
+    np.testing.assert_allclose(h_sub, v, atol=1e-10)
+
+
+@pytest.mark.parametrize("beta", [1, 2])
+def test_hermiticity_and_particle_number_conservation(beta):
+    n_levels = 6
+    rng = np.random.default_rng(1)
+    # Directly rebuild the dense (pre-restriction) Hamiltonian to check
+    # Hermiticity and particle-number conservation on the FULL Fock
+    # space, not just the already-restricted eigenvalue output.
+    from itertools import combinations
+
+    from physicskit.rmt.ensembles.embedded import _fermion_ladder_operators
+
+    creators = _fermion_ladder_operators(n_levels)
+    tuples = list(combinations(range(n_levels), 2))
+    n_tuples = len(tuples)
+    if beta == 1:
+        x = rng.standard_normal((n_tuples, n_tuples))
+        v = (x + x.T) / np.sqrt(2.0)
+    else:
+        real_part = rng.standard_normal((n_tuples, n_tuples))
+        imag_part = rng.standard_normal((n_tuples, n_tuples))
+        x = (real_part + 1j * imag_part) / np.sqrt(2.0)
+        v = (x + x.conj().T) / 2.0
+
+    def multi_create(idxs):
+        op = creators[idxs[0]]
+        for idx in idxs[1:]:
+            op = op @ creators[idx]
+        return op
+
+    p_ops = [multi_create(t) for t in tuples]
+    dim = p_ops[0].shape[0]
+    h = np.zeros((dim, dim), dtype=complex)
+    for a_idx in range(n_tuples):
+        q = sum(v[a_idx, b_idx] * p_ops[b_idx].conj().T for b_idx in range(n_tuples))
+        h += p_ops[a_idx] @ q
+
+    assert np.abs(h - h.conj().T).max() < 1e-10
+
+    annihilators = [c.conj().T for c in creators]
+    n_total = sum(creators[i] @ annihilators[i] for i in range(n_levels))
+    assert np.abs(h @ n_total - n_total @ h).max() < 1e-8
+
+
+def test_beta_and_k_are_stored():
+    ens = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=3, n_levels=6, beta=2, seed=0)
+    assert ens.k == 2
+    assert ens.beta == 2
+    assert ens.n_levels == 6
+
+
+def test_invalid_parameters_rejected():
+    with pytest.raises(ValueError):
+        rmt.ensembles.EmbeddedGaussianEnsemble(n_particles=3, n_levels=6, beta=3, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.EmbeddedGaussianEnsemble(n_particles=3, n_levels=6, k=1, seed=0)
+    with pytest.raises(ValueError):
+        rmt.ensembles.EmbeddedGaussianEnsemble(n_particles=8, n_levels=6, k=2, seed=0)
+
+
+def test_produces_binomial_n_levels_choose_m_eigenvalues():
+    from math import comb
+
+    ens = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=3, n_levels=6, seed=2)
+    spectrum = cached_sample(ens, n_samples=3)
+    assert spectrum.eigenvalues.shape == (3, comb(6, 3))
+
+
+def test_eigenvalues_are_real():
+    ens = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=3, n_levels=6, beta=2, seed=3)
+    spectrum = cached_sample(ens, n_samples=3)
+    assert not np.iscomplexobj(spectrum.eigenvalues)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+def test_beta_2_fresh_sample_is_real_and_finite():
+    # A fresh (uncached) direct .sample() call, to actually exercise the
+    # complex-construction (beta != 1) branch rather than risk a cache hit.
+    ens = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=2, n_levels=4, beta=2, seed=777)
+    spectrum = ens.sample(n_samples=2)
+    assert not np.iscomplexobj(spectrum.eigenvalues)
+    assert np.all(np.isfinite(spectrum.eigenvalues))
+
+
+def test_reproducibility():
+    ens_a = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=3, n_levels=6, seed=42)
+    ens_b = rmt.ensembles.TwoBodyRandomEnsemble(n_particles=3, n_levels=6, seed=42)
+    spec_a = ens_a.sample(n_samples=2)
+    spec_b = ens_b.sample(n_samples=2)
+    np.testing.assert_allclose(spec_a.eigenvalues, spec_b.eigenvalues)

physicskit/rmt/tests/test_free_probability.py

@@ -0,0 +1,81 @@
+"""Tests for the free probability module (Stieltjes/R-transform, free
+additive convolution).
+
+The semicircle R-transform (R(w) = w) was derived directly here (solving
+w = G(z) for z from the semicircle's own Stieltjes transform), not
+recalled, and the generic numerical inversion pipeline
+(``r_transform_numerical``) was checked to reproduce it before being
+trusted to derive/verify the Marchenko-Pastur R-transform
+(R(w) = 1/(1-gamma*w)) against the already-validated exact MP density.
+The free additive convolution theorem itself (R_{A+B} = R_A + R_B for
+independent, asymptotically free random matrices) is checked directly
+against real matrix simulation (independent GOE + Wishart matrices
+added together), not just asserted from the individual closed forms.
+"""
+
+import numpy as np
+import pytest
+
+import physicskit.rmt as rmt
+
+
+def test_stieltjes_transform_semicircle_matches_empirical():
+    ens = rmt.ensembles.GOE(n=2000, seed=0)
+    spectrum = ens.sample(n_samples=1)
+    eigs = spectrum.rescaled[0]
+    for z in [3.0, 5.0, 10.0]:
+        empirical = rmt.stats.stieltjes_transform_empirical(eigs, z)
+        exact = rmt.stats.stieltjes_transform_semicircle(z)
+        assert empirical.real == pytest.approx(exact.real, abs=0.02)
+
+
+def test_numerical_inversion_recovers_semicircle_r_transform():
+    # The pipeline itself, exercised on a Stieltjes transform with a
+    # known-exact R-transform (see module docstring for the derivation).
+    for w in [0.1, 0.3, 0.6, 0.9]:
+        r_numerical = rmt.stats.r_transform_numerical(rmt.stats.stieltjes_transform_semicircle, w, z_bracket=(2.0001, 100.0))
+        assert r_numerical == pytest.approx(rmt.stats.r_transform_semicircle(w), rel=1e-4)
+
+
+def test_numerical_inversion_recovers_marchenko_pastur_r_transform():
+    gamma = 0.5
+    lo, hi = rmt.stats.mp_support(gamma)
+
+    def stieltjes_mp(z):
+        from scipy.integrate import quad
+
+        real, _ = quad(lambda x: rmt.stats.mp_pdf(np.array([x]), gamma)[0] / (z - x), lo, hi, limit=200)
+        return real
+
+    for w in [0.1, 0.3, 0.6]:
+        r_numerical = rmt.stats.r_transform_numerical(stieltjes_mp, w, z_bracket=(hi + 1e-6, hi + 50.0))
+        assert r_numerical == pytest.approx(rmt.stats.r_transform_marchenko_pastur(w, gamma), rel=1e-3)
+
+
+def test_free_additive_convolution_for_goe_plus_wishart():
+    # The genuine content of free probability's additive convolution
+    # theorem: for independent (hence asymptotically free) GOE and
+    # Wishart matrices A, B, the R-transform of A+B's spectral
+    # distribution should equal R_A + R_B -- checked here against DIRECT
+    # matrix simulation, not just the two closed forms in isolation.
+    rng = np.random.default_rng(0)
+    n = 800
+    gamma = 0.5
+    m = int(n / gamma)
+
+    x = rng.standard_normal((n, n))
+    a = (x + x.T) / np.sqrt(2.0) / np.sqrt(n)  # semicircle normalization, variance 1
+
+    y = rng.standard_normal((n, m)) / np.sqrt(m)
+    b = y @ y.T  # Marchenko-Pastur normalization at aspect ratio gamma
+
+    c_eigs = np.linalg.eigvalsh(a + b)
+
+    def stieltjes_c(z):
+        return rmt.stats.stieltjes_transform_empirical(c_eigs, z)
+
+    z_bracket = (c_eigs.max() + 0.05, c_eigs.max() + 50.0)
+    for w in [0.1, 0.2, 0.3]:
+        r_c = rmt.stats.r_transform_numerical(stieltjes_c, w, z_bracket)
+        r_sum = rmt.stats.r_transform_semicircle(w) + rmt.stats.r_transform_marchenko_pastur(w, gamma)
+        assert r_c == pytest.approx(r_sum, rel=0.01)

physicskit/rmt/tests/test_gaussian_ensembles.py

@@ -0,0 +1,22 @@
+"""Coverage for physicskit.rmt.ensembles.gaussian.HermiteBetaEnsemble
+(previously untested directly): the return_eigenvectors=True guard for
+continuum (non-classical) beta values."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+import physicskit.rmt as rmt
+
+
+def test_return_eigenvectors_rejects_continuum_beta():
+    ens = rmt.ensembles.HermiteBetaEnsemble(n=10, beta=1.5, seed=0)
+    with pytest.raises(NotImplementedError):
+        ens.sample(n_samples=2, return_eigenvectors=True)
+
+
+def test_return_eigenvectors_works_for_classical_beta():
+    ens = rmt.ensembles.GOE(n=10, seed=0)
+    spectrum = ens.sample(n_samples=2, return_eigenvectors=True)
+    assert np.all(np.isfinite(spectrum.eigenvalues))