examples/16_FQAOA_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c5de313a",
   "metadata": {},
   "source": [
    "# 16 - Fermionic QAOA (FQAOA)\n",
    "\n",
    "This notebook provides a brief introduction to Fermionic QAOA (FQAOA). \n",
    "It shows how this technique is implemented in the OpenQAOA workflow by solving the constrained quadratic optimization problem, an NP-hard problem.\n",
    "\n",
    "## A brief introduction\n",
    "\n",
    "We present an implementation of a novel algorithm designed for solving combinatorial optimization problems with constraints, utilizing the principles of quantum computing. The algorithm, known as the FQAOA [[1](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.023071)\n",
    ", [2](https://arxiv.org/pdf/2312.04710)]\n",
    ", introduces a significant enhancement over traditional methods by leveraging fermion particle number preservation. This intrinsic property allows the algorithm to enforce constraints naturally throughout the optimization process, addressing a critical challenge in many combinatorial problems.\n",
    "\n",
    "### Key Features\n",
    "- Constraint Handling: In contrast to conventional approaches, which treat constraints as soft constraints in the cost function, FQAOA enforces constraints intrinsically by preserving fermion particle numbers, thereby enhancing the overall performance of the optimization algorithm.\n",
    "\n",
    "- Design of FQAOA Ansatz: In this algorithm,\n",
    "the mixer is designed so that any classical state can be reached by its multiple actions.\n",
    "The initial state is set to a ground state of the mixer Hamiltonian satisfying the constraints of the problem.\n",
    "\n",
    "- Adiabatic Evolution: FQAOA effectively reduces to quantum adiabatic computation in the large limit of circuit depth, $p$, offering improved performance even for shallow circuits by optimizing parameters starting from fixed angles determined by Trotterized quantum adiabatic evolution.\n",
    "\n",
    "- Performance Advantage: Extensive numerical simulations demonstrate that FQAOA offers substantial performance benefits over existing methods, particularly in portfolio optimization problems.\n",
    "\n",
    "- Broad Applicability: The Hamiltonian design guideline benefits QAOA and extends to other algorithms like Grover adaptive search and quantum phase estimation, making it a versatile tool for solving constrained combinatorial optimization problems.\n",
    "\n",
    "This notebook describes the implementation of FQAOA, illustrates its application through an example portfolio optimization problem, and provides insight into FQAOA's superior performance in constrained combinatorial optimization tasks.\n",
    "\n",
    "### Quadratic Constrained Binary Optimization Problems\n",
    "The constrained combinatorial optimization problem for a quadratic binary cost function $C_{\\boldsymbol x}$ can be written in the following form：\n",
    "$${\\boldsymbol x}^* = \\arg \\min_{\\boldsymbol x} C_{\\boldsymbol x}\\qquad {\\rm s.t.} \\quad\\sum_{i=1}^{N} x_i = M,$$\n",
    "with bit string ${\\boldsymbol x}\\in \\{0,1\\}^N$, where ${\\boldsymbol x}^*$ is the optimal solution.\n",
    "This problem can be replaced by the minimum eigenvalue problem in the following steps.\n",
    "\n",
    "1. map the cost function $C_{\\boldsymbol x}$ to the cost Hamiltonian $\\hat{\\cal H}_C$ by $x_i\\rightarrow \\hat{n}_i$:\n",
    "\\begin{eqnarray}\n",
    "C_{\\boldsymbol x} &=& \\sum_i \\mu_i x_{i}+\\sum_{i,j} \\sigma_{i,j} x_{i}x_{j}\n",
    "&\\quad\\mapsto\\quad&\\hat{\\cal H}_C=\\sum_i \\mu_i \\hat{n}_{i}+\\sum_{i,j} \\sigma_{i,j} \\hat{n}_{i_1}\\hat{n}_{i_2},\n",
    "\\end{eqnarray}\n",
    "where $\\hat{n}_i = \\hat{c}^\\dagger_i\\hat{c}_i$ is number operator and $\\hat{c}_i^\\dagger (\\hat{c}_i)$ is creation (annihilation) operator of fermion at $i$-th site.\n",
    "\n",
    "2. formulate eigenvalue problems for combinatorial optimization problem under the constraint:\n",
    "\\begin{eqnarray}\n",
    "\\hat{\\cal H}_C|x_1x_2\\cdots x_N\\rangle &=& C_{\\boldsymbol x}|x_1x_2\\cdots x_N\\rangle,\\\\\n",
    "\\sum_{i=1}^{N} \\hat{n}_i|x_1x_2\\cdots x_N\\rangle &=& M|x_1x_2\\cdots x_N\\rangle,\n",
    "\\end{eqnarray}\n",
    "where $|x_1x_2\\cdots x_N\\rangle=(\\hat{c}^\\dagger_1)^{x_1}(\\hat{c}^\\dagger_2)^{x_2}\\cdots (\\hat{c}^\\dagger_N)^{x_N}|{\\rm vac}\\rangle$ is fermionic basis state and $|\\rm vac\\rangle$ is vacuum satisfying $\\hat{c}_i|\\rm vac\\rangle=0$.\n",
    "\n",
    "3. optimize FQAOA ansatz:\n",
    "$$|\\psi_p({\\boldsymbol \\gamma}^*, {\\boldsymbol \\beta}^*)\\rangle \n",
    "= \\left[\\prod_{j=1}^pU(\\hat{\\cal H}_M,\\beta_j^*){U}(\\hat{\\cal H}_C,\\gamma_j^*)\\right]\\hat{U}_{\\rm init}|{\\rm vac}\\rangle\n",
    "\\qquad {\\rm by}\\quad\n",
    "C_p({\\boldsymbol \\gamma}^*, {\\boldsymbol \\beta}^*)=\\min_{{\\boldsymbol \\gamma}, {\\boldsymbol \\beta}}C_p({\\boldsymbol \\gamma},{\\boldsymbol \\beta}),$$\n",
    "$$\\qquad{\\rm where \\quad}C_p({\\boldsymbol \\gamma}, {\\boldsymbol \\beta}) = \\langle\\psi_p({\\boldsymbol \\gamma}, {\\boldsymbol \\beta})|\\hat{\\cal H}_C|\\psi_p({\\boldsymbol \\gamma}, {\\boldsymbol \\beta})\\rangle.$$\n",
    "The variational parameters $({\\boldsymbol \\gamma}^*, {\\boldsymbol \\beta}^*)$ give the lowest cost value at QAOA level $p$.\n",
    "\n",
    "\n",
    "### One-Dimensional Mixer Hamiltonian\n",
    "\n",
    "The FQAOA implemented on OpenQAOA employs mixer Hamiltonians on one-dimensional lattices. The main features of this computational model are summarized based on the study [[2]](https://arxiv.org/pdf/2312.04710):\n",
    "\n",
    "- Utilises a mixer Hamiltonian on a one-dimensional lattice dedicated to combinatorial optimization problems with equality constraints of the same coefficients.\n",
    "\n",
    "- Reduced Gate Operations: The new mixer Hamiltonian significantly reduces the number of gate operations in quantum circuits compared to previous studies [[1]](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.023071), thus improving computational efficiency.\n",
    "\n",
    "- Noise suppression: as demonstrated in a 16-qubit trapped-ion quantum computer on Amazon Braket, the proposed mixer Hamiltonian effectively suppresses noise and improves algorithm performance.\n",
    "\n",
    "As these features enhance the performance and reliability of FQAOA for solving constrained combinatorial optimization problems, we focus on FQAOA with one-dimensional mixer Hamiltonians.\n",
    "\n",
    "The specific mixer Hamiltonian $\\hat{\\cal H}_M$ on cyclic lattice to be implemented in OpenQAOA are as follow:\n",
    "\n",
    "\\begin{eqnarray}\n",
    "\\hat{\\cal H}_M &=& -t\\sum_{i=1}^{N-1} (\\hat{c}^\\dagger_i\\hat{c}_{i+1}+\\hat{c}^\\dagger_{i+1}\\hat{c}_i)-t(-1)^{M-1}(\\hat{c}^\\dagger_N\\hat{c}_{1}+\\hat{c}^\\dagger_{1}\\hat{c}_N).\n",
    "\\end{eqnarray}\n",
    "These Hamiltonians can be diagonalized as:\n",
    "$$\\hat{\\cal H}_M=\\sum_{i=1}^{N}\\varepsilon_i\\hat{\\gamma}_i^\\dagger\\hat{\\gamma}_i \\qquad {\\rm with} \\quad\n",
    "\\hat{\\gamma}_i^\\dagger = \\sum_{j=1}^N[\\phi_0]_{i,j}\\hat{c}^\\dagger_j,$$\n",
    "where $[\\phi_0]$ is the unitary matrix used for the diagonalization and $\\varepsilon_i$ is eigenvalue.\n",
    "The formulation and validation of the model on cyclic lattice are detailed in the study [[2]](https://arxiv.org/pdf/2312.04710).\n",
    "\n",
    "### Initial State and Mixer for FQAOA\n",
    "\n",
    "We describe the specific calculation model utilized for our implementation of the FQAOA on cyclic lattice. \n",
    "The initial state preparation unitary $\\hat{U}_{\\rm init}$ and the mixer $\\hat{U}_M$ used to implement the FQAOA are shown below.\n",
    "\n",
    "- initial state preparation unitary $\\hat{U}_{\\rm init}$ on cyclic lattice:\n",
    "$$|\\phi_0\\rangle=\\hat{U}_{\\rm init}|{\\rm vac}\\rangle=\\left(\\prod_{i=1}^{M}\\hat{\\gamma}_i^\\dagger\\right)|{\\rm vac}\\rangle,\n",
    "\\qquad{\\rm with}\\quad \\hat{U}_{\\rm init}=\\prod_{i=1}^{M}\\left(\\sum_{j=1}^N[\\phi_0]_{i,j}\\hat{c}^\\dagger_j\\right),$$\n",
    "where $M$ is the number of fermions and $i$ indexes the eigenvalues $\\varepsilon_i$ in ascending order.\n",
    "The implementation of the initial state preparation unitary on quantum circuit are shown in Refs. [[1](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.023071),[2](https://arxiv.org/pdf/2312.04710),[3](https://arxiv.org/pdf/1711.05395)].\n",
    "\n",
    "- mixing unitary $U(\\hat{\\cal H}_M, \\beta)$ on cyclic lattice:\n",
    "\\begin{eqnarray}\n",
    "U(\\hat{\\cal H}_M, \\beta) &\\sim&\n",
    "\\exp\\left[i\\beta t(-1)^{M-1}\\left(\\hat{c}^{\\dagger}_{ND}\\hat{c}_{1}+\\hat{c}^{\\dagger}_{1}\\hat{c}_{ND}\\right)\\right]\\\\&&\\times\n",
    "\\prod_{i\\ {\\rm even}}\\exp\\left[i\\beta t\\left(\\hat{c}^{\\dagger}_i\\hat{c}_{i+1}+\\hat{c}^{\\dagger}_{i+1}\\hat{c}_{i}\\right)\\right]\n",
    "\\prod_{i\\ {\\rm odd}}\\exp\\left[i\\beta t\\left(\\hat{c}^{\\dagger}_i\\hat{c}_{i+1}+\\hat{c}^{\\dagger}_{i+1}\\hat{c}_{i}\\right)\\right],\n",
    "\\end{eqnarray}\n",
    "where the approximation by Trotter decomposition is applied, as certain hopping terms are non-commutative.\n",
    "The implementation of the mixer unitary indicated on the right-hand side on quantum circuits is given in Refs. [[1](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.023071),\n",
    "[2](https://arxiv.org/pdf/2312.04710), [4](https://arxiv.org/pdf/1709.03489), [5](https://arxiv.org/pdf/1904.09314)]."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d3e2b171-0013-4e2e-9801-8a6a58d50370",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib notebook\n",
    "%matplotlib inline\n",
    "\n",
    "# Import the libraries needed to employ the QAOA and FQAOA quantum algorithm using OpenQAOA\n",
    "from openqaoa import FQAOA\n",
    "from openqaoa import QAOA\n",
    "\n",
    "# method to covnert a docplex model to a qubo problem\n",
    "from openqaoa.problems import PortfolioOptimization\n",
    "\n",
    "# Import external libraries to present an manipulate the data\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d47957a-251f-4206-8199-2c551713a754",
   "metadata": {},
   "source": [
    "## Portfolio Optimization\n",
    "\n",
    "In the following, the [portfolio optimization problem](https://en.wikipedia.org/wiki/Portfolio_optimization) is taken as a constrained quadratic optimization problem.\n",
    "Start by creating an instance of the portfolio optimization problem, using the `random_instance` method of the `PortfolioOptimization`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "0efc6710-2cfe-4a0d-bf2f-f9ef3aed2ec5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# create a problem instance for portfolio optimization\n",
    "num_assets = 4 # number of decision variables\n",
    "budget = 2 # constraint on the sum of decision variables\n",
    "problem = PortfolioOptimization.random_instance(num_assets=num_assets, budget=budget).qubo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe2621d4",
   "metadata": {},
   "source": [
    "##  Solving the problem"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f54c48a2",
   "metadata": {},
   "source": [
    "The simplest QAOA and FQAOA workflows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "0ee8df0b-e25d-4f9b-8304-1bdff0acb64b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# conventional QAOA workflow\n",
    "qaoa = QAOA()\n",
    "qaoa.compile(problem = problem)\n",
    "qaoa.optimize()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "11087210-d89c-4b4d-a85a-576a1faad80f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# FQAOA workflow\n",
    "fqaoa = FQAOA()\n",
    "fqaoa.compile(problem = problem, n_fermions = budget)\n",
    "fqaoa.optimize()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5bf46716-6f89-4e00-bbae-cbe8a991055e",
   "metadata": {},
   "source": [
    "## Performance Evaluation of FQAOA\n",
    "To evaluate the performance of FQAOA, we show expectation value of costs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e02d09a9-6c15-4539-accd-c4df75692f74",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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RERE5BWY1BAREZFXYFJDREREXoFJDREREXkFJjVERETkFZjUELmps2fPQpIk81Tq7uDYsWO45ppr4OPjg549e1otI4TAvffei9DQUJfH747vYWNt3boVkiTVWlPHGebPn2/z+hK5MyY1RDbcddddkCQJixcvttj+9ddfQ5IkF0XlWvPmzYO/vz+OHz9usbZLTRs3bsSKFSvw7bffIiMjA926dWuW2O666y5MnDjRYltsbGyzxuCJJEnC119/bbHtiSeesHl9idwZkxqiOvj4+OC1115DXl6eq0NxmIqKika/9vTp0xgyZAji4uIQFhZms0x0dDQGDRqEqKgoKBSKRp+vqeRyuctj8EQBAQE2ry+RO2NSQ1SHUaNGISoqCq+++qrNMtaa6t966y3Ex8ebn5taEV555RVERkYiODgYCxcuRGVlJZ588kmEhoaiTZs2WL58ea3jHzt2DIMGDYKPjw+6deuGbdu2Wew/cuQIxo0bh4CAAERGRuKOO+5Adna2ef+IESMwe/ZsPProowgPD8fYsWOt1sNgMGDhwoVo06YN1Go1evbsiY0bN5r3S5KE/fv3Y+HChZAkCfPnz691jLvuugsPPfQQzp8/D0mSzO9BfHw83nrrLYuyPXv2tDiGJEn4+OOPMWnSJPj5+SEpKQnffPONxWuOHj2KG2+8ERqNBoGBgRg6dChOnz6N+fPnY+XKldiwYQMkSYIkSdi6davV7qdt27ahf//+UKvViI6OxjPPPIPKykqL9+vhhx/GU089hdDQUERFRVmt69U+/vhjdO7cGT4+PujUqRPee+89875Bgwbh6aeftih/5coVKJVKbN++HQDw6aefom/fvggMDERUVBSmTp2KrKwsm+dryOdu7969GD16NMLDwxEUFIThw4fjjz/+MO83lZ00aZLF9br62PV9Nkzv81dffYWRI0fCz88PycnJ2LVrl7nMuXPnMH78eISEhMDf3x9du3bF999/X+d7SmQvJjVEdZDL5XjllVewZMkSXLhwoUnH2rJlCy5duoTt27fjzTffxLx583DjjTciJCQEe/bswf3334/77ruv1nmefPJJPP744/jzzz8xcOBAjB8/Hjk5OQCA/Px8XHvttejVqxf27duHjRs34vLly5g8ebLFMVauXAmVSoXffvsNH3zwgdX43n77bfzf//0f/vnPf+LQoUMYO3Ys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IZ+7pKQkfPrpp0hNTcWePXswbdq0Wi1e8fHx+Pnnn5GZmWlz6gJHfDYeffRRbNq0CWlpafjjjz/wyy+/mJNzIkdhUkNkh4ULF9bqhujcuTPee+89LF26FMnJyfj999+t3hnUWIsXL8bixYuRnJyMHTt24JtvvkF4eDgAmP+C1uv1GDNmDLp3745HH30UwcHBdn9JP/zww5gzZw4ef/xxdO/eHRs3bsQ333yDpKSkJtdh7ty5GD58OG688UbccMMNmDhxIhITE+06RlhYGLZs2YKioiIMHz4cffr0wUcffWTu8pg5cyY6duyIvn37IiIiolbLAgC0bt0a33//PX7//XckJyfj/vvvxz/+8Q88//zzTarfPffcg48//hjLly9H9+7dMXz4cKxYscKipQYwdkEdPHgQQ4cORdu2bc3bIyIisGLFCnzxxRfo0qULFi9ejH/+8591nrMhn7tly5YhLy8PvXv3xh133IGHH34YrVq1sijzf//3f9i8eTNiY2PRq1cvq+dyxGdDr9dj1qxZ6Ny5M66//np06NDB4rZ3IkeQxNWdskREREQeiC01RERE5BWY1BAREZFXYFJDREREXoFJDREREXkFJjVERETkFZjUEBERkVdgUkNERERegUkNEREReQUmNUREROQVmNQQERGRV2BSQ0RERF6BSQ0RERF5hf8HiLxQOiddVJgAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "labels = ['QAOA', 'FQAOA']\n",
    "\n",
    "# plot cost history\n",
    "fig, ax = plt.subplots()\n",
    "for i, result in enumerate([qaoa.result, fqaoa.result]):\n",
    "    result.plot_cost(ax=ax, color=f'C{i}', label=labels[i])\n",
    "ax.grid(True)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "e620d83e-0a6c-433a-af44-1b7a04f0d491",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "optimized expectation values of the cost\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Method</th>\n",
       "      <th>Optimized Cost $\\langle C_{\\boldsymbol x} \\rangle$</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>QAOA</td>\n",
       "      <td>-0.014343</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>FQAOA</td>\n",
       "      <td>-1.675643</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Method  Optimized Cost $\\langle C_{\\boldsymbol x} \\rangle$\n",
       "0   QAOA                                          -0.014343 \n",
       "1  FQAOA                                          -1.675643 "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# evaluate optimized expectation values of the cost\n",
    "exp_cost_dict = {\n",
    "    'Method': labels,\n",
    "    r'Optimized Cost $\\langle C_{\\boldsymbol x} \\rangle$':[qaoa.result.optimized['cost'], fqaoa.result.optimized['cost']]\n",
    "}\n",
    "df = pd.DataFrame(exp_cost_dict)\n",
    "print('optimized expectation values of the cost')\n",
    "display(df)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "6373b123-b0d2-44db-a4d6-5d2ca44185d8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "probabilities of finding the best five optimal solutions\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Bitstring, $\\boldsymbol{x}$</th>\n",
       "      <th>Cost, $C_{\\boldsymbol x}$</th>\n",
       "      <th>QAOA</th>\n",
       "      <th>FQAOA</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1010</td>\n",
       "      <td>-1.797905</td>\n",
       "      <td>0.144896</td>\n",
       "      <td>0.904789</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1100</td>\n",
       "      <td>-0.720493</td>\n",
       "      <td>0.124931</td>\n",
       "      <td>0.015386</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0110</td>\n",
       "      <td>-0.602018</td>\n",
       "      <td>0.122931</td>\n",
       "      <td>0.033298</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>1001</td>\n",
       "      <td>-0.471908</td>\n",
       "      <td>0.120777</td>\n",
       "      <td>0.031587</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>0011</td>\n",
       "      <td>-0.362333</td>\n",
       "      <td>0.119113</td>\n",
       "      <td>0.012593</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Bitstring, $\\boldsymbol{x}$  Cost, $C_{\\boldsymbol x}$      QAOA     FQAOA\n",
       "0                        1010                  -1.797905  0.144896  0.904789\n",
       "1                        1100                  -0.720493  0.124931  0.015386\n",
       "2                        0110                  -0.602018  0.122931  0.033298\n",
       "3                        1001                  -0.471908  0.120777  0.031587\n",
       "4                        0011                  -0.362333  0.119113  0.012593"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Print the best 5 solutions\n",
    "qaoa_lowest5_dict = qaoa.result.lowest_cost_bitstrings(5)\n",
    "fqaoa_lowest5_dict = fqaoa.result.lowest_cost_bitstrings(5)\n",
    "\n",
    "qaoa_dict = {\n",
    "    r'Bitstring, $\\boldsymbol{x}$': qaoa_lowest5_dict['solutions_bitstrings'],\n",
    "    r'Cost, $C_{\\boldsymbol x}$': qaoa_lowest5_dict['bitstrings_energies'],\n",
    "    labels[0]: qaoa_lowest5_dict['probabilities'],\n",
    "    labels[1]: fqaoa_lowest5_dict['probabilities']\n",
    "}\n",
    "df = pd.DataFrame(qaoa_dict)\n",
    "print('probabilities of finding the best five optimal solutions')\n",
    "display(df)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8106c098-1fe7-43ad-b276-8aeeb57f0e7d",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "[1] T. Yoshioka, K. Sasada, Y. Nakano, and K. Fujii, [Phys. Rev. Research 5, 023071 (2023).](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.5.023071), [arXiv:2301.10756 [quant-ph]](https://arxiv.org/pdf/2301.10756).\\\n",
    "[2] T. Yoshioka, K. Sasada, Y. Nakano, and K. Fujii, [2023 IEEE International Conference on Quantum Computing and Engineering (QCE) 1, 300-306 (2023).](https://ieeexplore.ieee.org/document/10313662), [arXiv:2312.04710 [quant-ph]](https://arxiv.org/pdf/2312.04710).\\\n",
    "[3] Z. Jiang, J. S. Kevin, K. Kechedzhi, V. N. Smelyanskiy, and S. Boixo, [Phys. Rev. Appl. 9, 044036 (2018).](https://journals.aps.org/prapplied/abstract/10.1103/PhysRevApplied.9.044036)[arXiv:1711.05395 [quant-ph]](https://arxiv.org/pdf/1711.05395).\\\n",
    "[4] S. Hadfield, Z. Wang, B. O’Gorman, E. G. Rieffel, D. Venturelli, and R. Biswas, [algorithms 12, 34 (2019).](https://www.mdpi.com/1999-4893/12/2/34),[arXiv:1709.03489v2 [quant-ph]](https://arxiv.org/pdf/1709.03489).\\\n",
    "[5] Z. Wang, N. C. Rubin, J. M. Dominy, and E. G. Rioeffel, [Phys. Rev. A 101, 012320 (2020).](https://journals.aps.org/pra/abstract/10.1103/PhysRevA.101.012320),[arXiv:1904.09314v2 [quant-ph]](https://arxiv.org/pdf/1904.09314)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}