freealg 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

freealg/__version__.py

@@ -1 +1 @@
-__version__ = "0.3.0"
+__version__ = "0.3.2"

freealg/_support.py

@@ -127,7 +127,7 @@ def detect_support(eigs, method='asymp', k=None, p=0.001, **kwargs):
         * ``'interior'``: estimates a support assuming the range overestimates;
             uses quantiles (p, 1-p).
         * ``'interior_smooth'``: same as ``'interior'`` but using kernel
-            density estimation.
+            density estimation, from [2]_.
 
     k : int, default = None
         Number of extreme order statistics to use for ``method='regression'``.
@@ -142,10 +142,12 @@ def detect_support(eigs, method='asymp', k=None, p=0.001, **kwargs):
     References
     ----------
 
-    .. [1] Quenouille, M. H. (1949, July). Approximate tests of correlation in
+    .. [1] Quenouille, M. H. (1949). 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.
+    .. [2] Cuevas, A., & Fraiman, R. (1997). A plug-in approach to support
+           estimation. The Annals of Statistics, 2300-2312.
     """
 
     if method == 'range':

freealg/eigh.py

@@ -17,6 +17,33 @@ from .freeform import FreeForm
 __all__ = ['eigh', 'cond', 'norm', 'trace', 'slogdet']
 
 
+def _subsample_apply(f, A, output_array=False):
+    """Compute f(A_n) over subsamples A_n of A. If the output of
+    f is an array (e.g. eigvals), specify output_array to be True."""
+
+    if A.ndim != 2 or A.shape[0] != A.shape[1]:
+        raise RuntimeError("Only square matrices are permitted.")
+    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 f(A), 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(f(A[numpy.ix_(indices, indices)]))
+    if output_array:
+        return numpy.concatenate(samples).ravel(), n, n_s
+
+    return numpy.array(samples), n, n_s
+
+
 # ====
 # eigh
 # ====
@@ -86,29 +113,11 @@ def eigh(A, N=None, psd=None, plots=False):
         >>> A = mp.matrix(3000)
         >>> eigs = eigh(A)
     """
-
-    if A.ndim != 2 or A.shape[0] != A.shape[1]:
-        raise RuntimeError("Only square matrices are permitted.")
-    n = A.shape[0]
+    samples, n, n_s = _subsample_apply(compute_eig, A, output_array=True)
 
     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
@@ -193,7 +202,7 @@ def cond(A, N=None):
         >>> cond(A)
     """
 
-    eigs = eigh(A, N)
+    eigs = eigh(A, N, psd=True)
     return eigs.max() / eigs.min()
 
 
@@ -224,7 +233,7 @@ def norm(A, N=None, order=None):
     order : {float, ``''inf``, ``'-inf'``, ``'fro'``, ``'nuc'``}, default=2
         Order of the norm.
 
-        * float :math:`p`: Schtten p-norm.
+        * float :math:`p`: Schatten p-norm.
         * ``'inf'``: Largest absolute eigenvalue
           :math:`\\max \\vert \\lambda_i \\vert)`
         * ``'-inf'``: Smallest absolute eigenvalue
@@ -300,19 +309,19 @@ def norm(A, N=None, order=None):
 # trace
 # =====
 
-def trace(A, N=None):
+def trace(A, N=None, p=1.0):
     """
-    Estimate the trace of a Hermitian matrix.
+    Estimate the trace of a power of a Hermitian matrix.
 
-    This function estimates the trace of the matrix :math:`\\mathbf{A}` or a
-    larger matrix containing :math:`\\mathbf{A}` using free decompression.
+    This function estimates the trace of the matrix power :math:`\\mathbf{A}^p`
+    or that of a larger matrix containing :math:`\\mathbf{A}`.
 
     Parameters
     ----------
 
     A : numpy.ndarray
-        The symmetric real-valued matrix :math:`\\mathbf{A}` whose condition
-        number (or that of a matrix containing :math:`\\mathbf{A}`) are to be
+        The symmetric real-valued matrix :math:`\\mathbf{A}` whose trace of
+        a power (or that of a matrix containing :math:`\\mathbf{A}`) is to be
         computed.
 
     N : int, default=None
@@ -320,6 +329,10 @@ def trace(A, N=None):
         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`.
+
+
     Returns
     -------
 
@@ -337,7 +350,9 @@ def trace(A, N=None):
     Notes
     -----
 
-    This is a convenience function using :func:`freealg.eigh`.
+    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:`freealg.eigh`.
 
     Examples
     --------
@@ -352,11 +367,14 @@ def trace(A, N=None):
         >>> A = mp.matrix(3000)
         >>> trace(A, 100_000)
     """
-
-    eigs = eigh(A, N)
-    trace_ = numpy.sum(eigs)
-
-    return trace_
+    if numpy.isclose(p, 1.0):
+        samples, n, n_s = _subsample_apply(numpy.trace, A, output_array=False)
+        if N is None:
+            N = n
+        return numpy.mean(samples) * (N / n_s)
+
+    eig = eigh(A, N)
+    return numpy.sum(eig ** p)
 
 
 # =======

{freealg-0.3.0.dist-info → freealg-0.3.2.dist-info}/METADATA

@@ -1,8 +1,13 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.3.0
+Version: 0.3.2
 Summary: Free probability for large matrices
-Keywords: leaderboard bot chat
+Home-page: https://github.com/ameli/freealg
+Download-URL: https://github.com/ameli/freealg/archive/main.zip
+Project-URL: Documentation, https://github.com/ameli/freealg/blob/main/README.rst
+Project-URL: Source, https://github.com/ameli/freealg
+Project-URL: Tracker, https://github.com/ameli/freealg/issues
+Keywords: linalg,free-probability
 Platform: Linux
 Platform: OSX
 Platform: Windows
@@ -37,9 +42,12 @@ Provides-Extra: docs
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
 Dynamic: keywords
 Dynamic: license-file
 Dynamic: platform
+Dynamic: project-url
 Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
@@ -52,7 +60,8 @@ Dynamic: summary
 
 `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>`__
+`Docs <https://ameli.github.io/freealg>`__ |
+`Live Demo <https://colab.research.google.com/github/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__
 
 .. `Slides <https://ameli.github.io/freealg/_static/data/slides.pdf>`__ |
 
