diff --git a/terra/qis_adv/two_approaches_to_implement_povms.ipynb b/terra/qis_adv/two_approaches_to_implement_povms.ipynb new file mode 100644 index 0000000..e5366ca --- /dev/null +++ b/terra/qis_adv/two_approaches_to_implement_povms.ipynb @@ -0,0 +1,1604 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Implementing generalized measurements with mid-circuit measurements\n", + "\n", + "**Contributors:** Alireza Seif, Derek Wang, Gideon Uchehara, Peter Ivashkov\n", + "\n", + "## Introduction \n", + "\n", + "Implementing generalized measurements in the form of positive operator valued measurements (POVM) is non-trivial, and to this end, several methods have been proposed. To compare contrasting approaches, we focus on two methods: Naimark's extension and the binary tree search methods, which significantly differ in terms of their scaling with the size of the POVM set and the hardware resources necessary to implement them.\n", + "\n", + "In this tutorial, we first introduce the theory behind generalized measurements and show how they can be implemented in Qiskit using Naimark's extension. After that, we demonstrate the implementation of the binary search tree approach using the protocol described by [Andersson and Oi](https://arxiv.org/abs/0712.2665) for a tetrad POVM using a single auxiliary qubit, thus demonstrating a promising application of mid-circuit measurements and feed-forward capabilities of near-term quantum devices." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Defining classes and functions \n", + "\n", + "To be able to follow this notebook, please first go to the [implementation section](#implementation) and execute two cells containing Python implementations of binary search and Naimark's algorithms. These sections define necessary classes and functions that will be used later in the notebook. After that, you can return to this section and continue with the notebook." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Understanding generalized measurements \n", + "\n", + "Generalized measurement or [POVM](https://en.wikipedia.org/wiki/POVM) is the most general kind of measurement in quantum mechanics. Formally, POVM is a set of measurement operators $\\{ M_a\\}$ which are Hermitian ($M_a^\\dagger = M_a$), positive ($\\bra{\\psi} M_a \\ket{\\psi} \\ge 0$), and complete ($\\sum_a M_a = I$). However, notice that POVM operators are, in general, not orthogonal projectors, i.e., $M_i M_j \\neq \\delta_{ij} M_i$, in contrast to standard projective measurements. The probability of measuring outcome $a$ of the POVM is given by Born's rule as $p(a) = Tr(\\rho M_a)$. Finally, the post-measurement state upon getting an outcome $M_a$ is $\\rho_{post} = \\frac{m_a \\rho m_a^\\dagger}{Tr(\\rho M_a)}$, where $m_a$ are the coresponding Kraus operators, i.e., $m_a^\\dagger m_a = M_a$.\n", + "\n", + "POVMs are, in fact, a generalization of projective measurements. They can be implemented by performing a projective measurement on the joint state of the system of interest coupled to an auxiliary system by a suitable unitary operation. POVMs are extensively used in quantum information processing. For instance, with POVMs, one can perform unambiguous state discrimination. The focus of this tutorial is the efficient implementation of POVMs." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Tetrad POVM: proof of concept \n", + "First, let's examine our POVM of interest - the tetrad POVM. This POVM is a symmetric informationally complete POVM (SIC-POVM) on a single qubit. Tetrad POVM has four elements $\\{ M_i = \\ket{\\psi_i}\\bra{\\psi_i} \\}_{i=0}^3$, where $\\ket{\\psi_i}$ are given as follows:\n", + "\n", + "$$\\ket{\\psi_0} = \\frac{1}{\\sqrt{2}}\\ket{0}$$\n", + "\n", + "$$\\ket{\\psi_1} = \\frac{1}{\\sqrt{6}}(\\ket{0} + \\sqrt{2}e^{2\\pi i/3}\\ket{1})$$\n", + "\n", + "$$\\ket{\\psi_2} = \\frac{1}{\\sqrt{6}}\\ket{0} + \\sqrt{2}e^{4\\pi i/3}\\ket{1})$$\n", + "\n", + "$$\\ket{\\psi_3} = \\frac{1}{\\sqrt{6}}(\\ket{0} + \\sqrt{2}\\ket{1})$$\n", + "\n", + "One can implement this POVM using Neumark's extension with a single auxiliary qubit and one projective measurement. Therefore, we wouldn't expect the binary tree approach to provide any improvement in terms of required ancilla qubits. We will nevertheless use this simple case POVM to demonstrate both algorithms.\n", + "\n", + "One can easily verify that this POVM satisfies the requirements for a [SIC-POVM](https://en.wikipedia.org/wiki/SIC-POVM). The state vectors can be represented on the Bloch sphere:\n", + "\n", + "![tetrad_povm](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/tetrad_povm.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's define our POVM and the initial state of the system. Note that in our case, we have chosen the initial state to be $\\ket{0}$ for simplicity. The implementation, however, works for any other initial state. We refer to POVM as a list of its measurement operators." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "from cmath import pi, sqrt, exp\n", + "\n", + "# Define the set of vectors on the Bloch sphere\n", + "psi_0 = np.array([[1/sqrt(2)],[0]])\n", + "psi_1 = np.array([[1],[sqrt(2)*exp(2j*pi/3)]])/sqrt(6)\n", + "psi_2 = np.array([[1],[sqrt(2)*exp(4j*pi/3)]])/sqrt(6)\n", + "psi_3 = np.array([[1],[sqrt(2)]])/sqrt(6)\n", + "\n", + "# POVM elements are given as M_i = |psi_i>\n", + "state = np.array([[1, 0]])\n", + "state = state/np.linalg.norm(state)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Naimark's extension \n", + "\n", + "Naimark's extension theory provides the path to implement generalized POVM measurement using projective von Neumann measurements by enlarging the Hilbert space of the measured system with an auxiliary quantum system, as shown in the figure below: \n", + "\n", + "![naimark_extension](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/naimarks_povm.PNG)\n", + "\n", + "In the above figure, an auxiliary system $\\ket{0}_B$ (also known as ancilla) is introduced to the system of interest $\\rho_A$. This is similar to bringing Bob to help Allice in measuring the POVM elements.\n", + "\n", + "More formally, for every POVM $\\{M_a\\}_{a \\in \\mathcal{A}}$, there exists an isometry U such that \n", + "\n", + "$$\n", + "\\begin{split}\n", + " M_a &= U^\\dagger \\left( \\mathcal{I} \\otimes \\ket{a}\\bra{a} \\right) U \\; \\forall \\; a \\in \\mathcal{A}.\n", + " %\\label{eq1}\n", + "\\end{split}\n", + "$$\n", + "\n", + "By implication, the isometry, $U$ can be defined as\n", + "\n", + "$$U = \\sum_{a \\in \\mathcal{A}} M_a \\otimes \\ket{a}$$" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The following section will show how to construct Naimark's extension circuit and measure the tetrad POVM using a single auxiliary qubit and one projective measurement." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Constructing Naimark's extension circuit" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Given the POVM and the initial state of the system of interest, we can construct the circuit for Naimark's extension using the function `construct_quantum_circuit()`. Considering that the isometry (unitary), $U$ is at the heart of Naimark's extension implementation, we created two functions, `compute_rank_one_unitary()` and `compute_full_rank_unitary()`, to construct the unitary for a rank-1 and non-rank-1 POVMs respectively. The function, `construct_quantum_circuit()` checks for the rank of the given POVM and creates the Naimark's extension circuit using the functions `rank_one_circuit()` and `full_rank_circuit()` for rank-1 and non-rank-1 POVMs respectively. \n", + "\n", + "To implement this in Qiskit, let's import the relevant libraries." + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [], + "source": [ + "# Naimark's quantum circuit for the tetrad POVM and state |0>\n", + "qc = construct_quantum_circuit(povm, state)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's visualize this circuit:" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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", + "text/plain": [ + "
" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "qc.draw(\"mpl\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Our next step would be to run the Naimark's circuit. We will defer the theoretical and simulated results for this circuit to when we have obtained the hardware result." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's get the backends assoicated with our account" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit import IBMQ\n", + "\n", + "# Load account and get backends\n", + "IBMQ.load_account()\n", + "provider = IBMQ.get_provider(hub='ibm-q', group='open', project='main')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Selecting an optimal layout using mapomatic\n", + "\n", + "Since we have access to multiple quantum backends, we want to select an optimal backend and an optimal layout to execute our transpiled circuit. In the following, we will use `mapomatic`, which will be discussed in more detail in the [appendix](#appendix). " + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Backends with the corresponding optimal layouts in ascending order. First backend is optimal.\n", + "([1, 2], 'ibm_oslo', 0.048246822245851195)\n", + "([1, 0], 'ibmq_lima', 0.06473001465010009)\n", + "([4, 5], 'ibm_nairobi', 0.0734194177317139)\n" + ] + } + ], + "source": [ + "import mapomatic as mm\n", + "from qiskit import transpile\n", + "\n", + "backend = provider.get_backend('ibmq_lima')\n", + "transpiled_qc = transpile(qc, backend=backend, optimization_level=3)\n", + "small_qc = mm.deflate_circuit(transpiled_qc)\n", + "\n", + "# Note: evaluating all available backends might block your environment for a long period\n", + "backends = [provider.get_backend('ibmq_lima'), provider.get_backend('ibm_nairobi'), provider.get_backend('ibm_oslo')]\n", + "\n", + "scores = mm.best_overall_layout(small_qc, backends, successors=True)\n", + "print(\"Backends with the corresponding optimal layouts in ascending order. First backend is optimal.\")\n", + "for score in scores: print(score)\n", + "\n", + "initial_layout = scores[0][0]" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit import transpile\n", + "trans_qc = transpile(qc, backend=backend, initial_layout=initial_layout, optimization_level=3)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's visualize our Naimark's circuit transpiled for the best backend and initial layout found with `mapomatic`." + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "iVBORw0KGgoAAAANSUhEUgAABaIAAAD7CAYAAACYJONmAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy89olMNAAAACXBIWXMAAA9hAAAPYQGoP6dpAAByk0lEQVR4nO3dd3RU1drH8e+kk0AIIUBCqAktBJBewwUUEJBiAQEVRFSsV8ACoqjgi1jRiygKNvDaELAgIlIERFSK9Kb0kEBoIUAS0uf9Y24GQtpMMiWT+X3WyoI59ZnskjPP7LOPwWg0GhERERERERERERERsRMPZwcgIiIiIiIiIiIiIuWbEtEiIiIiIiIiIiIiYldKRIuIiIiIiIiIiIiIXSkRLSIiIiIiIiIiIiJ2pUS0iIiIiIiIiIiIiNiVEtEiIiIiIiIiIiIiYldKRIuIiIiIiIiIiIiIXSkRLSIiIiIiIiIiIiJ2pUS0iIiIiIiIiIiIiNiVEtEiIiIiIiIiIiIiYldKRIuIiIiIiIiIiIiIXdktEd29e3fGjRtn933K6jFERERERERERERExKREieiEhATGjh1LgwYN8PPzo0aNGnTp0oX33nuP1NRUW8doU6NGjcJgMGAwGPDx8aFBgwa8+OKLZGVlOTs0q9WrV8/8Xq7+eeSRR6w+1j333MPkyZPzLX/llVcwGAxKzIuIiIiIiIiIiEiJeVm7w+HDh+nSpQtBQUFMnz6d5s2b4+vry65du5g7dy7h4eEMHDjQHrHaTJ8+ffjkk09IT09n2bJlPPLII3h7ezNp0iRnh2aVzZs3k52dbX69e/duevXqxZAhQ6w6TnZ2NkuXLuXHH3/Md/w5c+bQokULm8QrIiIiIiIiIiIi7snqEdEPP/wwXl5ebNmyhdtvv52oqCgiIiIYNGgQP/74IwMGDChwv/T0dB577DGqV6+On58fMTExbN68Od92WVlZPProo1SuXJmQkBCee+45jEYjAMuXLycmJoagoCCqVq1K//79OXTokLVvAV9fX0JDQ6lbty4PPfQQPXv2ZMmSJXm2ycnJYcKECQQHBxMaGsqUKVPM6yyJY9GiRTRv3pwKFSpQtWpVevbsSUpKivnYL7/8MvXr16dChQpcd911LFq0yOr3Ua1aNUJDQ80/S5cuJTIykm7dupm3iYqKKnDUtMFg4J133gHg999/x9vbm3bt2pn3S05O5s477+SDDz6gSpUqVscmIiIiIiIiIiIiksuqRPS5c+dYsWIFjzzyCAEBAQVuYzAYClw+YcIEFi9ezPz589m6dSsNGjTgxhtvJDExMc928+fPx8vLi02bNjFz5kzefPNNPvzwQwBSUlJ4/PHH2bJlC6tXr8bDw4NbbrmFnJwca95GPhUqVCAjIyNfHAEBAWzcuJHXXnuNF198kZUrV1oUx8mTJxk+fDijR49m3759rF27lltvvdWcUH/55Zf59NNPef/999mzZw/jx4/nrrvuYt26debzz5s3r9DfZUEyMjL47LPPGD16dJ79Fi9eDMDq1as5efIkR48excPDg4ULF3L//fcDsGTJEgYMGJBnv0ceeYSbbrqJnj17WvOrFBEREREREREREcnHqqk5Dh48iNFopHHjxnmWh4SEkJaWBpgSmK+++mqe9SkpKbz33nvMmzePvn37AvDBBx+wcuVKPvroI5566inztrVr1+att97CYDDQuHFjdu3axVtvvcX999/Pbbfdlue4H3/8MdWqVWPv3r00a9bMmrcCgNFoZPXq1fz888/8+9//zrOuRYsWvPDCCwA0bNiQd955h9WrV9OrV69i4zh58iRZWVnceuut1K1bF4DmzZsDppHh06dPZ9WqVXTq1AmAiIgIfvvtN+bMmWMezVy5cuV8v+eifPfddyQlJTFq1Kg8y0+dOoWXlxddunTB19eXv/76i5ycHLp27Yqvry8A33//PW+99ZZ5n6+++oqtW7cWOGJdRERERERERERExFoleljhtTZt2sT27duJjo4mPT093/pDhw6RmZlJly5dzMu8vb1p3749+/bty7Ntx44d84zM7dSpEwcOHCA7O5sDBw4wfPhwIiIiCAwMpF69egDExsZaFe/SpUupWLEifn5+9O3bl6FDh+aZegPINy9yWFgYp0+fBig2juuuu44bbriB5s2bM2TIED744APOnz8PmJL5qamp9OrVi4oVK5p/Pv300zzTe9xyyy3s37/f4vf00Ucf0bdvX2rWrJln+a5du2jUqJE56bxjxw6qV69OjRo1ANi3bx8nTpzghhtuAOD48eOMHTuWzz//HD8/P4vPLyIiIiIiIiIiIlIYq0ZEN2jQAIPBwN9//51neUREBGCa4sKeBgwYQN26dfnggw+oWbMmOTk5NGvWLN+0GsXp0aMH7733Hj4+PtSsWRMvr/y/Bm9v7zyvDQaDeeqN4uLw9PRk5cqV/P7776xYsYJZs2bx7LPPsnHjRpKTkwH48ccfCQ8Pz3OO3GSxtY4dO8aqVav45ptv8q3buXOneTQ2mBLRV79esmQJvXr1Mied//rrL06fPk3r1q3N22RnZ/Prr7/yzjvvkJ6ejqenZ4niFBEREREREREREfdk1YjoqlWr0qtXL9555x3zg/csERkZiY+PDxs2bDAvy8zMZPPmzTRt2jTPths3bszz+s8//6Rhw4YkJSXx999/M3nyZG644QaioqLMo4ytFRAQQIMGDahTp06BSeiinDt3zqI4DAYDXbp0YerUqWzbtg0fHx++/fZbmjZtiq+vL7GxsTRo0CDPT+3atUv0fj755BOqV6/OTTfdlG/dzp0784zu3rFjR57X33//PYMGDTK/vuGGG9i1axfbt283/7Rt25Y777yT7du3KwktIiIiIiIiIiIiVrMuCwvMnj2bLl260LZtW6ZMmUKLFi3w8PBg8+bN7N+/nzZt2uTbJyAggIceeoinnnqK4OBg6tSpw2uvvUZqair33ntvnm1jY2N5/PHHeeCBB9i6dSuzZs1ixowZVKlShapVqzJ37lzCwsKIjY3l6aefLvk7LyFL4ti4cSOrV6+md+/eVK9enY0bN3LmzBmioqKoVKkSTz75JOPHjycnJ4eYmBguXLjAhg0bCAwM5O677wbg22+/ZdKkScVOz5GTk8Mnn3zC3XffnS+pnpOTw549e3j++efNyw4dOsStt94KwOnTp9myZQtLliwxr69UqVK++bYDAgKoWrVqiebhFhEREREREREREbE6ER0ZGcm2bduYPn06kyZNIi4uDl9fX5o2bcqTTz7Jww8/XOB+r7zyCjk5OYwYMYJLly7Rtm1bfv75Z6pUqZJnu5EjR3L58mXat2+Pp6cnY8eOZcyYMRgMBr766isee+wxmjVrRuPGjXn77bfp3r17id54SXl4eBQbR2BgIL/++iv/+c9/uHjxInXr1mXGjBnmBzX+3//9H9WqVePll1/m8OHDBAUF0bp1a5555hnzMS5cuJBvCpSCrFq1itjYWEaPHp1v3aFDh0hNTc0zArp58+a88MILtGnThv3799O+fXtCQkJK8RsRERERERERERERKZrBaDQanR2EOMfAgQOJiYlhwoQJzg5FREREREREREREyjGr5oiW8iUmJobhw4c7OwwREREREREREREp5zQiWkRERERERERERETsSiOiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7MrL2QGIiIiIiIiIiIiUZ/v377dq+9OnT/P1119z++23U716dYv2adKkSUlCE3EYjYgWEREREREREREpQ86cOcO7777LmTNnnB2KiM0oES0iIiIiIiIiIiIidqVEtIiIiIiIiIiIiIjYlRLRIiIiIiIiIiIiImJXSkSLiIiIiIiIiIiUIZUrV2bAgAFUrlzZ2aGI2IzBaDQanR2EiIiIiIiIiIhIebV//367n6NJkyZ2P4dIaWhEtIiIiIiIiIiISBmSnp7OsWPHSE9Pd3YoIjajRLSIiIiIiIiIiEgZcvDgQfr06cPBgwedHYqIzSgRLSIiIiIiIiIiIiJ25eXsAERcmdEIOZnOjsI6Ht5gMNjmWEYjZGTb5liO4uNpm/fvimV/NVvVA3euA+Ca9cCWfYC7c8Xyz6V6ILbiiu1A9d+23L0OuPu1EKgOqA64Xh3Q3wHbMhqNpKamOjsMq/j7+2NQJXAKJaJFSiEnE9a87eworNPjMfD0sc2xMrJh4gLbHMtRXh0Kvjbo+Vyx7K9mq3rgznUAXLMe2LIPcHeuWP65VA/EVlyxHaj+25a71wF3vxYC1QHVAderA/o7YFupqalUrFjR2WFYJTk5mYCAAGeH4ZY0NYeIiIiIiIiIiIiI2JVGRIuIiIiIiIiIiJQh0dHR7Nu3z9lhiNiURkSLiIiIiIiIiIiIiF0pES0iIiIiIiIiIlKGHDlyhGHDhnHkyBFnhyJiM5qaQ0RERMqE1HQ4ngiJKZCVDR4eUNEXwqtA1Yp6urmUf+mZEH8ezlyCjCzwMEAFH6hZBapXMrUJKd8upUFcIiSlmvpBTw+o5Ae1giHIX/2giIg7SU1N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4LquzW+la/NbbROok1X2N/00+98z2/b/rx/084aWls9k4lKsuR4uqs9LunSq2D5Tyq6iyvba6+PC/rYV9XlJyjbrPhfPZdpnt5u/mHz0lnfMd0OUxzrg5+dHVFQUfn4ucAuMiIUMRqOx4E/EIlKs7AxY87azo7BOj8fA00ZzqqZnwcQFtjmWo7w61DSyqLRcseyvZqt64M51AFyzHtiyD7CnF74xJWAqV4CpZTTH5Irln8tV6oE7c4U2AK7ZDlyl/qsO2I+uh213LQSqA6oDrlcHnPV3YP/+/XY/R5Mmjr8TLiUlhYoVKzr8vKWRnJxMQECAs8NwSy54c5+IiIiIiIiIiIiIuBIlokVERERERERERMqQvXv30qJFC/bu3evsUERsRoloERERERERERGRMsRoNJKZmYlm1JXyRIloEREREREREREREbErG05PL+J+PLxNDzpwJR7etjuWj6fpQReuxMfTNsdxxbK/mq3qgTvXAXDNemDLPsDduWL551I9EFtxxXag+m9b7l4H3P1aCFQHVAdcrw7o74Bt+fv7k5ycbLPjvT7nKy6mpBIY4M9TDwzL99oW/P39bXIcsZ4S0SKlYDC4xlPX7cVgsO3Tll2Ju5d9LneuA6B64O5U/iJqB6I64O7XQqA6oDqgOuDuDAYDAQEBNjuej68fPpnZ+Pj6ERAQkO+1uDY37y5FRERERERERETKlsjISJYsWULt2rWdHYqIzSgRLSIiIiIiIiIiUob4+fnRsGFDZ4chYlN6WKGIiIiIiIiIiEgZEh8fz+TJk4mPj3d2KCI2o0S0iIiIiIiIiIhIGZKUlMTixYtJSkpydigiNqNEtIiIiIiIiIiIiIjYlRLRIiIiIiIiIiIiImJXSkSLiIiIiIiIiIiIiF0pES0iIiIiIiIiIlKGhISEcP/99xMSEuLsUERsRoloERERERERERGRMsRgMODj44PBYHB2KCI2o0S0iIiIiIiIiIhIGXLmzBneffddzpw54+xQRGxGiWgRERERERERERERsSslokVERERERERERETErpSIFhERERERERERERG7UiJaRERERERERESkDKlcuTIDBgygcuXKzg5FxGa8nB2AiIiIiIiIiIiIXFGrVi1ee+01Z4chYlMaES0iIiIiIiIiIlKGpKenc+zYMdLT050diojNKBEtIiIiIiIiIiJShhw8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n6ceGJbvtS34+/tjcMIFkR5WKFIKBgN4+jg7CucxGMDXzXsR1QH3rgPuXv6iNgBqB+5ObUDcvQ9w9zbg7uUP7l0HVP4iJgaDgYCAAJsdz8fXD5/MbHx8/QgICMj32pVpag4RERERERERERERsSs3/d5ORERERERERESkbIqMjGTJkiXUrl3b2aGI2IwS0SIiIiIiIiIiImWIn58fDRs2dHYYIjalqTlERERERERERETKkPj4eCZPnkx8fLyzQxGxGSWiRUREREREREREypCkpCQWL15MUlKSs0MRsRklokVERERERERERETErpSIFhERERERERERERG7UiJaREREREREREREROzKy9kBiIiIiIiIiIiIlGdNmjSxavvKlSvzwgsv0LlzZ8LCwuwUlYhjKREtIiIiIiIiIiJShoSFhTFlyhRnhyFiU5qaQ0RERERERERERETsSoloEREREREREREREbErJaJFRERERERERERExK6UiBYRERERERERERERu1IiWkRERERERERERETsSoloEREREREREREREbErJaJFRERERERERERExK6UiBYRERERERERERERu1IiWkRERERERERERETsSoloEREREREREREREbErJaJFRERERERERERExK6UiBax0Ouvv06nTp2oUqUKQUFBxMTEsHz5cmeHJSIiIiIiIiIihVi2bBktW7bE19eXevXq8eabbzo7JIf69ddfGTRoEHXr1sVgMDBt2jSnxaJEtIiFfvnlF0aPHs2aNWvYtGkTnTt3pn///mzYsMHZoYmIiIiIiIiIyDW2bNnCoEGD6Nu3L9u3b2fKlCk888wzvP/++84OzWGSk5Np2rQpr732GqGhoU6NxcupZxdxIT/99FOe16+99hrLly/nm2++oUuXLk6KSkRERERERERECvLmm2/Srl07Xn75ZQCioqLYs2cPr7zyCg8++KCTo3OMfv360a9fPwAmTpzo1Fg0IlqkhHJycrh48SIBAQHODkVERERERERERK6xYcMG+vTpk2dZnz59OHbsGHFxcU6Kyn1pRLRICU2fPp2kpCTGjBnj7FBERERERERERFxGdk4Oh46dyLc8Kzvb/O8/R+Lyvb5acFAlQqpULvI8J0+ezDcdRe7rkydPUqtWrRK/h9I6cfocySmX8y239Hfg5elBRJ2ajgnWRpSIFimB2bNn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02RlZRUa67lz58z/9/T0ZOzYsbz66qv07t2b1q1b07NnT2JiYujWrRuBgYGFHqc4lSpWKPG+oNHQIiIiIiIiIiJSvpUmf6ZEtJsKCAjItyx32g5L1l8tKSkJgL179xZ73tTUVPP/N2zYwJNPPomnpyfTpk1j0KBB1KtXj4CAAAwGAx9//DH33nuveYR0runTp1OrVi3effddtm7dytatW3nttdfw9fXljjvu4I033iA4OLjYWK5V0tsKAM4kJvHmhwsBePCugdQKrVbMHiIiIiIiIiIiIu5DiWgptYoVKwKwZMkSBgwYYPF+//3vfwF44oknePbZZ/Otv3ok9NU8PDx49NFHefTRR4mLi2P9+vWsXLmSr7/+mk8++YTjx4+zcuVKq99HaeaIvpyWjtFoxMvTk08XryjRMURERERERERERMoyzREtThUdHc327dvZvXu3VYnoI0eOABATE1Pg+j///LPYY9SqVYvhw4czfPhwnnjiCZo3b86qVas4cuQI9evXtzgWsM0c0ZobWkREREREREREJD8loqXUBg8ezOeff87cuXP597//bR4hXZwKFUxzyiQkJORbd+DAAZYuXWpVHNHR0VSuXJmkpCROnDhhdSK6pHPcXE5LJzMrS3NDi4iIiIiIiIhIuaY5osWpBg0aRLdu3Vi3bh29e/dm7ty5NGvWzLw+JyeHjRs3Mn/+fCZMmEBERAQAXbt25fvvv+fll1/m+uuvNz8gcc+ePdx22214eHjkO9fevXt56623uPfee+nQoYN53urs7GxmzZpFUlISfn5+REdHW/0+SnJbgeaGFhERERERERERKZ7BaDQanR2EOE5u4rawYi/p+rNnzzJo0CB+//13AOrWrUtoaCiXL1/m0KFDpKSYpqvYt28fTZo0AeDSpUu0bt2agwcP4u3tTePGjcnJyWHfvn2EhYXx8MMPM3nyZO6++27mzZsHwPbt22nVqhUAlSpVIjIyEk9PT44ePWqeU3r27Nk89NBDJfr9WGvB0jVs23OAqAZ1uPu2Pg45p4iIiIiIiIiIiKvJP+RUpARCQkJYt24d8+bNo1evXqSkpLBlyxaOHDlCgwYNGDt2LOvWraNRo0bmfSpVqsRvv/3G6NGjqVKlCn///TfJyck88MADbN26lfDw8HznadSoER9++CFDhw4lLCyMw4cPs2PHDvz8/BgyZAjr1693WBL6TGIS2/ceBOCGLm0cck4RERERERERERFXpBHRIiUUn3CW71asp2JABY2GFhERERERERERKYIS0SKlYDQaSc/IxM/Xx9mhiIiIiIiIiIiIlFlKRIuIiIiIiIiIiIiIXWmOaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbtSIlpERERERERERERE7EqJaBERERERERERERGxKyWiRURERERERERERMSulIgWEREREREREREREbv6fw0dVjNCaJBFAAAAAElFTkSuQmCC", + "text/plain": [ + "
" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "trans_qc.draw('mpl',idle_wires=False)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Simulating Naimark's circuit with the noise model of real backend\n", + "\n", + "Before running the Naimark's circuit on actual quantum hardware, we simulated it using the noise model of the best backend as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_aer.noise import NoiseModel\n", + "noise_model = NoiseModel.from_backend(backend)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For this simulation, we will use the `ibmq_qasm_simulator` and feed it with the noise model for our best backend." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n" + ] + } + ], + "source": [ + "from qiskit_ibm_runtime import QiskitRuntimeService\n", + "service = QiskitRuntimeService(channel='ibm_quantum')\n", + "# Simulator backend\n", + "simulator = service.backends(simulator=True)[0]\n", + "print(simulator)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To account for error mitigation, we will use the Qiskit runtime, `Sampler`. For details on this, please see the Sampler documentation." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Noisy Job ID: cev9hvkdo0fpfg2jpe20\n", + "Error mitigated Job ID: cev9i1p3v4f6ud9rn2ug\n" + ] + } + ], + "source": [ + "from qiskit_ibm_runtime import Sampler, Estimator, Session, Options\n", + "\n", + "# Set options to include noise_model only (noisy simulation)\n", + "options = Options(simulator={\n", + " \"noise_model\": noise_model,\n", + " \"seed_simulator\": 42,\n", + "}, resilience_level=0)\n", + "\n", + "# Set options to include noise_model and resilience_level (for error mitigation)\n", + "options_with_em = Options(\n", + " simulator={\n", + " \"noise_model\": noise_model,\n", + " \"seed_simulator\": 42,\n", + " }, \n", + " resilience_level=1\n", + ")\n", + "\n", + "with Session(service=service, backend=simulator):\n", + " sampler = Sampler(options=options)\n", + " noisy_job = sampler.run(circuits=[trans_qc])\n", + " print(f\"Noisy Job ID: {noisy_job.job_id()}\")\n", + " noisy_results = noisy_job.result()\n", + " \n", + " sampler = Sampler(options=options_with_em)\n", + " em_job = sampler.run(circuits=[trans_qc])\n", + " em_job = sampler.run(circuits=[trans_qc])\n", + " print(f\"Error mitigated Job ID: {em_job.job_id()}\")\n", + " em_results = em_job.result()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now that we have our results, let's visualize them." + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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EgNZIiIiItJIDGSJiIiISCMxkCUiIiIijcRAloiIiIg0EgNZIiIiItJIDGSJiIiISCMxkCUiIiIijcRAloiIiIg0EgNZIiIiItJIDGSJiIiISCMxkCUiIiIijcRAloiIiIg0EgNZIiIiItJIDGSJiIiISCMxkCUiIiIijcRAloiIiIg0EgNZIiIiItJIDGSJiIiISCMxkCUiIiIijcRAloiIiIg0EgNZIiIiItJIeQpkHz16hPDwcIW0GzduoH///ujVqxf27NmTl+KJiIiIiNTSzsvJI0aMQFJSEo4dOwYA+O+//9C8eXOkpaXBxMQEO3bsQEhICLp165YvlSUiIiIiypSnEdlLly6hdevW4usNGzYgJSUFN27cwNOnT9GyZUsEBgbmuZJERERERJ/KUyD7+vVrWFlZia/3798PNzc3ODo6QktLC926dcO9e/fyXEkiIiIiok/lKZC1tLRETEwMACA+Ph4XLlyAu7u7eFwmk0Emk+WthkREREREKuRpjmyrVq2waNEimJqa4tSpU5DL5ejSpYt4/M6dO7C1tc1rHYmIiIiIlOQpkP3tt99w//59jBkzBrq6uggMDES5cuUAAKmpqdi+fTv69u2bLxUlIiIiIvpYngLZkiVL4uzZs0hISICBgQF0dXXFY3K5HMePH+eILBEREREViDwFspnMzMyU0gwMDFCzZs38KJ6IiIiISEmed/Z69OgRhgwZgkqVKqFYsWIICwsDAMTFxWHEiBG4du1anitJRERERPSpPI3I3rlzB02aNIFcLkf9+vXx4MEDcZUCCwsLhIeHIzk5GWvXrs2XyhIRERERZcpTIPvLL7/A3NwcFy5cgEQiUVhTFgA6dOiAbdu25amCRERERESq5GlqQVhYGIYOHQpLS0tIJBKl42XLlsXTp0/zcgkiIiIiIpXyFMjK5XIYGhqqPR4bGws9Pb28XIKIiIiISKU8BbJ16tTBgQMHVB6TyWTYunUrGjRokJdLEBERERGplKdAdsKECTh8+DCGDh2Kf/75BwDw33//4dixY2jTpg3u3r2L8ePH50tFiYiIiIg+lqeHvdq1a4egoCCMHDkSq1atAgB4enpCEASYmppiw4YNaNq0ab5UlIiIiIjoY3neEOH7779Ht27dEBoaigcPHkAul8PR0RHu7u4wMTHJjzoSERERESnJl529jIyM0LVr1/wo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E/Hs2TPs2LEDUqkUffv2xbx58/KrrkREREREojwFsmXLlkXZsmXF1/r6+lizZg3WrFmT54oREREREWUlzxsiZBIEAbGxsQAAS0tLSCSS/CqaiIiIiEhJnreovXPnDnr06AFTU1OUKlUKpUqVgqmpKXr06IF//vknP+pIRERERKQkTyOyZ86cQbt27SCXy9G5c2dUrFgRABAREYF9+/bh0KFDOHz4MJo0aZIvlSUiIiIiypSnQPann36ClZUVTp8+DVtbW4Vjjx8/RtOmTTF69Ghcvnw5T5UkIiIiIvpUnqYW3L59G35+fkpBLADY2tpi6NChuH37dl4uQURERESkUp4CWTs7O6Smpqo9npaWpjLIJSIiIiLKqzwFslOmTMGiRYtw/fp1pWPXrl3D4sWL4e/vn5dLEBERERGplKs5siNGjFBKK1myJJydndGoUSOUL18eABAZGYnz58+jWrVquHDhAvr06ZM/tSUiIiIi+n+5CmSXLFmi9tjZs2dx9uxZhbRbt27hn3/+wcKFCz+vdkREREREauQqkJXL5QVVDyIiIiKiXMnzhghERERERIUhX7aojYqKwqFDhxATEwPgw2oG7dq1Q7ly5fKjeCIiIiIiJXkOZH/++WcsXLhQadqBlpYWRo0ahcDAwLxegoiIiIhISZ6mFsydOxfz589Ht27dcP78ecTHxyM+Ph7nz59Hjx49MH/+fMyfPz+/6kpEREREJMrTiOzq1avRqVMnbN++XSG9fv362Lp1K96/f4+VK1fip59+ylMliYiIiIg+lacR2ejoaLi7u6s97u7ujujo6LxcgoiIiIhIpTwFslZWVrhx44ba4zdu3IClpWVeLkFEREREpFKeAtmePXtizZo1+O2335CcnCymJycnY86cOVizZg169eqV50oSEREREX0qT3NkZ8yYgevXr2PixImYMmUKbGxsAADPnj2DTCZD8+bNMX369HypKBERERHRx/IUyBoaGuL48ePYu3evwjqybdu2Rfv27fHdd99BIpHkS0WJiIiIiD722YHsu3fv4Onpie7du6Nfv37o3LlzftaLiIiIiChLnz1H1tDQEMeOHcO7d+/ysz5ERERERDmSp4e9XF1dcf78+fyqCxERERFRjuUpkF2yZAnOnDmDyZMn48mTJ/lVJyIiIiKibOUpkK1ZsyaePHmCgIAA2NnZQU9PD6ampgpfZmZm+VVXIiIiIiJRnlYt6NGjR37Vg4iIiIgoVz4rkH3//j327t2LSpUqoUSJEujYsSNKlSqV33Ujom+Uh4cHdu3ahYyMDBgZGWHx4sUYMGCAyrx79+6Fn58f/vvvP2RkZKBLly7YvXu3Qp60tDS0bNkSFy5cgEwmg7a2Npo2bYqjR49CS0v5gyknJyfcvXtXZVlERFR05HpqwcuXL1GtWjX07dsXEydOxJAhQ1CxYkUcO3asIOpHRN+YkSNHIiQkBP3798fevXtha2uLgQMH4vbt2yrzx8fHw8bGBn5+fiqDUgDo2LEjzp49i0mTJuHMmTMYMWIETpw4gZ49eyrlHTduHKKiotSWRURERUeu79QzZsxAdHQ0fvrpJ+zfvx/z58+Hvr4+fH19C6J+RPSNWbt2LapXr45169ahU6dOuHXrFiQSCX7++WeV+b28vHD58mUsWrRI7QYsN27cQPny5eHv7w9XV1fMnTsXNjY2uHr1qkK+K1euIDAwEFu3buVmLkREGiDXgWxoaCj69++PwMBAtG/fHiNGjMCSJUsQHR2NiIiIgqgjEX0jkpKSkJycjA4dOohp2trasLe3x40bNz673Jo1a+Lff//FkSNHAADbt2/H8+fP0a5dOzGPTCZD69at0blz5xxt8LJ06VLY29tDX18f9evXx6VLl9TmvX37Nrp37w57e3tIJBIsWLBAKU9GRgZ+/fVXlCtXDgYGBnB0dMSMGTMgCELuG0xE9I3IdSD76NEjuLq6KqS5urpCEAT8999/+VYxIvr23L9/HwBQrlw5hfQSJUrg7du3n13uwYMHUbduXbRt2xYSiQS9evVC69atsWzZMjFPhw4doKWlhR07dmRb3rZt2zB69GhMnToVV69eRc2aNeHu7o6XL1+qzP/u3Ts4ODjgt99+g7W1tco8c+bMwfLly7FkyRLcvXsXc+bMwe+//47Fixd/XqOJiL4BuQ5kU1NToa+vr5CW+Vomk+VPrYiI8tHo0aNx5coVDB8+HDt27ICvry+OHj0KHx8fAMDGjRtx7NgxtQ9/fWrevHnw8fHBgAED4OTkhBUrVsDQ0BDr1q1Tmb9evXr4448/0Lt3b+jp6anMc+7cOXTu3BkdOnSAvb09evTogTZt2mQ50ktE9K37rFULoqOjFeaWJSQkAAAiIyNhbm6ulL9OnTqfVzsi+qZUrFgRABAVFaWQ/urVK5iYmHx2ucuWLUO3bt2waNEiAED37t3x4MEDbNiwAatXr8bOnTshl8vh7OyscN6ePXugra2t8Ed6Wloa/v77b0yYMEFM09LSQqtWrfK002GjRo2watUq3L9/HxUrVsSNGzcQHh6OefPmfXaZRERfu88KZH/99Vf8+uuvSul+fn4KrwVBgEQiQUZGxufVjoi+KcbGxjAyMsKBAwcQEBAA4MMnPdHR0WjduvVnlyuXyyGVShXSpFKpOP/0999/R//+/RWO9+jRA/Xq1cPUqVMV0uPi4pCRkYGSJUsqpJcsWRL37t377DqOHz8eiYmJqFy5MqRSKTIyMjBr1iz069fvs8skIvra5TqQXb9+fUHUg4gIADBw4EAsWrQIPj4+6Ny5M8aOHQtBEBAYGAgAcHR0hJWVlTj6mZSUhAMHDgD48MfzkydPsG3bNlhYWKBly5YAAAcHB2zfvh2VKlVCq1at8Ndff+Ho0aOoV68eAKBChQqoUKGCQj0kEglKlSql8EBYQdq+fTs2bdqEzZs3o2rVqrh+/TpGjRoFGxsbeHl5fZE6EBFpmlwHsryhElFBWrhwIZ49e4b169djzZo1MDIywurVq1GtWjUAH6YZfLw01vXr19G7d2/x9ZUrV9C7d2+YmZkhPj4eABAWFoYOHTpg5syZmDZtGrS1tdGoUSMcPnw41/WzsLCAVCpVerj1v//+U/sgV06MHTsW48ePF9tSvXp1xMTEICAggPfdXMrvDTW0tbVVfrJYrVo13Lp1Cw8fPkTXrl1x7949pKenQyqVomrVqvjrr79QtmxZLF26FH/88QdevHiBmjVrYvHixXBxcVFZn9u3b2PKlCn4+++/ERMTg/nz52PUqFEKeezt7RETE6N0rp+fH5YuXYrXr19j6tSpCA0NxaNHj2BpaYkuXbpgxowZ3Daevjpc8ZuIipyQkBDIZDIIgoCkpCQMHDhQPBYfH48HDx6IrzNXTfn0KzOIBQAbGxtcu3ZNLDM9PR3h4eEwNjZWWweZTKZyVy9dXV04Ozvj+PHjYppcLsfx48fRsGHDz27zu3fvlB40k0qlkMvln13mt6ggNtS4desWbty4IX7NmTMHAMR+efPmTbx69Qrjxo3D8ePHMWfOHNy9exeNGjUqkBUuLl++jOfPn4tfR48eBQBxg49nz57h2bNnCAwMxD///IOgoCAcPnxY4eeI6GshEbhIYYFITEyEmZkZEhISYGpqWuDX81lQ4JfIlfHL/Qu7CgrWNPipsKugICCYoyKabNu2bfDy8sLKlSvh4uKCBQsWYPv27bh37x5KliyJ/v37o3Tp0uI837S0NNy5cwcA0L59e/Tr1w/9+vWDsbExypcvDwDw9vbGsWPHsHLlSlStWhXXrl3D4MGD8cMPP4iBE2XP2NgYDg4OuHnzJoAPf5Do6emhdevW2Y7Aa2tr47vvvst2W+LatWvjn3/+QWpqqtrgd/To0Zg/fz7q1q2L+vXrY8mSJQA+/NFja2uL4cOHY/z48Vlex97eHqNGjVIakf3UqFGjsH//fkRGRqrdyCMkJASenp5ITk6GtvZnPR5D9MXkJobiiCwRoU6dOpBIJJBIJJBKpSof5sy0ePFiGBgYiPmrV6+uMt/BgwdhbGws5tPS0sK0adPE4w8fPkSJEiXE4xKJRJyzWtT16tULgYGBmDJlCmrVqoXr16/j8OHD4gNgjx49wvPnz8X8z549Q+3atVG7dm08f/4cgYGBqF27NgYNGiTmWbx4MXr06AE/Pz9UqVIFY8aMga+vL2bMmPHF25dbRaX/1K5du0A21PhYUlISbty4gebNm2e5VNurV68AANeuXUOrVq3E9PxY4eJjaWlp2LhxI3744Ycsd6PLDAiKYhBbVPqPptx/SBEDWaJvXLt27XDt2jW4urpi8eLFMDExwcyZMxEWFqYyf1xcHMzMzODu7q62zOvXr4sbDEyePBlbt26Ft7c3HB0dxTzOzs54/fo1fvzxR2zfvh0uLi64cuWK+PFoUTds2DDExMQgNTUVFy9eRP369cVjp06dQlBQkPja3t5e5fSHU6dOiXlMTEywYMECxMTEICUlBQ8fPsTMmTOhq6v7BVuVe0Wp/1y/fh1A/m+o8bFff/0VgiDgt99+U5snIiICmzZtQt26ddWucPHixYt8qc+ePXsQHx8Pb29vtXni4uIwY8YMDB48OF+umZ+KUv/RpPsP/Q+nFhQQTi3wL+wqKODUAvWkUinMzc3FEaS0tDTo6emhQoUK4k5b6kgkEvGBl4/Z2Njg5cuXWW6SoqWlBXt7e/z7778KaaVLl8bjx4/z0CL6kopS/8kckVy5cqVC0Obi4oI7d+4gKSkpy/rkZGqBuof9Mj158gSVK1eGgYEBLly4gPLly+PcuXMK86d/+eUXnD59GhcvXsyyPjmZWuDu7g5dXV389ddfKo8nJiaidevWKF68OPbt2wcdHZ0sr/mlFaX+w/tP0cGpBUSUI69fv4ZcLkezZs3ENF1dXRgbG+PRo0efXe7z589RvHhx8SNALS0tpQehTE1NERMTg4MHDyIjIwN+fn4QBAHdunX77OvSl1XU+k+m/N5QI9PZs2fx6tUrtQ9NPXv2DFWqVIGuri4iIyNha2tbICtcZIqJicGxY8cUpqh87O3bt2jbti1MTEywe/fuIhfEFrX+w/uPZmIgS/QNu3z5MgCIDxxlMjY2Rnp6ep7Kjo2NRYkSJTB79mzUq1cPFy5cgJubm3g8MjIShoaG6NChA7S1tbF8+XK4ublh4cKFeboufTlFsf9kbqiRKXNDjZo1a+apPgAwadIkaGlpYcqUKUrHnjx5gkqVKkEqleL+/fswNzcvsBUuMq1fvx5WVlYKc4IzJSYmok2bNtDV1cW+ffuUtpYvCopi/ymK95+lS5fC3t4e+vr6qF+/fpbbVt++fRvdu3eHvb09JBIJFixYoDLf06dP4enpiRIlSsDAwADVq1fHlStXAADp6ekYN24cqlevDiMjI9jY2KB///549uxZQTQvzxjIElGB0NLSwpMnTzBhwgRcvHgRJUqUQHh4uHi8adOmSEpKgoeHBwIDA1GrVi2cPn0aPj4+hVhrKio+t//Y29vj1q1b8PHxwf79+1G9enWlDTU+DiKTkpKwbds2bNu2TWFDjY+DT+BDQBweHo569eopBYWZ0wlkMhl27dqFZ8+e4ebNm7h58yZGjBiB1atXIzg4GHfv3sXQoUORnJwsrmvbv39/he2O09LScP36dVy/fh1paWl4+vQprl+/rrDkHPAhIF6/fj28vLyUHuDKDGKTk5Oxdu1aJCYm4sWLF3jx4sU3s9Pm13L/KYjl2968eYPGjRtDR0cHhw4dwp07dzB37lwUK1ZMLOPq1av49ddfcfXqVezatQsRERHo1KlTgbUzL4re44tE9MVkPqX76S/JpKSkPH8M+ekarfb29uI8uKdPn+LevXvo06cPNm/eDAD4+eefYWZmhqA16zA+rHSerp2fHCP8C7sKRVZR7D/3799Hjx498nVDDQD4448/kJGRofDke6YdO3YgOTkZAMTd5DKdOXNGXOHixYsXqFWrltIKFx+vfpC5wkWmwMBABAYGws3NTeHhwGPHjuHRo0f44YcflOpz9epVcf7tp6OdUVFRsLe3VzqnMBTF/hMcHIzVq1fn6dr5ad68efDx8RH/8FmxYgUOHDiAdevWqVy+rV69euL7qm55tzlz5sDW1lZhp9aPH5A0MzMT1ybOtGTJEri4uODRo0coW7ZsntuVnxjIEn3DihcvDi0tLZw+fVpMS0tLQ1JSktKWrblhaGgo/mLP9PEv7MTERAAfHvT4WFbLGVHRUxT7jyAICAkJUVv2x8Ep8L8NNbIzYcIEhZHTj2X3QJarqyuGDRum8tjHwSnwvxUustOmTRu1+Zo1a5ajMgpbUe0/RUVaWhr+/vtvhX6XH8u37du3D+7u7ujZsydOnz6N0qVLw8/PL8vR6ISEBEgkEpibm3/2dQsKf2sQfePatGmDV69ewc3NDcuXLxdHilatWgXgw7JQpUv/b4T09evXmDNnjrhIf2xsLObMmYMNGzaIecaMGYOMjAxUqFABGzZsQOvWrREbG4vmzZsDAKpUqQKpVIpNmzZh2LBh2LZtG5o2bYr4+HhU1lNcqoiKtqLWf/JjLix9Oew/6sXFxRXI8m3//vsvli9fjgoVKuDIkSMYOnQoRowYgeDgYJX5379/j3HjxqFPnz5fZBWm3OLyWwWEy2/5F3YVFHD5razVrl1bXINTS0sL48ePx6xZswB8WJLI0NBQHMUICQmBh4eHUhlSqVRhuZvevXtj+/bt4ghHgwYNFEYRTpw4gS5duiis71m1alXset9VaaSkMLHvZK8o9Z8bN24Uqf5D2WP/Ue3Zs2coXbp0vi/fpquri7p16+LcuXNi2ogRI3D58mWlkd709HR0794dT548walTp75YIMvlt4goV65duyYu0p+RkSH+EgE+POSS+UsE+LCfu6rF/T9ds3Hr1q2Qy+Xi8U9vkC1atEBiYqJCGf/880+R+SVCOcf+Q3lR1PqPh4cHtLW1IZFIYGxsrDCX9FN79+5F6dKlxfxdu3ZVytOsWTOFHcQkEgn09PRUlieXy2FpaSmuOFAQy7eVKlUKTk5OCmlVqlRRWvIsPT0dHh4eiImJwdGjR4vkaCzAQJaIiIgIADBy5EiEhISgf//+2Lt3L2xtbTFw4EDcvn1bZf74+HjY2NjAz88vyzn+enp6uHHjhvh18+ZNlfm6desmPowolUoLZPm2xo0bIyIiQiHt/v37sLOzE19nBrGRkZE4duwYSpQo8dnXK2h82IuIiIgIwNq1a1G9enWsW7cOANC+fXvo6enh559/xuHDh5Xye3l5wcvLCwCwbNkyteVKJBLUqFEjy2tv27YNf/31F65duybO1R09ejS8vLxQt25duLi4YMGCBUrLt5UuXRoBAQEAPjwgdufOHfH/mcu3GRsbiytY/PTTT2jUqBFmz54NDw8PXLp0CatWrRLnJaenp6NHjx64evUq9u/fj4yMDHFObvHixYvcttkMZImIiOibl5SUhOTkZIUNJrS1tWFvb48bN27kqez3799DKpWK2+Bu2bJFYVQ1Li4O/fv3x7hx4xQC3l69eiE2NjZfl2+rV68edu/ejQkTJmD69OkoV64cFixYgH79+gH4sDzZvn37AAC1atVSaMfJkycVdmIrChjIEhHRV+NhJf/CroICrkOsOe7fvw9AcU1VAChRooTSPNXcaNGiBerUqYNGjRohIiICv/32G5o0aYJHjx7BxsYGANCkSRPY29tj9uzZSucPGzYs35dv69ixIzp27KjyWE7LKCoYyBIRERWQCV4JhV0FBUVx1Yuv3adbGnt6esLe3h4TJ05EUFAQJk2ahIcPHyo9bEU5w4e9iIiI6JtXsWJFAB92P/vYq1evYGJikm/XsbOzg6GhofjA1cGDB5Geno5SpUqJqxoAwG+//VYkNyAoajgiS/SNK3JrEBd2BShX2H8oL4pW/zGGkZERDhw4ID48JZPJEB0djdatW+fbVV68eIGUlBRxWkFwcDAePnyokKdbt27o1q0bRo4cmW/X/VoxkCUiIiICMHDgQCxatAg+Pj7o3Lkzxo4dC0EQEBgYCABwdHSElZWVuC5tUlISDhw4AAAQBAFPnjzBtm3bYGFhgZYtWwIA6tati++//x7Ozs64ffs2Jk6cCACYOXMmAKBGjRoqVzSoWLEimjZtWuBt1nQMZImIiIgALFy4EM+ePcP69euxZs0aGBkZYfXq1ahWrRqAD9MMMj/6B4Dr16+jd+/e4usrV66gd+/eMDMzQ3x8PADg5cuXGD16NORyubhqQUhICKpUqfJF2/a1YiBLRERE9P9CQkLUHssMTjO5urpm+4T/5zzEpUmrBhQ2BrJERERERRBXvcgeVy0gIiIiIo3EQJaIiIiINBIDWSIiIiLSSEUykL18+TLat28Pc3NzGBkZoUGDBti+fXuOz3/48CH8/f3RqVMnlC5dGhKJBPb29lmek7kIsaovb2/vvDWIiIiIiPJdkXvY6+TJk3B3d4e+vj569+4NExMT7Ny5E7169cLjx4/x888/Z1vGmTNnMG3aNEilUlSpUgUvXrzI0bXt7OxUBq21atXKZSuIiIiIqKAVqUBWJpPBx8cHWlpaCAsLEwPIKVOmwMXFBRMnTkSPHj1gZ2eXZTlNmzbF+fPnUbNmTRgYGEBfXz9H17e3t4e/v38eW0FERESa6GEl/8KugqIGPxV2DYq8IjW14MSJE3j48CH69u2rMApqZmaGiRMnIi0tDcHBwdmW4+DggAYNGsDAwKAAa0tEREREhalIjcieOnUKANCmTRulY+7u7gCA06dPF9j14+PjsWrVKsTFxaF48eJo3LgxqlevnqNzU1NTkZqaKr5OTEwEAKSnpyM9PR0AoKWlBalUioyMDMjlcjFvZrpMJlNYBFkqlUJLS0ttema5H+h8TpOpkAiCAJlMppCmrf3hx/HTdB0dHcjlcmRkZIhpEokE2traatPV9TFV6YA0P5tGBezjn/vc3SPU97G89T3eezSJTCbL9T0i77+f1Pcx9h/N8un3taB+P316nawUqUA2MjISAFChQgWlY9bW1jA2NhbzFIQbN27A19dXIa1t27YIDg6GlZVVlucGBARg2rRpSumhoaEwNDQEAJQtWxa1a9fGzZs3FXb6qFSpEipXroxLly4hNjZWTK9Vqxbs7OwQFhaGt2/fiukNGzaElZUVQkNDP7opdM5tc6kQyWQyHDx4UCGtffv2SElJwcmTJ8U0bW1tdOjQAXFxceLe3gBgYmKCFi1a4PHjx7h+/bqYbmlpiUaNGiEyMhIRERFielZ9D6ic/w2kAvNxv8ndPQJo3rw5DAwM8rnv8d6jSS5dupTre0Tefz+p73vsP5rl4+9fQf5+evfuXY7rJBGK0D5obdq0wdGjRxEZGYny5csrHS9dujSSkpKQkJC7nS709fVhbW2N6OhotXnGjBmD7t27o2LFitDV1cU///yDGTNm4NChQ6hXrx7Onz8PqVT9yJWqEVlbW1vExcXB1NQUQMH+xeu3tGj9VTt+uX9hV0HBmiI2z2h2kGmRGZEdsrhojciy72Rt+hpD8f9FYUSW956sFbX+M2OtUZEakWX/yVpR6z8f33+Agvv9lJiYCAsLCyQkJIgxlDpFakS2MAUGBiq8btiwIfbv348WLVrg9OnT2Lt3L7p166b2fD09Pejp6Sml6+joQEdH8QdVKpWqDIozf9Bzmv5puaQ5JBKJ2u+fqnQtLa3/nwaQs3R1fUxdOmkOVf0jt/eIgux7VLRl9pXc3iPy6/cTf29pti/1+yk3/aRI3YXMzD7s4atuxDUxMVHM8yVoaWnBx8cHAHD27Nkvdl0iIiIiyl6RCmQz58aqmgf74sULJCUlqZw/W5AsLCwAAMnJyV/0ukRERESUtSIVyLq5uQH48IDUp44cOaKQ50u5ePEiAGS7MxgRERERfVlFKpBt2bIlHBwcsHnzZoUn3RISEjB79mzo6uqif//+Yvrz589x7969XD/89albt26pXOrh3LlzmDNnDnR0dNCzZ888XYOIiIiI8leRethLW1sba9asgbu7O5o2baqwRW1MTAwCAwMVRkYnTJiA4OBgrF+/XmFr2bi4OIwZM0Z8nZ6ejri4OIU8gYGB4rSBuXPn4sCBA3B1dYWtrS10dHRw+/ZthIaGQiKRYOnSpXB0dCzo5hMRERFRLhSpQBb4sNZceHg4pk6dim3btiE9PR3Vq1fHnDlz0KtXrxyVkZSUpLQDWHJyskKav7+/GMh27twZ8fHxuHHjBo4ePYq0tDRYW1ujd+/eGDVqFFxcXPKvgURERESUL4pcIAsALi4uOHToULb5goKCEBQUpJRub2+P3CyP27VrV3Tt2jU3VSQiIiKiQlak5sgSEREREeUUA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDQSA1kiIiIi0kgMZImIiIhIIzGQJSIiIiKNxECWiIiIiDRSkQxkL1++jPbt28Pc3BxGRkZo0KABtm/fnqsyUlNTMX36dFSoUAH6+vqwsbHB4MGD8fLlS7XnbNq0CS4uLjAyMkKxYsXQsWNHXL16Na/NISIiIqICUOQC2ZMnT6Jx48YIDw+Hh4cHhgwZghcvXqBXr16YO3dujsqQy+Xo3Lkzpk6dCgsLC4waNQoNGzbEmjVr0LBhQ8TGxiqdM2vWLHh6euLly5cYMmQIevbsibCwMDRq1Ahnz57N72YSERERUR5pF3YFPiaTyeDj4wMtLS2EhYWhVq1aAIApU6bAxcUFEydORI8ePWBnZ5dlOcHBwThy5Aj69OmDTZs2QSKRAABWrFiBoUOHYvLkyVi5cqWYPzIyEv7+/qhYsSIuXboEMzMzAICfnx8aNGgAHx8f/PPPP9DSKnJxPxEREdE3q0hFZidOnMDDhw/Rt29fMYgFADMzM0ycOBFpaWkIDg7OtpzVq1cDAAICAsQgFgB8fX3h4OCATZs2ISUlRUxfv349ZDIZJk2aJAaxAFCrVi306dMHd+/eRXh4eD60kIiIiIjyS5EKZE+dOgUAaNOmjdIxd3d3AMDp06ezLOP9+/e4ePEiKlWqpDRyK5FI0Lp1ayQnJ+PKlSv5el0iIiIi+rKK1NSCyMhIAECFChWUjllbW8PY2FjMo87Dhw8hl8tVlvFx2ZGRkWjSpIn4f2NjY1hbW2eZPyupqalITU0VXyckJAAAXr9+jfT0dACAlpYWpFIpMjIyIJfLxbyZ6TKZDIIgiOlSqRRaWlpq0zPLBYC09zpZ1u9Le5uRmn2mLyg1LbGwq6AgIeHDVJqPaWt/+HH8NF1HRwdyuRwZGRlimkQigba2ttp0dX1MVXrae2m+ti2v2Hey9urV//pHbu4RgPo+lpe+x3tP1opa/3n9OiPX94i8/n4C1Pcx9p+sFbX+8/H9Byi4309v374FAIW+pU6RCmQzg7+PP97/mKmpqZgnL2V8nC/z/1ZWVjnOr0pAQACmTZumlF6uXLksz/tabSjsCnzq4W+FXQMF87cWdg2KLvadrLHvZI39J2vsP1lj/8nal+4/b9++VRvPZSpSgawmmzBhAkaPHi2+lsvleP36NUqUKKEwT7coS0xMhK2tLR4/fiwG8EQ5wb5DecH+Q3nB/vP1EQQBb9++hY2NTbZ5i1Qgmxl1qxv9TExMRLFixfJcxsf5Mv+fm/yq6OnpQU9PTyHN3Nw8y3OKKlNTU94M6LOw71BesP9QXrD/fF2yi7syFamHvbKaj/rixQskJSWpnfuaycHBAVpaWmrntKqah1uhQgUkJSXhxYsXOcpPRERERIWvSAWybm5uAIDQ0FClY0eOHFHIo46BgQFcXFwQERGBmJgYhWOCIODo0aMwMjJC3bp18/W6RERERPRlFalAtmXLlnBwcMDmzZtx/fp1MT0hIQGzZ8+Grq4u+vfvL6Y/f/4c9+7dU5oWMHjwYAAf5q1+/MTbypUr8e+//6Jfv34wMDAQ0wcMGABtbW3MmjVLoazr169jy5YtqFKlClxdXfO7uUWOnp4epk6dqjRFgig77DuUF+w/lBfsP982iZCTtQ2+oJMnT8Ld3R36+vro3bs3TExMsHPnTsTExCAwMBA///yzmNfb2xvBwcFYv349vL29xXS5XI727dvjyJEjaNCgAdzc3PDgwQPs2rUL9vb2uHjxIiwtLRWuO2vWLEyePBl2dnbo3r073r59i61btyItLQ3Hjx9H48aNv9RbQEREREQ5UKRGZAGgefPmCA8PR+PGjbFt2zYsX74cJUuWxNatWxWC2KxoaWlh79698Pf3R2xsLObPn4+zZ89i4MCBOH/+vFIQCwCTJk3Cxo0bYWlpieXLl2P79u1o0qQJzp07xyCWiIiIqAgqciOyREREREQ5UeRGZImIiIiIcoKBLBERERFpJAayRERERKSRGMgSERERkUZiIEtEREREGomBLInkcnlhV4GIvkFcPIfygv3n28ZAlkRaWlpIS0sr7GoQ0TdGIpEA+BCQMCih7GT2EZlMBkCx/9C3R7uwK0CF6/379zhx4gR27twJQRBQokQJWFpaonbt2nBxcYGZmVlhV5GIvlLnz59HaGgoTExM0KNHD5QtW7awq0QaQCKRID4+HnPnzsWhQ4dQtWpV+Pr6olGjRoVdNSoE3BDhGxYZGYlp06Zh8+bNAABTU1O8f/8eaWlpMDQ0RN26ddGpUyd07NgRFStWhCAI4l++ROwP9LmePXuGxYsXY86cOQrpU6dOxdSpUwupVqQpIiIiMH78eOzdu1chPTQ0FK1atQIAxMbGIjk5Gba2tpBKpYVRTfpCGMh+wzw9PbF7926MHTsWXbt2xbt37yCTyXDr1i3s2fN/7d17VI35/sDx9+6iottIxSGXiJDLkcsQIiXGnejGaawQs9zGMQ5jGaNxWuMSc5bLmY5Bw0jKGYM1c9xGFlPGmTkc12FEHblERdOOpNrf3x9W+2crtwy77M9rrdbS9/k+z/N5rM96+uxnf7/f5xtSUlIoKyujf//+LFiwQF7VKwxMnz4dOzs7wsLCaNu27XPtU1xcjJWV1SuOTFR3s2bNYu3atfTu3Zvg4GAuXLjAxo0buXfvHl999RUjRoyQD0riiSZPnsxXX31FdHQ0I0aM4PvvvycqKoqoqCimTJnChx9+yJkzZ3B1dSUwMJBp06ZRr149Y4ctXhEpZE1UYWEh9erV47333iMmJgZra2uD7UopTp48ycaNG9m0aRNlZWXExcURGhpqpIhFdVJYWIi9vb3+d19fX0JCQhg0aBCNGjUy6KvT6TAzM+PGjRskJSXh6elJYGDg6w5ZVBNarRZXV1f69+/Pli1bqFOnDgA//fQTfn5+NG3alO+//x4XFxfKysowNzenoKCAc+fO4enpiaOjo3EvQBiVVqulQYMGjBs3jhUrVmBjYwPAkCFDOHXqFA0aNOD69et4eXmRnp5Oeno6kyZNIjY2Vp9r4s0ik71M1KFDhygtLaV169ZYW1tTUlJisF2j0dCxY0eio6NZuXIl8PBrv+vXrxsjXFHN7Nu3D4A+ffrg5+fHsWPHmDJlCp6enowePZqvv/6a/Px84OEkQoADBw7w/vvvc/z4cWOFLaqB5ORkLC0tiYiIoE6dOjx48ICysjK6dOnCkiVLOHv2LNu3bwf+P3eOHTtGjx49iIuLM2boohpISkoCICAgQF/E3rt3D2tra7KysggKCuLEiRMkJiaSkJCAl5cX//jHP/j555+NGbZ4haSQNVF2dnaYm5uTk5MDgIVF5fP+HBwcePfdd1m3bh3p6elyMxAAnD9/Hnj44ebAgQN8/fXXvP/++3h4ePDPf/6ToKAg2rZty9SpU0lNTaWoqIgff/wRgPDwcGOGLozshx9+4A9/+AOenp4AWFpa6scwhoeH06xZM+Li4sjNzUWj0aCU4j//+Q8AISEhRotbVA8HDx7E09OTNm3a6NsyMzO5cOEC/fv3Z/bs2Tg5OWFvb0/nzp357LPPALh06ZKRIhavmhSyJqpjx454eXkRExPDv/71L/1YNJ1OR1lZmb5f+ZNad3d3bG1tSUtLM0q8ovp48OABN27cANDPMh8wYACxsbHs2bOHrVu3EhERgZWVFWvXrqVXr1506tSJ+Ph4unTpIjPTTVhxcTGlpaVotVpatWoFGC6d5ODgwIwZMzh9+jQ7duwAICMjg++++46OHTvSpEkTo8UujK+wsJCcnBwKCgr0H4QAzp07x5kzZ4iMjASgrKxMvzRXrVq1sLCwICsryygxi1dPClkTVP4HY9asWZSUlBAVFcXy5cvRarWYmZnpn44opbC0tATg6tWrlJaWGtw8hGmqVasWERERLFiwQD+2uvzDj6urK8HBwWzcuJG9e/eyevVqRo4cyc2bNykqKmLy5MnGDF0YmYWFBXZ2djg6OlJSUmKw7md5QTt58mRcXFzYsGEDJSUlnD9/nqNHjzJx4kRjhS2qCQsLC0aPHs27774L/P99p0OHDixdupTRo0cDYG5urv+W8fLly5iZmek/OIk3j0z2MnFbtmxh3rx5XL16FQcHB4KDgxk9ejR9+/bFzMyM/Px8CgoK9DOLr127ph+XJEybTqdDo9EYzCwvX9C+fGwjPHyKMmzYMA4dOkRhYaHkj4n75ZdfSE1NZfDgwdSvX99gW/nEwCVLljBv3jy+/PJLLl68yF//+le0Wi21a9c2UtSiutBqtZSVlVWY9FdSUqJ/8FLu/v37zJo1i/Xr13Pnzh3JnzeUFLImpqCgADs7O4PiIzU1lbi4OLZs2aJ/QmJvb0/Xrl3Jy8vj9OnT2Nra8tFHHzFz5kwjRS6qg8ryp6ysDDMzswpLJZX/Yfnxxx8ZOXIk3t7e7N69+3WHLKqJJ+WORqMx+OADkJWVhbe3N2+99RYPHjygVatW7Nmz53WHLKqRF8mf0tJSLCws9MtyeXt7s23bttcdsnhNZGiBifnLX/6Cs7Mz8+bN00+g8PHxYdOmTeTk5LBq1SoCAgKoV68ely9fJicnh4EDB5KUlMSUKVOMHL0wtvL8mTt3rn71AXNzc/2knLKyMv2HofKnI6mpqWRnZzNp0iSjxS2Mrzx35syZo7/3mJubY2ZmViF33NzcCA4O5tKlS/zvf/9j+vTpxgxdVANPuvdUlj/lwwqWLl1KUVER06ZNM1rc4tWTJ7ImplatWvpB8ABvv/02o0aNYsSIEbi7u+vbs7OzuX37Nu7u7iil5OtgAVTMn+7duzNmzBhGjBhhMIlLp9OhlMLc3Jzr16+TmJjIrFmzjBGyqCaeN3fK147NysrCy8uLsrIyCgsLjRGyqEZe5N5TWlrK3r17mT17NpGRkcyZM8cYIYvXRApZE3LhwgW8vLywsbGhY8eO3Lx5k4sXLwJgbW2Nv78/QUFBDB061GD8kVIKnU4nr/kzcc/Kn/79+xMcHMygQYMMXpYgRFVzJy0tjVu3bjF8+HAjRS6qg6rmT3p6OnXr1qVu3brGCl28DkqYlJ07d6qWLVuqvn37quPHj6srV66oP//5z8rZ2VlpNBql0WhUgwYNVGRkpNq/f7/S6XTGDllUI8+bPxMnTlQHDhyQ/BF6L5I7cu8Rj5P8EU8ihawJSk1NVe3atVOWlpZqw4YN+vZdu3apUaNGKUtLS/2NoUmTJio2NtaI0YrqRvJHVNWL5s7SpUuNGK2obl40f5YvX27EaMXrIoWsiTpx4oTq3bu3srCwqPDHQqvVqvXr16u+ffsqjUaj5s6da6QoRXUl+SOqSnJHvAzJH/E4KWRN2J07d9T48eOVRqNRERER6sqVKxX6ZGRkKK1Wa4ToRHUn+SOqSnJHvAzJH/EoC2OP0RWvR/lMYPXIxC1HR0diYmKwtLRk3bp1lJaWEhsbi6urq359vqZNmxq8fUeYJskfUVWSO+JlSP6IZ5FVC0zI/fv39a8ULS4uxsrKSr8tMTGRsWPH0q1bNzZt2kTz5s2NFaaopiR/RFVJ7oiXIfkjnkaeyJqAcePGYW9vT35+PtnZ2dStW5fffvuNkpISrK2tyc/Pp7CwEJ1OR0ZGBvn5+cYOWVQjkj+iqiR3xMuQ/BHPQwrZN9yxY8fYsmULAM7Oznh5eXHr1i1ycnJwdHSkoKAACwsLPDw8cHFxoVOnTgYvRhCmTfJHVJXkjngZkj/ieUkh+4Zbv349AE5OTnTp0oUOHTrwpz/9iVatWun7FBcXU1RUhKOjIzqdrsJ7q4XpkvwRVSW5I16G5I94XjJG9g3366+/sn37drZt28bp06cBaNiwIf7+/gQGBuLj44Obm5u+v3q4koXcEAQg+SOqTnJHvAzJH/G8pJA1EaWlpRw7doykpCR27NjB1atXAfDy8sLPz48BAwbg4+ODnZ2dkSMV1ZHkj6gqyR3xMiR/xLNIIWuCtFotKSkpbN26le+++w6tVkutWrXo2rUrAQEB+Pn54ePjY+wwRTUl+SOqSnJHvAzJH1EZKWRNXHZ2Nt9++y0JCQkcOXKE0tJSvL29+emnn4wdmqgBJH9EVUnuiJch+SPKSSEr9M6fP098fDweHh5ERkYaOxxRw0j+iKqS3BEvQ/LHtEkhK4QQQgghaiSZ3ieEEEIIIWokKWSFEEIIIUSNJIWsEEIIIYSokaSQFUIIIYQQNZIUskIIIYQQokaSQlYIIYQQQtRIUsgKIYQJOnToEBqNhkOHDhk7FCGEqDIpZIUQJik+Ph6NRqP/sba2pmXLlkydOpWbN29W6H/lyhUmT55M06ZNsbKywsXFheHDh5OammrQr3379jRu3JinLdHt4+ODq6srpaWlZGZm6mNYvHhxpf3Dw8PRaDTY2tq+3EW/wdLS0vj444/Jz883dihCiNdIClkhhEmLjo5m8+bNrF69mh49evD3v/+d7t27c+/ePX2f1NRU2rVrx9atWxk1ahRr165lxowZnD17ll69erFq1Sp93/DwcLKysjhy5Eil58vMzOTo0aMEBwdjYWGhb7e2tmbr1q0V+t+9e5edO3dibW39O171myctLY1FixZJISuEiZFCVghh0gYOHMjYsWOZMGEC8fHxzJw5k4yMDHbu3AnAnTt3CAoKwsbGhuPHjxMbG0tkZCTz58/n1KlT9OzZk5kzZ5KWlgZAWFgYGo2GhISESs+3detWlFKEh4cbtL/zzjucO3eOkydPGrTv3LmTBw8eEBAQ8AquXgghajYpZIUQ4hF+fn4AZGRkABAXF0d2djbLli2jefPmBn1tbGz48ssv0Wg0REdHA+Dm5kbv3r3Zvn07JSUlFY6fkJBA8+bN6datm0F79+7dadasWYUCeMuWLQwYMIC6des+9zWcP3+eoKAg6tati7W1NZ07d2bXrl3Pte+xY8cYMGAADg4O1K5dG19f3wrDJz7++GM0Gg2//vorY8eOxcHBAWdnZxYsWIBSiqysLIYNG4a9vT3169cnNja2wnmKi4tZuHAhLVq0wMrKCjc3N+bMmUNxcbFBP41Gw9SpU/nmm2/w8vLCysqKtm3bsmfPHoN4PvjgAwCaNWumH6qRmZkJwP79++nZsyeOjo7Y2trSqlUrPvzww+f+/xRCVF9SyAohxCMuXboEgJOTEwC7d+/G2tqaMWPGVNq/WbNm9OzZk4MHD1JUVAQ8HF6Ql5fH3r17DfqePn2aM2fOVHgaWy40NJTExET9+Nrc3Fz27dtHWFjYc8d/9uxZ3n77bX755Rfmzp1LbGwsderUYfjw4ezYseOp+x48eJDevXtTUFDAwoULiYmJIT8/Hz8/P/79739X6B8cHIxOp+PTTz+lW7duLF68mM8++4yAgAAaNmzIkiVLaNGiBbNnz+bw4cP6/XQ6HUOHDmX58uUMGTKEVatWMXz4cFauXElwcHCF8/zwww+89957hISEsHTpUu7fv8+oUaPIy8sDYOTIkYSGhgKwcuVKNm/ezObNm3F2dubs2bMMHjyY4uJioqOjiY2NZejQoRWKcyFEDaWEEMIEbdy4UQHqwIEDKicnR2VlZanExETl5OSkbGxs1NWrV5VSSjk6OqoOHTo89VjTp09XgDp16pRSSqnbt28rKysrFRoaatBv7ty5ClAXLlzQt2VkZChALVu2TJ05c0YB6siRI0oppdasWaNsbW3V3bt3VUREhKpTp84zr6tfv36qXbt26v79+/o2nU6nevTooTw8PPRtKSkpClApKSn6Ph4eHiowMFDpdDp9v3v37qlmzZqpgIAAfdvChQsVoCZNmqRvKy0tVY0aNVIajUZ9+umn+vY7d+4oGxsbFRERoW/bvHmzMjMz019nuc8//1wBKjU1Vd8GqFq1aqn09HR928mTJxWgVq1apW9btmyZAlRGRobBMVeuXKkAlZOT86z/OiFEDSRPZIUQJs3f3x9nZ2fc3NwICQnB1taWHTt20LBhQwC0Wi12dnZPPUb59oKCAgDeeust3nnnHXbt2sXdu3cBUEqRmJhI586dadmyZaXHadu2Le3bt9dP+kpISGDYsGHUrl37ua7l9u3bHDx4kDFjxqDVasnNzSU3N5e8vDwCAwO5ePEi165dq3Tf//73v1y8eJGwsDDy8vL0+969e5d+/fpx+PBhdDqdwT4TJkzQ/9vc3JzOnTujlCIyMlLf7ujoSKtWrbh8+bK+LTk5mdatW+Pp6ak/T25urn5YR0pKisF5/P39DYZ1tG/fHnt7e4NjPomjoyPwcKzx4/ELIWo+KWSFECZtzZo17N+/n5SUFM6dO8fly5cJDAzUb7ezs0Or1T71GOXbHy14w8PD9SsOwMNZ9ZmZmU8cVlAuLCyM5ORk0tPTSUtLe6FhBenp6SilWLBgAc7OzgY/CxcuBODWrVuV7nvx4kUAIiIiKuz7xRdfUFxczG+//WawT+PGjQ1+d3BwwNramnr16lVov3PnjsG5zp49W+E85QX+4zE+fh54+GHh0WM+SXBwMD4+PkyYMAFXV1dCQkJISkqSolaIN4TFs7sIIcSbq2vXrnTu3PmJ21u3bs2JEycoLi7Gysqq0j6nTp3C0tISDw8PfdvgwYNxcHAgISGBsLAwEhISMDc3JyQk5KnxhIaGMm/ePCZOnIiTkxP9+/d/7mspL85mz55tUIw/qkWLFk/dd9myZXTs2LHSPo+vY2tubl6hT2VtgMG6ujqdjnbt2rFixYpK+7q5ub3wMZ/ExsaGw4cPk5KSwrfffsuePXvYtm0bfn5+7Nu374nHFkLUDFLICiHEUwwePJijR4+SnJzM2LFjK2zPzMzkyJEj+Pv7Y2Njo2+3srIiKCiITZs2cfPmTZKTk/Hz86N+/fpPPV/jxo3x8fHh0KFDTJkyxWCt2Wdxd3cHwNLSEn9//+feD9B/dW9vb//C+76o5s2bc/LkSfr164dGo/ldjvm045iZmdGvXz/69evHihUriImJYf78+aSkpLzyaxVCvFoytEAIIZ4iKioKFxcXPvjggwpjMu/fv8/48eNRSvHRRx9V2Dc8PJySkhKioqLIycl55rCCcosXL2bhwoVMmzbthWJ1cXGhT58+xMXFcePGjQrbc3Jynrivt7c3zZs3Z/ny5RQWFr7Qvi9qzJgxXLt2jXXr1lXYVlRUpB9X/CLq1KkDUOGFCLdv367Qt/yJ8+NLfQkhah55IiuEEE/h5OTE9u3bGTRoEJ06dWLChAm0adOG7Oxs4uPjSU9P529/+xs9evSosK+vry+NGjVi586d2NjYMHLkyOc6p6+vL76+vlWKd82aNfTs2ZN27doxceJE3N3duXnzJkePHuXq1asVXrhQzszMjC+++IKBAwfStm1bxo8fT8OGDbl27RopKSnY29uze/fuKsX0uHHjxpGUlMTkyZNJSUnBx8eHsrIyzp8/T1JSEnv37n3qcI/KeHt7AzB//nxCQkKwtLRkyJAhREdHc/jwYQYNGkSTJk24desWa9eupVGjRvTs2fN3uR4hhPFIISuEEM/Qq1cvTp06RUxMDMnJydy4cQMHBwd69OjBhg0bnlgQmZmZERoayrJlyxgyZMgzVz/4PbRp04aff/6ZRYsWER8fT15eHi4uLvzxj3+s9Knxo/r06cPRo0f55JNPWL16NYWFhdSvX59u3boRFRX1u8VoZmbGN998w8qVK9m0aRM7duygdu3auLu7M2PGjCeu6vA0Xbp04ZNPPuHzzz9nz5496HQ6MjIyGDp0KJmZmWzYsIHc3Fzq1auHr68vixYtwsHB4Xe7JiGEcWjU84yWF0IIIYQQopqRMbJCCCGEEKJGkkJWCCGEEELUSFLICiGEEEKIGkkKWSGEEEIIUSNJISuEEEIIIWokKWSFEEIIIUSNJIWsEEIIIYSokaSQFUIIIYQQNZIUskIIIYQQokaSQlYIIYQQQtRIUsgKIYQQQogaSQpZIYQQQghRI/0fkPgdZo+1qi8AAAAASUVORK5CYII=", + "text/plain": [ + "
" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "noisy_prob = noisy_results.quasi_dists[0]\n", + "l = len(noisy_prob)\n", + "n = int(np.ceil(np.log2(l)))\n", + "\n", + "noisy_prob = {np.binary_repr(key, n): value for key, value in noisy_prob.items()}\n", + "\n", + "em_prob = em_results.quasi_dists[0]\n", + "em_prob = {np.binary_repr(key, n): value for key, value in em_prob.items()}\n", + "\n", + "names = [\"Noise model simulation\", \"Error-mitigated simulation\"]\n", + "counts = [noisy_prob, em_prob]\n", + "naimark_plot(povm, state, counts, names, save=False)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The above plot shows that the noise model and error mitigated simulations are close to the theoretical values." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Running transpiled circuit on the real backend\n", + "\n", + "We are basically going to repeat the same thing we did for the simulations above, except that, in this case, we will replace the backends with the actual quantum hardware." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n" + ] + } + ], + "source": [ + "# Define the best backend to use\n", + "backend = service.get_backend(scores[0][1])\n", + "print(backend)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Uncomment the following lines of code to run this on real quantum hardware -- the best hardware we determined using `mapomatic`. In our case, we have decided to use the result obtained from our previous run. Note that this was done using `shots=1024`. Using the default number of shots may give a better result." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'\\n# Set options for noisy hardware run (without resilience to noise)\\noptions = Options(resilience_level=0)\\n\\n# Set options to include noisy hardware and resilience_level for noise mitigation\\noptions_with_em = Options(resilience_level=1)\\n\\n\\nwith Session(service=service, backend=backend):\\n sampler = Sampler(options=options)\\n noisy_hardware_job = sampler.run(circuits=[best_trans_qc], shots=1024)\\n print(f\"Noisy Job ID: {noisy_hardware_job.job_id()}\")\\n noisy_hardware_results = noisy_hardware_job.result()\\n \\n sampler = Sampler(options=options_with_em)\\n em_hardware_job = sampler.run(circuits=[best_trans_qc], shots=1024)\\n print(f\"Error mitigated Job ID: {em_hardware_job.job_id()}\")\\n em_hardware_results = em_hardware_job.result()\\n\\n'" + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + " \n", + "\"\"\"\n", + "# Set options for noisy hardware run (without resilience to noise)\n", + "options = Options(resilience_level=0)\n", + "\n", + "# Set options to include noisy hardware and resilience_level for noise mitigation\n", + "options_with_em = Options(resilience_level=1)\n", + "\n", + "\n", + "with Session(service=service, backend=backend):\n", + " sampler = Sampler(options=options)\n", + " noisy_hardware_job = sampler.run(circuits=[best_trans_qc], shots=1024)\n", + " print(f\"Noisy Job ID: {noisy_hardware_job.job_id()}\")\n", + " noisy_hardware_results = noisy_hardware_job.result()\n", + " \n", + " sampler = Sampler(options=options_with_em)\n", + " em_hardware_job = sampler.run(circuits=[best_trans_qc], shots=1024)\n", + " print(f\"Error mitigated Job ID: {em_hardware_job.job_id()}\")\n", + " em_hardware_results = em_hardware_job.result()\n", + "\n", + "\"\"\"" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can visualize the result after the job has completed by uncommenting and running the code below" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'\\nnoisy_hardware_prob = noisy_hardware_results.quasi_dists[0]\\nl = len(noisy_hardware_prob)\\nn = int(np.ceil(np.log2(l)))\\n\\nnoisy_hardware_prob = {np.binary_repr(key, n): value for key, value in noisy_hardware_prob.items()}\\n\\nem_hardware_prob = em_hardware_results.quasi_dists[0]\\nem_hardware_prob = {np.binary_repr(key, n): value for key, value in em_hardware_prob.items()}\\n\\nnames = [\"Hardware\", \"Error-mitigated\"]\\ncounts = [noisy_hardware_prob, em_hardware_prob]\\nnaimark_plot(povm, state, counts, names, save=True, file_name=\"hardware_output.pdf\")\\n'" + ] + }, + "execution_count": 19, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "\"\"\"\n", + "noisy_hardware_prob = noisy_hardware_results.quasi_dists[0]\n", + "l = len(noisy_hardware_prob)\n", + "n = int(np.ceil(np.log2(l)))\n", + "\n", + "noisy_hardware_prob = {np.binary_repr(key, n): value for key, value in noisy_hardware_prob.items()}\n", + "\n", + "em_hardware_prob = em_hardware_results.quasi_dists[0]\n", + "em_hardware_prob = {np.binary_repr(key, n): value for key, value in em_hardware_prob.items()}\n", + "\n", + "names = [\"Hardware\", \"Error-mitigated\"]\n", + "counts = [noisy_hardware_prob, em_hardware_prob]\n", + "naimark_plot(povm, state, counts, names, save=True, file_name=\"hardware_output.pdf\")\n", + "\"\"\"" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can obtain hardware results for Naimark's approach by following the steps above. The figure below shows one of the previous hardware experiments for Naimark's extension circuit.\n", + "\n", + "![naimark_hw_results](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/naimark_hw_results.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The above plot compares the hardware result with the theoretical and error-mitigated results. Although there are some deviations from the theoretical values, the difference is not so much. \n", + "\n", + "`Hellinger()` stands for the [Hellinger fidelity](https://en.wikipedia.org/wiki/Hellinger_distance) between different results." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In the next section we demonstrate the implementation of the tetrad POVM using the binary tree approach." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Binary tree approach " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Constructing binary tree circuit\n", + "\n", + "POVMs can be implemented through a binary search approach with a depth logarithmic in the number of possible outcomes. The algorithm was introduced and formalized by [Andersson and Oi](https://arxiv.org/abs/0712.2665). The following explains and illustrates a Python implementation of the binary tree approach to measure the tetrad POVM." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The approach performs a binary search by iteratively applying coupling unitaries conditioned on the results of mid-circuit measurements and measuring the ancilla in the computational basis. At each node, the number of possible outcomes is halved. The fine-grain level of the binary tree corresponds to the final POVM outcomes. The procedure for constructing suitable coupling unitaries is briefly explained in the [appendix](#appendix), while the exact algorithm is outlined in the [original paper](https://arxiv.org/abs/0712.2665).\n", + "\n", + "![sequential_povm](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/sequential_povm.png)\n", + "\n", + "The implementation in the form of a Python module consists of the central class `BinaryTreePOVM` and several helper functions. It creates a simple way to construct a measurement circuit for an arbitrary POVM. We will use it to build the corresponding measurement circuit for the tetrad POVM on a single qubit system." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We initialize a `BinaryTreePOVM` object **btp**, which holds information about the POVM, the coupling unitaries, and the `QuantumCircuit` itself." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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B8gTERGRdLHntAFo3bo19u7dK3YZRERERNVi1xkRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJBsMpEREREUkGwykRERERSQbDKRERERFJhlzsAoiIiIioYqriEiSlZehNLykt1f4/PjFN7/WfNXe0h72dbe0XayIMp0REREQSZSmX4beL1xB7M6XC+QVPCrH+u/2Vvm5sq8S0ccNqvU5T4s/6RERERBIlCAKG9guGjdLaqPWHvRACm0bGrSsWhlMiIiIiCWtso8TQiGCD1+vp3wFtvd1roaLaxXBKREREJHEdfb3QvbNvjZd3cmiCyNDAWqyo9jCc1jMHDx5Ev3794OjoCKVSic6dO2PJkiVQqVRil0ZERES1aMDfnoNDk8bVLmchCBjevzcUCss6qMr0GE7rkeXLlyMiIgIHDhxA48aN0bZtW8TFxWHevHno3bs3njx5InaJREREVEusrRQY/mIohGqW6/2sPzxcm9dJTbWB4bSeOHfuHGbOnAlBELBx40YkJSXh0qVLiIuLQ5s2bXD69GnMnTtX7DKJiIioFrVyd0FwoF+l81s6N0PYc93qsCLT462k6on33nsPGo0G48aNw9ixY7XTW7duja+++gohISFYs2YN5s2bh+bN6++3JSIyztbDS5CQfhEJadHIyEpECwdPfDsvSeyyqA6xDTQc4UEBuHE7FRn3s3Smy+UyDO/fGzJZ/e57rN/VmwG1Wo3vv/8egwcPhqurK6ysrODq6oqwsDCsWrUKKpUKubm5OHjwIABgwoQJetsIDg6Gr68vVCoV9uzZU9eHQEQSsP6nebh88zBcHVujcSMHscshEbANNBxyuQwjKgihL4QGormjvThFmRDD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", + "text/plain": [ + "
" + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "btp = BinaryTreePOVM(povm)\n", + "\n", + "btp.qc.draw('mpl')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note how a conditional X gate is applied instead of a reset after the mid-circuit readout. This trick reduces the error rate because the reset operation is significantly longer and noisier than an X gate. This idea was described and implemented in [Marz](https://github.com/Qiskit-Partners/marz)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Simulating binary tree circuit with readout errors\n", + "\n", + "Instead of running the circuit on a backend noise model, we create a custom noise model with only readout errors by applying a `pauli_error` *X* on `measure` instructions. This way, one can assess the effect of readout errors in our dynamic circuit. In contrast to the standard readout at the end of the circuit, errors from mid-circuit measurements propagate through the circuit if subsequent gates are conditioned on preceding classical measurement outcomes. In other words, an incorrectly measured bit will trigger the wrong conditional unitary. In this case, the evolution of the quantum state is affected by imperfect mid-circuit measurements." + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_ibm_provider import IBMProvider\n", + "\n", + "provider = IBMProvider()\n", + "backend = provider.get_backend('ibm_nairobi', instance='ibm-q/open/main')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's create a noise model where an *X* error occurs with probability `e = 0.03` during the measurement. The chosen value for `e` is close to real hardware readout errors." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "metadata": {}, + "outputs": [], + "source": [ + "from qiskit_aer import AerSimulator\n", + "from qiskit_aer.noise import NoiseModel, pauli_error\n", + "e = 0.03\n", + "noise_model_classical = NoiseModel()\n", + "error_meas = pauli_error([('X',e), ('I', 1-e)])\n", + "\n", + "noise_model_classical.add_quantum_error(error_meas, \"measure\", [1])\n", + "\n", + "simulator_noisy = AerSimulator(noise_model=noise_model_classical)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's transpile and visualize our binary tree circuit." + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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G+uJJ57I8jaioqLUokUL7dq1SzExMapXr548PT0t62nevLnl3ydPnlT37t116NAhOTs7KygoSP7+/jp58qQ+/vhjrVy5Uhs3bky2/I0bN3T27Fm5ublp6dKlev3111WyZEmVLVtWhw8f1urVq9WuXTsdOXJEP/zwg15//XUFBASodOnSOnz4sFatWqV27drp+PHjNh+rtk2bNlq/fr3++ecflS9fPt22+/fvV79+/TR//nxVqpT9x4v27NmjuLg4ubm5qWHDhqm2CQkJ0fHjx7V169Y8UYQtXayy6ld5WJLUuFon1awQole/CdEXC/6rcU/NlSTVCmqpJe/fSbbclZvnNfjLhurW/GW7x2wLF05sVovHP042bfO8sdq55EM9PPB7Bbd+Ntk8s9msBe+HKvLk33r83V0qVramPcO1KnIgCTlQsHPg8m1pysqkR8/TcyNamrJKGtZeKpEP34lpcHGR88gRShjyqhI/+1zOH74nSTKfC5dp1o8yVKsqp96POjhK2zhwTvphg5TRe8xPXZK+WSO98rDk5mKX0GyOc0ASrgPkADlADqTlTOQhLdo8RSE1e+rt/gss0wOKVNDXi4Zo3b65alvviXTWgLyOHEB+kqu/LhgxYoT279+vJ554QuHh4Tp+/Lh27Nih8+fP69y5c/r4449VqVIlFS5cWNWrV5ck7dy5M8V6YmJiNHr0aEnSZ599lqxXZma30a9fP23YsMHyDcuaNWu0adMmy582bdpIkq5du6ZOnTrp0KFDev755xUREaFjx47pyJEjOnz4sKpXr67du3dr8uTJyWLcu3evJCkxMVEfffSRfvvtN4WHh2v37t06cOCAChcurEuXLunpp5/W+++/r19//dUy/9ChQ/Lz89OFCxe0bNkyax+GHJk5c6b27dun0NBQnT59OtvrOX78uCSpXLlycnZO/buDihUrJmub1wSXb66H6z+tdfvm6dCZLam2iUuI1YQfe6pm+RA98dDYVNvkJWaTSWazWU5OyZ8xbvroeBUtU1Mbfh6u21fDk83b8+fniji6Xk16TsjTN9ypIQf+RQ4UnBz4eUvGBdh77sZJ/9uS1DsyPzJUriSnxx+TeddumZYtlzkxUYmffCqZzTKOHCFDPhyLPvreMc1k+/Br0rJ9Ng3JoQriOYDrQHLkwL/IgYKTA+lZu3eOzGazerYclmx65yYD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", + "text/plain": [ + "
" + ] + }, + "execution_count": 23, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# we use optimization_level=1 because at the time of writing higher\n", + "# transpiler optimizations were not yet available for dynamic circuits\n", + "transpiled_qc = transpile(btp.qc, backend, optimization_level=1)\n", + "transpiled_qc.draw('mpl', idle_wires=False)" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "metadata": {}, + "outputs": [], + "source": [ + "noisy_counts = simulator_noisy.run(transpiled_qc).result().get_counts()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A measurement outcome $M_j$ occurs with probability $p_j = Tr[M_j\\rho]$ where $\\rho$ is the initial state of the system. We can therefore precalculate the expected probability distribution by computing the expectation value for each $M_j$. This functionality is implemented in the `theoretical_probs()` function and returns a dictionary of outcomes and their probabilities." + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "metadata": {}, + "outputs": [], + "source": [ + "theo_probs = theoretical_probs(povm, state, binary_tree=True)" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "metadata": {}, + "outputs": [], + "source": [ + "legend = ['Theory', 'Simulation with readout errors']\n", + "data = [theo_probs, noisy_counts]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The histogram below shows the effect of readout errors in the binary tree circuit." + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "metadata": {}, + "outputs": [ + { + "data": { + "image/png": "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xUpEREREJNHLxV5yuRy+vr5Ys2YNHj58iHbt2uH69esYNWoUXFxcUL9+fezatUsfpyIiIiIiAqDHXQtCQ0PRr18/FCtWDFu2bJFmZGfNmoWXL1+iRYsWmDBhgr5OR0RERETfOKPMPPn69etYu3YtNmzYgIcPH8LR0RHdu3dH165d4eHhIdUbMmQI+vTpg4ULF2Ly5MmZjZmIiIiIKOOJrIeHB65cuQJTU1O0bNkSf/zxB3x9fSGXa5/krVOnDv78888MB0pERERE9LEMJ7J2dnZYunQp2rdvDxsbm8/Wb9myJe7du5fR0xERERERqclwIrt69Wo4ODjA3Nxc6/F3797h5cuXKFy4MADAwsICzs7OGT0dEREREZGaDF/s5erqiq1bt6Z6fMeOHXB1dc1o80REREREacpwIvu5u3glJSWlul6WiIiIiCizdFpaEBMTg6ioKOnxq1ev8PDhQ416UVFR2LhxI/Lly5fpAImIiIiItNEpkf3999+l7bNkMhmGDh2KoUOHaq0rhMAvv/yS6QCJiIiIiLTRKZFt2LAhrKysIITAyJEj0alTJ1SsWFGtjkwmg6WlJSpVqgRPT0+9BktEREREpKJTIuvt7Q1vb28AQHx8PNq0aYOyZctmSWBERERERGnJ8PZbAQEB+oyDiIiIiEgn6U5kJ0+eDJlMhrFjx0Iul6frVrMymQzjx4/PVIBERERERNrIxOf20fp/crkcMpkM7969g4mJSbq21pLJZEhJScl0kIYoJiYGtra2iI6OTtedzzLLf06WnyLLjVo0MbtDyLSiYROzOwQiIiKDpksOle4ZWaVSmeZjIiIiIqIviXcsICIiIiKDxESWiIiIiAxSupcWuLq6QiaT6dS4TCbDnTt3dA6KiIiIiOhz0p3I+vj46JzIEhERERFllXQnsqtWrcrCMIiIiIiIdMM1skRERERkkNI9I3vkyBEAQK1atdQef46qPhERERGRPqU7ka1du7baDRFUj1MjhPimb4hARERERFkr3YlsSEgIAMDExETtMRERERFRdtBp14K0HhMRERERfUnpTmTT8uLFC9y/fx8A4OLiAkdHR300S0RERESUqkztWnDgwAF4enoiX7588Pb2hre3N/LlywdPT0/s379fXzESEREREWnI8Izs1q1b0b59e+TNmxcjR45EiRIlAABhYWFYs2YNGjdujM2b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", + "text/plain": [ + "
" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "from qiskit.visualization import plot_histogram\n", + "import matplotlib.pyplot as plt\n", + "\n", + "fig = plot_histogram(data, legend=legend, bar_labels=True)\n", + "ax = fig.axes[0]\n", + "title = f'Tetrad POVM with the binary tree approach'\n", + "ax.set_title(title, fontsize=14)\n", + "ax.set_ylabel('Quasi-probability', fontsize=12)\n", + "ax.set_xlabel('POVM elements', fontsize=12)\n", + "x = ['M0','M1','M2','M3']\n", + "ax.set_xticklabels(x)\n", + "ax.legend(fontsize=12)\n", + "\n", + "fig.tight_layout()\n", + "plt.sca(ax)\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Running binary circuit on real hardware\n", + "\n", + "You can obtain hardware results for the binary tree approach by following the steps in [this section](#mid-circuit) of the appendix. The figure below shows one of the previous hardware experiments.\n", + "\n", + "![binary_tree_hw_results](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/binary_tree_hw_results.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Appendix " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Constructing measurement operators for the binary tree\n", + "\n", + "Consider a set of measurement operators $M_j$, which constitute a POVM. To perform the first step of the binary search, we partition this set into two cumulated operators:\n", + "\n", + "$$B_1 = \\sum_{j=0}^{N/2-1}M_j = M_0 + M_1$$ \n", + "\n", + "$$B_2 = \\sum_{j=N/2}^{N-1}M_j = M_2 + M_3$$\n", + "\n", + "The two cumulated operators constitute a two-outcome POVM which must be measured through a non-destructive measurement by coupling the system to a single ancilla qubit. The measurement outcome can be seen as the first step in a measurement trajectory, which ends at the fine-grain level. We halve the number of possible POVM outcomes at each subsequent measurement, thus going down the binary tree.\n", + "\n", + "![binary_tree](https://raw.githubusercontent.com/petr-ivashkov/qamp-generalized-measurements-img/master/Images/binary_tree.png)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Following the same logic, we partition the set $M_{0..N/2-1}$ into two and measure a binary POVM again. This time, however, we need to account for the evolved post-measurement state $^1$ of the system: \n", + "\n", + "$$\\rho_j' = \\frac{m_j\\rho m_j^{\\dagger}}{Tr[m_j\\rho m_j^{\\dagger}]}$$\n", + "\n", + "where a possible $m_j$ can be obtained from $m_j^{\\dagger}m_j = M_j$ as $m_j = \\sqrt{M_j}$\n", + "\n", + "For instance, we cannot perform the fine-grain measurement $M_{0..N/2-1}$ on the evolved state $\\rho_j'$. To adjust the state for further measurement, we modify the sequential measurement in a way that the probability distribution for the modified measurement on the evolved state is the same as from performing the original measurement on the initial state: \n", + "\n", + "$$Tr[\\rho M_j] = Tr[\\rho' M_j']$$ \n", + "\n", + "The [original paper](https://arxiv.org/abs/0712.2665) proves that one can write the required Kraus operators as:\n", + "\n", + "$$b_{0..N/4-1} = m_{{0..N/4-1}}\\bar m_{{0..N/2-1}}^{-1} + g_{{0..N/2-1}}$$\n", + "\n", + "where $\\bar m_{{0..N/2-1}}^{-1}$ is the Moore-Penrose pseudo-inverse of $m_{{0..N/2-1}}$ and $g_{{0..N/2-1}}$ guarantees the completeness of $M_j'$. Similarly, we construct the Kraus operators for every binary-outcome POVM. \n", + "\n", + "$$b_{ij} = m_{{ij}}\\bar m_{{i}}^{-1} + g_{{i}}$$\n", + "\n", + "Please refer to the original paper by [Andersson and Oi](https://arxiv.org/abs/0712.2665) for detailed proof. \n", + "\n", + "$^1$ Note that this state is not uniquely defined because of the unitary freedom $m_j \\rightarrow Um_j$." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Mid-circuit measurements \n", + "\n", + "Recently, IBM [announced](https://research.ibm.com/blog/quantum-dynamic-circuits) the support for dynamic circuits on IBM quantum devices. Dynamic circuits, as opposed to static circuits, allow to apply operations conditioned on classical outcomes, which are produced at runtime and therefore utilize mid-circuit measurements. This feature can significantly increase the variety of circuits by allowing for adaptive control and feed-forward operations.\n", + "\n", + "Dynamic circuits require the backend to support QASM3. At the time of writing, only selected backends had this support, but more will be added in the future. The list of backends that support QASM3 and are available with your provider can be obtained by setting `dynamic=True` to communicate to the backend that we want to run a dynamic circuit." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Dependent on your provider, you can have access to different quantum backends. In the following, we will retrieve publicly available devices which support dynamic circuits." + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Publicly available devices which support dynamic circuits are:\n", + "ibmq_jakarta\n", + "ibmq_manila\n", + "ibm_lagos\n", + "ibm_nairobi\n", + "ibm_perth\n", + "ibm_oslo\n" + ] + } + ], + "source": [ + "# backends supporting dynamic circuits\n", + "backends = [backend for backend in IBMProvider().backends(dynamic_circuits=True)]\n", + "print(\"Publicly available devices which support dynamic circuits are:\")\n", + "for backend in backends: print(backend.name)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To submit dynamic circuits to a quantum backend, we set `dynamic=True` when calling the `run()` function. This method invokes the `qasm3-runner`, which is a Qiskit Runtime program." + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'\\nbackend = provider.get_backend(\\'ibm_nairobi\\')\\n\\njob = backend.run(transpiled_qc, dynamic=True)\\nprint(f\"Job ID: {job.job_id}\")\\nprint(f\"Job status: {job.status()}\")\\n'" + ] + }, + "execution_count": 29, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# The following code submits binary measurement circuit to ibm_nairobi\n", + "# Uncomment it if you want to obtain hardware resultsa\n", + "'''\n", + "backend = provider.get_backend('ibm_nairobi')\n", + "\n", + "job = backend.run(transpiled_qc, dynamic=True)\n", + "print(f\"Job ID: {job.job_id}\")\n", + "print(f\"Job status: {job.status()}\")\n", + "'''" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively, one can directly submit circuits to `qasm3-runner`, which converts them to OpenQASM3, compiles, and executes them. This program can also take and execute one or more OpenQASM3 strings." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Independent of the selected method, one can retrieve the results after the job has been processed as follows:" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'\\ncounts = job.result().get_counts()\\n'" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# notice that the following call is blocking and will\n", + "# block your environment if the job is not ready\n", + "'''\n", + "counts = job.result().get_counts()\n", + "'''" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Selecting an optimal layout using mapomatic\n", + "\n", + "Given the access to different quantum backends, we want to choose the best hardware to run our circuit such that the effect of noise is minimized. In general, qubits with the longest coherence times should be preferred for the mapping. However, qubit connectivity is also essential to minimize the number of SWAP gates. However, a mapping that is optimal in terms of the number of SWAP gates may not have the best qubits. Therefore, selecting an optimal layout for your circuit is a nontrivial task. We use an open-source Qiskit extension, `mapomatic`, to find a good qubit layout. \n", + "\n", + "`mapomatic` is *\"... a post-compilation routine that finds the best low noise sub-graph on which to run a circuit given one or more quantum systems as target devices.\"* It uses a heuristic to grade different qubit layouts based on calibration data of qubits. For more on this, please refer to the [source code](https://github.com/Qiskit-Partners/mapomatic) or the [original paper](https://arxiv.org/abs/2209.15512).\n", + "\n", + "The function `best_overall_layout()` evaluates layouts based on the total error rate from gate and readout errors to find a good candidate out of multiple systems and layouts:" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'\\nmapomatic.best_overall_layout(transpiled_qc, provider.backends(), successors=True)\\n'" + ] + }, + "execution_count": 31, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import mapomatic\n", + "# Note: evaluating all available backends might block the environment for a long period\n", + "'''\n", + "mapomatic.best_overall_layout(transpiled_qc, provider.backends(), successors=True)\n", + "'''" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Implementation \n", + "\n", + "The following sections contain the Python implementation of the binary tree and Naimark's algorithms. Once you execute these sections, return to the [beginning](#beginning) of the notebook." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Implementing binary search tree circuit" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "metadata": {}, + "outputs": [], + "source": [ + "import numpy as np\n", + "import scipy\n", + "\n", + "from qiskit import QuantumCircuit, ClassicalRegister, QuantumRegister\n", + "from qiskit.extensions import UnitaryGate\n", + "\n", + "# Helper functions section:\n", + "def get_measurement_op(povm, start, end):\n", + " \"\"\"\n", + " Returns a cumulative measurement operator by grouping together\n", + " POVM elements from povm[start] to povm[end-1]\n", + " \"\"\"\n", + " return np.sum(povm[start:end],axis=0).round(5)\n", + "\n", + "def get_diagonalization(povm, start, end):\n", + " \"\"\"\n", + " Returns: \n", + " Kraus operator , diagonal and the modal matrix for a given \n", + " measurement operator by diagonalizing the measurement operator in the form:\n", + "\n", + " M = V@D@Vh such that M@M = E\n", + " \"\"\"\n", + " E = get_measurement_op(povm, start, end)\n", + " d2,V = np.linalg.eig(E)\n", + " D = np.real(np.sqrt(np.diag(d2)))\n", + " M = V@D@np.linalg.inv(V)\n", + " return M,D,V\n", + "\n", + "def get_next_level_binary_kraus_ops(povm, start, end):\n", + " \"\"\"\n", + " Computes two next level binary Kraus operators \n", + " Args:\n", + " povm: numpy array of POVM elements\n", + " start/end: indices which define the cumulative POVM element\n", + " Returns: \n", + " Two binary Kraus operators b0 and b1 which take from a higher to lower branch\n", + "\n", + " * is the Kraus operator corresponding to the current level in binary tree\n", + " * () is the Kraus operators corresponding to the left (right) branch\n", + " * asserts the completeness condition: b0@b0.T.conj() + b1@b1.T.conj() = I\n", + " * is the Moore-Penrose pseudo-inverse of \n", + " \"\"\"\n", + " mid = int(start + (end-start)/2)\n", + " # computing \n", + " M,D,V = get_diagonalization(povm, start, end)\n", + " # computing the null space of \n", + " P = np.sign(D.round(5))\n", + " Pc = np.eye(len(M))-P\n", + " Q = V@Pc@V.T.conj()\n", + " # computing \n", + " #D_inv = np.zeros_like(D)\n", + " #for i in range(len(M)):\n", + " # if D[i,i].round(5) == 0: continue\n", + " # else: D_inv[i,i] = np.real(1/D[i,i])\n", + " D_inv = np.linalg.pinv(D)\n", + " M_psinv = V@D_inv@V.T.conj()\n", + " # computing and \n", + " M0,_,_ = get_diagonalization(povm, start, mid)\n", + " M1,_,_ = get_diagonalization(povm, mid, end)\n", + " # computing and \n", + " b0 = M0@M_psinv + Q/np.sqrt(2)\n", + " b1 = M1@M_psinv + Q/np.sqrt(2)\n", + " return b0, b1\n", + "\n", + "def closest_unitary(A):\n", + " \"\"\" Calculates the unitary matrix U that is closest with respect to the\n", + " operator norm distance to the general matrix A.\n", + " \"\"\"\n", + " V, _, Wh = scipy.linalg.svd(A)\n", + " U = np.matrix(V.dot(Wh))\n", + " return U\n", + "\n", + "def closest_unitary_schur(A):\n", + " T, Z = scipy.linalg.schur(A, output='complex')\n", + " return Z @ np.diag(np.diag(T)/abs(np.diag(T))) @ Z.T.conj()\n", + "\n", + "def extend_to_unitary(b0, b1):\n", + " \"\"\" Creates a coupling unitary between the system and ancilla.\n", + "\n", + " The condition for unitary is: <0|U|0> = b0 and <1|U|0> = b1,\n", + " whereby the ancilla is projected onto states |0> and |1>.\n", + "\n", + " A two-column matrix A, with its upper left block given by b0, \n", + " and bottom left block by b1, is extended to unitary U by appending \n", + " a basis of the null space of A.\n", + " \"\"\" \n", + " A = np.concatenate((b0,b1))\n", + " u, _, _ = scipy.linalg.svd(A)\n", + " y = u[:, len(A[0]):]\n", + " U = np.hstack((A, y))\n", + " # verify U is close to unitary\n", + " assert np.allclose(U.T.conj()@U, np.eye(len(A)),atol=1e-03), \"Failed to construct U\"\n", + " return closest_unitary(U)\n", + "\n", + "def theoretical_probs(povm, state, binary_tree=False):\n", + " \"\"\" Precalculates the expected probabilities for a pure state\n", + " for the given POVM.\n", + " \"\"\" \n", + " rho = state.T.conj()@state # density matrix of the state\n", + " probs = [np.trace(povm[i]@rho).round(2).real for i in range(len(povm))] \n", + " \n", + " l = len(probs)\n", + " n = int(np.ceil(np.log2(l)))\n", + " prob_counts = {}\n", + " for i in range(l):\n", + " if binary_tree: key = np.binary_repr(i, n)[::-1]\n", + " else: key = np.binary_repr(i, n)\n", + " value = probs[i]\n", + " prob_counts[key] = value\n", + " \n", + " return prob_counts\n", + "\n", + "# Class definitions\n", + "class POVM:\n", + " \"\"\"Base class that holds an arbitrary POVM as a list of POVM elements.\n", + " \"\"\"\n", + " def __init__(self, povm):\n", + " \"\"\"\n", + " Constructor asserts that the given POVM is valid.\n", + " \"\"\"\n", + " self.povm = povm\n", + " self.N = len(povm)\n", + " self.depth = int(np.ceil(np.log2(self.N))) # required depth of the binary tree\n", + " self.povm_dim = len(povm[0]) # dimension of the POVM operators\n", + " self.n_qubits = int(np.log2(self.povm_dim)) # number of system qubits\n", + " assert self.is_valid()\n", + " def is_valid(self):\n", + " \"\"\"Verifies the hermiticity, positivity of the POVM and that\n", + " the POVM resolves the identity.\n", + " Returns:\n", + " True: if all conditions are satisfied\n", + " Raises:\n", + " Assertion Error: if one of conditions is not satisfied\n", + " \"\"\"\n", + " for E in self.povm:\n", + " assert np.allclose(E.conj().T, E), \"Some POVM elements are not hermitian\"\n", + " assert np.all(np.linalg.eigvals(E).round(3) >= 0), \"Some POVM elements are not positive semi-definite\"\n", + " assert np.allclose(sum(self.povm), np.eye(self.povm_dim)), \"POVM does not resolve the identity\"\n", + " return True\n", + "\n", + "class BinaryTreePOVM(POVM):\n", + " \"\"\"Class which implements the binary tree approach as described in https://arxiv.org/abs/0712.2665 \n", + " to contruct a POVM measurement tree. \n", + " \"\"\"\n", + " def __init__(self, povm, dual=False):\n", + " \"\"\"Creates a binary stree structure with BinaryMeasurementNode objects\n", + " stored in dictionary. The keys in the dictionary are the bitstrings \n", + " corresponding to the states of the classical register at the point when the\n", + " corresponding node has been \"reached\".\n", + "\n", + " Args:\n", + " povm: list of POVM elements\n", + " \"\"\"\n", + " super().__init__(povm)\n", + " # pad with zero operators if necessary\n", + " while np.log2(self.N)-self.depth != 0:\n", + " self.povm.append(np.zeros_like(self.povm[0]))\n", + " self.N += 1\n", + " \n", + " self.nodes = {}\n", + " self.dual = dual\n", + "\n", + " self.create_binary_tree(key=\"0\", start=0, end=self.N)\n", + " self.qc = self.construct_measurement_circuit()\n", + " def create_binary_tree(self, key, start, end):\n", + " \"\"\"Recursive method to build the measurement tree.\n", + " Terminates when the fine-grain level corresponding to the single POVM\n", + " elements is reached.\n", + "\n", + " and are the first and (last-1) indices of POVM elements\n", + " which were grouped together to obtain a cumulative coarse-grain operator. \n", + " The range [start, end) corresponds to the possible outcomes which \"sit\" in \n", + " the branches below.\n", + " \"\"\"\n", + " if start >= (end-1):\n", + " return\n", + " new_node = BinaryMeasurementNode(self.povm, key=key, start=start, end=end)\n", + " self.nodes[key] = new_node\n", + " mid = int(start + (end-start)/2)\n", + " self.create_binary_tree(new_node.left, start=start, end=mid)\n", + " self.create_binary_tree(new_node.right, start=mid, end=end) \n", + " def construct_measurement_circuit(self):\n", + " \"\"\"Contructs a quantum circuit for a given POVM by sequentially appending\n", + " coupling unitaries and measurements conditioned on the state of the\n", + " classical register . The method uses BFS traversal of the precomputed \n", + " binary measurement tree, i.e. the measurement nodes are visited in level-order.\n", + " \n", + " * Traversal terminates when the fine-grain level was reached.\n", + " * Ancilla qubit is reset before each level.\n", + " * The root node has the key \"0\".\n", + "\n", + " * The instruction is applied to the entire classical register ,\n", + " whereby the value is the key of the corresponding node - padded with zeros \n", + " from right to the length of the register - and interpreted as an integer.\n", + " \n", + " Example:\n", + " At the first level the two nodes have keys:\n", + " left = \"00\" and right = \"01\"\n", + " If the is 3 bits long, then the left/right unitary is applied if \n", + " the state of is int(\"000\",2) = 0 / int(\"010\",2) = 2\n", + " \"\"\"\n", + " system = QuantumRegister(self.n_qubits, name='system')\n", + " anc = QuantumRegister(1,name='ancilla')\n", + " cr = ClassicalRegister(self.depth)\n", + " qc = QuantumCircuit(system, anc, cr, name=\"measurement-circuit\")\n", + "\n", + " root = self.nodes[\"0\"]\n", + " U_gate = UnitaryGate(root.U, label=root.key)\n", + " qc.append(U_gate, system[:] + anc[:])\n", + " if self.dual: # works for depth = 2\n", + " qc.x(anc)\n", + " qc.measure(anc, cr[0])\n", + " if self.depth == 1: return qc\n", + " qc.x(anc).c_if(cr[0],1)\n", + " \n", + " current_level = [self.nodes[\"00\"],self.nodes[\"10\"]]\n", + "\n", + " for i in range(1,self.depth):\n", + " next_level = []\n", + " for node in current_level:\n", + " U_gate = UnitaryGate(node.U, label=node.key)\n", + " cr_state = int(node.key[:-1],2)\n", + " with qc.if_test((cr, cr_state)):\n", + " qc.append(U_gate, system[:]+anc[:])\n", + " if node.left in self.nodes: next_level.append(self.nodes[node.left])\n", + " if node.right in self.nodes: next_level.append(self.nodes[node.right])\n", + " current_level = next_level\n", + " # dual condition must be checked here for larger systems\n", + " qc.measure(anc, cr[i])\n", + " if i == self.depth-1: continue\n", + " qc.x(anc).c_if(cr[i],1) # instead of resetting apply conditional X gate\n", + " \n", + " return qc\n", + "\n", + "class BinaryMeasurementNode(POVM):\n", + " \"\"\"A BinaryMeasurementNode object is a node in the BinaryTreePOVM.\n", + " It contains:\n", + " 1. Its in the dictionary.\n", + " 2. and : the first and (last-1) indices of the accumulated \n", + " POVM elements, corresponding this node.\n", + " 3. Coupling unitary .\n", + " 4. Keys and of the two children nodes.\n", + " 5. Attributes of the POVM class: , , .\n", + " 6. Its level in the binary tree, where level of the root node is 0.\n", + " \"\"\"\n", + " def __init__(self, povm, key, start, end):\n", + " super().__init__(povm)\n", + " self.key = key\n", + " self.level = len(self.key)-1\n", + " self.start = start\n", + " self.end = end\n", + " self.left = \"0\" + self.key\n", + " self.right = \"1\" + self.key\n", + " b0, b1 = get_next_level_binary_kraus_ops(self.povm, self.start, self.end)\n", + " self.U = extend_to_unitary(b0, b1)\n", + " def __str__(self):\n", + " line1 = 'Node with the key {} at level {}\\n'.format(self.key, self.level)\n", + " line2 = 'Cumulative operator = [{},{})'.format(self.start, self.end)\n", + " line3 = 'left = {}, right = {}\\n'.format(self.left, self.right)\n", + " line4 = 'U = \\n{}\\n'.format(self.U)\n", + " return line1+line2+line3+line4" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Implementing Naimark's extension circuit" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "metadata": {}, + "outputs": [], + "source": [ + "from numpy.linalg import svd\n", + "from qiskit.visualization import plot_histogram\n", + "\n", + "def check_for_rank_one(povm):\n", + " \"\"\"\n", + " function to check if a povm is a rank-1 povm\n", + " \"\"\"\n", + " rank_one = True\n", + " for p in povm:\n", + " if np.linalg.matrix_rank(p)!=1:\n", + " rank_one = False\n", + " return rank_one\n", + " else:\n", + " continue\n", + " return rank_one\n", + " \n", + "# %%\n", + "def compute_rank_one_unitary(povm, atol=1e-13, rtol=0):\n", + " \"\"\"\n", + " This function computes the unitary that rotates the system to the Hilbert space of the ancilla\n", + " Input: POVM ---> a list of the elements of POVM\n", + " Output: Unitary matrix\n", + " \"\"\"\n", + " \n", + " # check if povm is a rank-1 povm:\n", + " assert check_for_rank_one(povm), \"This is not a rank-1 povm\"\n", + " new_povm = []\n", + " for p in povm:\n", + " if np.log2(len(povm))%2==0: #still under investigation\n", + " w, v = np.linalg.eig(p)\n", + " else: \n", + " w, v = np.linalg.eigh(p) #note the that the eigenvenvector is computer for hermitian eigh\n", + " for eigenvalue, engenvector in zip(w,v):\n", + " if np.isclose(np.abs(eigenvalue), 0):\n", + " continue\n", + " else:\n", + " new_p = np.sqrt(eigenvalue)*engenvector\n", + " new_povm.append(new_p)\n", + " v = np.vstack(new_povm) # arrange the povm elements to form a matrix of dimension: Row X Col*len(povm)\n", + " v = np.atleast_2d(v.T) # convert to 2d matrix\n", + " \n", + " u, s, vh = svd(v) # apply svd\n", + " tol = max(atol, rtol * s[0])\n", + " nnz = (s >= tol).sum()\n", + " ns = vh[nnz:] # missing rows of v\n", + " \n", + " # add the missing rows of v to v\n", + " V = np.vstack((v, ns)) \n", + " \n", + " \n", + " # make the unitary a square matrix of dimension N=2^n where n = int(np.ceil(np.log(V.shape[0])))\n", + " n = int(np.ceil(np.log2(V.shape[0])))\n", + " N = 2**n # dimension of system and ancilla Hilber space\n", + " r,c = V.shape \n", + " \n", + " U = np.eye(N, dtype=complex) # initialize Unitary matrix to the identity. Ensure it is complex\n", + " U[:r,:c] = V[:r,:c] # assign all the elements of V to the corresponding elements of U\n", + " \n", + " U = U.conj().T # Transpose the unitary so that the rows are the povm\n", + " \n", + " # check for unitarity of U\n", + " assert np.allclose(U.T.conj()@U, np.eye(N),atol=1e-13), \"Failed to construct U\"\n", + " \n", + " return U\n", + " \n", + "# %%\n", + "# Using the original unitary generator\n", + "\n", + "def compute_full_rank_unitary(povm, atol=1e-13, rtol=0):\n", + " \"\"\"\n", + " This function computes the unitary that rotates the system to the Hilbert space of the ancilla\n", + " Input: POVM ---> a list of the elements of POVM\n", + " Output: Unitary matrix\n", + " \"\"\"\n", + " \n", + " \n", + " # Here square root of the POVM elements were used as a replacement for the vector that form the povm\n", + " povm = [sqrtm(M)for M in povm]\n", + " \n", + " v = np.hstack(povm) # arrange the povm elements to form a matrix of dimension: Row X Col*len(povm)\n", + " v = np.atleast_2d(v) # convert to 2d matrix\n", + " u, s, vh = svd(v) # apply svd\n", + " tol = max(atol, rtol * s[0])\n", + " nnz = (s >= tol).sum()\n", + " ns = vh[nnz:] # missing rows of v\n", + " \n", + " # add the missing rows of v to v\n", + " V = np.vstack((v, ns)) \n", + " \n", + " \n", + " # make the unitary a square matrix of dimension N=2^n where n = int(np.ceil(np.log(V.shape[0])))\n", + " n = int(np.ceil(np.log2(V.shape[0])))\n", + " N = 2**n # dimension of system and ancilla Hilber space\n", + " r,c = V.shape \n", + " \n", + " U = np.eye(N, dtype=complex) # initialize Unitary matrix to the identity. Ensure it is complex\n", + " U[:r,:c] = V[:r,:c] # assign all the elements of V to the corresponding elements of U\n", + " \n", + " U = U.conj().T # Transpose the unitary so that the rows are the povm\n", + " \n", + " # check for unitarity of U\n", + " assert np.allclose(U.T.conj()@U, np.eye(N),atol=1e-07), \"Failed to construct U\"\n", + " \n", + " return U\n", + "\n", + "# %%\n", + "def rank_one_circuit(povm, state, U):\n", + " \n", + " # Define the quantum and classical registers\n", + " dim_system = state.shape[1] # dimension of state\n", + " num_system_qubit = int(np.ceil(np.log2(dim_system))) # total number of qubits for system\n", + "\n", + " system_reg = QuantumRegister(num_system_qubit, name='system') # system register\n", + "\n", + " N = U.shape[0] # Dimension of the unitary to be applied to system and ancilla\n", + "\n", + " num_ancilla_qubit = int(np.ceil(np.log2(N))) - num_system_qubit # total number of qubits for system\n", + "\n", + " ancilla_reg = QuantumRegister(num_ancilla_qubit, name='ancilla') # ancilla register\n", + "\n", + " U_gate = UnitaryGate(U, label='U') # unitary gate to be applied between system and ancilla\n", + " \n", + " \n", + " # create the quantum circuit for the system and ancilla\n", + " qc = QuantumCircuit(system_reg, ancilla_reg, name='circuit')\n", + " qc.initialize(state[0],system_reg)\n", + "\n", + " # reset ancilla to zero\n", + " qc.reset(ancilla_reg)\n", + "\n", + " # append the unitary gate\n", + " qc.append(U_gate, range(system_reg.size + ancilla_reg.size))\n", + "\n", + " # measure only the ancilliary qubits\n", + " qc.measure_all()\n", + " \n", + " return qc\n", + "\n", + "# %%\n", + "def full_rank_circuit(povm, state, U):\n", + " \n", + " # Define the quantum and classical registers\n", + " dim_system = state.shape[1] # dimension of state\n", + " num_system_qubit = int(np.ceil(np.log2(dim_system))) # total number of qubits for system\n", + "\n", + " system_reg = QuantumRegister(num_system_qubit, name='system') # system register\n", + "\n", + " N = U.shape[0] # Dimension of the unitary to be applied to system and ancilla\n", + "\n", + " num_ancilla_qubit = int(np.ceil(np.log2(N))) - num_system_qubit # total number of qubits for system\n", + "\n", + " ancilla_reg = QuantumRegister(num_ancilla_qubit, name='ancilla') # ancilla register\n", + "\n", + " classical_reg = ClassicalRegister(num_ancilla_qubit, name='measure') # classical register\n", + "\n", + " U_gate = UnitaryGate(U, label='U') # unitary gate to be applied between system and ancilla\n", + " \n", + " \n", + " # create the quantum circuit for the system and ancilla\n", + " qc = QuantumCircuit(system_reg, ancilla_reg, classical_reg, name='circuit')\n", + " qc.initialize(state[0],system_reg)\n", + "\n", + " # reset ancilla to zero\n", + " qc.reset(ancilla_reg)\n", + "\n", + " # append the unitary gate\n", + " qc.append(U_gate, range(system_reg.size + ancilla_reg.size))\n", + "\n", + " # measure only the ancilliary qubits\n", + " qc.measure(ancilla_reg, classical_reg)\n", + " \n", + " return qc\n", + "\n", + "# %%\n", + "def construct_quantum_circuit(povm, state):\n", + " \n", + " # compute unitary matrix\n", + " if check_for_rank_one(povm):\n", + " U = compute_rank_one_unitary(povm)\n", + " qc = rank_one_circuit(povm, state, U)\n", + " else:\n", + " U = compute_full_rank_unitary(povm)\n", + " qc = full_rank_circuit(povm, state, U)\n", + " \n", + " return qc\n", + "\n", + "# %%\n", + "def draw_circuit(qc, idle_wires=True):\n", + " \"\"\"\n", + " This functions draws the naimark extension quantum circuit\n", + " \"\"\"\n", + " \n", + " return qc.draw(output='mpl', idle_wires=idle_wires)\n", + "\n", + "def naimark_plot(povm, state, counts, names, save=False, file_name=\"povm_output.pdf\"): \n", + " theory_count = theoretical_probs(povm, state)\n", + " count_list = [theory_count]\n", + " #legend_list = [\"Theoretical result\"]\n", + " legend_list = ['Theory (t)']\n", + " \n", + " for count, name in zip(counts, names):\n", + " count_list.append(count)\n", + " legend_list.append(name)\n", + " \n", + " fig = plot_histogram(count_list, legend=legend_list, bar_labels=True)\n", + " ax = fig.axes[0]\n", + " title = f\"Tetrad POVM with Naimark's extension approach\"\n", + " ax.set_title(title, fontsize=12)\n", + " ax.set_ylabel('Probabilities', fontsize=12)\n", + " ax.set_xlabel('POVM elements', fontsize=12)\n", + " \n", + " x_lables = []\n", + " for i in range(len(povm)):\n", + " x_lables.append(\"M\"+str(i))\n", + " ax.set_xticks(range(len(povm)))\n", + " ax.set_xticklabels(x_lables)\n", + " \n", + " ax.legend(fontsize=12)\n", + " fig.tight_layout()\n", + " \n", + " if save:\n", + " fig.savefig(file_name)\n", + " \n", + " \n", + " return fig" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Qiskit version and copyright " + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "

Version Information

Qiskit SoftwareVersion
qiskit-terra0.22.3
qiskit-aer0.11.2
qiskit-ibmq-provider0.19.2
qiskit0.39.4
System information
Python version3.8.8
Python compilerMSC v.1916 64 bit (AMD64)
Python builddefault, Apr 13 2021 15:08:03
OSWindows
CPUs4
Memory (Gb)7.857898712158203
Wed Jan 11 12:10:31 2023 W. Europe Standard Time
" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "

This code is a part of Qiskit

© Copyright IBM 2017, 2023.

This code is licensed under the Apache License, Version 2.0. You may
obtain a copy of this license in the LICENSE.txt file in the root directory
of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.

Any modifications or derivative works of this code must retain this
copyright notice, and modified files need to carry a notice indicating
that they have been altered from the originals.

" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import qiskit.tools.jupyter\n", + "%qiskit_version_table\n", + "%qiskit_copyright" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3.8.8 ('qiskit_env': venv)", + "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.8.8" + }, + "vscode": { + "interpreter": { + "hash": "d40343b2b8fe07cae983373af2e631c3feb542de4b1fdf9434c5290f2e9f60fc" + } + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}