qiskit/terra/backend_monitoring_tools.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": [
    "# Tools for Monitoring Backends and Jobs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this section, we will learn how to monitor the status of jobs submitted to devices and simulators (collectively called backends), as well as discover how to easily query backend details and view the collective state of all the backends available to you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-11-08T16:22:54.277808Z",
     "start_time": "2018-11-08T16:22:54.274313Z"
    }
   },
   "source": [
    "## Loading the Monitoring Tools"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, let us load the default qiskit routines, and register our IBMQ credentials."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-22T08:57:10.431632Z",
     "start_time": "2018-12-22T08:57:07.746736Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit import *\n",
    "IBMQ.load_accounts(hub=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions for monitoring jobs and backends are here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-22T08:57:10.443958Z",
     "start_time": "2018-12-22T08:57:10.433764Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit.tools.monitor import job_monitor, backend_monitor, backend_overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tracking Job Status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many times a job(s) submitted to the IBM Q network can take a long time to process, e.g. jobs with many circuits and/or shots, or may have to wait in queue for other users.  In situations such as these, it is beneficial to have a way of monitoring the progress of a job, or several jobs at once.  As of Qiskit `0.6+` it is possible to monitor the status of a job in a Jupyter notebook, and also in a Python script (verision `0.7+`).\n",
    "\n",
    "Lets see how to make use of these tools."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Monitoring the status of a single job"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets build a simple Bell circuit, submit it to a device, and then monitor its status."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-21T16:47:57.789932Z",
     "start_time": "2018-12-21T16:47:57.780989Z"
    }
   },
   "outputs": [],
   "source": [
    "q = QuantumRegister(2)\n",
    "c = ClassicalRegister(2)\n",
    "qc = QuantumCircuit(q, c)\n",
    "\n",
    "qc.h(q[0])\n",
    "qc.cx(q[0], q[1])\n",
    "qc.measure(q, c);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets grab the least busy backend"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-22T08:57:22.950119Z",
     "start_time": "2018-12-22T08:57:19.524051Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'ibmq_16_melbourne'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.providers.ibmq import least_busy\n",
    "backend = least_busy(IBMQ.backends(filters=lambda x: not x.configuration().simulator))\n",
    "backend.name()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Monitor the job using `job_monitor` in blocking-mode (i.e. using the same thread as the Python interpretor)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-21T18:08:27.252779Z",
     "start_time": "2018-12-21T17:37:31.290147Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Job Status: job has successfully run\n"
     ]
    }
   ],
   "source": [
    "job1 = execute(qc, backend)\n",
    "job_monitor(job1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to monitor the job using `job_monitor` in async-mode (Jupyter notebooks only).  The job will be monitored in a separate thread, allowing you to continue to work in the notebook. For details see: [Jupyter tools for Monitoring jobs and backends](../jupyter/jupyter_backend_tools.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changing the interval of status updating"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, the interval at which the job status is checked is every two seconds.  However, the user is free to change this using the `interval` keyword argument in `job_monitor`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-21T18:32:41.652063Z",
     "start_time": "2018-12-21T18:09:28.381370Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Job Status: job has successfully run\n"
     ]
    }
   ],
   "source": [
    "job2 = execute(qc, backend)\n",
    "job_monitor(job2, interval=5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Backend Details"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far we have been executing our jobs on a backend, but we have explored the backends in any detail.  For example, we have found the least busy backend, but do not know if this is the best backend with respect to gate errors, topology etc.  It is possible to get detailed information for a single backend by calling `backend_monitor`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-22T08:57:27.524373Z",
     "start_time": "2018-12-22T08:57:25.677025Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ibmq_16_melbourne\n",
      "=================\n",
      "Configuration\n",
      "-------------\n",
      "    n_qubits: 14\n",
      "    operational: True\n",
      "    status_msg: active\n",
      "    pending_jobs: 0\n",
      "    basis_gates: ['u1', 'u2', 'u3', 'cx', 'id']\n",
      "    local: False\n",
      "    simulator: False\n",
      "    max_shots: 8192\n",
      "    description: 14 qubit device\n",
      "    max_experiments: 75\n",
      "    online_date: 2018-11-06T05:00:00+00:00\n",
      "    url: None\n",
      "    backend_version: 1.0.0\n",
      "    credits_required: True\n",
      "    memory: False\n",
      "    conditional: False\n",
      "    open_pulse: False\n",
      "    sample_name: albatross\n",
      "    coupling_map: [[1, 0], [1, 2], [2, 3], [4, 3], [4, 10], [5, 4], [5, 6], [5, 9], [6, 8], [7, 8], [9, 8], [9, 10], [11, 3], [11, 10], [11, 12], [12, 2], [13, 1], [13, 12]]\n",
      "    n_registers: 1\n",
      "    backend_name: ibmq_16_melbourne\n",
      "    allow_q_object: True\n",
      "\n",
      "Qubits [Name / Freq / T1 / T2 / U1 err / U2 err / U3 err / Readout err]\n",
      "-----------------------------------------------------------------------\n",
      "    Q0 / 5.10005 GHz / 67.38168 µs / 20.8927 µs / 0.0 / 0.00157 / 0.00313 / 0.0447\n",
      "    Q1 / 5.23867 GHz / 38.11844 µs / 72.55859 µs / 0.0 / 0.00556 / 0.01111 / 0.0397\n",
      "    Q2 / 5.03294 GHz / 45.8347 µs / 96.1172 µs / 0.0 / 0.00311 / 0.00622 / 0.0731\n",
      "    Q3 / 4.89617 GHz / 89.39497 µs / 84.33097 µs / 0.0 / 0.00101 / 0.00202 / 0.0618\n",
      "    Q4 / 5.02726 GHz / 53.93443 µs / 35.28576 µs / 0.0 / 0.00156 / 0.00313 / 0.0335\n",
      "    Q5 / 5.06715 GHz / 24.14202 µs / 45.93013 µs / 0.0 / 0.00209 / 0.00418 / 0.0402\n",
      "    Q6 / 4.92381 GHz / 64.313 µs / 46.5611 µs / 0.0 / 0.00158 / 0.00317 / 0.1202\n",
      "    Q7 / 4.97447 GHz / 47.12427 µs / 80.09072 µs / 0.0 / 0.0019 / 0.00381 / 0.1033\n",
      "    Q8 / 4.73979 GHz / 59.53633 µs / 76.3004 µs / 0.0 / 0.00239 / 0.00477 / 0.0579\n",
      "    Q9 / 4.96337 GHz / 45.71424 µs / 75.46827 µs / 0.0 / 0.00397 / 0.00794 / 0.1086\n",
      "    Q10 / 4.94505 GHz / 55.13212 µs / 56.69945 µs / 0.0 / 0.00185 / 0.0037 / 0.065\n",
      "    Q11 / 5.00527 GHz / 61.25009 µs / 101.05622 µs / 0.0 / 0.00181 / 0.00362 / 0.0816\n",
      "    Q12 / 4.76015 GHz / 96.01526 µs / 143.34551 µs / 0.0 / 0.00332 / 0.00663 / 0.1608\n",
      "    Q13 / 4.96847 GHz / 22.97295 µs / 39.88249 µs / 0.0 / 0.00524 / 0.01047 / 0.0493\n",
      "\n",
      "Multi-Qubit Gates [Name / Type / Gate Error]\n",
      "--------------------------------------------\n",
      "    CX1_0 / cx / 0.04706\n",
      "    CX1_2 / cx / 0.04913\n",
      "    CX2_3 / cx / 0.04437\n",
      "    CX4_3 / cx / 0.03565\n",
      "    CX4_10 / cx / 0.04076\n",
      "    CX5_4 / cx / 0.04962\n",
      "    CX5_6 / cx / 0.05647\n",
      "    CX5_9 / cx / 0.04919\n",
      "    CX6_8 / cx / 0.04215\n",
      "    CX7_8 / cx / 0.03156\n",
      "    CX9_8 / cx / 0.04416\n",
      "    CX9_10 / cx / 0.0493\n",
      "    CX11_3 / cx / 0.02672\n",
      "    CX11_10 / cx / 0.03757\n",
      "    CX11_12 / cx / 0.03782\n",
      "    CX12_2 / cx / 0.07713\n",
      "    CX13_1 / cx / 0.15178\n",
      "    CX13_12 / cx / 0.03901\n"
     ]
    }
   ],
   "source": [
    "backend_monitor(backend)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, if we are interested in a higher-level view of all the backends available to us, then we can use `backend_overview()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2018-12-22T08:57:37.557523Z",
     "start_time": "2018-12-22T08:57:31.725745Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ibmq_16_melbourne           ibmqx4\n",
      "-----------------           ------\n",
      "Num. Qubits:  14            Num. Qubits:  5\n",
      "Pending Jobs: 0             Pending Jobs: 40\n",
      "Least busy:   True          Least busy:   False\n",
      "Operational:  True          Operational:  True\n",
      "Avg. T1:      55.1          Avg. T1:      50.9\n",
      "Avg. T2:      69.6          Avg. T2:      25.3\n",
      "\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "backend_overview()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also Jupyter magic equivalents that give more detailed information, as demonstrated here: [Jupyter tools for Monitoring jobs and backends](../jupyter/jupyter_backend_tools.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}