physicskit 0.1.0__py3-none-any.whl

physicskit/rmt/ensembles/wishart.py

@@ -0,0 +1,88 @@
+"""Wishart (Laguerre) ensembles -- LOE, LUE, LSE -- plus the continuum
+Dyson-index generalization, built on the bidiagonal beta-Laguerre model
+(see ``physicskit.rmt.utils.tridiagonal.sample_laguerre_beta_eigenvalues``).
+
+References
+----------
+V. A. Marchenko, L. A. Pastur, "Distribution of eigenvalues for some sets
+of random matrices", Mat. Sb. 72 (1967) 507.
+I. Dumitriu, A. Edelman, J. Math. Phys. 43, 5830 (2002).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..utils.tridiagonal import sample_laguerre_beta_eigenvalues
+from .base import MatrixEnsemble
+
+
+class LaguerreBetaEnsemble(MatrixEnsemble):
+    """General beta-Laguerre (Wishart) ensemble.
+
+    Corresponds to an m x n rectangular data matrix (m "samples", n
+    "variables", m >= n) with i.i.d. unit-variance entries. beta=1, 2, 4
+    recover LOE, LUE, LSE exactly; any beta > 0 is a valid continuum
+    generalization.
+
+    ``n`` (the ensemble/matrix size, per the ``MatrixEnsemble`` base
+    class) is the number of variables; ``m`` is the number of samples,
+    with aspect ratio gamma = n / m controlling the Marchenko-Pastur
+    support.
+    """
+
+    def __init__(self, n: int, m: int, beta: float, seed: int | np.random.Generator | None = None) -> None:
+        """
+        Parameters
+        ----------
+        n : int
+            Number of variables (matrix dimension).
+        m : int
+            Number of samples; must be >= n.
+        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}")
+        if m < n:
+            raise ValueError(f"m (samples={m}) must be >= n (variables={n})")
+        super().__init__(n, seed=seed)
+        self.m = m
+        self.beta: float = float(beta)
+
+    @property
+    def gamma(self) -> float:
+        """Aspect ratio n/m controlling the Marchenko-Pastur support."""
+        return self.n / self.m
+
+    def _sample_eigenvalues(self, rng: np.random.Generator) -> np.ndarray:
+        return sample_laguerre_beta_eigenvalues(self.m, self.n, self.beta, rng)
+
+    def natural_scale(self) -> float:
+        # The bidiagonal construction already returns eigenvalues in the
+        # standard Marchenko-Pastur normalization (support
+        # [(1-sqrt(gamma))^2, (1+sqrt(gamma))^2]); no further rescaling
+        # needed.
+        return 1.0
+
+
+class LOE(LaguerreBetaEnsemble):
+    """Laguerre Orthogonal Ensemble (beta=1): real Wishart matrices."""
+
+    def __init__(self, n: int, m: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m, beta=1, seed=seed)
+
+
+class LUE(LaguerreBetaEnsemble):
+    """Laguerre Unitary Ensemble (beta=2): complex Wishart matrices."""
+
+    def __init__(self, n: int, m: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m, beta=2, seed=seed)
+
+
+class LSE(LaguerreBetaEnsemble):
+    """Laguerre Symplectic Ensemble (beta=4): quaternionic Wishart matrices."""
+
+    def __init__(self, n: int, m: int, seed: int | np.random.Generator | None = None) -> None:
+        super().__init__(n, m, beta=4, seed=seed)

physicskit/rmt/spectrum.py

