freealg 0.0.1__tar.gz

freealg-0.0.1/CHANGELOG.rst

@@ -0,0 +1,18 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
+and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
+
+[Unreleased]
+------------
+
+[0.0.1] - 2024-09-04
+--------------------
+
+Changed
+~~~~~~~
+
+packaging

freealg-0.0.1/LICENSE.txt

@@ -0,0 +1,24 @@
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

freealg-0.0.1/MANIFEST.in

@@ -0,0 +1,29 @@
+global-exclude *.py[cod] __pycache__
+global-exclude *.so *.dll *.dylib
+global-exclude *.o
+global-exclude *.swp
+
+recursive-include freealg *.rst
+recursive-include freealg/data *.json
+
+include CHANGELOG.rst
+include README.rst
+include LICENSE.txt
+include requirements.txt
+include pyproject.toml
+
+exclude .gitattributes
+exclude .tokeignore
+exclude .coveragerc
+exclude tox.ini
+exclude TODO.rst
+exclude CONTRIBUTING.rst
+exclude notebook/experimental/clean_battle_20240814_public.json
+
+prune docs
+prune archive
+prune benchmark
+prune notebooks
+prune tests
+prune .git
+prune .github

freealg-0.0.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: freealg
+Version: 0.0.1
+Summary: Free probability for large matrices
+Keywords: leaderboard bot chat
+Platform: Linux
+Platform: OSX
+Platform: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: texplot
+Requires-Dist: matplotlib
+Requires-Dist: colorcet
+Provides-Extra: test
+Requires-Dist: tox; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: codecov; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-math-dollar; extra == "docs"
+Requires-Dist: sphinx-toggleprompt<0.4; extra == "docs"
+Requires-Dist: pydata_sphinx_theme==0.9.0; extra == "docs"
+Requires-Dist: graphviz; extra == "docs"
+Requires-Dist: sphinx-automodapi; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: sphinx_design; extra == "docs"
+Requires-Dist: sphinx-multitoc-numbering; extra == "docs"
+Requires-Dist: pandoc; extra == "docs"
+Requires-Dist: sphinx-prompt; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-gallery; extra == "docs"
+Requires-Dist: sphinxcontrib-youtube; extra == "docs"
+Requires-Dist: sphinxext-opengraph; extra == "docs"
+Requires-Dist: sphinx-argparse; extra == "docs"
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+.. image:: https://raw.githubusercontent.com/ameli/freealg/refs/heads/main/docs/source/_static/images/icons/logo-freealg-light.png
+    :align: left
+    :width: 240
+    :class: custom-dark
+
+*freealg* is a python package that employs **free** probability for large matrix **form**\ s.
+
+Install
+=======
+
+Install with ``pip``:
+
+.. code-block::
+
+    pip install freealg
+
+Alternatively, clone the source code and install with
+
+.. code-block::
+
+    cd source_dir
+    pip install .
+
+Documentation
+=============
+
+Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/freealg>`__.
+
+Quick Usage
+===========
+
+Create and Train a Model
+------------------------
+
+.. code-block:: python
+
+    >>> import freealg as fa
+
+Test
+====
+
+You may test the package with `tox <https://tox.wiki/>`__:
+
+.. code-block::
+
+    cd source_dir
+    tox
+
+Alternatively, test with `pytest <https://pytest.org>`__:
+
+.. code-block::
+
+    cd source_dir
+    pytest
+
+How to Contribute
+=================
+
+We welcome contributions via GitHub's pull request. Developers should review
+our [Contributing Guidelines](CONTRIBUTING.rst) before submitting their code.
+If you do not feel comfortable modifying the code, we also welcome feature
+requests and bug reports.
+
+How to Cite
+===========
+
+* TBD
+
+  .. code::
+
+      @inproceedings{
+          TBD
+      }
+
+License
+=======
+
+|license|
+
+.. |license| image:: https://img.shields.io/github/license/ameli/freealg
+   :target: https://opensource.org/licenses/BSD-3-Clause

freealg-0.0.1/README.rst

@@ -0,0 +1,81 @@
+.. image:: https://raw.githubusercontent.com/ameli/freealg/refs/heads/main/docs/source/_static/images/icons/logo-freealg-light.png
+    :align: left
+    :width: 240
+    :class: custom-dark
+
+*freealg* is a python package that employs **free** probability for large matrix **form**\ s.
+
+Install
+=======
+
+Install with ``pip``:
+
+.. code-block::
+
+    pip install freealg
+
+Alternatively, clone the source code and install with
+
+.. code-block::
+
+    cd source_dir
+    pip install .
+
+Documentation
+=============
+
+Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/freealg>`__.
+
+Quick Usage
+===========
+
+Create and Train a Model
+------------------------
+
+.. code-block:: python
+
+    >>> import freealg as fa
+
+Test
+====
+
+You may test the package with `tox <https://tox.wiki/>`__:
+
+.. code-block::
+
+    cd source_dir
+    tox
+
+Alternatively, test with `pytest <https://pytest.org>`__:
+
+.. code-block::
+
+    cd source_dir
+    pytest
+
+How to Contribute
+=================
+
+We welcome contributions via GitHub's pull request. Developers should review
+our [Contributing Guidelines](CONTRIBUTING.rst) before submitting their code.
+If you do not feel comfortable modifying the code, we also welcome feature
+requests and bug reports.
+
+How to Cite
+===========
+
+* TBD
+
+  .. code::
+
+      @inproceedings{
+          TBD
+      }
+
+License
+=======
+
+|license|
+
+.. |license| image:: https://img.shields.io/github/license/ameli/freealg
+   :target: https://opensource.org/licenses/BSD-3-Clause

freealg-0.0.1/freealg/__init__.py

@@ -0,0 +1,13 @@
+# 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.
+
+from .freeform import FreeForm
+
+__all__ = ['FreeForm']
+
+from .__version__ import __version__                          # noqa: F401 E402

freealg-0.0.1/freealg/__version__.py

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

freealg-0.0.1/freealg/_chebyshev.py

