XanaduAI · thisac · Dec 16, 2021 · Dec 15, 2021 · Dec 15, 2021 · Dec 15, 2021
diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md
@@ -6,18 +6,31 @@
 
 ### Improvements
 
-* Permanent algorithms are implemented in numba, hence reducing the C++ dependencies of The Walrus. [#300](https://github.com/XanaduAI/thewalrus/pull/300)
+* Permanent algorithms are implemented in Python using Numba just-in-time compilation. [#300](https://github.com/XanaduAI/thewalrus/pull/300)
+
+* Hafnian algorithms are implemented in Python using Numba just-in-time compilation. [#311](https://github.com/XanaduAI/thewalrus/pull/311)
+
+* The Walrus is no longer dependent on C++, and all C++-related code and documentation is removed. Instead, all code has been ported to Python using just-in-time compilation to improve performance. [#311](https://github.com/XanaduAI/thewalrus/pull/311)
+
+* Documentation is updated to include the characteristic polynomials and decompositions modules. [#312](https://github.com/XanaduAI/thewalrus/pull/312)
 
 
 ### Bug fixes
 
+* Makes modules reachable via the global namespace, instead of requiring importing the modules explicitly. [#312](https://github.com/XanaduAI/thewalrus/pull/312)
+
+  ```python
+  import thewalrus as tw
+  tw.samples.generate_torontonian_sample
+  ```
+
 ### Breaking changes
 
 ### Contributors
 
 This release contains contributions from (in alphabetical order):
 
-Benjamin Lanthier, Dominic Leclerc, Nicolas Quesada, Brandon Turcotte, Trevor Vincent, Jiaqi Zhao
+Theodor Isacsson, Benjamin Lanthier, Dominic Leclerc, Nicolas Quesada, Brandon Turcotte, Trevor Vincent, Jiaqi Zhao
 
 ---
 

diff --git a/README.rst b/README.rst
@@ -5,17 +5,13 @@ The Walrus
     :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/codefactor/grade/github/XanaduAI/thewalrus/master?style=flat
+    :alt: CodeFactor Grade
+    :target: https://www.codefactor.io/repository/github/xanaduai/thewalrus
 
 .. image:: https://img.shields.io/readthedocs/the-walrus.svg?style=flat
     :alt: Read the Docs

diff --git a/docs/code.rst b/docs/code.rst
@@ -12,6 +12,10 @@ Python API
 
 * The :mod:`thewalrus.symplectic` submodule provides access to a convenient set of symplectic matrices and utility functions to manipulate them
 
+* The :mod:`thewalrus.decompositions` submodule provides access to common shared matrix decompositions used to perform gate decompositions
+
+* The :mod:`thewalrus.charpoly` submodule provides access to La Budde's algorithm to calculate the characteristic polynomials of matrices
+
 * The :mod:`thewalrus.random` submodule provides access to random unitary, symplectic and covariance matrices
 
 * The :mod:`thewalrus.fock_gradients` submodule provides access to the Fock representation of certain continuous-variable gates and their gradients
@@ -22,4 +26,4 @@ Python API
 Octave
 ------
 
-In addition, two auxiallary Octave functions are provided: :download:`octave/hafnian.m <../octave/hafnian.m>` and :download:`octave/loophafnian.m <../octave/loophafnian.m>`.
+In addition, two Octave functions are provided: :download:`octave/hafnian.m <../octave/hafnian.m>` and :download:`octave/loophafnian.m <../octave/loophafnian.m>`.
diff --git a/docs/code/charpoly.rst b/docs/code/charpoly.rst
@@ -0,0 +1,3 @@
+.. automodule:: thewalrus.charpoly
+	:members:
+	:exclude-members: alpha, beta, hij, mlo,
diff --git a/docs/code/decompositions.rst b/docs/code/decompositions.rst
@@ -0,0 +1,2 @@
+.. automodule:: thewalrus.decompositions
+	:members:
diff --git a/docs/code/fock_gradients.rst b/docs/code/fock_gradients.rst
@@ -1 +1,2 @@
 .. automodule:: thewalrus.fock_gradients
+    :members:
diff --git a/docs/code/reference.rst b/docs/code/reference.rst
@@ -1,2 +1,3 @@
 .. automodule:: thewalrus.reference
-    :members: memoized, partitions, spm, pmp, T
+    :members:
+    :exclude-members: LimitedSizeDict, hafnian
diff --git a/docs/index.rst b/docs/index.rst
@@ -165,6 +165,8 @@ The Walrus library is **free** and **open source**, released under the Apache Li
    code/samples
    code/csamples
    code/symplectic
+   code/charpoly
    code/random
    code/fock_gradients
+   code/decompositions
    code/reference
diff --git a/thewalrus/__init__.py b/thewalrus/__init__.py
@@ -72,8 +72,6 @@
     An algorithm that calculates the hafnian of a sparse matrix by taking advantage of the Laplace expansion and memoization, to store
     only the relevant paths that contribute non-zero values to the final calculation.
 
-
-
 Functions
 ---------
 
@@ -91,15 +89,17 @@
     low_rank_hafnian
 
 Code details
-^^^^^^^^^^^^
+------------
 """
-# pylint: disable=wrong-import-position
-import os
-import platform
-
-import numpy as np
-
 import thewalrus.quantum
+import thewalrus.csamples
+import thewalrus.decompositions
+import thewalrus.fock_gradients
+import thewalrus.charpoly
+import thewalrus.random
+import thewalrus.reference
+import thewalrus.samples
+import thewalrus.symplectic
 
 from ._hafnian import (
     hafnian,
@@ -182,6 +182,9 @@ def about():
         Cython version:            0.29.24
     """
     # pylint: disable=import-outside-toplevel
+    import os
+    import platform
+
     import sys
     import numpy
     import scipy

diff --git a/thewalrus/_hafnian.py b/thewalrus/_hafnian.py
@@ -477,6 +477,9 @@ def _calc_hafnian(A, edge_reps, glynn=True):  # pragma: no cover
 def _haf(A, reps=None, glynn=True):
     r"""Calculate hafnian with (optional) repeated rows and columns.
 
+    Code contributed by `Jake F.F. Bulmer <https://github.com/jakeffbulmer/gbs>`_ based on
+    `arXiv:2108.01622 <https://arxiv.org/abs/2108.01622>`_.
+
     Args:
         A (array): N x N matrix.
         reps (list): Length-N list of repetitions of each row/col (optional). If not provided,
@@ -519,6 +522,9 @@ def _calc_loop_hafnian(A, D, edge_reps, oddloop=None, oddV=None, glynn=True):  #
     """Compute loop hafnian, using inputs as prepared by frontend loop_hafnian function
     compiled with Numba.
 
+    Code contributed by `Jake F.F. Bulmer <https://github.com/jakeffbulmer/gbs>`_ based on
+    `arXiv:2108.01622 <https://arxiv.org/abs/2108.01622>`_.
+
     Args:
         A (array): matrix ordered according to the chosen perfect matching.
         D (array): diagonals ordered according to the chosen perfect matchin
@@ -586,6 +592,9 @@ def _calc_loop_hafnian(A, D, edge_reps, oddloop=None, oddV=None, glynn=True):  #
 def loop_hafnian(A, D=None, reps=None, glynn=True):
     """Calculate loop hafnian with (optional) repeated rows and columns.
 
+    Code contributed by `Jake F.F. Bulmer <https://github.com/jakeffbulmer/gbs>`_ based on
+    `arXiv:2108.01622 <https://arxiv.org/abs/2108.01622>`_.
+
     Args:
         A (array): N x N matrix.
         D (array): Diagonal entries of matrix (optional). If not provided, ``D`` is the diagonal of ``A``.
@@ -594,6 +603,7 @@ def loop_hafnian(A, D=None, reps=None, glynn=True):
             row/column assumed to be repeated once.
         glynn (bool): If ``True``, use Glynn-style finite difference sieve formula, if ``False``,
             use Ryser style inclusion/exclusion principle.
+
     Returns
         complex: result of loop hafnian calculation
     """
@@ -731,6 +741,9 @@ def hafnian(
 ):  # pylint: disable=too-many-arguments
     """Returns the hafnian of a matrix.
 
+    Code contributed by `Jake F.F. Bulmer <https://github.com/jakeffbulmer/gbs>`_ based on
+    `arXiv:2108.01622 <https://arxiv.org/abs/2108.01622>`_.
+
     Args:
         A (array): a square, symmetric array of even dimensions
         loop (bool): If ``True``, the loop hafnian is returned. Default is ``False``.
@@ -747,7 +760,7 @@ def hafnian(
         glynn (bool): whether to use finite difference sieve
 
     Returns:
-        int, float, complex: the hafnian of matrix ``A``
+        int or float or complex: the hafnian of matrix ``A``
     """
     # pylint: disable=too-many-return-statements,too-many-branches
     input_validation(A, rtol=rtol, atol=atol)
@@ -856,6 +869,9 @@ def lhaf(d: frozenset) -> float:
 def hafnian_repeated(A, rpt, mu=None, loop=False, rtol=1e-05, atol=1e-08, glynn=True):
     r"""Returns the hafnian of matrix with repeated rows/columns.
 
+    Code contributed by `Jake F.F. Bulmer <https://github.com/jakeffbulmer/gbs>`_ based on
+    `arXiv:2108.01622 <https://arxiv.org/abs/2108.01622>`_.
+
     The :func:`reduction` function may be used to show the resulting matrix
     with repeated rows and columns as per ``rpt``.
 
@@ -890,7 +906,7 @@ def hafnian_repeated(A, rpt, mu=None, loop=False, rtol=1e-05, atol=1e-08, glynn=
         glynn (bool): whether to use finite difference sieve
 
     Returns:
-        int, float, complex: the hafnian of matrix A
+        int or float or complex: the hafnian of matrix A
     """
     # pylint: disable=too-many-return-statements,too-many-branches
     input_validation(A, atol=atol, rtol=rtol)
@@ -936,7 +952,7 @@ def hafnian_banded(A, loop=False, rtol=1e-05, atol=1e-08):
         A (array): a square, symmetric array of even dimensions
 
     Returns:
-        int, float, complex: the loop hafnian of matrix ``A``
+        int or float or complex: the loop hafnian of matrix ``A``
     """
     input_validation(A, atol=atol, rtol=rtol)
     (n, _) = A.shape

diff --git a/thewalrus/_permanent.py b/thewalrus/_permanent.py
@@ -12,30 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 r"""
-Permanent Algorithms
-=============================
-
-.. currentmodule:: thewalrus._permanent
-
 This submodule provides access to tools for finding the permanent of a matrix. The algorithms implemented
 here was first derived in
+
 * Ryser, Herbert John (1963).
   Combinatorial Mathematics, The Carus Mathematical Monographs, Vol. 14, Mathematical Association of America.
 * Glynn, David G.
-  (2010), "The permanent of a square matrix", European Journal of Combinatorics, 31 (7): 1887–1891.
+  (2010), "The permanent of a square matrix", European Journal of Combinatorics, 31 (7): 1887-1891.
   <doi:10.1016/j.ejc.2010.01.010>`_
-
-Summary
--------
-.. autosummary::
-
-    perm
-    perm_ryser
-    perm_bbfg
-    permanent_repeated
-
-Code details
-------------
 """
 import numpy as np
 from numba import jit
@@ -54,8 +38,9 @@ def perm(A, method="bbfg"):
             or ``"bbfg"`` to use the
             `BBFG formula
             <https://en.wikipedia.org/wiki/Computing_the_permanent#Balasubramanian%E2%80%93Bax%E2%80%93Franklin%E2%80%93Glynn_formula>`_.
+
     Returns:
-        np.float64 or np.complex128: the permanent of matrix A.
+        float or complex: the permanent of matrix ``A``
     """
 
     if not isinstance(A, np.ndarray):
@@ -101,7 +86,7 @@ def perm_ryser(M):  # pragma: no cover
         M (array) : a square array.
 
     Returns:
-        np.float64 or np.complex128: the permanent of matrix M.
+        float or complex: the permanent of matrix ``M``
     """
     n = len(M)
     # row_comb keeps the sum of previous subsets.
@@ -143,7 +128,7 @@ def perm_bbfg(M):  # pragma: no cover
         M (array) : a square array.
 
     Returns:
-        np.float64 or np.complex128: the permanent of a matrix M.
+        float or complex: the permanent of a matrix ``M``
     """
 
     n = len(M)
@@ -186,7 +171,7 @@ def permanent_repeated(A, rpt):
             of A to be repeated.
 
     Returns:
-        np.int64 or np.float64 or np.complex128: the permanent of matrix A.
+        int or float or complex: the permanent of matrix ``A``
     """
     n = A.shape[0]
     O = np.zeros([n, n])
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		.. automodule:: thewalrus.decompositions
		:members:
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		.. automodule:: thewalrus.fock_gradients
		:members: