docs/source/migration2-qc.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# New in Forest 2 - QuantumComputer\n",
    "\n",
    "PyQuil is for constructing and running quantum programs on real quantum computers. With the release of pyQuil 2, we have changed parts of the API to better reflect that focus. Instead of swapping between a `QVMConnection` and a `QPUConnection`, you will primarily deal with a `QuantumComputer` with consistent API and behavior regardless of\n",
    "\n",
    " - QVM / QPU\n",
    " - Presence of noise model\n",
    " - Device topology\n",
    " \n",
    "## Running a program\n",
    "Let's show how you can run a simple program on a `QuantumComputer` first we start with the relevant imports."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyquil import Program\n",
    "from pyquil.gates import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll write a function that takes a list of qubits and returns a pyQuil `Program` that constructs an entangled \"GHZ\" state. This is a generalization of the two-qubit Bell state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "def ghz_state(qubits):\n",
    "    \"\"\"Create a GHZ state on the given list of qubits by applying\n",
    "    a Hadamard gate to the first qubit followed by a chain of CNOTs\n",
    "    \"\"\"\n",
    "    program = Program()\n",
    "    program += H(qubits[0])\n",
    "    for q1, q2 in zip(qubits, qubits[1:]):\n",
    "        program += CNOT(q1, q2)\n",
    "    return program"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, creating a GHZ state on qubits 1, 2, and 3 would look like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "H 0\n",
      "CNOT 0 1\n",
      "CNOT 1 2\n",
      "\n"
     ]
    }
   ],
   "source": [
    "program = ghz_state(qubits=[0, 1, 2])\n",
    "print(program)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Debugging with `WavefunctionSimulator`\n",
    "We can check that this program gives us the desired wavefunction by using [WavefunctionSimulator.wavefunction()](apidocs/autogen/pyquil.api.WavefunctionSimulator.wavefunction.html#pyquil.api.WavefunctionSimulator.wavefunction)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0.7071067812+0j)|000> + (0.7071067812+0j)|111>\n"
     ]
    }
   ],
   "source": [
    "from pyquil.api import WavefunctionSimulator\n",
    "wfn = WavefunctionSimulator().wavefunction(program)\n",
    "print(wfn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can't get the wavefunction from a real quantum computer though, so instead we'll sample bitstrings. We expect to always measure the bitstring 000 or the bitstring 111 based on the definition of a GHZ state and confirmed by our wavefunction simulation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `get_qc`\n",
    "\n",
    "We'll construct a `QuantumComputer` via the helper method [get_qc](apidocs/quantum_computer.html#pyquil.get_qc). You may be tempted to use the `QuantumComputer` constructor directly. Please refer to the [advanced documentation](#%E2%80%9CWhat-is-a-QuantumComputer?%E2%80%9D-Advanced-Edition) to see how to do that. Our program uses 3 qubits, so we'll ask for a 3-qubit QVM."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "QuantumComputer[name=\"3q-qvm\"]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from pyquil import get_qc\n",
    "qc = get_qc('3q-qvm')\n",
    "qc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can do a quick check to make sure it has 3 qubits"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 2]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qc.qubits()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sampling with `run_and_measure`\n",
    "\n",
    "`QuantumComputer.run_and_measure` will run a given program (that does not have explicit `MEASURE` instructions) and then measure *all qubits present in the quantum computer*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{0: array([1, 0, 0, 1, 1, 1, 1, 0, 1, 0]),\n",
       " 1: array([1, 0, 0, 1, 1, 1, 1, 0, 1, 0]),\n",
       " 2: array([1, 0, 0, 1, 1, 1, 1, 0, 1, 0])}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bitstrings = qc.run_and_measure(program, trials=10)\n",
    "bitstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's programatically verify that we always measure 000 or 111 by \"summing\" each bitstring and checking if it's eather 0 (for 000) or 3 (for 111)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([3, 0, 0, 3, 3, 3, 3, 0, 3, 0])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "bitstring_array = np.vstack(bitstrings[q] for q in qc.qubits()).T\n",
    "sums = np.sum(bitstring_array, axis=1)\n",
    "sums"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ True,  True,  True,  True,  True,  True,  True,  True,  True,\n",
       "        True])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sample_is_ghz = np.logical_or(sums == 0, sums == 3)\n",
    "sample_is_ghz"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.all(sample_is_ghz)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change alert: `run_and_measure` will return a dictionary of 1d bitstrings.\n",
    "\n",
    "*Not* a 2d array. To demonstrate why, consider a lattice whose qubits are not contiguously indexed from 0."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: we need a lattice that is not zero-indexed\n",
    "# qc = get_qc('Aspen-0-3Q-B')\n",
    "# qc.run_and_measure(ghz_state(qubits=[1,2,3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change alert: All qubits are measured\n",
    "\n",
    "PyQuil 1.x's `run_and_measure` would only measure qubits used in the given program. Now all qubits (per `qc.qubits()`) are measured. This is easier to reason about and reflects the reality of running on a QPU. When accounting for noise or when running QCVV tasks, you may be interested in the measurement results of qubits that weren't even used in your program!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{0: array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),\n",
       " 1: array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),\n",
       " 2: array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]),\n",
       " 3: array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qc = get_qc('4q-qvm')\n",
    "bitstrings = qc.run_and_measure(Program(X(0), X(1), X(2)), trials=10)\n",
    "bitstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can drop qubits you're not interested in by indexing into the returned dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0],\n",
       "       [1, 1, 1, 0]])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Stacking everything\n",
    "np.vstack(bitstrings[q] for q in qc.qubits()).T"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1],\n",
       "       [1, 1, 1]])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Stacking what you want (contrast with above)\n",
    "qubits = [0, 1, 2]\n",
    "np.vstack(bitstrings[q] for q in qubits).T"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change alert: `run_and_measure` works with noise models now.\n",
    "\n",
    "In pyQuil 1.x, `run_and_measure` would not work with noise models. Now noise models are supported. Pre-configured noise models can be used via `get_qc('xxxx-noisy-qvm')`.\n",
    "\n",
    "As a consequence, `run_and_measure` for large numbers of trials will be slower in Pyquil 2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{0: array([0, 1, 1, 0, 0, 1, 1, 0, 1, 1]),\n",
       " 1: array([0, 1, 1, 0, 0, 1, 1, 0, 1, 1]),\n",
       " 2: array([0, 1, 1, 0, 0, 1, 1, 0, 1, 1])}"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "qc = get_qc('3q-noisy-qvm')\n",
    "bitstrings = qc.run_and_measure(program, trials=10)\n",
    "bitstrings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 3, 3, 0, 0, 3, 3, 0, 3, 3])"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bitstring_array = np.vstack(bitstrings[q] for q in qc.qubits()).T\n",
    "sums = np.sum(bitstring_array, axis=1)\n",
    "sums"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Noise means now we measure things other than 000 or 111\n",
    "np.all(np.logical_or(sums == 0, sums == 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `list_quantum_computers`\n",
    "You can find all possible arguments to `get_qc` with `list_quantum_computers`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyquil import list_quantum_computers\n",
    "# TODO: unauthenticated endpoint\n",
    "# list_quantum_computers()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `QuantumComputer`s have a topology\n",
    "\n",
    "An important restriction when running on a real quantum computer is the mapping of qubits to the supported two-qubit gates. The QVM is designed to provide increasing levels of \"realism\" to guarantee that if your program executes successfully on `get_qc(\"Aspen-xxx-noisy-qvm\")` then it will execute successfully on `get_qc(\"Aspen-xxx\")`*\n",
    "\n",
    "\\* guarantee not currently guaranteed. This is a work in progress."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspecting the topology\n",
    "You can access a topology by `qc.qubit_topology()`, which will return a NetworkX representation of qubit connectivity. You can access the full set of supported instructions by `qc.get_isa()`. For example, we include a generic QVM named `\"9q-square-qvm\"` that has a square topology."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "qc = get_qc('9q-square-qvm')\n",
    "%matplotlib inline\n",
    "import networkx as nx\n",
    "nx.draw(qc.qubit_topology())\n",
    "from matplotlib import pyplot as plt\n",
    "_ = plt.title('9q-square-qvm', fontsize=18)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What If I don't want a topology?\n",
    "\n",
    "`WavefunctionSimulator` still has no notion of qubit connectivity, so feel free to use that for simulating quantum algorithms that you aren't concerned about running on an actual QPU. \n",
    "\n",
    "Above we used `get_qc(\"3q-qvm\")`, `\"4q-qvm\"`, and indeed you can do any `\"{n}q-qvm\"` (subject to computational resource constraints). These QVM's are constructed with a topology! It just happens to be fully connected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "nx.draw(get_qc('5q-qvm').qubit_topology())\n",
    "_ = plt.title('5q-qvm is fully connected', fontsize=16)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Heirarchy of realism\n",
    "\n",
    " - `WavefunctionSimulator` to debug algorithm\n",
    " - `get_qc(\"5q-qvm\")` to debug sampling\n",
    " - `get_qc(\"9q-square-qvm\")` to debug mapping to a lattice\n",
    " - `get_qc(\"9q-square-noisy-qvm\"`) to debug generic noise characteristics\n",
    " - `get_qc(\"Aspen-0-16Q-A-qvm\")` to debug mapping to a real lattice\n",
    " - `get_qc(\"Aspen-0-16Q-A-noisy-qvm\")` to debug noise characteristics of a real device\n",
    " - `get_qc(\"Aspen-0-16Q-A\")` to run on a real device"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## \"What is a `QuantumComputer`?\" Advanced Edition\n",
    "\n",
    "A `QuantumComputer` is a wrapper around three constituent parts, each of which has a programatic interface that must be respected by all classes that implement the interface. By having clear interfaces we can write backend-agnostic methods on `QuantumComputer` and mix-and-match backing objects.\n",
    "\n",
    "The following diagram shows the three objects that must be provided when constructing a `QuantumComputer` \"by hand\". The abstract classes are backed in grey with example implementing classes listed below. Please consult the [api reference](apidocs/quantum_computer.rst#pyquil.api.QuantumComputer) for details on each interface.\n",
    "\n",
    "![Pyquil Objects](./pyquil-objects.png)\n",
    "\n",
    "As an example, let's construct a 5-qubit QVM with one central node and only even numbered qubits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "topology = nx.from_edgelist([\n",
    "    (10, 2),\n",
    "    (10, 4),\n",
    "    (10, 6),\n",
    "    (10, 8),\n",
    "])\n",
    "from pyquil.device import NxDevice\n",
    "device = NxDevice(topology)\n",
    "\n",
    "from pyquil.api._qac import AbstractCompiler\n",
    "class MyLazyCompiler(AbstractCompiler):\n",
    "    def quil_to_native_quil(self, program):\n",
    "        return program\n",
    "    \n",
    "    def native_quil_to_executable(self, nq_program):\n",
    "        return nq_program\n",
    "    \n",
    "    \n",
    "from pyquil.api import QuantumComputer, QVM, ForestConnection\n",
    "my_qc = QuantumComputer(\n",
    "    name='my-qvm',\n",
    "    qam=QVM(connection=ForestConnection()),\n",
    "    device=device,\n",
    "    compiler=MyLazyCompiler(),\n",
    ")\n",
    "\n",
    "nx.draw(my_qc.qubit_topology())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{2: array([0, 0, 0, 0, 0]),\n",
       " 4: array([0, 0, 0, 0, 0]),\n",
       " 6: array([0, 0, 0, 0, 0]),\n",
       " 8: array([0, 0, 0, 0, 0]),\n",
       " 10: array([1, 1, 1, 1, 1])}"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "my_qc.run_and_measure(Program(X(10)), trials=5)"
   ]
  }
 ],
 "metadata": {
  "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}