freealg 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

freealg/distributions/_kesten_mckay.py

@@ -110,7 +110,7 @@ class KestenMcKay(object):
     # density
     # =======
 
-    def density(self, x=None, plot=False, latex=False, save=False):
+    def density(self, x=None, plot=False, latex=False, save=False, eig=None):
         """
         Density of distribution.
 
@@ -137,6 +137,10 @@ class KestenMcKay(object):
             assumed to the save filename (with the file extension). This option
             is relevant only if ``plot=True``.
 
+        eig : numpy.array, default=None
+            A collection of eigenvalues to compare to via histogram. This
+            option is relevant only if ``plot=True``.
+
         Returns
         -------
 
@@ -173,7 +177,11 @@ class KestenMcKay(object):
             numpy.sqrt(4.0 * (self.d - 1.0) - x[mask]**2)
 
         if plot:
-            plot_density(x, rho, label='', latex=latex, save=save)
+            if eig is not None:
+                label = 'Estimate'
+            else:
+                label = ''
+            plot_density(x, rho, label=label, latex=latex, save=save, eig=eig)
 
         return rho
 
@@ -539,9 +547,9 @@ class KestenMcKay(object):
 
         return samples
 
-    # ============
-    # Haar unitary
-    # ============
+    # ===============
+    # haar orthogonal
+    # ===============
 
     def _haar_orthogonal(self, n, k, seed=None):
         """

freealg/distributions/_marchenko_pastur.py

@@ -108,7 +108,7 @@ class MarchenkoPastur(object):
     # density
     # =======
 
-    def density(self, x=None, plot=False, latex=False, save=False):
+    def density(self, x=None, plot=False, latex=False, save=False, eig=None):
         """
         Density of distribution.
 
@@ -135,6 +135,10 @@ class MarchenkoPastur(object):
             assumed to the save filename (with the file extension). This option
             is relevant only if ``plot=True``.
 
+        eig : numpy.array, default=None
+            A collection of eigenvalues to compare to via histogram. This
+            option is relevant only if ``plot=True``.
+
         Returns
         -------
 
@@ -171,7 +175,11 @@ class MarchenkoPastur(object):
             numpy.sqrt((self.lam_p - x[mask]) * (x[mask] - self.lam_m))
 
         if plot:
-            plot_density(x, rho, label='', latex=latex, save=save)
+            if eig is not None:
+                label = 'Estimate'
+            else:
+                label = ''
+            plot_density(x, rho, label=label, latex=latex, save=save, eig=eig)
 
         return rho
 

freealg/distributions/_meixner.py

@@ -114,7 +114,7 @@ class Meixner(object):
     # density
     # =======
 
-    def density(self, x=None, plot=False, latex=False, save=False):
+    def density(self, x=None, plot=False, latex=False, save=False, eig=None):
         """
         Density of distribution.
 
@@ -141,6 +141,10 @@ class Meixner(object):
             assumed to the save filename (with the file extension). This option
             is relevant only if ``plot=True``.
 
+        eig : numpy.array, default=None
+            A collection of eigenvalues to compare to via histogram. This
+            option is relevant only if ``plot=True``.
+
         Returns
         -------
 
@@ -188,7 +192,11 @@ class Meixner(object):
         rho[mask] = numer[mask] / denom[mask]
 
         if plot:
-            plot_density(x, rho, label='', latex=latex, save=save)
+            if eig is not None:
+                label = 'Estimate'
+            else:
+                label = ''
+            plot_density(x, rho, label=label, latex=latex, save=save, eig=eig)
 
         return rho
 

freealg/distributions/_wachter.py

@@ -115,7 +115,7 @@ class Wachter(object):
     # density
     # =======
 
-    def density(self, x=None, plot=False, latex=False, save=False):
+    def density(self, x=None, plot=False, latex=False, save=False, eig=None):
         """
         Density of distribution.
 
@@ -142,6 +142,10 @@ class Wachter(object):
             assumed to the save filename (with the file extension). This option
             is relevant only if ``plot=True``.
 
+        eig : numpy.array, default=None
+            A collection of eigenvalues to compare to via histogram. This
+            option is relevant only if ``plot=True``.
+
         Returns
         -------
 
@@ -179,7 +183,11 @@ class Wachter(object):
             numpy.sqrt((self.lam_p - x[mask]) * (x[mask] - self.lam_m))
 
         if plot:
-            plot_density(x, rho, label='', latex=latex, save=save)
+            if eig is not None:
+                label = 'Estimate'
+            else:
+                label = ''
+            plot_density(x, rho, label=label, latex=latex, save=save, eig=eig)
 
         return rho
 

freealg/distributions/_wigner.py

@@ -96,7 +96,7 @@ class Wigner(object):
     # density
     # =======
 
-    def density(self, x=None, plot=False, latex=False, save=False):
+    def density(self, x=None, plot=False, latex=False, save=False, eig=None):
         """
         Density of distribution.
 
