{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Readout Calibration (RCAL)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This example illustrates how to generate readout calibration (:tqdoc:`RCAL`\\) circuits\nand use them to correct readout errors in other circuits. While this example uses a\n:doc:`simulator<../../guides/run/simulator>` to execute the circuits, the same\nprocedure can be followed for hardware applications.\n\nThe code below generates RCAL circuits for qubits ``0`` and ``1``, populates their\nresults using a simulator with readout error, and displays their confusion matrices.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import trueq as tq\n\n# generate RCAL circuits to measure the readout errors on qubits [0, 1]\ncircuits = tq.make_rcal([0, 1])\n\n# initialize a simulator with a 20% readout error on every qubit\nsim = tq.Simulator().add_readout_error(0.2)\n\n# run the circuits on the simulator to populate their results\nsim.run(circuits, n_shots=1000)\n\n# display the confusion matrices\ncircuits.fit()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Automatic Correction\n\nIf your circuit collection contains RCAL circuits, then that information will be\nused automatically to apply readout correction to your circuits when you call\n:py:meth:`~trueq.CircuitCollection.fit` or :py:meth:`~trueq.CircuitCollection.plot`\\.\nThe code below illustrates this for :tqdoc:`SRB` circuits executed on a noisy\nsimulator with readout error. It also shows how you can view the results with and\nwithout readout correction being applied.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# generate RCAL circuits to measure the readout errors on qubits [0, 1, 2]\ncircuits = tq.make_rcal([0, 1, 2])\n\n# generate SRB circuits to simultaneously characterize a single qubit [0] and\n# a pair of qubits [1, 2] with 30 circuits for each random cycle in [4, 32, 64]\ncircuits.append(tq.make_srb([[0], [1, 2]], [4, 32, 64], 30))\n\n# initialize a noisy simulator with a large 10% readout error\nsim = tq.Simulator().add_stochastic_pauli(px=0.01).add_readout_error(0.1)\n\n# RCAL generally needs more shots than the other protocols because it is estimating\n# an absolute value rather than a decay over randomizations, thus in this simulation\n# we use different amounts of shots for SRB and RCAL to populate their results\nsim.run(circuits.subset(protocol=[\"RCAL\"]), n_shots=50)\nsim.run(circuits.subset(protocol=\"RCAL\"), n_shots=1000)\n\n# plot the exponential decay with readout correction,\n# where each expectation value (dot) has been compensated\ncircuits.plot.raw()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "To avoid performing readout correction during analysis, we can remove all RCAL\ncircuits from the collection before calling :py:meth:`~trueq.CircuitCollection.plot`\\.\nNotice that the y-intercept is lower than in the plot above.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# plot the exponential decay without readout correction\ncircuits.subset(protocol=\"SRB\").plot.raw()"
      ]
    }
  ],
  "metadata": {
    "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.11"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}