Metadata-Version: 2.4
Name: freealg
Version: 0.1.13
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
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
Provides-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 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
=======

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

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

For more details on how to interface with *freealg* check out the `Quick Start Guide <https://github.com/ameli/freealg/blob/main/notebooks/quick_start.ipynb>`__.


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

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

  .. code::

      @article{ameli2025spectral,
        title={Spectral Estimation with Free Decompression},
        author={Siavash Ameli and Chris van der Heide and Liam Hodgkinson and Michael W. Mahoney},
        journal={arXiv preprint arXiv:2506.11994},
        year={2025}
      }


License
=======

|license|

.. |license| image:: https://img.shields.io/github/license/ameli/freealg
   :target: https://opensource.org/licenses/BSD-3-Clause
