physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/ensembles/graph_laplacian.py

@@ -0,0 +1,92 @@
+"""Random graph Laplacians -- spectral graph theory / network transport
+ensembles, built on an Erdos-Renyi G(n, p) random graph.
+
+References
+----------
+F. R. K. Chung, "Spectral Graph Theory", CBMS Regional Conference
+Series in Mathematics 92, AMS, 1997 -- normalized Laplacian eigenvalues
+lie in [0, 2] for any graph, with 2 attained iff a connected component
+is bipartite (used below as ``natural_scale`` for the normalized case).
+F. Chung, L. Lu, V. Vu, "Spectra of random graphs with given expected
+degrees", Proc. Natl. Acad. Sci. 100 (2003) 6313 -- Erdos-Renyi Laplacian
+spectral asymptotics.
+
+Construction: an n x n symmetric 0/1 adjacency matrix A with i.i.d.
+Bernoulli(p) entries above the diagonal (zero diagonal -- no self-loops),
+mirrored below. Two Laplacian variants:
+
+    combinatorial: L = D - A            (D = diag(degree))
+    normalized:    L_sym = I - D^(-1/2) A D^(-1/2)
+
+Isolated vertices (degree 0, possible whenever p is small enough) are
+handled by convention: an isolated vertex contributes an exact zero row/
+column to A, hence an exact zero eigenvalue to L trivially, and is
+assigned D^(-1/2) = 0 for that vertex in L_sym (rather than raising a
+division error) -- the standard spectral-graph-theory convention,
+matching how an isolated vertex trivially decouples from graph
+transport dynamics either way.
+
+Unlike the semicircle/Marchenko-Pastur ensembles, the COMBINATORIAL
+Laplacian's spectrum is not naturally centered at 0 (it concentrates
+around the mean degree n*p for large n*p, since L = D - A and D
+concentrates around n*p -- Chung-Lu-Vu), so ``natural_scale`` performs
+no rescaling for that case (dividing by a single scalar cannot both
+correctly center and rescale it); the NORMALIZED Laplacian, by contrast,
+has an exact, graph-independent bound (eigenvalues in [0, 2]), so no
+rescaling is needed there either, for the opposite reason.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+def _erdos_renyi_adjacency(n: int, p: float, rng: np.random.Generator) -> np.ndarray:
+    upper = np.triu(rng.random((n, n)) < p, k=1)
+    return upper.astype(float) + upper.T.astype(float)
+
+
+class GraphLaplacianEnsemble(MatrixEnsemble):
+    """Laplacian eigenvalues of an Erdos-Renyi G(n, p) random graph.
+
+    Parameters
+    ----------
+    n : int
+        Number of vertices.
+    p : float
+        Edge probability, in (0, 1].
+    normalized : bool, optional
+        If True (default False), use the normalized Laplacian
+        I - D^(-1/2) A D^(-1/2) (eigenvalues in [0, 2]) instead of the
+        combinatorial Laplacian D - A.
+    """
+
+    def __init__(
+        self,
+        n: int,
+        p: float,
+        normalized: bool = False,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if not 0.0 < p <= 1.0:
+            raise ValueError(f"p must be in (0, 1], got {p}")
+        super().__init__(n, seed=seed)
+        self.p = float(p)
+        self.normalized = normalized
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        a = _erdos_renyi_adjacency(self.n, self.p, rng)
+        degree = a.sum(axis=1)
+        if self.normalized:
+            with np.errstate(divide="ignore"):
+                d_inv_sqrt = np.where(degree > 0, 1.0 / np.sqrt(degree), 0.0)
+            laplacian = np.eye(self.n) - (d_inv_sqrt[:, None] * a) * d_inv_sqrt[None, :]
+        else:
+            laplacian = np.diag(degree) - a
+        laplacian = (laplacian + laplacian.T) / 2.0
+        return np.linalg.eigvalsh(laplacian)
+
+    def natural_scale(self) -> float:
+        return 1.0

physicskit/rmt/ensembles/haar.py

@@ -0,0 +1,57 @@
+"""Eigenvalue statistics of a raw Haar-random orthogonal matrix --
+deliberately distinct from the Circular Orthogonal Ensemble.
+
+Reference: F. Mezzadri, "How to generate random matrices from the
+classical compact groups", Notices Amer. Math. Soc. 54 (2007) 592.
+
+As already flagged in ``physicskit.rmt.ensembles.circular``'s module docstring:
+COE is NOT "eigenvalues of a Haar-random orthogonal matrix" -- a real
+orthogonal matrix's eigenvalues are either real (+-1) or complex-
+conjugate pairs on the unit circle, not the generic uniform-phase
+structure a circular ensemble requires. This module provides that
+other, genuinely different object directly, rather than leaving it as
+only a cautionary note: the raw-matrix generators themselves
+(``haar_orthogonal``, ``haar_unitary``, ``haar_symplectic``) live in
+``physicskit.rmt.utils.haar``, since what they return is the group element
+itself (useful directly as a random quantum gate / change of basis for
+circuit-simulation and randomized-benchmarking use cases) rather than
+an eigenvalue-only product -- the one architectural mismatch with every
+other ensemble in this package, whose ``.sample()`` is built around
+eigenvalues as the primary product (see ``physicskit.rmt.ensembles.base``).
+``HaarUnitary``'s and ``HaarSymplectic``'s eigenvalue-phase statistics
+are, respectively, already exactly what CUE and CSE model (see
+``physicskit.rmt.ensembles.circular``), so no separate ensemble classes are
+added here for those -- only the genuinely new, non-duplicate
+Haar-orthogonal eigenvalue ensemble below.
+
+Verified during development (see ``tests/test_haar.py``): unlike CUE
+(zero real eigenvalues, generically) and COE (also generically no real
+eigenvalues -- see ``physicskit.rmt.ensembles.circular``), a raw Haar-O(n)
+matrix has a genuinely nonzero real-eigenvalue count whose expectation
+stays O(1) (order unity, empirically close to 1) rather than vanishing
+or growing, as n increases -- structurally distinct from both the
+circular-ensemble and the GinOE real-eigenvalue-count stories (the
+latter grows like sqrt(2n/pi), Edelman-Kostlan-Shub 1994).
+"""
+
+import numpy as np
+
+from ..utils.haar import haar_orthogonal
+from .base import MatrixEnsemble
+
+
+class HaarOrthogonalEnsemble(MatrixEnsemble):
+    """Eigenvalues of a raw n x n Haar-random orthogonal matrix (O(n)).
+
+    ``Spectrum.eigenvalues`` holds n complex values per sample (a mix of
+    real +-1 eigenvalues and complex-conjugate pairs on the unit
+    circle) -- see module docstring for why this is a distinct object
+    from :class:`~physicskit.rmt.ensembles.circular.COE`.
+    """
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        o = haar_orthogonal(self.n, rng)
+        return np.linalg.eigvals(o)
+
+    def natural_scale(self) -> float:
+        return 1.0

physicskit/rmt/ensembles/jacobi.py

@@ -0,0 +1,182 @@
+"""Jacobi (MANOVA) ensembles -- JOE (beta=1), JUE (beta=2).
+
+References
+----------
+K. W. Wachter, "The limiting empirical measure of multiple discriminant
+ratios", Ann. Statist. 8 (1980) 937 -- the limiting law (see
+``physicskit.rmt.stats.wachter``).
+L. Erdos, B. Farrell, "Local Eigenvalue Density for General MANOVA
+Matrices" (arXiv:1207.0031) -- the construction and formula used here,
+verified numerically during development (see design notes and
+``tests/test_jacobi_wachter.py``).
+
+Construction: given two independent Wishart-type matrices A, B (n x n,
+built from m1 and m2 "samples" respectively, m1, m2 >= n), the Jacobi
+ensemble matrix is
+
+    J = A (A + B)^{-1}
+
+Unlike Gaussian/Wishart, this requires the actual dense matrices A and B
+(not just their eigenvalues), since the ratio construction mixes them --
+none of the tridiagonal/bidiagonal eigenvalue-only tricks used elsewhere
+in this package apply here. J itself is generally NOT symmetric, but is
+similar to the manifestly symmetric matrix
+
+    M = (A+B)^{-1/2} A (A+B)^{-1/2}
+
+(via conjugation by (A+B)^{1/2}), which has the same eigenvalues and is
+what's actually diagonalized here for numerical stability. Eigenvalues
+are real and confined to [0, 1] (a "double hard edge", unlike the
+semicircle/Marchenko-Pastur soft edges).
+
+Parametrization: following Erdos-Farrell/Wachter, a = m1/n, b = m2/n
+(inverse aspect ratios, i.e. "samples per variable" -- note this is the
+reciprocal of the gamma = n/m convention used in
+``physicskit.rmt.ensembles.wishart``).
+
+beta=4 (quaternion, "JSE"): A and B are built from n x m quaternion
+matrices, embedded as 2n x 2m complex matrices via the standard
+quaternion-to-2x2-complex-block map (the same convention as
+``physicskit.rmt.ensembles.ginibre.GinSE`` and
+``physicskit.rmt.ensembles.effective_hamiltonian``'s beta=4 case). Since that
+embedding is an algebra homomorphism, A, B, S = A+B, and
+M = S^{-1/2} A S^{-1/2} are all quaternionic self-dual Hermitian, so M's
+2n eigenvalues come in exact Kramers double-degenerate pairs -- verified
+numerically during development to machine precision (~1e-15) before
+being trusted here, the same true degeneracy GSE/CSE/EffGSE have (as
+opposed to GinSE's merely-conjugate, genuinely distinct pairs). Only the
+n distinct values are returned (one representative per pair), mirroring
+those other beta=4 ensembles.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+def _dense_wishart(n: int, m: int, rng: np.random.Generator, complex_entries: bool) -> np.ndarray:
+    if complex_entries:
+        x = (rng.standard_normal((n, m)) + 1j * rng.standard_normal((n, m))) / np.sqrt(2.0)
+    else:
+        x = rng.standard_normal((n, m))
+    return x @ x.conj().T
+
+
+def _quaternion_gaussian_block(n: int, m: int, rng: np.random.Generator) -> np.ndarray:
+    """N x M quaternion matrix, embedded as a 2N x 2M complex matrix
+    (same convention as ``physicskit.rmt.ensembles.ginibre.GinSE``)."""
+    a = rng.standard_normal((n, m))
+    b = rng.standard_normal((n, m))
+    c = rng.standard_normal((n, m))
+    d = rng.standard_normal((n, m))
+    w = np.zeros((2 * n, 2 * m), dtype=complex)
+    w[0::2, 0::2] = a + 1j * b
+    w[0::2, 1::2] = c + 1j * d
+    w[1::2, 0::2] = -c + 1j * d
+    w[1::2, 1::2] = a - 1j * b
+    return w / np.sqrt(2.0)
+
+
+def _dense_quaternion_wishart(n: int, m: int, rng: np.random.Generator) -> np.ndarray:
+    x = _quaternion_gaussian_block(n, m, rng)
+    return x @ x.conj().T
+
+
+class JacobiBetaEnsemble(MatrixEnsemble):
+    """General (beta=1, 2, or 4) Jacobi/MANOVA ensemble.
+
+    ``n`` is the ensemble/matrix size (per the ``MatrixEnsemble`` base
+    class, matching the other ensembles' convention -- for beta=4 this
+    is the number of *distinct* eigenvalues, per the module docstring);
+    ``m1``, ``m2`` are the two Wishart "sample sizes" (each must be >= n).
+    """
+
+    def __init__(
+        self,
+        n: int,
+        m1: int,
+        m2: int,
+        beta: int,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        n : int
+            Number of variables (matrix dimension).
+        m1 : int
+            Sample size of the first Wishart-type matrix; must be >= n.
+        m2 : int
+            Sample size of the second Wishart-type matrix; must be >= n.
+        beta : int
+            Dyson index; must be 1, 2, or 4.
+        seed : int, numpy.random.Generator, or None, optional
+        """
+        if beta not in (1, 2, 4):
+            raise ValueError(f"JacobiBetaEnsemble only supports beta in (1, 2, 4), got {beta}")
+        if m1 < n or m2 < n:
+            raise ValueError(f"m1 (samples={m1}) and m2 (samples={m2}) must both be >= n (variables={n})")
+        super().__init__(n, seed=seed)
+        self.m1 = m1
+        self.m2 = m2
+        self.beta: float = beta
+
+    @property
+    def a(self) -> float:
+        """Inverse aspect ratio m1/n (Erdos-Farrell/Wachter parametrization)."""
+        return self.m1 / self.n
+
+    @property
+    def b(self) -> float:
+        """Inverse aspect ratio m2/n."""
+        return self.m2 / self.n
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        if self.beta == 4:
+            mat_a = _dense_quaternion_wishart(self.n, self.m1, rng)
+            mat_b = _dense_quaternion_wishart(self.n, self.m2, rng)
+        else:
+            complex_entries = self.beta == 2
+            mat_a = _dense_wishart(self.n, self.m1, rng, complex_entries)
+            mat_b = _dense_wishart(self.n, self.m2, rng, complex_entries)
+        s = mat_a + mat_b
+        w, v = np.linalg.eigh(s)
+        s_inv_sqrt = (v * (1.0 / np.sqrt(w))) @ v.conj().T
+        m = s_inv_sqrt @ mat_a @ s_inv_sqrt
+        m = (m + m.conj().T) / 2.0  # symmetrize away numerical asymmetry
+        eigenvalues = np.linalg.eigvalsh(m)
+        if self.beta == 4:
+            # Exact Kramers double degeneracy (see module docstring) --
+            # keep one representative per pair, as GSE/CSE/EffGSE do.
+            eigenvalues = np.sort(eigenvalues)[0::2]
+        return eigenvalues
+
+    def natural_scale(self) -> float:
+        # Eigenvalues already live in the natural [0, 1] range; no rescaling.
+        return 1.0
+
+
+class JOE(JacobiBetaEnsemble):
+    """Jacobi Orthogonal Ensemble (beta=1): real double-Wishart ratio."""
+
+    def __init__(self, n: int, m1: int, m2: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m1, m2, beta=1, seed=seed)
+
+
+class JUE(JacobiBetaEnsemble):
+    """Jacobi Unitary Ensemble (beta=2): complex double-Wishart ratio."""
+
+    def __init__(self, n: int, m1: int, m2: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m1, m2, beta=2, seed=seed)
+
+
+class JSE(JacobiBetaEnsemble):
+    """Jacobi Symplectic Ensemble (beta=4): quaternionic double-Wishart
+    ratio. ``n`` is the quaternionic dimension; each sample produces n
+    distinct eigenvalues (each an exact Kramers pair internally -- see
+    module docstring)."""
+
+    def __init__(self, n: int, m1: int, m2: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m1, m2, beta=4, seed=seed)

physicskit/rmt/ensembles/poisson.py

@@ -0,0 +1,77 @@
+"""Poisson ensemble -- the integrable-system null model (Berry-Tabor
+conjecture).
+
+Reference
+---------
+M. V. Berry, M. Tabor, "Level clustering in the regular spectrum",
+Proc. R. Soc. Lond. A 356 (1977) 375 -- the semiclassical argument that
+quantized energy levels of a (generic) classically INTEGRABLE system are,
+locally, statistically indistinguishable from an uncorrelated Poisson
+point process, in sharp contrast to the level REPULSION seen in
+GOE/GUE/GSE for classically CHAOTIC systems (the complementary
+Bohigas-Giannoni-Schmit conjecture, Phys. Rev. Lett. 52 (1984) 1).
+
+This is not a matrix ensemble in the sense every other class in this
+package is -- there is no underlying random matrix, Dyson index, or
+symmetry class here. It is the standard baseline/null model that RMT
+level statistics (spacing distribution, ratio statistic, number
+variance) are always contrasted against; see
+``physicskit.rmt.stats.rigidity.number_variance_poisson``, which until this
+ensemble existed had no matching sampler in this package to validate it
+against empirically (see ``tests/test_poisson.py``).
+
+Construction: n levels are generated as the partial sums of n i.i.d.
+Exponential(1) spacings -- i.e. a single realization of a homogeneous
+Poisson point process of UNIT RATE on the positive real line. This is
+deliberately NOT "n i.i.d. Uniform(0, n) points" (a common shortcut):
+that construction only approaches Poisson-process statistics
+asymptotically in the bulk (finite-interval edge effects bias it at
+finite n), whereas partial sums of i.i.d. Exponential(1) spacings give
+EXACTLY unit-rate Poisson-process statistics at every n -- consecutive
+spacings are exactly i.i.d. Exponential(1) by construction, not merely
+on average.
+
+Because the process has constant unit rate everywhere (translation
+invariant), it needs no unfolding: unlike GOE/Wishart's compact,
+nontrivially-shaped limiting density (which spacing/rigidity statistics
+must first divide out via a CDF -- see ``physicskit.rmt.stats.unfolding``), the
+levels sampled here already have exactly unit mean spacing throughout --
+the same "no separate unfolding step needed" situation as the circular
+ensembles (``physicskit.rmt.ensembles.circular``), though for the opposite
+reason (uniform density on an unbounded line here, vs. exact rotational
+invariance on a compact circle there).
+
+``beta`` is left ``None`` (inherited from the base class): Poisson
+statistics are not part of Dyson's threefold way at all -- they are the
+uncorrelated baseline every beta-ensemble's level repulsion is
+contrasted against, NOT a beta -> 0 limit of the Gaussian-tailed Wigner-
+surmise family used for GOE/GUE/GSE. That limit is a half-Gaussian
+(Rayleigh-shaped) distribution, not the exponential spacing law of a
+true Poisson process -- worth knowing if you're tempted to reuse
+``physicskit.rmt.validation.WignerSurmise(beta=0)`` or
+``physicskit.rmt.validation.RatioDistribution(beta=0)`` here; both would
+silently validate against the wrong theoretical curve. The exact
+Poisson-process laws instead are: spacing PDF exp(-s) (``scipy.stats.expon``);
+and, for the min/max-normalized ratio statistic r in [0, 1] used by
+``physicskit.rmt.stats.ratios.ratio_statistics``, PDF 2/(1+r)**2, CDF 2r/(1+r)
+-- derived directly here (not taken from a remembered formula) from the
+ratio of two i.i.d. Exponential(1) variables, and checked numerically in
+the test suite.
+"""
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+class PoissonEnsemble(MatrixEnsemble):
+    """n "energy levels" of an integrable system's Berry-Tabor null
+    model: a unit-rate homogeneous Poisson point process, realized as
+    the partial sums of n i.i.d. Exponential(1) spacings.
+    """
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        return np.cumsum(rng.exponential(scale=1.0, size=self.n))
+
+    def natural_scale(self) -> float:
+        return 1.0

physicskit/rmt/ensembles/polynomial.py

@@ -0,0 +1,139 @@
+"""Polynomial ensembles -- squared singular values of a product of
+independent Ginibre matrices; a genuine BIORTHOGONAL ensemble (Borodin's
+general determinantal framework) whenever more than one factor is used.
+
+References
+----------
+A. B. J. Kuijlaars, D. Stivigny, "Singular values of products of random
+matrices and polynomial ensembles", Random Matrices Theory Appl. 3
+(2014) 1450011 -- the "polynomial ensemble" terminology, and the theorem
+that products of Ginibre matrices realize one, with explicit
+Meijer-G-function biorthogonal weight functions.
+A. Borodin, "Biorthogonal ensembles", Nucl. Phys. B 536 (1998) 704 --
+the general determinantal framework: joint density
+prod_{i<j}(x_i-x_j) * det[phi_k(x_j)] * det[psi_k(x_j)], of which the
+classical orthogonal-polynomial ensembles (a single factor, L=1 below)
+are the special case phi_k = psi_k (true orthogonal polynomials).
+E. Strahov, "Differential equations for singular values of products of
+Ginibre random matrices", J. Phys. A 47 (2014) 325203 -- the explicit
+non-orthogonal-polynomial biorthogonal kernel for L >= 2, confirming
+that construction is NOT reducible to a classical orthogonal-polynomial
+ensemble.
+G. Akemann, J. R. Ipsen, M. Kieburg, "Products of rectangular random
+matrices: singular values and progressive scattering", Phys. Rev. E 88
+(2013) 052118.
+K. A. Penson, K. Zyczkowski, "Product of Ginibre matrices: Fuss-Catalan
+and Raney distributions", Phys. Rev. E 83 (2011) 061118 -- the
+Fuss-Catalan limiting law and moment formula used for validation here.
+
+Construction
+------------
+X = X_1 @ X_2 @ ... @ X_L, each X_k an independent n x n Ginibre matrix
+(real, beta=1, or complex, beta=2). This ensemble's eigenvalues are the
+squared singular values of X, i.e. the eigenvalues of X^dagger @ X.
+
+L=1 recovers the classical Wishart/Laguerre ensemble EXACTLY (a genuine
+orthogonal-polynomial ensemble, phi_k=psi_k in Borodin's framework) --
+used as a strong validation anchor in the test suite (a direct match
+against the already-validated ``LaguerreBetaEnsemble``/
+``MarchenkoPastur`` machinery), not a separate approximation.
+
+L >= 2 is a GENUINE biorthogonal ensemble: Kuijlaars-Stivigny prove the
+joint eigenvalue density still has the determinantal
+Delta(x) * det[phi_k(x_j)] * det[psi_k(x_j)] form (making it a
+"polynomial ensemble"), but Strahov shows the correlation kernel is
+provably NOT the reproducing kernel of any single family of orthogonal
+polynomials once L >= 2 -- phi_k and psi_k are then genuinely different
+function families (built from Meijer G-functions), the defining feature
+that distinguishes a biorthogonal ensemble from the classical
+orthogonal-polynomial ensembles making up most of the rest of this
+package. ``num_factors`` therefore defaults to 2 here, not 1, so the
+default instance actually exhibits this genuine biorthogonal structure
+rather than silently reducing to the classical case.
+
+After the standard n**L rescaling, the limiting eigenvalue distribution
+is the Fuss-Catalan law with parameter L (Penson-Zyczkowski 2011):
+support [0, (L+1)**(L+1) / L**L] and exact moments
+
+    m_k = binom((L+1)*k, k) / (L*k + 1)
+
+(L=1 recovers the Marchenko-Pastur moments at gamma=1, i.e. the Catalan
+numbers, as it must). ``natural_scale`` divides by this n**L factor
+accordingly -- both the scaling exponent and the exact moment formula
+were verified numerically during development, at L=1..4, against Monte
+Carlo before being used here (not assumed from memory) -- see
+``tests/test_polynomial.py``.
+
+Only beta in {1, 2} are supported here (real or complex Ginibre
+factors), matching the precedent set by
+``physicskit.rmt.ensembles.universality.GeneralWignerEnsemble``: a quaternionic
+(beta=4) product-of-Ginibre construction is a further, separate
+extension not implemented here.
+"""
+
+from __future__ import annotations
+
+from math import comb
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+def fuss_catalan_moment(k: int, num_factors: int) -> float:
+    """Exact k-th moment of the Fuss-Catalan(L) distribution -- the
+    limiting law of a product of L independent square Ginibre matrices'
+    squared singular values, after the n**L rescaling.
+
+    m_k = binom((L+1)*k, k) / (L*k + 1). L=1 recovers the standard
+    Marchenko-Pastur moments at gamma=1 (Catalan numbers).
+    """
+    return comb((num_factors + 1) * k, k) / (num_factors * k + 1)
+
+
+class PolynomialEnsemble(MatrixEnsemble):
+    """Squared singular values of a product of ``num_factors`` independent
+    n x n Ginibre matrices -- a polynomial/biorthogonal ensemble (see
+    module docstring).
+
+    Parameters
+    ----------
+    n : int
+    num_factors : int, optional
+        Number of independent Ginibre factors L (default 2, the
+        smallest case exhibiting genuine biorthogonal, non-orthogonal-
+        polynomial structure; L=1 recovers the classical Wishart/
+        Laguerre ensemble exactly).
+    beta : int, optional
+        1 (real Ginibre factors) or 2 (complex Ginibre factors).
+    """
+
+    def __init__(
+        self,
+        n: int,
+        num_factors: int = 2,
+        beta: int = 2,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if num_factors < 1:
+            raise ValueError(f"num_factors must be >= 1, got {num_factors}")
+        if beta not in (1, 2):
+            raise ValueError(f"beta must be 1 or 2, got {beta}")
+        super().__init__(n, seed=seed)
+        self.num_factors = num_factors
+        self.beta: float = beta
+
+    def _sample_factor(self, rng: np.random.Generator) -> np.ndarray:
+        n = self.n
+        if self.beta == 1:
+            return rng.standard_normal((n, n))
+        return (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        x = self._sample_factor(rng)
+        for _ in range(self.num_factors - 1):
+            x = x @ self._sample_factor(rng)
+        return np.linalg.eigvalsh(x.conj().T @ x)
+
+    def natural_scale(self) -> float:
+        return float(self.n) ** self.num_factors

physicskit/rmt/ensembles/pt_symmetric.py

@@ -0,0 +1,120 @@
+"""PT-symmetric (pseudo-Hermitian) random matrix ensembles.
+
+References
+----------
+C. M. Bender, S. Boettcher, "Real Spectra in Non-Hermitian Hamiltonians
+Having PT Symmetry", Phys. Rev. Lett. 80 (1998) 5243 -- the original
+PT-symmetric-quantum-mechanics observation this construction realizes
+as a random matrix model.
+A. Mostafazadeh, "Pseudo-Hermiticity versus PT-symmetry", J. Math. Phys.
+43 (2002) 205, 2814, 3944 -- the equivalence (for a diagonalizable H
+with real spectrum) between PT-symmetry and pseudo-Hermiticity
+P H P^{-1} = H^dagger for some Hermitian, invertible P, which is the
+concrete condition realized here (P chosen as a fixed, real, diagonal
++-1 "signature" matrix, so P = P^dagger = P^{-1}).
+
+Construction: partition the n = p + q dimensions into a "+1" block
+(size p) and a "-1" block (size q), P = diag(I_p, -I_q). Writing H in
+the matching 2x2 block form,
+
+    H = [[A, B], [C, D]]
+
+the pseudo-Hermiticity condition P H P = H^dagger forces A = A^dagger
+(p x p Hermitian), D = D^dagger (q x q Hermitian), and C = -B^dagger
+(NOT the +B^dagger a genuinely Hermitian H would need) -- verified
+numerically here (``max|PHP - H^dagger|`` to machine precision) before
+being trusted. A, D are drawn as independent GOE/GUE-type Hermitian
+blocks; B is an independent p x q Ginibre-type block scaled by a
+non-Hermiticity/coupling parameter ``g``.
+
+Physics (verified numerically during development, see
+``tests/test_pt_symmetric.py``): at g=0, H is block-diagonal (A
+directly summed with D), so its spectrum is trivially real (each block
+is Hermitian) -- the fully "unbroken" PT-symmetric phase. Since H is
+similar to H^dagger (via the invertible P), its eigenvalue set is
+always closed under complex conjugation: every eigenvalue is either
+real or part of an exact complex-conjugate pair -- never an isolated
+complex value. As g increases from 0, an increasing fraction of
+eigenvalues collide in real-conjugate pairs and move off the real axis
+as complex-conjugate pairs (each such collision is an "exceptional
+point": both the eigenvalues AND their eigenvectors coalesce there,
+unlike an ordinary level crossing) -- the celebrated PT-symmetry-
+breaking transition. See ``physicskit.rmt.stats.pt_symmetric`` for the fraction-
+of-real-eigenvalues statistic that tracks this transition.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+def _dense_hermitian_block(n: int, rng: np.random.Generator, complex_entries: bool) -> np.ndarray:
+    if complex_entries:
+        x = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+        return (x + x.conj().T) / 2.0
+    x = rng.standard_normal((n, n))
+    return (x + x.T) / np.sqrt(2.0)
+
+
+class PTSymmetricEnsemble(MatrixEnsemble):
+    """Pseudo-Hermitian (PT-symmetric-realizing) random matrix ensemble
+    (see module docstring). ``n`` (inherited from ``MatrixEnsemble``) is
+    the total dimension p + q.
+
+    Parameters
+    ----------
+    p : int
+        Size of the "+1"-signature block.
+    q : int
+        Size of the "-1"-signature block.
+    g : float
+        Non-Hermiticity / coupling strength scaling the off-diagonal
+        block B (g=0: block-diagonal, trivially real spectrum; larger
+        g: more eigenvalues driven into complex-conjugate pairs).
+    beta : int, optional
+        1 (real blocks) or 2 (complex Hermitian blocks, default).
+    seed : int, numpy.random.Generator, or None, optional
+    """
+
+    def __init__(
+        self,
+        p: int,
+        q: int,
+        g: float,
+        beta: int = 2,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if beta not in (1, 2):
+            raise ValueError(f"PTSymmetricEnsemble only supports beta in (1, 2), got {beta}")
+        if g < 0:
+            raise ValueError(f"g (coupling strength) must be >= 0, got {g}")
+        super().__init__(p + q, seed=seed)
+        self.p = p
+        self.q = q
+        self.g = float(g)
+        self.beta: float = beta
+
+    def _sample_matrix(self, rng: np.random.Generator) -> np.ndarray:
+        complex_entries = self.beta == 2
+        a = _dense_hermitian_block(self.p, rng, complex_entries)
+        d = _dense_hermitian_block(self.q, rng, complex_entries)
+        if complex_entries:
+            b = self.g * (rng.standard_normal((self.p, self.q)) + 1j * rng.standard_normal((self.p, self.q))) / np.sqrt(2.0)
+        else:
+            b = self.g * rng.standard_normal((self.p, self.q))
+        c = -b.conj().T
+        top = np.hstack([a, b])
+        bottom = np.hstack([c, d])
+        return np.vstack([top, bottom])
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        return np.linalg.eigvals(self._sample_matrix(rng)).astype(complex)
+
+    def natural_scale(self) -> float:
+        # No single universal rescaling: unlike the Hermitian ensembles,
+        # this ensemble's spectral shape genuinely changes character
+        # (real -> partially complex) as g varies, so there is no fixed
+        # limiting law to normalize against.
+        return 1.0