[feature] Adding support for QuEST and Qulacs statevector simulators (#68)

* Added Qulacs simulator

* Added wrapper for QuEST

* Updated readme with simulator installation instructions

* Adding tests for HybridEngine on statevector simulators

* Supporting new statevector sims on HybridEngine

* Fixed a bug in CuStateVec relating to HybridEngine

Author: PabloAndresCQ

README.md

@@ -97,7 +97,8 @@ pytest tests
 
 Certain simulators from `pecos.simulators` require external packages that are not installed by `pip install .[all]`.
 
-- `CuStateVec` requires a Linux machine with an NVIDIA GPU (see requirements [here](https://docs.nvidia.com/cuda/cuquantum/latest/getting_started/getting_started.html#dependencies-custatevec-label)). PECOS' dependencies are specified in the `[cuda]` section of `pyproject.toml` and can be installed via `pip install .[cuda]`. If installation is not successful, see alternative instructions [here](https://docs.nvidia.com/cuda/cuquantum/latest/getting_started/getting_started.html#installing-cuquantum).
+- `QuEST` is installed along with the python package `pyquest` when calling `pip install .[all]`. However, it uses 64-bit float point precision by default, and if you wish to make use of 32-bit float point precision you will need to follow the installation instructions provided by the developers [here](https://github.com/rrmeister/pyQuEST/tree/develop).
+- `CuStateVec` requires a Linux machine with an NVIDIA GPU (see requirements [here](https://docs.nvidia.com/cuda/cuquantum/latest/getting_started/getting_started.html#dependencies-custatevec-label)). PECOS' dependencies are specified in the `[cuda]` section of `pyproject.toml`, however, installation via `pip` is not reliable. The recommended method of installation is via `conda`, as discussed [here](https://docs.nvidia.com/cuda/cuquantum/latest/getting_started/getting_started.html#installing-cuquantum). Note that there might be conflicts between `conda` and `venv`; if you intend to use `CuStateVec`, you may follow the installation instructions for PECOS within a `conda` environment without involving the `venv` commands.
 
 ## Uninstall
 

pyproject.toml

@@ -57,6 +57,8 @@ simulators = [
     "cython",
     "pybind11>=2.2.3,<3.0",
     "projectq>=0.5.0,<0.9.0",
+    "qulacs>=0.6.4",
+    "pyquest>=0.0.1",
 ]
 cuda = [
     "cuquantum-python>=24.03.0",

python/pecos/simulators/__init__.py

@@ -32,6 +32,18 @@
 except ImportError:
     pass
 
+# Attempt to import optional Qulacs package
+try:  # noqa: SIM105
+    from pecos.simulators.qulacs.state import Qulacs  # wrapper for Qulacs sim
+except ImportError:
+    pass
+
+# Attempt to import optional QuEST package
+try:  # noqa: SIM105
+    from pecos.simulators.quest.state import QuEST  # wrapper for QuEST sim
+except ImportError:
+    pass
+
 # Attempt to import optional cuquantum and cupy packages
 try:
     import cupy

python/pecos/simulators/basic_sv/state.py

@@ -11,6 +11,7 @@
 
 
 import numpy as np
+from numpy.typing import ArrayLike
 
 from pecos.simulators.basic_sv import bindings
 from pecos.simulators.sim_class_types import StateVector
@@ -109,5 +110,5 @@ def reset(self):
         return self
 
     @property
-    def vector(self) -> np.ndarray:
+    def vector(self) -> ArrayLike:
         return np.reshape(self.internal_vector, newshape=2**self.num_qubits)

python/pecos/simulators/custatevec/bindings.py

@@ -19,15 +19,17 @@
 
 gate_dict = {
     "Init": init_zero,
+    "Init +Z": init_zero,
+    "Init -Z": init_one,
     "init |0>": init_zero,
     "init |1>": init_one,
-    "Measure": meas_z,
-    "measure Z": meas_z,
     "leak": init_zero,
     "leak |0>": init_zero,
     "leak |1>": init_one,
     "unleak |0>": init_zero,
     "unleak |1>": init_one,
+    "Measure": meas_z,
+    "measure Z": meas_z,
     "I": one_q.identity,
     "X": one_q.X,
     "Y": one_q.Y,

python/pecos/simulators/custatevec/state.py

@@ -12,9 +12,9 @@
 import random
 
 import cupy as cp
-import numpy as np
 from cuquantum import ComputeType, cudaDataType
 from cuquantum import custatevec as cusv
+from numpy.typing import ArrayLike
 
 from pecos.simulators.custatevec import bindings
 from pecos.simulators.sim_class_types import StateVector
@@ -53,8 +53,7 @@ def __init__(self, num_qubits, seed=None) -> None:
         self.compute_type = ComputeType.COMPUTE_64F
 
         # Allocate the statevector in GPU and initialize it to |0>
-        self.cupy_vector = cp.zeros(shape=2**num_qubits, dtype=self.cp_type)
-        self.cupy_vector[0] = 1
+        self.reset()
 
         ####################################################
         # Set up cuStateVec library and GPU memory handles #
@@ -101,8 +100,8 @@ def free(ptr, size, stream):
     def reset(self):
         """Reset the quantum state for another run without reinitializing."""
         # Initialize all qubits in the zero state
-        self.vector = cp.zeros(shape=2**self.num_qubits, dtype=self.cp_type)
-        self.vector[0] = 1
+        self.cupy_vector = cp.zeros(shape=2**self.num_qubits, dtype=self.cp_type)
+        self.cupy_vector[0] = 1
         return self
 
     def __del__(self) -> None:
@@ -111,5 +110,5 @@ def __del__(self) -> None:
         cusv.destroy(self.libhandle)
 
     @property
-    def vector(self) -> np.ndarray:
+    def vector(self) -> ArrayLike:
         return self.cupy_vector.get()

python/pecos/simulators/parent_sim_classes.py

@@ -37,6 +37,9 @@ def run_gate(self, symbol: str, locations: set[int] | set[tuple[int, ...]], **pa
             for location in locations:
                 if params.get("angles") and len(params["angles"]) == 1:
                     params.update({"angle": params["angles"][0]})
+                elif "angle" in params and "angles" not in params:
+                    params["angles"] = (params["angle"],)
+
                 results = self.bindings[symbol](self, location, **params)
 
                 # TODO: get params var value ... -> result = {'sym':, 'index':, 'result': result, 'qubit': location}

python/pecos/simulators/quantum_simulator.py

@@ -18,6 +18,21 @@
 except ImportError:
     ProjectQSim = None
 
+try:
+    from pecos.simulators import Qulacs
+except ImportError:
+    Qulacs = None
+
+try:
+    from pecos.simulators import QuEST
+except ImportError:
+    QuEST = None
+
+try:
+    from pecos.simulators import CuStateVec
+except ImportError:
+    CuStateVec = None
+
 from pecos.reps.pypmir.op_types import QOp
 
 
@@ -38,7 +53,15 @@ def init(self, num_qubits: int):
             if self.backend == "stabilizer":
                 self.state = SparseSim
             elif self.backend == "state-vector":
+                self.state = Qulacs  # Seems to be the better default choice for now
+            elif self.backend == "ProjectQSim":
                 self.state = ProjectQSim
+            elif self.backend == "Qulacs":
+                self.state = Qulacs
+            elif self.backend == "QuEST":
+                self.state = QuEST
+            elif self.backend == "CuStateVec":
+                self.state = CuStateVec
             else:
                 msg = f"simulator `{self.state}` not currently implemented!"
                 raise NotImplementedError(msg)

python/pecos/simulators/quest/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2024 The PECOS Developers
+#
+# 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
+#
+#     https://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.
+
+from pecos.simulators.quest import bindings
+from pecos.simulators.quest.state import QuEST

python/pecos/simulators/quest/bindings.py

@@ -0,0 +1,74 @@
+# Copyright 2024 The PECOS Developers
+#
+# 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
+#
+#     https://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.
+
+import pecos.simulators.quest.gates_one_qubit as one_q
+import pecos.simulators.quest.gates_two_qubit as two_q
+from pecos.simulators.quest.gates_init import init_one, init_zero
+from pecos.simulators.quest.gates_meas import meas_z
+
+# Supporting gates from table:
+#   https://github.com/CQCL/phir/blob/main/spec.md#table-ii---quantum-operations
+
+gate_dict = {
+    "Init": init_zero,
+    "Init +Z": init_zero,
+    "Init -Z": init_one,
+    "init |0>": init_zero,
+    "init |1>": init_one,
+    "leak": init_zero,
+    "leak |0>": init_zero,
+    "leak |1>": init_one,
+    "unleak |0>": init_zero,
+    "unleak |1>": init_one,
+    "Measure": meas_z,
+    "measure Z": meas_z,
+    "I": one_q.identity,
+    "X": one_q.X,
+    "Y": one_q.Y,
+    "Z": one_q.Z,
+    "RX": one_q.RX,
+    "RY": one_q.RY,
+    "RZ": one_q.RZ,
+    "R1XY": one_q.R1XY,
+    "RXY1Q": one_q.R1XY,
+    "SX": one_q.SX,
+    "SXdg": one_q.SXdg,
+    "SqrtX": one_q.SX,
+    "SqrtXd": one_q.SXdg,
+    "SY": one_q.SY,
+    "SYdg": one_q.SYdg,
+    "SqrtY": one_q.SY,
+    "SqrtYd": one_q.SYdg,
+    "SZ": one_q.SZ,
+    "SZdg": one_q.SZdg,
+    "SqrtZ": one_q.SZ,
+    "SqrtZd": one_q.SZdg,
+    "H": one_q.H,
+    "F": one_q.F,
+    "Fdg": one_q.Fdg,
+    "T": one_q.T,
+    "Tdg": one_q.Tdg,
+    "CX": two_q.CX,
+    "CY": two_q.CY,
+    "CZ": two_q.CZ,
+    "RXX": two_q.RXX,
+    "RYY": two_q.RYY,
+    "RZZ": two_q.RZZ,
+    "R2XXYYZZ": two_q.R2XXYYZZ,
+    "SXX": two_q.SXX,
+    "SXXdg": two_q.SXXdg,
+    "SYY": two_q.SYY,
+    "SYYdg": two_q.SYYdg,
+    "SZZ": two_q.SZZ,
+    "SqrtZZ": two_q.SZZ,
+    "SZZdg": two_q.SZZdg,
+    "SWAP": two_q.SWAP,
+}

python/pecos/simulators/quest/gates_init.py

@@ -0,0 +1,40 @@
+# Copyright 2024 The PECOS Developers
+#
+# 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
+#
+#     https://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.
+
+from typing import Any
+
+from pecos.simulators.quest.gates_meas import meas_z
+from pecos.simulators.quest.gates_one_qubit import X
+
+
+def init_zero(state, qubit: int, **params: Any) -> None:
+    """Initialise or reset the qubit to state |0>
+
+    Args:
+        state: An instance of QuEST
+        qubit: The index of the qubit to be initialised
+    """
+    result = meas_z(state, qubit)
+
+    if result:
+        X(state, qubit)
+
+
+def init_one(state, qubit: int, **params: Any) -> None:
+    """Initialise or reset the qubit to state |1>
+    Args:
+        state: An instance of QuEST
+        qubit: The index of the qubit to be initialised
+    """
+    result = meas_z(state, qubit)
+
+    if not result:
+        X(state, qubit)

python/pecos/simulators/quest/gates_meas.py

@@ -0,0 +1,32 @@
+# Copyright 2024 The PECOS Developers
+#
+# 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
+#
+#     https://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.
+
+from typing import Any
+
+from pyquest.gates import M
+
+
+def meas_z(state, qubit: int, **params: Any) -> int:
+    """Measure in the Z-basis, collapse and normalise.
+
+    Notes:
+        The number of qubits in the state remains the same.
+
+    Args:
+        state: An instance of QuEST
+        qubit: The index of the qubit to be measured
+
+    Returns:
+        The outcome of the measurement, either 0 or 1.
+    """
+    # QuEST uses qubit index 0 as the least significant bit
+    idx = state.num_qubits - qubit - 1
+    return state.quest_state.apply_operator(M(idx))[0]