physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/stats/pt_symmetric.py

@@ -0,0 +1,265 @@
+"""Statistics for the PT-symmetry-breaking transition (see
+``physicskit.rmt.ensembles.pt_symmetric``): the fraction of real eigenvalues as
+a function of the non-Hermiticity/coupling parameter g -- the
+transition curve itself is the benchmark here, not a fixed limiting
+law, since the ensemble's spectral character genuinely changes (real ->
+partially complex) as g varies.
+
+Also implemented: exceptional-point detection. An exceptional point is
+where two eigenvalues AND their eigenvectors coalesce as a control
+parameter varies -- unlike an ordinary level crossing (eigenvalues
+cross, eigenvectors stay linearly independent), ``find_exceptional_points``
+locates these by sweeping g for a single FIXED random realization (same
+underlying blocks, only g rescaling the coupling block) and finding
+where the real-eigenvalue count drops. Verified numerically during
+development that these are genuine eigenvector coalescences, not mere
+crossings: the right-eigenvector matrix's condition number grows sharply
+approaching each detected g (2 -> 6 -> 38 within 0.002 of one such point
+in a test case), the signature of the matrix becoming nearly
+non-diagonalizable there -- see ``eigenvector_condition_number`` and
+``tests/test_pt_symmetric.py``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..ensembles.pt_symmetric import PTSymmetricEnsemble
+
+
+def real_eigenvalue_fraction(eigenvalues: np.ndarray, tol: float = 1e-6) -> np.ndarray:
+    """Fraction of (near-)real eigenvalues per sample.
+
+    Parameters
+    ----------
+    eigenvalues : numpy.ndarray, shape (n_samples, n), complex
+    tol : float, optional
+        An eigenvalue counts as real if ``abs(Im(lambda))`` is below
+        this.
+
+    Returns
+    -------
+    numpy.ndarray, shape (n_samples,)
+        Fraction (in [0, 1]) of real eigenvalues in each sample.
+    """
+    eigenvalues = np.asarray(eigenvalues)
+    return np.mean(np.abs(eigenvalues.imag) < tol, axis=-1)
+
+
+def semi_poisson_pdf(s: np.ndarray) -> np.ndarray:
+    """The semi-Poisson intermediate-statistics spacing density:
+    P(s) = 4*s*exp(-2*s). Normalized (integral P ds = 1) and unit mean
+    spacing (integral s*P ds = 1) -- checked directly here (both
+    integrals evaluate to exactly 1 in closed form) rather than assumed.
+
+    Characterizes level spacing at various "critical"/intermediate
+    universality classes between Poisson (uncorrelated) and Wigner-Dyson
+    (GOE-type): linear level repulsion at small s (like GOE, unlike
+    Poisson's flat P(0)=1), but exponential (not Gaussian) large-s decay
+    (like Poisson, unlike GOE's exp(-s^2)). Verified numerically here to
+    be a substantially better fit than either pure Poisson or pure GOE
+    to the surviving REAL eigenvalues' spacing distribution of
+    ``PTSymmetricEnsemble`` at small-to-moderate coupling g (KS
+    statistic roughly half that of the alternatives at g up to ~0.6) --
+    see ``tests/test_pt_symmetric.py``.
+
+    Parameters
+    ----------
+    s : numpy.ndarray
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    s = np.asarray(s, dtype=float)
+    return 4.0 * s * np.exp(-2.0 * s)
+
+
+def semi_poisson_cdf(s: np.ndarray) -> np.ndarray:
+    """CDF of the semi-Poisson spacing density: F(s) = 1 - (2s+1)*exp(-2s).
+
+    Parameters
+    ----------
+    s : numpy.ndarray
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    s = np.asarray(s, dtype=float)
+    return 1.0 - (2.0 * s + 1.0) * np.exp(-2.0 * s)
+
+
+def real_axis_spacings(eigenvalues: np.ndarray, tol: float = 1e-6) -> np.ndarray:
+    """Nearest-neighbor spacings of the (near-)real eigenvalues in each
+    sample, rescaled to unit mean spacing per sample and pooled.
+
+    No unfolding CDF is used (unlike
+    ``physicskit.rmt.stats.spacing.nearest_neighbor_spacings``): the real-
+    eigenvalue density of a PT-symmetric ensemble near its
+    symmetry-breaking transition has no known closed form, so this uses
+    the simple, standard alternative of rescaling each sample's raw
+    spacings by their own empirical mean -- adequate for a KS/shape
+    comparison against ``semi_poisson_cdf``, though not as precise as
+    unfolding against a known exact density.
+
+    Parameters
+    ----------
+    eigenvalues : numpy.ndarray, shape (n_samples, n), complex
+    tol : float, optional
+        Passed to the real/complex classification (see
+        ``real_eigenvalue_fraction``).
+
+    Returns
+    -------
+    numpy.ndarray
+        Pooled, mean-rescaled nearest-neighbor spacings of the real
+        eigenvalues (samples with fewer than 3 real eigenvalues are
+        skipped, since a mean spacing needs at least 2 spacings).
+    """
+    pooled = []
+    for row in eigenvalues:
+        real_values = np.sort(row.real[np.abs(row.imag) < tol])
+        if len(real_values) < 3:
+            continue
+        spacings = np.diff(real_values)
+        spacings = spacings[spacings > 1e-12]
+        if len(spacings) < 2:
+            continue
+        pooled.append(spacings / spacings.mean())
+    return np.concatenate(pooled)
+
+
+def _fixed_realization_matrix(p: int, q: int, beta: int, seed: int, g: float) -> np.ndarray:
+    """The PT-symmetric matrix for a SINGLE fixed random realization
+    (blocks A, D, and the unscaled coupling direction determined
+    entirely by ``seed``), at coupling strength ``g``. Since
+    ``PTSymmetricEnsemble._sample_matrix`` draws A, D, then the coupling
+    block (multiplied by g only at the very end) in a fixed order from a
+    generator seeded identically each call, reconstructing the ensemble
+    with a different g but the same seed reproduces the same A, D and
+    unscaled coupling direction -- verified during development (see
+    module docstring) -- making it possible to sweep g continuously for
+    one realization rather than redrawing new randomness at every g.
+    """
+    ensemble = PTSymmetricEnsemble(p=p, q=q, g=g, beta=beta, seed=seed)
+    return ensemble._sample_matrix(np.random.default_rng(seed))
+
+
+def find_exceptional_points(
+    p: int,
+    q: int,
+    beta: int,
+    seed: int,
+    g_max: float = 5.0,
+    n_grid: int = 4000,
+    tol: float = 1e-6,
+) -> np.ndarray:
+    """Locate exceptional points for a single fixed PT-symmetric
+    realization by sweeping the coupling g in ``[0, g_max]`` and finding
+    where the real-eigenvalue count decreases (a pair of real
+    eigenvalues has merged and split into a complex-conjugate pair).
+
+    Parameters
+    ----------
+    p, q : int
+        Signature block sizes (see ``PTSymmetricEnsemble``).
+    beta : int
+        1 or 2.
+    seed : int
+        Fixes the single realization swept over g.
+    g_max : float, optional
+        Upper end of the g-sweep.
+    n_grid : int, optional
+        Number of g-grid points.
+    tol : float, optional
+        Passed to ``real_eigenvalue_fraction``.
+
+    Returns
+    -------
+    numpy.ndarray
+        g-values (grid resolution) at which a real-eigenvalue-count drop
+        was detected -- approximate exceptional-point locations for this
+        realization.
+    """
+    g_grid = np.linspace(0.0, g_max, n_grid)
+    real_counts = np.empty(n_grid)
+    for i, g in enumerate(g_grid):
+        eigenvalues = np.linalg.eigvals(_fixed_realization_matrix(p, q, beta, seed, g))
+        real_counts[i] = np.sum(np.abs(eigenvalues.imag) < tol)
+    drops = np.where(np.diff(real_counts) < 0)[0]
+    return g_grid[drops]
+
+
+def mean_exceptional_point_count(
+    p: int,
+    q: int,
+    beta: int,
+    g_max: float,
+    n_realizations: int = 30,
+    seed: int | np.random.Generator | None = None,
+    n_grid: int = 2000,
+    tol: float = 1e-6,
+) -> tuple[float, float]:
+    """Ensemble-level exceptional-point statistic: the mean number of
+    exceptional points found in ``[0, g_max]`` (see
+    ``find_exceptional_points``), averaged over ``n_realizations``
+    independent random realizations.
+
+    Verified numerically during development to grow roughly linearly
+    with ``min(p, q)`` at fixed g_max (e.g. p=q=4, 8, 12 gave mean counts
+    of about 4.2, 8.7, 13.1 over g in [0, 2] with beta=2) -- consistent
+    with the expectation that roughly min(p, q) real-eigenvalue pairs
+    must eventually transition as g grows, though this specific scaling
+    was observed rather than derived from a closed-form prediction.
+
+    Parameters
+    ----------
+    p, q : int
+    beta : int
+    g_max : float
+    n_realizations : int, optional
+        Independent random realizations (distinct seeds) to average
+        over.
+    seed : int, numpy.random.Generator, or None, optional
+        Seeds the sequence of per-realization seeds.
+    n_grid, tol : see ``find_exceptional_points``.
+
+    Returns
+    -------
+    mean_count : float
+    standard_error : float
+    """
+    rng = np.random.default_rng(seed)
+    raw_counts = []
+    for _ in range(n_realizations):
+        realization_seed = int(rng.integers(1 << 31))
+        eps = find_exceptional_points(p, q, beta, realization_seed, g_max, n_grid, tol)
+        raw_counts.append(len(eps))
+    counts = np.array(raw_counts, dtype=float)
+    return float(counts.mean()), float(counts.std(ddof=1) / np.sqrt(n_realizations))
+
+
+def eigenvector_condition_number(p: int, q: int, beta: int, seed: int, g: float) -> float:
+    """Condition number of the right-eigenvector matrix of the fixed-
+    realization PT-symmetric matrix (see ``find_exceptional_points``) at
+    coupling ``g``. Diverges approaching a genuine exceptional point
+    (eigenvectors becoming parallel, the matrix approaching a Jordan
+    block there) -- unlike an ordinary level crossing, where eigenvectors
+    stay well-conditioned. The confirmatory structural check that
+    distinguishes an exceptional point from an incidental crossing.
+
+    Parameters
+    ----------
+    p, q : int
+    beta : int
+    seed : int
+    g : float
+
+    Returns
+    -------
+    float
+    """
+    h = _fixed_realization_matrix(p, q, beta, seed, g)
+    _, eigenvectors = np.linalg.eig(h)
+    return float(np.linalg.cond(eigenvectors))

physicskit/rmt/stats/ratios.py

@@ -0,0 +1,110 @@
+"""Consecutive-spacing ratio statistic (Oganesyan & Huse, Phys. Rev. B 75,
+155111, 2007) and its closed-form surmise (Atas, Bogomolny, Giraud & Roux,
+Phys. Rev. Lett. 110, 084101, 2013).
+
+The ratio statistic::
+
+    r_n = min(s_n, s_{n-1}) / max(s_n, s_{n-1})   in [0, 1]
+
+where s_n = x_{n+1} - x_n are consecutive *raw* spacings, is invariant
+under any smooth local rescaling of the eigenvalues -- unlike the spacing
+distribution P(s), it requires no unfolding. That makes it a genuinely
+independent validation of the same underlying level-repulsion physics: if
+both the (unfolding-dependent) spacing distribution and the
+(unfolding-free) ratio distribution agree with their respective surmises,
+unfolding artifacts can be ruled out as the source of agreement.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.integrate import cumulative_trapezoid
+from scipy.interpolate import interp1d
+
+from ..spectrum import Spectrum
+
+
+def ratio_statistics(spectrum: Spectrum, edge_trim: float = 0.1) -> np.ndarray:
+    """Pooled ratio statistics from every sample in a Spectrum, computed
+    directly on raw eigenvalues (rescaling is irrelevant to a ratio, but
+    ``spectrum.rescaled`` is used for consistency with the rest of the
+    package).
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+    edge_trim : float
+        Fraction of eigenvalues discarded from each edge before taking
+        spacings, for the same reason as in ``nearest_neighbor_spacings``.
+        No unfolding is involved, so trim order doesn't matter here.
+
+    Returns
+    -------
+    numpy.ndarray
+        Pooled ratio statistics, each in [0, 1].
+    """
+    all_ratios = []
+    for row in spectrum.rescaled:
+        n = len(row)
+        lo = int(edge_trim * n)
+        hi = n - lo
+        if hi - lo < 3:
+            continue
+        s = np.diff(row[lo:hi])
+        r = np.minimum(s[:-1], s[1:]) / np.maximum(s[:-1], s[1:])
+        all_ratios.append(r)
+    return np.concatenate(all_ratios)
+
+
+def _ratio_surmise_unnormalized_pdf(r: np.ndarray, beta: float) -> np.ndarray:
+    r = np.asarray(r, dtype=float)
+    return (r + r**2) ** beta / (1.0 + r + r**2) ** (1.0 + 1.5 * beta)
+
+
+class RatioSurmise:
+    """The Atas et al. (2013) surmise for the ratio statistic, restricted
+    to r in [0, 1] (the min/max-normalized convention used by
+    ``ratio_statistics`` above).
+
+    The normalizing constant and CDF have no simple closed form, so both
+    are built once per beta via a fine-grid cumulative trapezoidal
+    integration and cached as interpolators -- this is far cheaper than
+    calling ``scipy.integrate.quad`` per evaluation point, which matters
+    since a KS test evaluates the CDF at every data point.
+    """
+
+    def __init__(self, beta: float, grid_size: int = 4000) -> None:
+        """
+        Note on accuracy: this surmise is exact for a reduced (3-level)
+        model, not for the true N-level ensemble -- analogous to how the
+        classical Wigner surmise is exact for a 2x2 matrix but only an
+        excellent approximation at general N. Its own exact mean at
+        beta=1 is 4 - 2*sqrt(3) ~= 0.5359 (verified numerically against
+        this implementation), which is measurably different from the
+        numerically-exact full-GOE mean ratio (~0.5307) reported
+        elsewhere in the literature -- both numbers are correct, they
+        just answer different questions (surmise vs. true ensemble).
+        """
+        self.beta = beta
+        grid = np.linspace(0.0, 1.0, grid_size)
+        pdf_unnorm = _ratio_surmise_unnormalized_pdf(grid, beta)
+        cdf_unnorm = cumulative_trapezoid(pdf_unnorm, grid, initial=0.0)
+        self._normalization = cdf_unnorm[-1]
+        cdf = cdf_unnorm / self._normalization
+        self._cdf_interp = interp1d(grid, cdf, bounds_error=False, fill_value=(0.0, 1.0))
+        # For sampling: invert the CDF via interpolation the other way.
+        # cdf is monotonically increasing, so this is well-defined.
+        self._inv_cdf_interp = interp1d(cdf, grid, bounds_error=False, fill_value=(0.0, 1.0))
+        self._pdf_grid = grid
+        self._pdf_unnorm = pdf_unnorm
+
+    def pdf(self, r: np.ndarray) -> np.ndarray:
+        r = np.asarray(r, dtype=float)
+        return np.interp(np.clip(r, 0.0, 1.0), self._pdf_grid, self._pdf_unnorm) / self._normalization
+
+    def cdf(self, r: np.ndarray) -> np.ndarray:
+        return self._cdf_interp(r)
+
+    def rvs(self, size: int | tuple[int, ...], rng: np.random.Generator) -> np.ndarray:
+        u = rng.uniform(0.0, 1.0, size=size)
+        return self._inv_cdf_interp(u)

physicskit/rmt/stats/real_ginibre.py

@@ -0,0 +1,134 @@
+"""The real-Ginibre real-eigenvalue-count anomaly: a real Ginibre matrix
+(GinOE) has a mix of purely real eigenvalues and complex-conjugate
+pairs, with the expected number of real eigenvalues growing like
+sqrt(n) -- a celebrated result with no Hermitian-ensemble analogue (see
+``physicskit.rmt.ensembles.ginibre`` module docstring).
+
+Reference: A. Edelman, E. Kostlan, S. Shub, "How many eigenvalues of a
+random matrix are real?", J. Amer. Math. Soc. 7 (1994) 247.
+
+Precision note: Edelman-Kostlan-Shub's finite-n result is an exact
+closed form built from the real-Ginibre skew-orthogonal Hermite-
+polynomial kernel -- machinery not otherwise needed anywhere else in
+this package, and which this implementation does not reproduce. What IS
+implemented and verified here is the large-n asymptotic expansion
+
+    E[N_real](n) ~ sqrt(2*n/pi) + 1/2 + O(1/sqrt(n))
+
+The leading sqrt(2n/pi) term is the well-known leading-order asymptotic
+already noted in ``physicskit.rmt.ensembles.ginibre``; the +1/2 correction was
+fit against, and confirmed by, direct Monte Carlo real-eigenvalue
+counts on ``GinOE`` at n = 2, 4, ..., 128 during development (residual
+E[N_real] - sqrt(2n/pi) plateaus near 0.5, consistent with this
+correction, rather than assumed from memory) -- see
+``tests/test_real_ginibre.py``. This is therefore an asymptotic
+formula, not the exact EKS closed form, and is documented as such:
+expect several-percent-level disagreement at small n (n well below 30),
+narrowing as n grows.
+"""
+
+import numpy as np
+
+
+def real_eigenvalue_count_empirical(eigenvalues: np.ndarray, tol: float = 1e-8) -> np.ndarray:
+    """Count (near-)real eigenvalues per sample.
+
+    Parameters
+    ----------
+    eigenvalues : numpy.ndarray, shape (n_samples, n), complex
+        Raw complex eigenvalues, e.g. ``GinOE`` ``Spectrum.eigenvalues``.
+    tol : float, optional
+        An eigenvalue counts as real if ``abs(Im(lambda))`` is below
+        this (accounts for floating-point residue from
+        ``numpy.linalg.eigvals`` on an exactly-real matrix).
+
+    Returns
+    -------
+    numpy.ndarray, shape (n_samples,)
+        Integer count of real eigenvalues in each sample.
+    """
+    eigenvalues = np.asarray(eigenvalues)
+    return np.sum(np.abs(eigenvalues.imag) < tol, axis=-1)
+
+
+def real_eigenvalue_count_asymptotic(n: int) -> float:
+    """Large-n asymptotic expected number of real eigenvalues of an
+    n x n real Ginibre (GinOE) matrix: sqrt(2*n/pi) + 1/2.
+
+    See module docstring for precision caveats (asymptotic, not the
+    exact Edelman-Kostlan-Shub 1994 finite-n closed form).
+
+    Parameters
+    ----------
+    n : int
+
+    Returns
+    -------
+    float
+    """
+    return np.sqrt(2.0 * n / np.pi) + 0.5
+
+
+def real_eigenvalue_density_empirical(eigenvalues: np.ndarray, n: int, bins: int = 60, x_max: float = 1.2) -> tuple[np.ndarray, np.ndarray]:
+    """Empirical density of real eigenvalue positions (rescaled by
+    ``sqrt(n)``, matching ``GinOE.natural_scale``): expected number of
+    real eigenvalues per unit x per sample, histogrammed over the
+    (near-)real eigenvalues pooled across all samples.
+
+    Parameters
+    ----------
+    eigenvalues : numpy.ndarray, shape (n_samples, n), complex
+        Raw (unrescaled) ``GinOE`` eigenvalues.
+    n : int
+        Matrix dimension (for the sqrt(n) rescaling).
+    bins : int, optional
+    x_max : float, optional
+        Histogram range is ``[-x_max, x_max]``.
+
+    Returns
+    -------
+    centers, density : numpy.ndarray
+    """
+    eigenvalues = np.asarray(eigenvalues)
+    n_samples = eigenvalues.shape[0]
+    real_values = eigenvalues.real[np.abs(eigenvalues.imag) < 1e-8] / np.sqrt(n)
+    edges = np.linspace(-x_max, x_max, bins + 1)
+    counts, _ = np.histogram(real_values, bins=edges)
+    bin_width = edges[1] - edges[0]
+    centers = 0.5 * (edges[:-1] + edges[1:])
+    density = counts / (n_samples * bin_width)
+    return centers, density
+
+
+def real_eigenvalue_density_asymptotic(x: np.ndarray, n: int) -> np.ndarray:
+    """Large-n asymptotic expected density of real eigenvalue positions
+    (rescaled by sqrt(n)): uniform on (-1, 1) at height
+    ``real_eigenvalue_count_asymptotic(n) / 2`` (i.e. the total expected
+    real-eigenvalue count spread evenly over the rescaled real-axis
+    support), zero outside.
+
+    Verified numerically during development (not assumed): pooled,
+    rescaled real eigenvalues from direct Monte Carlo GinOE samples show
+    a flat bulk histogram (no visible x-dependence within statistical
+    noise) with a clean cutoff at |x|=1 matching the circular law's disk
+    radius, rather than any elevated edge density or bulk curvature --
+    see ``tests/test_real_ginibre.py``. Like
+    ``real_eigenvalue_count_asymptotic``, this is a verified large-n
+    asymptotic description, not the exact finite-n
+    Edelman-Kostlan-Shub density (which has additional fine structure,
+    e.g. a smooth rather than sharp edge, not captured here).
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    n : int
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    x = np.asarray(x, dtype=float)
+    height = real_eigenvalue_count_asymptotic(n) / 2.0
+    out = np.zeros_like(x)
+    out[np.abs(x) <= 1.0] = height
+    return out