physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/ensembles/embedded.py

@@ -0,0 +1,207 @@
+"""Embedded Gaussian ensembles (EGOE(k)/EGUE(k)) and the Two-Body Random
+Ensemble (TBRE, k=2) -- random k-body interactions among m fermions
+distributed over N single-particle levels.
+
+References
+----------
+K. K. Mon, J. B. French, "Statistical properties of many-particle
+spectra", Ann. Phys. 95 (1975) 90 -- the k-body embedded ensemble
+construction and the celebrated result that the many-body density of
+states approaches a GAUSSIAN (not the semicircle law) as m, N -> infinity
+at fixed k >= 2, k < m.
+T. A. Brody, J. Flores, J. B. French, P. A. Mello, A. Pandey,
+S. S. M. Wong, "Random-matrix physics: spectrum and strength
+fluctuations", Rev. Mod. Phys. 53 (1981) 385 -- review.
+V. K. B. Kota, "Embedded Random Matrix Ensembles in Quantum Physics",
+Lecture Notes in Physics 884, Springer, 2014 -- comprehensive reference.
+T. Papenbrock, H. A. Weidenmuller, "Colloquium: Random matrices and
+chaos in nuclear physics", Rev. Mod. Phys. 79 (2007) 997.
+
+Unlike every classical ensemble in this package (i.i.d. matrix entries),
+the many-body Hamiltonian matrix here is built by EMBEDDING a random
+k-body interaction into the m-particle Fock space: the interaction
+itself is a Hermitian random (GOE/GUE-type) matrix V on the space of
+k-particle Slater determinants (dimension C(N, k)), and the m-particle
+Hamiltonian is
+
+    H = sum_{I, J} V_{I, J} * a^dagger_I a_J
+
+summed over all k-index tuples I, J (I = i_1 < ... < i_k, similarly J),
+with a^dagger_I = a^dagger_{i_1} ... a^dagger_{i_k} and
+a_J = a_{j_k} ... a_{j_1} (reversed order, so a^dagger_I a_J is built
+from creation operators applied in ASCENDING index order and
+annihilation operators in DESCENDING index order -- get this backwards
+and Hermiticity silently survives but the exact k=m identity below does
+not, which is exactly how an initial, subtly wrong sign convention
+during development was caught).
+
+Because H is built from a SHARED set of k-body matrix elements rather
+than independent entries, the resulting many-body matrix elements are
+strongly correlated (unlike GOE) -- this correlation structure is
+exactly what drives the many-body density of states toward a Gaussian
+rather than a semicircle as m, N grow (Mon-French 1975), the qualitative
+signature this ensemble exists to demonstrate.
+
+Implementation: creation/annihilation operators are realized via the
+standard Jordan-Wigner tensor-product construction over N qubits (one
+per single-particle level, ``|0>``/``|1>`` = unoccupied/occupied) -- the SAME
+technique already used for SYK's Majorana operators
+(``physicskit.rmt.ensembles.syk``), just for fermionic number-conserving ladder
+operators instead. H is built on the full 2^N Fock space, then restricted
+to the fixed-m-particle sector (dimension C(N, m)) by selecting the
+appropriate basis states -- exact, not an approximation, since
+number-conserving k-body terms never mix different particle-number
+sectors.
+
+Verified during development (see ``tests/test_embedded.py``), independent
+of trusting the construction's well-known status in the literature:
+
+- H is exactly Hermitian and exactly commutes with the total particle
+  number operator (both to machine precision).
+- The celebrated special case k = m: with only m particles present, a
+  k=m-body interaction acts on all of them at once, so the embedding is
+  trivial and the m-particle Hamiltonian reduces EXACTLY (not merely
+  statistically) to the k-body matrix V itself -- checked directly for
+  k=m=2 and k=m=3 to machine precision, catching the operator-ordering
+  sign bug mentioned above during development.
+
+Cost note (genuinely different from the classical ensembles, exactly
+like SYK): the Fock-space dimension is 2^N, and building H requires
+O(C(N,k)^2) dense Hilbert-space operator products -- exponential in N,
+not polynomial. Keep ``n_levels`` small (roughly <= 10) for interactive
+use.
+
+``beta`` in {1, 2} selects a real-symmetric (EGOE, "orthogonal") or
+complex-Hermitian (EGUE, "unitary") random two-body interaction V; no
+simple universal ``natural_scale`` rescaling is attempted (unlike GOE's
+sqrt(n), the many-body spectral width here depends on N, m, and k
+through a nontrivial combinatorial moment formula -- see Mon-French
+1975 -- not implemented here).
+"""
+
+from __future__ import annotations
+
+from itertools import combinations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+_I2 = np.eye(2, dtype=complex)
+_Z = np.array([[1.0, 0.0], [0.0, -1.0]], dtype=complex)
+_CREATE_LOCAL = np.array([[0.0, 0.0], [1.0, 0.0]], dtype=complex)  # |0>=unoccupied -> |1>=occupied
+_ANNIHILATE_LOCAL = np.array([[0.0, 1.0], [0.0, 0.0]], dtype=complex)
+
+
+def _fermion_ladder_operators(n_levels: int) -> list[np.ndarray]:
+    """The N fermionic creation operators a^dagger_1, ..., a^dagger_N as
+    dense 2^N x 2^N complex matrices (Jordan-Wigner construction; the
+    corresponding annihilation operators are their conjugate transposes).
+    """
+    creators = []
+    for k in range(n_levels):
+        factors = [_Z] * k + [_CREATE_LOCAL] + [_I2] * (n_levels - k - 1)
+        op = factors[0]
+        for factor in factors[1:]:
+            op = np.kron(op, factor)
+        creators.append(op)
+    return creators
+
+
+class EmbeddedGaussianEnsemble(MatrixEnsemble):
+    """EGOE(k)/EGUE(k): m fermions in N single-particle levels,
+    interacting via a random k-body interaction (see module docstring).
+
+    Parameters
+    ----------
+    n_particles : int
+        Number of fermions m.
+    n_levels : int
+        Number of single-particle levels N (>= n_particles). Keep small
+        (roughly <= 10) -- see the module docstring's cost note.
+    k : int, optional
+        Interaction body-rank (default 2, i.e. TBRE). Must satisfy
+        2 <= k <= n_particles.
+    beta : int, optional
+        1 (real symmetric interaction, EGOE) or 2 (complex Hermitian,
+        EGUE).
+    """
+
+    def __init__(
+        self,
+        n_particles: int,
+        n_levels: int,
+        k: int = 2,
+        beta: int = 1,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if beta not in (1, 2):
+            raise ValueError(f"beta must be 1 or 2, got {beta}")
+        if not 2 <= k <= n_particles <= n_levels:
+            raise ValueError(f"require 2 <= k <= n_particles <= n_levels; got k={k}, n_particles={n_particles}, n_levels={n_levels}")
+        super().__init__(n_particles, seed=seed)
+        self.n_levels = n_levels
+        self.k = k
+        self.beta: float = beta
+        self._p_ops: list[np.ndarray] | None = None
+        self._basis: list[int] | None = None
+
+    def _operators(self) -> tuple[list[np.ndarray], list[int]]:
+        """The k-body creation operators P_a (one per k-subset of levels)
+        and the fixed-m-particle basis indices -- independent of the
+        random interaction V, so computed once and cached rather than
+        redone on every ``_sample_eigenvalues`` call.
+        """
+        if self._p_ops is None:
+            n_levels, k, m = self.n_levels, self.k, self.n
+            creators = _fermion_ladder_operators(n_levels)
+            tuples = list(combinations(range(n_levels), k))
+
+            def multi_create(idxs: tuple[int, ...]) -> np.ndarray:
+                op = creators[idxs[0]]
+                for idx in idxs[1:]:
+                    op = op @ creators[idx]
+                return op
+
+            self._p_ops = [multi_create(t) for t in tuples]
+            dim = self._p_ops[0].shape[0]
+            self._basis = [state for state in range(dim) if bin(state).count("1") == m]
+        return self._p_ops, self._basis
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        p_ops, basis = self._operators()
+        n_tuples = len(p_ops)
+
+        if self.beta == 1:
+            x = rng.standard_normal((n_tuples, n_tuples))
+            v = (x + x.T) / np.sqrt(2.0)
+        else:
+            x = (rng.standard_normal((n_tuples, n_tuples)) + 1j * rng.standard_normal((n_tuples, n_tuples))) / np.sqrt(2.0)
+            v = (x + x.conj().T) / 2.0
+
+        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
+
+        h_sub = h[np.ix_(basis, basis)]
+        h_sub = (h_sub + h_sub.conj().T) / 2.0
+        return np.linalg.eigvalsh(h_sub)
+
+    def natural_scale(self) -> float:
+        return 1.0
+
+
+class TwoBodyRandomEnsemble(EmbeddedGaussianEnsemble):
+    """TBRE: the k=2 special case of :class:`EmbeddedGaussianEnsemble`,
+    by far the most commonly studied (nuclear shell-model-type) case."""
+
+    def __init__(
+        self,
+        n_particles: int,
+        n_levels: int,
+        beta: int = 1,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        super().__init__(n_particles, n_levels, k=2, beta=beta, seed=seed)

physicskit/rmt/ensembles/gaussian.py

@@ -0,0 +1,153 @@
+"""Gaussian (Hermite) ensembles -- GOE, GUE, GSE -- plus the continuum
+Dyson-index generalization, all built on the Dumitriu-Edelman tridiagonal
+model (see ``physicskit.rmt.utils.tridiagonal``).
+
+References
+----------
+E. Wigner, Ann. Math. 62 (1955) 548; Ann. Math. 67 (1958) 325.
+M. L. Mehta, "Random Matrices" (3rd ed.), Academic Press, 2004.
+I. Dumitriu, A. Edelman, J. Math. Phys. 43, 5830 (2002).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..utils.tridiagonal import sample_hermite_beta_eigenvalues
+from .base import MatrixEnsemble
+
+
+def _dense_hermite(n: int, beta: int, rng: np.random.Generator) -> np.ndarray:
+    """Dense n x n GOE/GUE matrix (beta=1 real symmetric, beta=2 complex
+    Hermitian), same off-diagonal-variance-1/diagonal-variance-2
+    convention as the tridiagonal model above.
+
+    Used only for ``_sample_eigenvalues_and_vectors``: unlike the
+    tridiagonal model, whose eigenVALUES are exact in distribution but
+    whose eigenVECTORS are an artifact of that particular sparse
+    representation (verified numerically during development -- their
+    inverse participation ratio was 2-3x too large relative to the exact
+    Haar-vector result below, and the gap grew with n), a genuinely
+    dense, rotationally/unitarily-invariant construction is needed to
+    get Haar-distributed eigenvectors. See ``_dense_hermite_quaternion``
+    for the beta=4 (GSE) analogue.
+    """
+    if beta == 1:
+        x = rng.standard_normal((n, n))
+        return (x + x.T) / np.sqrt(2.0)
+    x = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+    return (x + x.conj().T) / 2.0
+
+
+def _dense_hermite_quaternion(n: int, rng: np.random.Generator) -> np.ndarray:
+    """Dense n x n quaternionic self-dual Hermitian matrix (GSE),
+    embedded as a 2n x 2n complex matrix via the standard
+    quaternion-to-2x2-complex-block map (same convention as
+    ``physicskit.rmt.ensembles.ginibre.GinSE``).
+
+    Its 2n eigenvalues come in exact Kramers double-degenerate pairs
+    (like GSE/CSE/EffGSE/JSE); ``_sample_eigenvalues_and_vectors`` keeps
+    one representative eigenvalue AND its (2n-dimensional complex, i.e.
+    n-quaternion) eigenvector per pair. Verified numerically during
+    development that folding each such eigenvector into n per-site
+    quaternion weights ``|v[2i]|^2 + |v[2i+1]|^2`` gives an inverse
+    participation ratio matching the exact beta=4 Haar-vector theory
+    (``physicskit.rmt.stats.localization.ipr_theory(n, beta=4)``) to four
+    significant figures -- see
+    ``physicskit.rmt.stats.localization.inverse_participation_ratio_quaternionic``
+    and ``tests/test_localization.py``.
+    """
+    a = rng.standard_normal((n, n))
+    b = rng.standard_normal((n, n))
+    c = rng.standard_normal((n, n))
+    d = rng.standard_normal((n, n))
+    m = np.zeros((2 * n, 2 * n), dtype=complex)
+    m[0::2, 0::2] = a + 1j * b
+    m[0::2, 1::2] = c + 1j * d
+    m[1::2, 0::2] = -c + 1j * d
+    m[1::2, 1::2] = a - 1j * b
+    return (m + m.conj().T) / 2.0
+
+
+class HermiteBetaEnsemble(MatrixEnsemble):
+    """General beta-Hermite (Gaussian) ensemble.
+
+    beta=1, 2, 4 recover GOE, GUE, GSE exactly (same joint eigenvalue
+    density, not merely the same limiting law); any beta > 0 is a valid
+    continuum generalization, useful for studying the Dyson index as a
+    continuous "inverse temperature" parameter.
+
+    Use the named subclasses (:class:`GOE`, :class:`GUE`, :class:`GSE`)
+    for the classical cases; use this class directly for other beta.
+    """
+
+    def __init__(self, n: int, beta: float, seed: int | np.random.Generator | None = None) -> None:
+        """
+        Parameters
+        ----------
+        n : int
+            Matrix dimension.
+        beta : float
+            Dyson index; must be positive.
+        seed : int, numpy.random.Generator, or None, optional
+        """
+        if beta <= 0:
+            raise ValueError(f"beta must be positive, got {beta}")
+        super().__init__(n, seed=seed)
+        self.beta: float = float(beta)
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        return sample_hermite_beta_eigenvalues(self.n, self.beta, rng)
+
+    def _sample_eigenvalues_and_vectors(self, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+        if self.beta not in (1, 2, 4):
+            raise NotImplementedError("return_eigenvectors=True is only supported for beta in (1, 2, 4) (GOE, GUE, GSE).")
+        if self.beta == 4:
+            h = _dense_hermite_quaternion(self.n, rng)
+            eigenvalues, eigenvectors = np.linalg.eigh(h)
+            # Exact Kramers double degeneracy: keep one eigenvalue and its
+            # (2n-dim complex) eigenvector per pair -- see
+            # _dense_hermite_quaternion's docstring.
+            return eigenvalues[0::2], eigenvectors[:, 0::2]
+        h = _dense_hermite(self.n, int(self.beta), rng)
+        eigenvalues, eigenvectors = np.linalg.eigh(h)
+        return eigenvalues, eigenvectors
+
+    def natural_scale(self) -> float:
+        # Verified empirically (see design notes): raw eigenvalue spread
+        # grows as sqrt(n * beta); dividing by this recovers the standard
+        # semicircle normalization with support [-2, 2] for all beta.
+        return np.sqrt(self.n * self.beta)
+
+
+class GOE(HermiteBetaEnsemble):
+    """Gaussian Orthogonal Ensemble (beta=1).
+
+    Real symmetric matrices; time-reversal symmetric with T^2 = +1.
+    Altland-Zirnbauer class AI.
+    """
+
+    def __init__(self, n: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, beta=1, seed=seed)
+
+
+class GUE(HermiteBetaEnsemble):
+    """Gaussian Unitary Ensemble (beta=2).
+
+    Complex Hermitian matrices; no time-reversal symmetry.
+    Altland-Zirnbauer class A.
+    """
+
+    def __init__(self, n: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, beta=2, seed=seed)
+
+
+class GSE(HermiteBetaEnsemble):
+    """Gaussian Symplectic Ensemble (beta=4).
+
+    Quaternionic self-dual Hermitian matrices; time-reversal symmetric
+    with T^2 = -1. Altland-Zirnbauer class AII.
+    """
+
+    def __init__(self, n: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, beta=4, seed=seed)

physicskit/rmt/ensembles/ginibre.py

@@ -0,0 +1,110 @@
+"""Ginibre ensembles -- GinOE (real), GinUE (complex), GinSE (quaternion).
+
+References
+----------
+J. Ginibre, "Statistical Ensembles of Complex, Quaternion, and Real
+Matrices", J. Math. Phys. 6 (1965) 440.
+A. Edelman, E. Kostlan, S. Shub, "How many eigenvalues of a random
+matrix are real?", J. Amer. Math. Soc. 7 (1994) 247 -- the real-Ginibre
+real-eigenvalue-count result, validated (against its large-n asymptotic
+form, not the exact finite-n closed form -- see
+``physicskit.rmt.stats.real_ginibre`` for why) by
+``physicskit.rmt.validation.RealGinibreEigenvalueCount``.
+
+Unlike the Hermitian/unitary ensembles built so far, Ginibre matrices
+have NO symmetry constraint at all -- just i.i.d. entries -- so their
+eigenvalues are genuinely complex and spread over a 2-D region (the unit
+disk, asymptotically), not confined to the real line or unit circle.
+``Spectrum.eigenvalues`` for these ensembles is therefore a complex
+array; ``natural_scale`` (sqrt(n)) rescales eigenvalues onto the unit
+disk (Ginibre's exact result, not merely asymptotic, for finite n up to
+this fixed rescaling).
+
+Real vs. complex vs. quaternion Ginibre are NOT interchangeable dtypes
+of the same construction -- they have qualitatively different eigenvalue
+structure::
+
+    GinUE (complex): eigenvalues spread generically over the disk.
+    GinOE (real): a mix of purely real eigenvalues and complex-conjugate
+        pairs (the number of real eigenvalues grows like sqrt(2n/pi),
+        Edelman-Kostlan-Shub 1994) -- a vanishing fraction of n as
+        n -> infinity, but a structurally distinct, celebrated result
+        with no Hermitian-ensemble analogue.
+    GinSE (quaternion): a real quaternion matrix, embedded as a 2n x 2n
+        complex matrix via the standard quaternion-to-2x2-complex-block
+        map, has exactly 2n eigenvalues occurring in complex-conjugate
+        pairs (z, z-bar) -- but, importantly, this is NOT the same kind
+        of degeneracy as GSE/CSE (where the paired eigenvalues are
+        *exactly identical*, a true Kramers symmetry): here z and
+        z-bar are genuinely distinct eigenvalues whenever z is not real,
+        so GinSE keeps all 2n eigenvalues rather than de-duplicating.
+"""
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+class GinOE(MatrixEnsemble):
+    """Real Ginibre ensemble.
+
+    ``Spectrum.eigenvalues`` holds n complex values per sample (purely
+    real entries have zero imaginary part).
+    """
+
+    beta: float = 1
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        x = rng.standard_normal((self.n, self.n))
+        return np.linalg.eigvals(x).astype(complex)
+
+    def natural_scale(self) -> float:
+        return np.sqrt(self.n)
+
+
+class GinUE(MatrixEnsemble):
+    """Complex Ginibre ensemble."""
+
+    beta: float = 2
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        x = (rng.standard_normal((self.n, self.n)) + 1j * rng.standard_normal((self.n, self.n))) / np.sqrt(2.0)
+        return np.linalg.eigvals(x)
+
+    def natural_scale(self) -> float:
+        return np.sqrt(self.n)
+
+
+class GinSE(MatrixEnsemble):
+    """Quaternion Ginibre ensemble.
+
+    ``n`` is the quaternion matrix dimension; each sample produces 2*n
+    complex eigenvalues (genuinely distinct conjugate pairs -- see
+    module docstring for why these are NOT de-duplicated, unlike GSE/CSE).
+    """
+
+    beta: float = 4
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n = self.n
+        a = rng.standard_normal((n, n))
+        b = rng.standard_normal((n, n))
+        c = rng.standard_normal((n, n))
+        d = rng.standard_normal((n, n))
+        # Vectorized quaternion-to-2x2-complex-block embedding (verified
+        # against the direct per-block loop construction to give an
+        # identical matrix): strided assignment places each block
+        # [[a+bi, c+di], [-c+di, a-bi]] / 2 directly, without a Python
+        # loop over n^2 blocks. The /2 normalizes entry scale to match
+        # the same unit-disk circular law radius as GinOE/GinUE after
+        # the shared sqrt(n) natural_scale -- verified numerically (see
+        # design notes / test suite).
+        m = np.zeros((2 * n, 2 * n), dtype=complex)
+        m[0::2, 0::2] = (a + 1j * b) / 2.0
+        m[0::2, 1::2] = (c + 1j * d) / 2.0
+        m[1::2, 0::2] = (-c + 1j * d) / 2.0
+        m[1::2, 1::2] = (a - 1j * b) / 2.0
+        return np.linalg.eigvals(m)
+
+    def natural_scale(self) -> float:
+        return np.sqrt(self.n)

physicskit/rmt/ensembles/girko.py

@@ -0,0 +1,190 @@
+"""Girko ensembles -- universality generalizations of the Ginibre
+ensembles.
+
+References
+----------
+V. L. Girko, "Circular law", Theory Probab. Appl. 29 (1984) 694 -- the
+circular law holds for ANY i.i.d. entry distribution (mean 0, unit
+variance), not just Gaussian.
+Z. D. Bai, "Circular law", Ann. Probab. 25 (1997) 494 -- fixed gaps in
+Girko's original proof.
+T. Tao, V. Vu (with an appendix by M. Krishnapur), "Random matrices:
+Universality of ESDs and the circular law", Ann. Probab. 38 (2010) 2023
+-- relaxed the moment condition to finite variance.
+V. L. Girko, "The elliptic law", Theory Probab. Appl. 30 (1985) 677 --
+matrices whose (X_ij, X_ji) entry pairs are correlated have eigenvalues
+filling an ellipse rather than a disk.
+A. Naumov, "Elliptic law for random matrices", arXiv:1201.1639 (2012) --
+rigorous elliptic law for general (non-Gaussian) entry distributions.
+Y. V. Fyodorov, B. A. Khoruzhenko, H.-J. Sommers, "Almost-Hermitian
+random matrices: eigenvalue density in the complex plane", Phys. Lett.
+A 226 (1997) 46 -- the Gaussian special case ("elliptic Ginibre"), which
+:class:`GirkoElliptic` recovers for its default entry distribution --
+per the design notes, FKS is a parametrization of the general Girko
+result below, not a separate construction.
+
+Both ensembles reuse ``physicskit.rmt.ensembles.universality``'s entry-sampler
+convention (``uniform_unit_variance``, ``rademacher``,
+``exponential_centered_unit_variance``) -- the same non-Gaussian entry
+distributions already used there to demonstrate Wigner (Hermitian)
+universality now demonstrate its non-Hermitian analogue: the circular
+and elliptic laws depend only on the first two moments of the entry
+distribution, not on Gaussianity.
+
+Unlike every Dyson-indexed ensemble elsewhere in this package,
+:class:`IIDEnsemble` and :class:`GirkoElliptic` have NO beta:
+Girko universality is a different, orthogonal axis from Dyson's
+threefold way -- it says the *macroscopic* eigenvalue law
+(circular/elliptic) is unchanged across entry distributions, not that
+the *exact* joint eigenvalue density matches a beta-ensemble formula
+(only Gaussian entries have that property). ``Spectrum.beta`` is
+therefore left ``None`` for both, inherited from the base class.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+EntrySampler = Callable[[np.random.Generator, tuple[int, ...]], np.ndarray]
+
+
+def standard_normal(rng: np.random.Generator, size: tuple[int, ...]) -> np.ndarray:
+    """i.i.d. standard Gaussian entries -- mean 0, variance 1. Default
+    entry distribution for :class:`GirkoElliptic` (the FKS elliptic
+    Ginibre special case); also usable directly with :class:`IIDEnsemble`
+    to recover plain Ginibre-law behavior via the general construction."""
+    return rng.standard_normal(size)
+
+
+class IIDEnsemble(MatrixEnsemble):
+    """Girko's circular law: eigenvalues of an n x n matrix with i.i.d.
+    mean-zero, unit-variance entries (real or complex) converge to the
+    uniform distribution on the unit disk after the sqrt(n) rescaling --
+    exactly the GinOE/GinUE limiting law, but for ANY entry distribution
+    satisfying those two moment conditions, not just Gaussian.
+
+    Parameters
+    ----------
+    n : int
+    entry_sampler : callable
+        ``entry_sampler(rng, size)`` returning i.i.d. mean-zero,
+        unit-variance real samples of the given shape -- see
+        ``standard_normal`` above and
+        ``physicskit.rmt.ensembles.universality.uniform_unit_variance``,
+        ``rademacher``, ``exponential_centered_unit_variance`` for
+        ready-made options.
+    complex_entries : bool, optional
+        If True (default), each entry is
+        ``(entry_sampler + 1j*entry_sampler) / sqrt(2)`` -- matching
+        GinUE's construction. If False, entries are real -- matching
+        GinOE, including its real-eigenvalue anomaly at any finite n
+        (a property of real matrices generally, not just Gaussian ones).
+    """
+
+    def __init__(
+        self,
+        n: int,
+        entry_sampler: EntrySampler,
+        complex_entries: bool = True,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        super().__init__(n, seed=seed)
+        self.entry_sampler = entry_sampler
+        self.complex_entries = complex_entries
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n = self.n
+        if self.complex_entries:
+            x = (self.entry_sampler(rng, (n, n)) + 1j * self.entry_sampler(rng, (n, n))) / np.sqrt(2.0)
+        else:
+            x = self.entry_sampler(rng, (n, n))
+        return np.linalg.eigvals(x).astype(complex)
+
+    def natural_scale(self) -> float:
+        return np.sqrt(self.n)
+
+
+def _correlated_pair_matrix(n: int, rho: float, entry_sampler: EntrySampler, rng: np.random.Generator) -> np.ndarray:
+    """n x n real matrix whose off-diagonal entry pairs (X_ij, X_ji)
+    (i != j) each have unit variance and correlation ``rho``.
+
+    Construction: independent A, B ~ entry_sampler; for i < j,
+        X_ij = c1*A_ij + c2*B_ij
+        X_ji = c1*A_ij - c2*B_ij
+    with c1 = sqrt((1+rho)/2), c2 = sqrt((1-rho)/2). Directly verifiable:
+    Var(X_ij) = Var(X_ji) = c1^2 + c2^2 = 1 and
+    Cov(X_ij, X_ji) = c1^2 - c2^2 = rho, for any entry_sampler with
+    mean 0, unit variance -- not just Gaussian (Naumov 2012).
+
+    Diagonal entries are set to X_ii = c1*sqrt(2)*A_ii, giving
+    Var(X_ii) = 1+rho -- chosen (rather than a fixed unit variance) so
+    the construction degenerates *exactly* at both endpoints: at rho=1
+    (c1=1) this is sqrt(2)*A_ii, the standard Wigner/GOE
+    variance-2 diagonal convention used elsewhere in this package (see
+    ``physicskit.rmt.ensembles.universality.GeneralWignerEnsemble``), and at
+    rho=-1 (c1=0) the diagonal is exactly zero -- required for X to be
+    exactly antisymmetric there (X_ii = -X_ii forces X_ii = 0; no
+    distribution of nonzero variance can satisfy that identically).
+    """
+    a = entry_sampler(rng, (n, n))
+    b = entry_sampler(rng, (n, n))
+    c1 = np.sqrt((1.0 + rho) / 2.0)
+    c2 = np.sqrt((1.0 - rho) / 2.0)
+    upper = np.triu(c1 * a + c2 * b, k=1)
+    lower = np.triu(c1 * a - c2 * b, k=1).T
+    diagonal = np.diag(c1 * np.sqrt(2.0) * np.diag(a))
+    return upper + lower + diagonal
+
+
+class GirkoElliptic(MatrixEnsemble):
+    """Girko's elliptic law: eigenvalues of an n x n real matrix whose
+    (X_ij, X_ji) entry pairs are correlated at ``rho`` (each individually
+    unit variance) fill an ellipse with semi-axes (1+rho) along the real
+    axis and (1-rho) along the imaginary axis, after the sqrt(n)
+    rescaling.
+
+    rho=0 recovers plain i.i.d. entries -- Girko's circular law, a disk
+    of radius 1, the same limiting law as :class:`IIDEnsemble` with
+    ``complex_entries=False``. The endpoints rho=+-1 are exact
+    (not just asymptotic) degenerate limits, checkable at any finite n:
+    rho=1 makes X exactly symmetric (X_ij = X_ji), so eigenvalues are
+    exactly real (recovering the real-entries Wigner/semicircle case,
+    the ellipse collapsed onto the real segment [-2, 2]); rho=-1 makes X
+    exactly antisymmetric, so eigenvalues are exactly purely imaginary
+    (real antisymmetric matrices have eigenvalues 0 or imaginary
+    conjugate pairs -- the ellipse collapsed onto the imaginary axis).
+
+    Parameters
+    ----------
+    n : int
+    rho : float
+        Entry-pair correlation, in [-1, 1].
+    entry_sampler : callable, optional
+        ``entry_sampler(rng, size)`` returning i.i.d. mean-zero,
+        unit-variance real samples (default: ``standard_normal``, i.e.
+        the Fyodorov-Khoruzhenko-Sommers elliptic Ginibre special case).
+    """
+
+    def __init__(
+        self,
+        n: int,
+        rho: float,
+        entry_sampler: EntrySampler | None = None,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if not -1.0 <= rho <= 1.0:
+            raise ValueError(f"rho must be in [-1, 1], got {rho}")
+        super().__init__(n, seed=seed)
+        self.rho = float(rho)
+        self.entry_sampler = entry_sampler or standard_normal
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        x = _correlated_pair_matrix(self.n, self.rho, self.entry_sampler, rng)
+        return np.linalg.eigvals(x).astype(complex)
+
+    def natural_scale(self) -> float:
+        return np.sqrt(self.n)