New backend specialised for Hamming-weight-preserving circuits

doc/source/api-reference/qibo.rst

@@ -2703,6 +2703,70 @@ Alternatively, a Clifford circuit can also be executed starting from the :class:
     :members:
     :member-order: bysource
 
+.. _Hamming-weight:
+
+Simulation of Hamming-weight-preserving circuits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This specialised backend in ``qibo`` supports the fast simulation of
+Hamming-weight-preserving circuits.
+Given a quantum state that only contains non-zero amplitudes associated with computational basis
+states of Hamming weight :math:`k`, the :class:`qibo.backends.hamming_weight.HammingWeightBackend`
+a compressed representation of quantum states that is restricted to the subspace of
+with fixed Hamming weight :math:`k`.
+The dimension of this subspace is :math:`d = \binom{n}{k}`,
+where :math:`n` is the total number of qubits.
+
+As for the other backends, the Hamming-weight backend can be set
+by specifying the engine used for calculation, *i.e.*
+
+.. testcode::  python
+
+    from qibo import set_backend
+
+    set_backend("hamming_weight", platform="numpy")
+
+If not provided, the current global backend is used:
+
+.. testcode::  python
+
+    from qibo import set_backend
+    from qibo.backends import HammingWeightBackend
+
+    # setting numpy as the global backend
+    set_backend("numpy")
+    # the Hamming-weight backend will use the numpy backend as engine
+    backend = HammingWeightBackend()
+
+
+.. autoclass:: qibo.backends.hamming_weight.HammingWeightBackend
+    :members:
+    :member-order: bysource
+
+
+The results of execution of a circuit through this backend creates a
+:class:`qibo.quantum_info.hamming_weight.HammingWeightResult`
+object that gives access to the final state through the
+:meth:`qibo.quantum_info.hamming_weight.HammingWeightResult.state` method.
+The probabilities are computed by the
+:meth:`qibo.quantum_info.hamming_weight.HammingWeightResult.probabilities` method.
+If there are no measurements in the circuit or the number of shots is :math:`0`,
+they are calculated from the statevector.
+Otherwise, they are calculated from the samples.
+The final measured samples and frequencies are accessible, respectively, through the
+:meth:`qibo.quantum_info.hamming_weight.HammingWeightResult.samples` and the
+:meth:`qibo.quantum_info.hamming_weight.HammingWeightResult.frequencies` methods.
+
+It is also possible to recover the standard state representation with the
+:meth:`qibo.quantum_info.hamming_weight.HammingWeightResult.full_state` method.
+Note, however, that this process is inefficient as it involves the construction of
+a statevector with size exponential in the number of qubits.
+
+.. autoclass:: qibo.quantum_info.hamming_weight.HammingWeightResult
+    :members:
+    :member-order: bysource
+
+
 Cloud Backends
 ^^^^^^^^^^^^^^
 

src/qibo/backends/__init__.py

@@ -6,6 +6,7 @@
 
 from qibo.backends.abstract import Backend
 from qibo.backends.clifford import CliffordBackend
+from qibo.backends.hamming_weight import HammingWeightBackend
 from qibo.backends.npmatrices import NumpyMatrices
 from qibo.backends.numpy import NumpyBackend
 from qibo.config import log, raise_error
@@ -32,18 +33,22 @@ def load(backend: str, **kwargs) -> Backend:
             :class:`qibo.backends.abstract.Backend`: Loaded backend.
         """
 
-        if backend not in QIBO_NATIVE_BACKENDS + ("clifford",):
+        if backend not in QIBO_NATIVE_BACKENDS + ("clifford", "hamming_weight"):
             raise_error(
                 ValueError,
                 f"Backend {backend} is not available. "
-                + f"The native qibo backends are {QIBO_NATIVE_BACKENDS + ('clifford',)}",
+                + f"The native qibo backends are {QIBO_NATIVE_BACKENDS + ('clifford', 'hamming_weight')}",
+            )
+
+        if backend in ["clifford", "hamming_weight"]:
+            backend_class = (
+                CliffordBackend if backend == "clifford" else HammingWeightBackend
             )
 
-        if backend == "clifford":
             engine = kwargs.pop("platform", None)
             kwargs["engine"] = engine
 
-            return CliffordBackend(**kwargs)
+            return backend_class(**kwargs)
 
         if backend == "qulacs":
             from qibo.backends.qulacs import QulacsBackend  # pylint: disable=C0415
@@ -287,6 +292,10 @@ def _check_backend(backend):
     return backend
 
 
+def _get_engine_name(backend):
+    return backend.platform if backend.platform is not None else backend.name
+
+
 def list_available_backends(*providers: str) -> dict:
     """Lists all the backends that are available."""
     available_backends = MetaBackend().list_available()
@@ -309,7 +318,7 @@ def construct_backend(backend, **kwargs) -> Backend:  # pylint: disable=R1710
     Returns:
         qibo.backends.abstract.Backend: The loaded backend.
     """
-    if backend in QIBO_NATIVE_BACKENDS + ("clifford",):
+    if backend in QIBO_NATIVE_BACKENDS + ("clifford", "hamming_weight"):
         return MetaBackend.load(backend, **kwargs)
 
     provider = backend.replace("-", "_")

src/qibo/backends/_clifford_operations.py

@@ -493,7 +493,7 @@ def M(state, qubits, nqubits, collapse=False):
     return sample
 
 
-def cast(x, dtype=None, copy=False):
+def cast(x, dtype=None, copy: bool = False):
     if dtype is None:
         dtype = "complex128"
     if isinstance(x, np.ndarray):

src/qibo/backends/abstract.py

@@ -77,12 +77,14 @@ def set_threads(self, nthreads):  # pragma: no cover
         raise_error(NotImplementedError)
 
     @abc.abstractmethod
-    def cast(self, x, copy=False):  # pragma: no cover
-        """Cast an object as the array type of the current backend.
+    def cast(self, x, dtype=None, copy=False):  # pragma: no cover
+        """Cast an object as the array or tensor type of the current backend.
 
         Args:
-            x: Object to cast to array.
-            copy (bool): If ``True`` a copy of the object is created in memory.
+            x: Object to cast to array or tensor.
+            dtype (optional): data type of the array or tensor. If ``None``, defaults
+                to the default data type of the current backend. Defaults to ``None``.
+            copy (bool, optional): If ``True`` a copy of the object is created in memory.
         """
         raise_error(NotImplementedError)
 

src/qibo/backends/clifford.py

@@ -12,10 +12,6 @@
 from qibo.config import raise_error
 
 
-def _get_engine_name(backend):
-    return backend.platform if backend.platform is not None else backend.name
-
-
 class CliffordBackend(NumpyBackend):
     """Backend for the simulation of Clifford circuits following
     `Aaronson & Gottesman (2004) <https://arxiv.org/abs/quant-ph/0406196>`_.
@@ -35,7 +31,10 @@ def __init__(self, engine=None):
             self._stim = stim
         else:
             if engine is None:
-                from qibo.backends import _check_backend  # pylint: disable=C0415
+                from qibo.backends import (  # pylint: disable=C0415
+                    _check_backend,
+                    _get_engine_name,
+                )
 
                 engine = _get_engine_name(_check_backend(engine))
 
@@ -80,6 +79,8 @@ def cast(self, x, dtype=None, copy: bool = False):
 
         Args:
             x: Object to cast to array.
+            dtype (optional): data type of the array or tensor. If ``None``, defaults
+                to the default data type of the current backend. Defaults to ``None``.
             copy (bool, optional): If ``True`` a copy of the object is created in memory.
                 Defaults to ``False``.
         """