Metadata-Version: 2.4
Name: freealg
Version: 0.5.0
Summary: Free probability for large matrices
Home-page: https://github.com/ameli/freealg
Download-URL: https://github.com/ameli/freealg/archive/main.zip
Project-URL: Documentation, https://ameli.github.io/freealg
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
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
License-File: AUTHORS.txt
Requires-Dist: numpy
Requires-Dist: scipy
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"
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"
Requires-Dist: sphinx-sitemap; 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
Dynamic: summary

.. figure:: https://raw.githubusercontent.com/ameli/freealg/refs/heads/main/docs/source/_static/images/icons/logo-freealg-light.png
    :align: left
    :width: 240

`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>`__ |
`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>`__ |

*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
=======

|pypi|

Install with ``pip``:

.. code-block::

    pip install freealg

Alternatively, clone the source code and install with

.. code-block::

    cd source_dir
    pip install .

Documentation
=============

|deploy-docs|

Documentation is available at `ameli.github.io/freealg <https://ameli.github.io/freealg>`__.

Quick Usage
===========

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.eigvalsh(A, 100_000)              # Estimate the eigenvalues of 100000 x 100000

For more details on how to interface with *freealg* check out the 
`Live Demo <https://colab.research.google.com/github/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__.


Test
====

|build-linux| 

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 <https://github.com/ameli/freealg/blob/main/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
===========

If you use this work, please cite our `arXiv paper <https://arxiv.org/abs/2506.11994>`__.

  .. code::

      @article{spectral2025,
          title={Spectral Estimation with Free Decompression},
          author={Siavash Ameli and Chris van der Heide and Liam Hodgkinson and Michael W. Mahoney},
          year={2025},
          eprint={2506.11994},
          archivePrefix={arXiv},
          primaryClass={stat.ML},
          url={https://arxiv.org/abs/2506.11994},
          journal={arXiv preprint arXiv:2506.11994},
      }


License
=======

|license|

.. |build-linux| image:: https://img.shields.io/github/actions/workflow/status/ameli/freealg/build-linux.yml
   :target: https://github.com/ameli/freealg/actions?query=workflow%3Abuild-linux 
.. |deploy-docs| image:: https://img.shields.io/github/actions/workflow/status/ameli/freealg/deploy-docs.yml?label=docs
   :target: https://github.com/ameli/freealg/actions?query=workflow%3Adeploy-docs
.. |pypi| image:: https://img.shields.io/pypi/v/freealg
   :target: https://pypi.org/project/freealg/
.. |license| image:: https://img.shields.io/github/license/ameli/freealg
   :target: https://opensource.org/licenses/BSD-3-Clause
