Refactoring API structure

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'windows-2022', 'macos-latest']
-        python: ['3.8', '3.9', '3.10', '3.11']
+        python: ['3.9', '3.10', '3.11', '3.12']
 
     name: "Python ${{ matrix.python }} / ${{ matrix.os }}"
     runs-on: ${{ matrix.os }}

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Updated to support Qiskit 1.0.
+- Modified the APIs for Qiskit simulation and execution on IBMQ hardware.
 
 ### Fixed
 

docs/source/tutorial.rst

@@ -29,7 +29,7 @@ First, let us import relevant modules and define function we will use:
 .. code-block:: python
 
     from graphix import Circuit
-    from graphix_ibmq.runner import IBMQBackend
+    from graphix_ibmq.backend import IBMQBackend
     import qiskit.quantum_info as qi
     from qiskit.visualization import plot_histogram
     import numpy as np

examples/gallery/aer_sim.py

@@ -12,10 +12,9 @@
 import matplotlib.pyplot as plt
 import networkx as nx
 import random
-from graphix import Circuit
-from graphix_ibmq.runner import IBMQBackend
-from qiskit.tools.visualization import plot_histogram
-from qiskit_aer.noise import NoiseModel, depolarizing_error
+from graphix.transpiler import Circuit
+from graphix_ibmq.backend import IBMQBackend
+from qiskit.visualization import plot_histogram
 
 
 def cp(circuit, theta, control, target):
@@ -84,23 +83,29 @@ def swap(circuit, a, b):
 pattern.minimize_space()
 
 # convert to qiskit circuit
-backend = IBMQBackend(pattern)
-print(type(backend.circ))
+backend = IBMQBackend()
+backend.compile(pattern)
+print(type(backend._compiled_circuit))
 
 #%%
 # We can now simulate the circuit with Aer.
 
 # run and get counts
-result = backend.simulate()
+backend.set_simulator()
+job = backend.submit_job(shots=1024)
+result = job.retrieve_result()
 
 #%%
 # We can also simulate the circuit with noise model
 
 # create an empty noise model
+from qiskit_aer.noise import NoiseModel, depolarizing_error
+
+# add depolarizing error to all single qubit gates
 noise_model = NoiseModel()
-# add depolarizing error to all single qubit u1, u2, u3 gates
 error = depolarizing_error(0.01, 1)
-noise_model.add_all_qubit_quantum_error(error, ["u1", "u2", "u3"])
+noise_model.add_all_qubit_quantum_error(error, ["id", "rz", "sx", "x", "u1"])
+backend.set_simulator(noise_model=noise_model)
 
 # print noise model info
 print(noise_model)
@@ -109,7 +114,8 @@ def swap(circuit, a, b):
 # Now we can run the simulation with noise model
 
 # run and get counts
-result_noise = backend.simulate(noise_model=noise_model)
+job = backend.submit_job(shots=1024)
+result_noise = job.retrieve_result()
 
 
 #%%
@@ -137,31 +143,3 @@ def swap(circuit, a, b):
 legend = ax.legend(fontsize=18)
 legend = ax.legend(loc='upper left')
 # %%
-
-
-#%%
-# Example demonstrating how to run a pattern on an IBM Quantum device. All explanations are provided as comments.
-
-# First, load the IBMQ account using an API token.
-"""
-from qiskit_ibm_runtime import QiskitRuntimeService
-service = QiskitRuntimeService(channel="ibm_quantum", token="your_ibm_token", instance="ibm-q/open/main")
-"""
-
-# Then, select the quantum system on which to run the circuit.
-# If no system is specified, the least busy system will be automatically selected.
-"""
-backend.get_system(service, "ibm_kyoto")
-"""
-
-# Finally, transpile the quantum circuit for the chosen system and execute it.
-"""
-backend.transpile()
-result = backend.run(shots=128)
-"""
-
-# To retrieve the result at a later time, use the code below.
-"""
-result = backend.retrieve_result("your_job_id")
-"""
-# %%

examples/gallery/qiskit_to_graphix.py

@@ -9,7 +9,7 @@
 
 
 # %%