@@ -123,6 +123,10 @@ class Wigner(object):
             assumed to the save filename (with the file extension). This option
             is relevant only if ``plot=True``.
 
+        eig : numpy.array, default=None
+            A collection of eigenvalues to compare to via histogram. This
+            option is relevant only if ``plot=True``.
+
         Returns
         -------
 
@@ -159,7 +163,11 @@ class Wigner(object):
             numpy.sqrt(self.r**2 - x[mask]**2)
 
         if plot:
-            plot_density(x, rho, label='', latex=latex, save=save)
+            if eig is not None:
+                label = 'Estimate'
+            else:
+                label = ''
+            plot_density(x, rho, label=label, latex=latex, save=save, eig=eig)
 
         return rho
 

freealg/eigfree.py

@@ -0,0 +1,120 @@
+# 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 ._util import compute_eig
+from .freeform import FreeForm
+
+__all__ = ['eigfree']
+
+
+# ========
+# eig free
+# ========
+
+
+def eigfree(A, N=None, psd=None, plots=False):
+    """
+    Estimate the eigenvalues of a matrix.
+
+    This function estimates the eigenvalues of the matrix :math:`\\mathbf{A}`
+    or a larger matrix containing :math:`\\mathbf{A}` using free decompression.
+
+    Parameters
+    ----------
+
+    A : numpy.ndarray
+        The symmetric real-valued matrix :math:`\\mathbf{A}` whose eigenvalues
+        (or those of a matrix containing :math:`\\mathbf{A}`) are to be
+        computed.
+
+    N : 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.
+
+    psd: bool, default=None
+        Determines whether the matrix is positive-semidefinite (PSD; all
+        eigenvalues are non-negative). If None, the matrix is considered PSD if
+        all sampled eigenvalues are positive.
+
+    plots : bool, default=False
+        Print out all relevant plots for diagnosing eigenvalue accuracy.
+
+    Notes
+    -----
+
+    This is a convenience function for the FreeForm class with some effective
+    defaults that work well for common random matrix ensembles. For improved
+    performance and plotting utilites, consider finetuning parameters using
+    the FreeForm class.
+
+    References
+    ----------
+
+    .. [1] Reference.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        >>> from freealg import FreeForm
+    """
+
+    if A.ndim != 2 or A.shape[0] != A.shape[1]:
+        raise RuntimeError("Only square matrices are permitted.")
+    n = A.shape[0]
+
+    if N is None:
+        N = n
+
+    # Size of sample matrix
+    n_s = int(80*(1 + numpy.log(n)))
+    # If matrix is not large enough, return eigenvalues
+    if n < n_s:
+        return compute_eig(A)
+    # Number of samples
+    num_samples = int(10 * (n / n_s)**0.5)
+
+    # Collect eigenvalue samples
+    samples = []
+    for _ in range(num_samples):
+        indices = numpy.random.choice(n, n_s, replace=False)
+        samples.append(compute_eig(A[numpy.ix_(indices, indices)]))
+    samples = numpy.concatenate(samples).ravel()
+
+    # If all eigenvalues are positive, set PSD flag
+    if psd is None:
+        psd = samples.min() > 0
+
+    ff = FreeForm(samples)
+    # Since we are resampling, we need to provide the correct matrix size
+    ff.n = n_s
+
+    # Perform fit and estimate eigenvalues
+    order = 1 + int(len(samples)**.2)
+    ff.fit(method='chebyshev', K=order, projection='sample',
+           force=True, plot=False, latex=False, save=False)
+
+    if plots:
+        ff.density(plot=True)
+        ff.stieltjes(plot=True)
+
+    _, _, eigs = ff.decompress(N, plot=plots)
+
+    if psd:
+        eigs = numpy.abs(eigs)
+        eigs.sort()
+
+    return eigs

freealg/freeform.py

@@ -28,7 +28,7 @@ from ._decompress import decompress
 from ._sample import qmc_sample
 from ._support import detect_support
 
-__all__ = ['FreeForm', 'eigfree']
+__all__ = ['FreeForm']
 
 
 # =========
@@ -75,15 +75,15 @@ class FreeForm(object):
         Eigenvalues of the matrix
 
     support: tuple