@@ -0,0 +1,82 @@
+"""The result of sampling an ensemble: eigenvalues plus the metadata needed
+to compare them against theory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Spectrum:
+    """Eigenvalues drawn from a :class:`~physicskit.rmt.ensembles.base.MatrixEnsemble`."""
+
+    eigenvalues: np.ndarray
+    """numpy.ndarray, shape (n_samples, n): Raw (unnormalized) eigenvalues,
+    one row per independent draw."""
+
+    n: int
+    """int: Matrix dimension used to generate this spectrum."""
+
+    beta: float | None
+    """float or None: Dyson index of the ensemble that produced this
+    spectrum, or None for ensembles outside Dyson's threefold way (e.g.
+    ``BuresHallEnsemble``, ``GraphLaplacianEnsemble``)."""
+
+    ensemble: str
+    """str: Name of the ensemble class, for provenance/repr purposes."""
+
+    scale: float = 1.0
+    """float: Factor by which ``eigenvalues`` should be divided to reach
+    the ensemble's standard asymptotic normalization (e.g. semicircle
+    support [-2, 2] for the Gaussian ensembles). Set by the ensemble via
+    ``natural_scale()``."""
+
+    eigenvectors: np.ndarray | None = None
+    """numpy.ndarray, shape (n_samples, m, n), or None: Eigenvectors as
+    columns, matching ``eigenvalues`` column-for-column
+    (``eigenvectors[s][:, i]`` is the eigenvector for
+    ``eigenvalues[s, i]``). Only present when the ensemble was sampled
+    with ``sample(return_eigenvectors=True)``; None otherwise. ``m`` is
+    usually ``n`` but can differ for ensembles whose eigenvalue count
+    isn't exactly ``n`` (see ``n_samples`` elsewhere in this package for
+    the analogous eigenvalue-count caveat)."""
+
+    @property
+    def flat(self) -> np.ndarray:
+        """All eigenvalues from all samples, raveled into one 1-D array.
+
+        Returns
+        -------
+        numpy.ndarray
+            1-D array of all eigenvalues, shape ``(n_samples * eigenvalues.shape[1],)``.
+        """
+        return self.eigenvalues.ravel()
+
+    @property
+    def rescaled(self) -> np.ndarray:
+        """Eigenvalues divided by ``scale``.
+
+        This is the array to compare against a theoretical limiting
+        distribution.
+
+        Returns
+        -------
+        numpy.ndarray
+            Same shape as ``eigenvalues``.
+        """
+        return self.eigenvalues / self.scale
+
+    @property
+    def n_samples(self) -> int:
+        """Number of independent realizations drawn.
+
+        Returns
+        -------
+        int
+        """
+        return self.eigenvalues.shape[0]
+
+    def __repr__(self) -> str:
+        return f"Spectrum(ensemble={self.ensemble!r}, n={self.n}, beta={self.beta}, n_samples={self.n_samples})"

physicskit/rmt/stats/__init__.py

@@ -0,0 +1,160 @@
+from .characteristic_polynomial import (
+    characteristic_polynomial_empirical_moment,
+    keating_snaith_moment,
+)
+from .circular_law import circular_law_radial_cdf, circular_law_radial_pdf
+from .correlations import (
+    k_point_correlation,
+    kernel_d,
+    kernel_i,
+    kernel_s,
+    pair_correlation_estimate,
+    sine_kernel_r2,
+)
+from .density import empirical_density, semicircle_cdf, semicircle_pdf
+from .entanglement import page_curve_average_entropy, von_neumann_entropy
+from .free_probability import (
+    invert_stieltjes_transform_numerical,
+    r_transform_marchenko_pastur,
+    r_transform_numerical,
+    r_transform_semicircle,
+    stieltjes_transform_empirical,
+    stieltjes_transform_semicircle,
+)
+from .localization import (
+    generalized_ipr,
+    inverse_participation_ratio,
+    inverse_participation_ratio_quaternionic,
+    ipr_theory,
+    mass_exponent,
+    multifractal_dimension,
+    participation_ratio,
+    singularity_spectrum,
+)
+from .marchenko_pastur import mp_cdf, mp_pdf, mp_support
+from .pt_symmetric import (
+    eigenvector_condition_number,
+    find_exceptional_points,
+    mean_exceptional_point_count,
+    real_axis_spacings,
+    real_eigenvalue_fraction,
+    semi_poisson_cdf,
+    semi_poisson_pdf,
+)
+from .ratios import RatioSurmise, ratio_statistics
+from .real_ginibre import (
+    real_eigenvalue_count_asymptotic,
+    real_eigenvalue_count_empirical,
+    real_eigenvalue_density_asymptotic,
+    real_eigenvalue_density_empirical,
+)
+from .rigidity import (
+    number_variance_empirical,
+    number_variance_goe_asymptotic,
+    number_variance_gse_asymptotic,
+    number_variance_gue_exact,
+    number_variance_poisson,
+    number_variance_theory,
+    spectral_rigidity_empirical,
+    spectral_rigidity_poisson,
+    spectral_rigidity_theory,
+)
+from .single_ring import (
+    annulus_radial_cdf,
+    annulus_radial_pdf,
+    single_ring_radii,
+    single_ring_radii_wishart_theory,
+)
+from .spacing import (
+    circular_spacings,
+    nearest_neighbor_spacings,
+    wigner_surmise_cdf,
+    wigner_surmise_params,
+    wigner_surmise_pdf,
+    wigner_surmise_samples,
+)
+from .tracy_widom import (
+    largest_eigenvalues,
+    tracy_widom_cdf,
+    tracy_widom_edge_scale,
+    tracy_widom_rvs,
+)
+from .truncated_unitary import truncated_unitary_edge_radius
+from .unfolding import unfold_by_cdf
+from .wachter import wachter_cdf, wachter_pdf, wachter_support
+
+__all__ = [
+    "empirical_density",
+    "semicircle_pdf",
+    "semicircle_cdf",
+    "unfold_by_cdf",
+    "nearest_neighbor_spacings",
+    "circular_spacings",
+    "wigner_surmise_params",
+    "wigner_surmise_pdf",
+    "wigner_surmise_cdf",
+    "wigner_surmise_samples",
+    "ratio_statistics",
+    "RatioSurmise",
+    "mp_pdf",
+    "mp_cdf",
+    "mp_support",
+    "pair_correlation_estimate",
+    "sine_kernel_r2",
+    "k_point_correlation",
+    "circular_law_radial_pdf",
+    "circular_law_radial_cdf",
+    "largest_eigenvalues",
+    "tracy_widom_cdf",
+    "tracy_widom_edge_scale",
+    "tracy_widom_rvs",
+    "wachter_pdf",
+    "wachter_cdf",
+    "wachter_support",
+    "truncated_unitary_edge_radius",
+    "keating_snaith_moment",
+    "characteristic_polynomial_empirical_moment",
+    "stieltjes_transform_empirical",
+    "stieltjes_transform_semicircle",
+    "r_transform_semicircle",
+    "r_transform_marchenko_pastur",
+    "invert_stieltjes_transform_numerical",
+    "r_transform_numerical",
+    "number_variance_empirical",
+    "number_variance_poisson",
+    "number_variance_gue_exact",
+    "number_variance_goe_asymptotic",
+    "number_variance_gse_asymptotic",
+    "number_variance_theory",
+    "spectral_rigidity_empirical",
+    "spectral_rigidity_poisson",
+    "spectral_rigidity_theory",
+    "von_neumann_entropy",
+    "page_curve_average_entropy",
+    "inverse_participation_ratio",
+    "inverse_participation_ratio_quaternionic",
+    "generalized_ipr",
+    "mass_exponent",
+    "multifractal_dimension",
+    "singularity_spectrum",
+    "participation_ratio",
+    "ipr_theory",
+    "real_eigenvalue_count_empirical",
+    "real_eigenvalue_count_asymptotic",
+    "real_eigenvalue_density_empirical",
+    "real_eigenvalue_density_asymptotic",
+    "single_ring_radii",
+    "single_ring_radii_wishart_theory",
+    "annulus_radial_pdf",
+    "annulus_radial_cdf",
+    "real_eigenvalue_fraction",
+    "find_exceptional_points",
+    "mean_exceptional_point_count",
+    "eigenvector_condition_number",
+    "semi_poisson_pdf",
+    "semi_poisson_cdf",
+    "real_axis_spacings",
+    "kernel_s",
+    "kernel_d",
+    "kernel_i",
+]

physicskit/rmt/stats/characteristic_polynomial.py

@@ -0,0 +1,77 @@
+"""Moments of the CUE characteristic polynomial (Keating-Snaith).
+
+Reference: J. P. Keating, N. C. Snaith, "Random matrix theory and
+zeta(1/2+it)", Commun. Math. Phys. 214 (2000) 57 -- moments of the CUE
+characteristic polynomial as a model for moments of the Riemann zeta
+function on the critical line (following C. P. Hughes, and the earlier
+exact CUE moment formula of P. Diaconis, M. Shahshahani, "On the
+eigenvalues of random matrices", J. Appl. Probab. 31A (1994) 49).
+
+For U an n x n Haar-random unitary matrix (CUE) and its characteristic
+polynomial evaluated on the unit circle, Z_n(theta) = det(I - U*e^{-i*theta}),
+the exact moments (for positive integer k, any theta -- the Haar measure
+is rotation-invariant, so the value does not depend on theta) are
+
+    ``E[|Z_n(theta)|^(2k)] = prod_{j=0}^{n-1} j! * (j+2k)! / (j+k)!^2``
+
+verified numerically here against direct Monte Carlo (CUE via
+``physicskit.rmt.utils.haar.haar_unitary``) at several (n, k) pairs (matching to
+within 1-2%, consistent with Monte Carlo noise) before being trusted --
+see ``tests/test_characteristic_polynomial.py``. A useful special case
+noticed and checked during that verification: k=1 gives exactly n+1 (the
+product telescopes), a simple closed form worth knowing independently of
+the general product formula.
+"""
+
+from math import factorial
+
+import numpy as np
+
+
+def keating_snaith_moment(n: int, k: int) -> float:
+    """Exact CUE characteristic polynomial moment
+    ``E[|Z_n(theta)|^(2k)] = prod_{j=0}^{n-1} j!*(j+2k)! / (j+k)!^2``.
+
+    Parameters
+    ----------
+    n : int
+        Matrix dimension.
+    k : int
+        Moment order (positive integer).
+
+    Returns
+    -------
+    float
+    """
+    if k < 1:
+        raise ValueError(f"k must be a positive integer, got {k}")
+    product = 1.0
+    for j in range(n):
+        product *= factorial(j) * factorial(j + 2 * k) / factorial(j + k) ** 2
+    return product
+
+
+def characteristic_polynomial_empirical_moment(eigenvalues: np.ndarray, k: int, theta: float = 0.0) -> float:
+    """Empirical mean of ``|det(I - U*e^{-i*theta})|^(2k)``, computed
+    directly from a CUE spectrum's eigenvalues (the phases of U):
+    det(I - U*e^{-i*theta}) = prod_j (1 - e^{i*(phi_j - theta)}) for
+    eigenvalue phases phi_j.
+
+    Parameters
+    ----------
+    eigenvalues : numpy.ndarray, shape (n_samples, n)
+        CUE eigenvalue phases (e.g. ``CUE.sample(...).eigenvalues``, or
+        ``.rescaled`` -- either works, since only the phase matters).
+    k : int
+        Moment order (positive integer).
+    theta : float, optional
+
+    Returns
+    -------
+    float
+    """
+    if k < 1:
+        raise ValueError(f"k must be a positive integer, got {k}")
+    eigenvalues = np.asarray(eigenvalues)
+    z = np.prod(1.0 - np.exp(1j * (eigenvalues - theta)), axis=-1)
+    return float(np.mean(np.abs(z) ** (2 * k)))

physicskit/rmt/stats/circular_law.py

@@ -0,0 +1,54 @@
+"""The circular law: limiting eigenvalue density of the Ginibre
+ensembles (uniform on the unit disk after the sqrt(n) rescaling).
+
+Reference: J. Ginibre, J. Math. Phys. 6 (1965) 440.
+
+Note on naming: this is a completely different concept from the
+"circular ensembles" (COE/CUE/CSE, Dyson 1962) in
+``physicskit.rmt.ensembles.circular`` -- the shared word "circular" refers to
+two unrelated things in the RMT literature (a disk-shaped eigenvalue
+density here, vs. eigenvalues literally on the unit circle there). Do
+not confuse the modules.
+
+For a uniform distribution on the unit disk, the radial marginal
+(density of eigenvalue *magnitude* ``|lambda|``, integrating out the
+angle) has PDF f(r) = 2r and CDF F(r) = r^2 on [0, 1] -- an ordinary 1-D
+distribution, which is what makes it possible to validate via the
+existing KS/Wasserstein ``Benchmark`` machinery (unlike the raw 2-D
+disk density itself).
+"""
+
+import numpy as np
+
+
+def circular_law_radial_pdf(r: np.ndarray) -> np.ndarray:
+    """Radial marginal density of the circular law: f(r) = 2r on [0, 1].
+
+    Parameters
+    ----------
+    r : numpy.ndarray
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    r = np.asarray(r, dtype=float)
+    out = np.zeros_like(r)
+    mask = (r >= 0) & (r <= 1)
+    out[mask] = 2.0 * r[mask]
+    return out
+
+
+def circular_law_radial_cdf(r: np.ndarray) -> np.ndarray:
+    """Radial marginal CDF of the circular law: F(r) = r^2 on [0, 1].
+
+    Parameters
+    ----------
+    r : numpy.ndarray
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    r = np.asarray(r, dtype=float)
+    return np.clip(r, 0.0, 1.0) ** 2

physicskit/rmt/stats/correlations.py

@@ -0,0 +1,162 @@
+"""Two-point (pair) correlation function of a point process, and the
+exact sine-kernel result for the Circular Unitary Ensemble.
+
+Scope note: the exact bulk two-point correlation function for CUE
+(beta=2) has the simple closed determinantal form used here. The
+corresponding beta=1 (COE) and beta=4 (CSE) results also reduce to
+sine-kernel-type expressions, but through the fuller Pfaffian
+point-process machinery: a 2x2 matrix kernel built from companion
+functions "S" (the same sine kernel as beta=2), "D" = S', and
+"I" = integral of S (Mehta, "Random Matrices", Ch. 6-7; Dyson's
+original papers). ``kernel_s``, ``kernel_d``, ``kernel_i`` below
+implement these three individually exact, independently verifiable
+building blocks (D and I are just the derivative and antiderivative of
+the already-validated sine kernel S).
+
+The COMBINATION of S, D, I into R_2 for beta=1, 4 is NOT implemented
+here: an attempted reconstruction (from memory) of the standard
+"R_2 = 1 - S^2 + D*I"-type combination was checked here two ways before
+being ruled out -- (1) a small-r Taylor expansion shows that
+combination can only ever produce a QUADRATIC leading term in r
+(D*I ~ r^2 near r=0, same order as 1-S^2), which is structurally
+incompatible with the well-established LINEAR level-repulsion exponent
+required for beta=1; and (2) fitting against direct Monte Carlo COE
+pair-correlation data (see ``pair_correlation_estimate``) confirmed no
+value of an overall coefficient on the D*I term brings it into
+agreement. Rather than ship a formula known to be structurally wrong,
+only the qualitative, robustly-verified physics is asserted here (see
+``tests/test_correlations.py``): level repulsion strength orders
+CSE >> CUE >> COE >> Poisson (uncorrelated) near r=0, and COE's own
+empirical correlation is consistent with genuine (sub-quadratic) level
+repulsion. The exact beta=1, 4 closed forms remain deferred.
+
+Reference: F. J. Dyson, J. Math. Phys. 3 (1962) 140, 157, 166.
+"""
+
+import numpy as np
+from scipy.special import sici
+
+from ..spectrum import Spectrum
+
+
+def pair_correlation_estimate(spectrum: Spectrum, r_max: float = 4.0, n_bins: int = 60) -> tuple[np.ndarray, np.ndarray]:
+    """Estimate the two-point correlation function R_2(r) of an unfolded
+    point process (e.g. a circular ensemble's phases) by histogramming
+    pairwise circular distances.
+
+    Convention note: pairwise distances are unsigned, so a bin at
+    separation r receives contributions from *both* sides of each
+    reference point; the standard R_2(r) convention is defined per
+    signed separation, so raw counts must be divided by 2 in addition to
+    the usual (n_points * bin_width) normalization -- verified during
+    development against a Poisson (uncorrelated) reference process,
+    where R_2(r) = 1 identically and the un-halved estimator gave
+    exactly 2.0 instead.
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+        A circular-ensemble spectrum (``spectrum.rescaled`` already
+        unfolded to unit mean spacing on a circle of circumference n).
+    r_max : float
+        Maximum separation to histogram.
+    n_bins : int
+
+    Returns
+    -------
+    centers, r2_estimate : numpy.ndarray
+    """
+    edges = np.linspace(0.0, r_max, n_bins + 1)
+    counts = np.zeros(n_bins)
+    total_points = 0
+    for row in spectrum.rescaled:
+        n = len(row)
+        diffs = np.abs(np.subtract.outer(row, row))
+        diffs = np.minimum(diffs, n - diffs)  # circular distance
+        np.fill_diagonal(diffs, np.inf)
+        flat = diffs[diffs <= r_max]
+        counts += np.histogram(flat, bins=edges)[0]
+        total_points += n
+    bin_width = edges[1] - edges[0]
+    centers = 0.5 * (edges[:-1] + edges[1:])
+    r2_estimate = counts / (2.0 * total_points * bin_width)
+    return centers, r2_estimate
+
+
+def sine_kernel_r2(r: np.ndarray) -> np.ndarray:
+    """Exact CUE (beta=2) two-point correlation function:
+    R_2(r) = 1 - [sin(pi*r) / (pi*r)]^2, with the removable singularity
+    at r=0 handled via its limit (R_2(0) = 0, full level repulsion)."""
+    r = np.asarray(r, dtype=float)
+    out = np.ones_like(r)
+    mask = np.abs(r) > 1e-8
+    out[mask] = 1.0 - (np.sin(np.pi * r[mask]) / (np.pi * r[mask])) ** 2
+    out[~mask] = 0.0
+    return out
+
+
+def kernel_s(r: np.ndarray) -> np.ndarray:
+    """The "S" Pfaffian-point-process kernel: S(r) = sin(pi*r)/(pi*r),
+    the same sine kernel as beta=2 (see module docstring's scope note
+    on why only this building block, not the full beta=1/4 R_2
+    combination, is implemented)."""
+    r = np.asarray(r, dtype=float)
+    out = np.ones_like(r)
+    mask = np.abs(r) > 1e-10
+    out[mask] = np.sin(np.pi * r[mask]) / (np.pi * r[mask])
+    return out
+
+
+def kernel_d(r: np.ndarray) -> np.ndarray:
+    """The "D" Pfaffian-point-process kernel: D(r) = dS/dr (an odd
+    function, since S is even)."""
+    r = np.asarray(r, dtype=float)
+    out = np.zeros_like(r)
+    mask = np.abs(r) > 1e-6
+    x = np.pi * r[mask]
+    out[mask] = np.pi * (x * np.cos(x) - np.sin(x)) / x**2
+    return out
+
+
+def kernel_i(r: np.ndarray) -> np.ndarray:
+    """The "I" Pfaffian-point-process kernel: I(r) = integral_0^r S(t) dt
+    = Si(pi*r)/pi, where Si is the sine integral function."""
+    si, _ = sici(np.pi * np.asarray(r, dtype=float))
+    return si / np.pi
+
+
+def k_point_correlation(positions: np.ndarray) -> float:
+    """Exact CUE (beta=2) k-point correlation function at the given
+    positions: R_k(x_1, ..., x_k) = det[S(x_i - x_j)]_{i,j=1}^k, the
+    defining property of a determinantal point process (Soshnikov,
+    "Determinantal random point fields", Russian Math. Surveys 55
+    (2000) 923; also Mehta Ch. 5) with kernel S (``kernel_s``, the same
+    sine kernel already validated for k=2 via ``sine_kernel_r2``).
+
+    Reduces EXACTLY to ``sine_kernel_r2`` at k=2 (checked directly:
+    ``det[[S(0),S(r)],[S(-r),S(0)]] = 1 - S(r)^2`` since S is even) --
+    this is the anchor this generalization rests on, since a fresh
+    Monte Carlo estimate of a k=3 (or higher) correlation value from
+    ensemble samples turned out to have a subtle reference-point-
+    selection bias that made a first attempt at direct verification
+    unreliable. What IS verified here (see ``tests/test_correlations.py``):
+    the formula vanishes exactly whenever two positions coincide (level
+    repulsion at all orders -- an algebraic property of a determinant
+    with a repeated row) and correctly factorizes,
+    ``R_3(x1, x2, x3) -> R_2(x1, x2)`` as ``x3`` moves to infinity
+    (cluster decomposition, checked numerically to 6 significant figures).
+
+    Parameters
+    ----------
+    positions : numpy.ndarray, shape (k,)
+        The k positions (unfolded, i.e. in units of the mean spacing).
+
+    Returns
+    -------
+    float
+    """
+    positions = np.asarray(positions, dtype=float)
+    k = len(positions)
+    diff = positions[:, None] - positions[None, :]
+    kernel_matrix = kernel_s(diff.ravel()).reshape(k, k)
+    return float(np.linalg.det(kernel_matrix))

physicskit/rmt/stats/density.py

@@ -0,0 +1,70 @@
+"""Empirical spectral density (ESD) and the Wigner semicircle reference
+density/CDF."""
+
+import numpy as np
+
+from ..spectrum import Spectrum
+
+
+def empirical_density(spectrum: Spectrum, bins: int = 100, rescaled: bool = True, density: bool = True) -> tuple[np.ndarray, np.ndarray]:
+    """Histogram-based empirical spectral density of a Spectrum.
+
+    Parameters
+    ----------
+    spectrum : physicskit.rmt.spectrum.Spectrum
+    bins : int
+    rescaled : bool
+        If True (default), histogram the ensemble-normalized eigenvalues
+        (``spectrum.rescaled``) rather than the raw ones.
+    density : bool
+        Passed through to ``numpy.histogram``.
+
+    Returns
+    -------
+    centers, counts : numpy.ndarray
+        Bin centers and (normalized, if density=True) counts.
+    """
+    data = spectrum.rescaled.ravel() if rescaled else spectrum.flat
+    counts, edges = np.histogram(data, bins=bins, density=density)  # type: ignore[call-overload]
+    centers = 0.5 * (edges[:-1] + edges[1:])
+    return centers, counts
+
+
+def semicircle_pdf(x: np.ndarray, radius: float = 2.0) -> np.ndarray:
+    """Wigner semicircle probability density on [-radius, radius].
+
+    f(x) = 2 / (pi * radius^2) * sqrt(radius^2 - x^2)
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    radius : float, optional
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    x = np.asarray(x, dtype=float)
+    out = np.zeros_like(x)
+    mask = np.abs(x) <= radius
+    out[mask] = 2.0 / (np.pi * radius**2) * np.sqrt(radius**2 - x[mask] ** 2)
+    return out
+
+
+def semicircle_cdf(x: np.ndarray, radius: float = 2.0) -> np.ndarray:
+    """Wigner semicircle cumulative distribution function on
+    [-radius, radius].
+
+    F(x) = 1/2 + x*sqrt(radius^2 - x^2) / (pi * radius^2) + arcsin(x/radius) / pi
+
+    Parameters
+    ----------
+    x : numpy.ndarray
+    radius : float, optional
+
+    Returns
+    -------
+    numpy.ndarray
+    """
+    x = np.clip(np.asarray(x, dtype=float), -radius, radius)
+    return 0.5 + x * np.sqrt(radius**2 - x**2) / (np.pi * radius**2) + np.arcsin(x / radius) / np.pi