freealg 0.1.10__tar.gz → 0.1.12__tar.gz

{freealg-0.1.10 → freealg-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.1.10
+Version: 0.1.12
 Summary: Free probability for large matrices
 Keywords: leaderboard bot chat
 Platform: Linux
@@ -31,6 +31,7 @@ Requires-Dist: texplot
 Requires-Dist: matplotlib
 Requires-Dist: colorcet
 Requires-Dist: statsmodels
+Requires-Dist: numba
 Provides-Extra: test
 Requires-Dist: tox; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -69,7 +70,10 @@ Dynamic: summary
     :width: 240
     :class: custom-dark
 
-*freealg* is a python package that employs **free** probability for large matrix **form**\ s.
+*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 
+submatrices to infer the eigenspectrum of extremely large matrices. 
 
 Install
 =======
@@ -95,12 +99,18 @@ Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/
 Quick Usage
 ===========
 
-Create and Train a Model
-------------------------
+The following code estimates the eigenvalues of a very large Wishart matrix using a much
+smaller Wishart matrix.
 
 .. code-block:: python
 
     >>> import freealg as fa
+    >>> mp = fa.distributions.MarchenkoPastur(1/50) # Wishart matrices with aspect ratio 1/50
+    >>> A = mp.matrix(1000)                         # Sample a 1000 x 1000 Wishart matrix
+    >>> eigs = fa.eigfree(A, 100_000)               # Estimate the eigenvalues of 100000 x 100000
+
+For more details on how to interface with *freealg* check out the `Quick Start Guide <https://github.com/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__.
+
 
 Test
 ====
@@ -130,14 +140,18 @@ requests and bug reports.
 How to Cite
 ===========
 
-* TBD
+If you use this work, please cite the `arXiv paper <https://arxiv.org/abs/2506.11994>`.
 
   .. code::
 
-      @inproceedings{
-          TBD
+      @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}
       }
 
+
 License
 =======
 

{freealg-0.1.10 → freealg-0.1.12}/README.rst

@@ -3,7 +3,10 @@
     :width: 240
     :class: custom-dark
 
-*freealg* is a python package that employs **free** probability for large matrix **form**\ s.
+*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 
+submatrices to infer the eigenspectrum of extremely large matrices. 
 
 Install
 =======
@@ -29,12 +32,18 @@ Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/
 Quick Usage
 ===========
 
-Create and Train a Model
-------------------------
+The following code estimates the eigenvalues of a very large Wishart matrix using a much
+smaller Wishart matrix.
 
 .. code-block:: python
 
     >>> import freealg as fa
+    >>> mp = fa.distributions.MarchenkoPastur(1/50) # Wishart matrices with aspect ratio 1/50
+    >>> A = mp.matrix(1000)                         # Sample a 1000 x 1000 Wishart matrix
+    >>> eigs = fa.eigfree(A, 100_000)               # Estimate the eigenvalues of 100000 x 100000
+
+For more details on how to interface with *freealg* check out the `Quick Start Guide <https://github.com/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__.
+
 
 Test
 ====
@@ -64,14 +73,18 @@ requests and bug reports.
 How to Cite
 ===========
 
-* TBD
+If you use this work, please cite the `arXiv paper <https://arxiv.org/abs/2506.11994>`.
 
   .. code::
 
-      @inproceedings{
-          TBD
+      @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}
       }
 
+
 License
 =======
 

{freealg-0.1.10 → freealg-0.1.12}/freealg/__init__.py

@@ -6,9 +6,9 @@
 # under the terms of the license found in the LICENSE.txt file in the root
 # directory of this source tree.
 
-from .freeform import FreeForm
+from .freeform import FreeForm, eigfree
 from . import distributions
 
-__all__ = ['FreeForm', 'distributions']
+__all__ = ['FreeForm', 'distributions', 'eigfree']
 
 from .__version__ import __version__                          # noqa: F401 E402

freealg-0.1.12/freealg/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.12"

{freealg-0.1.10 → freealg-0.1.12}/freealg/_chebyshev.py

@@ -13,6 +13,7 @@
 
 import numpy
 from scipy.special import eval_chebyu