-        The predicted (or given) support :math:`(\lambda_\min, \lambda_\max)` of the 
-        eigenvalue density.
+        The predicted (or given) support :math:`(\\lambda_{\\min},
+        \\lambda_{\\max})` of the eigenvalue density.
 
     psi : numpy.array
         Jacobi coefficients.
 
-    n   : int
-        Initial array size (assuming a square matrix when :math:`\\mathbf{A}`
-        is 2D).
+    n : int
+      Initial array size (assuming a square matrix when :math:`\\mathbf{A}` is
+      2D).
 
     Methods
     -------
@@ -390,10 +390,10 @@ class FreeForm(object):
             x_supp = numpy.linspace(self.lam_m, self.lam_p, 1000)
             g_supp = 2.0 * numpy.pi * self.hilbert(x_supp)
             self._pade_sol = fit_pade(x_supp, g_supp, self.lam_m, self.lam_p,
-                                    p=pade_p, q=pade_q, odd_side=odd_side,
-                                    pade_reg=pade_reg, safety=1.0, max_outer=40,
-                                    xtol=1e-12, ftol=1e-12, optimizer=optimizer,
-                                    verbose=0)
+                                      p=pade_p, q=pade_q, odd_side=odd_side,
+                                      pade_reg=pade_reg, safety=1.0,
+                                      max_outer=40, xtol=1e-12, ftol=1e-12,
+                                      optimizer=optimizer, verbose=0)
 
         if plot:
             g_supp_approx = eval_pade(x_supp[None, :], self._pade_sol)[0, :]
@@ -449,7 +449,8 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('The spectral density needs to be fit using the .fit() function.')
+            raise RuntimeError('The spectral density needs to be fit using ' +
+                               'the .fit() function.')
 
         # Create x if not given
         if x is None:
@@ -543,7 +544,8 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('The spectral density needs to be fit using the .fit() function.')
+            raise RuntimeError('The spectral density needs to be fit using ' +
+                               'the .fit() function.')
 
         # Create x if not given
         if x is None:
@@ -605,8 +607,10 @@ class FreeForm(object):
 
     def stieltjes(self, x=None, y=None, plot=False, latex=False, save=False):
         """
-        Compute Stieltjes transform of the spectral density, evaluated on an array
-        of points, or over a 2D Cartesian grid on the complex plane.
+        Compute Stieltjes transform of the spectral density on a grid.
+
+        This function evaluates Stieltjes transform on an array of points, or
+        over a 2D Cartesian grid on the complex plane.
 
         Parameters
         ----------
@@ -665,11 +669,11 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('The spectral density needs to be fit using the .fit() function.')
-
+            raise RuntimeError('The spectral density needs to be fit using ' +
+                               'the .fit() function.')
 
-        # Determine whether the Stieltjes transform is to be computed on
-        # a Cartesian grid
+        # Determine whether the Stieltjes transform is to be computed on a
+        # Cartesian grid
         cartesian = plot | (y is not None)
 
         # Create x if not given
@@ -693,8 +697,8 @@ class FreeForm(object):
             z = x_grid + 1j * y_grid              # shape (Ny, Nx)
         else:
             z = x
-        
-        m1, m2 = self._eval_stieltjes(z)
+
+        m1, m2 = self._eval_stieltjes(z, branches=True)
 
         if plot:
             plot_stieltjes(x, y, m1, m2, self.support, latex=latex, save=save)
@@ -705,7 +709,7 @@ class FreeForm(object):
     # eval stieltjes
     # ==============
 
-    def _eval_stieltjes(self, z):
+    def _eval_stieltjes(self, z, branches=False):
         """
         Compute Stieltjes transform of the spectral density.
 
@@ -716,12 +720,18 @@ class FreeForm(object):
             The z values in the complex plan where the Stieltjes transform is
             evaluated.
 
+        branches : bool, default = False
+            Return both the principal and secondary branches of the Stieltjes
+            transform. The default ``branches=False`` will return only
+            the secondary branch.
+
 
         Returns
         -------
 
         m_p : numpy.ndarray
-            The Stieltjes transform on the principal branch.
+            The Stieltjes transform on the principal branch if
+            ``branches=True``.
 
         m_m : numpy.ndarray
             The Stieltjes transform continued to the secondary branch.
@@ -737,14 +747,15 @@ class FreeForm(object):
         z = z.reshape(-1, 1)
 
         # # Set the number of bases as the number of x points insides support
