freealg 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

freealg/__init__.py

@@ -7,9 +7,10 @@
 # directory of this source tree.
 
 from .freeform import FreeForm
-from .eigh import eigh, cond
+from .eigh import eigh, cond, norm, trace, slogdet
 from . import distributions
 
-__all__ = ['FreeForm', 'distributions', 'eigh', 'cond']
+__all__ = ['FreeForm', 'distributions', 'eigh', 'cond', 'norm', 'trace',
+           'slogdet']
 
 from .__version__ import __version__                          # noqa: F401 E402

freealg/__version__.py

@@ -1 +1 @@
-__version__ = "0.2.0"
+__version__ = "0.3.1"

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

@@ -14,7 +14,7 @@ import numpy
 from ._util import compute_eig
 from .freeform import FreeForm
 
-__all__ = ['eigh', 'cond']
+__all__ = ['eigh', 'cond', 'norm', 'trace', 'slogdet']
 
 
 # ====
@@ -141,7 +141,7 @@ def eigh(A, N=None, psd=None, plots=False):
 
 def cond(A, N=None):
     """
-    Estimate the condition number of a positive-definite matrix.
+    Estimate the condition number of a Hermitian positive-definite matrix.
 
     This function estimates the condition number of the matrix
     :math:`\\mathbf{A}` or a larger matrix containing :math:`\\mathbf{A}`
@@ -170,6 +170,9 @@ def cond(A, N=None):
     --------
 
     eigh
+    norm
+    slogdet
+    trace
 
     Notes
     -----
@@ -190,5 +193,234 @@ def cond(A, N=None):
         >>> cond(A)
     """
 
-    eigs = eigh(A, N)
+    eigs = eigh(A, N, psd=True)
     return eigs.max() / eigs.min()
+
+
+# ====
+# norm
+# ====
+
+def norm(A, N=None, order=None):
+    """
+    Estimate the Schatten norm of a Hermitian matrix.
+
+    This function estimates the norm 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 condition
+        number (or that 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.
+
+    order : {float, ``''inf``, ``'-inf'``, ``'fro'``, ``'nuc'``}, default=2
+        Order of the norm.
+
+        * float :math:`p`: Schtten 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`
+
+    Returns
+    -------
+
+    norm : float
+        matrix norm
+
+    See Also
+    --------
+
+    eigh
+    cond
+    slogdet
+    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: 6
+
+        >>> from freealg import norm
+        >>> from freealg.distributions import MarchenkoPastur
+
+        >>> mp = MarchenkoPastur(1/50)
+        >>> A = mp.matrix(3000)
+        >>> norm(A, 100_000, order='fro')
+    """
+
+    eigs = eigh(A, N)
+
+    if (order == 'inf') or numpy.isinf(order):
+        norm_ = max(numpy.abs(eigs))
+
+    elif (order == '-inf') or numpy.isneginf(order):
+        norm_ = min(numpy.abs(eigs))
+
+    elif (order == 'nuc') or (order == 1.0):
+        norm_ = numpy.sum(numpy.abs(eigs))
+
+    elif (order == 'fro') or (order == 2.0):
+        norm_2 = numpy.sum(numpy.abs(eigs)**2)
+        norm_ = numpy.sqrt(norm_2)
+
+    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)
+
+    else:
+        raise ValueError('"order" is invalid.')
+
+    return norm_
+
+
+# =====
+# trace
+# =====
+
+def trace(A, N=None):
+    """
+    Estimate the trace 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.
+
+    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
+        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.
+
+    Returns
+    -------
+
+    trace : float
+        matrix trace
+
+    See Also
+    --------
+
+    eigh
+    cond
+    slogdet
+    norm
+
+    Notes
+    -----
+
+    This is a convenience function using :func:`freealg.eigh`.
+
+    Examples
+    --------
+
+    .. code-block:: python
+        :emphasize-lines: 6
+
+        >>> from freealg import norm
+        >>> from freealg.distributions import MarchenkoPastur
+
+        >>> mp = MarchenkoPastur(1/50)
+        >>> A = mp.matrix(3000)
+        >>> trace(A, 100_000)
+    """
+
+    eigs = eigh(A, N)
+    trace_ = numpy.sum(eigs)
+
+    return trace_
+
+
+# =======
+# slogdet
+# =======
+
+def slogdet(A, N=None):
+    """
+    Estimate the sign and logarithm of the determinant of a Hermitian matrix.
+
+    This function estimates the *slogdet* 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 condition
+        number (or that 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.
+
+    Returns
+    -------
+
+    sign : float
+        Sign of determinant
+
+    ld : float
+        natural logarithm of the absolute value of the determinant
+
+    See Also
+    --------
+
+    eigh
+    cond
+    trace
+    norm
+
+    Notes
+    -----
+
+    This is a convenience function using :func:`freealg.eigh`.
+
+    Examples
+    --------
+
+    .. code-block:: python
+        :emphasize-lines: 6
+
+        >>> from freealg import norm
+        >>> from freealg.distributions import MarchenkoPastur
+
+        >>> mp = MarchenkoPastur(1/50)
+        >>> A = mp.matrix(3000)
+        >>> sign, ld = slogdet(A, 100_000)
+    """
+
+    eigs = eigh(A, N)
+    sign = numpy.prod(numpy.sign(eigs))
+    ld = numpy.sum(numpy.log(numpy.abs(eigs)))
+
+    return sign, ld

