physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/ensembles/circular.py

@@ -0,0 +1,104 @@
+"""Circular ensembles -- COE, CUE, CSE.
+
+References
+----------
+F. J. Dyson, "Statistical Theory of the Energy Levels of Complex Systems
+I-III", J. Math. Phys. 3 (1962) 140, 157, 166 -- the original
+circular-ensemble classification, and the source of Dyson's beta=1,2,4
+threefold way.
+F. Mezzadri, Notices Amer. Math. Soc. 54 (2007) 592 -- the Haar-random
+sampling recipe used here.
+
+Important construction note (this is easy to get wrong): COE and CSE
+are NOT simply "eigenvalues of a Haar-random matrix from O(n) / Sp(n)".
+A real orthogonal matrix's eigenvalues are either +-1 or complex-conjugate
+pairs -- not the generic unit-circle structure a circular ensemble
+requires. Dyson's actual constructions::
+
+    CUE: eigenvalues of U, U Haar-random from U(n).
+    COE: eigenvalues of U = V^T V, V Haar-random from U(n) -- a
+         *symmetric* unitary matrix, built from a unitary building block.
+    CSE: eigenvalues of U = V^R V, V Haar-random from U(2n), where
+         V^R = Z V^T Z^{-1} is the symplectic dual (Z the symplectic
+         form). U is self-dual unitary; its 2n eigenvalues come in n
+         doubly-degenerate pairs, of which n distinct values are the CSE
+         eigenvalues.
+
+All three were verified during development by checking their unfolded
+level-spacing statistics against the already-validated (generalized)
+Wigner surmise at the matching beta -- see ``tests/test_circular.py``.
+This is a meaningful cross-family check: spacing statistics are
+universal in beta across the Gaussian and circular families, so
+agreement here is independent evidence the constructions are correct,
+not just that "some points ended up on a circle".
+
+Eigenvalue representation: ``Spectrum.eigenvalues`` for these ensembles
+holds the eigenvalue *phases* theta in [0, 2*pi), not the complex
+eigenvalues e^{i*theta} themselves -- this keeps the rest of the
+(real-array-based) stats machinery directly usable. ``natural_scale`` is
+set to 2*pi/n, so ``Spectrum.rescaled`` is already fully unfolded with
+exactly unit mean spacing -- exactly, not just asymptotically, since
+Haar measure is exactly rotation-invariant at any finite n. This is a
+structural simplification relative to the Gaussian/Wishart ensembles,
+which only have unit mean spacing after unfolding against their
+(asymptotic) limiting density.
+"""
+
+import numpy as np
+
+from ..utils.haar import haar_unitary, symplectic_form
+from .base import MatrixEnsemble
+
+
+class COE(MatrixEnsemble):
+    """Circular Orthogonal Ensemble (beta=1)."""
+
+    beta: float = 1
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        v = haar_unitary(self.n, rng)
+        u = v.T @ v  # symmetric unitary
+        eigs = np.linalg.eigvals(u)
+        return np.sort(np.angle(eigs) % (2.0 * np.pi))
+
+    def natural_scale(self) -> float:
+        return 2.0 * np.pi / self.n
+
+
+class CUE(MatrixEnsemble):
+    """Circular Unitary Ensemble (beta=2)."""
+
+    beta: float = 2
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        u = haar_unitary(self.n, rng)
+        eigs = np.linalg.eigvals(u)
+        return np.sort(np.angle(eigs) % (2.0 * np.pi))
+
+    def natural_scale(self) -> float:
+        return 2.0 * np.pi / self.n
+
+
+class CSE(MatrixEnsemble):
+    """Circular Symplectic Ensemble (beta=4).
+
+    ``n`` here is the number of *distinct* CSE eigenvalues; internally a
+    Haar-random matrix of size 2n is used (each eigenvalue of the dual
+    construction is doubly degenerate).
+    """
+
+    beta: float = 4
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n2 = 2 * self.n
+        v = haar_unitary(n2, rng)
+        z = symplectic_form(n2)
+        v_dual = (-z) @ v.T @ z  # Z^{-1} = -Z since Z^2 = -I
+        u = v_dual @ v
+        eigs = np.linalg.eigvals(u)
+        theta = np.sort(np.angle(eigs) % (2.0 * np.pi))
+        # Degenerate pairs are adjacent after sorting; keep one of each.
+        return theta[0::2]
+
+    def natural_scale(self) -> float:
+        return 2.0 * np.pi / self.n

