{"cells":[{"cell_type":"markdown","metadata":{},"source":["# Calibration and correction of state preparation and measurement (SPAM)\n","\n","**Download this notebook - {nb-download}`spam_example.ipynb`**"]},{"cell_type":"markdown","metadata":{},"source":["Quantum Computers available in the NISQ-era are limited by significant sources of device noise which cause errors in computation. One such noise source is errors in the preparation and measurement of quantum states, more commonly know as SPAM.<br>\n","<br>\n","If device SPAM error can be characterised, then device results can be modified to mitigate the error. Characterisation proceeds by determining overlap between different prepared basis states when measured, and mitigation modifies the distribution over output states of the corrected circuit. No modification of the quantum circuit being corrected is required. The ``` pytket```  ```SpamCorrecter```  class supports characterisation and mitigation of device SPAM error.<br>\n","<br>\n","In this tutorial we will show how the ```SpamCorrecter```  class can be used to modify real results and improve device performance when running experiments.<br>\n","<br>\n","This tutorial will require installation of ```pytket```, ```pytket_qiskit``` and ```qiskit```, all available on pip.<br>\n","<br>\n","First, import the ```SpamCorrecter``` class."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from pytket.utils.spam import SpamCorrecter"]},{"cell_type":"markdown","metadata":{},"source":["The SpamCorrecter class has methods for generating State Preparation and Measurement (SPAM) calibration experiments for pytket backends and correcting counts generated from those same backends.<br>\n","<br>\n","Let's first mitigate error from a noisy simulation, using a noise model straight from the 5-qubit IBMQ manila device. This will require a preloaded IBMQ account."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from qiskit import IBMQ"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["IBMQ.load_account()"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from pytket.extensions.qiskit import process_characterisation"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ibmq_manila_backend = IBMQ.providers()[0].get_backend(\"ibmq_manila\")\n","pytket_manila_characterisation = process_characterisation(ibmq_manila_backend)\n","pytket_manila_architecture = pytket_manila_characterisation[\"Architecture\"]"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["import networkx as nx\n","import matplotlib.pyplot as plt"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["manila_graph = nx.Graph(pytket_manila_architecture.coupling)\n","nx.draw(manila_graph, labels={node: node for node in manila_graph.nodes()})"]},{"cell_type":"markdown","metadata":{},"source":["SPAM correction requires subsets of qubits which are assumed to only have SPAM errors correlated with each other, and no other qubits.<br>\n","<br>\n","Correlated errors are usually dependent on the connectivity layout of devices, as shown above.<br>\n","<br>\n","As manila is a small 5-qubit device with few connections, let's assume that all qubits have correlated SPAM errors. The number of calibration circuits produced is exponential in the maximum number of correlated circuits, so finding good subsets of correlated qubits is important for characterising larger devices with smaller experimental overhead.<br>\n","<br>\n","We can produce an ```IBMQEmulatorBackend``` to run this. This uses a noise model from ```ibmq_manila``` produced using qiskit-aer. We can then execute all calibration circuits through the backend."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from pytket.extensions.qiskit import IBMQEmulatorBackend, AerBackend"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["n_shots = 8192\n","pytket_noisy_sim_backend = IBMQEmulatorBackend(\"ibmq_manila\")\n","manila_node_subsets = pytket_noisy_sim_backend.backend_info.architecture.nodes\n","manila_spam = SpamCorrecter([manila_node_subsets], pytket_noisy_sim_backend)"]},{"cell_type":"markdown","metadata":{},"source":["The SpamCorrecter uses these subsets of qubits to produce calibration circuits."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["calibration_circuits = manila_spam.calibration_circuits()\n","print(\"Number of calibration circuits: \", len(calibration_circuits))"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["sim_handles = pytket_noisy_sim_backend.process_circuits(calibration_circuits, n_shots)"]},{"cell_type":"markdown","metadata":{},"source":["Count results from the simulator are then used to calculate the matrices used for SPAM correction for ```ibmq_manila```."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["sim_count_results = pytket_noisy_sim_backend.get_results(sim_handles)\n","manila_spam.calculate_matrices(sim_count_results)"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from pytket import Circuit"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ghz_circuit = (\n","    Circuit(len(pytket_noisy_sim_backend.backend_info.architecture.nodes))\n","    .H(0)\n","    .CX(0, 1)\n","    .CX(1, 2)\n","    .measure_all()\n",")\n","ghz_circuit = pytket_noisy_sim_backend.get_compiled_circuit(ghz_circuit)\n","ghz_noisy_handle = pytket_noisy_sim_backend.process_circuit(ghz_circuit, n_shots)\n","ghz_noisy_result = pytket_noisy_sim_backend.get_result(ghz_noisy_handle)"]},{"cell_type":"markdown","metadata":{},"source":["We also run a noiseless simulation so we can compare performance."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["pytket_noiseless_sim_backend = AerBackend()\n","ghz_noiseless_handle = pytket_noiseless_sim_backend.process_circuit(\n","    ghz_circuit, n_shots\n",")\n","ghz_noiseless_result = pytket_noiseless_sim_backend.get_result(ghz_noiseless_handle)"]},{"cell_type":"markdown","metadata":{},"source":["Noisy simulator counts are corrected using the ```SpamCorrecter``` objects ```correct_counts``` method.<br>\n","<br>\n","To correctly amend counts, the ```correct_counts``` method requires a ``ParallelMeasures`` type object, a list of ``Dict[Qubit, Bit]`` where each dictionary denotes a set of Qubit measured in parallel and the Bit their measured values are assigned to.<br>\n","<br>\n","The ``SpamCorrecter`` class has a helper method ``get_parallel_measure`` for retrieving this object for a Circuit."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ghz_parallel_measure = manila_spam.get_parallel_measure(ghz_circuit)"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ghz_spam_corrected_result = manila_spam.correct_counts(\n","    ghz_noisy_result, ghz_parallel_measure\n",")"]},{"cell_type":"markdown","metadata":{},"source":["Import and define the Jensen-Shannon divergence, which we will use for comparing performance. The Jensen-Shannon divergence is a symmetric and finite measure of similarity between two probability distributions. A smaller divergence implies more similarity between two probability distributions."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from scipy.stats import entropy\n","import numpy as np\n","import itertools"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["def binseq(k):\n","    return [\"\".join(x) for x in itertools.product(\"01\", repeat=k)]"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["def probs_from_counts(result):\n","    counts = result.get_counts()\n","    counts_dict = dict()\n","    for x in counts:\n","        counts_dict[\"\".join(str(e) for e in x)] = counts[x]\n","    converted = []\n","    binary_strings = binseq(len(list(counts.keys())[0]))\n","    for b in binary_strings:\n","        converted.append(counts_dict.get(b, 0))\n","    return converted / np.sum(converted)"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["def JSD(P, Q):\n","    _P = P / np.linalg.norm(P, ord=1)\n","    _Q = Q / np.linalg.norm(Q, ord=1)\n","    _M = 0.5 * (_P + _Q)\n","    return 0.5 * (entropy(_P, _M) + entropy(_Q, _M))"]},{"cell_type":"markdown","metadata":{},"source":["Convert our counts results to a probability distribution over the basis states for comparison."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ghz_noiseless_probabilities = probs_from_counts(ghz_noiseless_result)\n","ghz_noisy_probabilities = probs_from_counts(ghz_noisy_result)\n","ghz_spam_corrected_probabilities = probs_from_counts(ghz_spam_corrected_result)"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["print(\n","    \"Jensen-Shannon Divergence between noiseless simulation probability distribution and noisy simulation probability distribution: \",\n","    JSD(ghz_noiseless_probabilities, ghz_noisy_probabilities),\n",")\n","print(\n","    \"Jensen-Shannon Divergence between noiseless simulation probability distribution and spam corrected noisy simulation probability distribution: \",\n","    JSD(ghz_noiseless_probabilities, ghz_spam_corrected_probabilities),\n",")"]},{"cell_type":"markdown","metadata":{},"source":["In our noisy simulated case, spam corrected results produced a distribution closer to the expected distribution.<br>\n","<br>\n","There are two methods available for correcting counts: the default ```bayesian```, and ```invert```. Further information on each method is available at our [documentation](https://cqcl.github.io/tket/pytket/api/utils.html#module-pytket.utils.spam).<br>\n","<br>\n","Let's look at how the ```invert``` method performs."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ghz_invert_corrected_result = manila_spam.correct_counts(\n","    ghz_noisy_result, ghz_parallel_measure, method=\"invert\"\n",")\n","ghz_invert_probabilities = probs_from_counts(ghz_invert_corrected_result)"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["print(\n","    \"Jensen-Shannon Divergence between noiseless simulation probability distribution and Bayesian-corrected noisy simulation probability distribution: \",\n","    JSD(ghz_noiseless_probabilities, ghz_spam_corrected_probabilities),\n",")\n","print(\n","    \"Jensen-Shannon Divergence between noiseless simulation probability distribution and invert-corrected noisy simulation probability distribution: \",\n","    JSD(ghz_noiseless_probabilities, ghz_invert_probabilities),\n",")"]},{"cell_type":"markdown","metadata":{},"source":["To see how SPAM correction performs on results from a real IBMQ quantum device, try replacing `IBMQEmulatorBackend` with `IBMQBackend`."]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["from pytket.extensions.qiskit import IBMQBackend"]},{"cell_type":"code","execution_count":null,"metadata":{},"outputs":[],"source":["ibm_backend = IBMQBackend(\"ibmq_manila\")"]}],"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.6.4"}},"nbformat":4,"nbformat_minor":2}