-        # mask_sup = numpy.logical_and(z.real >= self.lam_m, z.real <= self.lam_p)
+        # mask_sup = numpy.logical_and(z.real >= self.lam_m,
+        #                              z.real <= self.lam_p)
         # n_base = 2 * numpy.sum(mask_sup)
 
         # Stieltjes function
         if self.method == 'jacobi':
             stieltjes = partial(jacobi_stieltjes, psi=self.psi,
                                 support=self.support, alpha=self.alpha,
-                                beta=self.beta) # n_base = n_base
+                                beta=self.beta)  # n_base = n_base
         elif self.method == 'chebyshev':
             stieltjes = partial(chebyshev_stieltjes, psi=self.psi,
                                 support=self.support)
@@ -760,31 +771,34 @@ class FreeForm(object):
             m1[mask_p] = stieltjes(z[mask_p].reshape(-1, 1)).ravel()
 
             # Lower half-plane, use Schwarz reflection
-            m1[mask_m] = numpy.conjugate(
-                stieltjes(numpy.conjugate(z[mask_m].reshape(-1, 1)))).ravel()
+            z_conj = numpy.conjugate(z[mask_m].reshape(-1, 1))
+            m1[mask_m] = numpy.conjugate(stieltjes(z_conj)).ravel()
 
             # Second Riemann sheet
             m2[mask_p] = m1[mask_p]
             m2[mask_m] = -m1[mask_m] + self._glue(
                 z[mask_m].reshape(-1, 1)).ravel()
-        
-        else:
-            m2[:]      = stieltjes(z.reshape(-1,1)).reshape(*m2.shape)
-            m1[mask_p] = m2[mask_p]
-            m1[mask_m] = numpy.conjugate(
-                stieltjes(numpy.conjugate(z[mask_m].reshape(-1,1)))
-            ).ravel()
 
-        m1, m2 = m1.reshape(*shape), m2.reshape(*shape)
-
-        return m1, m2
+        else:
+            m2[:] = stieltjes(z.reshape(-1, 1)).reshape(*m2.shape)
+            if branches:
+                m1[mask_p] = m2[mask_p]
+                m1[mask_m] = numpy.conjugate(
+                    stieltjes(numpy.conjugate(z[mask_m].reshape(-1, 1)))
+                ).ravel()
+
+        if not branches:
+            return m2.reshape(*shape)
+        else:
+            m1, m2 = m1.reshape(*shape), m2.reshape(*shape)
+            return m1, m2
 
     # ==========
     # decompress
     # ==========
 
