qiskit/advanced/terra/6_creating_a_provider.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"../../../images/qiskit_header.png\" alt=\"Note: In order for images to show up in this jupyter notebook you need to select File => Trusted Notebook\" align=\"middle\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating a new provider\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Qiskit Terra is a software for generating quantum circuits, running them on a simulator or device (referred to as a \"backend\"), and processing the result. For a backend to work with Qiskit, it should be able to process a quantum circuit, which Qiskit passes as a ``Qobj``, and return a ``Job``. The ``Job`` allows for asynchronously tracking the run and returning a ``Result`` once complete.\n",
    "\n",
    "To simplify the addition of backends, Qiskit defines an interface that can be created by inheriting from ``BaseBackend`` and ``BaseJob``. Backends can then be grouped together and managed by inheriting from ``BaseProvider``.\n",
    "\n",
    "This tutorial explains how to create a Qiskit backend that wraps an external simulator. We can run the external simulator while enjoying the benefits of polymorphism and a uniform API across simulators."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## An external simulator for this tutorial\n",
    "\n",
    "We shall construct a very simple simulator. The simulator accepts only a single quantum circuit, where all the gates are Hadamard gates, and all qubits are measured at the end. The input format is a list of qubits on which Hadamard gates are applied. The simulator returns the counts of each basis state, in the form of a list, where the basis states are assumed to be ordered lexicographically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:01.054811Z",
     "start_time": "2019-08-21T09:35:01.041684Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[256, 0, 256, 0, 256, 0, 256, 0, 0, 0, 0, 0, 0, 0, 0, 0]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def run_hadamard_simulator(number_of_qubits, list_of_qubits, shots):\n",
    "    '''\n",
    "    Run our amazing Hadamard simulator!\n",
    "    Note: this function is not designed to be efficient\n",
    "    \n",
    "    Args:\n",
    "        number_of_qubits (integer): number of qubits in the qunatum circuit\n",
    "        list_of_qubits (list of integers): a list of qubits on whom Hadamard gates are applied\n",
    "        shots (integer): number of shots\n",
    "\n",
    "    Returns:\n",
    "        list of integers:\n",
    "            each entry in the list contains the number of shots \n",
    "            where the measurement result is the correspnding basis state;\n",
    "            basis states are ordered lexicographically\n",
    "    '''\n",
    "    \n",
    "    # For each qubit, store whether it is manipulated by an odd number of Hadamard gates\n",
    "    # Example: for run_hadamard_simulator(5, [3, 1, 3, 4], 100)\n",
    "    # we obtain hadamard_list:\n",
    "    # [0, 1, 0, 0, 1]\n",
    "    # because qubits 1 and 4 have an odd number of Hadamard gates.\n",
    "    hadamard_list = [0]*number_of_qubits\n",
    "    for qubit in list_of_qubits:\n",
    "        hadamard_list[qubit] = (1 + hadamard_list[qubit])%2\n",
    "    \n",
    "    # Calculate the result for each basis state\n",
    "    result = [int(shots/(2**hadamard_list.count(1)))]*(2**number_of_qubits)\n",
    "    for i in range(2**number_of_qubits):\n",
    "        # Example: when i is 2, \n",
    "        # the basis_state is 01000\n",
    "        basis_state = '{0:b}'.format(i).zfill(number_of_qubits)[::-1]\n",
    "        \n",
    "        for qubit in range(number_of_qubits):\n",
    "            if hadamard_list[qubit] == 0 and basis_state[qubit] == '1':\n",
    "                result[i] = 0\n",
    "                break\n",
    "                \n",
    "    return result\n",
    "\n",
    "\n",
    "run_hadamard_simulator(4, [3, 1, 3, 2], 1024)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating a job class\n",
    "\n",
    "A job class is a necessary building block when creating a provider. It allows to synchronize different executions of the simulator. Since this is out of the scope of this tutorial, we define a degenerated job, which effectively does nothing. See [The IBM Q Provider](../../fundamentals/3_the_ibmq_account.ipynb#The-Provider-) for relevant information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:03.510628Z",
     "start_time": "2019-08-21T09:35:01.072835Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit.providers import BaseJob\n",
    "\n",
    "class HadamardJob(BaseJob):\n",
    "    def __init__(self, backend):\n",
    "        super().__init__(backend, 1)\n",
    "        \n",
    "    def result(self):\n",
    "        return self._result\n",
    "    \n",
    "    def cancel(self):\n",
    "        pass\n",
    "    \n",
    "    def status(self):\n",
    "        pass\n",
    "    \n",
    "    def submit(self):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating a backend\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:03.547831Z",
     "start_time": "2019-08-21T09:35:03.534819Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit.providers import BaseBackend\n",
    "from qiskit.providers.models import BackendConfiguration\n",
    "from qiskit import qobj as qiskit_qobj\n",
    "from qiskit.result import Result\n",
    "\n",
    "\n",
    "class HadamardSimulator(BaseBackend):\n",
    "    '''\n",
    "    A wrapper backend for the Hadamard simulator\n",
    "    '''\n",
    "\n",
    "    def __init__(self, provider=None):\n",
    "        configuration = {\n",
    "            'backend_name': 'hadamard_simulator',\n",
    "            'backend_version': '0.1.0',\n",
    "            'url': 'http://www.i_love_hadamard.com',\n",
    "            'simulator': True,\n",
    "            'local': True,\n",
    "            'coupling_map': None,\n",
    "            'description': 'Simulates only Hadamard gates',\n",
    "            'basis_gates': ['h', 'x'],  # basis_gates must contain at least two gates\n",
    "            'memory': True,\n",
    "            'n_qubits': 30,\n",
    "            'conditional': False,\n",
    "            'max_shots': 100000,\n",
    "            'open_pulse': False,\n",
    "            'gates': [\n",
    "                {\n",
    "                    'name': 'TODO',\n",
    "                    'parameters': [],\n",
    "                    'qasm_def': 'TODO'\n",
    "                }\n",
    "            ]\n",
    "        }\n",
    "        \n",
    "        # We will explain about the provider in the next section\n",
    "        super().__init__(configuration=BackendConfiguration.from_dict(configuration),\n",
    "                         provider=provider)\n",
    "\n",
    "\n",
    "    def run(self, qobj):\n",
    "        \"\"\"Run qobj\n",
    "\n",
    "        Args:\n",
    "            qobj (QObj): circuit description\n",
    "\n",
    "        Returns:\n",
    "            HadamardJob: derived from BaseJob\n",
    "        \"\"\"\n",
    "        hadamard_job = HadamardJob(None)\n",
    "            \n",
    "        experiment_results = []\n",
    "        for circuit_index, circuit in enumerate(qobj.experiments):\n",
    "            number_of_qubits = circuit.config.n_qubits\n",
    "            shots = qobj.config.shots\n",
    "            \n",
    "            list_of_qubits = []\n",
    "            for operation in circuit.instructions:\n",
    "                if getattr(operation, 'conditional', None):\n",
    "                    raise QiskitError('conditional operations are not supported '\n",
    "                                      'by the Hadamard simulator')\n",
    "                if operation.name != 'h':\n",
    "                    if operation.name == 'measure':\n",
    "                        continue\n",
    "                    else:\n",
    "                        raise QiskitError('The Hadamrd simulator allows only Hadamard gates')\n",
    "                \n",
    "                list_of_qubits.append(operation.qubits[0])\n",
    "            \n",
    "            # Need to verify that \n",
    "            # all the qubits are measured, and to different classical registers.\n",
    "            # Raise an error otherwise.\n",
    "            # We skip this part here.            \n",
    "            \n",
    "            counts = run_hadamard_simulator(number_of_qubits, list_of_qubits, shots)\n",
    "            \n",
    "            formatted_counts = {}\n",
    "            for i in range(2**number_of_qubits):\n",
    "                if counts[i] != 0:\n",
    "                    formatted_counts[hex(i)] = counts[i]\n",
    "                           \n",
    "            experiment_results.append({\n",
    "                'name': circuit.header.name,\n",
    "                'success': True, \n",
    "                'shots': shots, \n",
    "                'data': {'counts': formatted_counts},\n",
    "                'header': circuit.header.to_dict()\n",
    "            })\n",
    "                        \n",
    "        hadamard_job._result = Result.from_dict({\n",
    "            'results': experiment_results,\n",
    "            'backend_name': 'hadamard_simulator',\n",
    "            'backend_version': '0.1.0',\n",
    "            'qobj_id': '0',\n",
    "            'job_id': '0',\n",
    "            'success': True\n",
    "        })\n",
    "        \n",
    "        return hadamard_job"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations, your backend is ready! Now you can create a Qiskit circuit and run your simulator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:03.573285Z",
     "start_time": "2019-08-21T09:35:03.559936Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'0000': 256, '0010': 256, '0100': 256, '0110': 256}\n"
     ]
    }
   ],
   "source": [
    "from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister, execute\n",
    "from qiskit.transpiler import PassManager\n",
    "\n",
    "qreg = QuantumRegister(4)\n",
    "creg = ClassicalRegister(4)\n",
    "qc = QuantumCircuit(qreg, creg)\n",
    "qc.h(qreg[3])\n",
    "qc.h(qreg[1])\n",
    "qc.h(qreg[3])\n",
    "qc.h(qreg[2])\n",
    "qc.measure(qreg, creg)\n",
    "\n",
    "hadamard_job = execute(qc, backend=HadamardSimulator(), pass_manager=PassManager(), shots=1024)\n",
    "result = hadamard_job.result()\n",
    "\n",
    "print(result.get_counts(qc))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating a provider"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a provider inherited from ``BaseProvider`` and minimally implement the ``backends`` method for retrieving a list of backends."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:03.601247Z",
     "start_time": "2019-08-21T09:35:03.591084Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit.providers import BaseProvider\n",
    "from qiskit.providers.providerutils import filter_backends\n",
    "\n",
    "class HadamardProvider(BaseProvider):\n",
    "    \"\"\"Provider for the Hadamard backend\"\"\"\n",
    "\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        super().__init__(args, kwargs)\n",
    "\n",
    "        # Populate the list of Hadamard backends\n",
    "        self._backends = [HadamardSimulator(provider=self)]\n",
    "\n",
    "    def backends(self, name=None, filters=None, **kwargs):\n",
    "        # pylint: disable=arguments-differ\n",
    "        backends = self._backends\n",
    "        if name:\n",
    "            backends = [backend for backend in backends if backend.name() == name]\n",
    "\n",
    "        return filter_backends(backends, filters=filters, **kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following piece of code runs two simulators on the same quantum circuit. The simulators are accessed by their providers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:04.061510Z",
     "start_time": "2019-08-21T09:35:04.030137Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hadamard simulator:\n",
      "{'0000': 256, '0010': 256, '0100': 256, '0110': 256}\n",
      "Aer simulator:\n",
      "{'0000': 252, '0010': 266, '0100': 237, '0110': 269}\n"
     ]
    }
   ],
   "source": [
    "from qiskit import execute, Aer\n",
    "from qiskit.transpiler import PassManager\n",
    "\n",
    "hadamard_provider = HadamardProvider()\n",
    "\n",
    "new_hadamard_job = execute(qc, hadamard_provider.get_backend('hadamard_simulator'), \n",
    "                           pass_manager=PassManager(), shots=1024)\n",
    "new_hadamard_result = new_hadamard_job.result()\n",
    "\n",
    "aer_job = execute(qc, Aer.get_backend('qasm_simulator'),\n",
    "                  pass_manager=PassManager(), shots=1024)\n",
    "aer_result = aer_job.result()\n",
    "\n",
    "print('Hadamard simulator:')\n",
    "print(new_hadamard_result.get_counts(qc))\n",
    "print('Aer simulator:')\n",
    "print(aer_result.get_counts(qc))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-08-21T09:35:24.611599Z",
     "start_time": "2019-08-21T09:35:24.600854Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<h3>Version Information</h3><table><tr><th>Qiskit Software</th><th>Version</th></tr><tr><td>Qiskit</td><td>0.12.2</td></tr><tr><td>Terra</td><td>0.9.1</td></tr><tr><td>Aer</td><td>0.3.0</td></tr><tr><td>Ignis</td><td>0.2.0</td></tr><tr><td>Aqua</td><td>0.5.5</td></tr><tr><td>IBM Q Provider</td><td>0.3.3</td></tr><tr><th>System information</th></tr><tr><td>Python</td><td>3.7.4 (default, Sep  7 2019, 18:27:02) \n",
       "[Clang 10.0.1 (clang-1001.0.46.4)]</td></tr><tr><td>OS</td><td>Darwin</td></tr><tr><td>CPUs</td><td>4</td></tr><tr><td>Memory (Gb)</td><td>16.0</td></tr><tr><td colspan='2'>Tue Oct 15 11:12:52 2019 CDT</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div style='width: 100%; background-color:#d5d9e0;padding-left: 10px; padding-bottom: 10px; padding-right: 10px; padding-top: 5px'><h3>This code is a part of Qiskit</h3><p>&copy; Copyright IBM 2017, 2019.</p><p>This code is licensed under the Apache License, Version 2.0. You may<br>obtain a copy of this license in the LICENSE.txt file in the root directory<br> of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.<p>Any modifications or derivative works of this code must retain this<br>copyright notice, and modified files need to carry a notice indicating<br>that they have been altered from the originals.</p></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import qiskit.tools.jupyter\n",
    "%qiskit_version_table\n",
    "%qiskit_copyright"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.4"
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}