freealg 0.2.0__tar.gz → 0.3.1__tar.gz

{freealg-0.2.0 → freealg-0.3.1}/PKG-INFO

@@ -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
@@ -72,7 +72,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 → freealg-0.3.1}/README.rst

@@ -5,7 +5,8 @@
 
 `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 → freealg-0.3.1}/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-0.3.1/freealg/__version__.py

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

{freealg-0.2.0 → freealg-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-0.3.1/freealg/eigh.py

@@ -0,0 +1,426 @@
+# 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__ = ['eigh', 'cond', 'norm', 'trace', 'slogdet']
+
+
+# ====
+# eigh
+# ====
+
+def eigh(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.
+
+    Returns
+    -------
+
+    eigs : numpy.array
+        Eigenvalues of decompressed matrix
+
+    See Also
+    --------
+
+    cond
+
+    Notes
+    -----
+
+    This is a convenience function for the :class:`freealg.FreeForm` class with
+    some effective defaults that work well for common random matrix ensembles.
+    For improved performance and plotting utilites, consider fine-tuning
+    parameters using the FreeForm class.
+
+    References
+    ----------
+
+    .. [1] Reference.
+
+    Examples
+    --------
+
+    .. code-block:: python
+        :emphasize-lines: 6
+
+        >>> from freealg import cond
+        >>> from freealg.distributions import MarchenkoPastur
+
+        >>> mp = MarchenkoPastur(1/50)
+        >>> 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]
+
+    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
+
+
+# ====
+# cond
+# ====
+
+def cond(A, N=None):
+    """
+    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}`
+    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
+    -------
+
+    c : float
+        Condition number
+
+    See Also
+    --------
+
+    eigh
+    norm
+    slogdet
+    trace
+
+    Notes
+    -----
+
+    This is a convenience function using :func:`freealg.eigh`.
+
+    Examples
+    --------
+
+    .. code-block:: python
+        :emphasize-lines: 6
+
+        >>> from freealg import cond
+        >>> from freealg.distributions import MarchenkoPastur
+
+        >>> mp = MarchenkoPastur(1/50)
+        >>> A = mp.matrix(3000)
+        >>> cond(A)
+    """
+
+    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-0.2.0 → freealg-0.3.1}/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 → freealg-0.3.1}/freealg.egg-info/PKG-INFO

@@ -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
@@ -72,7 +72,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 → freealg-0.3.1}/setup.py

@@ -165,7 +165,7 @@ def main(argv):
         description=description,
         long_description=long_description,
         long_description_content_type='text/x-rst',
-        keywords="""leaderboard bot chat""",
+        keywords="""linalg, free-probability""",
         platforms=['Linux', 'OSX', 'Windows'],
         packages=setuptools.find_packages(exclude=[
             'tests.*',

freealg-0.2.0/freealg/__version__.py

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

freealg-0.2.0/freealg/eigh.py

@@ -1,194 +0,0 @@
-# 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__ = ['eigh', 'cond']
-
-
-# ====
-# eigh
-# ====
-
-def eigh(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.
-
-    Returns
-    -------
-
-    eigs : numpy.array
-        Eigenvalues of decompressed matrix
-
-    See Also
-    --------
-
-    cond
-
-    Notes
-    -----
-
-    This is a convenience function for the :class:`freealg.FreeForm` class with
-    some effective defaults that work well for common random matrix ensembles.
-    For improved performance and plotting utilites, consider fine-tuning
-    parameters using the FreeForm class.
-
-    References
-    ----------
-
-    .. [1] Reference.
-
-    Examples
-    --------
-
-    .. code-block:: python
-        :emphasize-lines: 6
-
-        >>> from freealg import cond
-        >>> from freealg.distributions import MarchenkoPastur
-
-        >>> mp = MarchenkoPastur(1/50)
-        >>> 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]
-
-    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
-
-
-# ====
-# cond
-# ====
-
-def cond(A, N=None):
-    """
-    Estimate the condition number of a positive-definite matrix.
-
-    This function estimates the condition number 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
-    -------
-
-    c : float
-        Condition number
-
-    See Also
-    --------
-
-    eigh
-
-    Notes
-    -----
-
-    This is a convenience function using :func:`freealg.eigh`.
-
-    Examples
-    --------
-
-    .. code-block:: python
-        :emphasize-lines: 6
-
-        >>> from freealg import cond
-        >>> from freealg.distributions import MarchenkoPastur
-
-        >>> mp = MarchenkoPastur(1/50)
-        >>> A = mp.matrix(3000)
-        >>> cond(A)
-    """
-
-    eigs = eigh(A, N)
-    return eigs.max() / eigs.min()