notebooks/3. CX Circuits.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# CX Circuits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Changing working directory from `./notebooks/` to `./`, in order to import the Python packages defined in the repository."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "source": [
    "import os\n",
    "DEBUG = True\n",
    "try:\n",
    "    print(\"Original working directory: %s\"%str(original_wd)) # type: ignore\n",
    "    \"\"\"\n",
    "        You only get here if you---by mistake or otherwise---are re-running this cell, \n",
    "        in which case the working should not be changed again.\n",
    "    \"\"\"\n",
    "except NameError:\n",
    "    original_wd = os.getcwd()\n",
    "    os.chdir('../')\n",
    "print(\"Current working directory: %s\"%str(os.getcwd()))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "General purpose imports:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from IPython.display import set_matplotlib_formats\n",
    "%matplotlib inline\n",
    "set_matplotlib_formats('svg')\n",
    "# import qiskit"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Some utility code to display HTML elements and images/figures side-by-side:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "source": [
    "from io import BytesIO\n",
    "from typing import Union\n",
    "from IPython.display import Image, HTML # type: ignore\n",
    "def figure_to_image(fig: plt.Figure, fmt: str = \"png\") -> Image:\n",
    "    \"\"\" Converts a Matplotlib figure to a PNG IPython Image. \"\"\"\n",
    "    buffer = BytesIO()\n",
    "    fig.savefig(buffer, format=fmt)\n",
    "    buffer.seek(0)\n",
    "    image_png = buffer.getvalue()\n",
    "    buffer.close()\n",
    "    return Image(image_png, format=fmt, embed=True)\n",
    "def side_by_side(*elements: Union[str, Image]) -> HTML:\n",
    "    \"\"\"\n",
    "        Returns an HTML Div element with the given elements\n",
    "        displayed side by side. Accepts raw HTML code or\n",
    "        IPython Image objects.\n",
    "    \"\"\"\n",
    "    html = f\"<div style='display:flex; align-items: center;'>\"\n",
    "    for el in elements:\n",
    "        if isinstance(el, str):\n",
    "            html += el\n",
    "        elif isinstance(el, Image):\n",
    "            html += f\"<img src='data:image/png;base64,{el._repr_png_()}'/>\"\n",
    "    html += f\"</div>\"\n",
    "    return HTML(html)"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Conjugation by CX Circuits\n",
    "\n",
    "One of the optimisation techniques for a circuit $\\mathcal{C}$ of mixed ZX phase gadgets proceeds through conjugation of the circuit by a suitably chosen block $U$ of CX gates, obtaining another circuit $U \\circ \\mathcal{C}' \\circ U^\\dagger$ (hopefully simpler overall).\n",
    "\n",
    "These CX circuits are constructed and manipulated using the classes `CXCircuit` and `CXCircuitLayer`. Read-only views of such circuits are made available by the respective `as_readonly` properties, through the `CXCircuitView` and `CXCircuitLayerView` classes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "source": [
    "from pauliopt.phase import CXCircuit, CXCircuitLayer"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## CX Circuit Layers\n",
    "\n",
    "A single layer of a CX circuit is constructed with `CXCircuitLayer` from a topology and a collection of CX gates, specified as pairs `(ctrl, trgt)` of control and target qubits (in `CXCircuitLayer.topology.qubits`).\n",
    "It uses a `Matching` instance internally to keep track of which qubit pairs are covered by some gate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "source": [
    "from pauliopt.topologies import Topology\n",
    "topology = Topology.grid(3,3)\n",
    "layer = CXCircuitLayer(topology, [[0, 1], [2, 5], [6, 7]])"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "CX circuit layers exposes the underlying topology, number of gates and gates through suitably named read-only properties. Note that the `CXCircuitLayer.gates` property involves the creation of a fresh frozen-set at every call, since gates are stored internally in a different data structure.   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "source": [
    "print(f\"{layer.topology = }\")\n",
    "print(f\"{layer.num_gates = }\")\n",
    "print(f\"{layer.gates = }\")"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "CX circuit layers expose information about the gate incident to any given qubit (if any), through the `CXCircuitLayer.incident(qubit)` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "source": [
    "for q in layer.topology.qubits:\n",
    "    print(f\"Gate on qubit {q}: {layer.incident(q)}\")"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "CX circuit layers can be drawn using the `CXCircuitLayer.draw(**kwargs)` method. The allowed keyword arguments are those of `Topology.draw(**kwargs)`, plus `zcolor` and `xcolor` to control the colours for the Z and X dots in CX gates (analogous to `PhaseCircuit.to_svg(**kwargs)`).  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "source": [
    "layer.draw(figsize=(4,4))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## CX Gate Flipping\n",
    "\n",
    "CX circuit layers are modified by \"flipping\" CX gates, which can mean either:\n",
    "\n",
    "- removing a CX gate currently in the layer;\n",
    "- adding a CX gate to the layer on a pair of qubits, as long as neither qubit has an incident CX gate already.\n",
    "\n",
    "This guarantees that all CX gates in a layer can be performed simultaneously on the given qubit topology."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The list of CX gates that can be flipped in a layer is exposed by the `CXCircuitLayer.flippable_cxs` property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "source": [
    "print(f\"Flippable CX gates: {layer.flippable_cxs}\")\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The `CXCircuitLayer.is_cx_flippable(ctrl, trgt)` boolean property can be used to check whether the CX gate with given control and target is flippable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "source": [
    "print(f\"{layer.is_cx_flippable(4, 3) = }\") # no incident gates on qubits\n",
    "print(f\"{layer.is_cx_flippable(2, 5) = }\") # gate in circuit\n",
    "print(f\"{layer.is_cx_flippable(1, 0) = }\") # incident gate on both qubits\n",
    "print(f\"{layer.is_cx_flippable(7, 4) = }\") # incident gate on one qubit\n",
    "print(f\"{layer.is_cx_flippable(1, 2) = }\") # incident gates on both qubits\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "A CX gate with given control and target can be flipped using the `CXCircuitLayer.flip_cx(ctrl, trgt)` method (not available on the read-only view `CXCircuitLayerView`). The following example shows a CX gate being introduced on a pair of qubits `{3, 4}` neither of which already has a CX gate incident on it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "source": [
    "print(\"Before flipping (4,3):\")\n",
    "layer.draw(figsize=(3,3))\n",
    "layer.flip_cx(4,3)\n",
    "print(\"After flipping (4,3):\")\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The following example shows a CX gate being removed from a circuit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "source": [
    "print(\"Before flipping (6,7):\")\n",
    "layer.draw(figsize=(3,3))\n",
    "layer.flip_cx(6,7)\n",
    "print(\"After flipping (6,7):\")\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The in-place right-shift operator `>>=` can also be used to flip CX gates in a layer, resulting in a more compact syntax."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "source": [
    "layer = CXCircuitLayer(topology, [[0, 1], [2, 5], [6, 7]])\n",
    "layer >>= [4, 3], [6,7]\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "In fact, CX circuit layers can be created entirely with the in-place right-shift operator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "source": [
    "layer = CXCircuitLayer(topology)\n",
    "layer >>= [0, 1], [2, 5], [6, 7], [4, 3], [6,7]\n",
    "layer.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## CX Circuits\n",
    "\n",
    "CX Circuits are constructed with `CXCircuit` from a topology and a sequence of CX circuit layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "source": [
    "circuit = CXCircuit(topology, [\n",
    "    CXCircuitLayer(topology, [[0, 1], [2, 5], [6, 7]]),\n",
    "    CXCircuitLayer(topology, [[1, 2], [5, 4], [8, 7], [3, 6]]),\n",
    "    CXCircuitLayer(topology, [[0, 1], [4, 3], [7, 6]]),\n",
    "])"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "CX circuits are a sequence of CX circuit layers: they can be iterated, individual layers can be accessed and the number of layers can be obtained with `len()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "source": [
    "print(f\"Number of layers in circuit: {len(circuit)}\")\n",
    "for layer_idx, layer in enumerate(circuit):\n",
    "    print(f\"Gates in layer {layer_idx}: {layer.gates}\")\n",
    "print()\n",
    "print(\"Layer 0:\")\n",
    "circuit[0].draw(figsize=(3, 3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Drawing CX Circuits\n",
    "\n",
    "The `CXCircuit.draw` draws a CX circuit by drawing its individual layers left-to-right. The optional `figsize` parameter refers to the size of the individual layer sub-figures."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "source": [
    "circuit.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The in-place right-shift operator `>>=` can also be used to append layers to a CX circuit, resulting in a more compact syntax."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "source": [
    "circuit = CXCircuit(topology)\n",
    "circuit >>= CXCircuitLayer(topology, [[0, 1], [2, 5], [6, 7]])\n",
    "circuit >>= CXCircuitLayer(topology, [[1, 2], [5, 4], [8, 7], [3, 6]])\n",
    "circuit.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "In fact, the sequences of gates in each layer can be passed directly to the operator, further improving legibility."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "source": [
    "circuit = CXCircuit(topology)\n",
    "circuit >>= [[0, 1], [2, 5], [6, 7]]\n",
    "circuit >>= [[1, 2], [5, 4], [8, 7], [3, 6]]\n",
    "circuit.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Passing multiple layers to the operator on a line is allowed, but discouraged. If you do, make sure you understand that each layer should be passed as a list of gates (otherwise the gates will all be merged into a single layer, usually raising an error because some flips are invalid)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "source": [
    "circuit = CXCircuit(topology)\n",
    "circuit >>= [[0, 1], [2, 5], [6, 7]], [[1, 2], [5, 4], [8, 7], [3, 6]]\n",
    "circuit.draw(figsize=(3,3))"
   ],
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Example of an error when passing multiple layers all in one go:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "source": [
    "circuit = CXCircuit(topology)\n",
    "try:\n",
    "    circuit >>= [0, 1], [2, 5], [6, 7], [1, 2], [5, 4], [8, 7], [3, 6]\n",
    "except Exception as e:\n",
    "    print(\"Error:\", e)"
   ],
   "outputs": []
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}