examples/workflow_basics/1.the_basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Linq: the basics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`linq` is a submodule of `tangelo` that helps you connect to and leverage the features of various backends, may they be simulators or QPUs. This notebook talks about the abstract format used in Tangelo to represent a quantum circuit, and how we can then convert it to other formats or objects used in popular packages such as Braket, Qulacs, Qiskit, Cirq (...) and leverage the different features and performance these platforms offer.\n",
    "\n",
    "Write code once, run it on various platforms with minimal effort: no need to rewrite everything in order to port your project to a different hardware, or generate what you need for a publication. It also means that whatever new method or code you develop can just run on all the compute backends available.\n",
    "\n",
    "## Table of contents\n",
    "* [1. Abstract gate class](#1)\n",
    "* [2. Abstract circuit class](#2)\n",
    "* [3. Translator module](#3)\n",
    "* [4. Backends](#4)\n",
    "* [5. Beyond that](#end)\n",
    "\n",
    "The scope of this submodule goes beyond this, but this notebook only focuses on the basics: the abstract gate and circuit classes, as well as the `translator` and `simulator` modules. This should get you started with simulating a variety of quantum circuits, as well as computing expectation values of operators.\n",
    "\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Requirements\n",
    "\n",
    "In order to run the contents of this notebook, you need to have `tangelo` installed in your python environment. Some cells may require that a specific backend (such as `qiskit`, `qulacs`...) is installed to run. Please have a look at their installation instructions, if needed. Executing the cell below provides a quick way of installing the requirements of this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Installation of tangelo if not already installed.\n",
    "try:\n",
    "    import tangelo\n",
    "except ModuleNotFoundError:\n",
    "    !pip install git+https://github.com/goodchemistryco/Tangelo.git@develop  --quiet\n",
    "    !pip install qiskit qiskit-aer qulacs amazon-braket-sdk Pennylane --quiet"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Abstract gate class <a class=\"anchor\" id=\"1\"></a>\n",
    "\n",
    "The `linq` submodule aims at providing users a straightforward and transparent way to represent a quantum gate operation, and by extension a quantum circuit. It represents a quantum gate operation acting on qubits as a simple python object. An abstract gate has:\n",
    "\n",
    "- A name\n",
    "- target qubit(s)  (only one qubit supported at the moment)\n",
    "- control qubit(s) (only one supported at the moment)\n",
    "- parameter(s)     (only one supported at the moment)\n",
    "- a tag saying whether or not it is \"variational\", to keep track of gates with variational parameters\n",
    "\n",
    "\n",
    "An abstract gate is pretty much just a dictionary, with the fields above. Some gates do not need all these fields to be populated in order to be clearly defined: not all of them require control qubits or parameters for instance. \n",
    "\n",
    "Let's have a look at how someone can define a gate and print it. You can see below that at instantiation, you can skip some fields or omit their name if the call is non-ambiguous. We always start with the name and the index of the target qubit, as all gates have them.\n",
    "\n",
    "**Note**: qubit indexing starts at 0.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H         target : [2]   \n",
      "CNOT      target : [1]   control : [0]   \n",
      "RX        target : [1]   parameter : 2.0\n",
      "RZ        target : [1]   parameter : an expression\t (variational)\n",
      "POTATO    target : [3]   \n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq import Gate\n",
    "\n",
    "# Create a Hadamard gate acting on qubit 2\n",
    "H_gate = Gate(\"H\", 2)\n",
    "# Create a CNOT gate with control qubit 0 and target qubit 1\n",
    "CNOT_gate = Gate(\"CNOT\", target=1, control=0)\n",
    "# Create a parameterized rotation on qubit 1 with angle 2 radians\n",
    "RX_gate = Gate(\"RX\", 1, parameter=2.)\n",
    "# Create a parameterized rotation on qubit 1 , with an undefined angle, that will be tagged as variational\n",
    "RZ_gate = Gate(\"RZ\", 1, parameter=\"an expression\", is_variational=True)\n",
    "# Create a potato gate, acting on qubit 3.\n",
    "POTATO_gate = Gate(\"POTATO\", 3)\n",
    "\n",
    "for gate in [H_gate, CNOT_gate, RX_gate, RZ_gate, POTATO_gate]:\n",
    "    print(gate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What's that, you don't know about the POTATO gate?! Oof. Your imposter syndrom must be in full swing right now. It's ok. No one has noticed yet. Smile. Take another sip of that coffee. Keep reading.\n",
    "\n",
    "This abstract gate data structure simply stores information, and does not need to fully specify a valid gate operation that corresponds to, let's say, a very well-defined matrix representation of the operator. As you can see, the parameter for our `Rz` gate can be anything, and the actual existence of the POTATO gate is questionable. The gate set supported, the conventions on phases and parameters, are all backend-dependent. Therefore, the fields of your abstract gate only really need to make sense later on, once you have picked a target backend (qiskit, qulacs...).\n",
    "\n",
    "**Note**: The controlled gates, such as CNOT, expect that you first pass the target qubits and then the control ones, which may be counter-intuitive and trip you up."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Abstract circuit class <a class=\"anchor\" id=\"2\"></a>\n",
    "\n",
    "An abstract circuit can be simply seen as a list of abstract gates. This class has a few methods to help users know at a glance how many gates or qubits are in a quantum circuit, or if it contains gates tagged as variational for example. Other convenience methods to compute the depth of the circuit, identify unentangled registers or qubits that can be simulated separately, etc, are available.\n",
    "\n",
    "Users can instantiate abstract circuits by directly passing a list of gates, or using the `add_gate` method on an existing abstract circuit object. It is also possible to concatenate abstract circuits in a pythonic way using the $+$ or $*$ operators: useful to build more complex circuits using simpler ones as building blocks. Circuits are iterable objects, which means that you can traverse them in order to traverse the underlying list of gates they're made of.\n",
    "\n",
    "**Note**: It is more efficient to build circuits by using list comprehension and other python syntaxes to efficiently build a list of `Gate` objects, and then passing it to the `Circuit` class; rather than use `add_gate` or concatenate a lot of small `Circuit` objects with `+`.\n",
    "\n",
    "The number of qubits required by your circuit is automatically computed, based on the highest qubit index appearing in your gates. It is however possible to enforce a fixed-sized for your quantum circuit, that goes beyond this number.\n",
    "\n",
    "We're all grown-ups, and technically you could perform surgery on your quantum circuit, to directly modify the fields of some of its gates. This can be useful for instance, to change the parameters used in \"variational gates\" (i.e gates tagged as variational) in the context of variational algorithms. Use responsibly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit object. Size 6 \n",
      "\n",
      "H         target : [2]   \n",
      "CNOT      target : [1]   control : [0]   \n",
      "CNOT      target : [2]   control : [1]   \n",
      "Y         target : [0]   \n",
      "RX        target : [1]   parameter : 2.0\n",
      "RZ        target : [4]   parameter : some angle\t (variational)\n",
      "\n",
      "The number of gates contained in circuit3 is 6\n",
      "The number of qubits in circuit3 is 5\n",
      "Does circuit have gates tagged as variational? True\n",
      "Gate counts: {'H': 1, 'CNOT': 2, 'Y': 1, 'RX': 1, 'RZ': 1}\n",
      "\n",
      "Circuit object. Size 6 \n",
      "\n",
      "H         target : [2]   \n",
      "CNOT      target : [1]   control : [0]   \n",
      "CNOT      target : [2]   control : [1]   \n",
      "Y         target : [0]   \n",
      "RX        target : [1]   parameter : 2.0\n",
      "RZ        target : [4]   parameter : 777.0\t (variational)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq import Circuit\n",
    "\n",
    "# Here's a list of abstract gates\n",
    "mygates = [Gate(\"H\", 2), Gate(\"CNOT\", 1, control=0), Gate(\"CNOT\", target=2, control=1),\n",
    "           Gate(\"Y\", 0), Gate(\"RX\", 1, parameter=2.)]\n",
    "\n",
    "# Users can create empty circuit objects and use add_gate later on\n",
    "circuit1 = Circuit()\n",
    "for gate in mygates:\n",
    "    circuit1.add_gate(gate)\n",
    "    \n",
    "# Users can also directly instantiate a circuit with a list of gates (preferred)\n",
    "circuit2 = Circuit(mygates)\n",
    "\n",
    "# It is possible to concatenate abstract circuit objects\n",
    "circuit3 = Circuit(mygates) + Circuit([Gate(\"RZ\", 4, parameter=\"some angle\", is_variational=True)])\n",
    "\n",
    "# Printing a circuit prints gate list\n",
    "print(circuit3)\n",
    "\n",
    "# It is possible to examine properties of an abstract circuit directly\n",
    "print(f\"The number of gates contained in circuit3 is {circuit3.size}\")\n",
    "print(f\"The number of qubits in circuit3 is {circuit3.width}\")\n",
    "print(f\"Does circuit have gates tagged as variational? {circuit3.is_variational}\")\n",
    "\n",
    "# Even to have an overview of the type of gates it contains, and how many of them\n",
    "print(f\"Gate counts: {circuit3.counts}\")\n",
    "\n",
    "# Dark magic: update the parameters of the first variational gate in the circuit\n",
    "circuit3._variational_gates[0].parameter = 777.\n",
    "print(f\"\\n{circuit3}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The abstract circuit can therefore be thought as a list of abstract gates, with some self-awareness: it knows what gate objects it contains, yet does not know what operation they actually implement on a quantum state. The latter is deferred to the translation step, which is different for each backend.\n",
    "\n",
    "In the future, we may provide other features to optimize or analyze abstract circuits. The advantage of doing so means that whatever benefit come out of it, it will carry to any of the target backends.\n",
    "\n",
    "**Note:** It is implied that qubits are measured in the computational basis at the end of the circuit. Users should NOT explicitly perform final measurements using the `MEASURE` instruction, which is designed to handle mid-circuit measurements, indicating that we intend to simulate a mixed state. As mixed states cannot be represented by statevectors, they are simulated differently and require to draw shots / samples, which may increase simulation time considerably."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Helper functions to build circuits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This package provides helper functions allowing users to put together more general circuits easily, without the need to reinvent the wheel when it comes to common patterns. In the future, users could contribute functions generating useful for benchmarking reasons, building blocks to form larger circuits, or well-known quantum circuits such as the QFT, for instance. These could be contributed as helper functions, or available in a separate folder aiming to gather a collection a circuits for different purposes. If you need to do something that seems fairly common, take a quick look around: you may have all the pieces already (or have the opportunity to design and contribute the pieces you need!).\n",
    "\n",
    "**Note:** Most functions do not yield a `Circuit` object, but a list of gates (see the convention used at the end of the function name). For performance reasons, it is better to concatenate a list of gates and then turn it into a Circuit, than to turn smaller lists of gates into `Circuit` objects and then use the `+` operator to concatenate them. This will not be an issue unless you are for example running an algorithm that requires a circuit to be rebuilt frequently and requiring many `Circuit` objects to be concatenated.\n",
    "\n",
    "Below, an example of how we can design a function to easily produce `Circuit` objects implementing a parameter sweep, working for any pauli measurement basis, which is not uncommon in hardware experiments: just a combination of loops and helper functions.\n",
    "\n",
    "The measurement basis is assumed to be passed as a list of 2-tuples of the form `(i, K)` where `i` is an integer denoting the qubit index and `K` a letter (string) that can take the value 'I', 'X', 'Y', or 'Z'; which also happens to be the format encountered while traversing a `QubitOperator` object in `Openfermion`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit object. Size 3 \n",
      "\n",
      "CNOT      target : [0]   control : [1]   \n",
      "RX        target : [1]   parameter : 0.1\n",
      "CNOT      target : [0]   control : [1]   \n",
      "\n",
      "\n",
      "Circuit object. Size 3 \n",
      "\n",
      "CNOT      target : [0]   control : [1]   \n",
      "RX        target : [1]   parameter : 0.2\n",
      "CNOT      target : [0]   control : [1]   \n",
      "\n",
      "\n",
      "Circuit object. Size 5 \n",
      "\n",
      "CNOT      target : [0]   control : [1]   \n",
      "RX        target : [1]   parameter : 0.3\n",
      "CNOT      target : [0]   control : [1]   \n",
      "RY        target : [0]   parameter : -1.5707963267948966\n",
      "RX        target : [1]   parameter : 1.5707963267948966\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq.helpers.circuits import measurement_basis_gates, pauli_string_to_of\n",
    "\n",
    "def theta_sweep(theta, m_basis):\n",
    "    \"\"\" A single-parameter circuit, with change of basis at the end if needed \"\"\"\n",
    "    my_gates = [Gate('CNOT', target=0, control=1), \n",
    "                Gate('RX', target=1, parameter=theta), \n",
    "                Gate('CNOT', target=0, control=1)]\n",
    "    my_gates += measurement_basis_gates(pauli_string_to_of(m_basis))\n",
    "    return Circuit(my_gates)\n",
    "\n",
    "# It is easy with linq to move between string or Openfermion-style representations for Pauli words\n",
    "for theta, m_basis in [(0.1, 'ZZ'), (0.2, 'ZZ'), (0.3, 'XY')]:\n",
    "    c = theta_sweep(theta, m_basis)\n",
    "    print(f\"{c}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Translator module <a class=\"anchor\" id=\"3\"></a>\n",
    "\n",
    "In order to make use of the various compute backends available, the `translator` module provides users with functions that can translate from, and sometimes to, the abstract circuit format. Users can therefore import or export their quantum circuits to work with their favorite framework, using the umbrella function `translate_circuit` with the desired `target` and `source` parameters.\n",
    "\n",
    "A `translate_operator` function is also available, for doing the equivalent with qubit / Pauli operators.\n",
    "\n",
    "The `translator` module defines how the content of your abstract gates should be parsed, what gates are supported, the convention used, and is subject to error-checking: the contents must make sense for the target backend, otherwise you will get errors. At that point, your gates must be supported and their parameters correct.\n",
    "\n",
    "You can find in the translator module the dictionaries telling you what backends are supported, and what gates they currently support. As you can see, the exceptional `POTATO` gate is not yet supported by any available backend. You'd most certainly get an error if you tried to translate an abstract circuit containing such a gate into a given backend's format, unless a major breakthrough in toaster-oven technology happens and we integrate this disruptive compute platform."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "projectq : ['CNOT', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'T', 'X', 'Y', 'Z']\n",
      "ionq : ['CNOT', 'CPHASE', 'CRX', 'CRY', 'CRZ', 'CX', 'CY', 'CZ', 'H', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'XX', 'Y', 'Z']\n",
      "qdk : ['CH', 'CNOT', 'CPHASE', 'CRX', 'CRY', 'CRZ', 'CS', 'CSWAP', 'CT', 'CX', 'CY', 'CZ', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'Y', 'Z']\n",
      "openqasm : ['CNOT', 'CPHASE', 'CRZ', 'CSWAP', 'CY', 'CZ', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'Y', 'Z']\n",
      "qulacs : ['CH', 'CNOT', 'CPHASE', 'CRX', 'CRY', 'CRZ', 'CSWAP', 'CX', 'CY', 'CZ', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'XX', 'Y', 'Z']\n",
      "qiskit : ['CH', 'CNOT', 'CPHASE', 'CRX', 'CRY', 'CRZ', 'CSWAP', 'CX', 'CY', 'CZ', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'XX', 'Y', 'Z']\n",
      "cirq : ['CH', 'CNOT', 'CPHASE', 'CRX', 'CRY', 'CRZ', 'CSWAP', 'CX', 'CY', 'CZ', 'H', 'MEASURE', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'XX', 'Y', 'Z']\n",
      "braket : ['CNOT', 'CPHASE', 'CRZ', 'CSWAP', 'CX', 'CY', 'CZ', 'H', 'PHASE', 'RX', 'RY', 'RZ', 'S', 'SWAP', 'T', 'X', 'XX', 'Y', 'Z']\n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq import get_supported_gates\n",
    "\n",
    "for backend, gates in get_supported_gates().items():\n",
    "    print(f'{backend} : {gates}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result of the translation step is specific to the given backend: some will return a quantum circuit object, some will return a string of instructions in their specific syntax & language, some a serialized JSON object...\n",
    "\n",
    "**Note**: Do not use the `MEASURE` Gate in your noiseless/shotless simulations, unless your circuit requires a mid-circuit measurement. This gate is intended for the simulation of **mixed states**. \n",
    "\n",
    "**Note**: Backends often have different conventions, operations may differ up to a phase or sign convention for parametrized gates for instance. Since the outcome of your simulation should not depend on the target backend, the translation step enforces a given convention, detailed in the documentation. In particular, this implies that the native circuit written for a given backend may not be equivalent to the same one written in abstract format, and then translated to this backend. Be mindful of that as you try to take some code written for a given backend, to port it to `tangelo`.\n",
    "\n",
    "Below, we show how `translate_circuit` returns backend-specific objects, all with their usual built-in functionalities. See how the print function behaves differently for each of them for instance, and remember that you can use their built-in methods to accomplish many things (ex: after translating your circuit into a `Qiskit.QuantumCircuit` object, you can use the `draw` method to export it in a nice format: https://qiskit.org/documentation/stubs/qiskit.circuit.QuantumCircuit.draw.html). \n",
    "\n",
    "Here are a few examples. Some cells may fail depending on what packages you have installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Allocate | Qureg[0]\n",
      "Allocate | Qureg[1]\n",
      "Allocate | Qureg[2]\n",
      "Allocate | Qureg[3]\n",
      "Allocate | Qureg[4]\n",
      "H | Qureg[2]\n",
      "CX | ( Qureg[0], Qureg[1] )\n",
      "CX | ( Qureg[1], Qureg[2] )\n",
      "Y | Qureg[0]\n",
      "Rx(2.0) | Qureg[1]\n",
      "Rz(777.0) | Qureg[4]\n",
      "\n",
      "\n",
      "{'qubits': 5, 'circuit': [{'gate': 'h', 'targets': [2]}, {'gate': 'x', 'targets': [1], 'controls': [0]}, {'gate': 'x', 'targets': [2], 'controls': [1]}, {'gate': 'y', 'targets': [0]}, {'gate': 'rx', 'targets': [1], 'rotation': 2.0}, {'gate': 'rz', 'targets': [4], 'rotation': 777.0}]}\n",
      "\n",
      "namespace MyNamespace\n",
      "{\n",
      "    open Microsoft.Quantum.Intrinsic;\n",
      "    open Microsoft.Quantum.Canon;\n",
      "    open Microsoft.Quantum.Arrays;\n",
      "    open Microsoft.Quantum.Extensions.Convert;\n",
      "    open Microsoft.Quantum.Characterization;\n",
      "    open Microsoft.Quantum.Measurement;\n",
      "\n",
      "\n",
      "    /// # Summary:\n",
      "    ///         Returns the estimated probabilities associated to the different measurements\n",
      "    ///         after applying the state-preparation provided by the user at runtime to the quantum state\n",
      "    operation EstimateFrequencies(nQubits : Int, nShots : Int) : Double[]\n",
      "    {\n",
      "        mutable frequencies = new Double[2^nQubits];\n",
      "\n",
      "        for (iShot in 1..nShots)\n",
      "        {\n",
      "            // Apply Q# operation (state preparation to measurements) to qubit register of size nQubits\n",
      "            mutable results = MyQsharpOperation();\n",
      "\n",
      "            // Update frequencies based on sample value\n",
      "            mutable index = 0;\n",
      "            for (iQubit in nQubits-1..-1..0)\n",
      "            {\n",
      "                if (results[iQubit] == One) {set index = index + 2^iQubit;}\n",
      "            }\n",
      "\n",
      "            set frequencies w/= index <- frequencies[index] + 1.0;\n",
      "        }\n",
      "\n",
      "        // Rescale to obtain frequencies observed\n",
      "        for (iFreq in 0..2^nQubits-1)\n",
      "        {\n",
      "            set frequencies w/= iFreq <- frequencies[iFreq] / ToDouble(nShots);\n",
      "        }\n",
      "\n",
      "        return frequencies;\n",
      "    }\n",
      "\n",
      "    /// INSERT TRANSLATED CIRCUIT HERE\n",
      "@EntryPoint()\n",
      "operation MyQsharpOperation() : Result[] {\n",
      "\tmutable c = new Result[5];\n",
      "\tusing (qreg = Qubit[5]) {\n",
      "\t\tH(qreg[2]);\n",
      "\t\tCNOT(qreg[0], qreg[1]);\n",
      "\t\tCNOT(qreg[1], qreg[2]);\n",
      "\t\tY(qreg[0]);\n",
      "\t\tRx(2.0, qreg[1]);\n",
      "\t\tRz(777.0, qreg[4]);\n",
      "\n",
      "\t\treturn ForEach(MResetZ, qreg);\n",
      "\t}\n",
      "}\n",
      "\n",
      "}\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq import translate_circuit\n",
    "\n",
    "# Using the Tangelo format as an intermediate, many combinations of source and target\n",
    "# formats are available. \n",
    "circ3_projectq = translate_circuit(circuit3, target=\"projectq\", source=\"tangelo\")\n",
    "print(f\"{circ3_projectq}\\n\")\n",
    "\n",
    "# We now use the shorthand for translating a circuit \n",
    "# implicitly from tangelo format, to something else.\n",
    "circ3_projectq = translate_circuit(circuit3, \"ionq\")\n",
    "print(f\"{circ3_projectq}\\n\")\n",
    "\n",
    "circ3_projectq = translate_circuit(circuit3, \"qdk\")\n",
    "print(f\"{circ3_projectq}\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "                ┌───┐         \n",
      "q_0: ─────■─────┤ Y ├─────────\n",
      "        ┌─┴─┐   └───┘┌───────┐\n",
      "q_1: ───┤ X ├─────■──┤ Rx(2) ├\n",
      "        ├───┤   ┌─┴─┐└───────┘\n",
      "q_2: ───┤ H ├───┤ X ├─────────\n",
      "        └───┘   └───┘         \n",
      "q_3: ─────────────────────────\n",
      "     ┌─────────┐              \n",
      "q_4: ┤ Rz(777) ├──────────────\n",
      "     └─────────┘              \n",
      "c_0: ═════════════════════════\n",
      "                              \n",
      "c_1: ═════════════════════════\n",
      "                              \n",
      "c_2: ═════════════════════════\n",
      "                              \n",
      "c_3: ═════════════════════════\n",
      "                              \n",
      "c_4: ═════════════════════════\n",
      "                              \n",
      "\n",
      "OPENQASM 2.0;\n",
      "include \"qelib1.inc\";\n",
      "qreg q[5];\n",
      "creg c[5];\n",
      "h q[2];\n",
      "cx q[0],q[1];\n",
      "cx q[1],q[2];\n",
      "y q[0];\n",
      "rx(2) q[1];\n",
      "rz(777) q[4];\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "circ3_qiskit = translate_circuit(circuit3, \"qiskit\")\n",
    "print(f\"{circ3_qiskit}\\n\")\n",
    "\n",
    "circ3_openqasm = translate_circuit(circuit3, \"openqasm\")\n",
    "print(f\"{circ3_openqasm}\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "*** Quantum Circuit Info ***\n",
      "# of qubit: 5\n",
      "# of step : 3\n",
      "# of gate : 6\n",
      "# of 1 qubit gate: 4\n",
      "# of 2 qubit gate: 2\n",
      "Clifford  : no\n",
      "Gaussian  : no\n",
      "\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "circ3_qulacs = translate_circuit(circuit3, \"qulacs\")\n",
    "print(f\"{circ3_qulacs}\\n\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |    0     |1|   2    |\n",
      "                            \n",
      "q0 : -C----------Y----------\n",
      "      |                     \n",
      "q1 : -X----------C-Rx(2.00)-\n",
      "                 |          \n",
      "q2 : -H----------X----------\n",
      "                            \n",
      "q4 : -Rz(777.00)------------\n",
      "\n",
      "T  : |    0     |1|   2    |\n"
     ]
    }
   ],
   "source": [
    "circ3_braket = translate_circuit(circuit3, \"braket\")\n",
    "print(f\"{circ3_braket}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0: ───I───@─────────────Y────────────────\n",
      "          │\n",
      "1: ───I───X─────────────@───Rx(0.637π)───\n",
      "                        │\n",
      "2: ───I───H─────────────X────────────────\n",
      "\n",
      "3: ───I──────────────────────────────────\n",
      "\n",
      "4: ───I───Rz(-0.673π)────────────────────\n"
     ]
    }
   ],
   "source": [
    "circ3_cirq = translate_circuit(circuit3, \"cirq\")\n",
    "print(f\"{circ3_cirq}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: We provide limited support for translation from a backend-specific format to the abstract format, for convenience. Some of these formats are OpenQASM or projectq.\n",
    "\n",
    "### Saving, loading and sharing quantum circuits\n",
    "\n",
    "You may need to save, load or share quantum circuits or operators with collaborators, which may be used to working on other platforms.\n",
    "\n",
    "A first suggestion is to use the OpenQASM format, as it is a rather common human-readable format, supported by most framework. Tangelo proposes convertion to OPENQASM 2.0, and limited reverse convertion from a subset of OpenQASM to Tangelo format. \n",
    "\n",
    "Otherwise, python packages such as `pickle` or `json` may come in handy to export compatible non-string objects, but can be a bit tricky if version numbers of dependencies do not match."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.  Backends <a class=\"anchor\" id=\"4\"></a>\n",
    "\n",
    "The `get_backend` function provides a common interface to all supported compute backends, allowing users to focus on the high-level details of their simulation (number of shots, noise model...) without writing low-level code for the target backend. It returns an object inheriting from the abstract `Backend` class, which can refer to a simulator or an actual QPU. There are built-in backends for various simulators (qiskit, qulacs, cirq...) and it's possible to define your own backend.\n",
    "\n",
    "The backend object handles all translation and quantum circuit simulation steps, directly returning the results to the user. Some post-processing methods, such as the computation of the expectation value of a qubit operator, are available as well.\n",
    "\n",
    "Not all backends provide the same features: some of them do not give access to a state-vector representation of the quantum state, or do not support noisy simulation for instance. Just like the `translator` module, the `simulator` module provides a data-structure containing the currently supported features and characteristics of some backends."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "qdk : {'statevector_available': False, 'statevector_order': None, 'noisy_simulation': False}\n",
      "qiskit : {'statevector_available': True, 'statevector_order': 'msq_first', 'noisy_simulation': True}\n",
      "qulacs : {'statevector_available': True, 'statevector_order': 'msq_first', 'noisy_simulation': True}\n",
      "cirq : {'statevector_available': True, 'statevector_order': 'lsq_first', 'noisy_simulation': True}\n"
     ]
    }
   ],
   "source": [
    "from tangelo.linq import get_backend, backend_info\n",
    "\n",
    "for backend, info in backend_info.items():\n",
    "    print(f'{backend} : {info}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Noiseless simulation\n",
    "\n",
    "In the example below, we show how `get_backend` allows for switching backends easily, to perform quantum circuit simulation. We first show how to perform noiseless simulation with access to the exact amplitudes through the state-vector representation of the quantum state, and then show how a noiseless shot-based simulation can be performed.\n",
    "\n",
    "The `simulate` method returns a 2-tuple:\n",
    "\n",
    "- the first entry is a sparse histogram of frequencies associated to the different observed states, in least-significant qubit first order (e.g '01' means qubit 0 (resp 1) measured in $|0>$ (resp $|1>$) state). That is, it is to be read \"left-to-right\" in order to map each qubit to the basis state it was observed in.\n",
    "- the second entry contains the state-vector representation of the quantum state, if available on the target backend and if the user requires it using the `return_statevector` optional parameter. Watch out for the order of the amplitudes in the state vector: the `backend_info` data-structure described above helps with understanding how they map to the different basis states.\n",
    "\n",
    "The `simulate` method can also take the optional parameter `initial_statevector`, which allows to start the system in a given state and \"resume\" a simulation. It can in particular be useful to avoid resimulating something again and again, when the result is already known and could just be loaded instead. This is one of the perks of statevector simulators !"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "({'00': 0.2248275934887112, '10': 0.5453235594453588, '01': 0.06709898823771769, '11': 0.16274985882821247}, None)\n",
      "({'00': 0.2248275934887112, '01': 0.06709898823771769, '10': 0.5453235594453588, '11': 0.16274985882821247}, None)\n",
      "\n",
      "({'00': 0.2248275934887112, '10': 0.5453235594453588, '01': 0.06709898823771769, '11': 0.16274985882821247}, array([ 0.47415988+0.j        ,  0.        -0.73846026j,\n",
      "       -0.25903472+0.j        ,  0.        +0.40342268j]))\n"
     ]
    }
   ],
   "source": [
    "# Create a circuit object in abstract format\n",
    "c = Circuit([Gate(\"RX\", 0, parameter=2.), Gate(\"RY\", 1, parameter=-1.)])\n",
    "\n",
    "# Qiskit noiseless simulator (no shot count or noise model specified)\n",
    "sim_qiskit = get_backend(target=\"qiskit\")\n",
    "print(sim_qiskit.simulate(c))\n",
    "\n",
    "# cirq noiseless simulator (no shot count or noise model specified)\n",
    "sim_cirq = get_backend(target=\"cirq\")\n",
    "print(sim_cirq.simulate(c))\n",
    "\n",
    "# Qulacs noiseless simulator (no shot count or noise model specified)\n",
    "# Ask to return the state vector as well (exposes the complex amplitudes)\n",
    "sim_qulacs = get_backend(target=\"qulacs\")\n",
    "print(f\"\\n{sim_qulacs.simulate(c, return_statevector=True)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: If you do not specify any target when calling `get_backend`, the implementation defaults to either a qulacs simulator if the package found in your environment, or a cirq simulator otherwise."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: The native equivalents of this abstract circuit in Qulacs and Qiskit would not return the same results. This is due to the fact that $Rx_{qiskit}(\\theta) = Rx_{qulacs}(-\\theta)$ (e.g sign convention), which is also true for the $Ry$ and $Rz$ gates. This package however ensures consistent behavior across backends, by enforcing a specifying convention in the translator. For more information about conventions used, please refer to the documentation or check out the source code of the `translator` module.\n",
    "\n",
    "In the above cell, we called `get_backend` without specifying a number of shots or a noise model, but it is possible to do so. You can tweak the behavior of the `Backend` object by modifying -some- of its attributes after it has been instantied. In particular:\n",
    "\n",
    "- `freq_threshold` is the threshold used to discard negligible frequencies from the histogram returned by the `simulate` method, in order to avoid returning $2^{n\\_qubits}$ numbers and focus on the main observables.\n",
    "- `n_shots` and `noise_model` can be changed after the class has been instantiated\n",
    "\n",
    "In the cell below, we can see how instantiating a shot-based backend and increasing shot count yields results that are getting closer to the exact theoretical distribution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'00': 0.2248275934887112, '01': 0.06709898823771769, '10': 0.5453235594453588, '11': 0.16274985882821247}\n",
      "{'10': 0.58, '00': 0.2, '01': 0.05, '11': 0.17}\n",
      "{'00': 0.2275, '11': 0.1665, '10': 0.5419, '01': 0.0641}\n",
      "{'10': 0.545223, '00': 0.224795, '11': 0.163024, '01': 0.066958}\n"
     ]
    }
   ],
   "source": [
    "# Exact probabilities\n",
    "sim_qulacs = get_backend(target=\"cirq\")\n",
    "exact_freqs, _ = sim_qulacs.simulate(c)\n",
    "print(exact_freqs)\n",
    "\n",
    "# Approximation with different number of shots (higher=more accurate)\n",
    "sim_qulacs_shots = get_backend(target=\"cirq\", n_shots=100)\n",
    "freqs, _ = sim_qulacs_shots.simulate(c)\n",
    "print(freqs)\n",
    "\n",
    "sim_qulacs_shots.n_shots=10**4\n",
    "freqs, _ = sim_qulacs_shots.simulate(c)\n",
    "print(freqs)\n",
    "\n",
    "sim_qulacs_shots.n_shots=10**6\n",
    "freqs, _ = sim_qulacs_shots.simulate(c)\n",
    "print(freqs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mixed states\n",
    "\n",
    "The abstract circuit format provides a `MEASURE` instruction, supported by most compute backends, with the intent of simulating mixed states / mid-circuit measurements in the computational basis (e.g along the Z axis). As mixed states cannot be represented by a statevector, the statevector simulator backends default to simulating the quantum circuit with shots, in order to return a histogram of frequencies. Users thus must ensure the `n_shots` attribute of their `Backend` object has been set.\n",
    "\n",
    "Simulating a mixed state can be considerably slower than simulating a pure state (some backends are particularly **not** good at this). Including final measurements in your state-preparation circuit is not recommended, if you intend to use `linq` to simulate it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'01': 0.50089, '10': 0.49911}\n"
     ]
    }
   ],
   "source": [
    "# This circuit prepares a Bell pair (superposition of states |00> and |11>), then measures and flips qubit 0.\n",
    "# Depending on the result of the measurement, the statevector describing the quantum state would be different.\n",
    "circuit_mixed = Circuit([Gate(\"H\", 0), Gate(\"CNOT\", target=1, control=0), Gate(\"MEASURE\", 0), Gate(\"X\", 0)])\n",
    "sim = get_backend(target=\"cirq\", n_shots=10**5)\n",
    "\n",
    "freqs, _ = sim.simulate(circuit_mixed)\n",
    "print(freqs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We provide compute backends that are more appropriate to simulate mixed states, relying on density matrices for example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Expectation values\n",
    "\n",
    "The `get_expectation_value`method can be used to compute the expectation value of a qubit / Pauli operator with regards to a state-preparation circuit, and `get_expectation_value_from_frequencies_oneterm` can directly take a sparse histogram of frequencies obtained by executing or simulating a quantum circuit on a backend (which could be resulting from a QPU experiment).\n",
    "\n",
    "**Note**: For now, users are to manually loop over terms and corresponding histograms if they intend to compute the expectation value of a linear combination of operators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-0.4161468365471424\n",
      "-0.4161468365471424\n"
     ]
    }
   ],
   "source": [
    "# Openfermion operators can be used\n",
    "from openfermion.ops import QubitOperator\n",
    "op = 1.0 * QubitOperator('Z0')\n",
    "\n",
    "# Option1: Directly through a simulator backend, providing the state-preparation circuit\n",
    "sim = get_backend(target=\"cirq\")\n",
    "expval1 = sim.get_expectation_value(op, c)\n",
    "print(expval1)\n",
    "\n",
    "# Option2: Assume quantum circuit simulation was performed separately (by this package or different services)\n",
    "freqs, _ = sim.simulate(c)  # circuit c must be consistent with operator, regarding measurement along non-z axes\n",
    "term, coef = tuple(op.terms.items())[0]  # This yields ((0, 'Z'),), 1.0\n",
    "expval2 = coef * sim.get_expectation_value_from_frequencies_oneterm(term, freqs)\n",
    "print(expval2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Beyond that <a class=\"anchor\" id=\"end\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook provided a general introduction to the `linq` submodule, which hopefully helped you getting started with quantum circuits in Tangelo. There are many other notebooks available that illustrate quantum algorithms using these data structures, or more advanced features of `linq`.\n",
    "\n",
    "What will you do with Tangelo ?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "hands_on",
   "language": "python",
   "name": "hands_on"
  },
  "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}