docs/examples/orqviz_tutorial_orquestra.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7c804975",
   "metadata": {},
   "source": [
    "## Orqviz demo - How to get started (using Orquestra!)\n",
    "\n",
    "This notebook demonstrates how to get started with the _orqviz_ python package by Zapata Computing, Inc.\n",
    "The quantum computing framework used here is Zapata's _Orquestra Core_.\n",
    "\n",
    "The example algorithm in the demo is the _Variational Quantum Eigensolver_ (VQE) algorithm on a 2-qubit Hamiltonian for the H2 molecule. The goal of this algorithm is to minimize the energy of a parameterized quantum state on the Hamiltonian in order to approximate the ground state energy.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "To execute this notebook, you will need to install: numpy, matplotlib, openfermion, orquestra-core, and orqviz.\n",
    "</div>\n",
    "\n",
    "Links to Orquestra packages:\n",
    "- [orquestra-core](https://github.com/zapatacomputing/orquestra-core)\n",
    "- [orqviz](https://github.com/zapatacomputing/orqviz)\n",
    "\n",
    "#### Version Information\n",
    "\n",
    "| __Software__     | __Version__ |\n",
    "| ---------------- | ----------- |\n",
    "| numpy            | 1.20.3      |\n",
    "| matplotlib       | 3.4.2       |\n",
    "| orquestra-core   | 0.3.0       |\n",
    "| openfermion      | 1.3.0       | \n",
    "\n",
    "Let's get started!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f4a433c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87ae8b16",
   "metadata": {},
   "source": [
    "### Load the Hamiltonian"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "31502beb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0.2672918711075522+0j) [] +\n",
      "(0.09019208454797+0j) [X0 X1] +\n",
      "(0.09019208454797+0j) [Y0 Y1] +\n",
      "(0.3528491759440336+0j) [Z0] +\n",
      "(0.5776978208330051+0j) [Z0 Z1] +\n",
      "(-0.4628704661845907+0j) [Z1]\n"
     ]
    }
   ],
   "source": [
    "from openfermion.utils import load_operator\n",
    "\n",
    "H = load_operator(\"h2_ham_2q.data\", \"./data\")\n",
    "print(H)\n",
    "\n",
    "exact_g_energy = -1.145832178075"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ae8be88",
   "metadata": {},
   "source": [
    "This Hamiltonian _H_ contains X, Y and Z Pauli operators for two qubits. The goal is to prepare a quantum state, such that the sum of all the Pauli operator expectations with their respective coefficients is as low as possible. The best possible energy one can reach with this Hamiltonian is the exact ground state energy of -1.145832 Hartrees."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "abdf99bc",
   "metadata": {},
   "source": [
    "### Define my circuit\n",
    "\n",
    "Let's import the necessary components to construct our parameterized quantum circuit. Below, we construct a simple two-qubit circuit that comprises RY and CNOT gates. The CNOT gate is applied if there is more than one entangling layer. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "52ed8d00",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orquestra.quantum.circuits import Circuit, create_layer_of_gates, RY, CNOT, X"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "2a3ca3d8",
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_circuit(parameters, n_entangling_layers=0):\n",
    "    number_of_qubits = 2\n",
    "    parameter_index = 0\n",
    "    circuit = Circuit()\n",
    "    \n",
    "    circuit += X(0)\n",
    "    for ii in range(number_of_qubits):\n",
    "        circuit += RY(parameters[parameter_index])(ii)\n",
    "        parameter_index += 1\n",
    "    \n",
    "    for _ in range(n_entangling_layers):\n",
    "        circuit += CNOT(0, 1)                \n",
    "        for ii in range(number_of_qubits):\n",
    "            circuit += RY(parameters[parameter_index])(ii)\n",
    "            parameter_index += 1\n",
    "            \n",
    "    return circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "09dd6616",
   "metadata": {},
   "source": [
    "### Define my loss function (i.e. energy expectation)\n",
    "\n",
    "The most important routine needed to visualize the loss landscape of variational quantum algorithms is the _loss function_. The loss function takes in a vector of parameters, and returns a float/number which represents the _loss_. The loss function hides all the complicated quantum circuit shenanigans under the hood. Loss functions are sometimes also referred to as _cost functions_. \n",
    "\n",
    "In our VQE example, our loss is the energy, as we want to minimize it. Here, we define the function *calculate_energy*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "84615f5e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orquestra.quantum.estimation import calculate_exact_expectation_values\n",
    "from orquestra.quantum.api import EstimationTask\n",
    "\n",
    "def calculate_energy(parameters, n_entangling_layers):\n",
    "    \"\"\"\n",
    "    Function that receives parameters for a quantum circuit, as well as specifications for the circuit depth,\n",
    "    and returns the energy over a previously defined Hamiltonian H.\n",
    "    \"\"\"\n",
    "    circuit = get_circuit(parameters, n_entangling_layers)\n",
    "    task = EstimationTask(H, circuit, number_of_shots=None)\n",
    "    return np.sum(calculate_exact_expectation_values(backend, [task])[0].values)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "110efb56",
   "metadata": {},
   "source": [
    "As you might have noticed, `calculate_energy` has two inputs – `parameters` and `n_entangling_layers`. However, we said that in `orqviz` your loss function needs to take in only `parameters`. How do we deal with that?\n",
    "\n",
    "There are a couple of ways to do this:\n",
    "- use [`functools.partial`](https://docs.python.org/3/library/functools.html)\n",
    "- define a [closure function](https://www.programiz.com/python-programming/closure)\n",
    "- use our `LossFunctionWrapper` utility tool\n",
    "\n",
    "Let's focus on the last option – we added it to `orqviz` for people who don't feel comfortable with the other two options. `LossFunctionWrapper` is a utility tool which allows you to transform whatever function you want into a orqviz-compatible loss function that takes in only parameters.\n",
    "\n",
    "You just need to set all the other parameters to some constant value, like this:\n",
    "\n",
    "```\n",
    "loss_function = LossFunctionWrapper(calculate_energy, n_entangling_layers=1)\n",
    "```\n",
    "\n",
    "We'll see this in action in a moment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f177c428",
   "metadata": {},
   "source": [
    "### Get the simulator backend\n",
    "\n",
    "Now choose the quantum simulator backend to execute our algorithm. We choose _Qulacs_ simulator plugin in Orquestra because it is very fast. We could also choose other available backend plugin that Orquestra has integrated, e.g. the *statevector_simulator* from Qiskit, or built-in `SymbolicSimulator` (it doesn't require any additional installations, but is pretty slow)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "b874c4e3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# For better performance you might want to use Qulacs simulator\n",
    "from orquestra.integrations.qulacs import QulacsSimulator\n",
    "backend = QulacsSimulator()\n",
    "\n",
    "# from orquestra.quantum.symbolic_simulator import SymbolicSimulator\n",
    "# backend = SymbolicSimulator()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81d4d3e2",
   "metadata": {},
   "source": [
    "### Specify the quantum circuit \n",
    "\n",
    "We start out with no entanglement (i.e. no entangling operations) in the quantum circuit. This results in only 2 parameters.\n",
    "Additionally, we wrap our loss function with those specifications such that it only receives parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "6b657a88",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.loss_function import LossFunctionWrapper\n",
    "\n",
    "n_entangling_layers = 0\n",
    "initial_parameters = np.array([ 0.5896798 , -0.53733806])\n",
    "\n",
    "loss_function = LossFunctionWrapper(calculate_energy, n_entangling_layers=n_entangling_layers)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b6384117",
   "metadata": {},
   "source": [
    "Let's try computing the energy of our initial parameterized state."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "c9143f1c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "-0.8104077773325065"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "loss_function(initial_parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "86e9a62e",
   "metadata": {},
   "source": [
    "As a sidenote, `LossFunctionWrapper` has some additional utilities that you might find useful:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "22e4241f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Call count: 1\n",
      "Min value: -0.8104077773325065\n",
      "Average call time: 0.0017122920000001152\n"
     ]
    }
   ],
   "source": [
    "print(\"Call count:\", loss_function.call_count)\n",
    "print(\"Min value:\", loss_function.min_value)\n",
    "print(\"Average call time:\", loss_function.average_call_time)\n",
    "loss_function.reset() # this resets all the fields printed out above"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da926268",
   "metadata": {},
   "source": [
    "What does the circuit look like?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "6f8546d1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Circuit(operations=[X(0), RY(0.5896798)(0), RY(-0.53733806)(1)], n_qubits=2)\n"
     ]
    }
   ],
   "source": [
    "circuit = get_circuit(initial_parameters, n_entangling_layers)\n",
    "print(circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f52f0f1",
   "metadata": {},
   "source": [
    "In order to optimize our circuit, we grab a simple gradient descent optimizer from a local python file and a function to calculate a numerical gradient from _orqviz_."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "8a20e553",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gradient_descent_optimizer import gradient_descent_optimizer\n",
    "from orqviz.gradients import calculate_full_gradient\n",
    "\n",
    "def gradient_function(parameters):\n",
    "    return calculate_full_gradient(parameters, loss_function, stochastic=False, eps=1e-3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d83bcd3",
   "metadata": {},
   "source": [
    "### Optimize the circuit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "d9415a9a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "n_iters = 50\n",
    "parameter_trajectory, losses = gradient_descent_optimizer(initial_parameters, \n",
    "                                                          loss_function, \n",
    "                                                          n_iters, \n",
    "                                                          learning_rate=0.2, \n",
    "                                                          full_gradient_function=gradient_function)\n",
    "final_parameters = parameter_trajectory[-1]\n",
    "\n",
    "plt.plot(losses)\n",
    "plt.hlines(exact_g_energy, 0, n_iters, color=\"red\", label=\"Exact Energy\")\n",
    "plt.title(\"Final loss {:.3f}\".format(losses[-1]))\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cccd401c",
   "metadata": {},
   "source": [
    "This yields a final energy error of:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "16193452",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.01970658635894007"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.min(losses)-exact_g_energy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e5da2a4",
   "metadata": {},
   "source": [
    "What do we know about the problem so far? We know that optimizing with gradient descent is straightforward, but we haven't converged to a very good solution. Can we expect a solution better than this? Is this just a local minimum? VQE problems typically require a solution with error that is on the order of $10^{-3}$ Hartrees. \n",
    "\n",
    "For a better understanding of the problem and the optimization, we will use various methods from _orqviz_ in the following cells."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec2de59f",
   "metadata": {},
   "source": [
    "### Import visualization methods and start plotting\n",
    "\n",
    "First, let's interpolate between the initial and solution parameters to get a feel of the landscape that we are trying to traverse."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "8e642a0c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.scans import perform_1D_interpolation, plot_1D_interpolation_result, eval_points_on_path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "f4ab242a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "end_points = (-0.5, 1.5)\n",
    "\n",
    "interpolation_result = perform_1D_interpolation(initial_parameters, final_parameters, \n",
    "                                                loss_function, end_points=end_points)\n",
    "\n",
    "plot_1D_interpolation_result(interpolation_result, label=\"linear interpolation\", color=\"gray\")\n",
    "\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69c165d4",
   "metadata": {},
   "source": [
    "The red lines indicate the points you interpolate between, i.e. initial and final parameters.\n",
    "\n",
    "This looks very nice and convex. But is this all there is to see? Let's see this in 2D!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "71c3bafa",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.scans import perform_2D_scan, plot_2D_scan_result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "2f7079ef",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 432x288 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "dir1 = np.array([1., 0.])\n",
    "dir2 = np.array([0., 1.])\n",
    "\n",
    "scan_2D_result = perform_2D_scan(final_parameters, loss_function, \n",
    "                                 direction_x=dir1, direction_y=dir2, n_steps_x=40)\n",
    "\n",
    "plot_2D_scan_result(scan_2D_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "717e8a2d",
   "metadata": {},
   "source": [
    "Even in 2D it looks very well-behaved. We only have two parameters, so this plot is the exact landscape we are optimizing.\n",
    "\n",
    "But what was the path that we optimized? Let's see it with Principal Component Analysis (PCA)! In the case of 2 parameters, running PCA is a bit silly, but these plots can be useful for visualizing high-dimensional landscapes. We show the code for running PCA below, and this should work for any loss landscape with >2 parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "a1d1c745",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.pca import (get_pca, perform_2D_pca_scan, plot_pca_landscape, \n",
    "                        plot_optimization_trajectory_on_pca)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "1c4920c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "pca = get_pca(parameter_trajectory)\n",
    "scan_pca_result = perform_2D_pca_scan(pca, loss_function, n_steps_x=40)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "78fd2560",
   "metadata": {},
   "source": [
    "Note that our plotting functions allow for full flexibility with matplotlib. Any keywords that you would pass for plotting manually, you can pass to our plotting functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "da3e3534",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 432x288 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result, pca, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory, pca, ax=ax, \n",
    "                                    label=\"Optimization Trajectory\", color=\"lightsteelblue\")\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "029089d1",
   "metadata": {},
   "source": [
    "Because the landscape is so simple, optimization moves almost in a straight line."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21b0ddd8",
   "metadata": {},
   "source": [
    "### Let's zoom out a little!\n",
    "\n",
    "We can do so by setting the `offset` to a higher number. `offset` is the distance we leave between the edges of our trajectory and the border of the scan."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d1e709b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "scan_pca_result2 = perform_2D_pca_scan(pca, loss_function, n_steps_x=50, offset=8)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "69e0a39c",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result2, pca, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory, pca, ax=ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ebf7049",
   "metadata": {},
   "source": [
    "With this two-dimensional loss landscape, we can see the periodicity and notice that we do not sit in a bad local minimum. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46c5a117",
   "metadata": {},
   "source": [
    "### How about adding more layers in the quantum circuit?\n",
    "\n",
    "So far, we didn't include any entanglement in the quantum circuit. We will change this now!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25aa22ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "n_entangling_layers2 = 1\n",
    "\n",
    "initial_parameters2 = np.array([ 1.12840278, -1.85964912, -1.1847599 ,  1.27278466])\n",
    "\n",
    "loss_function2 = LossFunctionWrapper(calculate_energy, n_entangling_layers=n_entangling_layers2)\n",
    "\n",
    "def gradient_function2(parameters):\n",
    "    return calculate_full_gradient(parameters, loss_function2, stochastic=False, eps=1e-3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a915db3",
   "metadata": {},
   "source": [
    "The algorithm now has a 4-dimensional loss landscape. How do we even visualize that? In the exact same way! Our functions are fully flexible.\n",
    "\n",
    "### Optimize again!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9289a26",
   "metadata": {},
   "outputs": [],
   "source": [
    "n_iters = 50\n",
    "parameter_trajectory2, losses2 = gradient_descent_optimizer(initial_parameters2, \n",
    "                                                            loss_function2, \n",
    "                                                            n_iters, \n",
    "                                                            learning_rate=0.2, \n",
    "                                                            full_gradient_function=gradient_function2)\n",
    "final_parameters2 = parameter_trajectory2[-1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cbeb15a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(losses2)\n",
    "plt.hlines(exact_g_energy, 0, n_iters, color=\"red\", label=\"Exact Energy\")\n",
    "plt.title(\"Final loss {:.4f}\".format(losses2[-1]))\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "267c331c",
   "metadata": {},
   "source": [
    "Much better! We have a final energy error of:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0d66986",
   "metadata": {},
   "outputs": [],
   "source": [
    "np.min(losses2)-exact_g_energy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c318adc7",
   "metadata": {},
   "outputs": [],
   "source": [
    "end_points = (-0.5, 1.5)\n",
    "\n",
    "interpolation_result2 = perform_1D_interpolation(initial_parameters2, final_parameters2, \n",
    "                                                loss_function2, end_points=end_points)\n",
    "plot_1D_interpolation_result(interpolation_result2, label=\"linear interpolation\", color=\"gray\")\n",
    "\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcbac74a",
   "metadata": {},
   "source": [
    "How did we traverse the loss landscape this time?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8ebd474f",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "\n",
    "pca2 = get_pca(parameter_trajectory2)\n",
    "scan_pca_result3 = perform_2D_pca_scan(pca2, loss_function2, n_steps_x=50, offset=2)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result3, pca2, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory2, pca2, ax=ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "125057c3",
   "metadata": {},
   "source": [
    "This looks a little more complicated but still rather smooth. Note that with 4 parameters, this 2D scan is no longer an exact representation of the loss landscape. The scan is computing the loss on a 2D plane that \"slices\" the 4D space, and the parameter trajectory is _projected_ on the scan. The x and y labels indicate how representative the scan directions are for the trajectory and how big the degree of approximation is when projecting.\n",
    "\n",
    "Let's try zooming out again by increasing the `offset`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ca96b413",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "\n",
    "scan_pca_result4 = perform_2D_pca_scan(pca2, loss_function2, n_steps_x=50, offset=10)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result4, pca2, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory2, pca2, ax=ax)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3f36052",
   "metadata": {},
   "source": [
    "This looks much more involved and is no longer exactly periodic in the directions of our scan.\n",
    "\n",
    "_orqviz_ offers more than these simpler scans to help us understand the loss landscapes!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c385982d",
   "metadata": {},
   "source": [
    "### What does the Hessian tell us?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed0fa951",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.hessians import get_Hessian"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aac00f20",
   "metadata": {},
   "source": [
    "The function *get_Hessian* returns a numerically calculated Hessian of the loss function at a specified point in parameter space. The Hessian is a matrix of second partial derivatives of the loss, and as such, contains information about the _curvature_. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "af448068",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "hessian1 = get_Hessian(params=final_parameters, loss_function=loss_function, eps=1e-3)\n",
    "hessian2 = get_Hessian(params=final_parameters2, loss_function=loss_function2, eps=1e-3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81fb82ab",
   "metadata": {},
   "source": [
    "Calculating Hessians can be very expensive, as the number of loss function evaluations scales **quadratically** with the number of parameters. This is why _orqviz_ also provides an approximation of the Hessian with *get_Hessian_SPSA_approximation*. But let's not get ahead of ourselves. For now, this is very fast!\n",
    "\n",
    "What are the eigenvalues of the Hessian?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f88365cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.plot(hessian1.eigenvalues, label=f\"Eigenvalues with {n_entangling_layers} entangling layers\", \n",
    "         alpha=0.9, linewidth=1, marker=\"s\", ms=10)\n",
    "plt.plot(hessian2.eigenvalues, label=f\"Eigenvalues with {n_entangling_layers2} entangling layer\", \n",
    "         alpha=0.9, linewidth=1, marker=\"o\")\n",
    "plt.legend()\n",
    "plt.ylim(0,2)\n",
    "plt.title(\"Hessian Eigenvalues around the found solution\")\n",
    "plt.xlabel(\"Order of eigenvalue (sorted)\")\n",
    "plt.ylabel(\"Magnitude of eigenvalue\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87ffba3a",
   "metadata": {},
   "source": [
    "All eigenvalues are positive, which means that the Hessian is _positive-definite_ and we are in a convex region.\n",
    "\n",
    "We can also scan in the direction of the eigenvectors to see what it means to be in a convex region."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "795ed4c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.hessians import perform_1D_hessian_eigenvector_scan, plot_1D_hessian_eigenvector_scan_result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f406fd99",
   "metadata": {},
   "outputs": [],
   "source": [
    "hessian1_eigvec_scans = perform_1D_hessian_eigenvector_scan(hessian1, loss_function, n_points=31)\n",
    "hessian2_eigvec_scans = perform_1D_hessian_eigenvector_scan(hessian2, loss_function2, n_points=31)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1a48907",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12,4))\n",
    "\n",
    "plot_1D_hessian_eigenvector_scan_result(hessian1_eigvec_scans, eigenvalues=hessian1.eigenvalues, ax=ax1)\n",
    "plot_1D_hessian_eigenvector_scan_result(hessian2_eigvec_scans, eigenvalues=hessian2.eigenvalues, ax=ax2)\n",
    "\n",
    "ax1.set_ylim(-1.2,1.0)\n",
    "ax2.set_ylim(-1.2,1.0)\n",
    "ax1.set_title(\"Without entangling\")\n",
    "ax2.set_title(\"With one entangling Layer\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73a323d2",
   "metadata": {},
   "source": [
    "We see the energy mostly increases around our found solution when we scan in the directions of the Hessian eigenvectors. The respective eigenvalues of the eigenvectors are shown in the plot legend. We also see that there seem to be extensive low-energy regions around our solution. A 2D eigenvector scan can help us visualize that! Here we choose the eigenvectors as scan directions for 2D scans. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0949b499",
   "metadata": {},
   "outputs": [],
   "source": [
    "# A helper function to normalize the color ranges of the scans\n",
    "from orqviz.plot_utils import normalize_color_and_colorbar"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b9ef03af",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "scale_factor = np.pi  # how much to scan in the direction? The eigenvectors are normalized.\n",
    "\n",
    "scan_hess2_low = perform_2D_scan(parameter_trajectory2[-1], loss_function2, \n",
    "                                 direction_x=hessian2.eigenvectors[0]*scale_factor, \n",
    "                                 direction_y=hessian2.eigenvectors[1]*scale_factor,\n",
    "                                 n_steps_x=40)\n",
    "scan_hess2_high = perform_2D_scan(parameter_trajectory2[-1], loss_function2, \n",
    "                                 direction_x=hessian2.eigenvectors[-1]*scale_factor, \n",
    "                                 direction_y=hessian2.eigenvectors[-2]*scale_factor,\n",
    "                                 n_steps_x=40)\n",
    "\n",
    "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10,4))\n",
    "plot_2D_scan_result(scan_hess2_low, fig=fig, ax=ax1)\n",
    "plot_2D_scan_result(scan_hess2_high, fig=fig, ax=ax2)\n",
    "\n",
    "normalize_color_and_colorbar(fig=fig, ax=ax1, min_val=-1.2, max_val=1)\n",
    "normalize_color_and_colorbar(fig=fig, ax=ax2, min_val=-1.2, max_val=1)\n",
    "\n",
    "ax1.set_title(\"Scan in directions of minimal curvature\")\n",
    "ax2.set_title(\"Scan in directions of maximal curvature\")\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13a174bc",
   "metadata": {},
   "source": [
    "Informed by the Hessian, we were able to choose scan directions in which the loss increases very slowly or very quickly! \n",
    "\n",
    "Does this mean that there are low-energy paths throughout the landscape? Let's test this with the _Nudged Elastic Band_ in our _orqviz_ package.\n",
    "\n",
    "But first...\n",
    "\n",
    "### Find a second solution for the case with entanglement"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d022e477",
   "metadata": {},
   "outputs": [],
   "source": [
    "n_iters = 50\n",
    "initial_parameters3 = initial_parameters2 + np.array([-1.7, -2.3, -3.1,  2.8])\n",
    "\n",
    "parameter_trajectory3, losses3 = gradient_descent_optimizer(initial_parameters3, loss_function2, n_iters, \n",
    "                                                          learning_rate=0.2, full_gradient_function=gradient_function2)\n",
    "final_parameters3 = parameter_trajectory3[-1]\n",
    "\n",
    "plt.plot(losses3)\n",
    "plt.hlines(exact_g_energy, 0, n_iters, color=\"red\", label=\"Exact Energy\")\n",
    "plt.title(\"Final loss {:.3f}\".format(losses3[-1]))\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32c2fcd5",
   "metadata": {},
   "source": [
    "Let's run PCA's on both optimization trajectories to see where they went."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b23bda2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "\n",
    "pca3 = get_pca(np.append(parameter_trajectory2, parameter_trajectory3, axis=0))\n",
    "scan_pca_result5 = perform_2D_pca_scan(pca3, loss_function2, n_steps_x=50, offset=3)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result5, pca3, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory2, pca3, ax=ax, color=\"red\", label=\"The first trajectory\")\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory3, pca3, ax=ax, color=\"green\", label=\"The second trajectory\")\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a6760ed",
   "metadata": {},
   "source": [
    "This doesn't look like the two found solutions are connected at all... or are they?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6d04640",
   "metadata": {},
   "source": [
    "### Get the Nudged Elastic Band going!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "90fb2b09",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.elastic_band import Chain, ChainPath, run_NEB"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a609ba9",
   "metadata": {},
   "outputs": [],
   "source": [
    "initial_chain = Chain(np.linspace(final_parameters2, final_parameters3, num=10))\n",
    "initial_path = ChainPath(initial_chain)\n",
    "\n",
    "all_chains = run_NEB(initial_chain, loss_function2, \n",
    "                     n_iters=100, eps=1e-3, learning_rate=0.1)\n",
    "trained_chain = all_chains[-1]\n",
    "trained_path = ChainPath(trained_chain)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0fc6640f",
   "metadata": {},
   "outputs": [],
   "source": [
    "linear_loss = initial_path.evaluate_points_on_path(50, loss_function2)\n",
    "trained_loss = trained_path.evaluate_points_on_path(50, loss_function2)\n",
    "\n",
    "plt.plot(np.linspace(0,1,50), linear_loss, label=\"Linear Interpolation\")\n",
    "plt.plot(np.linspace(0,1,50), trained_loss, label=\"Optimized Path\")\n",
    "plt.ylabel(\"Energy\")\n",
    "plt.xlabel(\"Position on Path\")\n",
    "plt.legend()\n",
    "plt.ylim(-1.2, 0.6)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f57b2d49",
   "metadata": {},
   "source": [
    "There seems to be a path connecting the two found minima! Let's see it with PCA."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "47e79445",
   "metadata": {},
   "outputs": [],
   "source": [
    "pca_from_chain = get_pca(trained_chain.pivots)\n",
    "pca_chain_scan = perform_2D_pca_scan(pca_from_chain, loss_function2, n_steps_x=40, offset=3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d6754c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.pca import plot_line_through_points_on_pca, plot_scatter_points_on_pca"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb04f7cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(pca_chain_scan, pca_from_chain, fig=fig, ax=ax)\n",
    "plot_line_through_points_on_pca(trained_chain.pivots, pca_from_chain, ax=ax, linewidth=3, color=\"tab:orange\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0481792c",
   "metadata": {},
   "source": [
    "This looks very impressive! But the points seem very far apart. Given the periodicity of the gate parameters in our circuit, couldn't there be a shorter path? \n",
    "\n",
    "In fact, yes! Visualization techniques partially rely on respecting the symmetries of the loss function in order to produce the most valuable outcome. In the case of parameterized quantum circuits with Pauli gates like $Rx, Ry,$ and $Ry$,  all parameters are $2\\pi$-periodic, meaning that we get the same loss (and the same state) if we add multiples of $2\\pi$ to any or all parameters. Not only that, but the \"shortest path\" between two points in this periodic space is affected even more. _orqviz_ provides the following functions to _wrap_ parameters according to the periodicity of the parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be603c2c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from orqviz.geometric import relative_periodic_wrap, relative_periodic_trajectory_wrap"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "083d9793",
   "metadata": {},
   "source": [
    "`relative_periodic_wrap` wraps a point to the closest copy of itself with respect to a reference point. `relative_periodic_trajectory_wrap` wraps a parameter trajectory to a copy of itself such that the final point is the closest copy to a reference point. If we apply that to the two solutions that we found, this is what we get:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f1d5379",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "\n",
    "wrapped_parameter_trajectory3 = relative_periodic_trajectory_wrap(final_parameters2, parameter_trajectory3)\n",
    "\n",
    "pca3 = get_pca(np.append(parameter_trajectory2, wrapped_parameter_trajectory3, axis=0))\n",
    "scan_pca_result5 = perform_2D_pca_scan(pca3, loss_function2, n_steps_x=50, offset=3)\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(scan_pca_result5, pca3, fig=fig, ax=ax)\n",
    "plot_optimization_trajectory_on_pca(parameter_trajectory2, pca3, ax=ax, color=\"red\", label=\"The first trajectory\")\n",
    "plot_optimization_trajectory_on_pca(wrapped_parameter_trajectory3, pca3, ax=ax, color=\"green\", label=\"The second trajectory\")\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9b7e43f",
   "metadata": {},
   "outputs": [],
   "source": [
    "wrapped_final_parameters3 = relative_periodic_wrap(final_parameters2, final_parameters3)\n",
    "\n",
    "initial_chain2 = Chain(np.linspace(final_parameters2, wrapped_final_parameters3, num=10))\n",
    "initial_path2 = ChainPath(initial_chain2)\n",
    "###\n",
    "all_chains2 = run_NEB(initial_chain2, loss_function2, n_iters=100, eps=1e-3, learning_rate=0.1)\n",
    "trained_chain2 = all_chains2[-1]\n",
    "trained_path2 = ChainPath(trained_chain2)\n",
    "###\n",
    "linear_loss2 = initial_path2.evaluate_points_on_path(50, loss_function2)\n",
    "trained_loss2 = trained_path2.evaluate_points_on_path(50, loss_function2)\n",
    "###\n",
    "plt.plot(np.linspace(0,1,50), linear_loss2, label=\"Linear Interpolation\")\n",
    "plt.plot(np.linspace(0,1,50), trained_loss2, label=\"Optimized Path\")\n",
    "plt.ylabel(\"Energy\")\n",
    "plt.xlabel(\"Position on Path\")\n",
    "plt.legend()\n",
    "plt.ylim(-1.2, 0.6)\n",
    "plt.show()\n",
    "###\n",
    "pca_from_chain2 = get_pca(trained_chain2.pivots)\n",
    "pca_chain_scan2 = perform_2D_pca_scan(pca_from_chain2, loss_function2, n_steps_x=40, offset=3)\n",
    "###\n",
    "fig, ax = plt.subplots()\n",
    "plot_pca_landscape(pca_chain_scan2, pca_from_chain2, fig=fig, ax=ax)\n",
    "plot_line_through_points_on_pca(trained_chain2.pivots, pca_from_chain2, ax=ax, linewidth=3, color=\"tab:orange\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff6b45cb",
   "metadata": {},
   "source": [
    "The points were not separated by very high energy regions after all. \n",
    "\n",
    "This is a much richer picture than what we would have initially expected from just observing the optimization performance for 0 and 1 entangling layers (i.e. plotting the energy as a function of training epochs). Don't you agree?\n",
    "\n",
    "### For more ways to analyze loss landscapes of parameterized quantum circuits, check out the rest of the _orqviz_ package!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.0 64-bit",
   "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.10.0"
  },
  "vscode": {
   "interpreter": {
    "hash": "26de051ba29f2982a8de78e945f0abaf191376122a1563185a90213a26c5da77"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}