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