freealg 0.7.17__py3-none-any.whl → 0.7.18__py3-none-any.whl

freealg/_free_form/free_form.py

@@ -13,7 +13,7 @@
 
 import numpy
 from functools import partial
-from .._util import resolve_complex_dtype, compute_eig
+from .._util import compute_eig
 from ._density_util import kde, force_density
 from ._jacobi import jacobi_sample_proj, jacobi_kernel_proj, jacobi_density, \
     jacobi_stieltjes
@@ -21,11 +21,13 @@ from ._chebyshev import chebyshev_sample_proj, chebyshev_kernel_proj, \
     chebyshev_density, chebyshev_stieltjes
 from ._damp import jackson_damping, lanczos_damping, fejer_damping, \
     exponential_damping, parzen_damping
-from ._plot_util import plot_fit, plot_density, plot_hilbert, plot_stieltjes
+from ._plot_util import plot_fit
+from ..visualization._plot_util import plot_density, plot_hilbert, \
+    plot_stieltjes
 from ._pade import fit_pade, eval_pade
 from ._decompress import decompress
-from ._sample import sample
-from ._support import supp
+from .._support import supp
+from .._base_form import BaseForm
 
 # Fallback to previous numpy API
 if not hasattr(numpy, 'trapezoid'):
@@ -38,7 +40,7 @@ __all__ = ['FreeForm']
 # Free Form
 # =========
 
-class FreeForm(object):
+class FreeForm(BaseForm):
     """
     Free probability for large matrices.
 
@@ -143,12 +145,7 @@ class FreeForm(object):
         Initialization.
         """
 
-        self.A = None
-        self.eig = None
-        self.delta = delta    # Offset above real axis to apply Plemelj formula
-
-        # Data type for complex arrays
-        self.dtype = resolve_complex_dtype(dtype)
+        super().__init__(delta, dtype)
 
         # Eigenvalues
         if A.ndim == 1:
@@ -467,27 +464,6 @@ class FreeForm(object):
 
         return self.psi
 
-    # =============
-    # generate grid
-    # =============
-
-    def _generate_grid(self, scale, extend=1.0, N=500):
-        """
-        Generate a grid of points to evaluate density / Hilbert / Stieltjes
-        transforms.
-        """
-
-        radius = 0.5 * (self.lam_p - self.lam_m)
-        center = 0.5 * (self.lam_p + self.lam_m)
-
-        x_min = numpy.floor(extend * (center - extend * radius * scale))
-        x_max = numpy.ceil(extend * (center + extend * radius * scale))
-
-        x_min /= extend
-        x_max /= extend
-
-        return numpy.linspace(x_min, x_max, N)
-
     # =======
     # density
     # =======
@@ -1025,338 +1001,3 @@ class FreeForm(object):
                          label='Decompression', latex=latex, save=save)
 
         return rho, x
