Add local simulation capabilities

.github/workflows/main.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Install Deps
         run: make install
       - name: Downgrade Qiskit
-        run: venv/bin/pip install qiskit==0.41.1
+        run: venv/bin/pip install qiskit==0.43.0
       - name: Install and Run Tests
         run: make unit-tests
   lint:

MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include qiskit_alice_bob_provider/local/resources/*.json

README.md

@@ -14,7 +14,7 @@ pip install qiskit-alice-bob-provider
 `pip` will handle installing all the python dependencies automatically and you
 will always install the  latest (and well-tested) version.
 
-## Use your Alice & Bob API key
+## Remote execution on Alice & Bob QPUs: use your API key
 
 To obtain an API key, please [contact Alice & Bob](https://alice-bob.com/contact/).
 
@@ -29,7 +29,7 @@ Where `MY_API_KEY` is your API key to the Alice & Bob API.
 
 ```python
 print(ab.backends())
-backend = ab.get_backend('SINGLE_CAT_SIMULATOR')
+backend = ab.get_backend('SINGLE_CAT')
 ```
 
 The backend can then be used like a regular Qiskit backend:
@@ -45,3 +45,61 @@ job = execute(c, backend)
 res = job.result()
 print(res.get_counts())
 ```
+
+## Local simulation of cat quit processors
+
+This project contains multiple simulators of multi cat qubit processors.
+
+```python
+from qiskit_alice_bob_provider import AliceBobLocalProvider
+from qiskit import QuantumCircuit, execute, transpile
+
+provider = AliceBobLocalProvider()
+print(provider.backends())
+# PHYSICAL_CATS_6, PHYSICAL_CATS_40, LESCANNE_2020
+```
+
+The `PHYSICAL_CATS` backends are theoretical models of quantum processors made
+up of physical cat qubits.
+They can be used to study the properties of error correction codes implemented
+with physical cat qubits, for different hardware performance levels
+(see the parameters of class `PhysicalCatProcessor`).
+
+The `LESCANNE_2020` backend is an interpolated model simulating the processor
+used in the [seminal paper](https://arxiv.org/pdf/1907.11729.pdf) by Raphaël
+Lescanne in 2020.
+This interpolated model is configured to act as a digital twin of the cat qubit
+used in this paper.
+It does not represent the current performance of Alice & Bob's cat qubits.
+
+The example below schedules and simulates a Bell state preparation circuit on
+a `PHYSICAL_CATS_6` processor, for different values of parameters `alpha` and
+`kappa_2`.
+
+```python
+from qiskit_alice_bob_provider import AliceBobLocalProvider
+from qiskit import QuantumCircuit, execute, transpile
+
+provider = AliceBobLocalProvider()
+
+circ = QuantumCircuit(2, 2)
+circ.initialize('0+')
+circ.cx(0, 1)
+circ.measure(0, 0)
+circ.measure(1, 1)
+
+# Default 6-qubit QPU with the ratio of memory dissipation rates set to
+# k1/k2=1e-5 and cat amplitude alpha set to 4.
+backend = provider.get_backend('PHYSICAL_CATS_6')
+
+print(transpile(circ, backend).draw())
+# *Displays a timed and scheduled circuit*
+
+print(execute(circ, backend, shots=100000).result().get_counts())
+# {'11': 49823, '00': 50177}
+
+# Changing the cat amplitude from 4 (default) to 2 and k1/k2 to 1e-2.
+backend = provider.get_backend('PHYSICAL_CATS_6', alpha=2, kappa_2=1e4)
+print(execute(circ, backend, shots=100000).result().get_counts())
+# {'01': 557, '11': 49422, '10': 596, '00': 49425}
+```

pyproject.toml

@@ -31,9 +31,11 @@ urls = {Homepage = "https://github.com/Alice-Bob-SW/qiskit-alice-bob-provider",
 requires-python = ">=3.7"
 dependencies = [
     "requests",
-    "qiskit-terra>=0.22.0",  # first version with backend transpiler plugins
+    "qiskit-terra>=0.24.0",  # required for correct handling of durations
+    "qiskit-aer",
     "qiskit-qir-alice-bob-fork==0.3.2b0",
-    "tenacity"
+    "tenacity",
+    "pydantic>=2.0"
 ]
 
 [project.optional-dependencies]
@@ -57,6 +59,7 @@ dev = [
 
 [project.entry-points."qiskit.transpiler.translation"]
 state_preparation = "qiskit_alice_bob_provider.translation_plugin:StatePreparationPlugin"
+local_state_preparation = "qiskit_alice_bob_provider.local.translation_plugin:LocalStatePreparationPlugin"
 
 [tool.setuptools.packages.find]
 include = ["qiskit_alice_bob_provider*"]
@@ -73,6 +76,8 @@ line_length = 79
 module = [
     "setuptools",
     "qiskit.*",
-    "qiskit_qir.*"
+    "qiskit_qir.*",
+    "qiskit_aer.*",
+    "scipy.*"
 ]
 ignore_missing_imports = true

qiskit_alice_bob_provider/__init__.py

@@ -16,4 +16,5 @@
 
 # flake8: noqa: F401
 
+from .local import AliceBobLocalProvider
 from .provider import AliceBobProvider

qiskit_alice_bob_provider/custom_instructions.py

@@ -16,7 +16,7 @@
 
 from typing import Optional
 
-from qiskit.circuit import Instruction, InstructionSet, QuantumCircuit
+from qiskit.circuit import Instruction, InstructionSet, QuantumCircuit, Reset
 from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary
 from qiskit.circuit.quantumcircuit import ClbitSpecifier, QubitSpecifier
 
@@ -47,3 +47,16 @@ def _measure_x(
 SessionEquivalenceLibrary.add_equivalence(
     _measure_x_inst, _measure_x_inst.definition
 )
+
+
+# Add an equivalent from Reset to Initialize('0'). This is useful in the case
+# of the local provider.
+# Although we may want to preserve the Reset instruction for a future behavior
+# not yet implemented (e.g., resetting to the void state of the cavity in
+# case of cat qubits, which is not how the logical |0> state is encoded), users
+# are used to use Reset to actually say Initialize('0').
+# That's what this equivalence rule does. If it causes trouble in the future,
+# it may be removed.
+_c = QuantumCircuit(1, 0)
+_c.initialize('0', 0)
+SessionEquivalenceLibrary.add_equivalence(Reset(), _c)

qiskit_alice_bob_provider/ensure_preparation_pass.py

@@ -14,11 +14,17 @@
 #    limitations under the License.
 ##############################################################################
 
-from qiskit.circuit import Qubit, Reset
+from typing import Callable
+
+from qiskit.circuit import Instruction, Qubit, Reset
 from qiskit.dagcircuit import DAGCircuit, DAGInNode, DAGOpNode
 from qiskit.transpiler import TransformationPass
 
 
+def _reset_prep() -> Instruction:
+    return Reset()
+
+
 class EnsurePreparationPass(TransformationPass):
     """
     A transpilation pass that ensures there is a state preparation at the
@@ -47,6 +53,12 @@ class EnsurePreparationPass(TransformationPass):
     from Qiskit to QIR.
     """
 
+    def __init__(
+        self, prep_instruction: Callable[[], Instruction] = _reset_prep
+    ):
+        super().__init__()
+        self._prep = prep_instruction
+
     def run(self, dag: DAGCircuit) -> DAGCircuit:
         preparations = {'reset', 'initialize', 'state_preparation'}
         for node in dag.topological_nodes():
@@ -62,7 +74,7 @@ def run(self, dag: DAGCircuit) -> DAGCircuit:
                 new_dag = DAGCircuit()
                 new_dag.add_qubits(successor.qargs)
                 new_dag.add_clbits(successor.cargs)
-                new_dag.apply_operation_back(Reset(), qargs=(node.wire,))
+                new_dag.apply_operation_back(self._prep(), qargs=(node.wire,))
                 new_dag.apply_operation_back(
                     successor.op,
                     qargs=successor.qargs,

qiskit_alice_bob_provider/job.py

@@ -71,7 +71,7 @@ def __init__(
         self._backend_v2 = backend
         self._api_client = api_client
         self._circuit = circuit
-        self._last_response: Optional[dict] = None
+        self._last_response: Optional[Dict] = None
         self._status: Optional[JobStatus] = None
         self._counts: Optional[Dict[str, int]] = None
         self._files: Dict[str, _DownloadedFile] = {}

qiskit_alice_bob_provider/local/__init__.py

@@ -0,0 +1,19 @@
+##############################################################################
+# Copyright 2023 Alice & Bob
+#
+#    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.
+##############################################################################
+
+# flake8: noqa: F401
+
+from .provider import AliceBobLocalProvider