TFQ-QAOA-pasqal.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "kKeM2IR1dGN0"
   },
   "source": [
    "##### Copyright 2020 The TensorFlow Quantum Authors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "Z91w8WrIeYQX"
   },
   "source": [
    "# MaxCut QAOA\n",
    "\n",
    "Authors : Michael Streif, David Von Dollen\n",
    "\n",
    "Contributors : Michael Broughton\n",
    "\n",
    "Created : 2019\n",
    "\n",
    "Last updated : 2020-Mar-05"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "NO5t8JWLeaqO"
   },
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tensorflow/quantum/blob/research/qaoa/qaoa.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "7mlhXBELak9p"
   },
   "source": [
    "This notebook shows an example of how to optimize variational parameters for QAOA using TFQ"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "MDDFanHIbDfS"
   },
   "source": [
    "First we must install the required libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "3kQL6cljZyJq"
   },
   "outputs": [],
   "source": [
    "import tensorflow as tf\n",
    "import cirq\n",
    "import tensorflow_quantum as tfq\n",
    "import sympy\n",
    "import numpy as np\n",
    "\n",
    "# visualization tools\n",
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "from cirq.contrib.svg import SVGCircuit\n",
    "#supress warning for matplotlib\n",
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "Xc4ZYqG1aXJu"
   },
   "outputs": [],
   "source": [
    "import networkx as nx\n",
    "import cirq\n",
    "from cirq.pasqal import PasqalNoiseModel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "IxaTUKjkbnaS"
   },
   "source": [
    "We can use QAOA to solve Max-cut. First we need to generate a 3-regular graph with 10 nodes upon which to find the Max-cut using QAOA"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "1J6wZ6zfb0Bi"
   },
   "outputs": [],
   "source": [
    "# generate a 3-regular graph with 8 nodes\n",
    "maxcut_graph = nx.random_regular_graph(n=8,d=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "fM3quBeNcDF5"
   },
   "source": [
    "Let's visualize the graph"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "3GLOTJj6cFqC"
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 576x432 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots(1, 1, figsize=(8, 6));\n",
    "nx.draw_networkx(maxcut_graph, ax=ax)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "XaS5DlNqcJg6"
   },
   "outputs": [],
   "source": [
    "from cirq.pasqal import PasqalVirtualDevice, PasqalDevice\n",
    "\n",
    "p_qubits = cirq.GridQubit.square(3, 3)\n",
    "p_device=PasqalVirtualDevice(control_radius=4, qubits=p_qubits)\n",
    "p_named_device=PasqalDevice(qubits=cirq.NamedQubit.range(9, prefix='q'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "JGgm8N3_c9lu"
   },
   "outputs": [],
   "source": [
    "# create layer of hadamards to initialize the superposition state of all \n",
    "# computational states\n",
    "hadamard_circuit = cirq.Circuit(device=p_device)\n",
    "\n",
    "square_Y = cirq.YPowGate(exponent=0.5)\n",
    "for node in maxcut_graph.nodes():\n",
    "    qubit = p_qubits[node]\n",
    "    hadamard_circuit.append(cirq.H.on(qubit))\n",
    "\n",
    "# define the two parameters for one block of QAOA\n",
    "qaoa_parameters = sympy.symbols('a b')\n",
    "\n",
    "# define the the mixing and the cost Hamiltonian, H_M and H_P\n",
    "mixing_ham = 0\n",
    "for node in maxcut_graph.nodes():\n",
    "    qubit = cirq_qubits[node]\n",
    "    mixing_ham += cirq.PauliString(cirq.X(qubit))\n",
    "\n",
    "cost_ham = maxcut_graph.number_of_edges()/2\n",
    "for edge in maxcut_graph.edges():\n",
    "    qubit1 = cirq_qubits[edge[0]]\n",
    "    qubit2 = cirq_qubits[edge[1]]\n",
    "    cost_ham += cirq.PauliString(1/2*(cirq.Z(qubit1)*cirq.Z(qubit2)))\n",
    "\n",
    "# generate the qaoa circuit\n",
    "qaoa_circuit = tfq.util.exponential(operators = [cost_ham, mixing_ham], \n",
    "                                    coefficients = qaoa_parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "lG52WM2wdPCW"
   },
   "source": [
    "Subsequently, we use these ingredients to build our model. We note here in this case that QAOA has no input data and labels, as we have mapped our graph to the QAOA circuit. To use the TFQ framework we specify the Hadamard circuit as input and convert it to a TFQ tensor. We may then construct a tf.keras model using our QAOA circuit and cost in a TFQ PQC layer, and use a single instance sample for training the variational parameters of the QAOA with the Hadamard gates as an input layer and a target value of $0$ for our loss function. This translates into the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "8dfq7vf4dYRd"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "tensorflow_quantum.python.layers.high_level.pqc.PQC"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# define the model and training data\n",
    "model_circuit, model_readout = qaoa_circuit, cost_ham\n",
    "input_ = [hadamard_circuit]\n",
    "input_ = tfq.convert_to_tensor(input_)\n",
    "optimum = [0]\n",
    "\n",
    "# Build the Keras model.\n",
    "optimum=np.array(optimum)\n",
    "model = tf.keras.Sequential()\n",
    "model.add(tf.keras.layers.Input(shape=(), dtype=tf.dtypes.string))\n",
    "model.add(tfq.layers.PQC(model_circuit, model_readout))\n",
    "tfq.layers.PQC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "QtTxpOCRl1lE"
   },
   "source": [
    "To optimize the parameters of the ansatz state, we use a classical optimization routine. In general, it would be possible to use pre-calculated parameters  or to implement for QAOA tailored optimization routines. For this tutorial, we choose the Adam optimizer implemented in tensorflow. We also choose the mean absolute error as our loss function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "lVo2oeNC0fzs"
   },
   "outputs": [],
   "source": [
    "model.compile(loss=tf.keras.losses.mean_absolute_error,\n",
    "              optimizer=tf.keras.optimizers.Adadelta())\n",
    "    \n",
    "history = model.fit(input_,optimum,epochs=300,verbose=1)\n",
    "\n",
    "# Read out the optimal paramters and sample from the final state 1000 times\n",
    "\n",
    "params = model.trainable_variables\n",
    "add = tfq.layers.AddCircuit()\n",
    "output_circuit = add(input_, append =qaoa_circuit )\n",
    "\n",
    "p_noise_model = PasqalNoiseModel(device=p_named_device)\n",
    "my_sampler = cirq.DensityMatrixSimulator(noise=p_noise_model)\n",
    "\n",
    "sample_layer1 = tfq.layers.Sample(backend=my_sampler)\n",
    "output1 = sample_layer1(output_circuit,  symbol_names=qaoa_parameters, symbol_values = params, repetitions=1000)\n",
    "\n",
    "sample_layer = tfq.layers.Sample()\n",
    "output = sample_layer(output_circuit,  symbol_names=qaoa_parameters, symbol_values = params, repetitions=1000)\n",
    "\n",
    "# Translate output in cut sets\n",
    "cuts_qaoa = []\n",
    "for bit_string in output.values:\n",
    "  temp = []\n",
    "  for pos, bit in enumerate(bit_string):\n",
    "    if bit==1:\n",
    "      temp.append(pos)\n",
    "  cuts_qaoa.append(temp)\n",
    "\n",
    "\n",
    "cuts_qaoa1 = []\n",
    "for bit_string in output1.values:\n",
    "  temp1 = []\n",
    "  for pos, bit in enumerate(bit_string):\n",
    "    if bit==1:\n",
    "      temp1.append(pos)\n",
    "  cuts_qaoa1.append(temp1)\n",
    "#print(cuts_qaoa)\n",
    "#print(cuts_qaoa1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "93R1MoMe6guh"
   },
   "outputs": [],
   "source": [
    "# Generate a list with all possible subsets\n",
    "from itertools import combinations\n",
    "sub_lists = []\n",
    "for i in range(0, len(maxcut_graph.nodes())+1):\n",
    "  temp = [list(x) for x in combinations(maxcut_graph.nodes(), i)]\n",
    "  sub_lists.extend(temp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "9gOoGimx6z2v"
   },
   "outputs": [],
   "source": [
    "# Calculate the cut_size for all possible cuts\n",
    "cut_size = []\n",
    "for sub_list in sub_lists:\n",
    "  cut_size.append(nx.algorithms.cuts.cut_size(maxcut_graph,sub_list))\n",
    "\n",
    "# Calculate the cut_size for the cuts found with QAOA\n",
    "cut_size_qaoa = []\n",
    "for cut in cuts_qaoa:\n",
    "  cut_size_qaoa.append(nx.algorithms.cuts.cut_size(maxcut_graph,cut))\n",
    "\n",
    "\n",
    "cut_size_qaoa1 = []\n",
    "for cut in cuts_qaoa1:\n",
    "  cut_size_qaoa1.append(nx.algorithms.cuts.cut_size(maxcut_graph,cut))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "colab": {},
    "colab_type": "code",
    "id": "nW1uZWrK63PH"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.8289\n",
      "0.6829\n"
     ]
    }
   ],
   "source": [
    "# Calculate the approximation ratio\n",
    "print(np.mean(cut_size_qaoa)/np.max(cut_size))\n",
    "print(np.mean(cut_size_qaoa1)/np.max(cut_size))"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "name": "Copie de TFQ_Example_BasicQAOA.ipynb",
   "provenance": []
  },
  "kernelspec": {
   "display_name": "demo_cirq",
   "language": "python",
   "name": "demo_cirq"
  },
  "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": 1
}