-
-    # ========
-    # eigvalsh
-    # ========
-
-    def eigvalsh(self, size=None, seed=None, **kwargs):
-        """
-        Estimate the eigenvalues.
-
-        This function estimates the eigenvalues of the freeform matrix
-        or a larger matrix containing it using free decompression.
-
-        Parameters
-        ----------
-
-        size : int, default=None
-            The size of the matrix containing :math:`\\mathbf{A}` to estimate
-            eigenvalues of. If None, returns estimates of the eigenvalues of
-            :math:`\\mathbf{A}` itself.
-
-        seed : int, default=None
-            The seed for the Quasi-Monte Carlo sampler.
-
-        **kwargs : dict, optional
-            Pass additional options to the underlying
-            :func:`FreeForm.decompress` function.
-
-        Returns
-        -------
-
-        eigs : numpy.array
-            Eigenvalues of decompressed matrix
-
-        See Also
-        --------
-
-        FreeForm.decompress
-        FreeForm.cond
-
-        Notes
-        -----
-
-        All arguments to the `.decompress()` procedure can be provided.
-
-        Examples
-        --------
-
-        .. code-block:: python
-            :emphasize-lines: 1
-
-            >>> from freealg import FreeForm
-        """
-
-        if size is None:
-            size = self.n
-
-        rho, x = self.decompress(size, **kwargs)
-        eigs = numpy.sort(sample(x, rho, size, method='qmc', seed=seed))
-
-        return eigs
-
-    # ====
-    # cond
-    # ====
-
-    def cond(self, size=None, seed=None, **kwargs):
-        """
-        Estimate the condition number.
-
-        This function estimates the condition number of the matrix
-        :math:`\\mathbf{A}` or a larger matrix containing :math:`\\mathbf{A}`
-        using free decompression.
-
-        Parameters
-        ----------
-
-        size : int, default=None
-            The size of the matrix containing :math:`\\mathbf{A}` to estimate
-            eigenvalues of. If None, returns estimates of the eigenvalues of
-            :math:`\\mathbf{A}` itself.
-
-        **kwargs : dict, optional
-            Pass additional options to the underlying
-            :func:`FreeForm.decompress` function.
-
-        Returns
-        -------
-
-        c : float
-            Condition number
-
-        See Also
-        --------
-
-        FreeForm.eigvalsh
-        FreeForm.norm
-        FreeForm.slogdet
-        FreeForm.trace
-
-        Examples
-        --------
-
-        .. code-block:: python
-            :emphasize-lines: 1
-
-            >>> from freealg import FreeForm
-        """
-
-        eigs = self.eigvalsh(size=size, **kwargs)
-        return eigs.max() / eigs.min()
-
-    # =====
-    # trace
-    # =====
-
-    def trace(self, size=None, p=1.0, seed=None, **kwargs):
-        """
-        Estimate the trace of a power.
-
-        This function estimates the trace of the matrix power
-        :math:`\\mathbf{A}^p` of the freeform or that of a larger matrix
-        containing it.
-
-        Parameters
-        ----------
-
-        size : int, default=None
-            The size of the matrix containing :math:`\\mathbf{A}` to estimate
-            eigenvalues of. If None, returns estimates of the eigenvalues of
-            :math:`\\mathbf{A}` itself.
-
-        p : float, default=1.0
-            The exponent :math:`p` in :math:`\\mathbf{A}^p`.
-
-        seed : int, default=None
-            The seed for the Quasi-Monte Carlo sampler.
-
-        **kwargs : dict, optional
-            Pass additional options to the underlying
-            :func:`FreeForm.decompress` function.
-
-        Returns
-        -------
-
-        trace : float
-            matrix trace
-
-        See Also
-        --------
-
-        FreeForm.eigvalsh
-        FreeForm.cond
-        FreeForm.slogdet
-        FreeForm.norm
-
-        Notes
-        -----
-
-        The trace is highly amenable to subsampling: under free decompression
-        the average eigenvalue is assumed constant, so the trace increases
-        linearly. Traces of powers fall back to :func:`eigvalsh`.
-        All arguments to the `.decompress()` procedure can be provided.
-
-        Examples
-        --------
-
-        .. code-block:: python
-            :emphasize-lines: 1
-
-            >>> from freealg import FreeForm
-        """
-
-        if numpy.isclose(p, 1.0):
-            return numpy.mean(self.eig) * (size / self.n)
-
-        eig = self.eigvalsh(size=size, seed=seed, **kwargs)
-        return numpy.sum(eig ** p)
-
-    # =======
-    # slogdet
-    # =======
-
-    def slogdet(self, size=None, seed=None, **kwargs):
-        """
-        Estimate the sign and logarithm of the determinant.
-
-        This function estimates the *slogdet* of the freeform or that of
-        a larger matrix containing it using free decompression.
-
-        Parameters
-        ----------
-
-        size : int, default=None
-            The size of the matrix containing :math:`\\mathbf{A}` to estimate
-            eigenvalues of. If None, returns estimates of the eigenvalues of
-            :math:`\\mathbf{A}` itself.
-
-        seed : int, default=None
-            The seed for the Quasi-Monte Carlo sampler.
-
-        Returns
-        -------
-
-        sign : float
-            Sign of determinant
-
-        ld : float
-            natural logarithm of the absolute value of the determinant
-
-        See Also
-        --------
-
-        FreeForm.eigvalsh
-        FreeForm.cond
-        FreeForm.trace
-        FreeForm.norm
-
-        Notes
-        -----
-
-        All arguments to the `.decompress()` procedure can be provided.
-
-        Examples
-        --------
-
-        .. code-block:: python
-            :emphasize-lines: 1
-
-            >>> from freealg import FreeForm
-        """
-
-        eigs = self.eigvalsh(size=size, seed=seed, **kwargs)
-        sign = numpy.prod(numpy.sign(eigs))
-        ld = numpy.sum(numpy.log(numpy.abs(eigs)))
-        return sign, ld
-
-    # ====
-    # norm
-    # ====
-
-    def norm(self, size=None, order=2, seed=None, **kwargs):
-        """
-        Estimate the Schatten norm.
-
-        This function estimates the norm of the freeform or a larger
-        matrix containing it using free decompression.
-
-        Parameters
-        ----------
-
-        size : int, default=None
-            The size of the matrix containing :math:`\\mathbf{A}` to estimate
-            eigenvalues of. If None, returns estimates of the eigenvalues of
-            :math:`\\mathbf{A}` itself.
-
-        order : {float, ``''inf``, ``'-inf'``, ``'fro'``, ``'nuc'``}, default=2
-            Order of the norm.
-
-            * float :math:`p`: Schatten p-norm.
-            * ``'inf'``: Largest absolute eigenvalue
-              :math:`\\max \\vert \\lambda_i \\vert)`
-            * ``'-inf'``: Smallest absolute eigenvalue
-              :math:`\\min \\vert \\lambda_i \\vert)`
-            * ``'fro'``: Frobenius norm corresponding to :math:`p=2`
-            * ``'nuc'``: Nuclear (or trace) norm corresponding to :math:`p=1`
-
-        seed : int, default=None
-            The seed for the Quasi-Monte Carlo sampler.
-
-        **kwargs : dict, optional
-            Pass additional options to the underlying
-            :func:`FreeForm.decompress` function.
-
-        Returns
-        -------
-
-        norm : float
-            matrix norm
-
-        See Also
-        --------
-
-        FreeForm.eigvalsh
-        FreeForm.cond
-        FreeForm.slogdet
-        FreeForm.trace
-
-        Notes
-        -----
-
-        Thes Schatten :math:`p`-norm is defined by
-
-        .. math::
-
-            \\Vert \\mathbf{A} \\Vert_p = \\left(
-            \\sum_{i=1}^N \\vert \\lambda_i \\vert^p \\right)^{1/p}.
-
-        Examples
-        --------
-
-        .. code-block:: python
-            :emphasize-lines: 1
-
-            >>> from freealg import FreeForm
-        """
-
-        eigs = self.eigvalsh(size, seed=seed, **kwargs)
-
-        # Check order type and convert to float
-        if order == 'nuc':
-            order = 1
-        elif order == 'fro':
-            order = 2
-        elif order == 'inf':
-            order = float('inf')
-        elif order == '-inf':
-            order = -float('inf')
-        elif not isinstance(order,
-                            (int, float, numpy.integer, numpy.floating)) \
-                and not isinstance(order, (bool, numpy.bool_)):
-            raise ValueError('"order" is invalid.')
-
-        # Compute norm
-        if numpy.isinf(order) and not numpy.isneginf(order):
-            norm_ = max(numpy.abs(eigs))
-
-        elif numpy.isneginf(order):
-            norm_ = min(numpy.abs(eigs))
-
-        elif isinstance(order, (int, float, numpy.integer, numpy.floating)) \
-                and not isinstance(order, (bool, numpy.bool_)):
-            norm_q = numpy.sum(numpy.abs(eigs)**order)
-            norm_ = norm_q**(1.0 / order)
-
-        return norm_

