Skip to main content

Open source library for hafnian calculation

Project description

CircleCI Appveyor Codecov coverage Codacy grade Read the Docs PyPI - Python Version

The fastest exact hafnian library. For more information, please see the documentation.


  • The fastest calculation of the hafnians, loop hafnians, and torontonians of general and certain structured matrices.
  • An easy to use interface to use the loop hafnian for quantum state calculations
  • State of the art algorithms to sample from hafnian and torontonians of graphs.
  • Efficient classical methods for approximating the hafnian of non-negative matrices.


Pre-built binary wheels are available for the following platforms:

  macOS 10.6+ manylinux x86_64 Windows 64bit
Python 3.5
Python 3.6
Python 3.7

To install, simply run

pip install hafnian

Compiling from source

Hafnian depends on the following Python packages:

In addition, to compile the included Fortran and C++ extensions, the following dependencies are required:

  • A Fortran compiler, such as gfortran
  • A C++11 compiler, such as g++ >= 4.8.1, clang >= 3.3, MSVC >= 14.0/2015
  • Eigen3 - a C++ header library for linear algebra.

On Debian-based systems, these can be installed via apt and curl:

$ sudo apt install g++ gfortran libeigen3-dev

or using Homebrew on MacOS:

$ brew install gcc eigen

Alternatively, you can download the Eigen headers manually:

$ mkdir ~/.local/eigen3 && cd ~/.local/eigen3
$ wget -O eigen3.tar.gz
$ tar xzf eigen3.tar.gz eigen-eigen-323c052e1731/Eigen --strip-components 1
$ export EIGEN_INCLUDE_DIR=$HOME/.local/eigen3

Note that we export the environment variable EIGEN_INCLUDE_DIR so that Hafnian can find the Eigen3 header files (if not provided, Hafnian will by default look in /use/include/eigen3 and /usr/local/include/eigen3).

Once all dependencies are installed, you can compile the latest stable version of the Hafnian library as follows:

$ python -m pip install hafnian --no-binary :all:

Alternatively, you can compile the latest development version by cloning the git repository, and installing using pip in development mode.

$ git clone
$ cd hafnian && python -m pip install -e .


The Hafnian library uses OpenMP to parallelize both the permanent and the hafnian calculation. At the moment, this is only supported on Linux using the GNU g++ compiler, due to insufficient support using Windows/MSCV and MacOS/Clang.

Using LAPACK, OpenBLAS, or MKL

If you would like to take advantage of the highly optimized matrix routines of LAPACK, OpenBLAS, or MKL, you can optionally compile the Hafnian library such that Eigen uses these frameworks as backends. As a result, all calls in the Hafnian library to Eigen functions are silently substituted with calls to LAPACK/OpenBLAS/MKL.

For example, for LAPACK integration, make sure you have the lapacke C++ LAPACK bindings installed (sudo apt install liblapacke-dev in Ubuntu-based Linux distributions), and then compile with the environment variable USE_LAPACK=1:

$ USE_LAPACK=1 python -m pip install hafnian --no-binary :all:

Alternatively, you may pass USE_OPENBLAS=1 to use the OpenBLAS library.

Software tests

To ensure that the Hafnian library is working correctly after installation, the test suite can be run by navigating to the source code folder and running

$ make test

To run the low-level C++ test suite, Googletest will need to be installed. In Ubuntu-based distributions, this can be done as follows:

sudo apt-get install cmake libgtest-dev
cd /usr/src/googletest/googletest
sudo cmake
sudo make
sudo cp libgtest* /usr/lib/
sudo mkdir /usr/local/lib/googletest
sudo ln -s /usr/lib/libgtest.a /usr/local/lib/googletest/libgtest.a
sudo ln -s /usr/lib/libgtest_main.a /usr/local/lib/googletest/libgtest_main.a

Alternatively, the latest Googletest release can be installed from source:

sudo apt install cmake
wget -qO - | tar -xz
cmake -D CMAKE_INSTALL_PREFIX:PATH=$HOME/googletest -D CMAKE_BUILD_TYPE=Release googletest-release-1.8.1
make install

If installing Googletest from source, make sure that the included headers and libraries are available on your include/library paths.


The Hafnian+ documentation is currently not hosted online. To build it locally, you need to have the following packages installed:

They can be installed via a combination of pip and apt if on a Debian-based system:

$ sudo apt install pandoc doxygen
$ pip3 install sphinx sphinxcontrib-bibtex nbsphinx breathe exhale

To build the HTML documentation, go to the top-level directory and run the command

$ make doc

The documentation can then be found in the docs/_build/html/ directory.


Nicolás Quesada, Brajesh Gupt, and Josh Izaac.

All contributions are acknowledged in the acknowledgments page.

If you are doing research using Hafnian, please cite our paper:

Andreas Björklund, Brajesh Gupt, and Nicolás Quesada. A faster hafnian formula for complex matrices and its benchmarking on the Titan supercomputer arXiv, 2018. arxiv:1805.12498


If you are having issues, please let us know by posting the issue on our Github issue tracker.


Hafnian is free and open source, released under the Apache License, Version 2.0.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hafnian-0.6.1.tar.gz (261.4 kB view hashes)

Uploaded source

Built Distributions

hafnian-0.6.1-cp37-cp37m-win_amd64.whl (477.0 kB view hashes)

Uploaded cp37

hafnian-0.6.1-cp36-cp36m-win_amd64.whl (477.1 kB view hashes)

Uploaded cp36

hafnian-0.6.1-cp35-cp35m-win_amd64.whl (476.7 kB view hashes)

Uploaded cp35

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page