Backend module integration with WMI simulators and quantum computers (#3

)

* FEAT: WMI back-end integration general structure

FEAT: Implement initial ProcessorConfiguration logic

CHORE: Add configuration to twnsor_nw_proc

FEAT: Architecture WIP

Architecture WIP

Architecture WIP

Architecture WIP (Qiskit Simulator)

Configuration & Options WIP

FEAT: Options implementation and refactoring

TEST: QiskitSimulator test WIP

* FEAT: Core Experiment implementation and refactoring

REFACTOR: Processor Experiment relation

CHORE: Implement Martin's proposals regarding properties

FEAT: Experiment WIP

REFACTOR: experiment serialization and BE integration

* FEAT: Implement gates.as_qobj_openQASM serialization functions

* FEAT: Implement measurement operator and other tests, fixes, chores, and refactorings

CHORE + Measurement Operation WIP

TEST: UTs for gates Qobj OpenQASM serialization + FIX: Circular dependencies

FEAT: Implement measurement operator

FEAT: test & refactor measurement operator and gates

REFACTOR: as_qobj_openQASM() -> as_openQASM()

* FEAT: Implement ControlledGate openQASM serialization + UTs

* TEST: UT for openQASM Qobj circuit serialization

* FEAT: Implement Experiment validation, serialization, and refactor options

FEAT: Experiment validation + small refactoring

CHORE: Remove duplicate method

FEAT: Experiment options and serialization WIP + REFACTOR: remove hardcoded values (constants)

FEAT: Experiment serialization + REFACTOR: bits to clbits

CHORE: Rename QSIM to WMIQSIM

* REFACTOR: QuantumProcessor, configuration and experiment flow

* REFACTOR: Gate serialization and processor configuration

* FEAT: Implement id, sx, and iswap gates

CHORE: Add new gates to modules

Implement UTs for the id, sx, and iswap gates

* FEAT: Implement control instructions and restructure backend module

REFACTOR: Restructure backend module

FEAT: Control Instructions WIP + REFACTOR: Measurement

FEAT: Implement barrier and delay, and their UTs

* TEST: Add additional tests and hashing for Qubit

FIX: as_circuit_matrix() UT for iSwap gate

* FEAT: Implement WMI Qiskit Sim network communication

REFACTOR: Simplify architecture + FEAT: WMI Requests WIP

Add remaining TODOs

FEAT: Implement results() and wait_for_results()

FIX: Tie up loose-ends

CHORE: WMI Experiment

REFACTOR: counts as get_counts function

CHORE: QoL improvements

REFACTOR: TNP Refactoring WIP

* REFACTOR: Syntax update to Python 3.10

* REFACTOR: Various refactoring, syntax fixes, and chores

REFACTOR: WMI Options syntax and chores

CHORE: Fix "coupling_map" name conflict

FIX: Options syntax error

* FEAT: WMI QC Implementation

REFACTOR: as_openQASM -> as_qasm

Add requests as dependency and backend example ipynb

REFACTOR: Small fixes and UTs

TEST: UTs for backend functionalities + small refactoring

TEST: Add UTs for WMIQC as well

* FIX: Print warning if circuits contain control instructions

* DOC: Update documentation on extending the qib backend interface

* CHORE: Various fixes, minor chores, and code clean-up

FIX: Use radians instead of degrees

Chore

FIX: append_circuit object not iterable error

CHORE: Minor fixes and improvements

CHORE: Improve backend architecture diagram

* FEAT: Add Quantum State Tomography example (on both WMI QiskitSim and WMI QC)

Chore: wmi qc separate notebook

FEAT: Different query frequencies + QST clean-up WIP

WMI QSim + QC (almost) final experiments

CHORE: Restructure QST experiments, separate python notebooks, add WMIQC QST

QST on WMI quantum computer

Backend example QC

* FIX: Failing backend UTs

doc/index.rst

@@ -7,13 +7,14 @@ Welcome to *qib*'s documentation!
 
 Tutorials
 ---------
-The following tutorials provide an introduction to the main concepts and features of *qib*:
+The following tutorials provide insights to the main concepts and features of *qib*:
 
 .. toctree::
     :numbered:
     :maxdepth: 1
 
-    basics
+    tutorials/basics
+    tutorials/extending_backend
 
 
 API documentation

doc/requirements.txt

@@ -2,3 +2,4 @@ sphinx>=5.0.0
 ipython
 nbsphinx
 h5py
+requests

doc/tutorials/extending_backend.ipynb

