physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/stats/rigidity.py

@@ -0,0 +1,272 @@
+"""Number variance Sigma^2(L): a long-range spectral rigidity statistic,
+more discriminating than nearest-neighbor spacing alone at distinguishing
+correlated (GOE/GUE/GSE) from uncorrelated (Poisson) level sequences.
+
+References
+----------
+F. J. Dyson, M. L. Mehta, "Statistical Theory of the Energy Levels of
+Complex Systems. IV", J. Math. Phys. 4 (1963) 701 -- the original
+number variance formulas.
+M. L. Mehta, *Random Matrices* (3rd ed.), Academic Press, 2004.
+
+Sigma^2(L) is the variance of the number of (unfolded) eigenvalues found
+in a randomly placed interval of length L. For an uncorrelated (Poisson)
+sequence, Sigma^2(L) = L exactly. Level repulsion in GOE/GUE/GSE makes
+the spectrum far more "rigid": Sigma^2(L) grows only logarithmically,
+
+    Sigma^2_beta(L) = (2 / (beta * pi^2)) * ln(L) + K_beta + O(1/L)
+
+(Dyson-Mehta 1963) -- the leading log-coefficient's 1/beta dependence is
+generic across the Gaussian ensembles; the additive constant K_beta
+differs by symmetry class.
+
+Two levels of precision are implemented:
+
+- **beta=2 (GUE): exact**, via direct numerical integration of the
+  bulk two-point correlation function already validated for CUE in
+  ``physicskit.rmt.stats.correlations`` (spacing/rigidity statistics are
+  universal in beta across the Gaussian and circular families, so the
+  same sine-kernel Y_2(r) = (sin(pi*r)/(pi*r))^2 applies here)::
+
+      Sigma^2(L) = L - 2 * integral_0^L (L - r) * Y_2(r) dr
+
+  This is not merely asymptotic -- it holds at any L within the bulk
+  sine-kernel limit, and was verified numerically during development
+  against a Monte Carlo GUE window-counting estimate.
+
+- **beta=1 (GOE) and beta=4 (GSE): large-L asymptotic formulas**,
+  since deriving beta=1,4 analogues of the sine-kernel integral would
+  require the fuller Pfaffian point-process machinery deferred
+  elsewhere in this package (see ``physicskit.rmt.stats.correlations``). The
+  GOE formula is confirmed by two independent secondary sources; the
+  GSE formula follows the same commonly-cited structural pattern and
+  was verified numerically against Monte Carlo GSE window-counting
+  before being included here (both confirmed to agree with simulation
+  at L = 5, 10, 20 to within a few percent -- see
+  ``tests/test_rigidity.py``).
+
+Also implemented here: the companion Dyson-Mehta Delta_3(L) statistic
+(least-squares deviation of the staircase counting function from a
+locally fit straight line), via ``spectral_rigidity_empirical`` (a
+direct, formula-free estimator valid for any point process) and
+``spectral_rigidity_theory`` (the exact integral relation to Sigma^2(L),
+inheriting the same beta=2-exact / beta=1,4-asymptotic precision).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from scipy.integrate import quad
+
+from ..spectrum import Spectrum
+
+_GAMMA_E = 0.5772156649015329  # Euler-Mascheroni constant
+
+
+def number_variance_empirical(
+    spectrum: Spectrum,
+    cdf_func: Callable[[np.ndarray], np.ndarray],
+    l_values: np.ndarray,
+    n_windows: int = 200,
+    seed: int | np.random.Generator | None = None,
+) -> np.ndarray:
+    """Estimate Sigma^2(L) for each L in ``l_values`` by counting
+    unfolded eigenvalues in many randomly placed windows.
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+    cdf_func : callable
+        Theoretical CDF used for unfolding (e.g.
+        ``physicskit.rmt.stats.density.semicircle_cdf``).
+    l_values : sequence of float
+    n_windows : int
+        Random window placements per sample.
+    seed : int or None
+
+    Returns
+    -------
+    numpy.ndarray
+        Sigma^2(L) estimates, one per entry in ``l_values``.
+    """
+    rng = np.random.default_rng(seed)
+    results = []
+    for length in l_values:
+        all_counts = []
+        for row in spectrum.rescaled:
+            n = len(row)
+            unfolded = n * cdf_func(row)
+            lo, hi = unfolded[0], unfolded[-1]
+            if hi - lo < 3 * length:
+                continue  # window plus margin doesn't fit; skip this sample at this L
+            starts = rng.uniform(lo, hi - length, size=n_windows)
+            counts = np.array([np.sum((unfolded >= s) & (unfolded < s + length)) for s in starts])
+            all_counts.append(counts)
+        results.append(np.var(np.concatenate(all_counts)))
+    return np.array(results)
+
+
+def number_variance_poisson(l_values: np.ndarray) -> np.ndarray:
+    """Exact number variance for an uncorrelated (Poisson) sequence:
+    Sigma^2(L) = L. The "soft spectrum" baseline that GOE/GUE/GSE's
+    logarithmic rigidity is contrasted against."""
+    return np.asarray(l_values, dtype=float)
+
+
+def _sine_kernel_y2(r: np.ndarray) -> np.ndarray:
+    r = np.asarray(r, dtype=float)
+    out = np.ones_like(r)
+    mask = np.abs(r) > 1e-10
+    out[mask] = (np.sin(np.pi * r[mask]) / (np.pi * r[mask])) ** 2
+    return out
+
+
+def number_variance_gue_exact(l_values: np.ndarray) -> np.ndarray:
+    """Exact bulk-sine-kernel number variance (beta=2 / GUE / CUE):
+    Sigma^2(L) = L - 2 * integral_0^L (L-r) * Y_2(r) dr.
+    """
+    l_values = np.atleast_1d(np.asarray(l_values, dtype=float))
+    out = np.empty_like(l_values)
+    for i, length in enumerate(l_values):
+        # limit=200 (vs scipy's default 50): the oscillatory sine-kernel
+        # integrand at large L otherwise triggers a subdivision-limit
+        # warning even though the result is already converged (verified
+        # numerically -- the value is identical to 1e-7 either way, this
+        # just silences a spurious warning rather than fixing an
+        # accuracy problem).
+        val, _ = quad(lambda r, length=length: (length - r) * _sine_kernel_y2(r), 0, length, limit=200)
+        out[i] = length - 2.0 * val
+    return out
+
+
+def number_variance_goe_asymptotic(l_values: np.ndarray) -> np.ndarray:
+    """Large-L asymptotic number variance for beta=1 (GOE):
+    Sigma^2(L) = (2/pi^2) * [ln(2*pi*L) + gamma_E + 1 - pi^2/8].
+    """
+    l_values = np.asarray(l_values, dtype=float)
+    return (2.0 / np.pi**2) * (np.log(2 * np.pi * l_values) + _GAMMA_E + 1.0 - np.pi**2 / 8.0)
+
+
+def number_variance_gse_asymptotic(l_values: np.ndarray) -> np.ndarray:
+    """Large-L asymptotic number variance for beta=4 (GSE):
+    Sigma^2(L) = (1/(2*pi^2)) * [ln(4*pi*L) + gamma_E + 1 + pi^2/8].
+    """
+    l_values = np.asarray(l_values, dtype=float)
+    return (1.0 / (2 * np.pi**2)) * (np.log(4 * np.pi * l_values) + _GAMMA_E + 1.0 + np.pi**2 / 8.0)
+
+
+def number_variance_theory(l_values: np.ndarray, beta: float) -> np.ndarray:
+    """Dispatch to the appropriate theoretical Sigma^2(L) by beta:
+    exact for beta=2, large-L asymptotic for beta=1, 4."""
+    if beta == 1:
+        return number_variance_goe_asymptotic(l_values)
+    if beta == 2:
+        return number_variance_gue_exact(l_values)
+    if beta == 4:
+        return number_variance_gse_asymptotic(l_values)
+    raise ValueError(f"Only beta in (1, 2, 4) have implemented formulas here, got {beta}")
+
+
+def spectral_rigidity_empirical(
+    spectrum: Spectrum,
+    cdf_func: Callable[[np.ndarray], np.ndarray],
+    l_values: np.ndarray,
+    n_windows: int = 200,
+    n_grid_per_window: int = 1500,
+    seed: int | np.random.Generator | None = None,
+) -> np.ndarray:
+    """Estimate the Dyson-Mehta Delta_3(L) statistic for each L in
+    ``l_values``, directly from its definition: the mean-square deviation
+    of the (unfolded) staircase counting function N(xi) from its best-fit
+    line, over many randomly placed windows of length L.
+
+    Delta_3(L) = (1/L) * min_{A,B} <integral_x^{x+L} (N(xi) - A*xi - B)^2 dxi>
+
+    Unlike ``number_variance_theory``, no closed-form kernel is assumed
+    here -- each window's line fit is solved numerically (least squares
+    against N(xi) sampled on a fine grid), so this estimator is valid for
+    ANY point process, not just the classical beta-ensembles. Verified
+    against the exact Poisson result (``spectral_rigidity_poisson``,
+    Delta_3(L) = L/15) and against ``spectral_rigidity_theory`` at
+    beta=2 (GUE) during development -- both matched to within Monte Carlo
+    noise (a few percent) -- see ``tests/test_rigidity.py``.
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+    cdf_func : callable
+        Theoretical CDF used for unfolding (e.g.
+        ``physicskit.rmt.stats.density.semicircle_cdf``).
+    l_values : numpy.ndarray
+    n_windows : int
+        Random window placements per sample.
+    n_grid_per_window : int
+        Grid resolution used to approximate the line-fit integral within
+        each window.
+    seed : int, numpy.random.Generator, or None, optional
+
+    Returns
+    -------
+    numpy.ndarray
+        Delta_3(L) estimates, one per entry in ``l_values``.
+    """
+    rng = np.random.default_rng(seed)
+    results = []
+    for length in l_values:
+        vals = []
+        for row in spectrum.rescaled:
+            n = len(row)
+            unfolded = n * cdf_func(row)
+            lo, hi = unfolded[0], unfolded[-1]
+            if hi - lo < 3 * length:
+                continue
+            starts = rng.uniform(lo, hi - length, size=n_windows)
+            for start in starts:
+                grid = np.linspace(start, start + length, n_grid_per_window)
+                counts = np.searchsorted(unfolded, grid, side="right").astype(float)
+                design = np.vstack([grid, np.ones_like(grid)]).T
+                coeffs, *_ = np.linalg.lstsq(design, counts, rcond=None)
+                residual = counts - design @ coeffs
+                vals.append(np.mean(residual**2))
+        results.append(np.mean(vals))
+    return np.array(results)
+
+
+def spectral_rigidity_poisson(l_values: np.ndarray) -> np.ndarray:
+    """Exact Dyson-Mehta Delta_3(L) for an uncorrelated (Poisson)
+    sequence: Delta_3(L) = L/15 -- verified numerically here against
+    ``spectral_rigidity_empirical`` on ``PoissonEnsemble`` samples (see
+    ``tests/test_rigidity.py``), the same "soft spectrum" baseline
+    ``number_variance_poisson`` provides for Sigma^2(L)."""
+    return np.asarray(l_values, dtype=float) / 15.0
+
+
+def spectral_rigidity_theory(l_values: np.ndarray, beta: float) -> np.ndarray:
+    """Theoretical Delta_3(L) at Dyson index beta (1, 2, or 4), via its
+    exact integral relation to the number variance:
+
+        Delta_3(L) = (2/L^4) * integral_0^L (L^3 - 2*L^2*r + r^3) * Sigma^2(r) dr
+
+    (Dyson-Mehta 1963; also e.g. Guhr, Mueller-Groeling, Weidenmueller,
+    "Random-matrix theories in quantum physics", Phys. Rep. 299 (1998)
+    189, Eq. (2.14).) Sigma^2 is dispatched via
+    ``number_variance_theory``, so this inherits the same precision:
+    exact at beta=2, large-L asymptotic at beta=1, 4. Verified numerically
+    against ``spectral_rigidity_empirical`` during development: beta=2
+    matched Monte Carlo GUE to within ~1%, beta=1 matched Monte Carlo GOE
+    to within the same few-percent tolerance already documented for
+    ``number_variance_goe_asymptotic`` -- see ``tests/test_rigidity.py``.
+    """
+    l_values = np.atleast_1d(np.asarray(l_values, dtype=float))
+    out = np.empty_like(l_values)
+    for i, length in enumerate(l_values):
+
+        def integrand(r: float, length: float = length) -> float:
+            sigma2 = number_variance_theory(np.array([r]), beta)[0]
+            return (length**3 - 2.0 * length**2 * r + r**3) * sigma2
+
+        val, _ = quad(integrand, 0, length, limit=200)
+        out[i] = 2.0 / length**4 * val
+    return out

physicskit/rmt/stats/single_ring.py

@@ -0,0 +1,95 @@
+"""The single ring theorem's radii formula (see
+``physicskit.rmt.ensembles.single_ring`` for the full construction and
+references): a bi-unitarily-invariant non-Hermitian ensemble's
+eigenvalues fill the annulus ``r_in <= |z| <= r_out``, with
+
+    r_out = sqrt(<s^2>)          r_in = 1 / sqrt(<1/s^2>)
+
+for singular values s.
+"""
+
+import numpy as np
+
+
+def single_ring_radii(singular_values: np.ndarray) -> tuple[float, float]:
+    """Theoretical single-ring radii (r_in, r_out) from a set of
+    singular values (or samples from the limiting singular-value
+    distribution).
+
+    Parameters
+    ----------
+    singular_values : numpy.ndarray
+
+    Returns
+    -------
+    r_in : float
+    r_out : float
+    """
+    singular_values = np.asarray(singular_values, dtype=float)
+    r_out = np.sqrt(np.mean(singular_values**2))
+    r_in = 1.0 / np.sqrt(np.mean(1.0 / singular_values**2))
+    return float(r_in), float(r_out)
+
+
+def single_ring_radii_wishart_theory(gamma: float) -> tuple[float, float]:
+    """Exact single-ring radii for ``NonHermitianWishartEnsemble`` at
+    aspect ratio gamma = n/m < 1: r_out = 1, r_in = sqrt(1 - gamma), from
+    the Marchenko-Pastur distribution's exact moments E[X] = 1 and
+    E[1/X] = 1/(1-gamma) -- verified numerically during development (see
+    ``tests/test_single_ring.py``) before being used here.
+
+    Parameters
+    ----------
+    gamma : float
+        Aspect ratio n/m, must be in (0, 1).
+
+    Returns
+    -------
+    r_in : float
+    r_out : float
+    """
+    if not 0.0 < gamma < 1.0:
+        raise ValueError(f"gamma must be in (0, 1), got {gamma}")
+    return float(np.sqrt(1.0 - gamma)), 1.0
+
+
+def annulus_radial_cdf(r: np.ndarray, r_in: float, r_out: float) -> np.ndarray:
+    """Radial marginal CDF of the uniform distribution on the annulus
+    ``r_in <= |z| <= r_out``: F(r) = (r^2 - r_in^2) / (r_out^2 - r_in^2),
+    the direct generalization of
+    ``physicskit.rmt.stats.circular_law.circular_law_radial_cdf`` (its r_in=0,
+    r_out=1 special case).
+
+    Parameters
+    ----------
+    r : numpy.ndarray
+    r_in : float
+    r_out : float
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    r = np.clip(np.asarray(r, dtype=float), r_in, r_out)
+    return (r**2 - r_in**2) / (r_out**2 - r_in**2)
+
+
+def annulus_radial_pdf(r: np.ndarray, r_in: float, r_out: float) -> np.ndarray:
+    """Radial marginal density of the uniform distribution on the
+    annulus ``r_in <= |z| <= r_out``: f(r) = 2r / (r_out^2 - r_in^2).
+
+    Parameters
+    ----------
+    r : numpy.ndarray
+    r_in : float
+    r_out : float
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    r = np.asarray(r, dtype=float)
+    out = np.zeros_like(r)
+    mask = (r >= r_in) & (r <= r_out)
+    out[mask] = 2.0 * r[mask] / (r_out**2 - r_in**2)
+    return out

physicskit/rmt/stats/spacing.py

@@ -0,0 +1,150 @@
+"""Nearest-neighbor spacing distribution P(s), and the (generalized)
+Wigner surmise it is validated against.
+
+References
+----------
+E. P. Wigner -- the original surmise, for GOE (beta=1).
+M. L. Mehta, *Random Matrices* (3rd ed.), Academic Press, 2004 -- the
+GUE/GSE surmises and their derivation from the 2x2 ensemble.
+
+The beta-dependent closed form used here::
+
+    P_beta(s) = a(beta) * s**beta * exp(-b(beta) * s**2)
+
+with a, b fixed by normalization (integral P ds = 1) and unit mean
+spacing (integral s*P ds = 1), reduces exactly to the classical
+GOE/GUE/GSE surmises at beta = 1, 2, 4 and is the standard two-parameter
+generalization to continuum beta (see e.g. G. Livan, M. Novaes, P. Vivo,
+"Introduction to Random Matrices: Theory and Practice", Springer, 2018,
+Sec. 2.4). It is a surmise -- exact for the 2x2 ensemble, an excellent
+but not exact approximation to the true N-level spacing distribution --
+which is why it is validated here as a benchmark rather than assumed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from scipy.special import gamma, gammainc, gammaincinv
+
+from ..spectrum import Spectrum
+from .unfolding import unfold_by_cdf
+
+
+def nearest_neighbor_spacings(
+    spectrum: Spectrum,
+    cdf_func: Callable[[np.ndarray], np.ndarray],
+    edge_trim: float = 0.1,
+) -> np.ndarray:
+    """Unfolded nearest-neighbor spacings, pooled across every sample in
+    a Spectrum.
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+    cdf_func : callable
+        Theoretical CDF used for unfolding (e.g.
+        ``physicskit.rmt.stats.density.semicircle_cdf`` for the Gaussian
+        ensembles).
+    edge_trim : float
+        Fraction of eigenvalues discarded from each edge *after*
+        unfolding, before taking spacings. The mean spectral density --
+        and therefore unfolding accuracy -- is least reliable near the
+        spectrum edges (soft-edge Tracy-Widom effects live exactly
+        there), so edge eigenvalues bias the bulk spacing statistic if
+        included. Trimming must happen after unfolding, not before:
+        unfolding uses the total eigenvalue count N as the scale factor,
+        so trimming first would unfold against the wrong N and bias the
+        mean spacing away from 1.
+
+    Returns
+    -------
+    numpy.ndarray
+        Pooled unfolded spacings from all samples.
+    """
+    all_spacings = []
+    for row in spectrum.rescaled:
+        n = len(row)
+        unfolded = unfold_by_cdf(row, cdf_func)
+        lo = int(edge_trim * n)
+        hi = n - lo
+        if hi - lo < 2:
+            continue
+        all_spacings.append(np.diff(unfolded[lo:hi]))
+    return np.concatenate(all_spacings)
+
+
+def circular_spacings(spectrum: Spectrum) -> np.ndarray:
+    """Unfolded nearest-neighbor spacings for a circular ensemble
+    (COE/CUE/CSE), including the wraparound spacing between the largest
+    and smallest phase.
+
+    Unlike the Gaussian/Wishart ensembles, a circular ensemble has no
+    spectrum edge (it lives on a circle) and no unfolding-accuracy
+    concerns (``spectrum.rescaled`` is already exactly unfolded, see
+    ``physicskit.rmt.ensembles.circular``), so every spacing is used -- no edge
+    trimming, and one extra "wraparound" spacing per sample compared to
+    the linear-spectrum case.
+    """
+    all_spacings = []
+    for row in spectrum.rescaled:
+        n = len(row)
+        row_sorted = np.sort(row)
+        spacings = np.diff(row_sorted)
+        wraparound = (row_sorted[0] + n) - row_sorted[-1]
+        all_spacings.append(np.concatenate([spacings, [wraparound]]))
+    return np.concatenate(all_spacings)
+
+
+def wigner_surmise_params(beta: float) -> tuple[float, float]:
+    """(a, b) for P_beta(s) = a * s**beta * exp(-b * s**2), normalized to
+    integral P(s) ds = 1 and integral s * P(s) ds = 1 (unit mean spacing).
+
+    Derivation: writing the two normalization integrals in terms of
+    Gamma functions and eliminating a gives
+        b = [Gamma((beta+2)/2) / Gamma((beta+1)/2)]**2
+        a = 2 * b**((beta+1)/2) / Gamma((beta+1)/2)
+    Verified numerically against the classical closed forms at
+    beta=1 (a=pi/2, b=pi/4), beta=2 (a=32/pi^2, b=4/pi), and
+    beta=4 (a=2**18/(3**6 pi**3), b=64/(9 pi)).
+    """
+    b = (gamma((beta + 2) / 2) / gamma((beta + 1) / 2)) ** 2
+    a = 2 * b ** ((beta + 1) / 2) / gamma((beta + 1) / 2)
+    return a, b
+
+
+def wigner_surmise_pdf(s: np.ndarray, beta: float) -> np.ndarray:
+    """Generalized Wigner surmise density at spacing(s) s."""
+    a, b = wigner_surmise_params(beta)
+    s = np.asarray(s, dtype=float)
+    out = np.zeros_like(s)
+    mask = s >= 0
+    out[mask] = a * s[mask] ** beta * np.exp(-b * s[mask] ** 2)
+    return out
+
+
+def wigner_surmise_cdf(s: np.ndarray, beta: float) -> np.ndarray:
+    """Generalized Wigner surmise CDF.
+
+    Closed form: substituting u = t^2 in the defining integral reduces it
+    to the regularized lower incomplete gamma function,
+        F(s) = P((beta+1)/2, b*s^2)
+    (verified numerically against direct quadrature of the PDF).
+    """
+    _, b = wigner_surmise_params(beta)
+    s = np.asarray(s, dtype=float)
+    out = np.zeros_like(s)
+    mask = s >= 0
+    out[mask] = gammainc((beta + 1) / 2, b * s[mask] ** 2)
+    return out
+
+
+def wigner_surmise_samples(size: int | tuple[int, ...], beta: float, rng: np.random.Generator) -> np.ndarray:
+    """Exact samples from the generalized Wigner surmise via inverse-CDF
+    sampling (the CDF's closed form as a regularized incomplete gamma
+    function has a matching closed-form inverse, ``gammaincinv``, so no
+    rejection sampling is needed)."""
+    _, b = wigner_surmise_params(beta)
+    u = rng.uniform(0.0, 1.0, size=size)
+    return np.sqrt(gammaincinv((beta + 1) / 2, u) / b)