+from ._pade import wynn_pade
 
 __all__ = ['chebyshev_sample_proj', 'chebyshev_kernel_proj',
            'chebyshev_approx', 'chebyshev_stieltjes']
@@ -66,7 +67,7 @@ def chebyshev_sample_proj(eig, support, K=10, reg=0.0):
     for k in range(K+1):
 
         # empirical moment M_k = (1/N) \\sum U_k(t_i)
-        M_k = numpy.sum(eval_chebyu(k, t)) / N
+        M_k = numpy.mean(eval_chebyu(k, t))
 
         # Regularization
         if k == 0:
@@ -103,7 +104,7 @@ def chebyshev_kernel_proj(xs, pdf, support, K=10, reg=0.0):
 
     for k in range(K + 1):
         Pk = eval_chebyu(k, t)                       # U_k(t) on the grid
-        moment = numpy.trapz(Pk * pdf, xs)           # \int U_k(t) \rho(x) dx
+        moment = numpy.trapezoid(Pk * pdf, xs)           # \int U_k(t) \rho(x) dx
 
         if k == 0:
             penalty = 0
@@ -218,18 +219,21 @@ def chebyshev_stieltjes(z, psi, support):
     Jp = u + root
 
     # Make sure J is Herglotz
-    J = numpy.zeros_like(Jp)
-    J = numpy.where(Jp.imag > 0, Jm, Jp)
+    J = numpy.zeros_like(Jm)
+    J = numpy.where(root.imag < 0, Jp, Jm)
+
+    psi_zero = numpy.concatenate([[0], psi])
+    S = wynn_pade(psi_zero, J)
 
     # build powers J^(k+1) for k=0..K
-    K = len(psi) - 1
+    #K = len(psi) - 1
     # shape: (..., K+1)
-    Jpow = J[..., None] ** numpy.arange(1, K+2)
+    #Jpow = J[..., None] ** numpy.arange(1, K+2)
 
     # sum psi_k * J^(k+1)
-    S = numpy.sum(psi * Jpow, axis=-1)
+    #S = numpy.sum(psi * Jpow, axis=-1)
 
     # assemble m(z)
-    m_z = - (2.0 / span) * numpy.pi * S
+    m_z = -2 / span * numpy.pi * S
 
     return m_z

{freealg-0.1.10 → freealg-0.1.12}/freealg/_decompress.py

@@ -20,16 +20,16 @@ __all__ = ['decompress', 'reverse_characteristics']
 # decompress
 # ==========
 
-def decompress(matrix, size, x=None, delta=1e-4, iterations=500, step_size=0.1,
-               tolerance=1e-4):
+def decompress(freeform, size, x=None, delta=1e-6, iterations=500,
+               step_size=0.1, tolerance=1e-9):
     """
     Free decompression of spectral density.
 
     Parameters
     ----------
 
-    matrix : FreeForm
-        The initial matrix to be decompressed
+    freeform : FreeForm
+        The initial freeform object of matrix to be decompressed
 
     size : int
         Size of the decompressed matrix.
@@ -82,13 +82,13 @@ def decompress(matrix, size, x=None, delta=1e-4, iterations=500, step_size=0.1,
         >>> from freealg import FreeForm
     """
 
-    alpha = size / matrix.n
-    m = matrix._eval_stieltjes
+    alpha = size / freeform.n
+    m = freeform._eval_stieltjes
     # Lower and upper bound on new support
-    hilb_lb = (1 / m(matrix.lam_m + delta * 1j)[1]).real
-    hilb_ub = (1 / m(matrix.lam_p + delta * 1j)[1]).real
-    lb = matrix.lam_m - (alpha - 1) * hilb_lb
-    ub = matrix.lam_p - (alpha - 1) * hilb_ub
+    hilb_lb = (1 / m(freeform.lam_m + delta * 1j)[1]).real
+    hilb_ub = (1 / m(freeform.lam_p + delta * 1j)[1]).real
+    lb = freeform.lam_m - (alpha - 1) * hilb_lb
+    ub = freeform.lam_p - (alpha - 1) * hilb_ub
 
     # Create x if not given
     if x is None:
@@ -107,7 +107,7 @@ def decompress(matrix, size, x=None, delta=1e-4, iterations=500, step_size=0.1,
 
     target = x + delta * 1j
 
-    z = numpy.full(target.shape, numpy.mean(matrix.support) - .1j,
+    z = numpy.full(target.shape, numpy.mean(freeform.support) - .1j,
                    dtype=numpy.complex128)
 
     # Broken Newton steps can produce a lot of warnings. Removing them
@@ -141,22 +141,22 @@ def decompress(matrix, size, x=None, delta=1e-4, iterations=500, step_size=0.1,
 # reverse characteristics
 # =======================
 
-def reverse_characteristics(matrix, z_inits, T, iterations=500, step_size=0.1,
-                            tolerance=1e-8):
+def reverse_characteristics(freeform, z_inits, T, iterations=500,
+                            step_size=0.1, tolerance=1e-8):
     """
     """
 
     t_span = (0, T)
     t_eval = numpy.linspace(t_span[0], t_span[1], 50)
 
-    m = matrix._eval_stieltjes
+    m = freeform._eval_stieltjes
 
     def _char_z(z, t):
         return z + (1 / m(z)[1]) * (1 - numpy.exp(t))
 
     target_z, target_t = numpy.meshgrid(z_inits, t_eval)
 
-    z = numpy.full(target_z.shape, numpy.mean(matrix.support) - .1j,
+    z = numpy.full(target_z.shape, numpy.mean(freeform.support) - .1j,
                    dtype=numpy.complex128)
 
     # Broken Newton steps can produce a lot of warnings. Removing them for now.

{freealg-0.1.10 → freealg-0.1.12}/freealg/_pade.py

@@ -12,6 +12,7 @@
 # =======
 
 import numpy
+import numba
 from numpy.linalg import lstsq
 from itertools import product
 from scipy.optimize import least_squares, differential_evolution
@@ -235,6 +236,55 @@ def _eval_rational(z, c, D, poles, resid):
 
     return c + D * z + term
 
+# ========
+# Wynn epsilon algorithm for Pade
+# ========
+
+@numba.jit(nopython=True, parallel=True)
+def wynn_pade(coeffs, x):
+    """
+    Given the coefficients of a power series
+        f(x) = sum_{n=0}^∞ coeffs[n] * x^n,
+    returns a function handle that computes the Pade approximant at any x
+    using Wynn's epsilon algorithm.
+
+    Parameters:
+        coeffs (list or array): Coefficients [a0, a1, a2, ...] of the power series.
+
+    Returns:
+        function: A function approximant(x) that returns the approximated value f(x).
+    """
+    # Number of coefficients
+    xn = x.ravel()
+    d = len(xn)
+    N = len(coeffs)
+    
+    # Compute the partial sums s_n = sum_{i=0}^n a_i * x^i for n=0,...,N-1
+    eps = numpy.zeros((N+1, N, d), dtype=numpy.complex128)
+    for i in numba.prange(d):
+        partial_sum = 0.0
+        for n in range(N):
+            partial_sum += coeffs[n] * (xn[i] ** n)
+            eps[0,n,i] = partial_sum
+
+    for i in numba.prange(d):
+        for k in range(1, N+1):
+            for j in range(N - k):
+                delta = eps[k-1, j+1,i] - eps[k-1, j,i]
+                if delta == 0:
+                    rec_delta = numpy.inf
+                elif numpy.isinf(delta) or numpy.isnan(delta):
+                    rec_delta = 0.0
+                else:
+                    rec_delta = 1.0 / delta
+                eps[k,j,i] = rec_delta
+                if k > 1:
+                    eps[k,j,i] += eps[k-2,j+1,i]
+
+    if (N % 2) == 0:
+        N -= 1
+    
+    return eps[N-1, 0, :].reshape(x.shape)
 
 # ========
 # fit pade

{freealg-0.1.10 → freealg-0.1.12}/freealg/_sample.py

@@ -12,7 +12,7 @@
 
 import numpy
 from scipy.integrate import cumulative_trapezoid
-from scipy.interpolate import interp1d
+from scipy.interpolate import PchipInterpolator
 from scipy.stats import qmc
 
 __all__ = ['qmc_sample']
@@ -22,14 +22,16 @@ __all__ = ['qmc_sample']
 # quantile func
 # =============
 
-def _quantile_func(x, rho):
+def _quantile_func(x, rho, clamp=1e-4, eps=1e-8):
     """
     Construct a quantile function from evaluations of an estimated density
     on a grid (x, rho(x)).
     """
-    cdf = cumulative_trapezoid(rho, x, initial=0)
+    rho_clamp = rho.copy()
+    rho_clamp[rho < clamp] = eps
+    cdf = cumulative_trapezoid(rho_clamp, x, initial=0)
     cdf /= cdf[-1]
-    return interp1d(cdf, x, bounds_error=False, assume_sorted=True)
+    return PchipInterpolator(cdf, x, extrapolate=False)
 
 
 # ==========

freealg-0.1.12/freealg/_support.py

@@ -0,0 +1,85 @@
+import numpy
+from scipy.stats import gaussian_kde
+
+def detect_support(eigs, method='interior_smooth', k = None, p = 0.001, **kwargs):
+    """
+    Estimates the support of the eigenvalue density.
+
+    Parameters
+    ----------
+    method : {``'range'``, ``'jackknife'``, ``'regression'``, ``'interior'``, 
+                ``'interior_smooth'``}, \
+            default= ``'jackknife'``
+        The method of support estimation:
+
+        * ``'range'``: no estimation; the support is the range of the eigenvalues
+        * ``'jackknife'``: estimates the support using Quenouille's [1]
+            jackknife estimator. Fast and simple, more accurate than the range.
+        * ``'regression'``: estimates the support by performing a regression under
+            the assumption that the edge behavior is of square-root type. Often
+            most accurate.
+        * ``'interior'``: estimates a support assuming the range overestimates;
+            uses quantiles (p, 1-p).
+        * ``'interior_smooth'``: same as ``'interior'`` but using kernel density
+            estimation.
+
+    k : int, default = None
+        Number of extreme order statistics to use for ``method='regression'``. 
+    
+    p : float, default=0.001
+        The edges of the support of the distribution is detected by the
+        :math:`p`-quantile on the left and :math:`(1-p)`-quantile on the right
+        where ``method='interior'`` or ``method='interior_smooth'``.
+        This value should be between 0 and 1, ideally a small number close to
+        zero.
+
+    References
+    ----------
+
+    .. [1] Quenouille, M. H. (1949, July). Approximate tests of correlation in time-series. 
+        In Mathematical Proceedings of the Cambridge Philosophical Society (Vol. 45, No. 3, 
+        pp. 483-484). Cambridge University Press.
+    """
+
+    if method=='range':
+        lam_m = eigs.min()
+        lam_p = eigs.max()
+
+    elif method=='jackknife':
+        x, n = numpy.sort(eigs), len(eigs)
+        lam_m = x[0]  - (n - 1)/n * (x[1]  - x[0])
+        lam_p = x[-1] + (n - 1)/n * (x[-1] - x[-2])
+
+    elif method=='regression':
+        x, n = numpy.sort(eigs), len(eigs)
+        if k is None:
+            k = int(round(n ** (2/3)))
+            k = max(5, min(k, n // 2))
+
+        # The theoretical cdf near the edge behaves like const*(x - a)^{3/2},
+        # so (i/n) ≈ (x - a)^{3/2}  ⇒  x ≈ a + const*(i/n)^{2/3}.
+        y = ((numpy.arange(1, k + 1) - 0.5) / n) ** (2 / 3)
+
+        # Left edge: regress x_{(i)} on y
+        _, lam_m = numpy.polyfit(y, x[:k], 1)
+
+        # Right edge: regress x_{(n-i+1)} on y
+        _, lam_p = numpy.polyfit(y, x[-k:][::-1], 1)
+
+    elif method=='interior':
+        lam_m, lam_p = numpy.quantile(eigs, [p, 1-p])
+    
+    elif method=='interior_smooth':
+        kde = gaussian_kde(eigs)
+        xs = numpy.linspace(eigs.min(), eigs.max(), 1000)
+        fs = kde(xs)
+
+        cdf = numpy.cumsum(fs)
+        cdf /= cdf[-1]
+
+        lam_m = numpy.interp(p, cdf, xs)
+        lam_p = numpy.interp(1-p, cdf, xs)
+    else:
+        raise NotImplementedError("Unknown method")
+
+    return lam_m, lam_p

{freealg-0.1.10 → freealg-0.1.12}/freealg/_util.py

@@ -143,7 +143,7 @@ def force_density(psi0, support, approx, grid, alpha=0.0, beta=0.0):
     # Normalize first mode to unit mass
     x = numpy.linspace(lam_m, lam_p, 1000)
     rho = approx(x, psi)
-    mass = numpy.trapz(rho, x)
+    mass = numpy.trapezoid(rho, x)
     psi[0] = psi[0] / mass
 
     return psi

{freealg-0.1.10 → freealg-0.1.12}/freealg/freeform.py

@@ -26,8 +26,9 @@ from ._plot_util import plot_fit, plot_density, plot_hilbert, plot_stieltjes
 from ._pade import fit_pade, eval_pade
 from ._decompress import decompress
 from ._sample import qmc_sample
+from ._support import detect_support
 
-__all__ = ['FreeForm']
+__all__ = ['FreeForm', 'eigfree']
 
 
 # =========
@@ -50,12 +51,12 @@ class FreeForm(object):
         The support of the density of :math:`\\mathbf{A}`. If `None`, it is
         estimated from the minimum and maximum of the eigenvalues.
 
-    p : float, default=0.001
-        The edges of the support of the distribution is detected by the
-        :math:`p`-quantile on the left and :math:`(1-p)`-quantile on the right.
-        If the argument ``support`` is directly provided, this option is
-        ignored. This value should be between 0 and 1, ideally a small
-        number close to zero.
+    delta: float, default=1e-6
+        Size of perturbations into the upper half plane for Plemelj's
+        formula.
+
+    Parameters for the ``detect_support`` function can also be prescribed here
+    when ``support=None``.
 
     Notes
     -----
@@ -73,12 +74,16 @@ class FreeForm(object):
     eig : numpy.array
         Eigenvalues of the matrix
 
+    support: tuple
+        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)
+        is 2D).
 
     Methods
     -------
@@ -110,13 +115,14 @@ class FreeForm(object):
     # init
     # ====
 
-    def __init__(self, A, support=None, p=0.001):
+    def __init__(self, A, support=None, delta=1e-6, **kwargs):
         """
         Initialization.
         """
 
         self.A = None
         self.eig = None
+        self.delta = delta
 
         # Eigenvalues
         if A.ndim == 1:
@@ -134,8 +140,7 @@ class FreeForm(object):
 
         # Support
         if support is None:
-            self.lam_m, self.lam_p = self._detect_support(self.eig, p,
-                                                          smoothen=True)
+            self.lam_m, self.lam_p = detect_support(self.eig, **kwargs)
         else:
             self.lam_m = support[0]
             self.lam_p = support[1]
@@ -148,30 +153,6 @@ class FreeForm(object):
         self.beta = None
         self._pade_sol = None
 
-    # ==============
-    # detect support
-    # ==============
-
-    def _detect_support(self, eig, p, smoothen=True):
-        """
-        """
-
-        # Using quantile directly.
-        if smoothen:
-            kde = gaussian_kde(eig)
-            xs = numpy.linspace(eig.min(), eig.max(), 1000)
-            fs = kde(xs)
-
-            cdf = numpy.cumsum(fs)
-            cdf /= cdf[-1]
-
-            lam_m = numpy.interp(p, cdf, xs)
-            lam_p = numpy.interp(1-p, cdf, xs)
-        else:
-            lam_m, lam_p = numpy.quantile(eig, [p, 1-p])
-
-        return lam_m, lam_p
-
     # ===
     # fit
     # ===
@@ -403,19 +384,16 @@ class FreeForm(object):
         self.alpha = alpha
         self.beta = beta
 
-        # For holomorphic continuation for the lower half-plane
-        x_supp = numpy.linspace(self.lam_m, self.lam_p, 1000)
-        g_supp = 2.0 * numpy.pi * self.hilbert(x_supp)
-
         # Fit a pade approximation
-        # self._pade_sol = fit_pade(x_supp, g_supp, self.lam_m,
-        #                           self.lam_p, pade_p, pade_q, delta=1e-8,
-        #                           B=numpy.inf, S=numpy.inf)
-        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)
+        if method != 'chebyshev' or projection != 'sample':
+            # For holomorphic continuation for the lower half-plane
+            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)
 
         if plot:
             g_supp_approx = eval_pade(x_supp[None, :], self._pade_sol)[0, :]
@@ -471,7 +449,7 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('"fit" the model first.')
+            raise RuntimeError('The spectral density needs to be fit using the .fit() function.')
 
         # Create x if not given
         if x is None:
@@ -497,7 +475,7 @@ class FreeForm(object):
             raise RuntimeError('"method" is invalid.')
 
         # Check density is unit mass
-        mass = numpy.trapz(rho, x)
+        mass = numpy.trapezoid(rho, x)
         if not numpy.isclose(mass, 1.0, atol=1e-2):
             print(f'"rho" is not unit mass. mass: {mass:>0.3f}. Set ' +
                   r'"force=True".')
@@ -565,7 +543,7 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('"fit" the model first.')
+            raise RuntimeError('The spectral density needs to be fit using the .fit() function.')
 
         # Create x if not given
         if x is None:
@@ -599,7 +577,7 @@ class FreeForm(object):
 
         # Integrate each row over t using trapezoid rule on x_s
         # Namely, hilb[i] = int rho_s(t)/(t - x[i]) dt
-        hilb = numpy.trapz(D, x_s, axis=1) / numpy.pi
+        hilb = numpy.trapezoid(D, x_s, axis=1) / numpy.pi
 
         # We use negative sign convention
         hilb = -hilb
@@ -615,12 +593,10 @@ class FreeForm(object):
     # ====
 
     def _glue(self, z):
-        """
-        """
-
         # Glue function
+        if self._pade_sol is None:
+            return numpy.zeros_like(z)
         g = eval_pade(z, self._pade_sol)
-
         return g
 
     # =========
@@ -629,8 +605,8 @@ class FreeForm(object):
 
     def stieltjes(self, x=None, y=None, plot=False, latex=False, save=False):
         """
-        Compute Stieltjes transform of the spectral density over a 2D Cartesian
-        grid on the complex plane.
+        Compute Stieltjes transform of the spectral density, evaluated on an array
+        of points, or over a 2D Cartesian grid on the complex plane.
 
         Parameters
         ----------
@@ -689,7 +665,12 @@ class FreeForm(object):
         """
 
         if self.psi is None:
-            raise RuntimeError('"fit" the model first.')
+            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
+        cartesian = plot | (y is not None)
 
         # Create x if not given
         if x is None:
@@ -699,43 +680,21 @@ class FreeForm(object):
             x_min = numpy.floor(2.0 * (center - 2.0 * radius * scale)) / 2.0
             x_max = numpy.ceil(2.0 * (center + 2.0 * radius * scale)) / 2.0
             x = numpy.linspace(x_min, x_max, 500)
+            if not cartesian:
+                # Evaluate slightly above the real line
+                x = x.astype(complex)
+                x += self.delta * 1j
 
         # Create y if not given
-        if y is None:
-            y = numpy.linspace(-1, 1, 400)
-
-        x_grid, y_grid = numpy.meshgrid(x, y)
-        z = x_grid + 1j * y_grid              # shape (Ny, Nx)
-
-        # Set the number of bases as the number of x points insides support
-        mask_sup = numpy.logical_and(x >= self.lam_m, x <= 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)
-        elif self.method == 'chebyshev':
-            stieltjes = partial(chebyshev_stieltjes, psi=self.psi,
-                                support=self.support)
-
-        mask_p = y >= 0.0
-        mask_m = y < 0.0
-
-        m1 = numpy.zeros_like(z)
-        m2 = numpy.zeros_like(z)
-
-        # Upper half-plane
-        m1[mask_p, :] = stieltjes(z[mask_p, :])
-
-        # Lower half-plane, use Schwarz reflection
-        m1[mask_m, :] = numpy.conjugate(
-            stieltjes(numpy.conjugate(z[mask_m, :])))
-
-        # Second Riemann sheet
-        m2[mask_p, :] = m1[mask_p, :]
-        m2[mask_m, :] = -m1[mask_m, :] + self._glue(z[mask_m, :])
+        if cartesian:
+            if y is None:
+                y = numpy.linspace(-1, 1, 400)
+            x_grid, y_grid = numpy.meshgrid(x.real, y.real)
+            z = x_grid + 1j * y_grid              # shape (Ny, Nx)
+        else:
+            z = x
+        
+        m1, m2 = self._eval_stieltjes(z)
 
         if plot:
             plot_stieltjes(x, y, m1, m2, self.support, latex=latex, save=save)
@@ -766,44 +725,26 @@ class FreeForm(object):
 
         m_m : numpy.ndarray
             The Stieltjes transform continued to the secondary branch.
-
-        See Also
-        --------
-        density
-        hilbert
-
-        Notes
-        -----
-
-        Notes.
-
-        References
-        ----------
-
-        .. [1] tbd
-
-        Examples
-        --------
-
-        .. code-block:: python
-
-            >>> from freealg import FreeForm
         """
 
-        if self.psi is None:
-            raise RuntimeError('"fit" the model first.')
+        assert self.psi is not None, "The fit function has not been called."
 
+        # Allow for arbitrary input shapes
         z = numpy.asarray(z)
         shape = z.shape
         if len(shape) == 0:
             shape = (1,)
         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)
+        # 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)
+                                beta=self.beta) # n_base = n_base
         elif self.method == 'chebyshev':
             stieltjes = partial(chebyshev_stieltjes, psi=self.psi,
                                 support=self.support)
@@ -814,17 +755,25 @@ class FreeForm(object):
         m1 = numpy.zeros_like(z)
         m2 = numpy.zeros_like(z)
 
-        # Upper half-plane
-        m1[mask_p] = stieltjes(z[mask_p].reshape(-1, 1)).reshape(-1)
+        if self._pade_sol is not None:
+            # Upper half-plane
+            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)))).reshape(-1)
+            # Lower half-plane, use Schwarz reflection
+            m1[mask_m] = numpy.conjugate(
+                stieltjes(numpy.conjugate(z[mask_m].reshape(-1, 1)))).ravel()
 
-        # Second Riemann sheet
-        m2[mask_p] = m1[mask_p]
-        m2[mask_m] = -m1[mask_m] + self._glue(
-            z[mask_m].reshape(-1, 1)).reshape(-1)
+            # 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)
 
@@ -834,8 +783,8 @@ class FreeForm(object):
     # decompress
     # ==========
 
-    def decompress(self, size, x=None, delta=1e-6, iterations=500,
-                   step_size=0.1, tolerance=1e-4, seed=None, plot=False,
+    def decompress(self, size, x=None, iterations=500, eigvals=True,
+                   step_size=0.1, tolerance=1e-9, seed=None, plot=False,
                    latex=False, save=False):
         """
         Free decompression of spectral density.
@@ -850,17 +799,16 @@ class FreeForm(object):
             Positions where density to be evaluated at. If `None`, an interval
             slightly larger than the support interval will be used.
 
-        delta: float, default=1e-4
-            Size of the perturbation into the upper half plane for Plemelj's
-            formula.
-
         iterations: int, default=500
             Maximum number of Newton 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-4
+        tolerance: float, default=1e-9
             Tolerance for the solution obtained by the Newton solver. Also
             used for the finite difference approximation to the derivative.
 
@@ -882,12 +830,15 @@ class FreeForm(object):
         Returns
         -------
 
+        x : numpy.array
+            Locations where the spectral density is estimated
+
         rho : numpy.array
-            Spectral density
+            Estimated spectral density at locations x
 
         eigs : numpy.array
             Estimated eigenvalues as low-discrepancy samples of the estimated
-            spectral density.
+            spectral density. Only returns if ``eigvals=True``.
 
         See Also
         --------
@@ -915,7 +866,7 @@ class FreeForm(object):
 
         size = int(size)
 
-        rho, x, (lb, ub) = decompress(self, size, x=x, delta=delta,
+        rho, x, (lb, ub) = decompress(self, size, x=x, delta=self.delta,
                                       iterations=iterations,
                                       step_size=step_size, tolerance=tolerance)
         x, rho = x.ravel(), rho.ravel()
@@ -924,6 +875,94 @@ class FreeForm(object):
             plot_density(x, rho, support=(lb, ub),
                          label='Decompression', latex=latex, save=save)
 
-        eigs = numpy.sort(qmc_sample(x, rho, size, seed=seed))
+        if eigvals:
+            eigs = numpy.sort(qmc_sample(x, rho, size, seed=seed))
+            return x, rho, eigs
+        else:
+            return x, rho
+
+def eigfree(A, N = None, psd = None):
+    """
+    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 
+    the FreeForm class.
 
-        return rho, eigs
+    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.
+
+    Notes
+    -----
+
+    Notes.
+
+    References
+    ----------
+
+    .. [1] Reference.
+
+    Examples
+    --------
+
+    .. code-block:: python
+
+        >>> from freealg import FreeForm
+    """
+    n = A.shape[0]
+    
+    # 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)
+
+    # 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', damp='jackson', 
+           force=True, plot=False, latex=False, save=False, reg=0.05)
+    _, _, eigs = ff.decompress(N)
+
+    if psd:
+        eigs = numpy.abs(eigs)
+        eigs.sort()
+
+    return eigs

{freealg-0.1.10 → freealg-0.1.12}/freealg.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.1.10
+Version: 0.1.12
 Summary: Free probability for large matrices
 Keywords: leaderboard bot chat
 Platform: Linux
@@ -31,6 +31,7 @@ Requires-Dist: texplot
 Requires-Dist: matplotlib
 Requires-Dist: colorcet
 Requires-Dist: statsmodels
+Requires-Dist: numba
 Provides-Extra: test
 Requires-Dist: tox; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -69,7 +70,10 @@ Dynamic: summary
     :width: 240
     :class: custom-dark
 
-*freealg* is a python package that employs **free** probability for large matrix **form**\ s.
+*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 
+submatrices to infer the eigenspectrum of extremely large matrices. 
 
 Install
 =======
@@ -95,12 +99,18 @@ Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/
 Quick Usage
 ===========
 
-Create and Train a Model
-------------------------
+The following code estimates the eigenvalues of a very large Wishart matrix using a much
+smaller Wishart matrix.
 
 .. code-block:: python
 
     >>> import freealg as fa
+    >>> mp = fa.distributions.MarchenkoPastur(1/50) # Wishart matrices with aspect ratio 1/50
+    >>> A = mp.matrix(1000)                         # Sample a 1000 x 1000 Wishart matrix
+    >>> eigs = fa.eigfree(A, 100_000)               # Estimate the eigenvalues of 100000 x 100000
+
+For more details on how to interface with *freealg* check out the `Quick Start Guide <https://github.com/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__.
+
 
 Test
 ====
@@ -130,14 +140,18 @@ requests and bug reports.
 How to Cite
 ===========
 
-* TBD
+If you use this work, please cite the `arXiv paper <https://arxiv.org/abs/2506.11994>`.
 
   .. code::
 
-      @inproceedings{
-          TBD
+      @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}
       }
 
+
 License
 =======
 

{freealg-0.1.10 → freealg-0.1.12}/freealg.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ freealg/_jacobi.py
 freealg/_pade.py
 freealg/_plot_util.py
 freealg/_sample.py
+freealg/_support.py
 freealg/_util.py
 freealg/freeform.py
 freealg.egg-info/PKG-INFO

{freealg-0.1.10 → freealg-0.1.12}/freealg.egg-info/requires.txt

@@ -4,6 +4,7 @@ texplot
 matplotlib
 colorcet
 statsmodels
+numba
 
 [docs]
 sphinx

{freealg-0.1.10 → freealg-0.1.12}/requirements.txt

@@ -4,3 +4,4 @@ texplot
 matplotlib
 colorcet
 statsmodels
+numba

freealg-0.1.10/freealg/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.10"