freealg/_util.py

@@ -14,7 +14,7 @@
 import numpy
 import scipy
 
-__all__ = ['resolve_complex_dtype', 'compute_eig', 'subsample_matrix']
+__all__ = ['resolve_complex_dtype', 'compute_eig', 'submatrix']
 
 
 # =====================
@@ -72,24 +72,72 @@ def compute_eig(A, lower=False):
     return eig
 
 
-# ================
-# subsample matrix
-# ================
+# =========
+# submatrix
+# =========
 
-def subsample_matrix(matrix, submatrix_size, seed=None):
+def submatrix(matrix, size, paired=True, seed=None):
     """
-    Generate a random subsample of a larger matrix
+    Randomly sample a submatrix from a larger matrix.
+
+    Parameters
+    ----------
+
+    matrix : numpy.ndarray
+        A 2D square array
+
+    size : int
+        Number of rows and columns of the submatrix
+
+    paired : bool, default=True
+        If `True`, the rows and columns are sampled with the same random
+        indices. If `False`, separate random indices are used for selecting
+        rows and columns.
+
+    seed : int, default=None
+        Seed for random number generation. If `None`, results will not be
+        reproducible.
+
+    Returns
+    -------
+
+    sub : numpy.ndarray
+        A 2D array with the number of rows/columns specified by ``size``.
+
+    See Also
+    --------
+
+    freealg.sample
+
+    Examples
+    --------
+
+    .. code-block:: python
+        :emphasize-lines: 5
+
+        >>> import numpy
+        >>> from freealg import submatrix
+
+        >>> A = numpy.random.randn(1000, 1000)
+        >>> B = submatrix(A, size=500, paired=True, seed=0)
     """
 
     if matrix.shape[0] != matrix.shape[1]:
         raise ValueError("Matrix must be square")
 
     n = matrix.shape[0]
