Metadata-Version: 2.1
Name: thewalrus
Version: 0.17.0
Summary: Open source library for hafnian calculation
Home-page: https://github.com/XanaduAI/thewalrus
Maintainer: Xanadu Inc.
Maintainer-email: nicolas@xanadu.ai
License: Apache License 2.0
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Physics
Provides: thewalrus
License-File: LICENSE
Requires-Dist: dask[delayed]
Requires-Dist: numba (<0.54,>=0.49.1)
Requires-Dist: scipy (>=1.2.1)
Requires-Dist: sympy (>=1.5.1)

The Walrus
##########

.. image:: https://github.com/XanaduAI/thewalrus/actions/workflows/tests.yml/badge.svg
    :alt: Tests
    :target: https://github.com/XanaduAI/thewalrus/actions/workflows/tests.yml

.. image:: https://github.com/XanaduAI/thewalrus/actions/workflows/build.yml/badge.svg
    :alt: Build
    :target: https://github.com/XanaduAI/thewalrus/actions/workflows/build.yml

.. image:: https://img.shields.io/codecov/c/github/xanaduai/thewalrus/master.svg?style=flat
    :alt: Codecov coverage
    :target: https://codecov.io/gh/XanaduAI/thewalrus

.. image:: https://img.shields.io/codacy/grade/df94d22534cf4c05b1bddcf697011a82.svg?style=flat
    :alt: Codacy grade
    :target: https://app.codacy.com/app/XanaduAI/thewalrus?utm_source=github.com&utm_medium=referral&utm_content=XanaduAI/thewalrus&utm_campaign=badger

.. image:: https://img.shields.io/readthedocs/the-walrus.svg?style=flat
    :alt: Read the Docs
    :target: https://the-walrus.readthedocs.io

.. image:: https://img.shields.io/pypi/pyversions/thewalrus.svg?style=flat
    :alt: PyPI - Python Version
    :target: https://pypi.org/project/thewalrus

.. image:: https://joss.theoj.org/papers/10.21105/joss.01705/status.svg
    :alt: JOSS - The Journal of Open Source Software
    :target: https://doi.org/10.21105/joss.01705

A library for the calculation of hafnians, Hermite polynomials and Gaussian boson sampling. For more information, please see the `documentation <https://the-walrus.readthedocs.io>`_.

Features
========

* Fast calculation of hafnians, loop hafnians, and torontonians of general and certain structured matrices.

* An easy to use interface to use the loop hafnian for Gaussian quantum state calculations.

* Sampling algorithms for hafnian and torontonians of graphs.

* Efficient classical methods for approximating the hafnian of non-negative matrices.

* Easy to use implementations of the multidimensional Hermite polynomials, which can also be used to calculate hafnians of all reductions of a given matrix.


Installation
============

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

+------------+-------------+------------------+---------------+
|            | macOS 10.6+ | manylinux x86_64 | Windows 64bit |
+============+=============+==================+===============+
| Python 3.7 |      X      |        X         |       X       |
+------------+-------------+------------------+---------------+
| Python 3.8 |      X      |        X         |       X       |
+------------+-------------+------------------+---------------+
| Python 3.9 |      X      |        X         |       X       |
+------------+-------------+------------------+---------------+

To install, simply run

.. code-block:: bash

    pip install thewalrus


Compiling from source
=====================

The Walrus depends on the following Python packages:

* `Python <http://python.org/>`_ >= 3.7
* `NumPy <http://numpy.org/>`_  >= 1.13.3
* `Numba <https://numba.pydata.org/>`_ >= 0.43.1

In addition, to compile the C++ extension, the following dependencies are required:

* A C++11 compiler, such as ``g++`` >= 4.8.1, ``clang`` >= 3.3, ``MSVC`` >= 14.0/2015
* `Cython <https://cython.org/>`_ an optimising static compiler for the Python programming language.

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

.. code-block:: console

    $ sudo apt install g++
    $ pip install Cython

or using Homebrew on MacOS:

.. code-block:: console

    $ brew install gcc
    $ pip install Cython

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

.. code-block:: console

    $ git clone https://github.com/XanaduAI/thewalrus.git
    $ cd thewalrus && python -m pip install -e .


OpenMP
------

``libwalrus`` uses OpenMP to parallelize both the permanent and the hafnian calculation. **At the moment, this is only supported on Linux/MacOS using the GNU g++ compiler/Clang.**



Software tests
==============

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

.. code-block:: console

    $ make test

To run the low-level C++ test suite, `Googletest <https://github.com/google/googletest>`_
will need to be installed. In Ubuntu-based distributions, this can be done as follows:

.. code-block:: console

    sudo apt-get install cmake libgtest-dev

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

.. code-block:: console

    sudo apt install cmake
    wget -qO - https://github.com/google/googletest/archive/release-1.8.1.tar.gz | 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.

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

The Walrus documentation is available online on `Read the Docs <https://the-walrus.readthedocs.io>`_.

To build it locally, you need to have the following packages installed:

* `Sphinx <http://sphinx-doc.org/>`_ >= 1.5
* `sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/>`_ >= 0.3.6
* `nbsphinx <https://github.com/spatialaudio/nbsphinx>`_
* `Pandoc <https://pandoc.org/>`_
* `breathe <https://breathe.readthedocs.io/en/latest/>`_ >= 4.12.0
* `exhale <https://exhale.readthedocs.io/en/latest/>`_
* `Doxygen <http://www.doxygen.nl/>`_

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

.. code-block:: console

    $ make doc

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

Contributing to The Walrus
==========================

We welcome contributions - simply fork The Walrus repository, and then make a pull request containing your contribution. All contributors to The Walrus will be listed as authors on the releases.

We also encourage bug reports, suggestions for new features and enhancements, and even links to projects, applications or scientific publications that use The Walrus.

Authors
=======

The Walrus is the work of `many contributors <https://github.com/XanaduAI/thewalrus/blob/master/.github/ACKNOWLEDGMENTS.md>`_.

If you are doing research using The Walrus, please cite `our paper <https://joss.theoj.org/papers/10.21105/joss.01705>`_:

 Brajesh Gupt, Josh Izaac and Nicolas Quesada. The Walrus: a library for the calculation of hafnians, Hermite polynomials and Gaussian boson sampling. Journal of Open Source Software, 4(44), 1705 (2019)


Support
=======

- **Source Code:** https://github.com/XanaduAI/thewalrus
- **Issue Tracker:** https://github.com/XanaduAI/thewalrus/issues

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


License
=======

The Walrus is **free** and **open source**, released under the Apache License, Version 2.0.


