custom_gates.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "WZ1G8QHhdHZR"
   },
   "source": [
    "##### Copyright 2020 The Cirq Developers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "cellView": "form",
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:30.446798Z",
     "iopub.status.busy": "2025-03-01T10:30:30.446341Z",
     "iopub.status.idle": "2025-03-01T10:30:30.450288Z",
     "shell.execute_reply": "2025-03-01T10:30:30.449623Z"
    },
    "id": "KQa9t_gadIuR"
   },
   "outputs": [],
   "source": [
    "#@title 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": "xwec7FrkdFmi"
   },
   "source": [
    "# Custom gates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "5KZia7jmdJ3V"
   },
   "source": [
    "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://quantumai.google/cirq/build/custom_gates\"><img src=\"https://quantumai.google/site-assets/images/buttons/quantumai_logo_1x.png\" />View on QuantumAI</a>\n",
    "  </td>\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/quantumlib/Cirq/blob/main/docs/build/custom_gates.ipynb\"><img src=\"https://quantumai.google/site-assets/images/buttons/colab_logo_1x.png\" />Run in Google Colab</a>\n",
    "  </td>\n",
    "  <td>\n",
    "    <a target=\"_blank\" href=\"https://github.com/quantumlib/Cirq/blob/main/docs/build/custom_gates.ipynb\"><img src=\"https://quantumai.google/site-assets/images/buttons/github_logo_1x.png\" />View source on GitHub</a>\n",
    "  </td>\n",
    "  <td>\n",
    "    <a href=\"https://storage.googleapis.com/tensorflow_docs/Cirq/docs/build/custom_gates.ipynb\"><img src=\"https://quantumai.google/site-assets/images/buttons/download_icon_1x.png\" />Download notebook</a>\n",
    "  </td>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:30.453242Z",
     "iopub.status.busy": "2025-03-01T10:30:30.452740Z",
     "iopub.status.idle": "2025-03-01T10:30:49.820952Z",
     "shell.execute_reply": "2025-03-01T10:30:49.820063Z"
    },
    "id": "bd9529db1c0b"
   },
   "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.16.1 requires protobuf<4.21,>=3.20.3; python_version < \"3.11\", but you have protobuf 4.25.6 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 numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "y8P1T6duC-yo"
   },
   "source": [
    "Standard gates such as Pauli gates and `CNOT`s are defined in `cirq.ops` as described [here](gates.ipynb). To use a unitary which is not a standard gate in a circuit, one can create a custom gate as described in this guide."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "71ae01d45738"
   },
   "source": [
    "## General pattern"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ce675022b0b4"
   },
   "source": [
    "Gates are classes in Cirq. To define custom gates, we inherit from a base gate class and define a few methods.\n",
    "\n",
    "The general pattern is to:\n",
    "\n",
    "  - Inherit from `cirq.Gate`.\n",
    "  - Define one of the `_num_qubits_` or `_qid_shape_` methods.\n",
    "  - Define one of the `_unitary_` or `_decompose_` methods.\n",
    "  \n",
    "\n",
    "> *Note*: Methods beginning and ending with one or more underscores are *magic methods* and are used by Cirq's protocols or built-in Python functions. More information about magic methods is included at the end of this guide.\n",
    "\n",
    "We demonstrate these patterns via the following examples.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "38c6a07df259"
   },
   "source": [
    "## From a unitary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "58228b4b49f4"
   },
   "source": [
    "One can create a custom Cirq gate from a unitary matrix in the following manner. Here, we define a gate which corresponds to the unitary\n",
    "\n",
    "\n",
    "$$ U = \\frac{1}{\\sqrt{2}} \\left[ \\begin{matrix} 1 & 1 \\\\ -1 & 1 \\end{matrix} \\right] . $$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.825674Z",
     "iopub.status.busy": "2025-03-01T10:30:49.824765Z",
     "iopub.status.idle": "2025-03-01T10:30:49.830558Z",
     "shell.execute_reply": "2025-03-01T10:30:49.829866Z"
    },
    "id": "66346efdd520"
   },
   "outputs": [],
   "source": [
    "\"\"\"Define a custom single-qubit gate.\"\"\"\n",
    "class MyGate(cirq.Gate):\n",
    "    def __init__(self):\n",
    "        super(MyGate, self)\n",
    "        \n",
    "    def _num_qubits_(self):\n",
    "        return 1\n",
    "    \n",
    "    def _unitary_(self):\n",
    "        return np.array([\n",
    "            [1.0,  1.0],\n",
    "            [-1.0, 1.0]\n",
    "        ]) / np.sqrt(2)\n",
    "    \n",
    "    def _circuit_diagram_info_(self, args):\n",
    "        return \"G\"\n",
    "\n",
    "my_gate = MyGate()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "873c956ccf0e"
   },
   "source": [
    "In this example, the `_num_qubits_` method tells Cirq that this gate acts on a single-qubit, and the `_unitary_` method defines the unitary of the gate. The `_circuit_diagram_info_` method tells Cirq how to display the gate in a circuit, as we will see below.\n",
    "\n",
    "Once this gate is defined, it can be used like any standard gate in Cirq."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.833437Z",
     "iopub.status.busy": "2025-03-01T10:30:49.832925Z",
     "iopub.status.idle": "2025-03-01T10:30:49.838682Z",
     "shell.execute_reply": "2025-03-01T10:30:49.838014Z"
    },
    "id": "ec8550e51178"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit with custom gates:\n",
      "0: ───G───\n"
     ]
    }
   ],
   "source": [
    "\"\"\"Use the custom gate in a circuit.\"\"\"\n",
    "circ = cirq.Circuit(\n",
    "    my_gate.on(cirq.LineQubit(0))\n",
    ")\n",
    "\n",
    "print(\"Circuit with custom gates:\")\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "dc0e4ee48211"
   },
   "source": [
    "When we print the circuit, we see the symbol we specified in the `_circuit_diagram_info_` method.\n",
    "\n",
    "Circuits with custom gates can be simulated in the same manner as circuits with standard gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.841511Z",
     "iopub.status.busy": "2025-03-01T10:30:49.841010Z",
     "iopub.status.idle": "2025-03-01T10:30:49.846952Z",
     "shell.execute_reply": "2025-03-01T10:30:49.846263Z"
    },
    "id": "3885c629a1ef"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "measurements: (no measurements)\n",
      "\n",
      "qubits: (cirq.LineQubit(0),)\n",
      "output vector: 0.707|0⟩ - 0.707|1⟩\n",
      "\n",
      "phase:\n",
      "output vector: |⟩\n"
     ]
    }
   ],
   "source": [
    "\"\"\"Simulate a circuit with a custom gate.\"\"\"\n",
    "sim = cirq.Simulator()\n",
    "\n",
    "res = sim.simulate(circ)\n",
    "print(res)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.849662Z",
     "iopub.status.busy": "2025-03-01T10:30:49.849087Z",
     "iopub.status.idle": "2025-03-01T10:30:49.854351Z",
     "shell.execute_reply": "2025-03-01T10:30:49.853689Z"
    },
    "id": "71dd8d4666fc"
   },
   "outputs": [],
   "source": [
    "\"\"\"Define a custom two-qubit gate.\"\"\"\n",
    "class AnotherGate(cirq.Gate):\n",
    "    def __init__(self):\n",
    "        super(AnotherGate, self)\n",
    "\n",
    "    def _num_qubits_(self):\n",
    "        return 2\n",
    "    \n",
    "    def _unitary_(self):\n",
    "        return np.array([\n",
    "            [1.0, -1.0, 0.0,  0.0],\n",
    "            [0.0,  0.0, 1.0,  1.0],\n",
    "            [1.0,  1.0, 0.0,  0.0],\n",
    "            [0.0,  0.0, 1.0, -1.0]\n",
    "        ]) / np.sqrt(2)\n",
    "    \n",
    "    def _circuit_diagram_info_(self, args):\n",
    "        return \"Top wire symbol\", \"Bottom wire symbol\"\n",
    "\n",
    "this_gate = AnotherGate()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9c79b54f0ab4"
   },
   "source": [
    "Here, the `_circuit_diagram_info_` method returns two symbols (one for each wire) since it is a two-qubit gate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.857084Z",
     "iopub.status.busy": "2025-03-01T10:30:49.856652Z",
     "iopub.status.idle": "2025-03-01T10:30:49.861391Z",
     "shell.execute_reply": "2025-03-01T10:30:49.860709Z"
    },
    "id": "280e34a34bd6"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit with custom two-qubit gate:\n",
      "0: ───Top wire symbol──────\n",
      "      │\n",
      "1: ───Bottom wire symbol───\n"
     ]
    }
   ],
   "source": [
    "\"\"\"Use the custom two-qubit gate in a circuit.\"\"\"\n",
    "circ = cirq.Circuit(\n",
    "    this_gate.on(*cirq.LineQubit.range(2))\n",
    ")\n",
    "\n",
    "print(\"Circuit with custom two-qubit gate:\")\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "45a8342180aa"
   },
   "source": [
    "As above, this circuit can also be simulated in the expected way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "c896c2bb5f23"
   },
   "source": [
    "### With parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "ef59ca39c94c"
   },
   "source": [
    "Custom gates can be defined and used with parameters. For example, to define the gate\n",
    "\n",
    "$$ R(\\theta) = \\left[ \\begin{matrix} \\cos \\theta & \\sin \\theta \\\\ \\sin \\theta & - \\cos \\theta \\end{matrix} \\right], $$\n",
    "\n",
    "we can do the following."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.864308Z",
     "iopub.status.busy": "2025-03-01T10:30:49.863892Z",
     "iopub.status.idle": "2025-03-01T10:30:49.868943Z",
     "shell.execute_reply": "2025-03-01T10:30:49.868283Z"
    },
    "id": "262d28526fef"
   },
   "outputs": [],
   "source": [
    "\"\"\"Define a custom gate with a parameter.\"\"\"\n",
    "class RotationGate(cirq.Gate):\n",
    "    def __init__(self, theta):\n",
    "        super(RotationGate, self)\n",
    "        self.theta = theta\n",
    "        \n",
    "    def _num_qubits_(self):\n",
    "        return 1\n",
    "    \n",
    "    def _unitary_(self):\n",
    "        return np.array([\n",
    "            [np.cos(self.theta), np.sin(self.theta)],\n",
    "            [np.sin(self.theta), -np.cos(self.theta)]\n",
    "        ]) / np.sqrt(2)\n",
    "    \n",
    "    def _circuit_diagram_info_(self, args):\n",
    "        return f\"R({self.theta})\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "8a10fdb09fca"
   },
   "source": [
    "This gate can be used in a circuit as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.871773Z",
     "iopub.status.busy": "2025-03-01T10:30:49.871205Z",
     "iopub.status.idle": "2025-03-01T10:30:49.875861Z",
     "shell.execute_reply": "2025-03-01T10:30:49.875171Z"
    },
    "id": "485c560f0d25"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit with a custom rotation gate:\n",
      "0: ───R(0.1)───\n"
     ]
    }
   ],
   "source": [
    "\"\"\"Use the custom gate in a circuit.\"\"\"\n",
    "circ = cirq.Circuit(\n",
    "    RotationGate(theta=0.1).on(cirq.LineQubit(0))\n",
    ")\n",
    "\n",
    "print(\"Circuit with a custom rotation gate:\")\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "baf273b2fe60"
   },
   "source": [
    "## From a known decomposition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "708300eb2c33"
   },
   "source": [
    "Custom gates can also be defined from a known decomposition (of gates). This is useful, for example, when groups of gates appear repeatedly in a circuit, or when a standard decomposition of a gate into primitive gates is known.\n",
    "\n",
    "We show an example below of a custom swap gate defined from a known decomposition of three CNOT gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.878807Z",
     "iopub.status.busy": "2025-03-01T10:30:49.878256Z",
     "iopub.status.idle": "2025-03-01T10:30:49.883075Z",
     "shell.execute_reply": "2025-03-01T10:30:49.882426Z"
    },
    "id": "2c656362cd95"
   },
   "outputs": [],
   "source": [
    "class MySwap(cirq.Gate):\n",
    "    def __init__(self):\n",
    "        super(MySwap, self)\n",
    "\n",
    "    def _num_qubits_(self):\n",
    "        return 2\n",
    "\n",
    "    def _decompose_(self, qubits):\n",
    "        a, b = qubits\n",
    "        yield cirq.CNOT(a, b)\n",
    "        yield cirq.CNOT(b, a)\n",
    "        yield cirq.CNOT(a, b)\n",
    "    \n",
    "    def _circuit_diagram_info_(self, args):\n",
    "        return [\"CustomSWAP\"] * self.num_qubits()\n",
    "\n",
    "my_swap = MySwap()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "829c4602757a"
   },
   "source": [
    "The `_decompose_` method yields the operations which implement the custom gate. (One can also return a list of operations instead of a generator.)\n",
    "\n",
    "When we use this gate in a circuit, the individual gates in the decomposition do not appear in the circuit. Instead, the `_circuit_diagram_info_` appears in the circuit. As mentioned, this can be useful for interpreting circuits at a higher level than individual (primitive) gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.885806Z",
     "iopub.status.busy": "2025-03-01T10:30:49.885292Z",
     "iopub.status.idle": "2025-03-01T10:30:49.890896Z",
     "shell.execute_reply": "2025-03-01T10:30:49.890204Z"
    },
    "id": "psYGZcjUEF5V"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit:\n",
      "0: ───X───CustomSWAP───\n",
      "          │\n",
      "1: ───────CustomSWAP───\n"
     ]
    }
   ],
   "source": [
    "\"\"\"Use the custom gate in a circuit.\"\"\"\n",
    "qreg = cirq.LineQubit.range(2)\n",
    "circ = cirq.Circuit(\n",
    "    cirq.X(qreg[0]),\n",
    "    my_swap.on(*qreg)\n",
    ")\n",
    "\n",
    "print(\"Circuit:\")\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "856b1cdf0117"
   },
   "source": [
    "We can simulate this circuit and verify it indeed swaps the qubits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.893697Z",
     "iopub.status.busy": "2025-03-01T10:30:49.893128Z",
     "iopub.status.idle": "2025-03-01T10:30:49.902576Z",
     "shell.execute_reply": "2025-03-01T10:30:49.901930Z"
    },
    "id": "0cafcf4c4197"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "measurements: (no measurements)\n",
       "\n",
       "qubits: (cirq.LineQubit(0), cirq.LineQubit(1))\n",
       "output vector: |01⟩\n",
       "\n",
       "phase:\n",
       "output vector: |⟩"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "\"\"\"Simulate the circuit.\"\"\"\n",
    "sim.simulate(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "09f425a61484"
   },
   "source": [
    "## More on magic methods and protocols"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "d63f32eb1ac7"
   },
   "source": [
    "As mentioned, methods such as `_unitary_` which we have seen are known as \"magic\n",
    "methods.\" Much of Cirq relies on \"magic methods\", which are methods prefixed with one or\n",
    "two underscores and used by Cirq's protocols or built-in Python methods.\n",
    "For instance,  Python translates `cirq.Z**0.25` into\n",
    "`cirq.Z.__pow__(0.25)`.  Other uses are specific to cirq and are found in the\n",
    "protocols subdirectory.  They are defined below.\n",
    "\n",
    "At minimum, you will need to define either the ``_num_qubits_`` or\n",
    "``_qid_shape_`` magic method to define the number of qubits (or qudits) used\n",
    "in the gate."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "d05fa2e8d1ab"
   },
   "source": [
    "### Standard Python magic methods\n",
    "\n",
    "There are many standard magic methods in Python.  Here are a few of the most\n",
    "important ones used in Cirq:\n",
    "  * `__str__` for user-friendly string output and  `__repr__` is the Python-friendly string output, meaning that `eval(repr(y))==y` should always be true.\n",
    "  * `__eq__` and `__hash__` which define whether objects are equal or not.  You\n",
    "  can also use `cirq.value.value_equality` for objects that have a small list\n",
    "  of sub-values that can be compared for equality.\n",
    "  * Arithmetic functions such as `__pow__`, `__mul__`, `__add__` define the\n",
    "  action of `**`, `*`, and `+` respectively.\n",
    "   \n",
    "### `cirq.num_qubits` and `def _num_qubits_`\n",
    "\n",
    "A `Gate` must implement the `_num_qubits_` (or `_qid_shape_`) method.\n",
    "This method returns an integer and is used by `cirq.num_qubits` to determine\n",
    "how many qubits this gate operates on.\n",
    "\n",
    "### `cirq.qid_shape` and `def _qid_shape_`\n",
    "\n",
    "A qudit gate or operation must implement the `_qid_shape_` method that returns a\n",
    "tuple of integers.  This method is used to determine how many qudits the gate or\n",
    "operation operates on and what dimension each qudit must be.  If only the\n",
    "`_num_qubits_` method is implemented, the object is assumed to operate only on\n",
    "qubits. Callers can query the qid shape of the object by calling\n",
    "`cirq.qid_shape` on it. See [qudit documentation](qudits.ipynb) for more\n",
    "information.\n",
    "\n",
    "### `cirq.unitary` and `def _unitary_`\n",
    "\n",
    "When an object can be described by a unitary matrix, it can expose that unitary\n",
    "matrix by implementing a `_unitary_(self) -> np.ndarray` method.\n",
    "Callers can query whether or not an object has a unitary matrix by calling\n",
    "`cirq.unitary` on it.\n",
    "The `_unitary_` method may also return `NotImplemented`, in which case\n",
    "`cirq.unitary` behaves as if the method is not implemented.\n",
    "\n",
    "### `cirq.decompose` and `def _decompose_`\n",
    "\n",
    "Operations and gates can be defined in terms of other operations by implementing\n",
    "a `_decompose_` method that returns those other operations. Operations implement\n",
    "`_decompose_(self)` whereas gates implement `_decompose_(self, qubits)`\n",
    "(since gates don't know their qubits ahead of time).\n",
    "\n",
    "The main requirements on the output of `_decompose_` methods are:\n",
    "\n",
    "1. DO NOT CREATE CYCLES. The `cirq.decompose` method will iterative decompose until it finds values satisfying a `keep` predicate. Cycles cause it to enter an infinite loop.\n",
    "2. Head towards operations defined by Cirq, because these operations have good decomposition methods that terminate in single-qubit and two qubit gates.\n",
    "These gates can be understood by the simulator, optimizers, and other code.\n",
    "3. All that matters is functional equivalence.\n",
    "Don't worry about staying within or reaching a particular gate set; it's too hard to predict what the caller will want. Gate-set-aware decomposition is useful, but *this is not the protocol that does that*.\n",
    "Instead, use features available in the [transformer API](../transform/transformers.ipynb#compiling_to_nisq_targets_cirqcompilationtargetgateset).\n",
    "\n",
    "For example, `cirq.CCZ` decomposes into a series of `cirq.CNOT` and `cirq.T` operations.\n",
    "This allows code that doesn't understand three-qubit operation to work with `cirq.CCZ`; by decomposing it into operations they do understand.\n",
    "As another example, `cirq.TOFFOLI` decomposes into a `cirq.H` followed by a `cirq.CCZ` followed by a `cirq.H`.\n",
    "Although the output contains a three qubit operation (the CCZ), that operation can be decomposed into two qubit and one qubit operations.\n",
    "So code that doesn't understand three qubit operations can deal with Toffolis by decomposing them, and then decomposing the CCZs that result from the initial decomposition.\n",
    "\n",
    "In general, decomposition-aware code consuming operations is expected to recursively decompose unknown operations until the code either hits operations it understands or hits a dead end where no more decomposition is possible.\n",
    "The `cirq.decompose` method implements logic for performing exactly this kind of recursive decomposition.\n",
    "Callers specify a `keep` predicate, and optionally specify intercepting and fallback decomposers, and then `cirq.decompose` will repeatedly decompose whatever operations it was given until the operations satisfy the given `keep`.\n",
    "If `cirq.decompose` hits a dead end, it raises an error.\n",
    "\n",
    "Cirq doesn't make any guarantees about the \"target gate set\" decomposition is heading towards.\n",
    "`cirq.decompose` is not a method\n",
    "Decompositions within Cirq happen to converge towards X, Y, Z, CZ, PhasedX, specified-matrix gates, and others.\n",
    "But this set will vary from release to release, and so it is important for consumers of decompositions to look for generic properties of gates,\n",
    "such as \"two qubit gate with a unitary matrix\", instead of specific gate types such as CZ gates.\n",
    "\n",
    "### `cirq.inverse` and `__pow__`\n",
    "\n",
    "Gates and operations are considered to be *invertible* when they implement a `__pow__` method that returns a result besides `NotImplemented` for an exponent of -1.\n",
    "This inverse can be accessed either directly as `value**-1`, or via the utility method `cirq.inverse(value)`.\n",
    "If you are sure that `value` has an inverse, saying `value**-1` is more convenient than saying `cirq.inverse(value)`.\n",
    "`cirq.inverse` is for cases where you aren't sure if `value` is invertible, or where `value` might be a *sequence* of invertible operations.\n",
    "\n",
    "`cirq.inverse` has a `default` parameter used as a fallback when `value` isn't invertible.\n",
    "For example, `cirq.inverse(value, default=None)` returns the inverse of `value`, or else returns `None` if `value` isn't invertible.\n",
    "(If no `default` is specified and `value` isn't invertible, a `TypeError` is raised.)\n",
    "\n",
    "When you give `cirq.inverse` a list, or any other kind of iterable thing, it will return a sequence of operations that (if run in order) undoes the operations of the original sequence (if run in order).\n",
    "Basically, the items of the list are individually inverted and returned in reverse order.\n",
    "For example, the expression `cirq.inverse([cirq.S(b), cirq.CNOT(a, b)])` will return the tuple `(cirq.CNOT(a, b), cirq.S(b)**-1)`.\n",
    "\n",
    "Gates and operations can also return values beside `NotImplemented` from their `__pow__` method for exponents besides `-1`.\n",
    "This pattern is used often by Cirq.\n",
    "For example, the square root of X gate can be created by raising `cirq.X` to 0.5:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-03-01T10:30:49.905640Z",
     "iopub.status.busy": "2025-03-01T10:30:49.905111Z",
     "iopub.status.idle": "2025-03-01T10:30:49.909931Z",
     "shell.execute_reply": "2025-03-01T10:30:49.909287Z"
    },
    "id": "a37d151e71ed"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0.+0.j 1.+0.j]\n",
      " [1.+0.j 0.+0.j]]\n",
      "[[0.5+0.5j 0.5-0.5j]\n",
      " [0.5-0.5j 0.5+0.5j]]\n"
     ]
    }
   ],
   "source": [
    "print(cirq.unitary(cirq.X))\n",
    "# prints\n",
    "# [[0.+0.j 1.+0.j]\n",
    "#  [1.+0.j 0.+0.j]]\n",
    "\n",
    "sqrt_x = cirq.X**0.5\n",
    "print(cirq.unitary(sqrt_x))\n",
    "# prints\n",
    "# [[0.5+0.5j 0.5-0.5j]\n",
    "#  [0.5-0.5j 0.5+0.5j]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6fe65e2eb967"
   },
   "source": [
    "The Pauli gates included in Cirq use the convention ``Z**0.5 ≡ S ≡ np.diag(1, i)``, ``Z**-0.5 ≡ S**-1``, ``X**0.5 ≡ H·S·H``, and the square root of ``Y`` is inferred via the right hand rule.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9d8cecee52e8"
   },
   "source": [
    "### `_circuit_diagram_info_(self, args)` and `cirq.circuit_diagram_info(val, [args], [default])`\n",
    "\n",
    "Circuit diagrams are useful for visualizing the structure of a `Circuit`.\n",
    "Gates can specify compact representations to use in diagrams by implementing a `_circuit_diagram_info_` method.\n",
    "For example, this is why SWAP gates are shown as linked '×' characters in diagrams.\n",
    "\n",
    "The `_circuit_diagram_info_` method takes an `args` parameter of type `cirq.CircuitDiagramInfoArgs` and returns either\n",
    "a string (typically the gate's name), a sequence of strings (a label to use on each qubit targeted by the gate), or an\n",
    "instance of `cirq.CircuitDiagramInfo` (which can specify more advanced properties such as exponents and will expand\n",
    "in the future).\n",
    "\n",
    "You can query the circuit diagram info of a value by passing it into `cirq.circuit_diagram_info`."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [
    "Sh9QBnKbFf_B"
   ],
   "name": "custom_gates.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.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}