-    if submatrix_size > n:
-        raise ValueError("Submatrix size cannot exceed matrix size")
+    if size > n:
+        raise ValueError("Submatrix size cannot exceed matrix size.")
 
     rng = numpy.random.default_rng(seed)
-    idx = rng.choice(n, size=submatrix_size, replace=False)
-    idx = numpy.sort(idx)  # optional, preserves original ordering
 
-    return matrix[numpy.ix_(idx, idx)]
+    idx_row = rng.choice(n, size=size, replace=False)
+    idx_row = numpy.sort(idx_row)  # optional, preserves original ordering
+
+    if paired:
+        idx_col = idx_row
+    else:
+        idx_col = rng.choice(n, size=size, replace=False)
+        idx_col = numpy.sort(idx_col)  # optional, preserves original ordering
+
+    return matrix[numpy.ix_(idx_row, idx_col)]

freealg/distributions/__init__.py

@@ -15,7 +15,8 @@ from ._chiral_block import ChiralBlock
 from ._deformed_wigner import DeformedWigner
 from ._deformed_marchenko_pastur import DeformedMarchenkoPastur
 from ._compound_poisson import CompoundPoisson
+from ._fuss_catalan import FussCatalan
 
 __all__ = ['MarchenkoPastur', 'Wigner', 'KestenMcKay', 'Wachter', 'Meixner',
            'ChiralBlock', 'DeformedWigner', 'DeformedMarchenkoPastur',
-           'CompoundPoisson']
+           'CompoundPoisson', 'FussCatalan']

freealg/distributions/_base_distribution.py

