Photonics

thewalrus

Maintained by xanaduAI

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

PythonApache-2.0

View on GitHub Open project siteCompare

Resource snapshot

What you can build or learn

Understand how photonic circuits, modes, and optical programs are represented.
Compare photonic workflows with more familiar circuit-model SDKs.
Learn which parts of the photonics ecosystem are most approachable.

Code samples

Examples from the repository.

Timing Complex (examples/timing_complex.py)

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#     http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This module performs benchmarking on the Python interface lhaf"""
import time
import numpy as np
from thewalrus import haf_complex
header = ["Size", "Time(complex128)", "Result(complex128)"]
print("{: >5} {: >15} {: >25} ".format(*header))
for n in range(2, 23):
    mat2 = np.ones([2 * n, 2 * n], dtype=np.complex128)
    init2 = time.clock()
    x2 = np.real(haf_complex(mat2))
    end2 = time.clock()
    row = [2 * n, end2 - init2, x2]
    print("{: >5} {: >15} {: >25}".format(*row))

Timing Int Vs Real (examples/timing_int_vs_real.py)

#!/usr/bin/env python3
import time
from math import factorial
import numpy as np
from scipy import diagonal, randn
from scipy.linalg import qr
import matplotlib.pyplot as plt
from thewalrus.libwalrus import haf_int, haf_real, haf_complex
a0 = 100.0
anm1 = 2.0
n = 20
r = (anm1 / a0) ** (1.0 / (n - 1))
nreps = [(int)(a0 * (r ** ((i)))) for i in range(n)]
times = np.empty([n, 5])
for ind, reps in enumerate(nreps):
    size = 2 * (ind + 1)
    print("\nTesting matrix size {}, with {} reps...".format(size, reps))
    start = time.time()
    for i in range(reps):
        matrix = np.random.randint(low=-1, high=2, size=[size, size])
        A = np.complex128(np.clip(matrix + matrix.T, -1, 1))
        res = haf_complex(A)
    end = time.time()
    print("Mean time taken (complex): ", (end - start) / reps)
    # print('\t Haf result: ', res)
    times[ind, 0] = (end - start) / reps
    start = time.time()
    for i in range(reps):
        matrix = np.random.randint(low=-1, high=2, size=[size, size])
        A = np.complex128(np.clip(matrix + matrix.T, -1, 1))
        res = haf_complex(A, recursive=True)
    end = time.time()
    print("Mean time taken (complex, recursive): ", (end - start) / reps)
    # print('\t Haf result: ', res)
    times[ind, 1] = (end - start) / reps
    start = time.time()
    for i in range(reps):
        matrix = np.random.randint(low=-1, high=2, size=[size, size])
        A = np.float64(np.clip(matrix + matrix.T, -1, 1))
        res = haf_real(A)

Timing Real (examples/timing_real.py)

# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#     http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This module performs benchmarking on the Python interface rlhaf"""
import time
import numpy as np
from thewalrus import haf_real
header = ["Size", "Time(complex128)", "Result(complex128)"]
print("{: >5} {: >15} {: >25} ".format(*header))
for n in range(2, 23):
    mat2 = np.ones([2 * n, 2 * n], dtype=np.float64)
    init2 = time.clock()
    x2 = np.real(haf_real(mat2))
    end2 = time.clock()
    row = [2 * n, end2 - init2, x2]
    print("{: >5} {: >15} {: >25}".format(*row))

License

Apache-2.0

SPDX identifier detected from the repository metadata or license files.

Repository README

Preview from the project README.

Rendered as Markdown inside a scrollable preview. Long READMEs stay contained; expand or open on GitHub for the full document.

~555 words · about 3 min readOpen on GitHub

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

:alt: Codecov coverage
:target: https://codecov.io/gh/XanaduAI/thewalrus

:alt: CodeFactor Grade
:target: https://www.codefactor.io/repository/github/xanaduai/thewalrus

:alt: Read the Docs
:target: https://the-walrus.readthedocs.io

: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

The Walrus requires Python version 3.10, 3.11, or 3.12. Installation of The Walrus, as well as all dependencies, can be done using pip:

.. code-block:: bash

pip install thewalrus

Compiling from source

The Walrus has the following dependencies:

Python <http://python.org/>_ >= 3.10
NumPy <http://numpy.org/>_ >= 2.2.5
Numba <https://numba.pydata.org/>_ >= 0.61.2
SciPy <https://scipy.org/>_ >=1.15.3
SymPy <https://www.sympy.org/>_ >=1.14.0
Dask[delayed] <https://docs.dask.org/>_ >=2025.4.1

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 .

Software tests

To ensure that The Walrus library is working correctly after installation, the test suite can be run locally using pytest.

Additional packages are required to run the tests. These dependencies can be found in requirements-dev.txt and can be installed using pip:

.. code-block:: console

$ pip install -r requirements-dev.txt

To run the tests, navigate to the source code folder and run the command

.. code-block:: console

$ make test

Documentation

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

Additional packages are required to build the documentation locally as specified in doc/requirements.txt. These packages can be installed using:

.. code-block:: console

$ sudo apt install pandoc
$ pip install -r docs/requirements.txt

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)