Feature more simulators (#21)

* CoinToss simulator implemented.

* Replaced the old CuStateVec simulator (C API)  with a version using the Python API.

* Updated README with installation instructions for CuStateVec.

---------

Co-authored-by: PabloAndresCQ <[email protected]>
Co-authored-by: Kartik Singhal <[email protected]>

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
         args: []
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.292
+    rev: v0.1.5
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

README.md

@@ -57,6 +57,8 @@ options. To install all optional dependencies use:
 pip install .[all]
 ```
 
+Certain simulators have special requirements and are not installed by the command above. Installation instructions for these are provided [here](#simulators-with-special-requirements).
+
 For development, use (while including installation options as necessary):
 
 On Linux/Mac:
@@ -91,6 +93,12 @@ Tests can be run using:
 pytest tests
 ```
 
+### Simulators with special requirements
+
+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).
+
 ## Uninstall
 
 To uninstall:

pyproject.toml

@@ -58,6 +58,10 @@ simulators = [
     "pybind11>=2.2.3,<3.0",
     "projectq>=0.5.0,<0.9.0",
 ]
+cuda = [
+    "cuquantum-python>=23.6.0",
+    "cupy>=10.4.0",
+]
 wasmtime = [
     "wasmtime>=13.0"
 ]

python/pecos/simulators/__init__.py

@@ -11,6 +11,7 @@
 # specific language governing permissions and limitations under the License.
 
 from pecos.simulators import sim_class_types
+from pecos.simulators.cointoss import CoinToss  # Ignores quantum gates, coin toss for measurements
 from pecos.simulators.parent_sim_classes import Simulator
 from pecos.simulators.paulifaultprop import PauliFaultProp  # Pauli fault propagation sim
 from pecos.simulators.sparsesim import SparseSim as pySparseSim  # Python sparse stabilizer sim
@@ -30,10 +31,11 @@
 except ImportError:
     pass
 
-# Attempt to import optional qcgpu package
+# Attempt to import optional cuquantum and cupy packages
 try:
-    import qcgpu
+    import cupy
+    import cuquantum
 
-    from pecos.simulators._qcgpu_wrapper.state import QCQPUSim  # wrapper for qcgpu
+    from pecos.simulators.custatevec.state import CuStateVec  # wrapper for cuQuantum's cuStateVec
 except ImportError:
     pass

python/pecos/simulators/cuquantum/cuquantum_wrapper/__init__.py → python/pecos/simulators/cointoss/__init__.py

@@ -1,12 +1,13 @@
-# Copyright 2023 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.
-
-# Initial author: Tyson Lawrence
+# Copyright 2023 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.cointoss import bindings
+from pecos.simulators.cointoss.state import CoinToss

python/pecos/simulators/cointoss/bindings.py

@@ -0,0 +1,53 @@
+# Copyright 2023 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.cointoss.gates import ignore_gate, measure
+
+# Supporting gates from table:
+#   https://github.com/CQCL/phir/blob/main/spec.md#table-ii---quantum-operations
+
+gate_dict = {
+    "Init": ignore_gate,
+    "Measure": measure,
+    "I": ignore_gate,
+    "X": ignore_gate,
+    "Y": ignore_gate,
+    "Z": ignore_gate,
+    "RX": ignore_gate,
+    "RY": ignore_gate,
+    "RZ": ignore_gate,
+    "R1XY": ignore_gate,
+    "SX": ignore_gate,
+    "SXdg": ignore_gate,
+    "SY": ignore_gate,
+    "SYdg": ignore_gate,
+    "SZ": ignore_gate,
+    "SZdg": ignore_gate,
+    "H": ignore_gate,
+    "F": ignore_gate,
+    "Fdg": ignore_gate,
+    "T": ignore_gate,
+    "Tdg": ignore_gate,
+    "CX": ignore_gate,
+    "CY": ignore_gate,
+    "CZ": ignore_gate,
+    "RXX": ignore_gate,
+    "RYY": ignore_gate,
+    "RZZ": ignore_gate,
+    "R2XXYYZZ": ignore_gate,
+    "SXX": ignore_gate,
+    "SXXdg": ignore_gate,
+    "SYY": ignore_gate,
+    "SYYdg": ignore_gate,
+    "SZZ": ignore_gate,
+    "SZZdg": ignore_gate,
+    "SWAP": ignore_gate,
+}

python/pecos/simulators/cointoss/gates.py

@@ -0,0 +1,41 @@
+# Copyright 2023 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
+
+import numpy as np
+
+
+def ignore_gate(state, qubits: int, **params: Any) -> None:
+    """
+    Ignore the gate.
+
+    Args:
+        state: An instance of ``CoinToss``.
+        qubits: The qubits the gate was applied to.
+
+    Returns:
+
+    """
+
+
+def measure(state, qubits: int, **params: Any):
+    """
+    Return |1> with probability ``state.prob`` or |0> otherwise.
+
+    Args:
+        state: An instance of ``CoinToss``.
+        qubit: The qubit the measurement is applied to.
+
+    Returns:
+
+    """
+    return 1 if np.random.random() < state.prob else 0

python/pecos/simulators/cointoss/state.py

@@ -0,0 +1,50 @@
+# Copyright 2023 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 random
+
+from pecos.simulators.cointoss import bindings
+from pecos.simulators.parent_sim_classes import Simulator
+
+
+class CoinToss(Simulator):
+    """
+    Ignore all quantum operations and toss a coin to decide measurement outcomes.
+    Meant for stochastical debugging of the classical branches.
+    """
+
+    def __init__(self, num_qubits, prob=0.5, seed=None):
+        """
+        Initialization is trivial, since there is no state.
+
+        Args:
+            num_qubits (int): Number of qubits being represented.
+            prob (float): Probability of measurements returning |1>.
+                Default value is 0.5.
+            seed (int): Seed for randomness.
+
+        Returns:
+
+        """
+
+        if not isinstance(num_qubits, int):
+            msg = "``num_qubits`` should be of type ``int``."
+            raise TypeError(msg)
+        if not (prob >= 0 and prob <= 1):
+            msg = "``prob`` should be a real number in [0,1]."
+            raise ValueError(msg)
+        random.seed(seed)
+
+        super().__init__()
+
+        self.bindings = bindings.gate_dict
+        self.num_qubits = num_qubits
+        self.prob = prob