physicskit/rmt/stats/tracy_widom.py

@@ -0,0 +1,175 @@
+"""The Tracy-Widom distributions F_1, F_2, F_4: limiting law of the
+largest eigenvalue at the soft edge of the Gaussian ensembles.
+
+References
+----------
+C. A. Tracy, H. Widom, "Level-spacing distributions and the Airy
+kernel", Commun. Math. Phys. 159 (1994) 151 -- F_2 (GUE, beta=2).
+C. A. Tracy, H. Widom, "On orthogonal and symplectic matrix ensembles",
+Commun. Math. Phys. 177 (1996) 727 -- F_1 (GOE, beta=1) and F_4
+(GSE, beta=4).
+
+Construction
+------------
+All three distributions are built from q(x), the Hastings-McLeod
+solution of the Painleve II equation
+
+    q''(x) = x*q(x) + 2*q(x)^3,   q(x) ~ Ai(x) as x -> +infinity
+
+(the unique solution with this decaying tail; other solutions of the
+same ODE blow up). q is obtained numerically by integrating *backward*
+from a large positive x0 (where q(x0) = Ai(x0), q'(x0) = Ai'(x0) to
+machine precision) down to a negative x_min -- forward integration from
+-infinity is unstable, since nearby non-Hastings-McLeod solutions
+diverge exponentially in that direction.
+
+Numerical domain note: backward integration itself becomes unstable
+(round-off eventually kicks the trajectory onto a diverging branch) for
+x below about -9 to -10. This implementation restricts to [-6, 6] by
+default, verified to match the known asymptotic q(x) ~ sqrt(-x/2) to
+better than 0.2% at x=-6, and F_2/F_1/F_4 are already extremely close to
+0 there (the left tail decays like ``exp(-|s|^3/12)``), so truncating the
+domain has negligible effect on the distributions actually used.
+
+Given q, the three distributions are:
+
+    F_2(s) = exp(-integral_s^inf (x-s) q(x)^2 dx)
+    F_1(s) = sqrt(F_2(s)) * exp(-(1/2) * integral_s^inf q(x) dx)
+    F_4(s) = sqrt(F_2(s)) * cosh((1/2) * integral_s^inf q(x) dx)
+
+Edge-scaling note (important, and the one detail here that is NOT
+standard textbook boilerplate): for a Gaussian beta-ensemble normalized
+to semicircle support [-2, 2] (as ``physicskit.rmt.ensembles.gaussian`` uses),
+the largest eigenvalue converges as
+
+    n^(2/3) * (lambda_max - 2)  ->  F_1   (GOE, beta=1)
+    n^(2/3) * (lambda_max - 2)  ->  F_2   (GUE, beta=2)
+    (2n)^(2/3) * (lambda_max - 2)  ->  F_4   (GSE, beta=4)
+
+The GSE case's extra factor of 2 in the effective scale is easy to get
+wrong from memory (and was NOT assumed here) -- it was determined by
+directly comparing candidate scalings against Monte Carlo largest-
+eigenvalue samples from the already-validated ``GSE`` ensemble, via a
+KS test, rather than taken from a half-remembered formula. See the
+design/development notes and ``tests/test_tracy_widom.py``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.integrate import cumulative_trapezoid, solve_ivp
+from scipy.special import airy
+
+from ..spectrum import Spectrum
+
+
+@dataclass
+class _PainleveIISolution:
+    grid: np.ndarray
+    F1: np.ndarray
+    F2: np.ndarray
+    F4: np.ndarray
+
+
+_CACHE: dict[tuple[float, float, int], _PainleveIISolution] = {}
+
+
+def _solve(x_max: float = 6.0, x_min: float = -6.0, n_grid: int = 20000) -> _PainleveIISolution:
+    """Solve Painleve II once and build F1/F2/F4 on a grid. Cached by
+    (x_max, x_min, n_grid) since this is a one-time cost reused by every
+    subsequent CDF/PDF/sampling call."""
+    key = (x_max, x_min, n_grid)
+    if key in _CACHE:
+        return _CACHE[key]
+
+    def rhs(x: float, y: tuple[float, float]) -> list[float]:
+        q, qp = y
+        return [qp, x * q + 2.0 * q**3]
+
+    ai, aip, _, _ = airy(x_max)
+    sol = solve_ivp(
+        rhs,
+        [x_max, x_min],
+        [ai, aip],
+        dense_output=True,
+        rtol=1e-12,
+        atol=1e-14,
+        max_step=0.005,
+    )
+    if not sol.success:
+        raise RuntimeError(f"Painleve II integration failed: {sol.message}")
+
+    grid = np.linspace(x_min, x_max, n_grid)
+    q_vals = sol.sol(grid)[0]
+
+    # Reverse cumulative integrals (needed since every quantity here is
+    # defined as an integral from s to +infinity, i.e. against the grid's
+    # natural ascending order).
+    xs_rev = grid[::-1]
+    q2_rev = (q_vals**2)[::-1]
+    q_rev = q_vals[::-1]
+
+    a_s = -cumulative_trapezoid(q2_rev, xs_rev, initial=0.0)[::-1]  # int_s^inf q^2 dx
+    b_s = -cumulative_trapezoid(xs_rev * q2_rev, xs_rev, initial=0.0)[::-1]  # int_s^inf x q^2 dx
+    i_s = -cumulative_trapezoid(q_rev, xs_rev, initial=0.0)[::-1]  # int_s^inf q dx
+
+    r_s = b_s - grid * a_s
+    f2 = np.exp(-r_s)
+    f2_clipped = np.clip(f2, 0.0, 1.0)
+    f1 = np.sqrt(f2_clipped) * np.exp(-0.5 * i_s)
+    f4 = np.sqrt(f2_clipped) * np.cosh(0.5 * i_s)
+
+    result = _PainleveIISolution(grid=grid, F1=f1, F2=np.clip(f2, 0.0, 1.0), F4=np.clip(f4, 0.0, 1.0))
+    _CACHE[key] = result
+    return result
+
+
+# beta -> which precomputed curve, and the edge-scaling exponent base
+# (n for beta=1,2; 2*n for beta=4 -- see module docstring).
+_BETA_CURVE = {1: "F1", 2: "F2", 4: "F4"}
+_BETA_SCALE_MULTIPLIER = {1: 1.0, 2: 1.0, 4: 2.0}
+
+
+def largest_eigenvalues(spectrum: Spectrum) -> np.ndarray:
+    """The largest (rescaled) eigenvalue from each sample in a Spectrum
+    -- the raw statistic that Tracy-Widom-type soft-edge laws govern."""
+    return spectrum.rescaled.max(axis=1)
+
+
+def tracy_widom_cdf(s: np.ndarray, beta: int) -> np.ndarray:
+    """CDF of the Tracy-Widom distribution at Dyson index beta (1, 2, or 4)."""
+    if beta not in _BETA_CURVE:
+        raise ValueError(
+            f"Only beta in {{1, 2, 4}} have closed-form Tracy-Widom laws "
+            f"(F_1, F_2, F_4); beta={beta} is not supported. The general-beta "
+            f"soft-edge law exists (Ramirez-Rider-Virag stochastic Airy "
+            f"operator) but has no elementary closed form."
+        )
+    sol = _solve()
+    curve = getattr(sol, _BETA_CURVE[beta])
+    s = np.asarray(s, dtype=float)
+    return np.interp(s, sol.grid, curve, left=0.0, right=1.0)
+
+
+def tracy_widom_edge_scale(n: int, beta: int) -> float:
+    """Factor by which (lambda_max - 2) should be multiplied to compare
+    against the beta-indexed Tracy-Widom CDF: n^(2/3) for beta=1, 2;
+    (2n)^(2/3) for beta=4 (see module docstring for how the beta=4 factor
+    was determined)."""
+    if beta not in _BETA_SCALE_MULTIPLIER:
+        raise ValueError(f"Only beta in {{1, 2, 4}} are supported, got {beta}")
+    return (_BETA_SCALE_MULTIPLIER[beta] * n) ** (2.0 / 3.0)
+
+
+def tracy_widom_rvs(size: int | tuple[int, ...], beta: int, rng: np.random.Generator) -> np.ndarray:
+    """Sample from the Tracy-Widom distribution via inverse-CDF
+    interpolation on the same grid used for the CDF."""
+    if beta not in _BETA_CURVE:
+        raise ValueError(f"Only beta in {{1, 2, 4}} are supported, got {beta}")
+    sol = _solve()
+    curve = getattr(sol, _BETA_CURVE[beta])
+    # curve is monotonically increasing in practice; interpolate its inverse
+    u = rng.uniform(curve[0], curve[-1], size=size)
+    return np.interp(u, curve, sol.grid)