{ "cells": [ { "cell_type": "code", "execution_count": 1, "id": "a19a0fb1", "metadata": { "execution": { "iopub.execute_input": "2024-03-26T19:01:54.460790Z", "iopub.status.busy": "2024-03-26T19:01:54.460519Z", "iopub.status.idle": "2024-03-26T19:01:54.463034Z", "shell.execute_reply": "2024-03-26T19:01:54.462623Z" }, "nbsphinx": "hidden" }, "outputs": [], "source": [ "# Copyright 2024 Keysight Technologies Inc." ] }, { "cell_type": "raw", "id": "77c8f550", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Example: Emulating a device from measured error profiles\n", "========================================================\n", "\n", "In this example, we will see how to use the data from error diagnostics\n", "routines to construct a realistic emulator of a quantum processor.\n", "\n", "For the sake of this example, the device in question will also be a simulator.\n", "To avoid confusion, we will name it ``device``. Our device will be a\n", "minimalistic 3-qubit processor vulnerable to 2 noise sources. The first source\n", "consists of relaxation processes, and the second source consists of unitary\n", "overrotations of the entangling operations. The overrotation percentages are\n", "different for each of the two possible entanglers. This first code block deals\n", "only with initializing the ``device`` simulator; if you are interested solely\n", "in creating an emulator from KNR data retrieved from a device or simulator,\n", "skip to :ref:`this subsection `\\." ] }, { "cell_type": "code", "execution_count": 2, "id": "372f4004", "metadata": { "execution": { "iopub.execute_input": "2024-03-26T19:01:54.464951Z", "iopub.status.busy": "2024-03-26T19:01:54.464664Z", "iopub.status.idle": "2024-03-26T19:01:56.731614Z", "shell.execute_reply": "2024-03-26T19:01:56.731202Z" } }, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import matplotlib.pyplot as plt\n", "import trueq as tq\n", "import trueq.simulation as tqs\n", "\n", "# initiate a simulator\n", "device = tq.Simulator()\n", "\n", "# define time scales for single- and two-qubit gates\n", "t_single_qb_gate = 50e-9\n", "# 50 ns single-qubit gates\n", "t_entangling_gate = 450e-9\n", "# 450 ns entangling gates\n", "\n", "# define time scales for relaxation processes\n", "t1 = 100e-6 # 100 us population relaxation time\n", "t2 = 100e-6 # 100 us phase relaxation time\n", "\n", "# add a relaxation noise source based on the time scales above\n", "device.add_relaxation(\n", " t1=t1, t2=t2, t_single=t_single_qb_gate, t_multi=t_entangling_gate\n", ")\n", "\n", "# define matches for introducing entangling operations with different fidelities\n", "entangler_01_match = tqs.LabelMatch((0, 1)) & tqs.GateMatch(tq.Gate.cx)\n", "entangler_12_match = tqs.LabelMatch((1, 2)) & tqs.GateMatch(tq.Gate.cx)\n", "\n", "# add different unitary overrotation noise sources depending on the entangler\n", "device.add_overrotation(multi_sys=0.12, match=entangler_01_match)\n", "device.add_overrotation(multi_sys=0.08, match=entangler_12_match)" ] }, { "cell_type": "raw", "id": "1d2f6ca9", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Acquiring error profiles\n", "------------------------\n", "\n", "Now that our device is properly defined, let's pretend that we don't know the\n", "underlying error profile, and that we wish to learn it. To do so, let's\n", "perform typical :tqdoc:`KNR` experiments on two hard cycles, each defined\n", "respectively by a :math:`{\\rm CNOT}` operation between qubit :math:`0`\n", "(control) and :math:`1` (target) and by a :math:`{\\rm CNOT}` operation between\n", "qubit :math:`1` (control) and :math:`2` (target). Since the former has a\n", "significantly worse infidelity than the latter (as seen in the device\n", "simulator above), their respective KNR sequences necessitate slightly\n", "different numbers of random cycles to yield better estimates (see the\n", ":doc:`../error_diagnostics/parameter_selection` example)." ] }, { "cell_type": "code", "execution_count": 3, "id": "a03ab267", "metadata": { "execution": { "iopub.execute_input": "2024-03-26T19:01:56.733775Z", "iopub.status.busy": "2024-03-26T19:01:56.733398Z", "iopub.status.idle": "2024-03-26T19:02:04.264340Z", "shell.execute_reply": "2024-03-26T19:02:04.263896Z" } }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# define the twirl over all three qubits to ensure thorough diagnostics\n", "twirl = tq.Twirl(\"P\", (0, 1, 2))\n", "\n", "# define the cycles of interest for the diagnostics\n", "cycle1 = tq.Cycle({(0, 1): tq.Gate.cx})\n", "cycle2 = tq.Cycle({(1, 2): tq.Gate.cx})\n", "\n", "# initialize a circuit collection with KNR circuits to characterize each hard cycle\n", "knr_circuits = tq.make_knr(\n", " cycle1, n_random_cycles=[4, 16, 24], n_circuits=30, subsystems=1, twirl=twirl\n", ")\n", "knr_circuits += tq.make_knr(\n", " cycle2, n_random_cycles=[4, 24, 32], n_circuits=30, subsystems=1, twirl=twirl\n", ")\n", "\n", "# run the circuits on our device\n", "device.run(knr_circuits, n_shots=1e4)\n", "\n", "# plot the error profile:\n", "layout = tq.visualization.Graph.linear(3, show_labels=True) # specify the chip layout\n", "knr_circuits.plot.knr_heatmap(layout) # plot the heatmap" ] }, { "cell_type": "raw", "id": "0f2a55db", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "In the :tqdoc:`KNR` heatmap above, we can see the reconstructed error profile\n", "for each of the two hard cycles of interest. The labels on the left (e.g.\n", ":math:`ZI`\\) indicate specific errors, and the heatmap associates those errors\n", "with a probability. The cycle whose noise profile is plotted on the left,\n", "``cycle1``, is significantly noisier than ``cycle2``, with some errors\n", "reaching a probability of roughly :math:`1.2\\%`\\. Note that the accuracy of\n", "the emulator is limited by the quality of the error diagnostics. For\n", "instance, in the above reconstructed map, some error probabilities have an\n", "uncertainty associated to them, as observed by the varying color spectrum in\n", "each of the heatmap's cells. Moreover, certain errors are sometimes conflated\n", "(e.g. :math:`\\{IZ,ZZ\\}`\\), meaning that the diagnostic protocol couldn't\n", "distinguish which of the errors occured. In our case, the conflated errors\n", "are not expected to be a problem because they occur with very low probability\n", "compared to the dominant errors.\n", "\n", ".. _make_emulator:\n", "\n", "Using the reconstructed error profiles to make an emulator\n", "----------------------------------------------------------\n", "\n", "Once the :tqdoc:`KNR` circuits are run, an emulator can be easily constructed\n", "by instantiating a new :py:class:`~trueq.Simulator` and adding the measured\n", "error profile via the :py:meth:`~trueq.Simulator.add_knr_noise` method:" ] }, { "cell_type": "code", "execution_count": 4, "id": "71406d7e", "metadata": { "execution": { "iopub.execute_input": "2024-03-26T19:02:04.266583Z", "iopub.status.busy": "2024-03-26T19:02:04.266183Z", "iopub.status.idle": "2024-03-26T19:02:04.354962Z", "shell.execute_reply": "2024-03-26T19:02:04.354566Z" } }, "outputs": [], "source": [ "emulator = tq.Simulator().add_knr_noise(knr_circuits)" ] }, { "cell_type": "raw", "id": "5a248096", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "To see if our ``emulator`` correctly mimics the ``device``, let's submit a\n", "circuit to each and compare the distribution of results. In this example, we\n", "choose a circuit that ideally produces a GHZ state :math:`|\\psi\\rangle = (|\n", "000\\rangle+ | 111 \\rangle)/\\sqrt{2}`\\:" ] }, { "cell_type": "code", "execution_count": 5, "id": "13fbdda8", "metadata": { "execution": { "iopub.execute_input": "2024-03-26T19:02:04.356964Z", "iopub.status.busy": "2024-03-26T19:02:04.356610Z", "iopub.status.idle": "2024-03-26T19:02:04.385908Z", "shell.execute_reply": "2024-03-26T19:02:04.385541Z" } }, "outputs": [ { "data": { "text/html": [ "
0 1 2 Key: Labels: (0,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: 127.28 X: 127.28 0.71 0.71 0.71 -0.71 H Labels: (0, 1) Name: Gate.cx Aliases: Gate.cx Gate.cnot Locally Equivalent: CNOT Generators: ZX: -90.00 IX: 90.00 ZI: 90.00 1.00 1.00 1.00 1.00 CX CX Labels: (1, 2) Name: Gate.cx Aliases: Gate.cx Gate.cnot Locally Equivalent: CNOT Generators: ZX: -90.00 IX: 90.00 ZI: 90.00 1.00 1.00 1.00 1.00 CX CX 1 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M
" ], "text/plain": [ "DisplayWrapper(" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "tq.visualization.plot_results(\n", " device_results, emulator_results, labels=[\"Device\", \"Emulator\"]\n", ")\n", "\n", "plt.gca().set_yscale(\"log\")" ] }, { "cell_type": "raw", "id": "e55cf23f", "metadata": { "raw_mimetype": "text/restructuredtext" }, "source": [ "Notice that the ``emulator`` and the ``device`` yield very similar output\n", "distributions. Of course, the two histograms differ slightly, and this can be\n", "due to two causes. First, the results displayed in the histograms were\n", "obtained from finite measurement samples, and are therefore susceptible to\n", "small statistical deviations. Due to the logarithmic scaling of the plot,\n", "these statistical deviations are visually amplified for unlikely outcomes such\n", "as :math:`010` and :math:`101`\\. Second, the emulator originates from\n", "approximated error profiles. Small inaccuracies in the reconstructed error\n", "profiles may in turn yield small inaccuracies in the emulator." ] } ], "metadata": { "jupytext": { "cell_metadata_filter": "raw_mimetype,nbsphinx,-all", "main_language": "python", "notebook_metadata_filter": "-all", "text_representation": { "extension": ".py", "format_name": "percent" } }, "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.10" } }, "nbformat": 4, "nbformat_minor": 5 }