freealg/freeform.py

@@ -59,13 +59,14 @@ class FreeForm(object):
         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``.
+    **kwargs : dict, optional
+        Parameters for the ``detect_support`` function can also be prescribed
+        here when ``support=None``.
 
     Notes
     -----
 
-    Notes.
+    TBD
 
     References
     ----------

{freealg-0.2.0.dist-info → freealg-0.3.1.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: freealg
-Version: 0.2.0
+Version: 0.3.1
 Summary: Free probability for large matrices
-Keywords: leaderboard bot chat
+Keywords: linalg,free-probability
 Platform: Linux
 Platform: OSX
 Platform: Windows
@@ -52,7 +52,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://ameli.github.io/freealg/jlite/lab/index.html?path=quick_start.ipynb>`__
 
 .. `Slides <https://ameli.github.io/freealg/_static/data/slides.pdf>`__ |
 

{freealg-0.2.0.dist-info → freealg-0.3.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
-freealg/__init__.py,sha256=hxGvn8bF29NI4J7QnHrUfI7j_qh5lSwOF5g-QL5W7fc,553
-freealg/__version__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+freealg/__init__.py,sha256=AM0G2tX7sBgzCTcOVbWynA9NFkQZKyphL9IR1tKOoK4,614
+freealg/__version__.py,sha256=r4xAFihOf72W9TD-lpMi6ntWSTKTP2SlzKP1ytkjRbI,22
 freealg/_chebyshev.py,sha256=dsAj3YEpmkzB65smluZ0Fi5IZSdpnQXBSIuKMg19grA,5523
 freealg/_damp.py,sha256=k2vtBtWOxQBf4qXaWu_En81lQBXbEO4QbxxWpvuVhdE,1802
 freealg/_decompress.py,sha256=0MYoO3lqwMgNYlVriaRNUqUwY3XYyZZsDAtNRBq6rhE,10470
@@ -7,19 +7,19 @@ 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=4N_nbh-4ubcIC6ZJpoql3LakSt0fEUjQT2p_yE-bdmo,6438
 freealg/_util.py,sha256=8Tvz-XODtKYoU76ODmF1TBaIYLlr6-AXiyoMDwDSxVg,3779
-freealg/eigh.py,sha256=L_KGD75mKgfVmUs0AcMpZcWc_lAZxChhT-bGesxwrHA,4744
-freealg/freeform.py,sha256=_0hUqIJJ3jGiWY-yJSQUkDG-hXr2VQ83WwChrnkxmu0,28558
+freealg/eigh.py,sha256=rSGAcmp3bjyiRT479wfggvNyOqbjj7lSUjKIA-FfeVE,10119
+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
 freealg/distributions/_marchenko_pastur.py,sha256=kchFccRMuVF2Cus_99vdEwuRimkHzEUV8xt5kZFg7ZI,16994
 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.2.0.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
-freealg-0.2.0.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
-freealg-0.2.0.dist-info/METADATA,sha256=eqW_KJcQirHZZ2hg_iFEVklzPgF9FjStyqMPMf89fEA,4496
-freealg-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-freealg-0.2.0.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
-freealg-0.2.0.dist-info/RECORD,,
+freealg-0.3.1.dist-info/licenses/AUTHORS.txt,sha256=0b67Nz4_JgIzUupHJTAZxu5QdSUM_HRM_X_w4xCb17o,30
+freealg-0.3.1.dist-info/licenses/LICENSE.txt,sha256=J-EEYEtxb3VVf_Bn1TYfWnpY5lMFIM15iLDDcnaDTPA,1443
+freealg-0.3.1.dist-info/METADATA,sha256=F2ymhxBRzrg3dCOi-rcZ4StLoLHk51gd6cBlbBzP2NY,4593
+freealg-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+freealg-0.3.1.dist-info/top_level.txt,sha256=eR2wrgYwDdnnJ9Zf5PruPqe4kQav0GMvRsqct6y00Q8,8
+freealg-0.3.1.dist-info/RECORD,,