-from qiskit import QuantumCircuit, transpile
+from qiskit import transpile
 from qiskit.circuit.random.utils import random_circuit
 
 qc = random_circuit(5, 2, seed=42)

examples/ibm_device.py

@@ -12,10 +12,9 @@
 import matplotlib.pyplot as plt
 import networkx as nx
 import random
-from graphix import Circuit
-from graphix_ibmq.runner import IBMQBackend
-from qiskit_ibm_provider import IBMProvider
-from qiskit.tools.visualization import plot_histogram
+from graphix.transpiler import Circuit
+from graphix_ibmq.backend import IBMQBackend
+from qiskit.visualization import plot_histogram
 from qiskit.providers.fake_provider import FakeLagos
 
 
@@ -68,7 +67,7 @@ def swap(circuit, a, b):
 swap(circuit, 0, 2)
 
 # transpile and plot the graph
-pattern = circuit.transpile()
+pattern = circuit.transpile().pattern
 nodes, edges = pattern.get_graph()
 g = nx.Graph()
 g.add_nodes_from(nodes)
@@ -84,45 +83,39 @@ def swap(circuit, a, b):
 pattern.minimize_space()
 
 # convert to qiskit circuit
-backend = IBMQBackend(pattern)
-backend.to_qiskit()
-print(type(backend.circ))
+backend = IBMQBackend()
+backend.compile(pattern)
+print(type(backend._compiled_circuit))
 
 #%%
 # load the account with API token
-IBMProvider.save_account(token='MY API TOKEN')
+from qiskit_ibm_runtime import QiskitRuntimeService
+QiskitRuntimeService.save_account(channel="ibm_quantum", token="API TOKEN", overwrite=True)
 
 # get the device backend
-instance_name = 'ibm-q/open/main'
-backend_name = "ibm_lagos"
-backend.get_backend(instance=instance_name,resource=backend_name)
-
-#%%
-# Get provider and the backend.
-
-instance_name = "ibm-q/open/main"
-backend_name = "ibm_lagos"
-
-backend.get_backend(instance=instance_name, resource=backend_name)
+backend.select_device()
 
 #%%
 # We can now execute the circuit on the device backend.
 
-result = backend.run()
+job = backend.submit_job(shots=1024)
 
 #%%
-# Retrieve the job if needed
+# Retrieve the job result
 
-# result = backend.retrieve_result("Job ID")
+if job.is_done:
+    result = job.retrieve_result()
 
 #%%
-# We can simulate the circuit with noise model based on the device we used
+# We can simulate the circuit with device-based noise model.
 
 # get the noise model of the device backend
-backend_noisemodel = FakeLagos()
+from qiskit_ibm_runtime.fake_provider import FakeManilaV2
+backend.set_simulator(based_on=FakeManilaV2())
 
 # execute noisy simulation and get counts
-result_noise = backend.simulate(noise_model=backend_noisemodel)
+job = backend.submit_job(shots=1024)
+result_noise = job.retrieve_result()
 
 #%%
 # Now let us compare the results with theoretical output