physicskit/rmt/ensembles/crossover.py

@@ -0,0 +1,82 @@
+"""The Pandey-Mehta GOE-GUE crossover ensemble: a continuous
+symmetry-breaking deformation interpolating between time-reversal-
+symmetric (GOE, beta=1) and time-reversal-broken (GUE, beta=2) level
+statistics.
+
+References
+----------
+A. Pandey, M. L. Mehta, "Gaussian ensembles of random Hermitian
+matrices intermediate between orthogonal and unitary ones", Commun.
+Math. Phys. 87 (1982) 449.
+F. J. Dyson, "A Brownian-motion model for the eigenvalues of a random
+matrix", J. Math. Phys. 3 (1962) 1191 -- the same crossover realized as
+a continuous-time stochastic (Dyson Brownian motion) process; the
+static construction here is the same family at one fixed "time".
+
+Construction: H(lambda) = A + i*lambda*B, for A an independent real
+symmetric (GOE-type) matrix and B an independent real ANTIsymmetric
+matrix (so i*B is Hermitian: (i*B)^dagger = -i*B^dagger = -i*(-B) =
+i*B). H is Hermitian for any real lambda. lambda=0 recovers GOE exactly
+(H = A); as lambda grows, the added antisymmetric-times-i piece breaks
+time-reversal symmetry, and level statistics cross over toward GUE.
+
+Verified numerically during development (see
+``tests/test_crossover.py``): the raw eigenvalue spread grows as
+``sqrt(n*(1+lambda^2))`` (each off-diagonal entry's variance is
+Var(A_ij) + lambda^2*Var(B_ij) = 1 + lambda^2, by independence),
+confirmed by checking the empirical eigenvalue standard deviation
+against this formula at several (n, lambda) pairs before using it as
+``natural_scale``. The consecutive-spacing-ratio statistic
+(``physicskit.rmt.stats.ratios.ratio_statistics``, no unfolding needed) was
+checked against both the GOE and GUE surmises across a lambda sweep at
+n=400: KS distance to the GOE surmise is smallest at lambda=0 (0.013)
+and grows monotonically; KS distance to the GUE surmise is smallest by
+lambda~0.1 (0.012) -- a genuine, verified crossover, with the
+half-way point falling at a small lambda (roughly 0.03-0.05 at n=400),
+consistent with the well-known finite-size scaling of this crossover
+(the transition lambda shrinks like 1/sqrt(n) as n grows) -- that
+specific scaling law itself is not derived or asserted exactly here.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+class GOEGUECrossoverEnsemble(MatrixEnsemble):
+    """Pandey-Mehta GOE-GUE crossover ensemble (see module docstring):
+    H = A + i*lambda*B, A real symmetric, B real antisymmetric.
+
+    Parameters
+    ----------
+    n : int
+        Matrix dimension.
+    lam : float
+        Symmetry-breaking (time-reversal-breaking) crossover parameter.
+        lam=0 recovers GOE exactly; lam -> infinity approaches GUE-like
+        statistics (at a lam scale that shrinks with n -- see module
+        docstring).
+    seed : int, numpy.random.Generator, or None, optional
+    """
+
+    def __init__(self, n: int, lam: float, seed: int | np.random.Generator | None = None) -> None:
+        if lam < 0:
+            raise ValueError(f"lam must be >= 0, got {lam}")
+        super().__init__(n, seed=seed)
+        self.lam = float(lam)
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n = self.n
+        x = rng.standard_normal((n, n))
+        a = (x + x.T) / np.sqrt(2.0)
+        y = rng.standard_normal((n, n))
+        b = (y - y.T) / np.sqrt(2.0)
+        h = a + 1j * self.lam * b
+        return np.linalg.eigvalsh(h)
+
+    def natural_scale(self) -> float:
+        # Verified numerically (see module docstring): raw eigenvalue
+        # spread grows as sqrt(n*(1+lambda^2)).
+        return np.sqrt(self.n * (1.0 + self.lam**2))

physicskit/rmt/ensembles/density_matrix.py

@@ -0,0 +1,148 @@
+"""Random quantum state (density matrix) ensembles: the induced measure
+(Hilbert-Schmidt as its special case) and the Bures-Hall measure.
+
+References
+----------
+K. Zyczkowski, H.-J. Sommers, "Induced measures in the space of mixed
+quantum states", J. Phys. A 34 (2001) 7111 -- the induced-measure
+construction, its joint eigenvalue density, and the mean-purity formula
+used for validation here.
+D. N. Page, "Average entropy of a subsystem", Phys. Rev. Lett. 71
+(1993) 1291 -- the exact average-entanglement-entropy formula (the
+"Page curve"), realized directly by this ensemble at general k -- see
+below.
+K. Zyczkowski, K. A. Penson, I. Nechita, B. Collins, "Generating random
+density matrices", J. Math. Phys. 52 (2011) 062201 -- survey covering
+both measures used here.
+V. Osipov, H.-J. Sommers, K. Zyczkowski, "Random Bures mixed states and
+the distribution of their purity", J. Phys. A 43 (2010) 055302 -- the
+Bures-Hall construction and joint eigenvalue density.
+J. Hall, "Random quantum correlations and density operator
+distributions", Phys. Lett. A 242 (1998) 123 -- the original Bures-Hall
+measure.
+
+Induced measure (and its Hilbert-Schmidt special case)
+--------------------------------------------------------
+A Haar-random pure state on C^n (x) C^k (n <= k WLOG), traced out over
+the k-dimensional second factor, gives a reduced density matrix on the
+n-dimensional first factor distributed EXACTLY as
+
+    rho = A @ A^dagger / Tr(A @ A^dagger)
+
+for A an n x k complex Ginibre matrix -- the "induced measure" with
+environment dimension k (Zyczkowski-Sommers 2001). k=n is the
+Hilbert-Schmidt measure (the flat/uniform measure induced by the
+natural volume element on the space of density matrices);
+k -> infinity concentrates rho near the maximally mixed state I/n; k=1
+forces A to be a single column, so A @ A^dagger is rank 1 and rho is
+exactly a Haar-random PURE state (a rank-1 projector).
+
+This SAME construction is, with no modification, exactly the standard
+matrix model used to study the "Page curve": since A n x k IS the
+(unnormalized) reduced density matrix of a random bipartite pure state
+on C^n (x) C^k, ``InducedMeasureEnsemble(n, k)`` directly generates that
+bipartite ensemble too -- ``physicskit.rmt.stats.entanglement`` provides the
+matching von Neumann entropy calculation and Page's (1993) exact average
+-- see ``tests/test_density_matrix.py`` for the verification (both the
+mean-purity formula (n+k)/(n*k+1) and Page's average-entropy formula
+were checked directly against Monte Carlo, at several (n, k) pairs,
+before being trusted here).
+
+Bures-Hall measure
+-------------------
+A genuinely different, non-Hilbert-Schmidt measure on density matrices,
+induced by the Bures (fidelity) metric rather than the flat
+Hilbert-Schmidt one. Realized here as
+
+    rho = (I + U) @ G @ G^dagger @ (I + U)^dagger / Tr(...)
+
+for G an independent n x n complex Ginibre matrix and U an independent
+Haar-random unitary (Osipov-Sommers-Zyczkowski 2010). This construction
+was verified directly here (not assumed from a remembered formula, given
+how easy this measure is to get subtly wrong) by comparing Monte Carlo
+samples against the EXACT joint eigenvalue density
+
+    P(lambda) ~ prod_{i<j} (lambda_i-lambda_j)^2 / (lambda_i+lambda_j)
+                * prod_i lambda_i^(-1/2),           sum_i lambda_i = 1
+
+at n=2 (closed-form 1-D marginal, checked via a KS test) and n=3
+(2-D numerical integration over the simplex, checked via mean purity) --
+both matched to within Monte Carlo noise; see ``tests/test_density_matrix.py``.
+
+Unlike the induced measure (whose joint density is a pure Vandermonde
+power ``|Delta(lambda)|^2``, exactly the classical Dyson beta=2 form, so
+``beta=2`` is used below), the Bures-Hall joint density has the EXTRA
+prod 1/(lambda_i+lambda_j) factor -- not one of Dyson's classical
+beta-ensembles, so ``beta`` is left ``None`` for it.
+
+All three ensembles return eigenvalues already in the natural [0, 1]
+range, summing to 1 (a genuine probability distribution) --
+``natural_scale`` is 1.0 throughout, no rescaling needed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..utils.haar import haar_unitary
+from .base import MatrixEnsemble
+
+
+class InducedMeasureEnsemble(MatrixEnsemble):
+    """Induced-measure random density matrix: rho = A @ A^dagger / Tr(...)
+    for an n x k complex Ginibre matrix A.
+
+    Parameters
+    ----------
+    n : int
+        Dimension of the density matrix (the traced-IN subsystem).
+    k : int, optional
+        Environment/other-subsystem dimension (default: n, the
+        Hilbert-Schmidt measure). k=1 gives Haar-random pure states.
+    """
+
+    beta: float = 2
+
+    def __init__(self, n: int, k: int | None = None, seed: int | np.random.Generator | None = None) -> None:
+        k = n if k is None else k
+        if k < 1:
+            raise ValueError(f"k must be >= 1, got {k}")
+        super().__init__(n, seed=seed)
+        self.k = k
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        a = (rng.standard_normal((self.n, self.k)) + 1j * rng.standard_normal((self.n, self.k))) / np.sqrt(2.0)
+        rho = a @ a.conj().T
+        rho = rho / np.trace(rho).real
+        rho = (rho + rho.conj().T) / 2.0
+        return np.linalg.eigvalsh(rho)
+
+    def natural_scale(self) -> float:
+        return 1.0
+
+
+class HilbertSchmidtEnsemble(InducedMeasureEnsemble):
+    """Hilbert-Schmidt random density matrix: the k=n special case of
+    :class:`InducedMeasureEnsemble` (the flat/uniform measure on the
+    space of n x n density matrices)."""
+
+    def __init__(self, n: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, k=n, seed=seed)
+
+
+class BuresHallEnsemble(MatrixEnsemble):
+    """Bures-Hall random density matrix (see module docstring)."""
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n = self.n
+        g = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+        w = g @ g.conj().T
+        u = haar_unitary(n, rng)
+        ip = np.eye(n) + u
+        rho = ip @ w @ ip.conj().T
+        rho = rho / np.trace(rho).real
+        rho = (rho + rho.conj().T) / 2.0
+        return np.linalg.eigvalsh(rho)
+
+    def natural_scale(self) -> float:
+        return 1.0

