Learning2Learn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "3ByYL2o9sJe8"
   },
   "source": [
    "# Learning to Learn with Quantum NN via Classical NN\n",
    "\n",
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/stfnmangini/Learning2learn/blob/main/Learning2Learn.ipynb)\n",
    "\n",
    "This notebook aims to recreate the architecture proposed by Verdon et al. in the paper *Learning to learn with quantum neural networks via classical neural networks* [[1]](#1), using **PennyLane** [[2]](#2) and **TensorFlow** [[3]](#3). PennyLane is a cross-platform Python library for differentiable programming of quantum computers, which, in this tutorial will be used to create quantum circuits and interface them with TensorFlow, an open-source platform for machine learning, here used to build a custom model of a Recurrent Neural Network (RNN).\n",
    "\n",
    "We will start with a brief theoretical overview explaining the problem and the setup used to solve it. After that, we will deep dive into the code to build a fully functioning model, ready to be further developed or customized for your own needs. Without further ado, let's start!\n",
    "\n",
    "---\n",
    "\n",
    "### Problem: *Optimization of Variational Quantum Algorithms (VQAs)*\n",
    "\n",
    "Recently, a big effort by the quantum computing community has been devoted to the study of variational quantum algorithms (VQAs, for short) which leverage quantum circuits with fixed shape but with tunable parameters to solve a desired target task. The idea is similar to classical neural networks, where the weights of the network are optimized during training to perform best in regression or classification tasks. Similarly, once the shape of variational quantum circuit is chosen — something that is very difficult and sensitive to the particular task at hand — its tunable parameters are optimized iteratively by minimizing a cost (or loss) function, which measures how good the quantum algorithm is performing (see [[4]](#4) for a thorough overview on VQAs). \n",
    "\n",
    "\n",
    "A major challenge for VQAs relates to the optimization of tunable parameters, which was shown to be a very hard task to perform (a possible challenge is posed by the so called *barren plateaus*). In particular, parameters initialization plays a key role in this scenario, since initializing the parameters in the proximity of an optimal solution leads to faster convergence and better results with respect to random initialization, which could bring the model in a region in parameter space far from any good solution. Thus, a good initialization strategy is crucial to promote the convergence of local optimizers to local extrema and to select reasonably good local minima. Here, by local optimizer, we mean a procedure that moves from one solution to another by small (local) changes in parameter space. These are opposed to global search methods, which take into account the whole (or at least a large section) parameter space to propose a new solution.\n",
    "\n",
    "One such strategy could come from the classical machine learning literature. \n",
    "\n",
    "\n",
    "### Solution: *(Classical) Recurrent Neural Networks* \n",
    "\n",
    "By building on results from *meta-learning* literature in Classical ML, authors in [[1]](#1) propose to use a Recurrent Neural Network (RNN) as a black-box controller to optimize the tunable parameters of variational quantum algorithms, as shown in the figure below. The cost function used is the expectation value $\\langle H\\rangle_{\\boldsymbol{\\theta}} = \\langle \\psi_{\\boldsymbol{\\theta}}| H|\\psi_{\\boldsymbol{\\theta}}\\rangle $ of a Hamiltonian $H$ with respect to the parametrized state $|\\psi_{\\boldsymbol{\\theta}}\\rangle $ evolved by applying the variational quantum circuit to the zero state.\n",
    "\n",
    "|  |\n",
    "|:--|\n",
    "| <img src=\"./HybridLSTM.png\" alt=\"Scheme of the RNN architecture, as proposed in [[1]](#1)\" width=\"600\"/> | \n",
    "| **Recurrent Neural Network Scheme**. Given parameters $\\boldsymbol{\\theta}_{t-1}$ of the variational quantum circuit, the cost function $y_{t-1}$, and the hidden state of the classical network $h_{t-1}$ at the previous time step, the classical computer (the Recurrent Neural Network) proposes a new guess for the parameters $\\boldsymbol{\\theta}_t$, which are then fed into the quantum computer (the QAOA circuit) to evaluate the cost function $y_t$. By repeating this cycle a few times, and by training the weights of the recurrent neural network to minimize the loss function $y_t$, a good initialization heuristic is found for parameters $\\boldsymbol{\\theta}$ of the variational quantum circuit.|\n",
    "\n",
    "At a given iteration, the RNN receives as input the previous cost function $y_t$ evaluated on the quantum computer, where $y_t$ is the estimate of $\\langle H\\rangle_{t}$, as well as the parameters $\\boldsymbol{\\theta}_t$ for which the variational circuit was evaluated. The RNN at this time step also receives information stored in its internal hidden state from the previous time step $m_t$. The RNN itself has trainable parameters $\\phi$, and hence it applies the parametrized mapping:  \n",
    "\n",
    "$$ h_{t+1}, \\boldsymbol{\\theta}_{t+1} = \\text{RNN}_{\\phi}(h_{t}, \\boldsymbol{\\theta}_{t}, y_{t}) $$\n",
    "\n",
    "which generates a new suggestion for the variational parameters as well as a new internal state. Upon training the weights $\\phi$, the RNN eventually learns a good heuristic to suggest optimal parameters for the quantum circuit.  \n",
    "\n",
    "\n",
    "### VQAs in focus: QAOA for MaxCut\n",
    "There are multiple VQAs for which this hybrid training routine could be used, some of them directly analyzed in [[1]](#1). In the following, we will only focus on one of such examples, that is the use of the QAOA (Quantum Approximate Optimization Algorithm) for solving the MaxCut problem for graphs. Thus, referring to the picture above, the shape of the variational circuit is the one dictated by the QAOA ansatz, and such a quantum circuit is used to evaluate the cost Hamiltonian $H$ of the MaxCut problem of some graphs.  \n",
    "If you wish to refresh your memories, check out this great tutorial on how to use QAOA for solving graph problems: https://pennylane.ai/qml/demos/tutorial_qaoa_intro.html\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kiP9yNVrw780"
   },
   "source": [
    "**Run cell below only if using this notebook in Colab**  \n",
    "If you're running this notebook on Colab, you need to run the following cell to install required dependencies.\n",
    "\n",
    "On the other hand, if you're running this on your personal computer, be sure to have the following packages installed (including the listed standard Python libraries):\n",
    "\n",
    "* `Numpy`\n",
    "* `Matplotlib`\n",
    "* `TensorFlow` (`Keras` is integrated by default if using `TensorFlow 2.x`)\n",
    "* `PennyLane`\n",
    "* `NetworkX`\n",
    "\n",
    "***Note***: Running the whole tutorial requires approx. ~10m."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "id": "3Zq4Bnbttkoh"
   },
   "outputs": [],
   "source": [
    "IS_COLAB = False\n",
    "if IS_COLAB:\n",
    "    # TensorFlow is installed by default on Colab \n",
    "    !pip install --upgrade pennylane\n",
    "    !pip install networkx"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Importing the required packages\n",
    "\n",
    "As already mentioned at the start of the notebook, we will use *PennyLane* for executing quantum circuits and for integrating seamlessly with *TensorFlow*, which will be used for creating the RNN. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Quantum Machine Learning\n",
    "import pennylane as qml\n",
    "from pennylane import qaoa\n",
    "\n",
    "# Classical Machine Learning\n",
    "import tensorflow as tf\n",
    "\n",
    "# Generation of graphs\n",
    "import networkx as nx\n",
    "\n",
    "# Standard Python libraries\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import random\n",
    "\n",
    "# Set the seed for reproducibility of results\n",
    "# These seeds affect all random functions in this tutorial\n",
    "random.seed(42)\n",
    "np.random.seed(42)\n",
    "tf.random.set_seed(42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Package versions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "pennylane 0.13.0\n",
      "tensorflow 2.3.1\n",
      "networkx 2.4\n",
      "numpy 1.18.1\n"
     ]
    }
   ],
   "source": [
    "print('\\n'.join(f'{m.__name__} {m.__version__}' for m in globals().values() if getattr(m, '__version__', None)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6aEd_oBHter4"
   },
   "source": [
    "### Generation of training data: graphs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As for any Machine Learning project, the first step is to gather (or in our case create) a good dataset, which will be used to train the model and test its performances. In our case, we are analyzing the MaxCut problem, which deals with the problem of finding a good binary partition of nodes in a *graph*, such that the number of edges *cut* by such separation is maximized. For this reason, we start by generating some random graphs $G_{n,p}$ where:\n",
    "- $n$ is the number of nodes in the graphs,\n",
    "- $p$ is the probability of having an edge between two nodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "def generate_graphs(n_graphs, n_nodes, p_edge):\n",
    "    \"\"\"Generate a list containing random graphs generated by Networkx. \n",
    "    \n",
    "    Args:\n",
    "        n_graphs (int): length of final list, that is the number of graphs to generate\n",
    "        n_nodes (int): number of nodes in each graph\n",
    "        p_edge (float): Probability of having an edge between two nodes (see Networkx's documentation).\n",
    "    \n",
    "    Returns:\n",
    "        list: list containing the generated graphs\n",
    "    \"\"\"\n",
    "    \n",
    "    datapoints = []\n",
    "    for _ in range(n_graphs):\n",
    "        random_graph = nx.gnp_random_graph(n_nodes, p = p_edge)\n",
    "        datapoints.append(random_graph)\n",
    "    return datapoints"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An example of a random graph generated using the function `generate_graphs` just defined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Example of a random graph with 7 nodes and 11 edges (p=0.43)\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Define parameters of the graphs\n",
    "n_graphs = 20\n",
    "n_nodes = 7\n",
    "p_edge = 3./n_nodes\n",
    "graphs = generate_graphs(n_graphs, n_nodes, p_edge)\n",
    "\n",
    "print(f\"Example of a random graph with {len(graphs[0].nodes)} nodes and {len(graphs[0].edges)} edges (p={p_edge:.2f})\")\n",
    "nx.draw(graphs[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Variational Quantum Circuit: QAOA  \n",
    "\n",
    "Now that we have a dataset, we move on by creating the QAOA quantum circuits using PennyLane's built-in sub packages. In particular, using PennyLane's `qaoa` module, we will able to create fully functioning quantum circuits for the MaxCut problem, with very few lines of code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def qaoa_from_graph(graph, n_layers = 1):\n",
    "    \"\"\"Creates a cost function by encoding a Hamiltonian that solves the MaxCut problem using QAOA.\n",
    "\n",
    "    This function uses nested functions for the creation of the quantum circuit. When called, \n",
    "    it instantiates the QAOA circuit for the input graph and outputs a QAOA cost function. \n",
    "    Such function, given some parameters, evaluates the MaxCut cost function for the given graph.\n",
    "\n",
    "    Args:\n",
    "        graph (networkx.classes.graph.Graph): a graph generated with Networkx\n",
    "        n_layers (int): number of repetitions in the QAOA ansatz\n",
    "    \n",
    "    Returns:\n",
    "        hamiltonian (function): A function which, given some parameters as input, evaluates the MaxCut QAOA \n",
    "        cost function for the specified graph.\n",
    "    \"\"\"\n",
    "        \n",
    "    # Number of qubits (wires) equal to the number of nodes in the graph\n",
    "    wires = range(len(graph.nodes))\n",
    "    \n",
    "    # Define the structure of the cost and mixer subcircuits specifically for the MaxCut problem\n",
    "    cost_h, mixer_h = qaoa.maxcut(graph)   \n",
    "    \n",
    "    # Defines a layer of the QAOA ansatz from the cost and mixer Hamiltonians\n",
    "    def qaoa_layer(gamma, alpha):\n",
    "        qaoa.cost_layer(gamma, cost_h)\n",
    "        qaoa.mixer_layer(alpha, mixer_h)\n",
    "       \n",
    "    # Creates the actual quantum circuit for the QAOA algorithm\n",
    "    def circuit(params, **kwargs): \n",
    "        for w in wires:\n",
    "            qml.Hadamard(wires=w)\n",
    "        qml.layer(qaoa_layer, n_layers, params[0], params[1])\n",
    "     \n",
    "    # Evaluates the cost Hamiltonian\n",
    "    def hamiltonian(params, **kwargs):\n",
    "        \"\"\"Evaluate the MaxCut cost of the QAOA, given the angles for the circuit and the specified graph. \n",
    "        \n",
    "        Args:\n",
    "            params (list): List of angles for the QAOA circuit, with shape (n_layers x 2). \n",
    "                params has the shape [angles_1, ..., angles_(n_layers)], where angles_i = [alphas_i, gammas_i].\n",
    "        \n",
    "        Returns:\n",
    "            cost (function): Cost Hamiltonian evaluated with the input angles\n",
    "        \"\"\"\n",
    "        # We set the default.qubit.tf device for seamless integration with TensorFlow\n",
    "        dev = qml.device('default.qubit.tf', wires=len(graph.nodes))\n",
    "        \n",
    "        # ExpvalCost evaluates the expectation value of an operator\n",
    "        cost = qml.ExpvalCost(circuit, cost_h, dev, interface=\"tf\",  diff_method = \"backprop\")\n",
    "        \n",
    "        return cost(params)\n",
    "    \n",
    "    return hamiltonian"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before moving on, let's see how to use these functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<tf.Tensor: shape=(1,), dtype=float64, numpy=array([-3.19326796])>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create an instance of a QAOA circuit given a graph.\n",
    "cost = qaoa_from_graph(graph = graphs[0], n_layers = 1)\n",
    "\n",
    "# Define some paramenters\n",
    "# Since we use only one layer in QAOA, params have the shape 1 x 2, in the form [[alpha, gamma]].\n",
    "# If not specificed, TensorFlow converts Python floating point numbers to tf.float32. \n",
    "x = tf.Variable([[0.5], [0.5]], dtype = tf.float32)\n",
    "\n",
    "# Evaluate th QAOA instance just created with some angles.\n",
    "cost(x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we optimize the parameters to reduce the cost function `cost`. We can do this using `tf.GradientTape()`, which works directly thanks to PennyLane's seamless integration with TensorFlow when using the `default.qubit.tf` device. \n",
    "\n",
    "> We use the `Adam` optimizer for its ease of use and good performances on most optimization problems. Feel free to try other optimizers too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Step 1 - Loss = [-3.19326796]\n",
      "Step 2 - Loss = [-3.82155533]\n",
      "Step 3 - Loss = [-4.64066003]\n",
      "Step 4 - Loss = [-5.35547035]\n",
      "Step 5 - Loss = [-5.68578276]\n",
      "Step 6 - Loss = [-5.65524931]\n",
      "Step 7 - Loss = [-5.60867761]\n",
      "Step 8 - Loss = [-5.70526933]\n",
      "Step 9 - Loss = [-5.90673464]\n",
      "Step 10 - Loss = [-6.13248962]\n",
      "Step 11 - Loss = [-6.32379863]\n",
      "Step 12 - Loss = [-6.47240742]\n",
      "Step 13 - Loss = [-6.61170083]\n",
      "Step 14 - Loss = [-6.77039115]\n",
      "Step 15 - Loss = [-6.93776967]\n",
      "\n",
      "Final cost function: [-7.07072686]\n",
      "Optimized angles: [[0.53574044]\n",
      " [1.2945652 ]]\n"
     ]
    }
   ],
   "source": [
    "x = tf.Variable([[0.5], [0.5]], dtype = tf.float32)\n",
    "\n",
    "# Select an optimizer\n",
    "opt = tf.keras.optimizers.Adam(learning_rate=0.1)\n",
    "\n",
    "# Choose the number of optimization steps\n",
    "step = 15\n",
    "\n",
    "# Start of optimization (or training)\n",
    "for _ in range(step):\n",
    "    with tf.GradientTape() as tape:\n",
    "        loss = cost(x)\n",
    "        \n",
    "    gradients = tape.gradient(loss, [x])\n",
    "    opt.apply_gradients(zip(gradients, [x]))\n",
    "    print(f\"Step {_+1} - Loss = {loss}\")\n",
    "    \n",
    "print(f\"\\nFinal cost function: {cost(x).numpy()}\\nOptimized angles: {x.numpy()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the loss function is correctly minimized throughout the optimization process, which eventually yields an optimal value for the angles in the QAOA ansatz. \n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Recurrent Neural Network: LSTM  \n",
    "\n",
    "So far, we have defined the machinery which lets us build the QAOA algorithm for solving the MaxCut problem of a graph.  \n",
    "Now we wish to implement the Recurrent Neural Network architecture explained previously. In particular, as proposed in the original paper, we will build a custom model of an LSTM (Long-Short Term Memory) network, capable of handling the hybrid data passing between classical and quantum procedures. For this task, we will use `Keras` and `TensorFlow`.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First of all, let's define the elemental building block of the model, that is an LSTM cell (see [TensorFlow documentation](https://www.tensorflow.org/api_docs/python/tf/keras/layers/LSTMCell) for further details)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Number of layers in QAOA ansatz. The higher the better in terms of performance, \n",
    "# but it also gets more computationally hard. For simplicity, we will stick to the single layer case.\n",
    "n_layers = 1\n",
    "\n",
    "# Define a single LSTM cell. The cell has two units per layer\n",
    "# since each layer in the QAOA ansatz make use of two angles (parameters). \n",
    "cell = tf.keras.layers.LSTMCell(2*n_layers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the `qaoa_from_graph` function, we create a list `graph_cost_list` containing the cost functions of a set of graphs. You can see this as a preprocessing step of the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We create the QAOA MaxCut cost functions of some graphs\n",
    "graph_cost_list = [qaoa_from_graph(g) for g in graphs]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At this stage, we seek to reproduce the recurrent behavior depicted in the picture above, outlining the functioning of RNN as a black-box optimizer. We do so by defining two functions:   \n",
    "- `rnn_iteration`: accounts for the computations happening on a single time step in the figure, that is it performs the calculation inside the CPU and evaluates the quantum circuit on the QPU to obtain the loss function for the current parameters.\n",
    "- `recurrent_loop`: as the name suggests, it accounts for the creation of the recurrent loop of the model. In particular, it makes consecutive calls to the `rnn_iteration` function, where the outputs of a previous call are fed as inputs of the next call. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "def rnn_iteration(inputs, graph_cost, n_layers = 1):\n",
    "    \"\"\"Perform a single time step in the computational graph of the custom RNN. \n",
    "    \n",
    "    The function takes as inputs, the outputs from a previous time step and a graph cost function, \n",
    "    and then goes through the Keras' LSTM cell. Its output is used to evaluate the QAOA MaxCut cost function. \n",
    "    \n",
    "    Args:\n",
    "        inputs (list): List of inputs coming from the previous timestep: cost function, parameters, first LSTM hidden state,\n",
    "            second LSTM hidden state. \n",
    "        graph_cost (function): Cost function of a graph coming from the qaoa_from_graph function\n",
    "    \n",
    "    Returns:\n",
    "        list: A list containing new values for the cost, parameters, and hidden states. \n",
    "    \"\"\"\n",
    "    # Unpack the input list containing the previous cost, parameters, and hidden states (denoted as 'h' and 'c').\n",
    "    prev_cost = inputs[0]\n",
    "    prev_params = inputs[1]\n",
    "    prev_h = inputs[2]\n",
    "    prev_c = inputs[3]\n",
    "    \n",
    "    # Concatenate the previous parameters and previous cost to create new input\n",
    "    new_input = tf.keras.layers.concatenate([prev_cost, prev_params])\n",
    "        \n",
    "    # Call the LSTM cell, which outputs new values for the parameters along with new internal states h and c\n",
    "    new_params, [new_h, new_c] = cell(new_input, states = [prev_h, prev_c])\n",
    "             \n",
    "    # Reshape the parameters to correctly match those expected by PennyLane\n",
    "    _params = tf.reshape(new_params, shape = (2, n_layers))\n",
    "             \n",
    "    # Evaluate the cost using new angles \n",
    "    _cost = graph_cost(_params)\n",
    "    \n",
    "    # Reshape to be consistent with other tensors\n",
    "    new_cost = tf.reshape(tf.cast(_cost, dtype=tf.float32), shape = (1,1))\n",
    "    \n",
    "    return [new_cost, new_params, new_h, new_c] \n",
    "\n",
    "def recurrent_loop(graph_cost, n_layers = 1, intermediate_steps = False):\n",
    "    \"\"\"Creates the recurrent loop for the Recurrent Neural Network.\n",
    "    \n",
    "    The recurrent loops are created manually by connecting consecutive iterations calls \n",
    "    to the custom LSTM model created in `rnn_iteration`.\n",
    "    \n",
    "    Args:\n",
    "        graph_cost (function): Cost function of a graph coming from the qaoa_from_graph function\n",
    "        intermediate_steps (bool): Boolean flag, set to True if you wish to store values from intermediate iterations\n",
    "\n",
    "    Returns:\n",
    "        loss (tf.Tensor): Loss function driving the minimization process\n",
    "    \"\"\"\n",
    "    # Initialize starting all inputs (cost, parameters, hidden states) as zeros.\n",
    "    initial_cost = tf.zeros(shape = (1, 1))\n",
    "    initial_params = tf.zeros(shape = (1, 2*n_layers))\n",
    "    initial_h = tf.zeros(shape = (1, 2*n_layers))\n",
    "    initial_c = tf.zeros(shape = (1, 2*n_layers))\n",
    "    \n",
    "    # We perform five consecutive calls to 'rnn_iteration', thus creating the recurrent loop.\n",
    "    # More iterations lead to better results, at the cost of more computationally intensive simulations.\n",
    "    out0 = rnn_iteration([initial_cost, initial_params, initial_h, initial_c], graph_cost)\n",
    "    out1 = rnn_iteration(out0, graph_cost)\n",
    "    out2 = rnn_iteration(out1, graph_cost)\n",
    "    out3 = rnn_iteration(out2, graph_cost)\n",
    "    out4 = rnn_iteration(out3, graph_cost)\n",
    "    \n",
    "    # This cost function takes into account the cost from all iteration, but using different weights. \n",
    "    loss = tf.keras.layers.average([0.1 * out0[0], 0.2 * out1[0], 0.3 * out2[0], 0.4 * out3[0], 0.5 * out4[0]])\n",
    "    \n",
    "    if intermediate_steps:\n",
    "        return [out0[1], out1[1], out2[1], out3[1], out4[1], loss]\n",
    "    else:\n",
    "        return loss"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### The cost function\n",
    "A key part in the `recurrent_loop` function, is given by the definition of the variable `loss`. In order to drive the learning procedure of the weights in the LSTM cell, a cost function is needed. While in the original paper the authors suggest to use a measure called *observed improvement*, for simplicity here we use an easier cost function $\\cal{L}(\\phi)$ defined as:  \n",
    "\n",
    "$$\\cal{L}(\\phi) = {\\bf w} \\cdot {\\bf y}_t(\\phi)$$\n",
    "\n",
    "where ${\\bf y}_t(\\phi) = (y_1, \\cdots, y_5)$ contains the Hamiltonian cost functions from all iterations, and ${\\bf w}$ are just some coefficients weighting the different steps in the recurrent loop. In this case, we used ${\\bf w}=(0.1, 0.2, 0.3, 0.4, 0.5)$, to give more importance to the last steps rather than the initial steps. Intuitively in this way the RNN is more free (low coefficient) to explore a larger portion of parameter space during the first steps of optimization, while it is constrained (high coefficient) to select an optimal solution towards the end of the procedure.\n",
    "Note that one could also use just the final cost function from the last iteration to drive the training procedure of the RNN. However, using values also from intermediate steps allows for a smoother suggestion routine, since even non-optimal parameter suggestions from early steps are penalized using $\\cal{L}(\\phi)$.  \n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Training\n",
    "\n",
    "Now all the cards are on the table and we just need to prepare a training routine and then run it!\n",
    "\n",
    "First of all, let's wrap a single gradient descent step inside a custom function `train_step`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "def train_step(graph_cost):\n",
    "    \"\"\"Single optimization step in the training procedure. \n",
    "    \n",
    "    Given the cost/circuit of a graph, it evaluates the corresponding loss and eventually \n",
    "    computes the gradients and update the prameters.\n",
    "    \n",
    "    Args:\n",
    "        graph_cost (function): cost function of a graph coming from the qaoa_from_graph function\n",
    "    \n",
    "    Returns:\n",
    "        loss (tf.Tensor): loss for the specified graph, for the current values of the parameters\n",
    "    \"\"\"\n",
    "    with tf.GradientTape() as tape:\n",
    "        # Evaluates the cost function\n",
    "        loss = recurrent_loop(graph_cost)\n",
    "        \n",
    "    # Evaluates gradients, cell is the LSTM cell defined previously\n",
    "    grads = tape.gradient(loss, cell.trainable_weights)\n",
    "    \n",
    "    # Apply gradients and update the weights of the LSTM cell\n",
    "    opt.apply_gradients(zip(grads, cell.trainable_weights))\n",
    "    return loss"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are now ready to start the training. In particular, we will perform a stochastic gradient descent in the parameter space of the weights of the LSTM cell. For each graph in the training set, we evaluate gradients and update the weights accordingly. Then, we repeat this procedure for multiple times (epochs).\n",
    "\n",
    "> For a QAOA ansatz using one single layer, and for a training set of 20 graphs, each epoch takes approximately ~1m to run on a standard laptop. Be careful when using bigger dataset or training for larger epochs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch 1\n",
      " > Graph 1/20 - Loss: -1.6641689538955688\n",
      " > Graph 6/20 - Loss: -1.4186843633651733\n",
      " > Graph 11/20 - Loss: -1.3757232427597046\n",
      " > Graph 16/20 - Loss: -1.294339656829834\n",
      " >> Mean Loss during epoch: -1.7352586269378663\n",
      "Epoch 2\n",
      " > Graph 1/20 - Loss: -2.119091749191284\n",
      " > Graph 6/20 - Loss: -1.4789190292358398\n",
      " > Graph 11/20 - Loss: -1.3779840469360352\n",
      " > Graph 16/20 - Loss: -1.2963457107543945\n",
      " >> Mean Loss during epoch: -1.8252217948436738\n",
      "Epoch 3\n",
      " > Graph 1/20 - Loss: -2.1322619915008545\n",
      " > Graph 6/20 - Loss: -1.459418535232544\n",
      " > Graph 11/20 - Loss: -1.390620470046997\n",
      " > Graph 16/20 - Loss: -1.3165746927261353\n",
      " >> Mean Loss during epoch: -1.8328069806098939\n",
      "Epoch 4\n",
      " > Graph 1/20 - Loss: -2.1432175636291504\n",
      " > Graph 6/20 - Loss: -1.476362943649292\n",
      " > Graph 11/20 - Loss: -1.3938289880752563\n",
      " > Graph 16/20 - Loss: -1.3140206336975098\n",
      " >> Mean Loss during epoch: -1.8369774043560028\n",
      "Epoch 5\n",
      " > Graph 1/20 - Loss: -2.1429405212402344\n",
      " > Graph 6/20 - Loss: -1.477513074874878\n",
      " > Graph 11/20 - Loss: -1.3909202814102173\n",
      " > Graph 16/20 - Loss: -1.315887689590454\n",
      " >> Mean Loss during epoch: -1.8371947884559632\n"
     ]
    }
   ],
   "source": [
    "# Select an optimizer \n",
    "opt = tf.keras.optimizers.Adam(learning_rate=0.1)\n",
    "\n",
    "# Set the number of training epochs\n",
    "epochs = 5\n",
    "\n",
    "for epoch in range(epochs):\n",
    "    print(f\"Epoch {epoch+1}\")\n",
    "    total_loss = np.array([])\n",
    "    for i, graph_cost in enumerate(graph_cost_list):\n",
    "        loss = train_step(graph_cost)\n",
    "        total_loss = np.append(total_loss, loss.numpy())\n",
    "        # Log every 5 batches.\n",
    "        if i % 5 == 0:\n",
    "            print(f\" > Graph {i+1}/{len(graph_cost_list)} - Loss: {loss[0][0]}\")\n",
    "    print(f\" >> Mean Loss during epoch: {np.mean(total_loss)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the Loss for each graph keeps decreasing across epochs, indicating that the training routine is working correctly.  \n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see how to use the optimized RNN as an initializer for the angles in the QAOA algorithm. \n",
    "\n",
    "First, we pick a new graph, not present in the training dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "new_graph = nx.gnp_random_graph(7, p = 3/7)\n",
    "new_cost = qaoa_from_graph(new_graph)\n",
    "\n",
    "nx.draw(new_graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we apply the trained RNN to this new graph, saving intermediate results coming from all the recurrent iterations in the network."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Apply the RNN (be sure that training was performed)\n",
    "res = recurrent_loop(new_cost, intermediate_steps = True)\n",
    "\n",
    "# Extract all angle suggestions\n",
    "start_zeros = tf.zeros(shape = (2*n_layers, 1))\n",
    "guess_0 = res[0]\n",
    "guess_1 = res[1]\n",
    "guess_2 = res[2]\n",
    "guess_3 = res[3]\n",
    "guess_4 = res[4]\n",
    "final_loss = res[5]\n",
    "\n",
    "# Wrap them into a list\n",
    "guesses = [start_zeros, guess_0, guess_1, guess_2, guess_3, guess_4]\n",
    "\n",
    "# Losses from the hybrid LSTM model\n",
    "lstm_losses = [new_cost(tf.reshape(guess, shape = (2, n_layers))) for guess in guesses]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Plot of the loss function\n",
    "\n",
    "We can plot these losses to see how well the RNN propose new guesses for the parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAZMAAAEJCAYAAABR4cpEAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjMsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy+AADFEAAAgAElEQVR4nO3dfXxcZZ338c+vnTQtaZpAE2hLwcK6Iki1YhZ5uBEElqdd9MbFVfclCKiVvRdRkHtBuHFRVndFlsqKtw8IKre7osAqitwguFuVFVyDPFUKipWHlNJ2AmnTkA6Z5rd/nJlkksxMzpy5kslkvu/Xa145cx7mXOc3aX69ruuc6zJ3R0REpBpzal0AERGpf0omIiJSNSUTERGpmpKJiIhUTclERESqlqp1AaZaR0eHr1ixAoBsNgtAKjXrL3tKKY7hKJbhKJZhZLNZHnnkkbS7d1Zy3KyP+ooVK+ju7gYgnU4D0NHRUcsi1T3FMRzFMhzFMox0Ok1nZ+czlR6nZi4REamakomIiFRNyURERKo26/tMRETiGBoaoqenh507d9a6KNNm/vz5LF++nKampqo/q6GSiTrmwlAcw1Esw6k2lj09PbS2trJixQrMLFCpZi53p7e3l56eHvbbb7+R9UnjqGYuERFg586dLF68uCESCYCZsXjx4mA1MSUTEZGcRkkkeSGvt6GSSV9fH319fbUuRt1THMNRLMNRLMNIGsOGSSaf+ASceupuHH74Qv7rv2pdmvqWzWZHnjaW6iiW4cyGWC5cuHDCuieffJJjjjmGVatWceCBB7J69WruvvtuVq1axapVq1i4cCEHHHAAq1at4swzz2Tt2rWYGTfccMPIZzz00EOYGVdfffWkZUgaw4bpgH/4YbjvvnkAbNxY48KIiMR0/vnnc8EFF/D2t78dgMcee4yVK1dy4oknAnDMMcdw9dVX09XVBcDatWtZuXIl3/nOd3j/+98PwM0338wb3vCGKS1nw9RM9txzdHnLltqVQ0SkEps2bWL58uUj71euXDnpMfvuuy87d+5k8+bNuDt33XUXJ5988lQWs3GSSWfBkGVbt9auHCJSH664AszCvE49NXk5LrjgAo499lhOPvlk1qxZE7tP4/TTT+eWW27hF7/4BYcccgjNzc3JCxFDwyQT1UxEpB6dffbZrF+/nne+852sXbuWww47jEwmM+lxf/mXf8ktt9zCt7/9bd7znvdMeTkbJpmoZiIi9WrZsmWcc8453H777aRSKdatWzfpMUuWLKGpqYl77rmH4447bsrL2DAd8IXJRDWT6kx1dbmRKJbhhI7lFVdEr1q76667OO6442hqauKFF16gt7eXvffeO9axn/rUp9iyZQtz586Nfb6kcWyYZFLYzKWaSXVaW1trXYRZQ7EMZzbE8uWXXx7T2X7hhRfS09PDRz7yEebPnw/A5z73OZYsWRLr84444oiKy5A0jubuiQ6sF11dXd7d3U1PD+yzT7RuyRLYtKm25RKRmWX9+vUceOCBtS7GtCt23Wb2oLt3VfI5DdtnMjxcu7LUu6GhIYaGhmpdjFlBsQxHsQwjaQwbJpk0N0Nra5RBdu0CjbqQ3LZt29i2bVutizErKJbhKJZhJI1hwyQTgMWLR5v01AkvIuPN9mb/8UJe74xJJmZ2kZm5mRUdTN/M9jWzH5vZejN73MxWVHqOzs7Rti11wotIofnz59Pb29swCSU/n0m+Y79aM+JuLjPbB/hT4Nkyu90EfNrd7zGzhUDFvR6LF48eopqJiBRavnw5PT09bG2g/2nmZ1oMYUYkE2AN8LfA7cU2mtlBQMrd7wFw9x1xPzibzZJOpwFobZ0HRPdQ/+EPOxgcnMuCBQsAGBwcZGBgoOTnFM4+1tfXV3Jkzebm5pFb64aGhsq2P7a1tY1Ml9nf31/yqdZUKkV7e/vI+/z1FNPS0qJryqmXa8pkMmX3rcdrqsX3lM1mSaWiP2lJr6m1tXXMrbG1vqbp+J7Gn79u+0zM7G3ARnd/pMxurwH6zOzfzOwhM/ucmZV8CsfMVptZt5l19/b2jqxfvHjXyHJvb2NNgiMiMpWm5TkTM7sXKPaUzWXApcAJ7r7NzJ4Gutw9Pe7404EbgDcSNYV9B7jT3W9gEvnnTAD+/u93cPnl0XwB550HX/hC4ktqaPn/9Wj+8uopluEolmGk02k6Ozsrfs5kWpq53P34YuvNbCWwH/BIbvrI5cCvzexQd3+hYNce4CF335A77vvAYUQJJrbly0c7mhqoWTS4tra2Whdh1lAsw1Esw0gax5r2mbj7Y8DIQCelaibAr4DdzazT3bcCxwLdlZ5v2bLRy1UHfHL5NlypnmIZjmIZRtI4zpQO+AnMrAs4190/4O67zOwi4CcWVWEeBK6v9DNf9zq45proafj99w9dYhGRxtUwY3NBdDcEzI4B4WpJcQxHsQxHsQyjv7+fRYsWaWyucjKZTKxJZaQ8xTEcxTIcxTKMpDFsqGQiIiJTQ8lERESq1nDJ5NJLW1i5EvbaC+67r9alERGZHWbs3VxTpadnDvnpkzdvrm1ZRERmi4armXR0aBh6EZHQGqpmkkql+OhHX+HCC+ez555jZ1+U+PKD6Un1FMtwFMswksaxoaLf3t7OIYfUuhT1r3B0UqmOYhmOYhlG0jg2XDOXiIiEp2QiIiJVa6hkkk6nSafT7NoVjRr8+9/XukT1KR9HqZ5iGY5iGUbSGDZUnwnA5s3GXnvB8HDUAa87ukREqtdQNROA3Xd3hnNTwff2MrIsIiLJNVwymTcP8jcrDA/Diy/WtjwiIrNBwyUTGPt8iZq5RESq1/DJRNP3iohUryGTyZ57ji4rmYiIVK+h7uZqaWkB1MxVrXwcpXqKZTiKZRhJ49hQyWTBggWAaibVysdRqqdYhqNYhpE0jg3ZzKWaiYhIWA1VMxkcHARgzz1HM69qJpXLx1H/E6yeYhmOYhlGPo6VmlE1EzO7yMzczDpKbL/KzH5jZuvN7J/NzCr5/IGBAQYGBnQ3V5XycZTqKZbhKJZhJI3hjEkmZrYP8KfAsyW2HwEcCbweOBj4E+DoJOdSM5eISFgzqZlrDfC3wO0ltjswH5gHGNAETDrxbjabHRm4bNu2bQDMnWvAYmC0ZjI4OFg2I3d0jFaW+vr6yGazRfdrbm6mtbUVgKGhoZFzFtPW1kZTUxMA/f39ZDKZovulUqkxcwyUG4itpaVlpJqva6qPa8pkMmX3rcdrqsX3lM1mRyZ2mi3XVIvvqVx5ypkRNRMzexuw0d0fKbWPu98P/AewKfe6293Xl/i81WbWbWbdvb29E7YvXjw6dW9vL+zaVeUFiIg0OHP3yfcKcSKze4ElRTZdBlwKnODu28zsaaDL3dPjjn81cC3wrtyqe4CL3f1n5c7b1dXl3d3dwGi27ujoYI894KWXon22bNEUvpUojKNUR7EMR7EMI51O09nZ+aC7d1Vy3LQ1c7n78cXWm9lKYD/gkVx/+nLg12Z2qLu/ULDracAD7r4jd9z/Bw4DyiaTUjo7R5PJ1q1KJiIi1ah5M5e7P+bue7r7CndfAfQAh4xLJBB1zB9tZikzayLqfC/azBVH4YOL6oQXEanOTOqAn8DMuoBz3f0DwK3AscBjRJ3xd7n7Dyv5vMLqr24PTk7NCOEoluEolmEkjeOMSya52kl+uRv4QG55F/ChUOcpTCb55i4REUmm5s1ctfLJT0JPD2QysHp1rUsjIlLfZlzNZCr19fUB0N7ezpJi95VJLIVxlOooluEolmHk41iphkompR4iksoojuEoluEolmEkjWPDNnOJiEg4DVUzKTQ8HD39vmULDAzAoYfWukQiIvWrYZPJ5s2wbFm03NGh24NFRKrRsM1chbdSa3wuEZHqNGzNpKkJ9t8fUqnomZOBAVi0qNalEhGpTw2VTJqbm8e8//3va1SQOjc+jpKcYhmOYhlG0jg2VDLJzyEg1VEcw1Esw1Esw0gax4btMxERkXBi1UzMbB5wFrAKWFi4zd3PDF+sqTE0NAQwMnOZJKM4hqNYhqNYhpGPY6XiNnN9E3gD8ENiTJU7U+Wno8yPirlhA/zqV9FtwQcdBMceW8vS1Y/xcZTkFMtwFMswkk7bGzeZnATs5+7JBm2ZoX70Izj//Gj5r/9ayUREJKm4fSbPArPuVglNkCUiEkbcmslNwO1mdi3jmrnc/d+Dl2qaaIIsEZEw4iaT83I/PzNuvQP7hyvO9CpMJqqZiIgkFyuZuPt+U12QWihs5lLNREQkudgPLZpZCjgC2BvoAe5397qeQGDx4tHlF1+EbDYaXkVERCoT9zmT1xLdFrwAeA7YB9hpZqe6+/opLF9QbW1tY96nUlFC6e0F9+jnXnvVqHB1ZHwcJTnFMhzFMoykcYx7N9f/Bb4K7OPuh7v7cuDLufV1o6mpacIDTeqEr1yxOEoyimU4imUYSWMYN5msAq5xdy9Y9/nc+qqY2RVmttHMHs69Timx30lm9qSZPWVml1R73jx1wouIVC9uMnkeOHrcuqNy60NY4+6rcq87x280s7nAF4GTgYOA95jZQZWepL+/n/7+/jHr1AlfuWJxlGQUy3AUyzCSxjBud/OlwA/M7A7gGeBVwJ8B70101sodCjzl7hsAzOxm4O3A45MdmM1mSafTwOgwAZlMBoCWlhY6OxeM7Lthww7S6Z1FP6dwiIa+vj6y2eL3HjQ3N4+Mujk0NFR2aIK2traRKmV/f/9IucZLpVK0t7ePvM9fTzEtLS0sWBBd0+DgIAMDAyX3TXpNW3JVuGLlrddrqtX3lMlkRl6z5ZqgNt9TNpsllUrR2to6a66pFt9T0uFUYtVM3P0HwCHAOqA19/NN7n57orNOdJ6ZPWpmN5rZ7kW2703U8Z/Xk1tXlJmtNrNuM+vu7e0te+LCZq7eXg2iLCKShI3tBpmik5jdCywpsuky4AEgTfQA5JXAUnc/Z9zx7wROdPcP5N6fARzq7h+e7NxdXV3e3d0NjGbrwv9BXHcdfDj3KeeeC1/6UmXX1oiKxVGSUSzDUSzDSKfTdHZ2PujuXZUcV7KZy8y+6u6rc8v/j+iP/QRxhqB39+PjFMbMrgfuKLKph+h25LzlBOqvUQe8iEj1yvWZ/KFg+ampKoCZLXX3Tbm3pxE1oY33K+CPzWw/YCPwbuCvQpxfHfAiItUrmUzc/R8K3n7F3V8Yv4+ZFWu6qtRVZraKqObzNPCh3GcvA77m7qe4e9bMzgPuBuYCN7r7bwKcWzUTEZEA4t7N9VtgUZH1jwN7VFMAdz+jxPrngVMK3t8JTLhtuBKpImOl6KHFyhWLoySjWIajWIaRNI5xj7IJK8wWAcOJzlojhbfO5S1eDGbRcCovvghDQ6CHaMsrFkdJRrEMR7EMI2kcyyYTM3uOqPlpgZk9O27zYuDbic46g6RScOihUQLp7ISdO5VMREQqNVnN5L1EtZI7gcLmKAc2u/uTU1Ww6fTAA7UugYhIfSubTNz9pwBm1uHuL09PkaaO7kMPQ3EMR7EMR7EMo9zT8+XEfeT7W2Z2VOEKMzvKzG5NdFYREZlV4iaTo4FfjFt3P/DWsMUREZF6FPdurp1AC7C9YN1CYCh4iWpg3TpYuza6NbirC049tdYlEhGpL3FrJncDX8ndDpy/Lfg64K6pKth0+ulPo/G5PvUp+NGPal0aEZH6EzeZfIzoocUXzWwL8CLQBnx0qgo2nTSkiohIdWI1c7n7S8Cf5YZP2Qd4rtjwKvXqwAOjEYM7O2FV1XNHiog0nkqfmx8GeoHdzGx/gPyEVfWgpaWl6PqDD9bQ85UoFUepnGIZjmIZRtI4xkomZnYScAOwdNwmJxp4sS7kZxeT6iiO4SiW4SiWYSSNY9w+ky8STVzV4u5zCl51k0hERGTqxG3m2p1oGPqpn5ZxCg0ODgL6H0y1FMdwFMtwFMsw8nGsVNyayQ3A2YnOMIMMDAwwMDBQdNuVV8Jf/AUcdRQ88cQ0F6zOlIujVEaxDEexDCNpDOPWTA4DzjezS4Axd3G5+1sSnXmG+clPoudNAHp64LWvrW15RETqSdxk8rXca9bSJFkiIsnFfc7km1NdkForfHBR0/eKiFQm7q3B55Ta5u43hitO7ahmIiKSXNxmrvHztC8B/gj4T2BWJBMNqSIiklzcZq4JQ83naisHVlsAM7sC+CCQ/xN+qbvfOW6ffYCbiJLYMPBVd7+22nMXKqyZqJlLRKQylQ6nUugbQBr43wHKscbdry6zPQt8zN1/bWatwINmdo+7P17JScrNwKaaSXyayS4cxTIcxTKMpHGM22cy/nmU3Yjmh+9LdNYKufsmYFNuud/M1gN7AxUlk3JUMxERSS5uzSRLNA5XoY1EzVMhnGdmZwLdRDWQl0rtaGYrgDcCv4zzwdlstuScxi0tLSNPyy5cOAhEy1u2DJNOvzhm38Js3dfXRzabLfqZzc3NtLa2AjA0NMS2bdtKlq2trY2mpiYA+vv7yWQyRfdLpVK0t7ePvC83R3PhNQ0ODpZ9AEnXpGsCXZOuKcyDniWTiZntXvBHfb9xmwfcPfas82Z2L1F/x3iXAV8iGvfLcz//CSh695iZLQRuAz7q7tuL7ZPbbzWwGmD58uUj63fs2AHAwoULJxyzxx4wZ44zPGxs2zaHV16BefPiXF3jKRdHqUxfXx+ZTIa5czXMXbW2bds24Y+qVC7/77tSVmq4LTPb7u75mRXvdffjkxcvZmGiWscd7n5wkW1NwB3A3e5+TdzP7Orq8u7ubmA0W5dqE9xzz9H+ko0bYdmySkrfOCaLo8SnWIajWIaRTqfp7Ox80N27Kjmu3NhcL5vZwWY2FzjUInPGv6orNphZ4bD2pwHriuxjROODra8kkVRKnfAiIsmUSwafBP4LeAVoIeo3GSp45d9X6yoze8zMHgXeClwAYGbLzCx/i/CRRM+6HGtmD+depwQ49xh6cFFEJJmSfSbu/iUzu56or+MJ4HVTUQB3H/9AZH7988ApueX7AJuK8xfSkCoiIsmUvZvL3bNAj5m90d2fmaYy1YxqJiIiycTq83D33011QWYCPWsiIpJMNU/A153m5uay29UBH89kcZT4FMtwFMswksaxoZJJ/kGhUtTMFc9kcZT4FMtwFMswksYx7nAqFxUbO8vMLpzKW3Wn2+tfD5dfHiWVgw6qdWlEROpHyYcWx+xU8ADjuPUvuvseU1KyQAofWhwaiu5kzg9PIMkojuEoluEolmEMDQ0xb968ih9aLFszMbNjc4tzzeytjL09d3+gv7Ji1lZ+DBw9IVsdxTEcxTIcxTKMcmOFlTNZM9cNuZ/zGTsJlgObgQ8nOquIiMwqkz1nsh+Amd3k7mdOT5FERKTexH3OZEwiMbO3mtlRU1Ok2rrgAjjqKDjgAHjssVqXRkSkPsRKJmb2UzM7Mrd8MXAzcLOZXTqVhauFRx6B++6D3/4WNm2qdWlEROpD3FF/DwYeyC1/EDgGOAw4dwrKVFN61kREpHJxH1qcA7iZ/RHR7cTrIZpAa8pKViMXXwznnhs9Df+qV9W6NCIi9SFuMrkPuA5YCnwPIJdYYs+2OBO0tbVNus8hh0xDQepcnDhKPIplOIplGEnjGLeZ6yygD3gUuCK37rXAtYnOWiNNTU16oCkAxTEcxTIcxTKMpDGMVTNx917g0nHrfpTojCIiMuvEvZurycw+aWYbzGxn7ucnzWzeVBcwpP7+fvr74z20/8orkK6rRrzpU0kcpTzFMhzFMoykMYzbzHUVcDzR3VtvyP08FvhsorPWSCaTIZPJlN1nwwbYfXdobobDD5+mgtWZOHGUeBTLcBTLMJLGMG4H/DuBN+SauwCeNLNfA4+Qm7N9tmhvh76+aFkTZImIxBO3ZlJq/vUpn5d9urW3w9y50fL27aD/6IiITC5uMrkF+KGZnWhmB5rZScD3ge9OXdFqY84cKBx0VP0mIiKTi5tM/ha4F/gi8CDwBeA/gIurLYCZXWFmG83s4dzrlDL7zjWzh8zsjmrPW07h9L1q6hIRmVzcW4NfAT6Re02FNcVmciziI8B6YMJEXSFpSBURkcpMNjnWkcDb3H1CDcTM/hH4vrs/MPHI8MxsOfBnwKeBC+Mel81mSefaqnbs2DFmW0tLCwsWLABgcHCQgYEBABYtagWaAfj97/tJpzNjJtzp6+sjm80WPV9zc/PIHMpDQ0NlJ5ppa2sbeUCov7+/5F0UqVSK9vb2kffpMm1vpa6pmKTXND6Oher1mmr1PaVSKTKZTNl96+2aoDbfU768MHuuqRbfU7l/3+VM1sx1KfCzEtt+ClyW6KwTnWdmj5rZjWXG+/o8UXPb8GQfZmarzazbzLp7e3tH1i9cuJCFCxdOWpiOjtFT9PbOunsMqhY3jjK59vZ2Fi2a0op2w2hraxvzB1WSSfpvu+wc8Ga2EdjX3XcV2ZYCnnX3ZZOexOxeYEmRTZcRjUacJpq98UpgqbufM+74PwdOcff/ZWbHABe5+59Pdl4YOwd8XFdeCZ/INehdcgn8wz9UdLiISF0zs7BzwBP1TcwDBotsawJa45zE3Y+Ps5+ZXQ8U61w/EnhbrnN+PrDIzL7l7u+N87mVKuyAV5+JiMjkJmvmegI4ocS2E3Lbq2JmSwvengasG7+Pu3/c3Ze7+wrg3cC/J0kk6XS6bFtinjrgy4sbR5mcYhmOYhlG0hhOlkzWAF8xs3eY2RwAM5tjZu8Avgxck+isY11lZo+Z2aPAW8k9UW9my8zszgCfX7HCZKJbg0VEJle2mcvd/9XMlgDfBJrNLA10ADuBv3P3b1dbAHc/o8T654EJz5y4+1pgbbXnLUfNXCIilZn0ORN3v8bMvgYcDiwGeoH73X37VBeuVlQzERGpTNyHFrcDd09xWWaM/Phcu3ZBfz/s3Anz59e6VCIiM1fc4VQaypw56oQXEamEkkkJSiYiIvHFnc9kVmhpaYm9rzrhS6skjlKeYhmOYhlG0jg2VDLJj0cThzrhS6skjlKeYhmOYhlG0jiqmauEK6+EdeuiRPJXf1Xr0oiIzGwNVTMZHIxGhYmTeV/96qkuTf2qJI5SnmIZjmIZRj6OlWqoZJIfalm/bNVRHMNRLMNRLMMoN8x+OWrmEhGRqimZlPHKK/D88/C739W6JCIiM5uSSQlPPQXNzbD33nDSSbUujYjIzKZkUsLixaPLes5ERKS8huqAr0R7ezQe16JF0TMnQ0OQm4pZRETGUTIpwQwGBqJxukREpLyGSiYdHR0V7a9EUlylcZTSFMtwFMswksZRfy5FRKRqSiYiIlK1hmrm6uvrA6C9vT3W/s89B+vXR3dzvfa18KY3TWXp6kelcZTSFMtwFMsw8nGsVEPVTLLZLNlsNvb+N90EJ54I730vfPe7U1iwOlNpHKU0xTIcxTKMpDFsqGRSKU2QJSIST82TiZldYWYbzezh3OuUEvu1m9mtZvaEma03s8OnumyFE2RpThMRkdJmSp/JGne/epJ9rgXucvfTzWwesNtUF0o1ExGReGZKMinLzBYBbwHOAnD3V4BX4hybzWZJp9MAbNu2bcy2lpaWkeGqBwcHJwy9nErNAfYAxiaTvr6+ku2Kzc3NtLa2AjA0NDThnIXa2tpoyj1W39/fTyaTKbpfKpUa06mYv55iJrumQoX3k+uaandNmUym7L71eE21+J6y2SypVPQnbbZcUy2+p3LlKafmzVw555nZo2Z2o5ntXmT7/sBW4Otm9pCZfc3MSk5UbGarzazbzLp7e3sTF6qjw0eW1cwlIlKaufvke1V7ErN7gSVFNl0GPACkAQeuBJa6+znjju/K7Xeku//SzK4Ftrv75ZOdu6ury7u7u4EoswMj/yuYjHs0cvDQUPT+5ZdB8+5UHkcpTbEMR7EMo7+/n0WLFj3o7l2VHDctzVzufnyc/czseuCOIpt6gB53/2Xu/a3AJZWWo9JfMrOo3+T556P3W7fCvvtWetbZR/9Yw1Esw1Esw0gax5o3c5nZ0oK3pwHrxu/j7i8Az5nZAblVxwGPT0PxxnTCq6lLRKS4mdABf5WZrSJq5noa+BCAmS0Dvubu+VuFPwz8S+5Org3A2ZWeaCjXXtVUwVjyhbcH646uSJI4SnGKZTiKZRj5OFaq5snE3c8osf554JSC9w8DFbXhjZe/S6GSUTFVM5koSRylOMUyHMUyjHq/m2vGUs1ERGRySiaT0IOLIiKTUzKZhJq5REQmp2QyCTVziYhMTslkEmrmEhGZnJLJJDRysIjI5Gp+a/B0amtrq/gY1UwmShJHKU6xDEexDCNpHBsqmSR5mGnRIth7b2hvjxLL0BA0+jNReigsHMUyHMUyjKRxbKhkkoQZ9PTUuhQiIjNbQ/WZ9Pf3j4wsKskpjuEoluEolmEkjWFDJZNMJlNychmJT3EMR7EMR7EMI2kMGyqZiIjI1FCfSQxPPAHd3dHdXG96E7zlLbUukYjIzKKaSQzf+x6ccQZceCH88Ie1Lo2IyMyjZBKDnjURESlPzVwxHHQQvOtdUVI54ohal0ZEZOZpqGSSSiW73COOUBIplDSOMpFiGY5iGUbSODZU9Nvb22tdhFlBcQxHsQxHsQwjaRzVZyIiIlVTMhERkao1VDNXOp0GoKOjo+JjP/tZ+O1vo2Hov/IVWLYsdOnqRzVxlLEUy3AUyzDycaxUzZOJmV0BfBDI33R7qbvfWWS/C4APAA48Bpzt7junq5zf+Q489FC0vHFjbZJJXx/853/CU0+BezQIZbnX6adD4b8rd/j610e3n3XW2M9/4QW47TYYHo72HR4uvtzfv4ATTniFo4+e1ssXkRms5skkZ427X11qo5ntDZwPHOTug2b2XeDdwDemqXw1mSTrhRfg5z+PXj/7GTz6aPTHPK7DDhubTHbtgve/P1pOpSYmk6efhvPOi/PJLSxdOqxkIiIjZkoyiSMFLDCzIWA34Pk4B2Wz2ZFq27Zt28Zsa2lpYcGCBQAMDg4yMDBQ8nM6O0f/Kj/zzMuk0y8X3a+5uZnW1lYAhoaGJpyzUFtb28jcAf39/ezYkeG225q5//4mHnigiQ0b5sa4wtIymZ2k0ztG3g8NAUTXMTzsgI1s6+vrY/t2gHh3crz88mHHQ20AAAhjSURBVCDp9MQB4cZfU6lB41Kp1Ji7RspVrSv5ngqbOPr6+shms0X3q+Z7Cn1NmUym7L71eE21+J6y2ezIba2z5Zpq8T2VK085MyWZnGdmZwLdwMfc/aXCje6+0cyuBp4FBoEfu/uPS32Yma0GVgMsX748SAELayZbt1rpHWMaHp440dbcuXD55S309RW/L2LOHHjjG+HggweZNy+qpRS+os9oYu7cFO6wxx5jqzFm8O5378Q9+iyYP2Z7Z+cwZ589iFm0fc6c6JimprnMnz8PM3DfxY4d2znggAywoOo4iMjsYF5Ju0nSk5jdCywpsuky4AEgTdQXciWw1N3PGXf87sBtwLuAPuAW4FZ3/9Zk5+7q6vLu7m6gug66f/xH+PjHo+WLLoLPfW7iPu6QycD27dFreBhe85qx+zzwAHzmM3DffbBmDbzvfWO3v+1to+N/NTfDm98MRx0VvQ4/PJr5sdbU0RmOYhmOYhlGOp2ms7PzQXfvquS4aamZuPvxcfYzs+uBO4psOh74g7tvze33b8ARwKTJJJTC8bluvRV+85soYfT3jyaP7duhsGb7+tfDI4+M/ZwnnhhNFj//+cRkctZZUdI46ij4kz+JEoqIyExX82YuM1vq7ptyb08D1hXZ7VngMDPbjaiZ6ziiJrGKtLS0JC5nYTPX009Hr8lEfRBj5ZpKAXj88Ynb3/GOSks2/aqJo4ylWIajWIaRNI41TybAVWa2iqiZ62ngQwBmtgz4mruf4u6/NLNbgV8DWeAh4KuVnijf6ZTE4YfDwoWwY0f5/ZqaoK0tao7aZ5+J21euhK9+NZoTZXwTWL2oJo4ylmIZjmIZRtI4TkufSS0V9plUa8MGWLsWFiyIahiLFo2+8u/VLCUi9c7MZmafyUwxODgIJM+8++8fvRpdtXGUUYplOIplGPk4Vqqhkkn+fmr9slVHcQxHsQxHsQyj3LM05WigRxERqZqSiYiIVE3JREREqqZkIiIiVVMyERGRqimZiIhI1Wb9Q4tmthV4pmBVB9HAklIdxTEcxTIcxTKMA9y9dfLdRs3650zcvbPwvZl1V/pkp0ykOIajWIajWIZhZhUPG6JmLhERqZqSiYiIVK0Rk0nFow1LUYpjOIplOIplGBXHcdZ3wIuIyNRrxJqJiIgEpmQiIiJVa5hkYmYnmdmTZvaUmV1S6/LUMzN72sweM7OHk9xC2MjM7EYz22Jm6wrW7WFm95jZ73I/d69lGetBiTheYWYbc7+XD5vZKbUsY70ws33M7D/MbL2Z/cbMPpJbX9HvZUMkEzObC3wROBk4CHiPmR1U21LVvbe6+yrd01+xbwAnjVt3CfATd/9j4Ce591LeN5gYR4A1ud/LVe5+5zSXqV5lgY+5+4HAYcDf5P4+VvR72RDJBDgUeMrdN7j7K8DNwNtrXCZpQO7+M+DFcavfDnwzt/xN4H9Oa6HqUIk4SgLuvsndf51b7gfWA3tT4e9loySTvYHnCt735NZJMg782MweNLPVtS7MLLCXu2+C6B82sGeNy1PPzjOzR3PNYGourJCZrQDeCPySCn8vGyWZWJF1uic6uSPd/RCiZsO/MbO31LpAIsCXgD8CVgGbgH+qbXHqi5ktBG4DPuru2ys9vlGSSQ+wT8H75cDzNSpL3XP353M/twDfI2pGlOQ2m9lSgNzPLTUuT11y983uvsvdh4Hr0e9lbGbWRJRI/sXd/y23uqLfy0ZJJr8C/tjM9jOzecC7gR/UuEx1ycxazKw1vwycAKwrf5RM4gfA+3LL7wNur2FZ6lb+D1/Oaej3MhYzM+AGYL27X1OwqaLfy4Z5Aj53m+DngbnAje7+6RoXqS6Z2f5EtRGIRp3+V8UyPjP7NnAM0VDpm4G/A74PfBfYF3gWeKe7q3O5jBJxPIaoicuBp4EP5dv8pTQz+x/Az4HHgOHc6kuJ+k1i/142TDIREZGp0yjNXCIiMoWUTEREpGpKJiIiUjUlExERqZqSiYiIVE3JRGSGMrMduVuxRWY8JROREnJD7R9vZmeZ2X1TfK61ZvaBwnXuvtDdN0zleUVCUTIRmWJmlqp1GUSmmpKJSHkHAl8GDs81O/UBmFmzmV1tZs+a2WYz+7KZLchtO8bMeszsYjN7Afi6me1uZneY2VYzeym3vDy3/6eBo4Drcue4LrfezezVueU2M7spd/wzZvZ/zGxObttZZnZfrjwvmdkfzOzkaY+UNDQlE5Hy1gPnAvfnmp3ac+s/C7yGaPiOVxNNafCJguOWAHsArwJWE/1b+3ru/b7AIHAdgLtfRjScxXm5c5xXpBxfANqA/YGjgTOBswu2vxl4kmh4kauAG3JjLolMCyUTkQrl/kh/ELjA3V/MTSj0GaIBRPOGgb9z94y7D7p7r7vf5u4v5/b/NFFSiHO+ucC7gI+7e7+7P000vPoZBbs94+7Xu/suoomMlgJ7VXmpIrGpLVekcp3AbsCDBf/5N6JBRPO2uvvOkY1muwFriKaazU/a1Gpmc3MJoJwOYB7wTMG6Zxg7wdsL+QV3fzlXroVxL0ikWqqZiExu/GioaaJmqte5e3vu1ebuC8sc8zHgAODN7r4IyE8oZiX2H3++IaImsrx9gY0VXIPIlFIyEZncZmB5bi4cCiZfWmNmewKY2d5mdmKZz2glSkB9ZrYH0ZDp489R9JmSXM3lu8CnzazVzF4FXAh8q4prEglKyURkcv8O/AZ4wczSuXUXA08BD5jZduBeoppHKZ8HFhDVMh4A7hq3/Vrg9NzdWP9c5PgPAwPABuA+4F+BG5Ndjkh4ms9ERESqppqJiIhUTclERESqpmQiIiJVUzIREZGqKZmIiEjVlExERKRqSiYiIlI1JRMREanafwMgnXECOHmw2QAAAABJRU5ErkJggg==\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "\n",
    "plt.plot(lstm_losses, color = \"blue\", lw = 3, ls = \"-.\", label=\"LSTM\")\n",
    "\n",
    "plt.grid(ls = \"--\", lw = 2, alpha = 0.25)\n",
    "plt.ylabel(\"Cost function\", fontsize = 12)\n",
    "plt.xlabel(\"Iteration\", fontsize = 12)\n",
    "plt.legend()\n",
    "ax.set_xticks([0,5,10,15,20]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Comparison with standard Stochastic Gradient Descent (SGD)\n",
    "\n",
    "That's remarkable! The RNN learned to propose new parameters such that the MaxCut cost is minimized very rapidly: in just few iterations the loss reaches a minimum — actually, just after one single step, the LSTM finds a very good minimum. But how well does this method compare with standard optimization techniques, for example, leveraging Stochastic Gradient Descent (SGD) to optimize the parameters in the QAOA?  \n",
    "\n",
    "Let's check it out. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Step 1 - Loss = [-4.1700805]\n",
      "Step 2 - Loss = [-4.67503588]\n",
      "Step 3 - Loss = [-5.09949909]\n",
      "Step 4 - Loss = [-5.40388533]\n",
      "Step 5 - Loss = [-5.59529203]\n",
      "Step 6 - Loss = [-5.70495197]\n",
      "Step 7 - Loss = [-5.7642561]\n",
      "Step 8 - Loss = [-5.79533198]\n",
      "Step 9 - Loss = [-5.81138752]\n",
      "Step 10 - Loss = [-5.81966529]\n",
      "Step 11 - Loss = [-5.82396722]\n",
      "Step 12 - Loss = [-5.82624537]\n",
      "Step 13 - Loss = [-5.82749126]\n",
      "Step 14 - Loss = [-5.82820626]\n",
      "Step 15 - Loss = [-5.82864379]\n",
      "Final cost function: [-5.78429065]\n",
      "Optimized angles: [[0.53574044]\n",
      " [1.2945652 ]]\n"
     ]
    }
   ],
   "source": [
    "# Parameters are randomly initialized\n",
    "x0 = tf.Variable(np.random.rand(2,1))\n",
    "\n",
    "# We set the optimizer to be a Stochastic Gradient Descent\n",
    "opt = tf.keras.optimizers.SGD(learning_rate=0.01)\n",
    "step = 15\n",
    "\n",
    "# Training process\n",
    "steps = []\n",
    "sdg_losses = []\n",
    "for _ in range(step):\n",
    "    with tf.GradientTape() as tape:\n",
    "        loss = new_cost(x0)\n",
    "        \n",
    "    steps.append(x0)\n",
    "    sdg_losses.append(loss)\n",
    "    \n",
    "    gradients = tape.gradient(loss, [x0])\n",
    "    opt.apply_gradients(zip(gradients, [x0]))\n",
    "    print(f\"Step {_+1} - Loss = {loss}\")\n",
    "    \n",
    "print(f\"Final cost function: {new_cost(x).numpy()}\\nOptimized angles: {x.numpy()}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "\n",
    "plt.plot(sdg_losses, color = \"orange\", lw = 3, label=\"SGD\")\n",
    "\n",
    "plt.plot(lstm_losses, color = \"blue\", lw = 3, ls = \"-.\", label=\"LSTM\")\n",
    "\n",
    "plt.grid(ls = \"--\", lw = 2, alpha = 0.25)\n",
    "plt.legend()\n",
    "plt.ylabel(\"Cost function\", fontsize = 12)\n",
    "plt.xlabel(\"Iteration\", fontsize = 12)\n",
    "ax.set_xticks([0,5,10,15,20]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Hurray!* 🎉🎉   \n",
    "As is it clear from the picture, the RNN reaches a better minimum in fewer (but comparable) iterations than the standard SGD (Stochastic Gradient Descent). Thus, as the authors suggest, the (trained) RNN can be used for few iterations at the start of the training procedure to initialize the parameters of the quantum circuit close to an optimal solution. Then, a standard optimizer like the SGD, can be used to fine-tune the proposed parameters and reach even better solutions.  \n",
    "While on this small scale example the benefits of using an LSTM to initialize parameters may seem modest, on more complicated instances and problems it can make a big difference, since, on random initialization of the parameters, standard local optimizer may encounter problems finding a good minimization direction (for further details, see [[1,4]](#1))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Loss landscape in parameter space\n",
    "In addition, we can also plot the path suggested by the RNN in the space of the parameters. Note that this is possible only if one layer is used in the QAOA ansatz since in this case only two angles are needed and they can be plotted on a 2D plane. Of course, if more layers are used, you can always select a pair of them to reproduce a similar plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Note: this cell takes approx. ~1m to run with an 11 by 11 grid\n",
    "\n",
    "# Evaluate the cost function on a grid in parameter space\n",
    "dx = dy = np.linspace(-1., 1., 11)\n",
    "dz = np.array([new_cost([[xx],[yy]]).numpy() for yy in dy for xx in dx])\n",
    "Z = dz.reshape((11,11))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot cost landscape\n",
    "plt.contourf(dx, dy, Z)\n",
    "plt.colorbar()\n",
    "\n",
    "# Extract optimizer steps\n",
    "params_x = [0.]+[res[i].numpy()[0,0] for i in range(len(res[:-1]))]\n",
    "params_y = [0.]+[res[i].numpy()[0,1] for i in range(len(res[:-1]))]\n",
    "\n",
    "# Plot steps\n",
    "plt.plot(params_x, params_y, linestyle = \"--\", color = \"red\", marker = \"x\")\n",
    "\n",
    "plt.yticks(np.linspace(-1,1,5))\n",
    "plt.xticks(np.linspace(-1,1,5))\n",
    "plt.xlabel(r\"$\\alpha$\", fontsize = 12)\n",
    "plt.ylabel(r\"$\\gamma$\", fontsize = 12)\n",
    "plt.title(\"Loss Landscape\", fontsize = 12)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "--- \n",
    "\n",
    "### Generalization performances"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A very interesting feature of this model, is that it can be straightforwardly applied to graphs having different number of nodes. In fact, until now our analysis focused only on graphs with the same number of nodes for ease of explanation, and there is no actual restriction in this respect. The same machinery works fine for any graph, since the number of QAOA parameters are only dependent on the number of layers in the ansatz, and not on the number of qubits (equal to the number of nodes in the graph) in the quantum circuit. \n",
    "\n",
    "Thus, we might want to challenge our model to learn a good initialization heuristic for a non-specific graph, with an arbitrary number of nodes. For this purpose, let's create a training dataset containing graphs with a different number of nodes $n$, taken in the interval $n \\in [7,9]$ (that is, our dataset now contains graphs having either 7, 8 and 9 nodes)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "cell2 = tf.keras.layers.LSTMCell(2*n_layers)\n",
    "\n",
    "g7 = generate_graphs(5, 7, 3/7)\n",
    "g8 = generate_graphs(5, 8, 3/7)\n",
    "g9 = generate_graphs(5, 9, 3/7)\n",
    "\n",
    "gs = g7+g8+g9\n",
    "gs_cost_list = [qaoa_from_graph(g) for g in gs]\n",
    "\n",
    "# Shuffle the dataset\n",
    "import random\n",
    "random.shuffle(gs_cost_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So far, we created an equally balanced dataset that contains graphs with different number of nodes. We now use this dataset to train the LSTM."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch 1\n",
      " > Graph 1/15 - Loss: [[-2.3892174]]\n",
      " > Graph 6/15 - Loss: [[-2.1072261]]\n",
      " > Graph 11/15 - Loss: [[-1.957976]]\n",
      " >> Mean Loss during epoch: -2.0667606353759767\n",
      "Epoch 2\n",
      " > Graph 1/15 - Loss: [[-2.3797882]]\n",
      " > Graph 6/15 - Loss: [[-2.2293403]]\n",
      " > Graph 11/15 - Loss: [[-1.9649515]]\n",
      " >> Mean Loss during epoch: -2.117209537823995\n",
      "Epoch 3\n",
      " > Graph 1/15 - Loss: [[-2.3686786]]\n",
      " > Graph 6/15 - Loss: [[-2.2524612]]\n",
      " > Graph 11/15 - Loss: [[-1.9757932]]\n",
      " >> Mean Loss during epoch: -2.1220582803090413\n"
     ]
    }
   ],
   "source": [
    "# Select an optimizer \n",
    "opt = tf.keras.optimizers.Adam(learning_rate=0.1)\n",
    "\n",
    "# Set the number of training epochs\n",
    "epochs = 3\n",
    "\n",
    "for epoch in range(epochs):\n",
    "    print(f\"Epoch {epoch+1}\")\n",
    "    total_loss = np.array([])\n",
    "    for i, graph_cost in enumerate(gs_cost_list):\n",
    "        loss = train_step(graph_cost)\n",
    "        total_loss = np.append(total_loss, loss.numpy())\n",
    "        # Log every 5 batches.\n",
    "        if i % 5 == 0:\n",
    "            print(f\" > Graph {i+1}/{len(gs_cost_list)} - Loss: {loss}\")\n",
    "    print(f\" >> Mean Loss during epoch: {np.mean(total_loss)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Generalization performances"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check if this hybrid model eventually learned a good heuristic to propose new updates for the parameters in the QAOA ansatz of the MaxCut problem.  \n",
    "  \n",
    "\n",
    "For this reason, we consider a new graph. In particular, we can take a graph with 10 nodes, which is something that the recurrent network has not seen before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "new_graph = nx.gnp_random_graph(10, p = 3/7)\n",
    "new_cost = qaoa_from_graph(new_graph)\n",
    "\n",
    "nx.draw(new_graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We call the trained recurrent LSTM on this graph, saving not only the last, but all intermediate guesses for the parameters. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "res = recurrent_loop(new_cost, intermediate_steps = True)\n",
    "\n",
    "# Extract all angle suggestions\n",
    "start_zeros = tf.zeros(shape = (2*n_layers, 1))\n",
    "guess_0 = res[0]\n",
    "guess_1 = res[1]\n",
    "guess_2 = res[2]\n",
    "guess_3 = res[3]\n",
    "guess_4 = res[4]\n",
    "final_loss = res[5]\n",
    "\n",
    "# Wrap them into a list\n",
    "guesses = [start_zeros, guess_0, guess_1, guess_2, guess_3, guess_4]\n",
    "\n",
    "# Losses from the hybrid LSTM model\n",
    "lstm_losses = [new_cost(tf.reshape(guess, shape = (2, n_layers))) for guess in guesses]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots()\n",
    "\n",
    "plt.plot(lstm_losses, color = \"blue\", lw = 3, ls = \"-.\", label=\"LSTM\")\n",
    "\n",
    "plt.grid(ls = \"--\", lw = 2, alpha = 0.25)\n",
    "plt.legend()\n",
    "plt.ylabel(\"Cost function\", fontsize = 12)\n",
    "plt.xlabel(\"Iteration\", fontsize = 12)\n",
    "ax.set_xticks([0,5,10,15,20]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See that the custom optimizer based on the LSTM quickly reaches a good value of the loss function, much faster than  standard stochastic gradient descent.  \n",
    "\n",
    "To get the optimized weights of the LSTM use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Trained LSTM weights:\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "[array([[-0.7376077 , -1.1101236 , -1.0129981 , -0.99815595, -1.3686112 ,\n",
       "          1.0585576 ,  0.05369393, -0.00978925],\n",
       "        [ 0.01871599,  0.05814846,  0.08489752,  0.7269866 , -0.00381951,\n",
       "         -0.60114694, -0.49916103, -0.00289286],\n",
       "        [-1.1315999 , -0.44949213, -0.21226467, -0.85746855, -0.1839902 ,\n",
       "          0.73502725, -0.06100825,  1.0624388 ]], dtype=float32),\n",
       " array([[ 0.4672368 ,  0.66579676,  0.10499239,  0.22465926,  0.31523764,\n",
       "         -1.4863725 , -0.8446547 , -0.8977875 ],\n",
       "        [-0.7462862 , -0.5458552 , -0.09516533, -0.35871622, -0.9762555 ,\n",
       "          0.7245814 , -0.16661918,  1.1168702 ]], dtype=float32),\n",
       " array([ 2.8783693 ,  1.0010815 ,  1.5721463 ,  1.6766872 ,  2.834282  ,\n",
       "        -1.7745968 ,  1.1729774 ,  0.32245708], dtype=float32)]"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "optimized_weights = cell.get_weights()\n",
    "print(\"Trained LSTM weights:\\n\")\n",
    "optimized_weights"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To set initial weights for the LSTM cell, use instead: `cell.set_weights(optimized_weights)`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---  \n",
    "\n",
    "### Final remarks  \n",
    "\n",
    "#### Summary\n",
    "In this tutorial we saw how to use a recurrent neural network, an LSTM in particular, as a black-box optimizer to initialize the parameters in a variational quantum circuit close to an optimal solution. In order to do that, we connected MaxCut QAOA quantum circuits built in PennyLane with an LSTM built with TensorFlow, and we used a custom hybrid training routine to optimize the whole network.  \n",
    "\n",
    "Such architecture proved itself to be a good candidate for the initialization problem of Variational Quantum Algorithms, since it reaches good optimal solutions in very few iterations. Besides, the architecture is quite general, since the same machinery can be used for graphs having a generic number of nodes.\n",
    "\n",
    "#### What's next? \n",
    "But the story does not end here. There are multiple ways this work could be improved. Here are a few:  \n",
    "\n",
    "- Use the proposed architecture for VQAs other than QAOA for MaxCut. You can check the paper [[1]](#1) to get some inspiration. \n",
    "- Scale up the simulation, using bigger graphs and longer recurrent loops. \n",
    "- While working correctly, the training routine is quite basic and it could be improved for example by implementing batch learning or a stopping criterion. Also, one could implement the `observed improvement` loss function, as used in the original paper [[1]](#1).\n",
    "- Depending on the problem, you may wish to transform the functions `rnn_iteration` and `recurrent_loop` to actual `Keras Layers` and `Models`. This way, by compiling the model before the training takes place, `TensorFlow` can create the computational graph of the model and train more efficiently. If you're interested, you can find some ideas below to start working on it.  \n",
    "\n",
    "If you have any doubt, or wish to discuss about the project don't hesitate to contact me, I'll be very happy to help you as much as I can 😁  \n",
    "\n",
    "Have a great quantum day!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---  \n",
    "\n",
    "#### Ideas for creating a Keras Layer and Keras Model  \n",
    "\n",
    "Definition of a `Keras Layer` containing a single pass through the LSTM and the Quantum Circuit. That's equivalent to the function `rnn_iteration` from before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "class QRNN(tf.keras.layers.Layer):\n",
    "    def __init__(self, p = 1, graph = None):\n",
    "        super(QRNN, self).__init__()\n",
    "        # p is the number of layers in the QAOA ansatz\n",
    "        self.cell = tf.keras.layers.LSTMCell(2*p)\n",
    "        self.expectation = qaoa_from_graph(graph, n_layers = p)\n",
    "        self.qaoa_p = p\n",
    "\n",
    "    def call(self, inputs):\n",
    "        prev_cost = inputs[0]\n",
    "        prev_params = inputs[1]\n",
    "        prev_h = inputs[2]\n",
    "        prev_c = inputs[3]\n",
    "        \n",
    "        # Concatenate the previous parameters and previous cost to create new input\n",
    "        new_input = tf.keras.layers.concatenate([prev_cost, prev_params])\n",
    "        \n",
    "        # New parameters obtained by the LSTM cell, along with new internal states h and c\n",
    "        new_params, [new_h, new_c] = self.cell(new_input, states = [prev_h, prev_c])\n",
    "                \n",
    "        # This part is used to feed the parameters to the PennyLane function\n",
    "        _params = tf.reshape(new_params, shape = (2, self.qaoa_p))\n",
    "                \n",
    "        # Cost evaluation, and reshaping to be consistent with other Keras tensors\n",
    "        new_cost = tf.reshape(tf.cast(self.expectation(_params), \n",
    "                                      dtype=tf.float32),\n",
    "                              shape = (1,1))\n",
    "    \n",
    "        return [new_cost, new_params, new_h, new_c]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Code for creating an actual `Keras Model` starting from the previous layer definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model: \"functional_1\"\n",
      "__________________________________________________________________________________________________\n",
      "Layer (type)                    Output Shape         Param #     Connected to                     \n",
      "==================================================================================================\n",
      "input_1 (InputLayer)            [(None, 1)]          0                                            \n",
      "__________________________________________________________________________________________________\n",
      "input_2 (InputLayer)            [(None, 2)]          0                                            \n",
      "__________________________________________________________________________________________________\n",
      "input_3 (InputLayer)            [(None, 2)]          0                                            \n",
      "__________________________________________________________________________________________________\n",
      "input_4 (InputLayer)            [(None, 2)]          0                                            \n",
      "__________________________________________________________________________________________________\n",
      "qrnn (QRNN)                     [(1, 1), (None, 2),  48          input_1[0][0]                    \n",
      "                                                                 input_2[0][0]                    \n",
      "                                                                 input_3[0][0]                    \n",
      "                                                                 input_4[0][0]                    \n",
      "                                                                 qrnn[0][0]                       \n",
      "                                                                 qrnn[0][2]                       \n",
      "                                                                 qrnn[0][2]                       \n",
      "                                                                 qrnn[0][3]                       \n",
      "                                                                 qrnn[1][0]                       \n",
      "                                                                 qrnn[1][2]                       \n",
      "                                                                 qrnn[1][2]                       \n",
      "                                                                 qrnn[1][3]                       \n",
      "__________________________________________________________________________________________________\n",
      "tf_op_layer_Mul (TensorFlowOpLa [(1, 1)]             0           qrnn[0][0]                       \n",
      "__________________________________________________________________________________________________\n",
      "tf_op_layer_Mul_1 (TensorFlowOp [(1, 1)]             0           qrnn[1][0]                       \n",
      "__________________________________________________________________________________________________\n",
      "tf_op_layer_Mul_2 (TensorFlowOp [(1, 1)]             0           qrnn[2][0]                       \n",
      "__________________________________________________________________________________________________\n",
      "average_147 (Average)           (1, 1)               0           tf_op_layer_Mul[0][0]            \n",
      "                                                                 tf_op_layer_Mul_1[0][0]          \n",
      "                                                                 tf_op_layer_Mul_2[0][0]          \n",
      "==================================================================================================\n",
      "Total params: 48\n",
      "Trainable params: 48\n",
      "Non-trainable params: 0\n",
      "__________________________________________________________________________________________________\n"
     ]
    }
   ],
   "source": [
    "_graph = nx.gnp_random_graph(7, p = 3/7)\n",
    "\n",
    "# Instantiate the LSTM cells\n",
    "rnn0 = QRNN(graph = _graph)\n",
    "\n",
    "# Create some input layers to feed the data\n",
    "inp_cost = tf.keras.layers.Input(shape = (1,))\n",
    "inp_params = tf.keras.layers.Input(shape = (2,))\n",
    "inp_h = tf.keras.layers.Input(shape = (2,))\n",
    "inp_c = tf.keras.layers.Input(shape = (2,))\n",
    "\n",
    "# Manually creating the recurrent loops. In this case just three iterations are used.\n",
    "out0 = rnn0([inp_cost, inp_params, inp_h, inp_c])\n",
    "out1 = rnn0(out0)\n",
    "out2 = rnn0(out1)\n",
    "\n",
    "# Definition of a loss function driving the training of the LSTM\n",
    "loss = tf.keras.layers.average([0.15 * out0[0], 0.35 * out1[0], 0.5 * out2[0]])\n",
    "\n",
    "# Definition of a Keras Model\n",
    "model = tf.keras.Model(inputs=[inp_cost, inp_params, inp_h, inp_c],\n",
    "                       outputs=[out0[1], out1[1], out2[1], loss])\n",
    "\n",
    "model.summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A basic training routine for the `Keras Model` just created:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Step 1 - Loss = [[-2.014311]] - Cost = [-6.05823489]\n",
      "Step 2 - Loss = [[-2.0410357]] - Cost = [-6.1869224]\n",
      "Step 3 - Loss = [[-2.0691178]] - Cost = [-6.31767668]\n",
      "Step 4 - Loss = [[-2.099209]] - Cost = [-6.45284001]\n",
      "Step 5 - Loss = [[-2.1298494]] - Cost = [-6.58368088]\n",
      "Final Loss: [[-2.1298494]]\n",
      "Final Outs:\n",
      " >Step 1: [[-0.01035318 -0.00192326]]\n",
      " >Step 2: [[-0.06707703  0.19985358]]\n",
      " >Step 3: [[-0.10908641  0.37953332]]\n",
      " >Loss: [[-2.1298494]]\n"
     ]
    }
   ],
   "source": [
    "p = 1\n",
    "\n",
    "inp_costA = tf.zeros(shape = (1, 1))\n",
    "inp_paramsA = tf.zeros(shape = (1, 2*p))\n",
    "inp_hA = tf.zeros(shape = (1, 2*p))\n",
    "inp_cA = tf.zeros(shape = (1, 2*p))\n",
    "\n",
    "inputs = [inp_costA, inp_paramsA, inp_hA, inp_cA]\n",
    "\n",
    "opt = tf.keras.optimizers.Adam(learning_rate=0.01)\n",
    "step = 5\n",
    "\n",
    "for _ in range(step):\n",
    "    with tf.GradientTape() as tape:\n",
    "        pred = model(inputs)\n",
    "        loss = pred[3]\n",
    "            \n",
    "    gradients = tape.gradient(loss, model.trainable_variables)\n",
    "    opt.apply_gradients(zip(gradients, model.trainable_variables))\n",
    "    print(f\"Step {_+1} - Loss = {loss} - Cost = {qaoa_from_graph(_graph, n_layers=p)(np.reshape(pred[2].numpy(),(2, p)))}\")\n",
    "    \n",
    "print(\"Final Loss:\", loss.numpy())\n",
    "print(\"Final Outs:\")\n",
    "for t, s in zip(pred, [\"Step 1\",\"Step 2\",\"Step 3\",\"Loss\"]):\n",
    "    print(f\" >{s}: {t.numpy()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*NOTE:*  \n",
    "This code works only for a single graph at a time, since a graph was needed to create the `QRNN` `Keras Layer` named `rnn0`. Thus, in order to actually train the RNN network for multiple graphs, the above training routine must be modified. Otherwise, you could find a way to define the model to accept as input a whole dataset of graphs, and not just single one. Still, this might prove particularly hard, since `TensorFlow` deals with tensors, and is not able to directly manage other data structures, like graphs or functions taking graphs as input, like `qoao_from_graph`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "#### References\n",
    "<a id=\"1\">[1]</a> \n",
    "Verdon G., Broughton M., McClean J. R., Sung K. J., Babbush R., Jiang Z., Neven H. and Mohseni M. (2019),  \n",
    "Learning to learn with quantum neural networks via classical neural networks, [arXiv:1907.05415](https://arxiv.org/abs/1907.05415).\n",
    "\n",
    "<a id=\"2\">[2]</a> \n",
    "https://pennylane.ai/\n",
    "\n",
    "<a id=\"3\">[3]</a> \n",
    "https://www.tensorflow.org/\n",
    "\n",
    "<a id=\"4\">[4]</a> \n",
    "Cerezo M., Arrasmith A., Babbush R., Benjamin S. C., Endo S., Fujii K., McClean J. R., Mitarai K., Yuan X., Cincio L. and Coles P. J. (2020),  \n",
    "Variational Quantum Algorithms, [arXiv:2012.09265](https://arxiv.org/abs/2012.09265).  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "colab": {
   "name": "l2l_0.ipynb",
   "provenance": []
  },
  "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}