@@ -0,0 +1,201 @@
+# 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 scipy.special import eval_chebyu
+
+__all__ = ['chebyshev_proj', 'chebyshev_approx', 'chebyshev_stieltjes']
+
+
+# ==============
+# chebyshev proj
+# ==============
+
+def chebyshev_proj(eig, support, K=10, reg=0.0):
+    """
+    Estimate the coefficients \\psi_k in
+
+        \\rho(x) = w(t) \\sum_{k=0}^K \\psi_k U_k(t),
+
+    where t = (2x–(\\lambda_{-} + \\lambda_{+}))/ (\\lambda_{+} - \\lambda_{-})
+    in [-1, 1] and w(t) = \\sqrt{(1 - t^2}.
+
+    Parameters
+    ----------
+
+    eig : array_like, shape (N,)
+        The raw eigenvalues x_i.
+
+    support : tuple
+        The assumed compact support of rho.
+
+    K : int
+        Highest Chebyshev‐II order.
+
+    reg : float
+        Tikhonov‐style ridge on each coefficient (defaults to 0).
+
+    Returns
+    -------
+
+    psi : ndarray, shape (K+1,)
+        The projected coefficients \\psi_k.
+    """
+
+    lam_m, lam_p = support
+
+    # Map to [–1,1] interval
+    t = (2 * eig - (lam_m + lam_p)) / (lam_p - lam_m)
+    N = eig.size
+
+    # Inner‐product norm of each U_k under w(t) = sqrt{1–t^2} is \\pi/2
+    norm = numpy.pi / 2
+
+    psi = numpy.empty(K+1)
+    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
+
+        # Regularization
+        if k == 0:
+            # Do not penalize at k=0, as this  keeps unit mass.
+            # k=0 has unit mass, while k>0 has zero mass by orthogonality.
+            penalty = 0
+        else:
+            penalty = reg * (k / (K + 1))**2
+
+        # Add regularization on the diagonal
+        psi[k] = M_k / (norm + penalty)
+
+    return psi
+
+
+# ================
+# chebyshev approx
+# ================
+
+def chebyshev_approx(x, psi, support):
+    """
+    Given \\psi_k, evaluate the approximate density \\rho(x).
+
+    Parameters
+    ----------
+
+    x : array_like
+        Points at which to evaluate \\rho.
+
+    psi : array_like, shape (K+1,)
+        Coefficients from chebyshev_proj.
+
+    support : tuple
+        Same support used for projection.
+
+    Returns
+    -------
+
+    rho_x : ndarray, same shape as x
+        Approximated spectral density on the original x‐axis.
+    """
+
+    lam_m, lam_p = support
+
+    # Map to [–1,1] interval
+    t = (2 * numpy.asarray(x) - (lam_m + lam_p)) / (lam_p - lam_m)
+
+    # Weight sqrt{1–t^2} (clip for numerical safety)
+    w = numpy.sqrt(numpy.clip(1 - t**2, a_min=0, a_max=None))
+
+    # Summation approximation
+    U = numpy.vstack([eval_chebyu(k, t) for k in range(len(psi))]).T
+    rho_t = w * (U @ psi)
+
+    # Adjust for dt to dx transformation
+    rho_x = rho_t * (2.0 / (lam_p - lam_m))
+
+    return rho_x
+
+
+# ===================
+# chebushev stieltjes
+# ===================
+
+def chebyshev_stieltjes(z, psi, support):
+    """
+    Compute the Stieltjes transform m(z) for a Chebyshev‐II expansion
+
+    rho(x) = (2/(lam_p - lam_m)) * sqrt(1−t(x)^2) * sum_{k=0}^K psi_k U_k(t(x))
+
+    via the closed‐form
+
+      \\int_{-1}^1 U_k(t) sqrt(1−t^2)/(u - t) dt = \\pi J(u)^(k+1),
+
+    where
+
+      u = (2(z−center))/span,
+      center = (lam_p + lam_m)/2,
+      span = lam_p - lam_m,
+      J(u) = u − sqrt(u^2−1)
+
+    and then
+
+      m(z) = - (2/ span) * \\sum{k=0}^K \\psi_k * [ \\pi J(u)^(k+1) ].
+
+    Parameters
+    ----------
+
+    z : complex or array_like of complex
+        Points in the complex plane.
+
+    psi : array_like, shape (K+1,)
+        Chebyshev‐II coefficients \\psi.
+
+    support : tuple
+        The support interval of the original density.
+
+    Returns
+    -------
+
+    m_z : ndarray of complex
+        The Stieltjes transform m(z) on the same shape as z.
+    """
+
+    z = numpy.asarray(z, dtype=numpy.complex128)
+    lam_m, lam_p = support
+    span = lam_p - lam_m
+    center = 0.5 * (lam_m + lam_p)
+
+    # map z -> u in the standard [-1,1] domain
+    u = (2.0 * (z - center)) / span
+
+    # inverse-Joukowski: pick branch sqrt with +Im
+    root = numpy.sqrt(u*u - 1)
+    Jm = u - root
+    Jp = u + root
+
+    # Make sure J is Herglotz
+    J = numpy.zeros_like(Jp)
+    J = numpy.where(Jp.imag > 0, Jm, Jp)
+
+    # build powers J^(k+1) for k=0..K
+    K = len(psi) - 1
+    # shape: (..., K+1)
+    Jpow = J[..., None] ** numpy.arange(1, K+2)
+
+    # sum psi_k * J^(k+1)
+    S = numpy.sum(psi * Jpow, axis=-1)
+
+    # assemble m(z)
+    m_z = - (2.0 / span) * numpy.pi * S
+
+    return m_z

freealg-0.0.1/freealg/_damp.py

@@ -0,0 +1,88 @@
+# 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
+
+__all__ = ['jackson_damping', 'lanczos_damping', 'fejer_damping',
+           'exponential_damping', 'parzen_damping']
+
+
+# ===============
+# jackson damping
+# ===============
+
+def jackson_damping(K):
+    """
+    Compute Jackson damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    g = ((K - k + 1) * numpy.cos(numpy.pi * k / (K + 1)) +
+         numpy.sin(numpy.pi * k / (K + 1)) / numpy.tan(numpy.pi / (K + 1))) \
+        / (K + 1)
+
+    return g
+
+
+# ===============
+# lanczos damping
+# ===============
+
+def lanczos_damping(K):
+    """
+    Compute Lanczos damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    sigma = numpy.sinc(k / K)
+
+    return sigma
+
+
+# =============
+# fejer damping
+# =============
+
+def fejer_damping(K):
+    """
+    Compute Fejer damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return 1 - k / K
+
+
+# ===================
+# exponential damping
+# ===================
+
+def exponential_damping(K, alpha=6):
+    """
+    Compute exponential damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return numpy.exp(-alpha * (k / K)**2)
+
+
+# ==============
+# parzen damping
+# ==============
+
+def parzen_damping(K):
+    """
+    Compute Parzen damping coefficients for orders k = 0, 1, ..., K-1.
+    """
+
+    k = numpy.arange(K)
+    return 1 - numpy.abs((k - K/2) / (K/2))**3