physicskit/rmt/ensembles/effective_hamiltonian.py

@@ -0,0 +1,230 @@
+"""Non-Hermitian effective Hamiltonians for open quantum systems (Feshbach
+projection / chaotic-scattering resonance ensembles).
+
+References
+----------
+V.V. Sokolov, V.G. Zelevinsky, "Dynamics and statistics of unstable
+quantum states", Nucl. Phys. A 504 (1989) 562.
+Y.V. Fyodorov, H.-J. Sommers, "Statistics of resonance poles, phase
+shifts and time delays in quantum chaotic scattering: Random matrix
+approach for systems with broken time-reversal invariance", J. Math.
+Phys. 38 (1997) 1918.
+Y.V. Fyodorov, D.V. Savin, H.-J. Sommers, "Scattering, reflection and
+impedance of waves in chaotic and disordered systems with absorption",
+J. Phys. A 38 (2005) 10731 (review).
+
+Physical picture
+-----------------
+A quantum system with N internal levels, coupled to M open decay/
+scattering channels, is no longer described by a Hermitian Hamiltonian
+once the continuum is eliminated via a Feshbach projection: the
+resulting effective Hamiltonian is
+
+    H_eff = H - (i / 2) * coupling**2 * V @ V^dagger
+
+where H (N x N) is drawn from the closed-system ensemble (GOE/GUE/GSE)
+and V (N x M) collects the amplitudes coupling each internal level to
+each open channel, drawn from the matching Dyson symmetry class.
+Complex eigenvalues E_k - i*Gamma_k/2 of H_eff are resonance poles:
+Re(E_k) are resonance positions, Gamma_k >= 0 are widths (decay rates).
+beta = 1, 2, 4 fixes both H's and V's symmetry class together
+(time-reversal-invariant / broken / self-dual), so this is the direct
+non-Hermitian analogue of GOE/GUE/GSE, not an unrelated construction --
+see :class:`EffGOE`, :class:`EffGUE`, :class:`EffGSE`.
+
+``m`` (number of open channels) controls the openness of the system::
+
+    m=0:              recovers the parent Hermitian ensemble exactly
+                       (H_eff = H, eigenvalues real to machine precision).
+    m << n:            weak-coupling/isolated-resonance regime.
+    m ~ n or m >> n:   strong-coupling/overlapping-resonance regime --
+                       "resonance trapping", where a few short-lived
+                       states absorb most of the total decay width and
+                       n-m long-lived states remain.
+
+Causality (widths are never negative): for ANY complex vector x with
+H_eff @ x = lam * x,
+
+    lam = (x^dagger @ H @ x - (i/2) * x^dagger @ Gamma @ x) / (x^dagger @ x)
+
+where Gamma = coupling**2 * V @ V^dagger. x^dagger @ H @ x and
+x^dagger @ x are real (H Hermitian), and x^dagger @ Gamma @ x is real
+and >= 0 (Gamma Hermitian positive semi-definite), so
+Im(lam) = -(x^dagger @ Gamma @ x) / (2 * x^dagger @ x) <= 0 always --
+this holds for every eigenvalue of every realization, not just on
+average, regardless of beta, n, or m. See ``tests/test_effective_hamiltonian.py``.
+
+beta=4 (:class:`EffGSE`) construction note: both H and V are built from
+2x2 quaternion blocks (the same embedding as :class:`~physicskit.rmt.ensembles.ginibre.GinSE`),
+so H is quaternionic self-dual Hermitian and Gamma = V @ V^dagger is
+quaternionic self-dual Hermitian PSD (the quaternion embedding is an
+algebra homomorphism, so products and adjoints of embedded matrices stay
+embedded). H_eff = H - (i/2)*Gamma is therefore a sum of two self-dual
+matrices and, verified numerically during development (to ~1e-14,
+machine precision -- see the test suite), its 2n eigenvalues retain
+Kramers' exact two-fold degeneracy even though H_eff itself is not
+Hermitian -- the same true degeneracy GSE itself has, unlike
+:class:`~physicskit.rmt.ensembles.ginibre.GinSE`'s *distinct* conjugate pairs.
+Only the n distinct values are returned (one representative per
+degenerate pair), mirroring :class:`~physicskit.rmt.ensembles.circular.CSE`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import MatrixEnsemble
+
+
+def _quaternion_block_embedding(rows: int, cols: int, rng: np.random.Generator) -> np.ndarray:
+    """N x M quaternion matrix, embedded as a 2N x 2M complex matrix via
+    the standard quaternion-to-2x2-complex-block map (same convention as
+    ``physicskit.rmt.ensembles.ginibre.GinSE``)."""
+    a = rng.standard_normal((rows, cols))
+    b = rng.standard_normal((rows, cols))
+    c = rng.standard_normal((rows, cols))
+    d = rng.standard_normal((rows, cols))
+    m = np.zeros((2 * rows, 2 * cols), 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
+
+
+def _sample_hamiltonian(n: int, rng: np.random.Generator, beta: float) -> np.ndarray:
+    """Dense closed-system Hamiltonian H for the given Dyson index."""
+    if beta == 1:
+        x = rng.standard_normal((n, n))
+        return (x + x.T) / np.sqrt(2.0)
+    if beta == 2:
+        x = (rng.standard_normal((n, n)) + 1j * rng.standard_normal((n, n))) / np.sqrt(2.0)
+        return (x + x.conj().T) / 2.0
+    if beta == 4:
+        m = _quaternion_block_embedding(n, n, rng)
+        return (m + m.conj().T) / 2.0  # quaternionic self-dual Hermitian
+    raise ValueError(f"beta must be 1, 2, or 4, got {beta}")
+
+
+def _sample_coupling(n: int, m: int, rng: np.random.Generator, beta: float) -> np.ndarray:
+    """Dense N x M (or, for beta=4, 2N x 2M) coupling matrix V."""
+    if beta == 1:
+        return rng.standard_normal((n, m))
+    if beta == 2:
+        return (rng.standard_normal((n, m)) + 1j * rng.standard_normal((n, m))) / np.sqrt(2.0)
+    if beta == 4:
+        return _quaternion_block_embedding(n, m, rng) / np.sqrt(2.0)
+    raise ValueError(f"beta must be 1, 2, or 4, got {beta}")
+
+
+class EffectiveHamiltonianEnsemble(MatrixEnsemble):
+    """Non-Hermitian effective Hamiltonian H_eff = H - (i/2) * coupling**2 * V @ V^dagger.
+
+    Use the named subclasses (:class:`EffGOE`, :class:`EffGUE`,
+    :class:`EffGSE`) for the classical beta=1,2,4 cases.
+
+    Parameters
+    ----------
+    n : int
+        Dimension of the closed system (number of resonances).
+    m : int
+        Number of open decay/scattering channels (m=0 recovers the
+        parent Hermitian ensemble exactly).
+    beta : {1, 2, 4}
+        Dyson index shared by the parent Hamiltonian H and the coupling
+        matrix V.
+    coupling : float, optional
+        Overall coupling strength scaling V (default 1.0); larger values
+        drive the system from the isolated-resonance regime towards
+        resonance trapping without changing beta or the number of
+        channels m.
+    """
+
+    def __init__(
+        self,
+        n: int,
+        m: int,
+        beta: int,
+        coupling: float = 1.0,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        if beta not in (1, 2, 4):
+            raise ValueError(f"beta must be 1, 2, or 4, got {beta}")
+        if m < 0:
+            raise ValueError(f"m (number of open channels) must be >= 0, got {m}")
+        super().__init__(n, seed=seed)
+        self.m = m
+        self.beta: float = beta
+        self.coupling = float(coupling)
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        n, m, beta = self.n, self.m, self.beta
+        h = _sample_hamiltonian(n, rng, beta)
+        if m > 0:
+            v = self.coupling * _sample_coupling(n, m, rng, beta)
+            gamma = v @ v.conj().T
+        else:
+            gamma = np.zeros_like(h)
+        h_eff = h - 0.5j * gamma
+        eigs = np.linalg.eigvals(h_eff)
+        if beta == 4:
+            # Exact Kramers double degeneracy (see module docstring) --
+            # keep one representative per pair, as CSE does.
+            order = np.lexsort((eigs.imag, eigs.real))
+            eigs = eigs[order][0::2]
+        return eigs.astype(complex)
+
+    def natural_scale(self) -> float:
+        # Re(eigenvalues) inherit the parent Hermitian ensemble's level
+        # scale (exactly, at m=0; approximately for weak-to-moderate
+        # coupling) -- see HermiteBetaEnsemble.natural_scale. Widths
+        # (Im part) have no comparably universal n-independent scale --
+        # they depend on m and coupling as well as n -- so this factor
+        # should be treated as a Re-axis convenience, not a full
+        # normalization of the complex plane.
+        return np.sqrt(self.n * self.beta)
+
+
+class EffGOE(EffectiveHamiltonianEnsemble):
+    """Effective Hamiltonian built on GOE (beta=1): time-reversal
+    invariant closed system, real coupling to the open channels."""
+
+    def __init__(
+        self,
+        n: int,
+        m: int,
+        coupling: float = 1.0,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        super().__init__(n, m, beta=1, coupling=coupling, seed=seed)
+
+
+class EffGUE(EffectiveHamiltonianEnsemble):
+    """Effective Hamiltonian built on GUE (beta=2): broken time-reversal
+    symmetry, complex coupling to the open channels."""
+
+    def __init__(
+        self,
+        n: int,
+        m: int,
+        coupling: float = 1.0,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        super().__init__(n, m, beta=2, coupling=coupling, seed=seed)
+
+
+class EffGSE(EffectiveHamiltonianEnsemble):
+    """Effective Hamiltonian built on GSE (beta=4): self-dual
+    (Kramers-degenerate) closed system, quaternionic coupling to the
+    open channels. ``n`` is the quaternionic dimension; each sample
+    produces n distinct complex resonances (each an exact Kramers pair
+    internally -- see module docstring)."""
+
+    def __init__(
+        self,
+        n: int,
+        m: int,
+        coupling: float = 1.0,
+        seed: int | np.random.Generator | None = None,
+    ) -> None:
+        super().__init__(n, m, beta=4, coupling=coupling, seed=seed)