@@ -0,0 +1,163 @@
+# SPDX-FileCopyrightText: Copyright 2025, Siavash Ameli <sameli@berkeley.edu>
+# SPDX-License-Identifier: BSD-3-Clause
+# SPDX-FileType: SOURCE
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the license found in the LICENSE.txt file in the root
+# directory of this source tree.
+
+
+# =======
+# Imports
+# =======
+
+import numpy
+from scipy.interpolate import interp1d
+from ..visualization._plot_util import plot_samples
+
+try:
+    from scipy.integrate import cumtrapz
+except ImportError:
+    from scipy.integrate import cumulative_trapezoid as cumtrapz
+from scipy.stats import qmc
+
+
+# =================
+# Base Distribution
+# =================
+
+class BaseDistribution(object):
+    """
+    Base class for distributions.
+    """
+
+    # ====
+    # init
+    # ====
+
+    def __init__(self):
+        """
+        """
+
+        self.lam_m = None
+        self.lam_p = None
+
+    # ======
+    # sample
+    # ======
+
+    def sample(self, size, x_min=None, x_max=None, method='qmc', seed=None,
+               plot=False, latex=False, save=False):
+        """
+        Sample from distribution.
+
+        Parameters
+        ----------
+
+        size : int
+            Size of sample.
+
+        x_min : float, default=None
+            Minimum of sample values. If `None`, the left edge of the support
+            is used.
+
+        x_max : float, default=None
+            Maximum of sample values. If `None`, the right edge of the support
+            is used.
+
+        method : {``'mc'``, ``'qmc'``}, default= ``'qmc'``
+            Method of drawing samples from uniform distribution:
+
+            * ``'mc'``: Monte Carlo
+            * ``'qmc'``: Quasi Monte Carlo
+
+        seed : int, default=None,
+            Seed for random number generator.
+
+        plot : bool, default=False
+            If `True`, samples histogram is plotted.
+
+        latex : bool, default=False
+            If `True`, the plot is rendered using LaTeX. This option is
+            relevant only if ``plot=True``.
+
+        save : bool, default=False
+            If not `False`, the plot is saved. If a string is given, it is
+            assumed to the save filename (with the file extension). This option
+            is relevant only if ``plot=True``.
+
+        Returns
+        -------
+
+        s : numpy.ndarray
+            Samples.
+
+        Notes
+        -----
+
+        This method uses inverse transform sampling.
+
+        Examples
+        --------
+
+        .. code-block::python
+
+            >>> from freealg.distributions import KestenMcKay
+            >>> km = KestenMcKay(3)
+            >>> s = km.sample(2000)
+
+        .. image:: ../_static/images/plots/km_samples.png
+            :align: center
+            :class: custom-dark
+        """
+
+        if x_min is None:
+            x_min = self.lam_m
+
+        if x_max is None:
+            x_max = self.lam_p
+
+        # Grid and PDF
+        xs = numpy.linspace(x_min, x_max, size)
+        pdf = self.density(xs)
+
+        # CDF (using cumulative trapezoidal rule)
+        cdf = cumtrapz(pdf, xs, initial=0)
+        cdf /= cdf[-1]  # normalize CDF to 1
+
+        # Inverse CDF interpolator
+        inv_cdf = interp1d(cdf, xs, bounds_error=False,
+                           fill_value=(x_min, x_max))
+
+        # Random generator
+        rng = numpy.random.default_rng(seed)
+
+        # Draw from uniform distribution
+        if method == 'mc':
+            u = rng.random(size)
+
+        elif method == 'qmc':
+            try:
+                engine = qmc.Halton(d=1, scramble=True, rng=rng)
+            except TypeError:
+                # Older scipy versions
+                engine = qmc.Halton(d=1, scramble=True, seed=rng)
+            u = engine.random(size).ravel()
+
+        else:
+            raise NotImplementedError('"method" is invalid.')
+
+        # Draw from distribution by mapping from inverse CDF
+        samples = inv_cdf(u).ravel()
+
+        if plot:
+            radius = 0.5 * (self.lam_p - self.lam_m)
+            center = 0.5 * (self.lam_p + self.lam_m)
+            scale = 1.25
+            x_min = numpy.floor(center - radius * scale)
+            x_max = numpy.ceil(center + radius * scale)
+            x = numpy.linspace(x_min, x_max, 500)
+            rho = self.density(x)
+            plot_samples(x, rho, x_min, x_max, samples, latex=latex, save=save)
+
+        return samples