{ "cells": [ { "cell_type": "code", "execution_count": 1, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:25.275261Z", "iopub.status.busy": "2025-05-30T09:55:25.275031Z", "iopub.status.idle": "2025-05-30T09:55:25.279108Z", "shell.execute_reply": "2025-05-30T09:55:25.278521Z" }, "id": "906e07f6e562" }, "outputs": [], "source": [ "# @title Copyright 2022 The Cirq Developers\n", "# Licensed under the Apache License, Version 2.0 (the \"License\");\n", "# you may not use this file except in compliance with the License.\n", "# You may obtain a copy of the License at\n", "#\n", "# https://www.apache.org/licenses/LICENSE-2.0\n", "#\n", "# Unless required by applicable law or agreed to in writing, software\n", "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", "# See the License for the specific language governing permissions and\n", "# limitations under the License." ] }, { "cell_type": "markdown", "metadata": { "id": "19599098c1f9" }, "source": [ "# Introduction to Cirq" ] }, { "cell_type": "markdown", "metadata": { "id": "8bd3406cf99e" }, "source": [ "\n", " \n", " \n", " \n", " \n", "
\n", " View on QuantumAI\n", " \n", " Run in Google Colab\n", " \n", " View source on GitHub\n", " \n", " Download notebook\n", "
" ] }, { "cell_type": "markdown", "metadata": { "id": "8m9ye4AS6dE4" }, "source": [ "[Cirq](https://github.com/quantumlib/cirq) is a framework for writing quantum algorithms for noisy intermediate-scale quantum (NISQ) devices. Roughly speaking, NISQ devices are those with O(100) qubits that can enact O(1000) gates. Because the resources for NISQ devices are so constrained, we believe that a framework for writing programs on these devices needs to be aware of all of the architectural properties of the device on which the algorithm is written. This is in contrast to other frameworks where there is a clean separation between the abstract model being used and the details of the device. \n", "\n", "In this tutorial we will walk through the basics of writing quantum algorithms in Cirq. Our final goal will be to write a variational ansatz for use in an optimization algorithm." ] }, { "cell_type": "markdown", "metadata": { "id": "cc948e49cecb" }, "source": [ "# Installing Cirq" ] }, { "cell_type": "markdown", "metadata": { "id": "rPgPbry6-mF3" }, "source": [ "To use Cirq one first needs to install Cirq. Installation instructions are available at [https://quantumai.google/cirq/start/install](https://quantumai.google/cirq/start/install). For the purpose of this tutorial, we run `pip install cirq` as shown in the following code cell to install the latest release of Cirq. \n", "\n", "> Different notebook execution systems exist, but for most part they have \"run\" button on a cell which you can click, or \"shift + enter\" is often the shortcut to run the cell. \n" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:25.282273Z", "iopub.status.busy": "2025-05-30T09:55:25.282046Z", "iopub.status.idle": "2025-05-30T09:55:39.966124Z", "shell.execute_reply": "2025-05-30T09:55:39.965377Z" }, "id": "RlJBDvNgC00H" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "installing cirq...\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "\u001b[31mERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.\r\n", "tensorflow-metadata 1.17.1 requires protobuf<4.22,>=4.21.6; python_version < \"3.11\", but you have protobuf 5.29.5 which is incompatible.\u001b[0m\u001b[31m\r\n", "\u001b[0m" ] }, { "name": "stdout", "output_type": "stream", "text": [ "installed cirq.\n" ] } ], "source": [ "try:\n", " import cirq\n", "except ImportError:\n", " print(\"installing cirq...\")\n", " !pip install --quiet cirq\n", " print(\"installed cirq.\")\n", " import cirq\n", "\n", "import matplotlib.pyplot as plt\n", "import numpy as np" ] }, { "cell_type": "markdown", "metadata": { "id": "GPjUqrK8DJTq" }, "source": [ "Let's check that Cirq has been successfully installed by importing Cirq and printing out a diagram of Google's Sycamore device.\n", "\n", "\n", "![Google's Sycamore chip](https://4.bp.blogspot.com/-b9akad6ismU/WpmyaJo-cYI/AAAAAAAACa8/mCqPBJxv5oUivy6Jq42FSOQYkeRlTmkiwCLcBGAs/s1600/image1.png)" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:39.970094Z", "iopub.status.busy": "2025-05-30T09:55:39.969664Z", "iopub.status.idle": "2025-05-30T09:55:40.443330Z", "shell.execute_reply": "2025-05-30T09:55:40.442624Z" }, "id": "FTrmLyq4C2gf" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " (0, 5)───(0, 6)\n", " │ │\n", " │ │\n", " (1, 4)───(1, 5)───(1, 6)───(1, 7)\n", " │ │ │ │\n", " │ │ │ │\n", " (2, 3)───(2, 4)───(2, 5)───(2, 6)───(2, 7)───(2, 8)\n", " │ │ │ │ │ │\n", " │ │ │ │ │ │\n", " (3, 2)───(3, 3)───(3, 4)───(3, 5)───(3, 6)───(3, 7)───(3, 8)───(3, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", " (4, 1)───(4, 2)───(4, 3)───(4, 4)───(4, 5)───(4, 6)───(4, 7)───(4, 8)───(4, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", "(5, 0)───(5, 1)───(5, 2)───(5, 3)───(5, 4)───(5, 5)───(5, 6)───(5, 7)───(5, 8)\n", " │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │\n", " (6, 1)───(6, 2)───(6, 3)───(6, 4)───(6, 5)───(6, 6)───(6, 7)\n", " │ │ │ │ │\n", " │ │ │ │ │\n", " (7, 2)───(7, 3)───(7, 4)───(7, 5)───(7, 6)\n", " │ │ │\n", " │ │ │\n", " (8, 3)───(8, 4)───(8, 5)\n", " │\n", " │\n", " (9, 4)\n" ] } ], "source": [ "\"\"\"Test successful installation by printing out the Sycamore device.\"\"\"\n", "\n", "import cirq_google\n", "\n", "print(cirq_google.Sycamore)" ] }, { "cell_type": "markdown", "metadata": { "id": "09zRgohCMiBs" }, "source": [ "This cell should run successfully, and the output should in fact be the grid of qubits for the Sycamore device. If so, the install worked!\n" ] }, { "cell_type": "markdown", "metadata": { "id": "3340594dd8c1" }, "source": [ "# Qubits, Operations, Moments and Circuits" ] }, { "cell_type": "markdown", "metadata": { "id": "8A7a3jcql1l5" }, "source": [ "In Cirq, circuits are represented by a `Circuit` object. Conceptually:\n", "\n", "- A `Circuit` is a collection of `Moment`s. \n", "- A `Moment` is a collection of `Operation`s that all act during the same abstract time slice. \n", "- An `Operation` is an effect that operates on a specific subset of Qubits. \n", " - The most common type of `Operation` is a `Gate` applied to several qubits (a \"`GateOperation`\"). \n", "- The `Qubit`s of a circuit are implicitly defined by the operations - you can't allocate qubits to a Circuit.\n", " " ] }, { "cell_type": "markdown", "metadata": { "id": "03b7d753ecd5" }, "source": [ "" ] }, { "cell_type": "markdown", "metadata": { "id": "ca7d9d7b3953" }, "source": [ "These ideas are illustrated by the above diagram, where time goes from left to right, horizontal lines are different qubits, operations acting on qubits are the boxes (sometimes spanning multiple qubits) and a moment is a group of operations that \"happen at the same time\". " ] }, { "cell_type": "markdown", "metadata": { "id": "9768d38c9151" }, "source": [ "## Create a `Circuit`" ] }, { "cell_type": "markdown", "metadata": { "id": "VFwmWPf7D057" }, "source": [ "A typical way to create a `Circuit` is shown below." ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.447011Z", "iopub.status.busy": "2025-05-30T09:55:40.446595Z", "iopub.status.idle": "2025-05-30T09:55:40.453608Z", "shell.execute_reply": "2025-05-30T09:55:40.452967Z" }, "id": "pE88WsFeDGfs" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", "a: ───H───────────\n", "\n", "b: ───H───@───H───\n", " │\n", "c: ───────X───────\n" ] } ], "source": [ "\"\"\"Creating a circuit.\"\"\"\n", "\n", "# Define three qubits.\n", "a = cirq.NamedQubit(\"a\")\n", "b = cirq.NamedQubit(\"b\")\n", "c = cirq.NamedQubit(\"c\")\n", "\n", "# Define a list of operations.\n", "ops = [cirq.H(a), cirq.H(b), cirq.CNOT(b, c), cirq.H(b)]\n", "\n", "# Create a circuit from the list of operations.\n", "circuit = cirq.Circuit(ops)\n", "print(\"Circuit:\\n\")\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "j0qHxsoyIrcj" }, "source": [ "## Exercise: Create a Circuit\n", "\n", "Write a program to create the following circuit.\n", "\n", "```\n", " ┌──┐\n", "0: ───H─────@────────\n", " │\n", "1: ───H────@┼────H───\n", " ││\n", "2: ────────X┼────────\n", " │\n", "3: ─────────X────────\n", " └──┘\n", "```\n", "\n", "Note that the circuit has a total of 3 different moments." ] }, { "cell_type": "code", "execution_count": 5, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.456589Z", "iopub.status.busy": "2025-05-30T09:55:40.456028Z", "iopub.status.idle": "2025-05-30T09:55:40.459439Z", "shell.execute_reply": "2025-05-30T09:55:40.458813Z" }, "id": "6a5TEN5bKAPz" }, "outputs": [], "source": [ "# @title Attempt the solution here\n", "\n", "# Define 4 qubits.\n", "\n", "# Define a list of operations.\n", "\n", "# Create a circuit from the list of operations." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.461930Z", "iopub.status.busy": "2025-05-30T09:55:40.461670Z", "iopub.status.idle": "2025-05-30T09:55:40.468840Z", "shell.execute_reply": "2025-05-30T09:55:40.468109Z" }, "id": "Q52e1pX_JIdi" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", " ┌──┐\n", "0: ───H─────@────────\n", " │\n", "1: ───H────@┼────H───\n", " ││\n", "2: ────────X┼────────\n", " │\n", "3: ─────────X────────\n", " └──┘\n" ] } ], "source": [ "# @title Expand to view the solution\n", "\"\"\"Creating a circuit.\"\"\"\n", "# Define four line qubits. NamedQubits would also work, however this demonstrates a more succint syntax.\n", "q = cirq.LineQubit.range(4)\n", "\n", "# Define a list of operations.\n", "ops = [cirq.H(q[0]), cirq.H(q[1]), cirq.CNOT(q[1], q[2]), cirq.CNOT(q[0], q[3]), cirq.H(q[1])]\n", "\n", "# Create a circuit from the list of operations.\n", "print(\"Circuit:\\n\")\n", "print(cirq.Circuit(ops))" ] }, { "cell_type": "markdown", "metadata": { "id": "-06jQwEdI4DJ" }, "source": [ "## Unpacking the circuit\n", "We can unpack this a bit and see all of the components for the circuit.\n", "\n", "The first thing we do is pick some qubits to use. There are many different types of qubits in Cirq, and you can define your own by inheriting from the `cirq.Qid` class. There's nothing inherently special or magical about these quantum id types such as `cirq.NamedQubit`. They simply identify what you wish to operate on, which is relevant when you are targeting a specific device. For example, if we were creating a circuit for the Sycamore device and wanted to refer to the qubit in the left-most position, we would use `cirq.GridQubit(5, 0)`. (See the first diagram of the Sycamore device we printed out.) For simplicity, in the previous cell we defined `cirq.NamedQubit`s which are simply qubits that can be identified by a name.\n", "\n", "Next, we encounter the object `cirq.H` which is a Hadamard gate with unitary\n", "\n", "$$\n", "H = {1 \\over \\sqrt{2}} \\left[ \\begin{array}[cc] & 1 & 1 \\\\ 1 & -1 \\end{array}\\right] .\n", "$$\n", "\n", "In Cirq, `cirq.H` is an instance of the `cirq.HPowGate` class, which itself is a subclass of `Gate` (along with other classes). We can use Cirq to see the unitary matrix of `Gate` objects as follows." ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.471713Z", "iopub.status.busy": "2025-05-30T09:55:40.471147Z", "iopub.status.idle": "2025-05-30T09:55:40.478588Z", "shell.execute_reply": "2025-05-30T09:55:40.477948Z" }, "id": "YKfg575v1DQB" }, "outputs": [ { "data": { "text/plain": [ "array([[ 0.70710678+0.j, 0.70710678+0.j],\n", " [ 0.70710678+0.j, -0.70710678+0.j]])" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"\"\"Get the unitary of a gate, here the Hadamard gate.\"\"\"\n", "\n", "cirq.unitary(cirq.H)" ] }, { "cell_type": "markdown", "metadata": { "id": "hJMAciW21KEg" }, "source": [ "We see that this agrees with the unitary for the Hadamard gate above.\n", "\n", "`Gate` objects have the ability to be applied \"on\" one or more qubits. There are two ways to do this for gates, either using the `on` method or by directly calling the gate on the qubits as if the gate were a function and the qubits were arguments. For example to apply the `H` on qubit `a` we can say `cirq.H.on(a)` or `cirq.H(a)`.\n", "\n", "The result of those expressions is typically a `GateOperation` object, which is a type of `Operation`.\n", "\n", "> **Note**: In Cirq, there is a strong distinction between `Operation`s and `Gate`s. An `Operation` is associated with specific qubits and can be put in `Circuit`s. A `Gate` has unspecified qubits, and will produce an operation when acting on qubits.\n", "\n", "Once you have a collection of operations, you can construct a `Circuit` by passing the operations into the constructor for a `Circuit`:\n", "\n", "```\n", "ops = [list of operations]\n", "circuit = cirq.Circuit(ops)\n", "```\n", "\n", "The last thing we did in the example code was use the (surprisingly useful) ability to print the circuit as a text diagram.\n", "\n", "The diagram is visually helpful, but it doesn't really get into the internal details of how the `Circuit` is represented. As mentioned, a `Circuit` is made up of a sequence of `Moment` objects, and each `Moment` object is a list of non-overlapping `Operation`s. To see this internal structure, we can iterate over the `Moment`s in the `Circuit` and print them out." ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.481064Z", "iopub.status.busy": "2025-05-30T09:55:40.480834Z", "iopub.status.idle": "2025-05-30T09:55:40.486858Z", "shell.execute_reply": "2025-05-30T09:55:40.486293Z" }, "id": "hH-y4JiEMv25" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", "a: ───H───────────\n", "\n", "b: ───H───@───H───\n", " │\n", "c: ───────X───────\n", "\n", "Moments in the circuit:\n", "\n", "Moment 0: \n", " ╷ None\n", "╶─┼──────\n", "a │ H\n", " │\n", "b │ H\n", " │\n", "Moment 1: \n", " ╷ None\n", "╶─┼──────\n", "b │ @\n", " │ │\n", "c │ X\n", " │\n", "Moment 2: \n", " ╷ None\n", "╶─┼──────\n", "b │ H\n", " │\n" ] } ], "source": [ "\"\"\"Print out the moments in a circuit.\"\"\"\n", "\n", "print(\"Circuit:\\n\")\n", "print(circuit)\n", "\n", "# Inspecting individual moments.\n", "print(\"\\nMoments in the circuit:\\n\")\n", "for i, moment in enumerate(circuit):\n", " print(f'Moment {i}: \\n{moment}')" ] }, { "cell_type": "markdown", "metadata": { "id": "pm5iC7MNQY6-" }, "source": [ "We see that this circuit consists of three moments. For even more on the underlying structure of a circuit, we can print the circuit's `repr`. This returns a more detailed (and usually less readable) expression." ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.489227Z", "iopub.status.busy": "2025-05-30T09:55:40.489010Z", "iopub.status.idle": "2025-05-30T09:55:40.492594Z", "shell.execute_reply": "2025-05-30T09:55:40.492033Z" }, "id": "2Y6zG_peQG1y" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "cirq.Circuit([\n", " cirq.Moment(\n", " cirq.H(cirq.NamedQubit('a')),\n", " cirq.H(cirq.NamedQubit('b')),\n", " ),\n", " cirq.Moment(\n", " cirq.CNOT(cirq.NamedQubit('b'), cirq.NamedQubit('c')),\n", " ),\n", " cirq.Moment(\n", " cirq.H(cirq.NamedQubit('b')),\n", " ),\n", "])\n" ] } ], "source": [ "\"\"\"Print the repr of a circuit.\"\"\"\n", "\n", "print(repr(circuit))" ] }, { "cell_type": "markdown", "metadata": { "id": "zyVbU8yfW_qi" }, "source": [ "Although it is less readable, the usefulness of printing the `repr` is that it includes *all* the gory details which can be useful when debugging. The `repr` is also a valid python expression that evaluates to the circuit.\n", "For example, if we notice that a circuit generated in some complicated way triggers a bug in a simulator, copy-pasting the generated circuit's `repr` into a test, and then working from there, is a simple way to decouple the reproduction of the bug from the circuit generation code." ] }, { "cell_type": "markdown", "metadata": { "id": "0bb8611c3865" }, "source": [ "## More ways to create `Circuit`s" ] }, { "cell_type": "markdown", "metadata": { "id": "uaDb6B_jPgrb" }, "source": [ "Above we created a `Circuit` by passing in a list of operations to its constructor. In Cirq, there are many ways to construct and modify circuits, and each of these is useful in different contexts. Here are a few examples:\n", "\n", "\n", "1. `Circuit(...)`: This is the simplest way to make a circuit. Give this method some operations, and out pops a circuit.\n", "2. `append`: `Circuit`s are mutable. You can start with an empty `circuit = cirq.Circuit()` and simply `circuit.append(operations)` to add on more and more operations .\n", "3. `insert`: Instead of appending, you can insert before a particular moment location (labeled by an integer index).\n", "\n", "One interesting, and extremely convenient, fact about `Circuit(...)`, `append`, and `insert` is that they \"auto flatten\" whatever you give them.\n", "You *can* give them a list of operations, but you can also give them\n", "\n", "- a list *of lists* of operations,\n", "- a generator function that sometimes yields tuples of operations and other times yields individual operations,\n", "- or just a single operation (without a list around it).\n", "\n", "If it can recursively iterated into individual operations, these three methods will take it.\n", "\n", "> The above idea uses a concept we call an `OP_TREE` in Cirq. An `OP_TREE` is not a class, but a contract. The basic idea is that if the input can be iteratively flattened into a list of operations, then the input is an `OP_TREE`.\n", "\n", "The main place where auto-flattening is useful is when you are building a circuit's operations using generators. \n", "\n", "> Recall that, in Python, functions that have a `yield` statement are *generators*. Generators are functions that act as *iterators*. \n", "\n", "In this context, auto-flattening means that generators producing operations for a circuit can simply `yield` sub-generators (instead of iterating over them and yielding their items). We show an example of this below." ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.495619Z", "iopub.status.busy": "2025-05-30T09:55:40.495096Z", "iopub.status.idle": "2025-05-30T09:55:40.501562Z", "shell.execute_reply": "2025-05-30T09:55:40.501058Z" }, "id": "QFoV-eOE1tGN" }, "outputs": [ { "data": { "text/html": [ "
a: ───@───X───@───\n",
       "      │   │   │\n",
       "b: ───X───@───X───
" ], "text/plain": [ "a: ───@───X───@───\n", " │ │ │\n", "b: ───X───@───X───" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "\"\"\"Creating a circuit from generator functions.\"\"\"\n", "\n", "\n", "def xor_swap(a, b):\n", " \"\"\"Swaps two qubits with three CNOTs.\"\"\"\n", " yield cirq.CNOT(a, b) # |a> |b> --> |a> |a ^ b>\n", " yield cirq.CNOT(b, a) # |a> |a ^ b> --> |a ^ a ^ b> | a ^ b> = |b>|a^b>\n", " yield cirq.CNOT(a, b) # |b> |a ^ b> --> |b>|a ^ b ^ b> = |b> |a>\n", "\n", "\n", "cirq.Circuit(xor_swap(a, b))" ] }, { "cell_type": "markdown", "metadata": { "id": "Z76Kcs27EcY5" }, "source": [ "## Exercise: Create a circuit to left rotate 5 qubits. \n", "\n", "Now that we've learnt how to build a circuit to swap the state of two qubits, use this to build a circuit which left rotates 5 qubits i.e. on applying the circuit on 5 qubits (0 - 4), the state of qubits should change as follows:\n", "``` \n", "0 --> 4 \n", "4 --> 3\n", "3 --> 2\n", "2 --> 1\n", "1 --> 0\n", "```" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.504114Z", "iopub.status.busy": "2025-05-30T09:55:40.503561Z", "iopub.status.idle": "2025-05-30T09:55:40.506417Z", "shell.execute_reply": "2025-05-30T09:55:40.505865Z" }, "id": "LbIZIMINEzD9" }, "outputs": [], "source": [ "# @title Attempt the solution here" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.508618Z", "iopub.status.busy": "2025-05-30T09:55:40.508371Z", "iopub.status.idle": "2025-05-30T09:55:40.512083Z", "shell.execute_reply": "2025-05-30T09:55:40.511466Z" }, "id": "5oqmyccsE1kK" }, "outputs": [], "source": [ "# @title Expand to view the solution\n", "def left_rotate(qubits):\n", " \"\"\"Rotates qubits to the left.\"\"\"\n", " for i in range(len(qubits) - 1):\n", " a, b = qubits[i : i + 2]\n", " yield xor_swap(a, b)\n", "\n", "\n", "# Get five qubits on a line.\n", "line = cirq.LineQubit.range(5)\n", "\n", "# Create a circuit which rotates the qubits to the left.\n", "# uncomment the next line to compare with your circuit\n", "# print(cirq.Circuit(left_rotate(line)))" ] }, { "cell_type": "markdown", "metadata": { "id": "ae159315c56d" }, "source": [ "One can see how this method of creating circuits is quite powerful. \n", "\n", "> Note that `cirq.SWAP` is a pre-defined gate in Cirq. We used three `cirq.CNOT`s instead of `cirq.SWAP` in the above example to demonstrate auto-flattening with generators." ] }, { "cell_type": "markdown", "metadata": { "id": "60d8516a19b2" }, "source": [ "## Insert strategies" ] }, { "cell_type": "markdown", "metadata": { "id": "p9LUxAU41wWs" }, "source": [ "You may have noticed that there is a hole in what we've explained so far. We have been passing a one-dimensional sequence of operations, but the output is a two-dimensional circuit (a list-of-lists-of-operations). There is a degree of freedom that hasn't been account for. Specifically, how does Cirq choose the moment that each operation will be placed within?\n", "\n", "The answer is the concept of a `cirq.InsertStrategy`. An `InsertStrategy` defines how `Operation`s are placed in a `Circuit` when requested to be inserted at a given location. Here a `location` is identified by the index of the `Moment` in the `Circuit` that operations should be placed before. \n", "\n", "> *Note*: In the case of `Circuit.append` this means inserting at the index `len(circuit)` which is one more than the largest moment index and so represents the end of the circuit.\n", "\n", "There are currently four insertion strategies in Cirq:\n", "\n", "1. `InsertStrategy.EARLIEST` (the default),\n", "2. `InsertStrategy.NEW`,\n", "3. `InsertStrategy.INLINE`,\n", "4. `InsertStrategy.NEW_THEN_INLINE`.\n", "\n", "The strategy `InsertStrategy.EARLIEST` is defined as follows:\n", "\n", "> `InsertStrategy.EARLIEST`: Scans backward from the insert\n", "> location until a moment with operations touching qubits affected by the\n", "> operation to insert is found. The operation is added into the moment just\n", "> after that location.\n", "\n", "For example, if we first create an `Operation` in a single moment,\n", "and then use `InsertStrategy.EARLIEST` the `Operation` can slide back to this\n", "first `Moment` if there is space." ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.514833Z", "iopub.status.busy": "2025-05-30T09:55:40.514607Z", "iopub.status.idle": "2025-05-30T09:55:40.519884Z", "shell.execute_reply": "2025-05-30T09:55:40.519298Z" }, "id": "wNek1WjpX4MR" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", "a: ───@───H───\n", " │\n", "b: ───@───H───\n", "\n", "c: ───H───────\n" ] } ], "source": [ "\"\"\"Appending operations with InsertStrategy.EARLIEST.\"\"\"\n", "\n", "# Create an empty circuit.\n", "circuit = cirq.Circuit()\n", "\n", "# Append an operation.\n", "# Note: InsertStrategy.EARLIEST is used by default if not otherwise specified.\n", "circuit.append([cirq.CZ(a, b)])\n", "\n", "# Append more operations.\n", "# Note: InsertStrategy.EARLIEST is used by default if not otherwise specified.\n", "circuit.append([cirq.H(a), cirq.H(b), cirq.H(c)])\n", "\n", "# Display the circuit.\n", "print(\"Circuit:\\n\")\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "4d93a69cfcb8" }, "source": [ "After creating the first moment with a `CZ` gate, the second\n", "append uses the `InsertStrategy.EARLIEST` strategy. The\n", "`H` on ``a`` and ``b`` cannot slide back, while the `H` on ``c`` can and so ends up in the first `Moment`." ] }, { "cell_type": "markdown", "metadata": { "id": "TcHeZM6qXvbS" }, "source": [ "While `InsertStrategy.EARLIEST` is the default strategy, the second most important strategy is `InsertStrategy.NEW_THEN_INLINE`, defined as follows:\n", "\n", "> `InsertStrategy.NEW_THEN_INLINE`: For the first operation, add it to a new \n", "> `Moment` the insertion point. Attempts to add the operation after the first \n", "> operation to insert into the moment just before the desired insert location. \n", "> But, if there's already an existing operation affecting any of the qubits\n", "> touched by the operation to insert, a new moment is created instead and this \n", "> `Moment` is the one that is subsequently used for insertions.\n", "\n", "To see an example of this strategy, we create a circuit with the same operations but inserting them with a different strategy." ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.522334Z", "iopub.status.busy": "2025-05-30T09:55:40.522120Z", "iopub.status.idle": "2025-05-30T09:55:40.527089Z", "shell.execute_reply": "2025-05-30T09:55:40.526572Z" }, "id": "qWVDhLxFYuRp" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", "a: ───@───H───\n", " │\n", "b: ───@───H───\n", "\n", "c: ───────H───\n" ] } ], "source": [ "\"\"\"Appending operations with InsertStrategy.NEW_THEN_INLINE.\"\"\"\n", "\n", "# Create an empty circuit.\n", "circuit = cirq.Circuit()\n", "\n", "# Append an operation.\n", "circuit.append([cirq.CZ(a, b)], strategy=cirq.InsertStrategy.NEW_THEN_INLINE)\n", "\n", "# Append more operations.\n", "circuit.append([cirq.H(a), cirq.H(b), cirq.H(c)], strategy=cirq.InsertStrategy.NEW_THEN_INLINE)\n", "\n", "# Display the circuit.\n", "print(\"Circuit:\\n\")\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "69a53a1f5de2" }, "source": [ "In contrast to the previous codeblock using `InsertStrategy.EARLIEST`, we see that the three `cirq.H` gates appended after the `cirq.CZ` gate appear in the same moment when we use `InsertStrategy.NEW_THEN_INLINE`." ] }, { "cell_type": "markdown", "metadata": { "id": "y9conKPAPn26" }, "source": [ "## Exercise: Create the given circuit using least number of appends\n", "\n", "Now that you've learned about `InsertStrategy`s, here is an exercise to validate your understanding. Create, **using the least number of appends**, the following circuit:\n", "\n", "\n", "\n", "```\n", "a: ───@───H───────────H───H───\n", " │\n", "b: ───@───────H───@───H───────\n", " │\n", "c: ───H───────────@───────────\n", "```\n", "\n", "Here imagine that you want exactly the moments indicated by the spacing of the circuit so that there are six moments in this circuit." ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.530018Z", "iopub.status.busy": "2025-05-30T09:55:40.529773Z", "iopub.status.idle": "2025-05-30T09:55:40.532686Z", "shell.execute_reply": "2025-05-30T09:55:40.532112Z" }, "id": "-HXXD801OFGF" }, "outputs": [], "source": [ "# @title Attempt the solution here" ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.535013Z", "iopub.status.busy": "2025-05-30T09:55:40.534768Z", "iopub.status.idle": "2025-05-30T09:55:40.541343Z", "shell.execute_reply": "2025-05-30T09:55:40.540764Z" }, "id": "jP4VkPeHcjJT" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "\n", "a: ───@───H───────────H───H───\n", " │\n", "b: ───@───────H───@───H───────\n", " │\n", "c: ───H───────────@───────────\n" ] } ], "source": [ "# @title Expand to view the solution\n", "# Define three qubits.\n", "a = cirq.NamedQubit('a')\n", "b = cirq.NamedQubit('b')\n", "c = cirq.NamedQubit('c')\n", "\n", "# Get an empty circuit.\n", "circuit = cirq.Circuit()\n", "\n", "# Append these gates using cirq.InsertStrategy.EARLIEST (the default strategy).\n", "circuit.append([cirq.CZ(a, b), cirq.H(c), cirq.H(a)])\n", "\n", "# Append these gates using cirq.InsertStrategy.NEW_THEN_INLINE.\n", "circuit.append(\n", " [cirq.H(b), cirq.CZ(b, c), cirq.H(b), cirq.H(a), cirq.H(a)],\n", " strategy=cirq.InsertStrategy.NEW_THEN_INLINE,\n", ")\n", "\n", "# Display the circuit.\n", "print(\"Circuit:\\n\")\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "X15yPl_KQ20Z" }, "source": [ "# Simulations of a Circuit\n", "\n", "Now that we know how to construct `Circuit`s in Cirq, let's see how to execute them on a simulator. First we create a simple circuit to simulate in the following cell." ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.543804Z", "iopub.status.busy": "2025-05-30T09:55:40.543532Z", "iopub.status.idle": "2025-05-30T09:55:40.549305Z", "shell.execute_reply": "2025-05-30T09:55:40.548735Z" }, "id": "V6tZk3qGqBoH" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───X^0.5───@───X^0.5───M───\n", " │ │\n", "b: ───X^0.5───@───X^0.5───M───\n" ] } ], "source": [ "\"\"\"Get a circuit to simulate.\"\"\"\n", "\n", "\n", "def basic_circuit(measure=True):\n", " \"\"\"Returns a simple circuit with some one- and two-qubit gates,\n", " as well as (optionally) measurements.\n", " \"\"\"\n", " # Gates we will use in the circuit.\n", " sqrt_x = cirq.X**0.5\n", " cz = cirq.CZ\n", "\n", " # Yield the operations.\n", " yield sqrt_x(a), sqrt_x(b)\n", " yield cz(a, b)\n", " yield sqrt_x(a), sqrt_x(b)\n", " if measure:\n", " yield cirq.measure(a, b)\n", "\n", "\n", "# Create a circuit including measurements.\n", "circuit = cirq.Circuit(basic_circuit())\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "WpywVOeDqi4Q" }, "source": [ "The main simulator in Cirq is the `cirq.Simulator`. The general pattern of simulation is to instantiate this simulator, then pass in a circuit to either the `run` or `simulate` methods (more on this below)." ] }, { "cell_type": "code", "execution_count": 18, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.551879Z", "iopub.status.busy": "2025-05-30T09:55:40.551524Z", "iopub.status.idle": "2025-05-30T09:55:40.558191Z", "shell.execute_reply": "2025-05-30T09:55:40.557541Z" }, "id": "KmGuMjvGw_Ef" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Measurement results:\n", "a,b=0, 0\n" ] } ], "source": [ "\"\"\"Example of simulating a circuit in Cirq.\"\"\"\n", "\n", "# Get a simulator.\n", "simulator = cirq.Simulator()\n", "\n", "# Pass the circuit to the simulator.run method.\n", "result = simulator.run(circuit, repetitions=1)\n", "print(\"Measurement results:\")\n", "print(result)" ] }, { "cell_type": "markdown", "metadata": { "id": "aHugx9T0z047" }, "source": [ "Running this multiple times should result in different measurement results, since the circuit produces a superposition over all computational basis states." ] }, { "cell_type": "markdown", "metadata": { "id": "416e9c012263" }, "source": [ "Above we used the `run` method of the `simulator`. In Cirq, `run` methods mimic the actual hardware in that they don't give one access to unphysical objects like the wavefunction. The `repetitions` argument is how many times to sample from the circuit.\n", "\n", "\n", "\n", "If one wants to get the wavefunction, the `simulate` methods can be used as shown below." ] }, { "cell_type": "code", "execution_count": 19, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.561004Z", "iopub.status.busy": "2025-05-30T09:55:40.560600Z", "iopub.status.idle": "2025-05-30T09:55:40.567482Z", "shell.execute_reply": "2025-05-30T09:55:40.566854Z" }, "id": "Apj7WiFZ0WFm" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "State vector:\n", "[0.5+0.j 0. +0.5j 0. +0.5j 0.5+0.j ]\n", "\n", "Dirac notation:\n", "0.5|00⟩ + 0.5j|01⟩ + 0.5j|10⟩ + 0.5|11⟩\n" ] } ], "source": [ "\"\"\"Simulating a circuit with the `simulate` method.\"\"\"\n", "\n", "# Get a circuit without measurements.\n", "circuit = cirq.Circuit(basic_circuit(measure=False))\n", "\n", "# Simulate the circuit.\n", "result = simulator.simulate(circuit, qubit_order=[a, b])\n", "\n", "# Print the final state vector (wavefunction).\n", "print(\"State vector:\")\n", "print(np.around(result.final_state_vector, 3))\n", "\n", "# Print the state vector in Dirac notation.\n", "print(\"\\nDirac notation:\")\n", "print(result.dirac_notation())" ] }, { "cell_type": "markdown", "metadata": { "id": "t18-sIJc0cvf" }, "source": [ "Notice that we passed a `qubit_order` into the `simulate` method. This order helps define the order of the kronecker (tensor) product used in the resulting `final_state_vector`. \n", "\n", "> *Note*: The `qubit_order` argument is optional. When it is omitted, qubits are sorted ascending according to the ordering methods defined by their Python class (for example `cirq.NamedQubit` sorts lexicographically by name).\n", "If there are multiple types of qubits in one circuit, the name of the type is used as a tie breaker.\n", "\n", "The simplest `qubit_order` value you can provide is a list of the qubits in the desired order. Any qubits from the circuit that are not in the list will be ordered using the default `__str__` ordering, but come after qubits that are in the list. \n", "\n", "> **Note**: Be aware that all qubits in the list are included in the simulation, even if they are not operated on by the circuit.\n", "\n", "The mapping from the order of the qubits to the order of the amplitudes in the wave function can be tricky to understand. Basically, it is the same as the ordering used by `numpy.kron`.\n", "\n", "> If the state vector is the array \n", ">> (0.1, 0.2, 0.3, 0.4),\n", "\n", "> then this is \n", ">> 0.1|00⟩ + 0.2|01⟩ + 0.3|10⟩ + 0.4|11⟩ \n", "\n", "> in Dirac notation. If \n", ">> qubit order = [a, b]\n", "\n", "> then |00> means qubit a is in 0 and qubit b is in 0, |01> means \n", "> qubit a is 0 and qubit b is 1, etc.\n", "\n", "Another way to think about the qubit-to-amplitude ordering is as \"for loop ordering\":\n", "\n", "```\n", "for a in [0, 1]:\n", " for b in [0, 1]:\n", " print(a, b)\n", "```\n", "\n", "The first index (the outermost loop) is the slowest to vary." ] }, { "cell_type": "markdown", "metadata": { "id": "YLpiz0aN1Jd6" }, "source": [ "## Repetitions and histograms\n", "\n", "As mentioned, the simulator `run` methods also take an option for repeating the circuit, namely, the `repetitions` argument. If the measurements in the circuit are terminal and all other operations are unitary, this simulator is optimized to not recompute the state vector before sampling from the circuit." ] }, { "cell_type": "code", "execution_count": 20, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.570054Z", "iopub.status.busy": "2025-05-30T09:55:40.569828Z", "iopub.status.idle": "2025-05-30T09:55:40.713203Z", "shell.execute_reply": "2025-05-30T09:55:40.712595Z" }, "id": "QxkmBlo21lrQ" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({3: 254, 1: 251, 2: 248, 0: 247})\n" ] }, { "data": { "text/plain": [ "" ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" }, { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAAjsAAAHHCAYAAABZbpmkAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjMsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvZiW1igAAAAlwSFlzAAAPYQAAD2EBqD+naQAANgpJREFUeJzt3Xl4FeXd//HPCWQjqwGSsATCpgHFgGExiBAhEJZSEKxFUQIiKE2gEkWlKms1iiJxoeDTRwkoebRgWaSWHYIiIkQBAUGgKCBZZElCAoQs8/vDi/l5TIAccsIJ0/fruuYyc88993xnTgsfZu45sRmGYQgAAMCi3FxdAAAAQHUi7AAAAEsj7AAAAEsj7AAAAEsj7AAAAEsj7AAAAEsj7AAAAEsj7AAAAEsj7AAAAEsj7AAw2Ww2TZ061dVl3HC4bkDNRtgBrpPU1FTZbDZzqV27tho1aqQRI0bop59+cnV5Ffriiy80depU5ebmVnqfTz75RN27d1dwcLDq1Kmj5s2b6/7779eqVavMPidOnNDUqVO1c+fOa67t008/rZaAMXXqVNlsNp08ebLC7eHh4frd735X5eOkpaUpJSWlyuMAuDrCDnCdTZ8+Xe+//77mzZunvn376oMPPlD37t114cIFV5dWzhdffKFp06ZVOuy89tpr+v3vfy+bzaZJkyZp9uzZGjJkiA4ePKgPP/zQ7HfixAlNmzatymFn2rRp17y/M50/f17PP/+8Q/sQdoDrp7arCwD+2/Tt21cdOnSQJD366KOqV6+eXnnlFa1YsUL333+/i6u7diUlJZoxY4Z69eqlNWvWlNuek5PjgqquDy8vL1eX4LDCwkL5+Pi4ugzguuDODuBid999tyTp8OHDdu379+/Xfffdp6CgIHl5ealDhw5asWKFXZ/i4mJNmzZNrVq1kpeXl+rWrauuXbtq7dq1Zp+YmBjFxMSUO+6IESMUHh5+2bqmTp2qiRMnSpKaNWtmPn774YcfKux/8uRJ5efn66677qpwe3BwsCRp06ZN6tixoyRp5MiR5ripqamSpM8++0x/+MMf1KRJE3l6eiosLEwTJkzQ+fPn7WqfM2eOJNk9GrykrKxMKSkpuvXWW+Xl5aWQkBA99thjOnPmzGXPtyp+O2fn7NmzeuKJJxQeHi5PT08FBwerV69e+vrrryX98pn861//0o8//mjW/uvPIicnR6NGjVJISIi8vLwUGRmpBQsWlDvuqVOn9PDDD8vf31+BgYGKj4/Xrl277K6n9Mv18vX11eHDh9WvXz/5+flp2LBhkip3vX89xtGjR/W73/1Ovr6+atSokfk5fPvtt+rRo4d8fHzUtGlTpaWlOenqAlXHnR3AxS6Fh5tuusls27t3r+666y41atRIzz77rHx8fPSPf/xDgwYN0scff6x7771X0i+BJDk5WY8++qg6deqk/Px87dixQ19//bV69epVpboGDx6s77//Xv/3f/+n2bNnq169epKk+vXrV9g/ODhY3t7e+uSTTzRu3DgFBQVV2K9169aaPn26Jk+erDFjxphhr0uXLpKkxYsX69y5cxo7dqzq1q2rr776Sm+99ZaOHz+uxYsXS5Iee+wxnThxQmvXrtX7779f7hiPPfaYUlNTNXLkSI0fP15HjhzR22+/rW+++UZbtmyRu7v7Vc//9OnTFbaXlZVddd/HH39cS5YsUWJiotq0aaNTp07p888/13fffac77rhDzz33nPLy8nT8+HHNnj1bkuTr6yvpl0diMTExOnTokBITE9WsWTMtXrxYI0aMUG5urv785z+bdQwYMEBfffWVxo4dq4iICC1fvlzx8fEV1lRSUqK4uDh17dpVr732murUqSOpctf7ktLSUvXt21fdunXTzJkztWjRIiUmJsrHx0fPPfechg0bpsGDB2vevHkaPny4oqOj1axZs6teL6DaGQCui/nz5xuSjHXr1hk///yzcezYMWPJkiVG/fr1DU9PT+PYsWNm3549expt27Y1Lly4YLaVlZUZXbp0MVq1amW2RUZGGv3797/icbt372507969XHt8fLzRtGlTuzZJxpQpU8z1V1991ZBkHDlypFLnOHnyZEOS4ePjY/Tt29d48cUXjYyMjHL9tm/fbkgy5s+fX27buXPnyrUlJycbNpvN+PHHH822hIQEo6I/wj777DNDkrFo0SK79lWrVlXY/ltTpkwxJF1x+e01/+11CwgIMBISEq54nP79+5e7/oZhGCkpKYYk44MPPjDbLl68aERHRxu+vr5Gfn6+YRiG8fHHHxuSjJSUFLNfaWmp0aNHj3LXNj4+3pBkPPvss+WOV9nrfWmMl156yWw7c+aM4e3tbdhsNuPDDz802/fv31/umgCuxGMs4DqLjY1V/fr1FRYWpvvuu08+Pj5asWKFGjduLOmXOwobNmzQ/fffr7Nnz+rkyZM6efKkTp06pbi4OB08eNB8eyswMFB79+7VwYMHXXlKpmnTpiktLU3t27fX6tWr9dxzzykqKkp33HGHvvvuu0qN4e3tbf5cWFiokydPqkuXLjIMQ998881V91+8eLECAgLUq1cv89qdPHlSUVFR8vX11caNGytVx8cff6y1a9eWW0JCQq66b2BgoLZt26YTJ05U6li/9umnnyo0NFQPPPCA2ebu7q7x48eroKBA6enpkqRVq1bJ3d1do0ePNvu5ubkpISHhsmOPHTu2XJuj1/vRRx81fw4MDNQtt9wiHx8fu/lmt9xyiwIDA/Wf//ynkmcNVC8eYwHX2Zw5c3TzzTcrLy9P7733njZv3ixPT09z+6FDh2QYhl544QW98MILFY6Rk5OjRo0aafr06Ro4cKBuvvlm3XbbberTp48efvhh3X777dfrdMp54IEH9MADDyg/P1/btm1Tamqq0tLSNGDAAO3Zs+eqk3mPHj2qyZMna8WKFeXm2OTl5V31+AcPHlReXp45R+i3KjtRulu3buaju1+rzGTkmTNnKj4+XmFhYYqKilK/fv00fPhwNW/e/Kr7/vjjj2rVqpXc3Oz/Ldq6dWtz+6X/NmjQwHwcdUnLli0rHLd27dpmoP41R663l5dXuceYAQEBaty4sd2cqUvt1TVHCnAUYQe4zjp16mS+jTVo0CB17dpVDz74oA4cOCBfX19zTshTTz2luLi4Cse49Bdat27ddPjwYS1fvlxr1qzR//7v/2r27NmaN2+e+S9wm80mwzDKjVFaWlodp2fy9/dXr1691KtXL7m7u2vBggXatm2bunfvftl9SktL1atXL50+fVrPPPOMIiIi5OPjo59++kkjRoyo1HyZsrIyBQcHa9GiRRVuv9ycI2e6//77dffdd2vp0qVas2aNXn31Vb3yyiv65z//qb59+1b78Svi6elZLkA5er1r1apV4diXa6/of3eAKxB2ABeqVauWkpOTdc899+jtt9/Ws88+a/7r393dXbGxsVcdIygoSCNHjtTIkSNVUFCgbt26aerUqWbYuemmmyp8nHDpDsGV/PZf69eqQ4cOWrBggTIzM6847rfffqvvv/9eCxYs0PDhw832X79ddrXaWrRooXXr1umuu+6ye0RzvTVo0EB/+tOf9Kc/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P/30k1OKAgAAcJZKv3q+YsUK8+fVq1crICDAXC8tLdX69esVHh7u1OIAAACqqtJhZ9CgQZIkm82m+Ph4u23u7u4KDw/XrFmznFocAABAVVU67JSVlUmSmjVrpu3bt6tevXrVVhQAAICzOPwNykeOHKmOOgAAAKpFpcLOm2++WekBx48ff83FAAAAOFulws7s2bMrNZjNZiPsAACAGqVSYYdHVwAA4EbFNygDAABLc3iC8iOPPHLF7e+99941FwMAAOBsDoedM2fO2K0XFxdrz549ys3NVY8ePZxWGAAAgDM4HHaWLl1arq2srExjx45VixYtnFIUAACAszhlzo6bm5uSkpIq/dYWAADA9eK0CcqHDx9WSUmJs4YDAABwCocfYyUlJdmtG4ahzMxM/etf/yr3O7MAAABczeGw880339itu7m5qX79+po1a9ZV39QCAAC43hwOOxs3bqyOOgAAAKqFw3N2zp8/r3PnzpnrP/74o1JSUrRmzRqnFgYAAOAMDoedgQMHauHChZKk3NxcderUSbNmzdLAgQM1d+5cpxcIAABQFQ6Hna+//lp33323JGnJkiUKDQ3Vjz/+qIULFzr029EBAACuB4fDzrlz5+Tn5ydJWrNmjQYPHiw3Nzfdeeed+vHHH51eIAAAQFU4HHZatmypZcuW6dixY1q9erV69+4tScrJyZG/v7/TCwQAAKgKh8PO5MmT9dRTTyk8PFydOnVSdHS0pF/u8rRv397pBQIAAFSFw6+e33ffferatasyMzMVGRlptvfs2VP33nuvU4sDAACoqmv6dRGhoaHy8/PT2rVrdf78eUlSx44dFRER4dTiAAAAqsrhsHPq1Cn17NlTN998s/r166fMzExJ0qhRo/Tkk086vUAAAICqcDjsTJgwQe7u7jp69Kjq1Kljtv/xj3/UqlWrnFocAABAVTk8Z2fNmjVavXq1GjdubNfeqlUrXj0HAAA1jsN3dgoLC+3u6Fxy+vRpeXp6OqUoAAAAZ3E47Nx9993mr4uQJJvNprKyMs2cOVP33HOPU4sDAACoKocfY82cOVM9e/bUjh07dPHiRT399NPau3evTp8+rS1btlRHjQAAANfM4Ts7t912m77//nt17dpVAwcOVGFhoQYPHqxvvvlGLVq0qI4aAQAArplDd3aKi4vVp08fzZs3T88991x11QQAAOA0Dt3Z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AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApRF2AACApVkm7MyZM0fh4eHy8vJS586d9dVXX7m6JAAAUANYIux89NFHSkpK0pQpU/T1118rMjJScXFxysnJcXVpAADAxSwRdl5//XWNHj1aI0eOVJs2bTRv3jzVqVNH7733nqtLAwAALnbDh52LFy8qIyNDsbGxZpubm5tiY2O1detWF1YGAABqgtquLqCqTp48qdLSUoWEhNi1h4SEaP/+/RXuU1RUpKKiInM9Ly9PkpSfn+/0+sqKzjl9TFROdXyev8Zn6zp8ttbE52pd1fXZXhrXMIwr9rvhw861SE5O1rRp08q1h4WFuaAaVJeAFFdXgOrCZ2tNfK7WVd2f7dmzZxUQEHDZ7Td82KlXr55q1aql7Oxsu/bs7GyFhoZWuM+kSZOUlJRkrpeVlen06dOqW7eubDZbtdZ7I8nPz1dYWJiOHTsmf39/V5cDJ+FztS4+W+vis62YYRg6e/asGjZseMV+N3zY8fDwUFRUlNavX69BgwZJ+iW8rF+/XomJiRXu4+npKU9PT7u2wMDAaq70xuXv78//uSyIz9W6+Gyti8+2vCvd0bnkhg87kpSUlKT4+Hh16NBBnTp1UkpKigoLCzVy5EhXlwYAAFzMEmHnj3/8o37++WdNnjxZWVlZateunVatWlVu0jIAAPjvY4mwI0mJiYmXfWyFa+Pp6akpU6aUe+SHGxufq3Xx2VoXn23V2Iyrva8FAABwA7vhv1QQAADgSgg7AADA0gg7AADA0gg7AADA0gg7qNCcOXMUHh4uLy8vde7cWV999ZWrS0IVbd68WQMGDFDDhg1ls9m0bNkyV5cEJ0lOTlbHjh3l5+en4OBgDRo0SAcOHHB1WaiiuXPn6vbbbze/SDA6Olr//ve/XV3WDYmwg3I++ugjJSUlacqUKfr6668VGRmpuLg45eTkuLo0VEFhYaEiIyM1Z84cV5cCJ0tPT1dCQoK+/PJLrV27VsXFxerdu7cKCwtdXRqqoHHjxnr55ZeVkZGhHTt2qEePHho4cKD27t3r6tJuOLx6jnI6d+6sjh076u2335b0y6/fCAsL07hx4/Tss8+6uDo4g81m09KlS81fsQJr+fnnnxUcHKz09HR169bN1eXAiYKCgvTqq69q1KhRri7lhsKdHdi5ePGiMjIyFBsba7a5ubkpNjZWW7dudWFlACorLy9P0i9/McIaSktL9eGHH6qwsFDR0dGuLueGY5lvUIZznDx5UqWlpeV+1UZISIj279/voqoAVFZZWZmeeOIJ3XXXXbrttttcXQ6q6Ntvv1V0dLQuXLggX19fLV26VG3atHF1WTccwg4AWEhCQoL27Nmjzz//3NWlwAluueUW7dy5U3l5eVqyZIni4+OVnp5O4HEQYQd26tWrp1q1aik7O9uuPTs7W6GhoS6qCkBlJCYmauXKldq8ebMaN27s6nLgBB4eHmrZsqUkKSoqStu3b9cbb7yhd955x8WV3ViYswM7Hh4eioqK0vr16822srIyrV+/nufEQA1lGIYSExO1dOlSbdiwQc2aNXN1SagmZWVlKioqcnUZNxzu7KCcpKQkxcfHq0OHDurUqZNSUlJUWFiokSNHuro0VEFBQYEOHTpkrh85ckQ7d+5UUFCQmjRp4sLKUFUJCQlKS0vT8uXL5efnp6ysLElSQECAvL29XVwdrtWkSZPUt29fNWnSRGfPnlVaWpo2bdqk1atXu7q0Gw6vnqNCb7/9tl599VVlZWWpXbt2evPNN9W5c2dXl4Uq2LRpk+65555y7fHx8UpNTb3+BcFpbDZbhe3z58/XiBEjrm8xcJpRo0Zp/fr1yszMVEBAgG6//XY988wz6tWrl6tLu+EQdgAAgKUxZwcAAFgaYQcAAFgaYQcAAFgaYQcAAFgaYQcAAFgaYQcAAFgaYQcAAFgaYQdAjfPDDz/IZrNp586dl+2zadMm2Ww25ebmXre6ANyYCDsAbkhdunQxv1lWklJTUxUYGFilMa91DIIXULPxu7EA3JA8PDwUGhrq6jIA3AC4swPAqQoLCzV8+HD5+vqqQYMGmjVrlmJiYvTEE0+YfWw2m5YtW2a3X2BgYLnf0bV//3516dJFXl5euu2225Senm5u+/XdlE2bNmnkyJHKy8uTzWaTzWbT1KlTK6xv165duueee+Tn5yd/f39FRUVpx44dVxzj/fffV4cOHeTn56fQ0FA9+OCDysnJkfTLI7dLv3Pspptuks1mM38fVVlZmZKTk9WsWTN5e3srMjJSS5YsueZrC+DaEHYAONXEiROVnp6u5cuXa82aNdq0aZO+/vrrax7rySef1DfffKPo6GgNGDBAp06dKtevS5cuSklJkb+/vzIzM5WZmamnnnqqwjGHDRumxo0ba/v27crIyNCzzz4rd3f3K45RXFysGTNmaNeuXVq2bJl++OEHM9CEhYXp448/liQdOHBAmZmZeuONNyRJycnJWrhwoebNm6e9e/dqwoQJeuihh+xCG4Dqx2MsAE5TUFCgd999Vx988IF69uwpSVqwYIEaN258TeMlJiZqyJAhkqS5c+dq1apVevfdd/X000/b9fPw8FBAQIBsNttVH20dPXpUEydOVEREhCSpVatW5rbLjfHII4+YPzdv3lxvvvmmOnbsqIKCAvn6+iooKEiSFBwcbM75KSoq0ksvvaR169YpOjra3Pfzzz/XO++8o+7du1/DFQFwLbizA8BpDh8+rIsXL6pz585mW1BQkG655ZZrGu9SSJCk2rVrq0OHDvruu++qVGNSUpIeffRRxcbG6uWXX9bhw4evuk9GRoYGDBigJk2ayM/PzwwqR48evew+hw4d0rlz59SrVy/5+vqay8KFCyt1TADOQ9gBcN3ZbDYZhmHXVlxcfF2OPXXqVO3du1f9+/fXhg0b1KZNGy1duvSy/QsLCxUXFyd/f38tWrRI27dvN/tfvHjxsvsVFBRIkv71r39p586d5rJv3z7m7QDXGWEHgNO0aNFC7u7u2rZtm9l25swZff/993b96tevr8zMTHP94MGDOnfuXLnxvvzyS/PnkpISZWRkqHXr1hUe28PDQ6WlpZWq8+abb9aECRO0Zs0aDR48WPPnz7/sGPv379epU6f08ssv6+6771ZERIQ5OfnXx5Zkt2+bNm3k6empo0ePqmXLlnZLWFhYpeoE4BzM2QHgNL6+vho1apQmTpyounXrKjg4WM8995zc3Oz/XdWjRw+9/fbbio6OVmlpqZ555hm5u7uXG2/OnDlq1aqVWrdurdmzZ+vMmTN282d+LTw8XAUFBVq/fr0iIyNVp04d1alTx67P+fPnNXHiRN13331q1qyZjh8/ru3bt5vzgioao0mTJvLw8NBbb72lxx9/XHv27NGMGTPsxm3atKlsNptWrlypfv36ydvbW35+fnrqqac0YcIElZWVqWvXrsrLy9OWLVvk7++v+Pj4qlxqAI4wAMCJzp49azz00ENGnTp1jJCQEGPmzJlG9+7djT//+c9mn59++sno3bu34ePjY7Rq1cr49NNPjYCAAGP+/PmGYRjGkSNHDElGWlqa0alTJ8PDw8No06aNsWHDBnOMjRs3GpKMM2fOmG2PP/64UbduXUOSMWXKlHK1FRUVGUOHDjXCwsIMDw8Po2HDhkZiYqJx/vz5K46RlpZmhIeHG56enkZ0dLSxYsUKQ5LxzTffmPtNnz7dCA0NNWw2mxEfH28YhmGUlZUZKSkpxi233GK4u7sb9evXN+Li4oz09PSqXmYADrAZxm8enAOAk8XExKhdu3ZKSUlxdSkA/gsxZwcAAFgaYQcAAFgaj7EAAIClcWcHAABYGmEHAABYGmEHAABYGmEHAABYGmEHAABYGmEHAABYGmEHAABYGmEHAABYGmEHAABY2v8DlZgbxYYkyRkAAAAASUVORK5CYII=", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "\"\"\"Simulate a circuit using 1000 repetitions.\"\"\"\n", "\n", "# Get a circuit with terminal measurements to simulate.\n", "circuit = cirq.Circuit(basic_circuit())\n", "\n", "# Sample from the circuit 1000 times.\n", "result = simulator.run(circuit, repetitions=1000)\n", "\n", "# Get a histogram of measurement results.\n", "print(result.histogram(key=\"a,b\"))\n", "\n", "# Plot a state histogram of the result.\n", "cirq.plot_state_histogram(result)" ] }, { "cell_type": "markdown", "metadata": { "id": "bD0zX0zP2HxQ" }, "source": [ "Here we have also demonstrated the use of the `histogram` method on the `result` which sums over all the different results for all of the different repetitions.\n", "\n", "The `histogram` method can also be given a `fold_func` argument, in order to group measurement results under some key before counting them up.\n", "For example, we can group by whether or not the two measurement results agreed:" ] }, { "cell_type": "code", "execution_count": 21, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.716302Z", "iopub.status.busy": "2025-05-30T09:55:40.715852Z", "iopub.status.idle": "2025-05-30T09:55:40.720569Z", "shell.execute_reply": "2025-05-30T09:55:40.719970Z" }, "id": "rPqVUsD9snYf" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Counter({'agree': 501, 'disagree': 499})\n" ] } ], "source": [ "print(\n", " result.histogram(\n", " key=\"a,b\", fold_func=lambda bits: \"agree\" if bits[0] == bits[1] else \"disagree\"\n", " )\n", ")" ] }, { "cell_type": "markdown", "metadata": { "id": "qFsytBIbOVD8" }, "source": [ "# The Deutsch-Jozsa Algorithm\n", "\n", "The very first indication that quantum computers could be more powerful than classical computers was provided by David Deutsch in his 1985 paper\n", "\n", "> David Deutsch, \"[Quantum Theory, the Church-Turing Principle and the Universal Quantum Computer](https://www.daviddeutsch.org.uk/wp-content/deutsch85.pdf)\" *Proc. R. Soc. Lond.* A **400** 97–117. http://doi.org/10.1098/rspa.1985.0070\n", "\n", "This algorithm was extended by Deutsch and Richard Jozsa to a more convincing algorithmic separation and what is now called the Deutsch-Jozsa algorithm. In this section we will show how to write circuits for the Deutsch algorithm and then as an exercise in using Cirq for algorithms for a small version of the Deutsch-Jozsa algorithm.\n", "\n", "Let's begin with the Deutsch algorithm. In Deutsch's algorithm you are given access to a box which computes a one bit boolean function. That is it is a box which takes in a bit and outputs a bit. If we want to be a mathematician or theoretical computer scientist we write the function $f$ as $f: \\{0, 1\\} \\rightarrow \\{0, 1\\}$. There are exactly four such boolean functions which we can write out in a table\n", "\n", "| $x$ | $f_0$ | $f_1$ | $f_x$ | $f_{\\bar{x}}$ |\n", "| --- | --- | --- | --- | --- |\n", "| 0 | 0 | 1 | 0 | 1\n", "| 1 | 0 | 1 | 1 | 0\n", "\n", "The first two of these are *constant* functions, $f_0$ and $f_1$. That is they always output a constant value (independent of the input). The other two $f_x$ and $f_\\bar{x}$ are *balanced*. Over their inputs $0$ and $1$, they have an equal number of $0$s and $1$s in their truth table. \n", "\n", "We can now state Deutsch's problem:\n", "\n", "> Given access to a one bit input one bit output boolean function, determine by querying the function whether the function is *balanced* or *constant*.\n", "\n", "It shouldn't take you much to convince yourself that in order to solve this problem classically you need to call the function on both possible input values. The easiest way to see this is just to consider what happens if you query the function on one particular input and notice that, for either input, learning the value of the function does not separate the constant from balanced functions. In summary:\n", "\n", "*Classically one must query the binary function twice to distinguish the constant function from the balanced function.*" ] }, { "cell_type": "markdown", "metadata": { "id": "UAec5ZBuSWYU" }, "source": [ "Now lets turn to the quantum approach to this problem. There is one bit of book keeping we need to take care of. Above we have described a classical function on bits that is not reversible. That is, knowing the values of the output does not allow us to determine uniquely the value of the input. In order to run this on a quantum computer, however we need to make this computation reversible. A trick for taking a classical non-reversible function and making it \"quantum happy\" is to compute the value in an extra register and store the input. Suppose we have an $n$ bit input $x$ and we are computing a (potentially non-reverisble) boolean function $f(x)$. Then we can implement this via a Unitary $U_f$ that acts like on $n + 1$ qubits\n", "\n", "$$\n", "U_f |x\\rangle |y\\rangle = |x\\rangle | y \\oplus f(x)\\rangle .\n", "$$\n", "\n", "Here $\\oplus$ is addition modulo $2$ (XOR) and we have identified how $U_f$ acts by its action on all computational basis states $|x\\rangle$ ($n$ input qubits) and $|y\\rangle$ ($1$ output qubit). To see that this is reversible one can note that applying the transformation twice returns the state to its original form.\n", "\n", "Let's see how to implement these functions in Cirq.\n", "\n", "$f_0$ enacts the transform\n", "$$\n", "\\begin{eqnarray}\n", "|00\\rangle &\\rightarrow& |00\\rangle \\\\\n", "|01\\rangle &\\rightarrow& |01\\rangle \\\\\n", "|10\\rangle &\\rightarrow& |10\\rangle \\\\\n", "|11\\rangle &\\rightarrow& |11\\rangle \\\\\n", "\\end{eqnarray}\n", "$$\n", "Well this is just the identity transform, i.e. an empty circuit.\n", "\n", "$f_1$ enacts the transform\n", "$$\n", "\\begin{eqnarray}\n", "|00\\rangle &\\rightarrow& |01\\rangle \\\\\n", "|01\\rangle &\\rightarrow& |00\\rangle \\\\\n", "|10\\rangle &\\rightarrow& |11\\rangle \\\\\n", "|11\\rangle &\\rightarrow& |10\\rangle \\\\\n", "\\end{eqnarray}\n", "$$\n", "This is the `cirq.X` bit flip gate on the second qubit.\n", "\n", "$f_x$ enacts the transform\n", "$$\n", "\\begin{eqnarray}\n", "|00\\rangle &\\rightarrow& |00\\rangle \\\\\n", "|01\\rangle &\\rightarrow& |01\\rangle \\\\\n", "|10\\rangle &\\rightarrow& |11\\rangle \\\\\n", "|11\\rangle &\\rightarrow& |10\\rangle \\\\\n", "\\end{eqnarray}\n", "$$\n", "This is nothing more than a `cirq.CNOT` from the first bit to the second bit.\n", "\n", "Finally $f_\\bar{x}$ enacts the transform\n", "$$\n", "\\begin{eqnarray}\n", "|00\\rangle &\\rightarrow& |01\\rangle \\\\\n", "|01\\rangle &\\rightarrow& |00\\rangle \\\\\n", "|10\\rangle &\\rightarrow& |10\\rangle \\\\\n", "|11\\rangle &\\rightarrow& |11\\rangle \\\\\n", "\\end{eqnarray}\n", "$$\n", "which is a `cirq.CNOT` from the first bit to the second bit followed by a `cirq.X` on the second bit.\n", "\n", "We can encapulate these functions into a dictionary from a oracle name to the operations in the circuit needed to enact this function." ] }, { "cell_type": "code", "execution_count": 22, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.723378Z", "iopub.status.busy": "2025-05-30T09:55:40.723151Z", "iopub.status.idle": "2025-05-30T09:55:40.727375Z", "shell.execute_reply": "2025-05-30T09:55:40.726763Z" }, "id": "YtWiBHonly69" }, "outputs": [], "source": [ "\"\"\"Store the operations to query each function in a dictionary.\"\"\"\n", "\n", "# Get qubits for the operations to act on.\n", "q0, q1 = cirq.LineQubit.range(2)\n", "\n", "# Define the dictionary of operations. The key of each dictionary entry\n", "# is the subscript of the function f in the above explanatory text.\n", "oracles = {\n", " '0': [],\n", " '1': [cirq.X(q1)],\n", " 'x': [cirq.CNOT(q0, q1)],\n", " 'notx': [cirq.CNOT(q0, q1), cirq.X(q1)],\n", "}" ] }, { "cell_type": "markdown", "metadata": { "id": "axCSYj3EmAEo" }, "source": [ "We now turn to Deutsch's algorithm. Suppose we are given access to the reversible oracle functions we have defined above. By a similar argument for our irreversible classical functions you can show that you cannot distinguish the balanced from the constant functions by using this oracle only once. But now we can ask the question: what if we are allowed to query this box in superposition, i.e. what if we can use the power of quantum computing?\n", "\n", "Deutsch was able to show that you could solve this problem now, with quantum computers, using only a single query. To see how this works we need two simple insights.\n", "\n", "Suppose that we prepare the second qubit in the superposition state $|-\\rangle=\\frac{1}{\\sqrt{2}}(|0\\rangle-|1\\rangle)$ and apply the oracle. Then we can check that\n", "$$ \n", "U_f |x\\rangle |-\\rangle = U_f|x\\rangle \\frac{1}{\\sqrt{2}}(|0\\rangle -|1\\rangle ) = |x\\rangle \\frac{1}{\\sqrt{2}}(|f(x)\\rangle -|f(x) \\oplus 1\\rangle ) = (-1)^{f(x)} |x\\rangle |-\\rangle .\n", "$$ \n", "This is the so called \"phase kickback trick\". By applying $U_f$ onto a target which is in superposition, the value of the function ends up showing up in the global phase. \n", "\n", "How can we leverage this to distinguish between the constant and balanced functions? Note that for the constant functions the phase that is applied is the same for all inputs $|x\\rangle$, whereas for the balanced functions the phase is different for each value of $x$. In other words, if we use the phase kickback trick then for each of the oracles we apply the following transform on the first qubit:\n", "\n", "$$\n", "\\begin{eqnarray}\n", "f_0 \\rightarrow I, &&\n", "f_1 \\rightarrow -I, &&\n", "f_x \\rightarrow Z, &&\n", "f_\\bar{x} \\rightarrow -Z &&\n", "\\end{eqnarray}\n", "$$\n", "\n", "Now we only need, on the first qubit, to distinguish between the identity gate and the $Z$ gate. But we can do this by recalling the identity\n", "\n", "$$ \n", "H Z H = X\n", "$$\n", "\n", "where $H$ is the Hamadard gate.\n", "\n", "This means that we can turn a phase flip into a bit flip by applying Hadamards before and after the phase flip. If we look at the constant and balanced functions we see that this means that the constant functions will be proportional to $I$ and the balanced functions will be proportional to $X$. If we feed in $|0\\rangle$ to this register, then in the first cases we will only see $|0\\rangle$ and in the second case we will only see $|1\\rangle$. In other words we will be able to distinguish constant from balanced using a single query of the oracle.\n", "\n", "Let's code this up." ] }, { "cell_type": "code", "execution_count": 23, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.729940Z", "iopub.status.busy": "2025-05-30T09:55:40.729686Z", "iopub.status.idle": "2025-05-30T09:55:40.738876Z", "shell.execute_reply": "2025-05-30T09:55:40.738242Z" }, "id": "aMHzLxztj-gq" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit for f_0:\n", "0: ───H───H───M───\n", "\n", "1: ───X───H───────\n", "\n", "Circuit for f_1:\n", "0: ───H───H───M───\n", "\n", "1: ───X───H───X───\n", "\n", "Circuit for f_x:\n", "0: ───H───────@───H───M───\n", " │\n", "1: ───X───H───X───────────\n", "\n", "Circuit for f_notx:\n", "0: ───H───────@───H───M───\n", " │\n", "1: ───X───H───X───X───────\n", "\n" ] } ], "source": [ "\"\"\"Creating the circuit used in Deutsch's algorithm.\"\"\"\n", "\n", "\n", "def deutsch_algorithm(oracle):\n", " \"\"\"Returns the circuit for Deutsch's algorithm given an input\n", " oracle, i.e., a sequence of operations to query a particular function.\n", " \"\"\"\n", " yield cirq.X(q1)\n", " yield cirq.H(q0), cirq.H(q1)\n", " yield oracle\n", " yield cirq.H(q0)\n", " yield cirq.measure(q0)\n", "\n", "\n", "for key, oracle in oracles.items():\n", " print(f\"Circuit for f_{key}:\")\n", " print(cirq.Circuit(deutsch_algorithm(oracle)), end=\"\\n\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "Zy-2ysxzweyv" }, "source": [ "Lets run these circuits a bunch of times to see that the measurement result ends up correctly distinguishing constant from balanced." ] }, { "cell_type": "code", "execution_count": 24, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.741844Z", "iopub.status.busy": "2025-05-30T09:55:40.741556Z", "iopub.status.idle": "2025-05-30T09:55:40.753298Z", "shell.execute_reply": "2025-05-30T09:55:40.752664Z" }, "id": "ImffrBgJvLme" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "oracle: f_0 results: q(0)=0000000000\n", "oracle: f_1 results: q(0)=0000000000\n", "oracle: f_x results: q(0)=1111111111\n", "oracle: f_notx results: q(0)=1111111111\n" ] } ], "source": [ "\"\"\"Simulate each of the circuits.\"\"\"\n", "\n", "simulator = cirq.Simulator()\n", "for key, oracle in oracles.items():\n", " result = simulator.run(cirq.Circuit(deutsch_algorithm(oracle)), repetitions=10)\n", " print(f'oracle: f_{key:<4} results: {result}')" ] }, { "cell_type": "markdown", "metadata": { "id": "845af7bfc7d6" }, "source": [ "We interpret the simulation results as follows:\n", "\n", "- For the first two functions $f_0$ and $f_1$, we always measure $0$. Therefore, we know that these functions are constant.\n", "- For the second two functions $f_x$ and $f_{\\bar{x}}$, we always measure $1$. Therefore, we know that these functions are balanced." ] }, { "cell_type": "markdown", "metadata": { "id": "5edb6fe11163" }, "source": [ "## Exercise: Two Bit Deutsch-Jozsa Algorithm" ] }, { "cell_type": "markdown", "metadata": { "id": "v4ka34Kuj4K0" }, "source": [ "All boolean functions for one input bit are either constant or balanced. For boolean functions from two input bits not all functions are constant or balanced. There are two constant functions, $f(x_0, x_1) = 0$ and $f(x_0, x_1)=1$, while there are ${4 \\choose 2} = 6$ balanced functions. The following code gives you the operations for these functions where we take two input qubits and compute the function in the third qubit." ] }, { "cell_type": "code", "execution_count": 25, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.756819Z", "iopub.status.busy": "2025-05-30T09:55:40.756206Z", "iopub.status.idle": "2025-05-30T09:55:40.761069Z", "shell.execute_reply": "2025-05-30T09:55:40.760464Z" }, "id": "V5ZCXGCrxl4k" }, "outputs": [], "source": [ "\"\"\"Operations to query all possible functions on two bits.\n", "Two of these functions are constant, and six of these functions are balanced.\n", "\"\"\"\n", "\n", "# Define three qubits to use.\n", "q0, q1, q2 = cirq.LineQubit.range(3)\n", "\n", "# Define the operations to query each of the two constant functions.\n", "constant = ([], [cirq.X(q2)])\n", "\n", "# Define the operations to query each of the six balanced functions.\n", "balanced = (\n", " [cirq.CNOT(q0, q2)],\n", " [cirq.CNOT(q1, q2)],\n", " [cirq.CNOT(q0, q2), cirq.CNOT(q1, q2)],\n", " [cirq.CNOT(q0, q2), cirq.X(q2)],\n", " [cirq.CNOT(q1, q2), cirq.X(q2)],\n", " [cirq.CNOT(q0, q2), cirq.CNOT(q1, q2), cirq.X(q2)],\n", ")" ] }, { "cell_type": "markdown", "metadata": { "id": "mr9ltXSJyB79" }, "source": [ "An extension of Deutsch's orginal algorithm is the Deutsch-Jozsa algorithm, which can distinguish constant from balanced functions like these using a single query to the oracle. **The goal of this exercise** is to write a quantum circuit that can distinguish these." ] }, { "cell_type": "code", "execution_count": 26, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.763531Z", "iopub.status.busy": "2025-05-30T09:55:40.763304Z", "iopub.status.idle": "2025-05-30T09:55:40.766683Z", "shell.execute_reply": "2025-05-30T09:55:40.766088Z" }, "id": "qJP_e68e1JBs" }, "outputs": [], "source": [ "# @title Attempt the solution here\n", "\"\"\"Exercise: Write a quantum circuit that can distinguish\n", "constant from balanced functions on two bits.\n", "\"\"\"\n", "\n", "\n", "def your_circuit(oracle):\n", " # Your code here!\n", " yield oracle\n", " # Your code here!\n", " yield cirq.measure(q2)" ] }, { "cell_type": "markdown", "metadata": { "id": "3e75a276e239" }, "source": [ "You can check your circuit by running the follow cell which simulates the circuit for all oracles." ] }, { "cell_type": "code", "execution_count": 27, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.769698Z", "iopub.status.busy": "2025-05-30T09:55:40.769125Z", "iopub.status.idle": "2025-05-30T09:55:40.782753Z", "shell.execute_reply": "2025-05-30T09:55:40.782179Z" }, "id": "81da6ec6fc5a" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "Your result on constant functions:\n", "q(2)=0000000000\n", "q(2)=1111111111\n", "\n", "Your result on balanced functions:\n", "q(2)=0000000000\n", "q(2)=0000000000\n", "q(2)=0000000000\n", "q(2)=1111111111\n", "q(2)=1111111111\n", "q(2)=1111111111\n" ] } ], "source": [ "\"\"\"Check your answer by running this cell.\"\"\"\n", "\n", "simulator = cirq.Simulator()\n", "\n", "print(\"\\nYour result on constant functions:\")\n", "for oracle in constant:\n", " result = simulator.run(cirq.Circuit(your_circuit(oracle)), repetitions=10)\n", " print(result)\n", "\n", "print(\"\\nYour result on balanced functions:\")\n", "for oracle in balanced:\n", " result = simulator.run(cirq.Circuit(your_circuit(oracle)), repetitions=10)\n", " print(result)" ] }, { "cell_type": "code", "execution_count": 28, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:40.785165Z", "iopub.status.busy": "2025-05-30T09:55:40.784946Z", "iopub.status.idle": "2025-05-30T09:55:40.789059Z", "shell.execute_reply": "2025-05-30T09:55:40.788428Z" }, "id": "mUvm9rmRFb4p" }, "outputs": [], "source": [ "# @title Expand to view the solution\n", "def dj_circuit(oracle):\n", " # Phase kickback trick.\n", " yield cirq.X(q2), cirq.H(q2)\n", "\n", " # Get an equal superposition over input bits.\n", " yield cirq.H(q0), cirq.H(q1)\n", "\n", " # Query the function.\n", " yield oracle\n", "\n", " # Use interference to get result, put last qubit into |1>.\n", " yield cirq.H(q0), cirq.H(q1), cirq.H(q2)\n", "\n", " # Use a final OR gate to put result in final qubit.\n", " yield cirq.X(q0), cirq.X(q1), cirq.CCX(q0, q1, q2)\n", " yield cirq.measure(q2)" ] }, { "cell_type": "markdown", "metadata": { "id": "79348c9be8a9" }, "source": [ "As above, we can check the solution by running the circuit with each of the oracles." ] }, { "cell_type": "code", "execution_count": 29, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.791689Z", "iopub.status.busy": "2025-05-30T09:55:40.791439Z", "iopub.status.idle": "2025-05-30T09:55:40.816242Z", "shell.execute_reply": "2025-05-30T09:55:40.815628Z" }, "id": "c1b1e989dab2" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Result on constant functions:\n", "q(2)=0000000000\n", "q(2)=0000000000\n", "\n", "Result on balanced functions:\n", "q(2)=1111111111\n", "q(2)=1111111111\n", "q(2)=1111111111\n", "q(2)=1111111111\n", "q(2)=1111111111\n", "q(2)=1111111111\n" ] } ], "source": [ "\"\"\"Simulate the Deutsch-Jozsa circuit and check the results.\"\"\"\n", "\n", "print(\"Result on constant functions:\")\n", "for oracle in constant:\n", " result = simulator.run(cirq.Circuit(dj_circuit(oracle)), repetitions=10)\n", " print(result)\n", "\n", "print(\"\\nResult on balanced functions:\")\n", "for oracle in balanced:\n", " result = simulator.run(cirq.Circuit(dj_circuit(oracle)), repetitions=10)\n", " print(result)" ] }, { "cell_type": "markdown", "metadata": { "id": "2d62c4a01340" }, "source": [ "As with the single-bit case (Deutsch's algorithm), we always measure $0$ for constant functions and always measure $1$ for balanced functions." ] }, { "cell_type": "markdown", "metadata": { "id": "mmhbPIhT4YAI" }, "source": [ "# Gates" ] }, { "cell_type": "markdown", "metadata": { "id": "F5ubTic94X79" }, "source": [ "Cirq comes with a plethora of common quantum gates. Here we show a few of them." ] }, { "cell_type": "code", "execution_count": 30, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.819107Z", "iopub.status.busy": "2025-05-30T09:55:40.818854Z", "iopub.status.idle": "2025-05-30T09:55:40.827427Z", "shell.execute_reply": "2025-05-30T09:55:40.826795Z" }, "id": "iIpoDaqK4yjV" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0: ───X───@───H───────@───×───@───@───iSwap──────Rx(0.5π)───X^0.5───\n", " │ │ │ │ │ │\n", "1: ───Y───@───@───T───@───×───×───@───iSwap──────Ry(0.5π)───────────\n", " │ │ │ │\n", "2: ───Z───────X───S───@───────×───X───Rz(0.5π)──────────────────────\n" ] } ], "source": [ "\"\"\"Examples of common gates defined in Cirq.\"\"\"\n", "\n", "# Get some qubits.\n", "q0, q1, q2 = cirq.LineQubit.range(3)\n", "\n", "# Get a bunch of common gates defined in Cirq.\n", "ops = [\n", " cirq.X(q0), # Pauli-X.\n", " cirq.Y(q1), # Pauli-Y.\n", " cirq.Z(q2), # Pauli-Z.\n", " cirq.CZ(q0, q1), # Controlled-Z gate.\n", " cirq.CNOT(q1, q2), # Controlled-X gate.\n", " cirq.H(q0), # Hadamard gate.\n", " cirq.T(q1), # T gate.\n", " cirq.S(q2), # S gate.\n", " cirq.CCZ(q0, q1, q2), # Controlled CZ gate.\n", " cirq.SWAP(q0, q1), # Swap gate.\n", " cirq.CSWAP(q0, q1, q2), # Controlled swap gate.\n", " cirq.CCX(q0, q1, q2), # Toffoli (CCNOT) gate.\n", " cirq.ISWAP(q0, q1), # ISWAP gate.\n", " cirq.Rx(rads=0.5 * np.pi)(q0), # Rotation about X.\n", " cirq.Ry(rads=0.5 * np.pi)(q1), # Rotation about Y.\n", " cirq.Rz(rads=0.5 * np.pi)(q2), # Rotation about Z.\n", " cirq.X(q0) ** 0.5, # Sqrt of NOT gate.\n", "]\n", "\n", "# Display a circuit with all of these operations.\n", "print(cirq.Circuit(ops))" ] }, { "cell_type": "markdown", "metadata": { "id": "FKRGtncT7R0v" }, "source": [ "For each of these gates, you can figure out how they act on the computational basis by calling `cirq.unitary` on the gate. For example, to see the unitary of `CNOT`, we can do:" ] }, { "cell_type": "code", "execution_count": 31, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.829994Z", "iopub.status.busy": "2025-05-30T09:55:40.829746Z", "iopub.status.idle": "2025-05-30T09:55:40.833707Z", "shell.execute_reply": "2025-05-30T09:55:40.833121Z" }, "id": "7SUAT5F17afR" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[[1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n", " [0.+0.j 1.+0.j 0.+0.j 0.+0.j]\n", " [0.+0.j 0.+0.j 0.+0.j 1.+0.j]\n", " [0.+0.j 0.+0.j 1.+0.j 0.+0.j]]\n" ] } ], "source": [ "\"\"\"Get the unitary of CNOT.\"\"\"\n", "\n", "print(cirq.unitary(cirq.CNOT))" ] }, { "cell_type": "markdown", "metadata": { "id": "flm4CcqT2DoI" }, "source": [ "For single qubit gates, we have named gates like `cirq.H` for the Hadmard gate as well as the single qubit rotation gates defined as follows.\n", "\n", "$$ \n", "{\\tt cirq.Rx(\\theta)}: \\exp(-i \\frac{\\theta}{2} X) = cos \\frac{\\theta}{2} I - i \\sin \\frac{\\theta}{2} X =\\left[ \\begin{array} ~\\cos \\frac{\\theta}{2} & -i \\sin \\frac{\\theta}{2} \\\\ -i \\sin \\frac{\\theta}{2} & \\cos \\frac{\\theta}{2}\\end{array} \\right] \\\\\n", "$$ \n", "$$ \n", "{\\tt cirq.Ry(\\theta)}: \\exp(-i \\frac{\\theta}{2} Y) = cos \\frac{\\theta}{2} I - i \\sin \\frac{\\theta}{2} Y =\\left[ \\begin{array} ~\\cos \\frac{\\theta}{2} & -\\sin \\frac{\\theta}{2} \\\\ \\sin \\frac{\\theta}{2} & \\cos \\frac{\\theta}{2}\\end{array} \\right] \\\\\n", "$$ \n", "$$ \n", "{\\tt cirq.Rz(\\theta)}: \\exp(-i \\frac{\\theta}{2} Z) = cos \\frac{\\theta}{2} I - i \\sin \\frac{\\theta}{2} Z =\\left[ \\begin{array} ~e^{i \\frac{\\theta}{2}} & 0 \\\\ 0 & e^{-i \\frac{\\theta}{2}} \\end{array} \\right] \\\\\n", "$$ \n", "\n", "In addition to `cirq.unitary` another important method (behind the scenes, anyways) is `cirq.apply_unitary`. This allows you to apply a unitary gate onto a state. Of course we could have applied the unitary directly to the state, using `cirq.unitary`. We'll see below in understanding how these methods are implemented that the `cirq.apply_unitary` can be used to apply the gate more directly onto the state and can save allocations of memory to store the unitary. \n", "\n", "If we apply `cirq.Rx` to a state we can see how it rotates the state. To do this let us introduce a new simulate method `simulate_moment_steps`. This allows us to simulate the circuit `Moment` by `Moment`. At each point we can access the state. For example here we can use this to create a circuit that is a series of small `cirq.Rx` rotations and plot the probability of measuring the state in the $|0\\rangle$ state:" ] }, { "cell_type": "code", "execution_count": 32, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:40.836100Z", "iopub.status.busy": "2025-05-30T09:55:40.835870Z", "iopub.status.idle": "2025-05-30T09:55:41.010725Z", "shell.execute_reply": "2025-05-30T09:55:41.010027Z" }, "id": "UgoNBN1H8B6h" }, "outputs": [ { "data": { "image/png": "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NpvbX01hrly5gtOnT8vdDCIiIqqDuLg4REVFOX1fk8nL9evXUVBQgMDAQPj58coYERGRGlitVly7dg0GgwH16jm/OKTJ5IWIiIi0i6cliIiISFWYvBAREZGqMHkRKCcnB0899RS6deuGPn36YO7cubXeDa10OTk5mDBhArp164YePXrglVdeQWFhIc6dO4c2bdogKSnJ4c+KFSvkbrIobdq0QWJiokMf5syZAwDYtWsXRowYgU6dOmHw4MH49ttvZW6teHv37q02R4mJiWjTpg1+++23Gufw+++/l7vZtfr555/Ro0cPTJo0qdp7mzdvxpAhQ9CxY0c88MAD+OWXX6res1qtWLBgAe6991506dIFTz75JM6ePevNpgvmqo//+c9/MHToUHTs2BEDBw7El19+WfXe4sWL0bZt22rzevnyZW82XxBnffz6669x++23V+vDoUOHAKhnHp31b8aMGdX6Fh8fj1dffRUA8MorryA+Pt7h/TvuuEOOLtTK2c8IADhy5Agee+wxdO7cGQMGDMDKlSsd/q2rWJWEjQQZPny4bcaMGbbCwkJbdna2bcCAAbaVK1fK3Sy33HfffbZXXnnFVlRUZMvNzbU98MADtunTp9vOnj1ra926tdzNc1vr1q1tZ8+erfb6hQsXbB06dLCtXbvWVlZWZtu5c6etXbt2tkOHDsnQSmktW7bM9sILL9h2795t69Onj9zNEW358uW2AQMG2EaOHGl78cUXHd47fPiwLTEx0bZ9+3ZbWVmZbcOGDbb27dvbcnNzbTabzfbZZ5/Z+vTpYzt58qTtjz/+sL3xxhu2IUOG2KxWqxxdccpVHw8ePGhLSkqybd261VZRUWHbvn27LSEhwbZ3716bzWazLVq0yPbyyy/L0WxRXPXxq6++sj322GNO/60a5tFV/25WUVFhGzx4sG379u02m81me/nll22LFi3yRjPd5uxnRGlpqa1Xr162xYsX24qLi20ZGRm2rl272rZs2WKz2WqPVSnwzIsAJpMJR48exdSpUxEeHo64uDiMGTMGqampcjetzgoLC5GYmIgpU6YgNDQURqMRw4cPx759++Rumsdt3LgRcXFxGDFiBAIDA9GjRw/07dsXa9eulbtpbjl//jxSUlLw0ksvyd2UOgsMDMS6devQvHnzau+tXbsWvXv3Ru/evREYGIihQ4eidevWVWfN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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "\"\"\"Plot the probability of measuring a qubit in the ground state.\"\"\"\n", "\n", "# Get a qubit.\n", "a = cirq.NamedQubit('a')\n", "\n", "# Get a circuit of a bunch of X rotations.\n", "num_angles = 200\n", "circuit = cirq.Circuit([cirq.Rx(rads=np.pi / 50.0)(a) for theta in range(num_angles)])\n", "\n", "# List to store probabilities of the ground state.\n", "probs = []\n", "\n", "# Step through the simulation results.\n", "for step in simulator.simulate_moment_steps(circuit):\n", " prob = np.abs(step.state_vector(copy=True)) ** 2\n", " probs.append(prob[0])\n", "\n", "# Plot the probability of the ground state at each simulation step.\n", "plt.style.use('seaborn-v0_8-whitegrid')\n", "plt.plot(probs, 'o')\n", "plt.xlabel(\"Step\")\n", "plt.ylabel(\"Probability of ground state\");" ] }, { "cell_type": "markdown", "metadata": { "id": "6q0YkXSZBvzd" }, "source": [ "Above we have given ourselves direct access to the wave function and calculated the exact probabilities. Suppose we wanted to sample from the wave function at each point instead. " ] }, { "cell_type": "code", "execution_count": 33, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.013796Z", "iopub.status.busy": "2025-05-30T09:55:41.013513Z", "iopub.status.idle": "2025-05-30T09:55:41.222520Z", "shell.execute_reply": "2025-05-30T09:55:41.221908Z" }, "id": "iynhJEvoCIro" }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "\"\"\"Plot the probability of measuring a qubit in the ground state by sampling.\"\"\"\n", "\n", "# Number of times to sample.\n", "repetitions = 100\n", "\n", "# List to store the probability of the ground state.\n", "sampled_probs = []\n", "\n", "for i, step in enumerate(simulator.simulate_moment_steps(circuit)):\n", " samples = step.sample([a], repetitions=repetitions)\n", " prob = np.sum(samples, axis=0)[0] / repetitions\n", " sampled_probs.append(prob)\n", "\n", "\n", "# Plot the probability of the ground state at each simulation step.\n", "plt.style.use('seaborn-v0_8-whitegrid')\n", "plt.plot(sampled_probs, 'o')\n", "plt.xlabel(\"Step\")\n", "plt.ylabel(\"Probability of ground state\");" ] }, { "cell_type": "markdown", "metadata": { "id": "2483adccd339" }, "source": [ "## Custom gates" ] }, { "cell_type": "markdown", "metadata": { "id": "RACz4Z5GDMAf" }, "source": [ "Suppose there is a gate that you want Cirq to support, but it is not implemented in Cirq. How do you go about defining your new gate? \n", "\n", "Cirq aims to be Pythonic. One way in which it does this is that it relies on Python's **protocol** pattern. Protocols are similar to interfaces, in that they define a collection of methods that an object must support to implement a protocol, but different in that this requirement is more informal and not a part of a class or interface declaration. An object supports a protocol if it implements the methods that the protocol defines. You're probably familiar with this if you've ever done something like defined your own `Container` in Python. To do this for an object you simply define the `__contains__`, `__setitem__`, and `__getitem__` methods on your object, and then you can use this object anywere the Container protocol is supported. \n", "\n", "Let's see how this works for defining a custom gate. The gate we will define is a single qubit gate that has only rational amplitudes. This is based on the famous 3, 4, 5 triangle you may remember from a long ago math class: $3^2 + 4^2 = 5^2$. Using this observation we can construct normalized vectors and a unitary transform using the ratios of $3$, $4$, and $5$: \n", "$$\n", "\\zeta =\\left[ \\begin{array}\n", "~\\frac{3}{5} & \\frac{4}{5} \\\\\n", "-\\frac{4}{5} & \\frac{3}{5}\n", "\\end{array} \\right]\n", "$$\n", "\n", "Below is a simple implementation of this gate in Cirq. To do this we simply define a class that inherits from `cirq.Gate` and implements the `cirq.SupportsUnitary` protocol by implementing the `_unitary_(self)` method. We also define an optional `__str__` representation which Cirq will use when printing this gate out in a circuit diagram." ] }, { "cell_type": "code", "execution_count": 34, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.225253Z", "iopub.status.busy": "2025-05-30T09:55:41.225001Z", "iopub.status.idle": "2025-05-30T09:55:41.229184Z", "shell.execute_reply": "2025-05-30T09:55:41.228622Z" }, "id": "Y2a7t2qmLDTb" }, "outputs": [], "source": [ "\"\"\"Example of defining a custom gate in Cirq.\"\"\"\n", "\n", "\n", "class RationalGate(cirq.Gate):\n", " def _num_qubits_(self) -> int:\n", " return 1\n", "\n", " def _unitary_(self):\n", " return np.array([[3 / 5, 4 / 5], [-4 / 5, 3 / 5]])\n", "\n", " def __str__(self):\n", " return 'ζ'" ] }, { "cell_type": "markdown", "metadata": { "id": "6d262b57bb0c" }, "source": [ "We can now use this custom gate just like any other gate in Cirq." ] }, { "cell_type": "code", "execution_count": 35, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.231624Z", "iopub.status.busy": "2025-05-30T09:55:41.231406Z", "iopub.status.idle": "2025-05-30T09:55:41.235864Z", "shell.execute_reply": "2025-05-30T09:55:41.235260Z" }, "id": "28f06d1baf9b" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───ζ───\n" ] } ], "source": [ "\"\"\"Using the custom gate in a circuit.\"\"\"\n", "\n", "a = cirq.NamedQubit('a')\n", "rg = RationalGate()\n", "print(cirq.Circuit(rg(a)))" ] }, { "cell_type": "markdown", "metadata": { "id": "3132dcbe8413" }, "source": [ "We can also get its unitary, as shown below, because the `RationalGate` defines a `_unitary_` method." ] }, { "cell_type": "code", "execution_count": 36, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.238298Z", "iopub.status.busy": "2025-05-30T09:55:41.238056Z", "iopub.status.idle": "2025-05-30T09:55:41.241681Z", "shell.execute_reply": "2025-05-30T09:55:41.241083Z" }, "id": "x9dHKNfgMoyz" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[[ 0.6 0.8]\n", " [-0.8 0.6]]\n" ] } ], "source": [ "print(cirq.unitary(rg))" ] }, { "cell_type": "markdown", "metadata": { "id": "xmF-uscmPP_G" }, "source": [ "Let's check that we can use this gate in a simulation." ] }, { "cell_type": "code", "execution_count": 37, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.244532Z", "iopub.status.busy": "2025-05-30T09:55:41.243903Z", "iopub.status.idle": "2025-05-30T09:55:41.249174Z", "shell.execute_reply": "2025-05-30T09:55:41.248594Z" }, "id": "_RXBrSQ8PWnu" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[ 0.6+0.j -0.8+0.j]\n" ] } ], "source": [ "\"\"\"Simulate a circuit with a custom gate.\"\"\"\n", "\n", "circuit = cirq.Circuit(rg(a))\n", "simulator = cirq.Simulator()\n", "result = simulator.simulate(circuit)\n", "print(result.final_state_vector)" ] }, { "cell_type": "markdown", "metadata": { "id": "9da706cd9038" }, "source": [ "> *Note on simulating circuits with custom gates.* The `_unitary_` method is extremely inefficient for gates over many qubits. In most cases the method `_apply_unitary_` will be used instead, if it is available.\n", "This method allows much more fine grained control on how a unitary is applied to a state, but it is harder to implement, for example because it is expected to use the pre-allocated workspace buffer that was given to it.\n", "Almost all of the basic gates we have defined in Cirq have this method implemented. If you need to get performant, custom multi-qubit gates, you should implement a custom `_apply_unitary_` method for such gates." ] }, { "cell_type": "markdown", "metadata": { "id": "y63aDja8R4rc" }, "source": [ "## Exercise: Custom Controlled Rx gate\n", "\n", "Recall that the `cirq.Rx` gate is a rotation about the $X$ Pauli axis:\n", "$$ \n", "{\\tt cirq.Rx(θ)}: \\exp(-i \\frac{\\theta}{2} X) = cos \\frac{\\theta}{2} I - i \\sin \\frac{\\theta}{2} X =\\left[ \\begin{array} ~\\cos \\frac{\\theta}{2} & -i \\sin \\frac{\\theta}{2} \\\\ -i \\sin \\frac{\\theta}{2} & \\cos \\frac{\\theta}{2}\\end{array} \\right] . \\\\\n", "$$ \n", "\n", "As an exercise, create a two-qubit controlled `cirq.Rx` gate defined as follows:\n", "$$\n", "{\\tt CRx(\\theta)}:\n", "\\left[\\begin{array}\n", "~1 & 0 & 0 & 0 \\\\\n", "0 & 1 & 0 & 0 \\\\\n", "0 & 0 & \\cos \\frac{\\theta}{2} & -i \\sin \\frac{\\theta}{2} \\\\\n", "0 & 0 & -i \\sin \\frac{\\theta}{2} & \\cos \\frac{\\theta}{2}\n", "\\end{array} \\right] .\n", "$$" ] }, { "cell_type": "code", "execution_count": 38, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.252075Z", "iopub.status.busy": "2025-05-30T09:55:41.251428Z", "iopub.status.idle": "2025-05-30T09:55:41.256207Z", "shell.execute_reply": "2025-05-30T09:55:41.255579Z" }, "id": "9htgTzqAYHsA" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[]\n" ] } ], "source": [ "# @title Attempt the solution here\n", "\"\"\"Define a custom controlled cirq.rx gate here.\"\"\"\n", "\n", "\n", "class CRx(cirq.Gate):\n", " def __init__(self, theta):\n", " self.theta = theta\n", "\n", " def _num_qubits_(self):\n", " return 2\n", "\n", " def _unitary_(self):\n", " return np.array(\n", " [\n", " # Your code here!\n", " ]\n", " )\n", "\n", "\n", "# Print out its unitary.\n", "print(np.around(cirq.unitary(CRx(0.5 * np.pi)), 3))" ] }, { "cell_type": "code", "execution_count": 39, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.258840Z", "iopub.status.busy": "2025-05-30T09:55:41.258323Z", "iopub.status.idle": "2025-05-30T09:55:41.264466Z", "shell.execute_reply": "2025-05-30T09:55:41.263859Z" }, "id": "XaG8n5bdGgf2" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[[1. +0.j 0. +0.j 0. +0.j 0. +0.j ]\n", " [0. +0.j 1. +0.j 0. +0.j 0. +0.j ]\n", " [0. +0.j 0. +0.j 0.707+0.j 0. -0.707j]\n", " [0. +0.j 0. +0.j 0. -0.707j 0.707+0.j ]]\n" ] } ], "source": [ "# @title Expand to view the solution\n", "\"\"\"Defining a custom controlled cirq.Rx gate.\"\"\"\n", "\n", "\n", "class CRx(cirq.Gate):\n", " def __init__(self, theta):\n", " self.theta = theta\n", "\n", " def _num_qubits_(self):\n", " return 2\n", "\n", " def _unitary_(self):\n", " return np.array(\n", " [\n", " [1, 0, 0, 0],\n", " [0, 1, 0, 0],\n", " [0, 0, np.cos(self.theta / 2), -1j * np.sin(self.theta / 2)],\n", " [0, 0, -1j * np.sin(self.theta / 2), np.cos(self.theta / 2)],\n", " ]\n", " )\n", "\n", " def _circuit_diagram_info_(self, args):\n", " return '@', f'Rx({self.theta / np.pi}π)'\n", "\n", "\n", "# Print out its unitary.\n", "print(np.around(cirq.unitary(CRx(0.5 * np.pi)), 3))" ] }, { "cell_type": "markdown", "metadata": { "id": "af7add86ab34" }, "source": [ "Note that we also define the `_circuit_diagram_info_` method which tells Cirq how to display the gate in a circuit diagram. The first string in the tuple is the symbol for the top wire, and the second string in the tuple is the symbol for the bottom wire. We can use this in a circuit to see the diagram info as shown below." ] }, { "cell_type": "code", "execution_count": 40, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.267175Z", "iopub.status.busy": "2025-05-30T09:55:41.266604Z", "iopub.status.idle": "2025-05-30T09:55:41.271140Z", "shell.execute_reply": "2025-05-30T09:55:41.270516Z" }, "id": "a1cd089df7ba" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit diagram:\n", "a: ───@───────────\n", " │\n", "b: ───Rx(0.25π)───\n" ] } ], "source": [ "\"\"\"Display a circuit with the custom gate.\"\"\"\n", "\n", "# Get qubits.\n", "a = cirq.NamedQubit('a')\n", "b = cirq.NamedQubit('b')\n", "\n", "# Display the circuit.\n", "print('Circuit diagram:')\n", "print(cirq.Circuit(CRx(0.25 * np.pi)(a, b)))" ] }, { "cell_type": "markdown", "metadata": { "id": "9W_Vlgpzz0D1" }, "source": [ "## Decompose Protocol\n" ] }, { "cell_type": "markdown", "metadata": { "id": "OXqzGmclSP-n" }, "source": [ "Cirq also supports creating custom \"composite\" gates which can be defined in terms of other \"simpler\" gates. The custom gate should implement the `cirq.SupportsDecompose` protocol by implementing `_decompose_` method.\n", "\n", "Note that implementing `_decompose_` on custom gates is convenient because if a gate has its `_decompose_` method defined, other protocols, like `cirq.SupportsUnitary`, are automatically supported by composing the values obtained from the decomposed operations. \n", "\n", "Below we show how one can construct a custom gate that can be decomposed into two gates." ] }, { "cell_type": "code", "execution_count": 41, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.274289Z", "iopub.status.busy": "2025-05-30T09:55:41.273601Z", "iopub.status.idle": "2025-05-30T09:55:41.277481Z", "shell.execute_reply": "2025-05-30T09:55:41.276889Z" }, "id": "9G-9_29h09Mx" }, "outputs": [], "source": [ "\"\"\"Example of a custom gate which supports the decompose protocol.\"\"\"\n", "\n", "\n", "class HXGate(cirq.Gate):\n", " def _num_qubits_(self) -> int:\n", " return 1\n", "\n", " def _decompose_(self, qubits):\n", " return cirq.H(*qubits), cirq.X(*qubits)\n", "\n", " def __str__(self):\n", " return 'HX'" ] }, { "cell_type": "markdown", "metadata": { "id": "1a88ad617867" }, "source": [ "Even though the above gate does not define a `_unitary_` method, we can use it in a circuit as follows. " ] }, { "cell_type": "code", "execution_count": 42, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.279951Z", "iopub.status.busy": "2025-05-30T09:55:41.279538Z", "iopub.status.idle": "2025-05-30T09:55:41.284499Z", "shell.execute_reply": "2025-05-30T09:55:41.283940Z" }, "id": "370e8528c762" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───HX───\n", "\n", "[[ 0.70710678+0.j -0.70710678+0.j]\n", " [ 0.70710678+0.j 0.70710678+0.j]]\n" ] } ], "source": [ "\"\"\"Use the gate in a circuit.\"\"\"\n", "\n", "HX = HXGate()\n", "\n", "a = cirq.NamedQubit('a')\n", "circuit = cirq.Circuit(HX(a))\n", "assert cirq.has_unitary(HX(a))\n", "print(circuit, cirq.unitary(circuit), sep=\"\\n\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "eb4e74261590" }, "source": [ "The symbol `HX` is a single gate, not a product of two gates. We can decompose the `HXGate` using `cirq.decompose` as shown below." ] }, { "cell_type": "code", "execution_count": 43, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.287049Z", "iopub.status.busy": "2025-05-30T09:55:41.286569Z", "iopub.status.idle": "2025-05-30T09:55:41.290930Z", "shell.execute_reply": "2025-05-30T09:55:41.290341Z" }, "id": "47ec94cdecf3" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───Y^0.5───X───X───\n" ] } ], "source": [ "\"\"\"Decompose the gate.\"\"\"\n", "\n", "print(cirq.Circuit(cirq.decompose(circuit)))" ] }, { "cell_type": "markdown", "metadata": { "id": "RLF1narS66iB" }, "source": [ "Note that this not only decomposed the `HX` gate into `H` and `X`, it also decomposed `H` into `Y**0.5` and `X`. In order to decompose only once, one can use `cirq.decompose_once`:" ] }, { "cell_type": "code", "execution_count": 44, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.293790Z", "iopub.status.busy": "2025-05-30T09:55:41.293225Z", "iopub.status.idle": "2025-05-30T09:55:41.297263Z", "shell.execute_reply": "2025-05-30T09:55:41.296655Z" }, "id": "AS-YMmAv6zUg" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───H───X───\n" ] } ], "source": [ "\"\"\"Decompose the gate once.\"\"\"\n", "\n", "print(cirq.Circuit(cirq.decompose_once(HX(a))))" ] }, { "cell_type": "markdown", "metadata": { "id": "5BtDCUe-XS1H" }, "source": [ "## Gatesets" ] }, { "cell_type": "markdown", "metadata": { "id": "8J5jNvBBXZLp" }, "source": [ "In many contexts, the notion of what gate you can apply is defined either by the physical hardware you are running or perhaps by the quantum error correcting code you are working with. In quantum computing we typically talk about **gate sets** and work with respect to a given gate set. \n", "\n", "Cirq provides a `cirq.Gateset` abstraction to create custom gatesets, which is useful for\n", "\n", " * Describing the set of allowed gates in a human readable format\n", " * Validating a given gate / optree against the set of allowed gates\n", "\n", "\n", "For example, a gateset that supports any x/y/z single qubit rotation and CNOT can be defind as follows:" ] }, { "cell_type": "code", "execution_count": 45, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.300079Z", "iopub.status.busy": "2025-05-30T09:55:41.299658Z", "iopub.status.idle": "2025-05-30T09:55:41.304479Z", "shell.execute_reply": "2025-05-30T09:55:41.303854Z" }, "id": "YnaqZI6dRNxX" }, "outputs": [], "source": [ "# Insert a type (eg: cirq.XPowGate) to accept all instances of that type.\n", "# Insert an instance (eg: cirq.CNOT) to accept only one specific instance of the type.\n", "gateset = cirq.Gateset(cirq.XPowGate, cirq.YPowGate, cirq.ZPowGate, cirq.CNOT)\n", "\n", "# Valid gates and operations are accepted by the gateset.\n", "assert cirq.CNOT(*cirq.LineQubit.range(2)) in gateset\n", "assert cirq.X**0.5 in gateset\n", "\n", "# Arbitrary powers of cirq.CXPowGate are not part of the gateset.\n", "assert cirq.CNOT**0.5 not in gateset" ] }, { "cell_type": "markdown", "metadata": { "id": "3HtlMxa6QpVo" }, "source": [ "# Parameterized Circuits\n", "\n", "In addition to circuit gates with fixed values, Cirq also supports parameterized gates with symbolic values via `sympy`. These are placeholder values, such as `sympy.Symbol('x')`, that will only be resolved at *run-time*. For simulators these values are resolved by providing a `ParamResolver`. A `ParamResolver` provides a map from the `Symbol`'s name to its assigned value. \n", "\n", "> Plain Python dictionaries can also be used whenever a `ParamResolver` is needed." ] }, { "cell_type": "code", "execution_count": 46, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.307057Z", "iopub.status.busy": "2025-05-30T09:55:41.306654Z", "iopub.status.idle": "2025-05-30T09:55:41.312238Z", "shell.execute_reply": "2025-05-30T09:55:41.311570Z" }, "id": "0afe36a32636" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit with parameterized gates:\n", "\n", "a: ───X^s───\n", "\n", "b: ───X^s───\n" ] } ], "source": [ "\"\"\"Define a circuit with parameterized gates.\"\"\"\n", "\n", "# Import sympy for parameterized values.\n", "import sympy as sp\n", "\n", "# Get qubits to use in the circuit.\n", "a = cirq.NamedQubit(\"a\")\n", "b = cirq.NamedQubit(\"b\")\n", "\n", "# Define a parameterized value.\n", "val = sp.Symbol(\"s\")\n", "\n", "# Create a circuit.\n", "circuit = cirq.Circuit(cirq.X.on(a) ** val, cirq.X.on(b) ** val)\n", "\n", "# Display it.\n", "print(\"Circuit with parameterized gates:\\n\")\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "c67ac3447a5f" }, "source": [ "When we simulate this circuit, we must provide a `param_resolver` as mentioned." ] }, { "cell_type": "code", "execution_count": 47, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.314638Z", "iopub.status.busy": "2025-05-30T09:55:41.314257Z", "iopub.status.idle": "2025-05-30T09:55:41.325114Z", "shell.execute_reply": "2025-05-30T09:55:41.324459Z" }, "id": "TIaVRzCD4deU" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "s=0: [1.+0.j 0.+0.j 0.+0.j 0.+0.j]\n", "\n", "s=1: [ 0.6 +0.6j 0.25-0.25j 0.25-0.25j -0.1 -0.1j ]\n", "\n", "s=2: [0. +0.5j 0.5+0.j 0.5+0.j 0. -0.5j]\n", "\n", "s=3: [-0.1 +0.1j 0.25+0.25j 0.25+0.25j 0.6 -0.6j ]\n", "\n", "s=4: [0.+0.j 0.+0.j 0.+0.j 1.+0.j]\n", "\n" ] } ], "source": [ "\"\"\"Simulate the circuit at multiple parameter values.\"\"\"\n", "\n", "simulator = cirq.Simulator()\n", "\n", "# Simulate the circuit for several values of the parameter.\n", "num_params = 5\n", "for y in range(num_params):\n", " result = simulator.simulate(circuit, param_resolver={\"s\": y / 4.0})\n", " print(f\"s={y}: {np.around(result.final_state_vector, 2)}\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "1_2i73Oo4aM1" }, "source": [ "Here we see that the `Symbol` is used in two gates, and then the resolver provides this value at run time.\n", "\n", "Parameterized values are most useful in defining what we call a `cirq.Sweep`. A `cirq.Sweep` is a collection of parameter resolvers. Our `cirq.Simulator` and `cirq.Sampler` (for real devices) interfaces support parameter sweeps. The `run_sweep` method allows the user to a parameterized circuit with each of the configurations. Within each run, the user might specify the number of repetitions as well which determines the sample size for each run. Running parameter sweeps returns a list of `cirq.Result`s, one per set of fixed parameter values and repetitions. Example:\n" ] }, { "cell_type": "code", "execution_count": 48, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.327687Z", "iopub.status.busy": "2025-05-30T09:55:41.327212Z", "iopub.status.idle": "2025-05-30T09:55:41.338923Z", "shell.execute_reply": "2025-05-30T09:55:41.338274Z" }, "id": "Gj_Y3Lrh49o9" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "params: OrderedDict([('s', 0.0)])\n", "a=0000000000\n", "b=0000000000\n", "\n", "params: OrderedDict([('s', 0.125)])\n", "a=0000000000\n", "b=0000000000\n", "\n", "params: OrderedDict([('s', 0.25)])\n", "a=0001000000\n", "b=0000100010\n", "\n", "params: OrderedDict([('s', 0.375)])\n", "a=0110000101\n", "b=0110100100\n", "\n", "params: OrderedDict([('s', 0.5)])\n", "a=1010011010\n", "b=1101000000\n", "\n" ] } ], "source": [ "\"\"\"Simulate the circuit at multiple parameter values.\"\"\"\n", "\n", "# Get a list of param resolvers.\n", "num_params = 5\n", "resolvers = [cirq.ParamResolver({'s': y / 8.0}) for y in range(num_params)]\n", "\n", "# Add measurements to the circuit.\n", "circuit.append([cirq.measure(a), cirq.measure(b)])\n", "\n", "# Simulate the circuit using run_sweep.\n", "results = simulator.run_sweep(program=circuit, params=resolvers, repetitions=10)\n", "\n", "for i, result in enumerate(results):\n", " print(f'params: {result.params.param_dict}\\n{result}\\n')" ] }, { "cell_type": "markdown", "metadata": { "id": "d31ac13186d3" }, "source": [ "A very similar method to `run_sweep` is the `sample` method. This returns a pandas `DataFrame`, where each column is a parameter/measurement key and each row is a repetition.\n" ] }, { "cell_type": "code", "execution_count": 49, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.341492Z", "iopub.status.busy": "2025-05-30T09:55:41.341111Z", "iopub.status.idle": "2025-05-30T09:55:41.366202Z", "shell.execute_reply": "2025-05-30T09:55:41.365647Z" }, "id": "074f9fd5cdcd" }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
sab
count50.00000050.00000050.000000
mean0.2500000.2000000.160000
std0.1785710.4040610.370328
min0.0000000.0000000.000000
25%0.1250000.0000000.000000
50%0.2500000.0000000.000000
75%0.3750000.0000000.000000
max0.5000001.0000001.000000
\n", "
" ], "text/plain": [ " s a b\n", "count 50.000000 50.000000 50.000000\n", "mean 0.250000 0.200000 0.160000\n", "std 0.178571 0.404061 0.370328\n", "min 0.000000 0.000000 0.000000\n", "25% 0.125000 0.000000 0.000000\n", "50% 0.250000 0.000000 0.000000\n", "75% 0.375000 0.000000 0.000000\n", "max 0.500000 1.000000 1.000000" ] }, "execution_count": 49, "metadata": {}, "output_type": "execute_result" } ], "source": [ "results = simulator.sample(program=circuit, params=resolvers, repetitions=10)\n", "\n", "results.describe()" ] }, { "cell_type": "markdown", "metadata": { "id": "av09E7pH44YO" }, "source": [ "Above we passed in a list of `ParamResolver`s to the `params` parameter of `run_sweep` and `sample`. But one can also pass in a `Sweepable`. There are some useful methods for generating `Sweepable`s, for example to generate an equally spaced set of `ParamResolver`s one can use `Linspace`\n" ] }, { "cell_type": "code", "execution_count": 50, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.368945Z", "iopub.status.busy": "2025-05-30T09:55:41.368417Z", "iopub.status.idle": "2025-05-30T09:55:41.372400Z", "shell.execute_reply": "2025-05-30T09:55:41.371838Z" }, "id": "zOymGxlb72Fk" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "cirq.ParamResolver({'x': 0.0})\n", "cirq.ParamResolver({'x': 0.1})\n", "cirq.ParamResolver({'x': 0.2})\n", "cirq.ParamResolver({'x': 0.3})\n", "cirq.ParamResolver({'x': 0.4})\n", "cirq.ParamResolver({'x': 0.5})\n", "cirq.ParamResolver({'x': 0.6})\n", "cirq.ParamResolver({'x': 0.7})\n", "cirq.ParamResolver({'x': 0.8})\n", "cirq.ParamResolver({'x': 0.9})\n", "cirq.ParamResolver({'x': 1.0})\n" ] } ], "source": [ "\"\"\"Alternative method of getting a sequence of param resolvers.\"\"\"\n", "\n", "linspace = cirq.Linspace(start=0, stop=1.0, length=11, key='x')\n", "for p in linspace:\n", " print(p)" ] }, { "cell_type": "markdown", "metadata": { "id": "r-CjbPwkRI_I" }, "source": [ "## Exercise: Rotate a qubit\n", "\n", "Let's do the equivalent of a Rabi-flop experiment. That is, let's apply a `XPowGate` rotating about the `X` axis for a linearly spaced set of values followed by a computational basis measurement. The end result should be a plot of the sampled fraction that were $|1\\rangle$ as a function of gates of $X^t$ for $t$ between 0 and $1$ for 100 values of $t$ and each result sampled 100 times." ] }, { "cell_type": "code", "execution_count": 51, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.375279Z", "iopub.status.busy": "2025-05-30T09:55:41.374723Z", "iopub.status.idle": "2025-05-30T09:55:41.380644Z", "shell.execute_reply": "2025-05-30T09:55:41.380047Z" }, "id": "8yW2e3sq9JM8" }, "outputs": [], "source": [ "# @title Attempt the solution here\n", "import pandas\n", "\n", "q = cirq.NamedQubit(\"q\")\n", "theta = sp.Symbol(\"theta\")\n", "parameterized_circuit = cirq.Circuit(\n", " # your code here\n", " cirq.measure(q)\n", ")\n", "# replace None with something else\n", "param_resolvers = None\n", "repetitions = 100\n", "results = cirq.Simulator().sample(\n", " program=parameterized_circuit, params=param_resolvers, repetitions=repetitions\n", ")\n", "\n", "# You can test with the following plot\n", "# pandas.crosstab(results.theta, results.q).plot()" ] }, { "cell_type": "code", "execution_count": 52, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.383064Z", "iopub.status.busy": "2025-05-30T09:55:41.382569Z", "iopub.status.idle": "2025-05-30T09:55:41.725939Z", "shell.execute_reply": "2025-05-30T09:55:41.725245Z" }, "id": "sl1UGhThC6rn" }, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 52, "metadata": {}, "output_type": "execute_result" }, { "data": { "image/png": "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dx81NTX069d0MaewsDCKi4tbveaBAwdaPd4VMuTTMnk2revtz8fXoH55bEvZS01O+4MPnaueT3jWWoYClQED2b9jh0vu6cgA/5H0Zyup/hMp2769zfN7+89PV8izaV1vej5OCz709SL++Mc/2gONm266iauuuoqZM2d26pqJiYkEBAQ4q4mAispSUlJITk7GZGq7eFNfIs+mdX3l+URt3sKxilL6xScwYXRMuz/n6udjKP4CgICEyUyYMKHb79ei5KexVN3L0OD+rZ7WV35+OkOeTet60vOpqqpqV8eB04KPqChbnYCQEPu+uLg4NE2jvr6ekpKSJucXFxcTERHR6jVNJlO3PejuvHZPJ8+mdb39+YQGqDyPijpLp76ny55PwX4AjDFJ4M7/HiYT+MR34PTe/fPTFfJsWtcTnk972+e02S6xsbEEBQWxd+9e+76srCy8vb056aST2LVrV5Pzd+3axfjx4511eyGEk/SYWh/2mS6S5ClET+O04MPLy4vFixfzyiuvkJGRQWFhIS+++CILFy7kvPPOIysri+XLl1NbW8v69etZv349F154obNuL4RwkobF5Tx4qm19jSppDhJ8CNEDOXWq7e23305dXR1Lliyhvr6e008/nfvuu4/AwEBeffVVHnroIR588EHi4uJ44oknGDVqVNsXFUK4VI9YXK7gAGhW8A+HoH5tny+E8ChODT58fHx44IEHeOCBB5odmzp1KitXrnTm7YQQ3aBHLC6nD7lEj4Y2VvMVQngeWdtFCNFEj1hcTi+rHiO9p0L0RBJ8CCGasCecenTw4aCsuhCix5DgQwjRhJ5wWu7JCafHLygnRB+0ZcsW5s+fz/jx47nyyit54403OPnknrG4oQQfQogmgj19qm1dJZRkqG2Z6SL6KIvFwl133cUpp5zCzz//zI033sh7773n7ma1mwQfQogmGoZdPLTnI18VFyMwGgKj3NsWIdwkJSWFvLw8rrnmGnx9fZk4cSKnnnqqu5vVbhJ8CCGasNf5qK5Hqy2HPStVb4OnyLMVMpQhF9GH5eTkEBQURFhYmH3f4MGD3degDpLgQwjRhN7zYbZqmH94ET68DH582c2taiTfFnxIsqnow/T11BqztrKqsqeR4EMI0USAjwmTUdXOMBfZcityd7XyCRezz3SRng/Rd8XExFBRUUFZWZl938GDB93Yoo6R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z3H22Wdrd999t1ZRUaFlZ2dr559/vnbPPfc0O2/Pnj3a2LFjtXXr1mk1NTXaypUrtfHjx2vZ2dluaLVrtPfZfPTRR9oll1zihha6T21trXbCCSdoL7zwglZbW6sVFhZql1xyiXb99dc3O7e3/N3Vq3o+UlJS2LdvH3fccQfBwcEkJCSwbNkyPvjgg2bnfvDBB5x//vmMHz8ePz8//vjHPwKwdu1aVzfbZTryfPoiX19fVqxYweDBg9s894MPPmDZsmUMGzaMoKAgbr31VlJTU9mxY4cLWuoeHXk+fVFZWRljx47l9ttvJzAwkNjYWM477zx+/fXXZucuX76ck046iZNOOglfX1/OOeccEhMTWbVqlRta3v068mz6ourqam699VauueYafHx8iIiI4LTTTuPgwYPNzu0tf3f1quBj9+7dxMXFERoaat83ZswY0tPTqaioaHZuUlKS/b3RaGT06NGkpKS4rL2u1pHnA7B//36WLl3KpEmTWLBgQa/vFr7ssssIDg5u87yamhoOHTrU5OcnKCiIwYMH9+qfn/Y+H92PP/7IokWLmDhxIosXL+6ZXcMdEBISwqOPPkpUVJR9X3Z2NjExMc3OPf73D0BSUlKv/fnpyLPRj11++eVMnTqVU045hZUrV7qqqW4RGhrKkiVL7FNT09LS+OSTTzjzzDObndtb/u7qVcFHSUkJISEhTfbpf9EWFxc3O7fxX8L6ucef15t05PnExsYycOBAHn/8cX744QeWLFnCtddeS1pamsva66lKS0vRNK3P/fx0xMCBAxk8eDCvvvoqGzduZMqUKVxxxRV96vmkpKTw3nvvcd111zU71hd//zTW2rOJiIggISGBO++8kx9++IHbbruNe+65hy1btrihpa6VlZXF2LFjOeuss0hOTubmm29udk5v+dnpVcEHgNaBsiUdObe3aO93XrJkCc899xyDBw/G39+fZcuWMXr06F7bLdwZffHnp71uuOEGHnnkEfr160dQUBB33nknPj4+rFmzxt1Nc4mtW7dy5ZVXcvvttzNz5kyH5/TVn5+2ns3cuXN54403SEpKwsfHhwULFnDaaafx8ccfu6G1rhUXF0dKSgpff/01hw8f5s9//rPD83rDz06vCj4iIiIoKSlpsq+kpASDwUBEREST/eHh4Q7PPf683qQjz8eRuLg48vLyuql1PUdYWBhG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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# @title Expand to view the solution\n", "import pandas\n", "\n", "q = cirq.NamedQubit(\"q\")\n", "parameterized_circuit = cirq.Circuit([cirq.Rx(rads=sp.Symbol(\"theta\"))(q), cirq.measure(q)])\n", "param_resolvers = cirq.Linspace(start=0, stop=np.pi, length=100, key='theta')\n", "results = cirq.Simulator().sample(\n", " program=parameterized_circuit, params=param_resolvers, repetitions=repetitions\n", ")\n", "pandas.crosstab(results.theta, results.q).plot()" ] }, { "cell_type": "markdown", "metadata": { "id": "930ee2edd71b" }, "source": [ "# Noise" ] }, { "cell_type": "markdown", "metadata": { "id": "FEM73JPALREa" }, "source": [ "In addition to circuits with unitary gates, Cirq also has support for modeling noisy quantum evolutions. This is useful when modeling what will happen when running on actual hardware.\n", "\n", "Cirq currently supports noise that fits within the context of *operator sum representations* of noise (a.k.a quantum operations, quantum dyanamical maps, superoperators, etc). This formalism models the evolution of a density matrix via \n", "\n", "$$ \n", "\\rho \\rightarrow \\sum_k A_k \\rho A_k^\\dagger \n", "$$\n", "\n", "where the $A_k$ are *Kraus operators*. These operators are not necessarily unitary and satisfy the property\n", "\n", "$$ \n", "\\sum_k A_k^\\dagger A_k = I . \n", "$$\n", "\n", "An example of a noise operator is the depolarizing channel on one qubit. This takes\n", "\n", "$$\n", "\\rho \\rightarrow (1-p) \\rho + \\frac{p}{3} (X \\rho X + Y \\rho Y + Z \\rho Z) .\n", "$$\n", "\n", "In Cirq we can define such a channel and use it in a quantum circuit:" ] }, { "cell_type": "code", "execution_count": 53, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.728903Z", "iopub.status.busy": "2025-05-30T09:55:41.728631Z", "iopub.status.idle": "2025-05-30T09:55:41.733493Z", "shell.execute_reply": "2025-05-30T09:55:41.732845Z" }, "id": "YclVFbKZ0aD4" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a: ───D(0.2)───M───\n" ] } ], "source": [ "\"\"\"Create a circuit with a depolarizing channel.\"\"\"\n", "\n", "circuit = cirq.Circuit(cirq.depolarize(0.2)(a), cirq.measure(a))\n", "print(circuit)" ] }, { "cell_type": "markdown", "metadata": { "id": "CvteYd9s00t_" }, "source": [ "Previously we saw that gates could implement that `_unitary_` protocol, and by doing so they could be used to perform wave function simulation. For noise the gates implement the `_kraus_` protocol. Classes that implement this protocol return the Krauss operators on their `_kraus_` method. Thus" ] }, { "cell_type": "code", "execution_count": 54, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.736352Z", "iopub.status.busy": "2025-05-30T09:55:41.735754Z", "iopub.status.idle": "2025-05-30T09:55:41.740953Z", "shell.execute_reply": "2025-05-30T09:55:41.740313Z" }, "id": "0ig_NSrS12PE" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Kraus operator 0 is:\n", "[[0.89442719 0. ]\n", " [0. 0.89442719]]\n", "\n", "Kraus operator 1 is:\n", "[[0. +0.j 0.25819889+0.j]\n", " [0.25819889+0.j 0. +0.j]]\n", "\n", "Kraus operator 2 is:\n", "[[0.+0.j 0.-0.25819889j]\n", " [0.+0.25819889j 0.+0.j ]]\n", "\n", "Kraus operator 3 is:\n", "[[ 0.25819889+0.j 0. +0.j]\n", " [ 0. +0.j -0.25819889+0.j]]\n", "\n" ] } ], "source": [ "for i, kraus in enumerate(cirq.kraus(cirq.depolarize(0.2))):\n", " print(f\"Kraus operator {i} is:\", kraus, sep=\"\\n\", end=\"\\n\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "4ee0055e4015" }, "source": [ "The Kraus operators are often more conveniently represented in a Pauli basis. We can do this in Cirq as shown below." ] }, { "cell_type": "code", "execution_count": 55, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.743546Z", "iopub.status.busy": "2025-05-30T09:55:41.743304Z", "iopub.status.idle": "2025-05-30T09:55:41.748285Z", "shell.execute_reply": "2025-05-30T09:55:41.747591Z" }, "id": "a2e5258ae33d" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Kraus operator 0 is:\n", "0.894*I\n", "\n", "Kraus operator 1 is:\n", "0.258*X\n", "\n", "Kraus operator 2 is:\n", "0.258*Y\n", "\n", "Kraus operator 3 is:\n", "0.258*Z\n", "\n" ] } ], "source": [ "for i, kraus in enumerate(cirq.kraus(cirq.depolarize(0.2))):\n", " pauli_ex = cirq.expand_matrix_in_orthogonal_basis(kraus, cirq.PAULI_BASIS)\n", " print(f\"Kraus operator {i} is:\", pauli_ex, sep=\"\\n\", end=\"\\n\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "spU2l26r0tQS" }, "source": [ "In addition to the wavefunction simulator, Cirq also has a density matrix simulator. Instead of keeping track of the wavefunction, this simulator keeps track of the density matrix. It has the same `run` and `simulate` type methods. For example we can use this to simulate depolarizing channel and return the final density matrix of the system." ] }, { "cell_type": "code", "execution_count": 56, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.750823Z", "iopub.status.busy": "2025-05-30T09:55:41.750572Z", "iopub.status.idle": "2025-05-30T09:55:41.757328Z", "shell.execute_reply": "2025-05-30T09:55:41.756614Z" }, "id": "skLIvXYq4yvX" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit:\n", "a: ───D(0.2)───\n", "\n", "Final density matrix:\n", "[[0.8666667 +0.j 0. +0.j]\n", " [0. +0.j 0.13333333+0.j]]\n" ] } ], "source": [ "\"\"\"Example of simulating a noisy circuit with the density matrix simulator.\"\"\"\n", "\n", "# Circuit to simulate.\n", "circuit = cirq.Circuit(cirq.depolarize(0.2)(a))\n", "print(f'Circuit:\\n{circuit}\\n')\n", "\n", "# Get the density matrix simulator.\n", "simulator = cirq.DensityMatrixSimulator()\n", "\n", "# Simulate the circuit and get the final density matrix.\n", "matrix = simulator.simulate(circuit).final_density_matrix\n", "print(f'Final density matrix:\\n{matrix}')" ] }, { "cell_type": "markdown", "metadata": { "id": "Eudp7NYo51LT" }, "source": [ "One thing to note is that the density matrix simulator simulates measurement statistically, and not as a channel where the outcome is not known. Consider the following example." ] }, { "cell_type": "code", "execution_count": 57, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.759846Z", "iopub.status.busy": "2025-05-30T09:55:41.759527Z", "iopub.status.idle": "2025-05-30T09:55:41.767620Z", "shell.execute_reply": "2025-05-30T09:55:41.766986Z" }, "id": "_SjPRrIX5F4O" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "False\n" ] } ], "source": [ "\"\"\"Simulating a circuit with measurements using the DensityMatrixSimulator.\"\"\"\n", "\n", "# Get a circuit with measurements.\n", "circuit = cirq.Circuit(cirq.depolarize(0.5)(a), cirq.measure(a))\n", "\n", "# Simulate with the density matrix multiple times.\n", "dmat1 = simulator.simulate(circuit).final_density_matrix\n", "dmat2 = simulator.simulate(circuit).final_density_matrix\n", "\n", "print(np.allclose(dmat1, dmat2))" ] }, { "cell_type": "markdown", "metadata": { "id": "286ab4baf9fd" }, "source": [ "Because the final density matrix is statistical due to the measurements, the output of the above cell will change when executed multiple times." ] }, { "cell_type": "markdown", "metadata": { "id": "3qUM-Kpi8Iy4" }, "source": [ "## Monte carlo simulations\n", "\n", "Density matrix simulations are more expensive than pure state wave function simulations. However some channels allow an interpreation of randomly applying one of a fixed set of unitaries with differing probabilites. For example the depolarizing channel above can be interpretted as: \n", "\n", "- With probability $1-p$ apply the identity to the state, and\n", "- with probability $p$ apply one of the three Pauli matrices $X$, $Y$, or $Z$ with equal probability.\n", "\n", "Channels that can be interpretted in this form can be simulating using a wavefunction simulator: when this channel is simulated the simulation will sample a unitary with the appropriate probability. \n", "\n", "For channels of these type, the channel can, instead of implementing the `_kraus_` protocol, implement the `_mixture_` protocol:" ] }, { "cell_type": "code", "execution_count": 58, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.770731Z", "iopub.status.busy": "2025-05-30T09:55:41.770191Z", "iopub.status.idle": "2025-05-30T09:55:41.775067Z", "shell.execute_reply": "2025-05-30T09:55:41.774406Z" }, "id": "9Pt7o-Tq2SNz" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "prob = 0.8\n", "unitary: \n", "[[1. 0.]\n", " [0. 1.]]\n", "\n", "prob = 0.06666666666666667\n", "unitary: \n", "[[0.+0.j 1.+0.j]\n", " [1.+0.j 0.+0.j]]\n", "\n", "prob = 0.06666666666666667\n", "unitary: \n", "[[0.+0.j 0.-1.j]\n", " [0.+1.j 0.+0.j]]\n", "\n", "prob = 0.06666666666666667\n", "unitary: \n", "[[ 1.+0.j 0.+0.j]\n", " [ 0.+0.j -1.+0.j]]\n", "\n" ] } ], "source": [ "\"\"\"Use the cirq.mixture protocol on the cirq.depolarize channel.\"\"\"\n", "\n", "for p, u in cirq.mixture(cirq.depolarize(0.2)):\n", " print(f\"prob = {p}\\nunitary: \\n{u}\\n\")" ] }, { "cell_type": "markdown", "metadata": { "id": "z4FIsadc4Nmg" }, "source": [ "In fact the depolarizing channel does not implement `_kraus_`. Instead it only implements `_mixture_` and the `cirq.kraus` method notices this and derives the kraus operators from the mixture." ] }, { "cell_type": "code", "execution_count": 59, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.777503Z", "iopub.status.busy": "2025-05-30T09:55:41.777256Z", "iopub.status.idle": "2025-05-30T09:55:41.781482Z", "shell.execute_reply": "2025-05-30T09:55:41.780845Z" }, "id": "HvhpBD334o1v" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "does cirq.depolarize(0.2) have _kraus_? no\n", "does cirq.depolarize(0.2) have _mixture_? yes\n" ] } ], "source": [ "\"\"\"Check if cirq.depolarize has _kraus_ and _mixture_ methods.\"\"\"\n", "\n", "# Get a depolarizing channel.\n", "d = cirq.depolarize(0.2)\n", "\n", "# Check if it has _kraus_ implemented.\n", "print(f\"does cirq.depolarize(0.2) have _kraus_? {'yes' if getattr(d, '_kraus_', None) else 'no'}\")\n", "\n", "# Check if it has _mixture_ implemented.\n", "print(\n", " f\"does cirq.depolarize(0.2) have _mixture_? {'yes' if getattr(d, '_mixture_', None) else 'no'}\"\n", ")" ] }, { "cell_type": "markdown", "metadata": { "id": "OMCyapOd28h2" }, "source": [ "When channels implement mixture then, as we said, we can use the wavefunction simulator:" ] }, { "cell_type": "code", "execution_count": 60, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.784411Z", "iopub.status.busy": "2025-05-30T09:55:41.783833Z", "iopub.status.idle": "2025-05-30T09:55:41.796527Z", "shell.execute_reply": "2025-05-30T09:55:41.795896Z" }, "id": "vDEhGG0v-UJy" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "a=0100101000\n" ] } ], "source": [ "\"\"\"Use the wavefunction simulator on a channel that implements the mixture protocol.\"\"\"\n", "\n", "circuit = cirq.Circuit(cirq.depolarize(0.5).on(a), cirq.measure(a))\n", "simulator = cirq.Simulator()\n", "result = simulator.run(circuit, repetitions=10)\n", "print(result)" ] }, { "cell_type": "markdown", "metadata": { "id": "a13d48d4836f" }, "source": [ "Because the unitary Kraus operators are applied stochastically, executing the above cell multiple times will produce different outputs." ] }, { "cell_type": "markdown", "metadata": { "id": "weWPzaPx8zly" }, "source": [ "## Adding noise to circuits and simulations" ] }, { "cell_type": "markdown", "metadata": { "id": "X-dT_CLu0fH9" }, "source": [ "To add noise to circuits or during simulations, we provide the notion of a `NoiseModel`. A `NoiseModel` may add noise operation by operation, or it may add noise moment by moment, or it may add noise across a list of moments.\n", "\n", "For example we can define a noise model that add a single qubit depolarizing for every qubit in each moment. " ] }, { "cell_type": "code", "execution_count": 61, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.799425Z", "iopub.status.busy": "2025-05-30T09:55:41.798866Z", "iopub.status.idle": "2025-05-30T09:55:41.805906Z", "shell.execute_reply": "2025-05-30T09:55:41.805335Z" }, "id": "PfRP7K598wNQ" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Circuit with no noise:\n", "a: ───H───@───M───\n", " │ │\n", "b: ───────X───M───\n", "\n", "Circuit with noise:\n", "a: ───H───D(0.2)[]───@───D(0.2)[]───M───D(0.2)[]───\n", " │ │\n", "b: ───────D(0.2)[]───X───D(0.2)[]───M───D(0.2)[]───\n" ] } ], "source": [ "\"\"\"Adding noise to a circuit.\"\"\"\n", "\n", "# Get a noiseless circuit.\n", "noise = cirq.ConstantQubitNoiseModel(cirq.depolarize(0.2))\n", "circuit = cirq.Circuit(cirq.H(a), cirq.CNOT(a, b), cirq.measure(a, b))\n", "print(f'Circuit with no noise:\\n{circuit}\\n')\n", "\n", "# Add noise to the circuit.\n", "system_qubits = sorted(circuit.all_qubits())\n", "noisy_circuit = cirq.Circuit()\n", "for moment in circuit:\n", " noisy_circuit.append(noise.noisy_moment(moment, system_qubits))\n", "print(f'Circuit with noise:\\n{noisy_circuit}')" ] }, { "cell_type": "markdown", "metadata": { "id": "e4946d8f236f" }, "source": [ "We can also pass a noise model into the `cirq.DensityMatrixSimulator` and execute a noisy circuit in this manner." ] }, { "cell_type": "code", "execution_count": 62, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.808380Z", "iopub.status.busy": "2025-05-30T09:55:41.808136Z", "iopub.status.idle": "2025-05-30T09:55:41.820357Z", "shell.execute_reply": "2025-05-30T09:55:41.819690Z" }, "id": "uzxaFCGIz2aQ" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "After step 0 state was\n", "[[0.43333334+0.j 0. +0.j 0.31777778+0.j 0. +0.j]\n", " [0. +0.j 0.06666666+0.j 0. +0.j 0.04888889+0.j]\n", " [0.31777778+0.j 0. +0.j 0.43333334+0.j 0. +0.j]\n", " [0. +0.j 0.04888889+0.j 0. +0.j 0.06666666+0.j]]\n", "\n", "After step 1 state was\n", "[[0.3485926 +0.j 0. +0.j 0. +0.j 0.17089383+0.j]\n", " [0. +0.j 0.15140742+0.j 0.02629136+0.j 0. +0.j]\n", " [0. +0.j 0.02629136+0.j 0.15140742+0.j 0. +0.j]\n", " [0.17089383+0.j 0. +0.j 0. +0.j 0.3485926 +0.j]]\n", "\n", "After step 2 state was\n", "[[0.75111115+0.j 0. +0.j 0. +0.j 0. +0.j]\n", " [0. +0.j 0.11555555+0.j 0. +0.j 0. +0.j]\n", " [0. +0.j 0. +0.j 0.11555555+0.j 0. +0.j]\n", " [0. +0.j 0. +0.j 0. +0.j 0.01777778+0.j]]\n", "\n" ] } ], "source": [ "\"\"\"Perform noisy simulation by defining a density matrix simulator with a noise model.\"\"\"\n", "\n", "# Define a noise model.\n", "noise = cirq.ConstantQubitNoiseModel(cirq.depolarize(0.2))\n", "\n", "# Pass this noise model into the simulator.\n", "simulator = cirq.DensityMatrixSimulator(noise=noise)\n", "\n", "# Get a circuit to simulate.\n", "circuit = cirq.Circuit(cirq.H(a), cirq.CNOT(a, b), cirq.measure(a, b))\n", "\n", "# Simulate the circuit in steps.\n", "for i, step in enumerate(simulator.simulate_moment_steps(circuit)):\n", " print(f'After step {i} state was\\n{step.density_matrix()}\\n')" ] }, { "cell_type": "markdown", "metadata": { "id": "6308948de99a" }, "source": [ "# Devices" ] }, { "cell_type": "markdown", "metadata": { "id": "PvJCA3e0QsuI" }, "source": [ "NISQ algorithms work in a regime where every gate counts. A key philosophy behind Cirq is that we believe the details of the hardware, the performance characteristics, as well as device constraints, will be key to getting the most out of NISQ algorithms. Towards this end these hardware features are contained in the `Device` class.\n", "\n", "For example, here is Google's Sycamore device which we printed out at the start of this notebook." ] }, { "cell_type": "code", "execution_count": 63, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.822869Z", "iopub.status.busy": "2025-05-30T09:55:41.822608Z", "iopub.status.idle": "2025-05-30T09:55:41.830065Z", "shell.execute_reply": "2025-05-30T09:55:41.829422Z" }, "id": "BmzxGpDB9jJ4" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " (0, 5)───(0, 6)\n", " │ │\n", " │ │\n", " (1, 4)───(1, 5)───(1, 6)───(1, 7)\n", " │ │ │ │\n", " │ │ │ │\n", " (2, 3)───(2, 4)───(2, 5)───(2, 6)───(2, 7)───(2, 8)\n", " │ │ │ │ │ │\n", " │ │ │ │ │ │\n", " (3, 2)───(3, 3)───(3, 4)───(3, 5)───(3, 6)───(3, 7)───(3, 8)───(3, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", " (4, 1)───(4, 2)───(4, 3)───(4, 4)───(4, 5)───(4, 6)───(4, 7)───(4, 8)───(4, 9)\n", " │ │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │ │\n", "(5, 0)───(5, 1)───(5, 2)───(5, 3)───(5, 4)───(5, 5)───(5, 6)───(5, 7)───(5, 8)\n", " │ │ │ │ │ │ │\n", " │ │ │ │ │ │ │\n", " (6, 1)───(6, 2)───(6, 3)───(6, 4)───(6, 5)───(6, 6)───(6, 7)\n", " │ │ │ │ │\n", " │ │ │ │ │\n", " (7, 2)───(7, 3)───(7, 4)───(7, 5)───(7, 6)\n", " │ │ │\n", " │ │ │\n", " (8, 3)───(8, 4)───(8, 5)\n", " │\n", " │\n", " (9, 4)\n" ] } ], "source": [ "print(cirq_google.Sycamore)" ] }, { "cell_type": "markdown", "metadata": { "id": "GGejgRf0AGni" }, "source": [ "In a future version, we intend for each `Device` to define a noise model.\n", "\n", "`Device`s also contain more information about the timing of the device. For example here we can calculate the duration of an `X` on the `Sycamore` device." ] }, { "cell_type": "code", "execution_count": 64, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.832590Z", "iopub.status.busy": "2025-05-30T09:55:41.832363Z", "iopub.status.idle": "2025-05-30T09:55:41.836932Z", "shell.execute_reply": "2025-05-30T09:55:41.836360Z" }, "id": "HAwdWkprAPXN" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "25 ns\n" ] } ], "source": [ "\"\"\"Get the duration of an operation.\"\"\"\n", "\n", "op = cirq.X.on(cirq.GridQubit(5, 5))\n", "gate_durations = cirq_google.Sycamore.metadata.gate_durations\n", "for gate_family in gate_durations:\n", " if op in gate_family:\n", " print(gate_durations[gate_family])" ] }, { "cell_type": "markdown", "metadata": { "id": "IxnyURhnAdph" }, "source": [ "Another property of devices is that they can be used to enforce constraints from the hardware, both checking that these constraints are satisfied, but also enforcing the constraints on the device. For example, on the `Sycamore` device, a two-qubit gate can be only be performed between adjacent qubits. So, for example, validating an operation on non-adjacent qubits will raise an error." ] }, { "cell_type": "code", "execution_count": 65, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.839387Z", "iopub.status.busy": "2025-05-30T09:55:41.839170Z", "iopub.status.idle": "2025-05-30T09:55:41.845614Z", "shell.execute_reply": "2025-05-30T09:55:41.845053Z" }, "id": "r5F4FUtmA5kW" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "(5, 5): ───iSwap───────\n", " │\n", "(6, 6): ───iSwap^0.5───\n", "error, as expected: \n", "Qubit pair is not valid on device: (cirq.GridQubit(5, 5), cirq.GridQubit(6, 6)).\n" ] } ], "source": [ "\"\"\"Validate operations on a device.\"\"\"\n", "\n", "# Get non-adjacent qubits on the Sycamore device.\n", "q55 = cirq.GridQubit(5, 5)\n", "q56 = cirq.GridQubit(5, 6)\n", "q66 = cirq.GridQubit(6, 6)\n", "\n", "# Operations on adjacent qubits will be validated.\n", "cirq_google.Sycamore.validate_operation(cirq.SQRT_ISWAP(q55, q56))\n", "cirq_google.Sycamore.validate_operation(cirq.SQRT_ISWAP(q56, q66))\n", "\n", "# Operation on non-adjacent qubits will raise an error.\n", "ops = [cirq.SQRT_ISWAP(q55, q66)]\n", "circuit = cirq.Circuit(ops)\n", "print(circuit)\n", "\n", "try:\n", " cirq_google.Sycamore.validate_circuit(circuit)\n", "except ValueError as ex:\n", " print(f\"error, as expected: \\n{ex}\")" ] }, { "cell_type": "markdown", "metadata": { "id": "lyFcloaARXg4" }, "source": [ "### Exercise: Make a Device\n", "\n", "Construct a device that acts on a square sized lattice, and only allows Hadamard, CZ, and measurement gates." ] }, { "cell_type": "code", "execution_count": 66, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.848351Z", "iopub.status.busy": "2025-05-30T09:55:41.847722Z", "iopub.status.idle": "2025-05-30T09:55:41.850648Z", "shell.execute_reply": "2025-05-30T09:55:41.850084Z" }, "id": "zDE-19I_a3on" }, "outputs": [], "source": [ "# @title Attempt the solution here" ] }, { "cell_type": "code", "execution_count": 67, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.852935Z", "iopub.status.busy": "2025-05-30T09:55:41.852578Z", "iopub.status.idle": "2025-05-30T09:55:41.857694Z", "shell.execute_reply": "2025-05-30T09:55:41.857060Z" }, "id": "DuOcTG3XZfmb" }, "outputs": [], "source": [ "# @title Expand to view the solution\n", "class SquareDevice(cirq.Device):\n", " \"\"\"A Square Grid Device.\n", "\n", " The device that only allows\n", " 1) Grid Qubits from (0, 0) to (grid_size - 1, grid_size - 1)\n", " 2) H, CZ and MeasurementGate gates.\n", " \"\"\"\n", "\n", " def __init__(self, grid_size):\n", " self.qubits = []\n", " for i in range(grid_size):\n", " for j in range(grid_size):\n", " self.qubits.append(cirq.GridQubit(i, j))\n", "\n", " def validate_operation(self, operation: 'cirq.Operation') -> None:\n", " if not isinstance(operation, cirq.GateOperation):\n", " raise ValueError(f\"Unsupported operation {operation}\")\n", " if not (\n", " operation.gate in [cirq.H, cirq.CZ] or isinstance(operation.gate, cirq.MeasurementGate)\n", " ):\n", " raise ValueError(f\"Unsupported gate {operation.gate}\")\n", " for qubit in operation.qubits:\n", " if qubit not in self.qubits:\n", " raise ValueError(f\"Qubit {qubit} not on device\")" ] }, { "cell_type": "markdown", "metadata": { "id": "0ffeaed6f5e2" }, "source": [ "# Quantum Virtual Machine\n", "\n", "Cirq provides the [Quantum Virtual Machine](../simulate/quantum_virtual_machine.ipynb) as a way to run circuits using the same interface that quantum hardware uses and get results that approximate those the hardware would produce. It combines [Devices](../hardware/devices.ipynb), [Noisy Simulation](../simulate/noisy_simulation.ipynb), realistic [Noise Models](../noise/representing_noise.ipynb) and a [Virtual Engine Interface](../simulate/virtual_engine_interface.ipynb) to produce a `cirq.SimulatedLocalEngine` that you can treat almost interchangeably with hardware devices. See the [Quantum Virtual Machine](../simulate/quantum_virtual_machine.ipynb) page to learn more about how it works, or jump to the [QVM Creation Template](../simulate/qvm_builder_code.ipynb) notebook to just start using it. " ] }, { "cell_type": "markdown", "metadata": { "id": "ed20ea519cc9" }, "source": [ "# Transformers for circuit compilation" ] }, { "cell_type": "markdown", "metadata": { "id": "J9ia4eatUQ_x" }, "source": [ "A transformer in Cirq is any callable, that satisfies the `cirq.TRANSFORMER` API, and *transforms* an input circuit into an output circuit. A custom transformer can be created by simply decorating the method/class with `@cirq.transformer` decorator. \n", "\n", "Cirq also provides useful transformer primitives which can be composed together to implement common compilation patterns. For example:\n", "\n", "- **`cirq.map_operations`**: Applies local transformations on operations, by calling `map_func(op)` for each `op`.\n", "- **`cirq.merge_operations`**: Merges connected component of operations by calling `merge_func(op1, op2)` on iteratively for every mergeable operation `op1` and `op2`.\n", "\n", "Below, we give an example of how you can create a circuit optimizer using the above primitives. " ] }, { "cell_type": "code", "execution_count": 68, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.860395Z", "iopub.status.busy": "2025-05-30T09:55:41.860163Z", "iopub.status.idle": "2025-05-30T09:55:41.867035Z", "shell.execute_reply": "2025-05-30T09:55:41.866461Z" }, "id": "l7eFMVe1GEe2" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Before optimizing:\n", "a: ───X───Z───@───X───\n", " │\n", "b: ───────────@───────\n", "\n", "After optimizing:\n", "a: ───Y───────@───X───\n", " │\n", "b: ───────────@───────\n" ] } ], "source": [ "\"\"\"Example of writing a custom cirq transformer.\"\"\"\n", "\n", "@cirq.transformer\n", "def xz_optimizer(circuit, *, context=None):\n", " \"\"\"Replaces an X followed by a Z with a Y.\"\"\"\n", "\n", " def merge_func(op1, op2):\n", " return cirq.Y(*op1.qubits) if op1.gate == cirq.X and op2.gate == cirq.Z else None\n", "\n", " return cirq.merge_operations(circuit, merge_func)\n", "\n", "\n", "circuit = cirq.Circuit(cirq.X(a), cirq.Z(a), cirq.CZ(a, b), cirq.X(a))\n", "print(f\"Before optimizing:\\n{circuit}\\n\")\n", "circuit = xz_optimizer(circuit)\n", "print(f\"After optimizing:\\n{circuit}\")" ] }, { "cell_type": "markdown", "metadata": { "id": "--aUfkiaUb3S" }, "source": [ "## Exercise: Simplify flipped CNOTs\n", "\n", "Write a transformer, using transformer primitives, which (greedily) performs the simplification that\n", "\n", "```\n", "a: ───H───@───H───\n", " │\n", "b: ───H───X───H───\n", "```\n", "is equal to\n", "\n", "\n", "```\n", "a: ───X───\n", " │\n", "b: ───@───\n", "```\n" ] }, { "cell_type": "code", "execution_count": 69, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.869401Z", "iopub.status.busy": "2025-05-30T09:55:41.869185Z", "iopub.status.idle": "2025-05-30T09:55:41.873600Z", "shell.execute_reply": "2025-05-30T09:55:41.873037Z" }, "id": "S0PThmctKFxl" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "None\n" ] } ], "source": [ "# @title Attempt the solution here\n", "@cirq.transformer\n", "def simplify_flipped_cnots(circuit, *, context=None):\n", " # Use transformer primitives to simplify your circuit.\n", " pass\n", "\n", "\n", "\"\"\"Test your optimizer on this circuit.\"\"\"\n", "circuit = cirq.Circuit(\n", " cirq.H.on_each(a, b, c), cirq.CNOT(a, b), cirq.H.on_each(a, b), cirq.CZ(a, b)\n", ")\n", "print(simplify_flipped_cnots(circuit))" ] }, { "cell_type": "code", "execution_count": 70, "metadata": { "cellView": "form", "execution": { "iopub.execute_input": "2025-05-30T09:55:41.875726Z", "iopub.status.busy": "2025-05-30T09:55:41.875502Z", "iopub.status.idle": "2025-05-30T09:55:41.886992Z", "shell.execute_reply": "2025-05-30T09:55:41.886408Z" }, "id": "O8pnDlAngS80" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Before optimizing:\n", "a: ───H───@───H───@───\n", " │ │\n", "b: ───H───X───H───@───\n", "\n", "c: ───H───────────────\n", "\n", "After optimizing:\n", "a: ───────X───────@───\n", " │ │\n", "b: ───────@───────@───\n", "\n", "c: ───H───────────────\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n" ] } ], "source": [ "# @title Expand to view the solution\n", "def simplify_flipped_cnots(circuit, *, context=None):\n", " \"\"\"Replaces a CX surrounded by Hadamards\"\"\"\n", "\n", " def can_merge(ops1, ops2):\n", " merged = cirq.Circuit(ops1, ops2)\n", " return (\n", " len(merged) <= 3\n", " and all(o.gate == cirq.H for o in merged[0].operations)\n", " and merged[1].operations[0].gate == cirq.CNOT\n", " and (len(merged) < 3 or all(o.gate == cirq.H for o in merged[2].operations))\n", " )\n", "\n", " merged_tag = \"h_cx_h\"\n", " circuit = cirq.merge_operations_to_circuit_op(\n", " circuit, can_merge, merged_circuit_op_tag=merged_tag\n", " )\n", "\n", " def map_func(op, _):\n", " if merged_tag not in op.tags:\n", " return op\n", " cops = [*op.untagged.mapped_circuit().all_operations()]\n", " return cirq.CNOT(*cops[2].qubits[::-1]) if len(cops) == 5 else cops\n", "\n", " return cirq.map_operations(circuit, map_func)\n", "\n", "\n", "circuit = cirq.Circuit(\n", " cirq.H.on_each(a, b, c), cirq.CNOT(a, b), cirq.H.on_each(a, b), cirq.CZ(a, b)\n", ")\n", "print(f\"Before optimizing:\\n{circuit}\\n\")\n", "print(f\"After optimizing:\\n{simplify_flipped_cnots(circuit)}\")" ] }, { "cell_type": "markdown", "metadata": { "id": "Q-C_Yh6oz9uq" }, "source": [ "## Compiling to Target Gatesets\n", "\n", "Cirq's philosophy on compiling circuits for execution on a NISQ target device or simulator is that it would often require running only a handful of individual compilation passes on the input circuit, one after the other. \n", "\n", "**`cirq.CompilationTargetGateset`** is an abstraction in Cirq to represent such compilation targets as well as the bundles of transformer passes which should be executed to compile a circuit to this target. Cirq has implementations for common target gatesets like `cirq.CZTargetGateset`, `cirq.SqrtIswapTargetGateset` etc.\n", "\n", "\n", "Below, we give an example of compiling a circuit to a specific target gateset. " ] }, { "cell_type": "code", "execution_count": 71, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:41.889331Z", "iopub.status.busy": "2025-05-30T09:55:41.889116Z", "iopub.status.idle": "2025-05-30T09:55:42.025058Z", "shell.execute_reply": "2025-05-30T09:55:42.024410Z" }, "id": "ydDrxmlL18F1" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Original Circuit (depth 6): ┌──┐ ┌──┐\n", "0: ───iSwap──────────────iSwap───iSwap────@─────\n", " │ │ │ │\n", "1: ───┼─────────×────T───iSwap───iSwap────┼×────\n", " │ │ ││\n", "2: ───┼────────T┼────────X────────────────@┼────\n", " │ │ │\n", "3: ───iSwap─────×──────────────────────────×────\n", " └──┘ └──┘\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Compiled circuit for CZ Target (depth 17):" ] }, { "name": "stdout", "output_type": "stream", "text": [ " ┌──────────────────┐ ┌───────────────────────┐\n", "0: ───PhXZ(a=0.25,x=-0.5,z=0)─────────@───PhXZ(a=0.25,x=0.5,z=5.55e-17)───@───PhXZ(a=-0.75,x=0.5,z=0.5)────────────────────────────────────────────────────────────────PhXZ(a=0,x=0,z=1)──────────────────────────────────────────────────────────────@─────────────────────────────────────────────────────────────────\n", " │ │ │\n", "1: ───────────────────────────────────┼───────────────────────────────────┼───────────────────────────────@───PhXZ(a=0.5,x=0.5,z=0)───@───PhXZ(a=0.5,x=-0.5,z=0)───@───PhXZ(a=-1.11e-16,x=0.25,z=0.5)────@──────────────────────PhXZ(a=0,x=-0.5,z=0)──┼────@───PhXZ(a=-2.22e-16,x=0.5,z=0)───@───PhXZ(a=0,x=0,z=-0.5)───\n", " │ │ │ │ │ │ │ │ │\n", "2: ───────────────────────────────────┼───────────────────────────────────┼───────────────────────────────┼───────────────────────────┼────────────────────────────┼───PhXZ(a=0,x=0,z=0.25)──────────────┼PhXZ(a=0,x=1,z=0)───────────────────────────@────┼─────────────────────────────────┼──────────────────────────\n", " │ │ │ │ │ │ │ │\n", "3: ───PhXZ(a=0.25,x=0.5,z=5.55e-17)───@───PhXZ(a=0.25,x=-0.5,z=0)─────────@───PhXZ(a=0.25,x=0.5,z=0.5)────@───PhXZ(a=0.5,x=0.5,z=0)───@───PhXZ(a=0.5,x=-0.5,z=0)───@───PhXZ(a=-0.5,x=0,z=-1)─────────────@──────────────────────PhXZ(a=0.5,x=-0.5,z=0)─────@───PhXZ(a=0.5,x=0.5,z=0)─────────@───PhXZ(a=0,x=0,z=0.5)────\n", " └──────────────────┘ └───────────────────────┘\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Compiled circuit for Sqrt-Iswap Target (depth 16): " ] }, { "name": "stdout", "output_type": "stream", "text": [ " ┌──────────────────┐ ┌──────────────────┐\n", "0: ───PhXZ(a=-4.44e-16,x=0,z=0.5)───iSwap───────iSwap──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────PhXZ(a=-0.5,x=0.5,z=0.5)──────────────iSwap────────PhXZ(a=-0.5,x=1,z=0)───────────────────iSwap────────PhXZ(a=-1,x=0.5,z=1.04e-08)───────────────────────────────────────────\n", " │ │ │ │\n", "1: ─────────────────────────────────┼───────────┼─────────────────────────────────────iSwap───────PhXZ(a=-0.83,x=0.5,z=0.83)───iSwap───────PhXZ(a=0.5,x=0.5,z=0)───iSwap───────PhXZ(a=-0.5,x=0.92,z=0.5)────iSwap────┼────────────PhXZ(a=0.17,x=0.5,z=-0.17)────iSwap────┼────────────PhXZ(a=0.5,x=0.5,z=0)─────────iSwap───────PhXZ(a=0.5,x=0.83,z=-0.5)───\n", " │ │ │ │ │ │ │ │ │ │\n", "2: ─────────────────────────────────┼───────────┼─────────────────────────────────────┼────────────────────────────────────────┼───────────────────────────────────┼───────────PhXZ(a=-1,x=0.5,z=0)─────────┼────────iSwap^0.5──────────────────────────────────┼────────iSwap^0.5────PhXZ(a=-1,x=0.5,z=0.25)───────┼───────────────────────────────────────\n", " │ │ │ │ │ │ │ │\n", "3: ─────────────────────────────────iSwap^0.5───iSwap^0.5───PhXZ(a=-1.0,x=0,z=-0.5)───iSwap^0.5───PhXZ(a=-0.83,x=0.5,z=0.83)───iSwap^0.5───PhXZ(a=0.5,x=0.5,z=0)───iSwap^0.5───PhXZ(a=0.5,x=0.83,z=0.5)─────iSwap^0.5─────────────PhXZ(a=0.17,x=0.5,z=-0.17)────iSwap^0.5─────────────PhXZ(a=0.5,x=0.5,z=0)─────────iSwap^0.5───PhXZ(a=0.5,x=0.83,z=-1.0)───\n", " └──────────────────┘ └──────────────────┘\n" ] }, { "name": "stderr", "output_type": "stream", "text": [ "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n", "/tmpfs/src/tf_docs_env/lib/python3.10/site-packages/cirq/circuits/circuit_operation.py:173: FutureWarning: In cirq 1.6 the default value of `use_repetition_ids` will change to\n", "`use_repetition_ids=False`. To make this warning go away, please pass\n", "explicit `use_repetition_ids`, e.g., to preserve current behavior, use\n", "\n", " CircuitOperations(..., use_repetition_ids=True)\n", " warnings.warn(msg, FutureWarning)\n" ] } ], "source": [ "circuit = cirq.testing.random_circuit(qubits=4, n_moments=6, op_density=0.8, random_state=1234)\n", "print(f\"Original Circuit (depth {len(circuit)}):\", circuit)\n", "cz_compiled_circuit = cirq.optimize_for_target_gateset(circuit, gateset=cirq.CZTargetGateset())\n", "cirq.testing.assert_circuits_with_terminal_measurements_are_equivalent(\n", " circuit, cz_compiled_circuit, atol=1e-6\n", ")\n", "print(f\"Compiled circuit for CZ Target (depth {len(cz_compiled_circuit)}):\", cz_compiled_circuit)\n", "sqrt_iswap_compiled_circuit = cirq.optimize_for_target_gateset(\n", " circuit, gateset=cirq.SqrtIswapTargetGateset()\n", ")\n", "cirq.testing.assert_circuits_with_terminal_measurements_are_equivalent(\n", " circuit, sqrt_iswap_compiled_circuit, atol=1e-6\n", ")\n", "print(\n", " f\"Compiled circuit for Sqrt-Iswap Target (depth {len(sqrt_iswap_compiled_circuit)}):\",\n", " sqrt_iswap_compiled_circuit,\n", ")" ] }, { "cell_type": "markdown", "metadata": { "id": "b13526b78348" }, "source": [ "# Other interesting things in Cirq" ] }, { "cell_type": "markdown", "metadata": { "id": "tMC-nLE474nH" }, "source": [ "**Experiments**. The `cirq.experiments` package can perform and plot the results of some basic experiments for understanding how well a system is performing.\n" ] }, { "cell_type": "code", "execution_count": 72, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:42.028389Z", "iopub.status.busy": "2025-05-30T09:55:42.027718Z", "iopub.status.idle": "2025-05-30T09:55:42.348847Z", "shell.execute_reply": "2025-05-30T09:55:42.348131Z" }, "id": "Ih8YgwX19h2-" }, "outputs": [ { "data": { "image/png": "iVBORw0KGgoAAAANSUhEUgAAA6YAAAGpCAYAAACeSysXAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjMsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvZiW1igAAAAlwSFlzAAAPYQAAD2EBqD+naQABAABJREFUeJzsnXd8G/X9/1/akuW994YASYCwQhIgkLDKaEoINNAyS4GWWaAtYZRR8gXKbJmFskuhv9ICAUqB0JZN2CEEkpDEtiTLlockW3vd/f5wP8dJlmyNOw37/Xw8eDyILd+dTqfP+/Ner7eC53keBEEQBEEQBEEQBJEjlLm+AIIgCIIgCIIgCGJ2Q44pQRAEQRAEQRAEkVPIMSUIgiAIgiAIgiByCjmmBEEQBEEQBEEQRE4hx5QgCIIgCIIgCILIKeSYEgRBEARBEARBEDmFHFOCIAiCIAiCIAgip5BjShAEQRAEQRAEQeQUckwJgiAIgiAIgiCInEKOaYFx5ZVXYs6cOcJ/8+bNw6GHHopLL70UH3zwQc6uy2KxYM6cOXjmmWckPe4999yDOXPm4LTTTkv4mrVr12LOnDm48sorJT03Y8OGDZgzZw7efvvtjI81OjqKQw89FH/6058ATP482X/77bcffvKTn+DTTz/N+JzxSOY9xbu2efPm4eijj8Z9992HYDAo+XWFQiH88Ic/lO2zJAiCkAOyzZMpZNvM3l8gEMj42FJx5ZVXYsmSJbm+jCn5xz/+MWnfsPvuu+Pggw/GNddcg6GhIVnOe8stt+D444+Hx+OR5fhE9iDHtACprKzEu+++i3fffRevvfYabr75ZhiNRpx99tm45ZZbcnJNDQ0NePfdd3HCCScIPzvssMOwYcOGjI9tMBjw8ccfw2w2T/pdKBTCyy+/jKKiopSPGwwGMW/ePFgslilft2DBArz77rs48MADUz6HmEgkgosuugi77747zjnnHOHn4s/z3Xffxdtvv40HH3wQCoUCZ5xxBr788suMzpsJsdf24osv4sc//jEefvhhyTYbH374IZYtWwYA0Gg0uPvuu/Hvf/8bTz75pCTHJwiCyAZkm79jJtjmfOPqq6/GSy+9lOvLSIqnn35a+C68/vrr+M1vfoMPP/wQp556Knw+X8bHj31GrrjiChiNRvz617/O+NhEblHn+gKI1FEqlaipqRH+3dTUhEWLFmHRokW4/PLL0d3djVWrVmX1mlQqVdQ12Ww2WK1WSY5dWVkJo9GIf/zjH7jkkkuifvf2228jFApht912S/m4mzZtQigUmvZ1Wq026r2lywsvvICNGzfi1Vdfjfp57OcJAHV1dbjnnntwyCGH4KmnnsJtt92W8fnTIfbaampq0NXVBbvdjvvuuw+/+tWvUF9fn9E5Pv/886h/NzQ04JxzzsHdd9+N4447DpWVlRkdnyAIIhuQbf6OmWCb842SkpJcX0LSVFRURH02LS0tKCkpwRlnnIE33ngD3//+9zM6fuwzolarsWbNGpx88sl4++23ccghh2R0fCJ3UMZ0BnHcccdh0aJFeOihh4Sf8TyPxx9/HCtWrMDee++NxYsX4ze/+Q3Gx8eF11x55ZVYsWIFNmzYgJUrV2KvvfbCEUccgeeff154TTAYxC233IJly5Zh/vz5WLJkCX7961/D4XAAiC4X2rBhg7AonH766Vi2bBkuvvhiLF++HDzPR13zK6+8gjlz5mD79u1Tvrdly5bhhRdeAMdxUT9/4YUXcMghh0Ctjo6xeDwe3HTTTTj44IMxd+5cHHLIIbjqqquE6/3HP/6BU089FQCwfPlyoRxp2bJluOmmm7BmzRrstdde+Pe//x1VLjQ+Po5DDjkEV1xxRdT51qxZgyVLlsBut8e9fp7ncd999+G4445Da2vrlO+VYTAY0NbWhsHBwajjTPd5AsDjjz+OY445BvPmzcPChQvxk5/8BFu2bEnqvMnANhtsgxMOh/H73/8ey5cvx9y5c7FkyRJcfPHFURFvVuLz1ltvYfny5TjxxBNx5ZVX4u6770Z/fz/mzJmDe+65BwBw2mmnQalU4pFHHpHsmgmCIHIB2ebvKFTbLD7X+eefjwULFmDJkiV49NFHMTY2hosvvhj77LMPDj74YDzxxBNRf/v222/jlFNOwd57740FCxbghBNOwOuvvx71GpvNhvPPPx977703DjzwQNx666144YUXMGfOHMGOxpbyLlu2DGvXrsXTTz+N5cuXY++998aqVasmVVlNtx9g7+3VV1/F8ccfj0WLFuHWW2/FggULJpXGfvHFF4IdT5XYfQMArFu3DieccALmz5+PfffdF6eccgo++ugj4ffs+f3b3/6G1atXY968eXjiiSfiPiN77bUXlixZIuwjiMKEHNMZxvLly9HX1yd88R944AHccsstOPbYY7Fu3TrccsstePfdd3HhhRdG/Z3dbse9996La665Bi+88AK6urpw7bXXYmBgAABw//3345VXXsHatWvx+uuv4/e//z2+/vpr/PKXv5x0DQsWLMAdd9wBYKJP47nnnsMPf/hDWCyWqAUHmDB+CxYsQHd395Tv6/jjj4fVasWHH34o/MzpdOI///kPjj322Emvv+mmm/DSSy/hlltuwfr163HHHXdgw4YN+M1vfgMAOOaYYwQD9re//S1qIXvrrbdgNBrx0ksvTSoRKi0txdq1a/Hyyy/j/fffBwB89NFHeP7553HTTTclzO5t3rwZ/f39QslqMgSDQZjNZjQ2Ngo/S+bzfOGFF3DzzTfjRz/6EV5//XU88cQTUCqVOPfcc+H3+5M+/1T09vYCmMhuAsCDDz6Ihx9+GL/85S+xfv16PPDAA+jv78fFF1886W//+Mc/4v/+7//w4IMP4uqrr8by5ctRX1+Pd999F2effTaACad88eLFWL9+vSTXSxAEkUvINk9Q6Lb5zjvvxIoVK/DCCy9g8eLF+N3vfoeLL74Yy5Ytw/PPP49FixbhlltuEcqbTSYTfv7zn6OzsxMvvPACXnzxRRx00EG49NJL8fXXXwvHveSSS7Bx40bcdddd+POf/wyXy4X7779/2ut55513sHHjRjz44IN48sknMTY2hl/96lfC71PZDzz44IO45JJL8Pzzz+Pkk0+Gz+fDa6+9FvWaV155BQ0NDTj44IOTul9i+vr6AHy3b/j444/xy1/+EkuXLsU///lP/O1vf0N7ezvOO+882Gy2qL995JFHsGrVKrz++us46aSTEj4jy5Ytw5dffjnp74nCgRzTGQb7wg8PDyMUCuGRRx7BihUrcO6556K1tVWITm7YsAGfffaZ8HdDQ0O49tprsc8++6CjowM/+clPEAqFhIVz8+bNmDNnDhYtWoSGhgbst99+giMSi1arRWlpKQCgrKwMlZWVWLx4Mdra2vCPf/xDeJ3L5cI777yDk046adr31d3djT322AN///vfhZ+9/PLLMBqNcUs2fvGLX+C5557DkiVL0NDQgP333x/f+9738O6774Lneej1ehQXFwOYKEcqLy8X/tbj8eCqq65Ca2tr3P6Ygw8+GCeffDKuv/56uN1uXHfddVi5ciUOO+ywhNf/8ccfAwD233//ad8rAIyMjOA3v/kN3G63EBlM9vNctmwZXnrpJfzoRz9CY2MjdtttN5x22mmw2WzYtm1bUudPRCgUwrvvvotHH30URx55pPC8nXrqqVi3bh2OPvpoNDQ0YM8998SqVauwefPmSZHqY445BgsXLkRNTQ1KSkqg0+mEcjOj0Si8br/99kNvb69sYgkEQRDZgmzzBIVumw855BB873vfQ1tbG8444wzwPI+Wlhb84Ac/QFtbG04//XRwHIetW7cCmGjLefHFF3H11Vejvb0dra2tuPDCCxGJRAQHure3F59//jkuuOACHHbYYeju7sZNN90k3IepcLvduOmmm7DLLrtgzz33xIoVK9DT0wO32w0gtf3A4sWLcfjhh6O+vh4dHR1YuHBh1HPBcRz+9a9/YeXKlVAqk3cfeJ7Ht99+ixtvvBENDQ044ogjAABz587Fyy+/jAsvvBAtLS3o7OzEOeecA6/XG/UdAIBdd90Vq1atQmNjI4qKihI+I/vttx+A7z5XovCgHtMZRjgcBjDRV7Jjxw643e5JKm4s0vj1119jn332AQAUFRVh1113FV7DoousrGj58uW47rrrcPHFF+Poo4/GwoULUV9fn3R/oUKhwMknn4z77rsPv/nNb2A0GvHGG29Ao9Hge9/7XlLHWLFiBe68806Mj4+jtLQUzz//PI466ihoNJpJr1UqlXjqqafw9ttvY2RkBJFIBKFQCKFQCMFgEDqdLuF5dt9992kX3V//+tdYsWIFVq1ahWAwiKuuumrK1w8NDUGtVqOiomLS70ZHR7FgwQLh3xzHwe/3Y+7cubj//vux1157AUDSn6fBYMDbb7+NK6+8ElarFYFAAJFIBMBEJDsVYq8tEAhArVZjxYoVUeJHOp0O69atw5tvvgmbzYZQKCQ8iw6HIypaPW/evKTOzfpThoeHUVtbm9J1EwRB5BNkmycoJNscj7lz5wr/X1ZWJlxX7M9cLheACdu4fft23HjjjdixY0dUaSyzxyaTCQAwf/78qHMdeuih2Lx587TXo9VqhX+z52NsbAzFxcUp7QdibfPq1avxi1/8AmazGS0tLfj4448xMjKCE088ccprAoATTzwRCoUCwERAOxKJ4MADD8Sdd94pBBWKiorwxRdf4Nprr4XJZILP5xNKyqe7tkSwvcLw8HBSryfyD3JMZxh9fX1QKBRobGzEzp07AQDXXHMNrrvuukmvFX9xEynnsUVi9erVqKurw1/+8hesWbMGwWAQBx54IK6++uppS30YK1euxN13341XX30Vq1atwiuvvILjjjsuadW+Y489Fr/73e/wyiuvYP/998dXX32FNWvWxL3mn/zkJxgYGMCVV16JefPmQafT4amnnsJTTz017XlYRHkqjEYjfvCDH+Cee+7BueeeO21k0+Vyobi4WFioxZSXl+Ovf/2r8O+vvvoKl112GX7yk59g6dKlws9ZBHS6z/PWW2/Fn//8Z/z85z/H8uXLUVxcjI0bN8aNoE9H7LWp1WrU1NREGUJgQhHv3XffxRVXXIGFCxfCYDDg9ddfx+233z7pmMkKOLDPIbZ/liAIotAg21x4tjkeBoNB+H/2N/F+xj6fN954Qwga3H333aiuroZCocCRRx4p/A1zwsQVQwCSEv6L/Yxiz5/KfiDWNh9++OGoqqoSxK1eeeUVLF68GE1NTdNe17333ouWlhYAE8GIioqKSZ/F448/jptvvhmnnHIKrrrqKpSVlcFms8UdQZTsvoG9jvYNhQs5pjOM1157DXPnzkVlZSVGR0cBAL/85S/jltSkqvB22GGH4bDDDkMwGMT777+PO+64A+eeey7efPPNpP6+srISRx11FF5++WUsW7YMH374IZ599tmkz19TU4NFixbhn//8JwYHB9HY2Ih999130uu2bduGLVu24IYbbsDKlSuFn0s5d9NiseDRRx/FYYcdhieeeAI/+MEP0NXVlfD1JSUlcLvd4Hl+kgFUqVRoa2sT/t3W1obXXnsNa9euxZIlS4QyFRaJne7zfOmll3DMMcdE9Xdu2rQprfcZe23xcLvd+M9//oOf/vSnOOOMM4Sfx4phpAozLMlsRgiCIPIZss2FZ5ulYN26dairq8Ndd90lZHtj21NYoDd2jEqqFU7xyGQ/oNFocOKJJ+Lll1/GBRdcgNdffx3XX399Un/b0NAw7d5h3bp12HvvvaOOmUikKllYppr2DYUL9ZjOIJ566ils3rwZ559/PgCgo6MDpaWlMJvNaGtrE/5rbm5GOBxOegwHx3F4/fXXBbEFrVaLQw89FBdffDH6+/sxNjaW8G9jlf5Wr16Njz76CE899RS6u7snla5Mx/e//318/vnnePXVV3HcccfFNSRMQlz8/txut6CCF3tNsf+eDp7ncdVVV2HevHl44IEHsP/+++PXv/61UKoVj9raWoTD4aQX3auuugo+nw8333yz8LNkP89gMDjps2Uqjqm+12QIhULgeT7qnJFIBOvWrUv6GPGui2UNqqurM79IgiCIHEG2eYKZYJtTJRQKoaysLKoEOdYet7e3A0CUmi7P85OUe9Mh0/3AySefDIvFIsxWX758ecbXxAiFQpNKqFPdq8S+jjn9UowRInIDOaYFCMdxGB4exvDwMGw2Gz7//HNce+21WLt2Lc477zyhsVytVuOcc87BM888gyeffBK9vb345ptvsGbNGpx00klJq5YplUr86U9/wqWXXopPPvkEAwMD2Lx5M5599lnsuuuuUY3nDJbde++99/D1118Li8f++++Pjo4OPPTQQ0kJK8RyxBFHQKPRoK+vD8cff3zc13R2dqKsrAxPP/00enp68MUXX+Ccc87B4YcfDmBCGt3n8wnX+NZbbwlCBcnw5z//GRs3bsRvf/tbKBQKXH/99di+fTv++Mc/JvwbJqyQbEN+fX09LrroIrzwwgt47733ACT/eS5YsACvv/46Nm7ciB07duDKK69Ec3MzAOCzzz6TvMSloqIC7e3t+Mc//oGtW7fim2++wc9+9jMhYv7xxx8LZcjxKC0txfDwMD755JOoQe0ff/wx2tvbUVdXJ+n1EgRByAHZ5plvm1Nl7733xvbt2/HPf/4TZrMZjzzyCDZu3IiGhgZ8/fXXGBoawpw5c9DZ2YmHH34YH3zwAXbs2IHrrrsu46ojIPP9QHNzMw466CA88MAD+MEPfhC3bzhd9t57b2zYsAHvv/8++vr6cNttt4HjOKhUKnz55ZdTBgsSPSOpilkR+Qc5pgWI3W7HQQcdhIMOOghLly7F+eefD5vNhj/96U+47LLLol573nnn4de//jWeeeYZHHfccfjRj36EsbExPP300ylt+O+77z60tLTgkksuwRFHHIHzzz8f5eXleOCBB+K+fv78+Vi+fDkee+wxnHPOOVEL7Pe+9z1oNJq0BiwXFRXhiCOOwJw5c6IEIWJfc/vtt2NoaAgrVqzAtddei5/+9Ke47LLL0N3djYsvvhifffYZli5din322Qe33HJL3H6YePT19eGOO+7AhRdeKJSpsPvywAMPRMm/i5k7dy6amprwn//8J+n3evrpp2PXXXfFb37zG6HEJ5nP87rrrhMUA88++2y0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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "qubit = cirq.LineQubit(0)\n", "result = cirq.experiments.single_qubit_state_tomography(\n", " sampler=cirq.Simulator(), # In case of Google QCS or other hardware providers, sampler could point at real hardware.\n", " qubit=qubit,\n", " circuit=cirq.Circuit(cirq.Z(qubit), cirq.X(qubit)),\n", " repetitions=1000,\n", ")\n", "result.plot();" ] }, { "cell_type": "markdown", "metadata": { "id": "38c8tWcX90Zn" }, "source": [ "**Testing**. The `cirq.testing` package has useful debugging and testing methods like `cirq.testing.assert_implements_consistent_protocols` and `cirq.testing.assert_allclose_up_to_global_phase`.\n" ] }, { "cell_type": "code", "execution_count": 73, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:42.352423Z", "iopub.status.busy": "2025-05-30T09:55:42.351796Z", "iopub.status.idle": "2025-05-30T09:55:42.356448Z", "shell.execute_reply": "2025-05-30T09:55:42.355775Z" }, "id": "j7FoZGKv90qe" }, "outputs": [], "source": [ "class InconsistentXGate(cirq.Gate):\n", " def _num_qubits_(self) -> int:\n", " return 1\n", "\n", " def _decompose_(self, qubits):\n", " yield cirq.H(qubits[0])\n", " yield cirq.Z(qubits[0])\n", " yield cirq.H(qubits[0])\n", "\n", " def _unitary_(self):\n", " return np.array([[0, -1j], [1j, 0]]) # Oops! Y instead of X!\n", "\n", "\n", "# cirq.testing.assert_decompose_is_consistent_with_unitary(InconsistentXGate())" ] }, { "cell_type": "markdown", "metadata": { "id": "iYqy0qwU9sZy" }, "source": [ "**Export**. You can export a circuit as Qasm." ] }, { "cell_type": "code", "execution_count": 74, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:42.359172Z", "iopub.status.busy": "2025-05-30T09:55:42.358778Z", "iopub.status.idle": "2025-05-30T09:55:42.363526Z", "shell.execute_reply": "2025-05-30T09:55:42.362949Z" }, "id": "qH7xB-vZ-Jsn" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "// Generated from Cirq v1.5.0\n", "\n", "OPENQASM 2.0;\n", "include \"qelib1.inc\";\n", "\n", "\n", "// Qubits: [q(0), q(1), q(2)]\n", "qreg q[3];\n", "\n", "\n", "h q[0];\n", "h q[2];\n", "cx q[0],q[1];\n", "\n", "// Gate: CCZ\n", "h q[2];\n", "ccx q[0],q[1],q[2];\n", "h q[2];\n", "\n" ] } ], "source": [ "\"\"\"Export a circuit to Qasm.\"\"\"\n", "\n", "a, b, c = cirq.LineQubit.range(3)\n", "circuit = cirq.Circuit(cirq.H(a), cirq.H(c), cirq.CNOT(a, b), cirq.CCZ(a, b, c))\n", "print(circuit.to_qasm())" ] }, { "cell_type": "markdown", "metadata": { "id": "QlgFtRQs-TfQ" }, "source": [ "You can also turn a circuit into a link to the drag-and-drop web simulation Quirk (though somewhat inconveniently)." ] }, { "cell_type": "code", "execution_count": 75, "metadata": { "execution": { "iopub.execute_input": "2025-05-30T09:55:42.366486Z", "iopub.status.busy": "2025-05-30T09:55:42.365946Z", "iopub.status.idle": "2025-05-30T09:55:42.370289Z", "shell.execute_reply": "2025-05-30T09:55:42.369714Z" }, "id": "Ydst5b0S9IGE" }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "http://algassert.com/quirk#circuit=%7B%22cols%22%3A%5B%5B%22H%22%2C1%2C%22H%22%5D%2C%5B%22%E2%80%A2%22%2C%22X%22%5D%2C%5B%22%E2%80%A2%22%2C%22%E2%80%A2%22%2C%22Z%22%5D%5D%7D\n" ] } ], "source": [ "\"\"\"Export a circuit to a Quirk URL.\"\"\"\n", "\n", "from cirq.contrib.quirk.export_to_quirk import circuit_to_quirk_url\n", "\n", "print(circuit_to_quirk_url(circuit))" ] } ], "metadata": { "colab": { "collapsed_sections": [], "name": "intro.ipynb", "toc_visible": true }, "kernelspec": { "display_name": "Python 3", "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.10.17" } }, "nbformat": 4, "nbformat_minor": 0 }