freealg 0.3.1

Free probability for large matrices

Paper | Slides | Docs | Live Demo

freealg is a Python package that employs free probability to evaluate the spectral densities of large matrix forms. 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:

pip install freealg

Alternatively, clone the source code and install with

cd source_dir
pip install .

Documentation

Documentation is available at ameli.github.io/freealg.

Quick Usage

The following code estimates the eigenvalues of a very large Wishart matrix using a much smaller Wishart matrix.

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

Test

You may test the package with tox:

cd source_dir
tox

Alternatively, test with pytest:

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.

@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