graphix_ibmq/backend.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from graphix_ibmq.compiler import IBMQPatternCompiler
+from graphix_ibmq.job import IBMQJob
+from graphix_ibmq.compile_options import IBMQCompileOptions
+
+from qiskit_aer.noise import NoiseModel
+from qiskit_aer import AerSimulator
+from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
+from qiskit_ibm_runtime import SamplerV2 as Sampler
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from graphix.pattern import Pattern
+    from qiskit import QuantumCircuit
+    from qiskit.providers.backend import BackendV2
+
+
+class IBMQBackend:
+    """IBMQ backend implementation for compiling and executing quantum patterns."""
+
+    _options: IBMQCompileOptions
+    _compiled_circuit: QuantumCircuit | None
+    _execution_mode: str | None
+    _noise_model: NoiseModel | None
+    _simulator: AerSimulator | None
+    _resource: BackendV2 | None
+    _compiler: IBMQPatternCompiler | None
+
+    def __init__(self) -> None:
+        self._compiler = None
+        self._options = IBMQCompileOptions()
+        self._compiled_circuit = None
+        self._execution_mode = None
+        self._noise_model = None
+        self._simulator = None
+        self._resource = None
+
+    def compile(self, pattern: Pattern, options: IBMQCompileOptions | None = None) -> None:
+        """Compile the assigned pattern using IBMQ options.
+
+        Parameters
+        ----------
+        options : CompileOptions, optional
+            Compilation options. Must be of type IBMQCompileOptions.
+        """
+        if options is None:
+            self._options = IBMQCompileOptions()
+        elif not isinstance(options, IBMQCompileOptions):
+            raise TypeError("Expected IBMQCompileOptions")
+        else:
+            self._options = options
+
+        self._compiler = IBMQPatternCompiler(pattern)
+        self._compiled_circuit = self._compiler.to_qiskit_circuit(
+            save_statevector=self._options.save_statevector,
+            layout_method=self._options.layout_method,
+        )
+
+    def set_simulator(
+        self,
+        noise_model: NoiseModel | None = None,
+        based_on: BackendV2 | None = None,
+    ) -> None:
+        """Configure the backend to use a simulator.
+
+        Parameters
+        ----------
+        noise_model : NoiseModel, optional
+            Noise model to apply to the simulator.
+        based_on : BackendV2, optional
+            Backend to base the noise model on.
+        """
+        if noise_model is None and based_on is not None:
+            noise_model = NoiseModel.from_backend(based_on)
+
+        self._execution_mode = "simulation"
+        self._noise_model = noise_model
+        self._simulator = AerSimulator(noise_model=noise_model)
+
+    def select_device(
+        self,
+        name: str | None = None,
+        least_busy: bool = False,
+        min_qubits: int = 1,
+    ) -> None:
+        """Select a hardware backend from IBMQ.
+
+        Parameters
+        ----------
+        name : str, optional
+            Specific device name to use.
+        least_busy : bool, optional
+            If True, select the least busy device that meets requirements.
+        min_qubits : int, optional
+            Minimum number of qubits required.
+        """
+        from qiskit_ibm_runtime import QiskitRuntimeService
+
+        self._execution_mode = "hardware"
+        service = QiskitRuntimeService()
+
+        if least_busy or name is None:
+            self._resource = service.least_busy(min_num_qubits=min_qubits, operational=True)
+        else:
+            self._resource = service.backend(name)
+
+        print(f"Selected device: {self._resource.name}")
+
+    def submit_job(self, shots: int = 1024) -> IBMQJob:
+        """Submit the compiled circuit to either simulator or hardware backend.
+
+        Parameters
+        ----------
+        shots : int, optional
+            Number of execution shots. Defaults to 1024.
+
+        Returns
+        -------
+        Job
+            A handle to monitor the job status and retrieve results.
+
+        Raises
+        ------
+        RuntimeError
+            If the pattern has not been compiled or execution mode is not set.
+        """
+        if self._compiled_circuit is None:
+            raise RuntimeError("Pattern must be compiled before submission.")
+
+        if self._execution_mode is None:
+            raise RuntimeError("Execution mode is not configured. Use select_backend() or set_simulator().")
+
+        if not hasattr(self, "_options") or self._options is None:
+            raise RuntimeError("Compile options are not set.")
+
+        if self._execution_mode == "simulation":
+            pm = generate_preset_pass_manager(
+                backend=self._simulator,
+                optimization_level=self._options.optimization_level,
+            )
+            transpiled = pm.run(self._compiled_circuit)
+            sampler = Sampler(mode=self._simulator)
+            job = sampler.run([transpiled], shots=shots)
+            return IBMQJob(job, self._compiler)
+
+        elif self._execution_mode == "hardware":
+            pm = generate_preset_pass_manager(
+                backend=self._resource,
+                optimization_level=self._options.optimization_level,
+            )
+            transpiled = pm.run(self._compiled_circuit)
+            sampler = Sampler(mode=self._resource)
+            job = sampler.run([transpiled], shots=shots)
+            return IBMQJob(job, self._compiler)
+
+        else:
+            raise RuntimeError("Execution mode is not configured. Use select_backend() or set_simulator().")