-    def decompress(self, size, x=None, iterations=500, eigvals=True,
-                   step_size=0.1, tolerance=1e-9, seed=None, plot=False,
+    def decompress(self, size, x=None, max_iter=500, eigvals=True,
+                   tolerance=1e-9, seed=None, plot=False,
                    latex=False, save=False):
         """
         Free decompression of spectral density.
@@ -799,15 +813,12 @@ class FreeForm(object):
             Positions where density to be evaluated at. If `None`, an interval
             slightly larger than the support interval will be used.
 
-        iterations: int, default=500
-            Maximum number of Newton iterations.
+        max_iter: int, default=500
+            Maximum number of secant method iterations.
 
         eigvals: bool, default=True
             Return estimated (sampled) eigenvalues as well as the density.
 
-        step_size: float, default=0.1
-            Step size for Newton iterations.
-
         tolerance: float, default=1e-9
             Tolerance for the solution obtained by the Newton solver. Also
             used for the finite difference approximation to the derivative.
@@ -867,8 +878,7 @@ class FreeForm(object):
         size = int(size)
 
         rho, x, (lb, ub) = decompress(self, size, x=x, delta=self.delta,
-                                      iterations=iterations,
-                                      step_size=step_size, tolerance=tolerance)
+                                      max_iter=max_iter, tolerance=tolerance)
         x, rho = x.ravel(), rho.ravel()
 
         if plot:
@@ -881,14 +891,15 @@ class FreeForm(object):
         else:
             return x, rho
 
-def eigfree(A, N = None, psd = None):
+
+def eigfree(A, N=None, psd=None, plots=False):
     """
     Estimate the eigenvalues of a matrix :math:`\\mathbf{A}` or a larger matrix
     containing :math:`\\mathbf{A}` using free decompression.
 
     This is a convenience function for the FreeForm class with some effective
     defaults that work well for common random matrix ensembles. For improved
-    performance and plotting utilites, consider finetuning parameters using 
+    performance and plotting utilites, consider finetuning parameters using
     the FreeForm class.
 
     Parameters
@@ -896,18 +907,22 @@ def eigfree(A, N = None, psd = None):
 
     A : numpy.ndarray
         The symmetric real-valued matrix :math:`\\mathbf{A}` whose eigenvalues
-        (or those of a matrix containing :math:`\\mathbf{A}`) are to be computed.
+        (or those of a matrix containing :math:`\\mathbf{A}`) are to be
+        computed.
 
     N : 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.
 
-    psd: bool, default=None
-        Determines whether the matrix is positive-semidefinite (PSD; all 
+    psd : bool, default=None
+        Determines whether the matrix is positive-semidefinite (PSD; all
         eigenvalues are non-negative). If None, the matrix is considered PSD if
         all sampled eigenvalues are positive.
 
+    plots : bool, default=False
+        Print out all relevant plots for diagnosing eigenvalue accuracy.
+
     Notes
     -----
 
@@ -925,20 +940,24 @@ def eigfree(A, N = None, psd = None):
 
         >>> from freealg import FreeForm
     """
+    if A.ndim != 2 or A.shape[0] != A.shape[1]:
+        raise RuntimeError("Only square matrices are permitted.")
     n = A.shape[0]
-    
+
+    if N is None:
+        N = n
+
     # Size of sample matrix
     n_s = int(80*(1 + numpy.log(n)))
-
     # If matrix is not large enough, return eigenvalues
     if n < n_s:
         return compute_eig(A)
-    
-    if N is None:
-        N = n
-    
     # Number of samples
     num_samples = int(10 * (n / n_s)**0.5)
+    # else:
+    #     # Use the entire matrix given
+    #     n_s = n
+    #     num_samples = 1
 
     # Collect eigenvalue samples
     samples = []
@@ -957,12 +976,17 @@ def eigfree(A, N = None, psd = None):
 
     # Perform fit and estimate eigenvalues
     order = 1 + int(len(samples)**.2)
-    ff.fit(method='chebyshev', K=order, projection='sample', damp='jackson', 
-           force=True, plot=False, latex=False, save=False, reg=0.05)
-    _, _, eigs = ff.decompress(N)
+    ff.fit(method='chebyshev', K=order, projection='sample',
+           force=True, plot=False, latex=False, save=False)
+
+    if plots:
+        ff.density(plot=True)
+        ff.stieltjes(plot=True)
+
+    _, _, eigs = ff.decompress(N, plot=plots)
 
     if psd:
         eigs = numpy.abs(eigs)
         eigs.sort()
 
-    return eigs
+    return eigs

{freealg-0.1.12.dist-info → freealg-0.1.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.1.12
+Version: 0.1.14
 Summary: Free probability for large matrices
 Keywords: leaderboard bot chat
 Platform: Linux
@@ -50,6 +50,12 @@ Dynamic: summary
     :width: 240
     :class: custom-dark
 
+`Paper <https://arxiv.org/abs/2506.11994>`__ |
+`Slides <https://www.dropbox.com/scl/fi/03gjuyz17k9yhsqy0isoz/free_decomporession_slides.pdf?rlkey=8f82mhciyl2ju02l7hv1md5li&st=26xmhjga&dl=0>`__ |
+`Docs <https://ameli.github.io/freealg>`__
+
+.. `Slides <https://ameli.github.io/freealg/_static/data/slides.pdf>`__ |
+
 *freealg* is a Python package that employs **free** probability to evaluate the spectral
 densities of large matrix **form**\ s. The fundamental algorithm employed by *freealg* is
 **free decompression**, which extrapolates from the empirical spectral densities of small 
@@ -120,15 +126,19 @@ requests and bug reports.
 How to Cite
 ===========
 
-If you use this work, please cite the `arXiv paper <https://arxiv.org/abs/2506.11994>`.
+If you use this work, please cite the `arXiv paper <https://arxiv.org/abs/2506.11994>`__.
 
   .. code::
 
-      @article{ameli2025spectral,
-        title={Spectral Estimation with Free Decompression},
-        author={Siavash Ameli and Chris van der Heide and Liam Hodgkinson and Michael W. Mahoney},
-        journal={arXiv preprint arXiv:2506.11994},
-        year={2025}
+      @article{spectral2025,
+          title={Spectral Estimation with Free Decompression},
+          author={Siavash Ameli and Chris van der Heide and Liam Hodgkinson and Michael W. Mahoney},
+          year={2025},
+          eprint={2506.11994},
+          archivePrefix={arXiv},
+          primaryClass={stat.ML},
+          url={https://arxiv.org/abs/2506.11994},
+          journal={arXiv preprint arXiv:2506.11994},
       }