qiskit/terra/creating_a_provider.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"../../images/qiskit-heading.gif\" alt=\"Note: In order for images to show up in this jupyter notebook you need to select File => Trusted Notebook\" width=\"500 px\" align=\"left\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# _*Creating a new provider*_ \n",
    "\n",
    "The latest version of this notebook is available on https://github.com/qiskit/qiskit-tutorial.\n",
    "\n",
    "***\n",
    "### Contributors\n",
    "Yael Ben-Haim"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Qiskit Terra is a software for generating quantum circuits, running them on a simulator or device, generically 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 which 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 which wraps an external simulator. This allows to 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 whom 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": {},
   "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 = [0]*(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",
    "            if hadamard_list[qubit] == 1:\n",
    "                result[i] += int(shots/(2**(1 + hadamard_list.count(1))))\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 https://nbviewer.jupyter.org/github/Qiskit/qiskit-tutorial/blob/master/qiskit/basics/the_ibmq_provider.ipynb for relevant information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "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": {},
   "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",
    "            '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.as_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": {
    "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": [
    "To create a provider inhereit from ``BaseProvider`` and minimally implement the ``backends`` method for retreiving a list of backends."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "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": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hadamard simulator:\n",
      "{'0000': 256, '0010': 256, '0100': 256, '0110': 256}\n",
      "Aer simulator:\n",
      "{'0000': 270, '0010': 263, '0100': 253, '0110': 238}\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))"
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}