@@ -126,7 +135,7 @@ 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 our `arXiv paper <https://arxiv.org/abs/2506.11994>`__.
 
   .. code::
 

{freealg-0.3.0.dist-info → freealg-0.3.2.dist-info}/RECORD

@@ -1,5 +1,5 @@
 freealg/__init__.py,sha256=AM0G2tX7sBgzCTcOVbWynA9NFkQZKyphL9IR1tKOoK4,614
-freealg/__version__.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
+freealg/__version__.py,sha256=vNiWJ14r_cw5t_7UDqDQIVZvladKFGyHH2avsLpN7Vg,22
 freealg/_chebyshev.py,sha256=dsAj3YEpmkzB65smluZ0Fi5IZSdpnQXBSIuKMg19grA,5523
 freealg/_damp.py,sha256=k2vtBtWOxQBf4qXaWu_En81lQBXbEO4QbxxWpvuVhdE,1802
 freealg/_decompress.py,sha256=0MYoO3lqwMgNYlVriaRNUqUwY3XYyZZsDAtNRBq6rhE,10470
@@ -7,9 +7,9 @@ freealg/_jacobi.py,sha256=AT4ONSHGGDxVKE3MGMLyMR8uDFiO-e9u3x5udYfdJJk,5635
 freealg/_pade.py,sha256=Diw850oH2OLQeUrBR-q19TmjSBoBvXl6ogp4o1s2UIo,15184
 freealg/_plot_util.py,sha256=U4alp7Pzg315_7jJdu1UB0tIUcxUovQgHDHsUYoa2Z0,19728
 freealg/_sample.py,sha256=ckC75eqv-mRP1F5BnhvsjfLTaoAzHK8bebl9bCRZYDo,2561
-freealg/_support.py,sha256=sxp867DxfmvYqyQNOyla3zlcVyxm7KL0M-fxZaRIw8E,6299
+freealg/_support.py,sha256=mYlrsdLbniqFgFofbHrZIiYSyJudPqtyMQQTPBD9Y6M,6439
 freealg/_util.py,sha256=8Tvz-XODtKYoU76ODmF1TBaIYLlr6-AXiyoMDwDSxVg,3779
-freealg/eigh.py,sha256=Vm9kLiksmOhsbsxUH7vBtAAKEtwR_RHeEDJCH4Qkr28,10109
+freealg/eigh.py,sha256=5SFixxpXiVBsf5R9S0neg1lqWgmPoqGwVx4jwunh0xg,10856
 freealg/freeform.py,sha256=8emyCQ6AUjp_HB1gWQ-ecddlDgfxHGr3PqXSyoPxeMo,28593
 freealg/distributions/__init__.py,sha256=t_yZyEkW_W_tSV9IvgYXtVASxD2BEdiNVXcV2ebMy8M,579
 freealg/distributions/_kesten_mckay.py,sha256=210RF2OQEYLZBeLB6wmbdHnZPs_9ldDNHm_FMlg5tis,19881
@@ -17,9 +17,9 @@ freealg/distributions/_marchenko_pastur.py,sha256=kchFccRMuVF2Cus_99vdEwuRimkHzE
 freealg/distributions/_meixner.py,sha256=ws7t_EUa7V0s97dgMQIJLv1b6qMLqf9fLLbTJQudf_8,17512
 freealg/distributions/_wachter.py,sha256=Hna_MXqAPjuRkeilLPMf4Xg_3C6tTu5oZLEQnA-RuE4,16897
 freealg/distributions/_wigner.py,sha256=SxgPLtvIVBi9m4De-oBD0x6-2Je_eBqpDrpDYcoLuis,15871
-freealg-0.3.0.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
-freealg-0.3.0.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
-freealg-0.3.0.dist-info/METADATA,sha256=Z9HFCclNCRzFORlR2dQ6pzvPmAJfa5-Dxpee67QxqdM,4496
-freealg-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-freealg-0.3.0.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
-freealg-0.3.0.dist-info/RECORD,,
+freealg-0.3.2.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
+freealg-0.3.2.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
+freealg-0.3.2.dist-info/METADATA,sha256=uRwMJGay5-IuqPSOWqpoMeaSqbNC1dq47moA2MxkGlo,4978
+freealg-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+freealg-0.3.2.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
+freealg-0.3.2.dist-info/RECORD,,