@@ -0,0 +1,207 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# _qib_ Extending the Backend Interface"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this section we explain how someone could extend the backend interface of qib to support their Quantum Backend Architecture. First we explain how the current classes and relations are configured and what their role is, then we explicitly offer a how-to guide on what abstract classes should be implemented in order to support one's custom backend."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **Note:** *For a hands-on demonstration on how the backend module of qib can be used in order to execute circuits, one can check the WMI backend example, at* `📂examples/backend/qib_backend_wmi.ipynb`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The Current Configuration"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The core components of qib's backend module are represented by the following classes :\n",
+    "\n",
+    "1. `QuantumProcessor` *(abstract)*: The actual representation of the given quantum processor. This class defines the functionality of interacting with the targeted quantum backend (usually over a networking request-response mechanism), in order to generate and submit experiment objects.\n",
+    "\n",
+    "2. `Experiment` *(abstract)*: This component defines the behaviour of a quantum experiment performed on the given processor. It acts as both a data class and a behaviour class, defining how the experiment gets initialized, validated, controlled, and queried (i.e. how the results of the experiment are obtained).\n",
+    "\n",
+    "3. `ExperimentResults` *(abstract)*: A purely data-class responsible for representing and interpreting quantum experiment results of an experiment already performed on the given processor.\n",
+    "\n",
+    "4. `Options` *(abstract)*: The (configurable) options that the clients of qib are able to dynamically modify in order to run experiments in different configurations or with different properties. Each quantum processor defines its own available options.\n",
+    "\n",
+    "5. `ProcessorConfiguration` *(abstract)*: The configuration of the `QuantumProcessor`. This class can also be extended on need, but it should more or less follow the same base principles. It represents the immutable properties of a quantum processor (such as qubits and gates configuration, if it is a simulator or not, etc.). These properties are hardcoded when defining the quantum processor, and thus should not (frequently) change."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Have a look at the architecture below for a more detailed understanding of the components and how they interconnect with each other:\n",
+    "\n",
+    "<img src=\"../_static/qib_backend_architecture.jpg\" alt=\"qib Backend Module Architecture\" width=\"640px\"/>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## How to Extend the Interface"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In order to extend the currently available backend interface, one must:\n",
+    "\n",
+    "### Create Provider Sub-Module\n",
+    "\n",
+    "Create a new python sub-module with the provider name:\n",
+    "\n",
+    "- Create a new folder under `src/backend` with the provider name (e.g. `src/backend/myprov`)\n",
+    "\n",
+    "- Create a `__init__.py` file within the folder, where to import all python implementations\n",
+    "\n",
+    "`📂src/backend/myprov/__init__.py`\n",
+    "```python\n",
+    "from qib.backend.myprov.myprov_options import MyProvOptions\n",
+    "from qib.backend.myprov.myprov_experiment import MyProvExperiment, MyProvExperimentResults\n",
+    "\n",
+    "# Backend A\n",
+    "from qib.backend.myprov.myprov_backend_a import MyProvBackendA\n",
+    "\n",
+    "# Backend B\n",
+    "from qib.backend.myprov.myprov_backend_b import MyProvBackendB\n",
+    "\n",
+    "# ...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Implement the core abstract classes:\n",
+    "\n",
+    "Implement `qib.backend.Options`\n",
+    "\n",
+    "`📂src/backend/myprov/myprov_options.py`\n",
+    "```python\n",
+    "from qib.backend.options import Options\n",
+    "\n",
+    "class MyProvOptions(Options):\n",
+    "   def __init__(self,\n",
+    "                  option1: str = \"default_value1\", # required option\n",
+    "                  option2: str = None # optional option\n",
+    "                  # ...\n",
+    "               ):\n",
+    "      self.option1: str = option1\n",
+    "      self.option2: str = option2\n",
+    "\n",
+    "   def optional(self) -> dict:\n",
+    "      optional: dict = {}\n",
+    "      if self.option2: optional['option2'] = self.option2\n",
+    "      return optional\n",
+    "```\n",
+    "\n",
+    "Implement `qib.backend.Experiment` and `qib.backend.ExperimentResults`\n",
+    "\n",
+    "`📂src/backend/myprov/myprov_experiment.py`\n",
+    "```python\n",
+    "from qib.circuit import Circuit\n",
+    "from qib.backend.myprov import MyProvOptions\n",
+    "from qib.backend import ExperimentStatus, Experiment, ExperimentResults, ExperimentType\n",
+    "\n",
+    "class MyProvExperiment(Experiment):\n",
+    "   def __init__(self, circuit: Circuit, options: MyProvOptions, exp_type: ExperimentType)\n",
+    "      self.circuit: Circuit = circuit\n",
+    "      self.options: MyProvOptions = options\n",
+    "      self.exp_type: ExperimentType = exp_type\n",
+    "      self._initialize()\n",
+    "      self._validate()\n",
+    "\n",
+    "   def results(self) -> MyProvExperimentResults | None:\n",
+    "      # implement accordingly\n",
+    "\n",
+    "   # ...\n",
+    "\n",
+    "\n",
+    "class MyProvExperimentResults(ExperimentResults):\n",
+    "   # ...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> **Note:** `Options` *or* `Experiment` *implementations might be also implemented separately for each backend (if this is necessary). Example:* `BackendAExperiment`*,* `BackendBExperiment`*, etc.*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Implement Backend Processors\n",
+    "\n",
+    "For each new quantum backend processor that one would like to implement within their provider module, implement `qib.backend.Processor`\n",
+    "\n",
+    "`📂src/backend/myprov/myprov_backend_a.py`\n",
+    "```python\n",
+    "from qib.circuit import Circuit\n",
+    "from qib.backend import QuantumProcessor, ProcessorConfiguration\n",
+    "from qib.backend.myprov import MyProvOptions, MyProvExperiment\n",
+    "\n",
+    "class MyProvBackendA(QuantumProcessor):\n",
+    "    def __init__(self):\n",
+    "        # implement accordingly\n",
+    "\n",
+    "    @staticmethod\n",
+    "    def configuration() -> ProcessorConfiguration:\n",
+    "        return ProcessorConfiguration(\n",
+    "            backend_name = 'BackendA'\n",
+    "            backend_version = 'v1.5.6'\n",
+    "            # ...\n",
+    "        )\n",
+    "    \n",
+    "    def submit_experiment(circuit: Circuit, options: MyProvOptions = MyProvOptions()) -> MyProvExperiment:\n",
+    "        # implement accordingly\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "quantum_p310",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}