docs/tutorials/3_tutorial_minimum_eigen_optimizer.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Minimum Eigen Optimizer\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About this notebook and the adaptation to Amazon Braket backend\n",
    "The original version of this notebook is accessible at [docs/tutorials/03_minimum_eigen_optimizer.ipynb](https://github.com/qiskit-community/qiskit-optimization/blob/stable/0.6/docs/tutorials/03_minimum_eigen_optimizer.ipynb). The only changes made to the original notebook are contained in the first cell and in cell #6 where we pass the `BackendSampler` object to execute the tasks on Amazon Braket SV1 simulator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:27.376670Z",
     "start_time": "2024-03-06T06:20:22.831320Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit.primitives import BackendSampler\n",
    "from qiskit_braket_provider import BraketProvider\n",
    "\n",
    "sampler = BackendSampler(\n",
    "    backend=BraketProvider().get_backend(\"SV1\"),\n",
    "    options={\"shots\": 1000},\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An interesting class of optimization problems to be addressed by quantum computing are Quadratic Unconstrained Binary Optimization (QUBO) problems.\n",
    "Finding the solution to a QUBO is equivalent to finding the ground state of a corresponding Ising Hamiltonian, which is an important problem not only in optimization, but also in quantum chemistry and physics. For this translation, the binary variables taking values in $\\{0, 1\\}$ are replaced by spin variables taking values in $\\{-1, +1\\}$, which allows one to replace the resulting spin variables by Pauli Z matrices, and thus, an Ising Hamiltonian. For more details on this mapping we refer to [1].\n",
    "\n",
    "Qiskit optimization provides automatic conversion from a suitable `QuadraticProgram` to an Ising Hamiltonian, which then allows leveraging all the `SamplingMinimumEigensolver` implementations, such as\n",
    "\n",
    "- `SamplingVQE`,\n",
    "- `QAOA`, or\n",
    "- `NumpyMinimumEigensolver` (classical exact method).\n",
    "\n",
    "Note 1: `MinimumEigenOptimizer` does not support `qiskit_algorithms.VQE`. But `qiskit_algorithms.SamplingVQE`\n",
    "can be used instead.\n",
    "\n",
    "Note 2: `MinimumEigenOptimizer` can use `NumpyMinimumEigensolver` as an exception case though it inherits `MinimumEigensolver` (not `SamplingMinimumEigensolver`).\n",
    "\n",
    "Qiskit optimization provides a the `MinimumEigenOptimizer` class, which wraps the translation to an Ising Hamiltonian (in Qiskit Terra also called `SparsePauliOp`), the call to a `MinimumEigensolver`, and the translation of the results back to an `OptimizationResult`.\n",
    "\n",
    "In the following we first illustrate the conversion from a `QuadraticProgram` to a `SparsePauliOp` and then show how to use the `MinimumEigenOptimizer` with different `MinimumEigensolver`s to solve a given `QuadraticProgram`.\n",
    "The algorithms in Qiskit optimization automatically try to convert a given problem to the supported problem class if possible, for instance, the `MinimumEigenOptimizer` will automatically translate integer variables to binary variables or add linear equality constraints as a quadratic penalty term to the objective. It should be mentioned that a `QiskitOptimizationError` will be thrown if conversion of a quadratic program with integer variables is attempted.\n",
    "\n",
    "The circuit depth of `QAOA` potentially has to be increased with the problem size, which might be prohibitive for near-term quantum devices.\n",
    "A possible workaround is Recursive QAOA, as introduced in [2].\n",
    "Qiskit optimization generalizes this concept to the `RecursiveMinimumEigenOptimizer`, which is introduced at the end of this tutorial.\n",
    "\n",
    "### References\n",
    "[1] [A. Lucas, *Ising formulations of many NP problems,* Front. Phys., 12 (2014).](https://arxiv.org/abs/1302.5843)\n",
    "\n",
    "[2] [S. Bravyi, A. Kliesch, R. Koenig, E. Tang, *Obstacles to State Preparation and Variational Optimization from Symmetry Protection,* arXiv  preprint arXiv:1910.08980 (2019).](https://arxiv.org/abs/1910.08980)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Converting a QUBO to a SparsePauliOp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.106501Z",
     "start_time": "2024-03-06T06:20:27.379478Z"
    }
   },
   "outputs": [],
   "source": [
    "from qiskit_algorithms.utils import algorithm_globals\n",
    "from qiskit_algorithms import QAOA, NumPyMinimumEigensolver\n",
    "from qiskit_algorithms.optimizers import COBYLA\n",
    "from qiskit_optimization.algorithms import (\n",
    "    MinimumEigenOptimizer,\n",
    "    RecursiveMinimumEigenOptimizer,\n",
    "    SolutionSample,\n",
    "    OptimizationResultStatus,\n",
    ")\n",
    "from qiskit_optimization import QuadraticProgram\n",
    "from qiskit.visualization import plot_histogram\n",
    "from typing import List, Tuple\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.112908Z",
     "start_time": "2024-03-06T06:20:28.107086Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Problem name: \n",
      "\n",
      "Minimize\n",
      "  x*y - x*z + 2*y*z + x - 2*y + 3*z\n",
      "\n",
      "Subject to\n",
      "  No constraints\n",
      "\n",
      "  Binary variables (3)\n",
      "    x y z\n"
     ]
    }
   ],
   "source": [
    "# create a QUBO\n",
    "qubo = QuadraticProgram()\n",
    "qubo.binary_var(\"x\")\n",
    "qubo.binary_var(\"y\")\n",
    "qubo.binary_var(\"z\")\n",
    "qubo.minimize(\n",
    "    linear=[1, -2, 3], quadratic={(\"x\", \"y\"): 1, (\"x\", \"z\"): -1, (\"y\", \"z\"): 2}\n",
    ")\n",
    "print(qubo.prettyprint())"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we translate this QUBO into an Ising operator. This results not only in a `SparsePauliOp` but also in a constant offset to be taken into account to shift the resulting value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.118283Z",
     "start_time": "2024-03-06T06:20:28.114211Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "offset: 1.5\n",
      "operator:\n",
      "SparsePauliOp(['IIZ', 'IZI', 'ZII', 'IZZ', 'ZIZ', 'ZZI'],\n",
      "              coeffs=[-0.5 +0.j,  0.25+0.j, -1.75+0.j,  0.25+0.j, -0.25+0.j,  0.5 +0.j])\n"
     ]
    }
   ],
   "source": [
    "op, offset = qubo.to_ising()\n",
    "print(\"offset: {}\".format(offset))\n",
    "print(\"operator:\")\n",
    "print(op)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes a `QuadraticProgram` might also directly be given in the form of a `SparsePauliOp`. For such cases, Qiskit optimization also provides a translator from a `SparsePauliOp` back to a `QuadraticProgram`, which we illustrate in the following."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.123093Z",
     "start_time": "2024-03-06T06:20:28.119163Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Problem name: \n",
      "\n",
      "Minimize\n",
      "  x0*x1 - x0*x2 + 2*x1*x2 + x0 - 2*x1 + 3*x2\n",
      "\n",
      "Subject to\n",
      "  No constraints\n",
      "\n",
      "  Binary variables (3)\n",
      "    x0 x1 x2\n"
     ]
    }
   ],
   "source": [
    "qp = QuadraticProgram()\n",
    "qp.from_ising(op, offset, linear=True)\n",
    "print(qp.prettyprint())"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This translator allows, for instance, one to translate a `SparsePauliOp` to a `QuadraticProgram` and then solve the problem with other algorithms that are not based on the Ising Hamiltonian representation, such as the `GroverOptimizer`."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Solving a QUBO with the MinimumEigenOptimizer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by initializing the `MinimumEigensolver` we want to use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.126319Z",
     "start_time": "2024-03-06T06:20:28.123842Z"
    }
   },
   "outputs": [],
   "source": [
    "algorithm_globals.random_seed = 10598\n",
    "qaoa_mes = QAOA(sampler=sampler, optimizer=COBYLA(), initial_point=[0.0, 0.0])\n",
    "exact_mes = NumPyMinimumEigensolver()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we use the `MinimumEigensolver` to create `MinimumEigenOptimizer`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.129084Z",
     "start_time": "2024-03-06T06:20:28.127160Z"
    }
   },
   "outputs": [],
   "source": [
    "qaoa = MinimumEigenOptimizer(qaoa_mes)  # using QAOA\n",
    "exact = MinimumEigenOptimizer(\n",
    "    exact_mes\n",
    ")  # using the exact classical numpy minimum eigen solver"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We first use the `MinimumEigenOptimizer` based on the classical exact `NumPyMinimumEigensolver` to get the optimal benchmark solution for this small example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:20:28.140826Z",
     "start_time": "2024-03-06T06:20:28.129858Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "objective function value: -2.0\n",
      "variable values: x=0.0, y=1.0, z=0.0\n",
      "status: SUCCESS\n"
     ]
    }
   ],
   "source": [
    "exact_result = exact.solve(qubo)\n",
    "print(exact_result.prettyprint())"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we apply the `MinimumEigenOptimizer` based on `QAOA` to the same problem."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.762902Z",
     "start_time": "2024-03-06T06:20:28.141722Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/caw/Documents/GitHub/qiskit-braket-provider/qiskit_braket_provider/providers/adapter.py:438: UserWarning: The Qiskit circuit contains barrier instructions that are ignored.\n",
      "  warnings.warn(\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "objective function value: -2.0\n",
      "variable values: x=0.0, y=1.0, z=0.0\n",
      "status: SUCCESS\n"
     ]
    }
   ],
   "source": [
    "qaoa_result = qaoa.solve(qubo)\n",
    "print(qaoa_result.prettyprint())"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Analysis of Samples\n",
    "`OptimizationResult` provides useful information in the form of `SolutionSample`s (here denoted as *samples*). Each `SolutionSample` contains\n",
    "information about the input values (`x`), the corresponding objective function value (`fval`), the fraction of samples corresponding to that input (`probability`),\n",
    "and the solution `status` (`SUCCESS`, `FAILURE`, `INFEASIBLE`). Multiple samples corresponding to the same input are consolidated into a single `SolutionSample` (with its `probability` attribute being the aggregate fraction of samples represented by that `SolutionSample`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.769958Z",
     "start_time": "2024-03-06T06:22:25.766296Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "variable order: ['x', 'y', 'z']\n",
      "SolutionSample(x=array([0., 1., 0.]), fval=-2.0, probability=0.446, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 1., 0.]), fval=0.0, probability=0.141, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 0., 0.]), fval=0.0, probability=0.24, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 0., 0.]), fval=1.0, probability=0.093, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 0., 1.]), fval=3.0, probability=0.02, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 1., 1.]), fval=3.0, probability=0.042, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 0., 1.]), fval=3.0, probability=0.018, status=<OptimizationResultStatus.SUCCESS: 0>)\n"
     ]
    }
   ],
   "source": [
    "print(\"variable order:\", [var.name for var in qaoa_result.variables])\n",
    "for s in qaoa_result.samples:\n",
    "    print(s)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We may also want to filter samples according to their status or probabilities."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.774975Z",
     "start_time": "2024-03-06T06:22:25.771471Z"
    }
   },
   "outputs": [],
   "source": [
    "def get_filtered_samples(\n",
    "    samples: List[SolutionSample],\n",
    "    threshold: float = 0,\n",
    "    allowed_status: Tuple[OptimizationResultStatus] = (\n",
    "        OptimizationResultStatus.SUCCESS,\n",
    "    ),\n",
    "):\n",
    "    res = []\n",
    "    for s in samples:\n",
    "        if s.status in allowed_status and s.probability > threshold:\n",
    "            res.append(s)\n",
    "\n",
    "    return res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.778731Z",
     "start_time": "2024-03-06T06:22:25.775933Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SolutionSample(x=array([0., 1., 0.]), fval=-2.0, probability=0.446, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 1., 0.]), fval=0.0, probability=0.141, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 0., 0.]), fval=0.0, probability=0.24, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 0., 0.]), fval=1.0, probability=0.093, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([1., 0., 1.]), fval=3.0, probability=0.02, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 1., 1.]), fval=3.0, probability=0.042, status=<OptimizationResultStatus.SUCCESS: 0>)\n",
      "SolutionSample(x=array([0., 0., 1.]), fval=3.0, probability=0.018, status=<OptimizationResultStatus.SUCCESS: 0>)\n"
     ]
    }
   ],
   "source": [
    "filtered_samples = get_filtered_samples(\n",
    "    qaoa_result.samples,\n",
    "    threshold=0.005,\n",
    "    allowed_status=(OptimizationResultStatus.SUCCESS,),\n",
    ")\n",
    "for s in filtered_samples:\n",
    "    print(s)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to obtain a better perspective of the results, statistics is very helpful, both with respect to\n",
    "the objective function values and their respective probabilities. Thus, mean and standard deviation are the very\n",
    "basics for understanding the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.782108Z",
     "start_time": "2024-03-06T06:22:25.780115Z"
    }
   },
   "outputs": [],
   "source": [
    "fvals = [s.fval for s in qaoa_result.samples]\n",
    "probabilities = [s.probability for s in qaoa_result.samples]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.786833Z",
     "start_time": "2024-03-06T06:22:25.782986Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "1.1428571428571428"
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.mean(fvals)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.790398Z",
     "start_time": "2024-03-06T06:22:25.787811Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "1.8070158058105026"
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.std(fvals)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, despite all the number-crunching, visualization is usually the best early-analysis approach."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:25.794232Z",
     "start_time": "2024-03-06T06:22:25.791390Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "{'x=0 y=1 z=0': 0.446,\n 'x=1 y=1 z=0': 0.141,\n 'x=0 y=0 z=0': 0.24,\n 'x=1 y=0 z=0': 0.093,\n 'x=1 y=0 z=1': 0.02,\n 'x=0 y=1 z=1': 0.042,\n 'x=0 y=0 z=1': 0.018}"
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "samples_for_plot = {\n",
    "    \" \".join(\n",
    "        f\"{qaoa_result.variables[i].name}={int(v)}\" for i, v in enumerate(s.x)\n",
    "    ): s.probability\n",
    "    for s in filtered_samples\n",
    "}\n",
    "samples_for_plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:26.203433Z",
     "start_time": "2024-03-06T06:22:25.795208Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "<Figure size 700x500 with 1 Axes>",
      "image/png": "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x8xptVq0atUKly5dwsGDB9G+fXsAQH5+PsLDw5GWloYTJ04Yz07Nzs5GdnY2/Pz84OfnV+b2LT1m7mGGn3fL+t2ayJE56jFz0VPt3QMiIsdjae3hcD+zajQarFq1Cnq9HhEREZgwYQKmT5+Oxx9/HCdOnMDcuXNNLjOydOlStGnTBkuXLrVjr4mIiIjsw+F+ZgXunx68f/9+REVFYdOmTSgsLETbtm2xYMECDB061N7dIyIiInIYDvczq6Piz6xUFfBnViIi9VDtz6xEREREZDkWc0REREQqxmKOiIiISMVYzBERERGpGIs5IiIiIhVjMUdERESkYizmiIiIiFSMxRwRERGRirGYIyIiIlIxFnNEREREKsZijoiIiEjFWMwRERERqRiLOSIiIiIVYzFHREREpGIs5oiIiIhUjMUcERERkYqxmCMiIiJSMRZzRERERCrGYo6IiIhIxVjMEREREakYizkiIiIiFWMxR0RERKRiLOaIiIiIVIzFHBEREZGKsZgjIiIiUjEWc0REREQqxmKOiIiISMVYzBERERGpGIs5IiIiIhVjMUdERESkYizmiIiIiFSMxRwRERGRirGYIyIiIlIxq4u5kJAQLF++HHl5ebbsDxERERFJsLqYO3nyJF577TXUr18fo0aNwv79+23ZLyIiIiKygNXF3JUrV/CPf/wDzZs3x7p169ClSxe0adMGH3/8MbKzs23ZRyIiIiIqgdXFXK1atTBlyhQcPXoUhw4dwvjx45GVlYXp06ejUaNGGDRoEGJjY23ZVyIiIiJ6iE1OgAgLC8OKFSuQlZWFNWvWoGPHjvjXv/6FXr16ITg4GO+99x6ysrJs8VRERERE9ACbns3q6emJ559/HgMGDECDBg0ghMC5c+cwZ84cNGnSBK+99hru3Lljy6ckIiIicmo2K+Z27dqFwYMHo2HDhpg+fTr0ej1mzpyJtLQ0bNiwwXj262uvvWarpyQiIiJyepryPPjy5ctYs2YN1q5di8zMTABAjx49MGHCBPTr1w+urq4AgBYtWuCll15C37598f3335e700RERER0n9XFXN++fbFjxw7odDoEBATgnXfewfjx49GkSZMSH9OpUyfExMRY+5RERERE9BCri7lt27aZzMJpNGVvqm/fvmjQoIG1T0lERERED7G6mMvIyEBwcLDUY9q1a4d27dpZ+5RERERE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Rg3JURMRERE5Fot/Z3zwlFkAGDx4sPF2W2+88QY6d+5sPAEiMTERn376KcLDw/HSSy9Jd6pbt27Yv38/oqKisGnTJhQWFqJt27ZYsGABhg4datE25s2bhx07dmD//v24fv06FEVB48aNMW7cOEydOhVt27aV7hcRERGRo5G+N+vDhBAlthseZ+lF7xwZz2alqoBnsxIRqYfN7806YsQIqevFEREREVHFs7iY+/LLLyuwG0RERERkDce9WSMRERERlYnFHBEREZGKleuqufn5+Vi6dCl27dqFy5cvm71fqqIoyMjIKM/TEBEREVEJrC7mrl+/jk6dOiEjIwPe3t7GMy4KCwtx9+5dAECDBg3g5uZms84SERERkSmrf2adO3cuMjIysG7dOty8eRMA8Oabb+L27dv46aef0LFjRzRp0gQnTpywWWeJiIiIyJTVxVxMTAy6d++OYcOGFbtkSYcOHbB9+3ZkZmZi7ty55e0jEREREZXA6mIuKysLISEhxr9dXV2NP68CgK+vL3r16oV//etf5eshEREREZXI6mLOx8cHRUVFxr99fX1x8eJFk3W8vb1LvHcrEREREZWf1cVc06ZNkZmZafw7JCQEcXFxuHHjBgDg7t27+O9//4vAwMByd5KIiIiIzLO6mIuMjMTu3btx584dAMArr7yCa9eu4fHHH8eLL76Idu3aISMjA6NGjbJVX4mIiIjoIVYXcxMnTkR0dLSxmPvzn/+MDz/8EL///js2b96MK1euYNq0afjrX/9qs84SERERkSlFCCFsuUGdTofs7GzUrVu32Fmuama4jl5ubi68vb3t3R0iq4xfYu8emBc91d49ICJyPJbWHuW6A4Q5rq6uCAgIsPVmiYiIiMiMchdzt2/fxvfff4/U1FTk5ubCx8cH7du3R79+/VCjRg1b9JGIiIiISmD1MXMA8O233yIwMBDDhw/H4sWLER0djcWLF2P48OEIDAzEhg0bbNVPp7ds2TIEBwfDw8MDoaGhSExMLHHdLVu2oEePHvD394e3tzfCw8Oxc+fOEtffsGEDFEVB//79K6DnREREVJGsLub++9//YtiwYbh37x4mTZqEDRs2YO/evdiwYQNeffVV3Lt3D8OGDcO2bdts2V+ntHHjRkydOhWzZs1CSkoKIiIi0KtXL5w/f97s+gkJCejRowdiYmKQnJyMbt26oW/f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qKenZ4nXbWvbti3atm1bns0TERERURkc987bRERERFSmcs3M6XQ6bNq0Cbt27cLly5fN3i9VURTjT7FEREREZFtWF3O3b99GZGQkDh48CCEEFEUxOYPU8PeDZ7cSERERkW1Z/TPrwoULkZSUhHnz5iE7OxtCCMydOxdZWVnYuHEjgoODMXDgQLOzdURERERkG1YXc1u2bMFTTz2F2bNno3bt2sb2gIAAvPjii4iPj8fu3bul781KRERERJazupg7f/48nnrqqT825OJiMgvXqFEj9OnTB1999VX5ekhEREREJbK6mKtRowZcXP54uI+PD7KyskzWqVevHs6fP29974iIiIioVFYXc0FBQSaFWrt27bBnzx7j7JwQArt370b9+vXL30siIiIiMsvqYq579+7Yu3cvtFotAGDkyJE4f/48wsPD8de//hWdO3dGamoqXnjhBZt1loiIiIhMWX1pkvHjx6NOnTq4fv066tevjzFjxiAlJQXLli1DamoqAOCFF17A3LlzbdRVIiIiInqY1cVcixYt8Pbbb5u0ffbZZ3j33Xdx5swZBAUFoV69euXuIBERERGVrFx3gDDH398f/v7+tt4sEREREZnBe7MSERERqZjVM3NNmza1aD1FUZCRkWHt0xARERFRKawu5vR6vdn7rubm5uLWrVsAgPr168Pd3d3qzhERERFR6awu5jIzM0tdNm3aNFy9ehVxcXHWPgURERERlaFCjplr0qQJNm7ciJs3b2LWrFkV8RRERETkZJYtW4bg4GB4eHggNDQUiYmJJa6blZWFIUOGoFWrVnBxccHUqVNL3faGDRugKAr69+9v0p6QkIC+ffuiQYMGUBQF3333XfkHYmMVdgKEm5sbevTogU2bNlXUUxAREZGT2LhxI6ZOnYpZs2YhJSUFERER6NWrV4m3DS0oKIC/vz9mzZqFxx9/vNRtnzt3DtOnT0dERESxZbdv38bjjz+OpUuX2mQcFaFCz2a9c+cObty4UZFPQURERE7g448/xtixYzFu3Di0adMGS5YsQePGjbF8+XKz6zdp0gSffPIJRowYAR8fnxK3q9PpMHToUMybN8/syZ29evXCwoUL8ec//9lmY7G1CivmEhIS8O2336JVq1YV9RRERETkBAoLC5GcnIzIyEiT9sjISPz444/l2vb8+fPh7++PsWPHlms79mT1CRDPPPOM2XatVotLly4hMzMTQgjMnj3b6s4RERERZWdnQ6fTISAgwKQ9ICAAV65csXq7Bw4cwOrVq423IVUrq4u5+Ph4s+2KosDX1xc9evTAm2++iZ49e1r7FERERERGD18STQhh9jJplsjPz8ewYcMQHR0NPz8/W3TPbsp1nTkiIiKiiubn5wdXV9dis3DXrl0rNltnqYyMDGRmZqJv377GNkNto9FokJaWhmbNmlnf6UpU7nuzXrt2DZcuXYJer0fDhg1Rr149W/SLiIiICADg7u6O0NBQxMXFYcCAAcb2uLg49OvXz6pttm7dGsePHzdpmz17NvLz8/HJJ5+gcePG5epzZbKqmCsoKMCnn36K6OjoYrfq8vX1xfDhw/HGG2+gSZMmtugjEREROblp06Zh+PDhCAsLQ3h4OFauXInz589j4sSJAIAZM2bg0qVLWLdunfExhmPhfv/9d1y/fh2pqalwd3fHI488Ag8PD7Rr187kOWrVqgUAJu2///47Tp8+bfz77NmzSE1NRe3atREYGFhBo5UjXcxduHABffr0wYkTJyCEQIMGDdC4cWMIIXDx4kVcvnwZn3zyCb7++mts2LABzz77LADg8uXL2L9/P1566SWbD4KIiIiqtkGDBiEnJwfz589HVlYW2rVrh5iYGAQFBQG4f5Hgh685FxISYvzv5ORkrF+/HkFBQaXexephR44cQbdu3Yx/T5s2DQAwcuRIfPnll9YPyIYUIYSwdOWioiI88cQTOHHiBIYMGYI5c+YUu/RIWloaFi5ciG+++Qaenp745ZdfoNPpEBkZiVGjRuHdd9+1+SAqQ15eHnx8fJCbmwtvb+8Ke57xSyps0+USPdXePSBb4P5FRKQeltYeUjNzX3zxBU6cOIGoqChERUWZXadVq1b4+uuv0bJlS0RFRWHIkCHIzMzEjRs3EBoaKjcKIiIiIiqV1EWDN23ahObNm1s0uzZ79my0aNECP/30EwoLC7Fjxw706dPH6o4SERERUXFSxdyvv/6KyMhIi67poiiKcd2ffvrJ5PdmIiIiIrINqWLu999/L/X+Zg/z9vaGRqNB8+bNpTtGRERERGWTKubq1q1rcnpuWTIyMlC3bl3pThERERGRZaSKufDwcGzfvt2i+6BduXIF27ZtQ+fOna3uHBERERGVTqqYmzhxIn7//XcMGDAA2dnZJa6Xk5ODAQMG4M6dO3jllVfK3UkiIiIiMk/q0iTdunXD+PHjER0djTZt2uCVV17BM888Y7zlxYULF7B7925ER0cjOzsbEyZMQNeuXSui30REROQkeI3M0knfAWLZsmXw9vbGP/7xDyxatAiLFi0yWS6EgIuLC6ZPn15sGRERERHZlnQx5+rqig8//BCvvPIK1q5di6SkJOMxdPXq1UOnTp0watQonsFKREREVAmkizmD5s2b47333rNlX4iIiIhIktQJEERERETkWFjMEREREakYizkiIiIiFWMxR0RERKRiLOaIiIiIVIzFHBEREZGKsZgjIiIiUjEWc0REREQqxmKOiIiISMVYzBERERGpGIs5IiIiIhVjMUdERESkYizmiIiIiFSMxRwRERGRirGYIyIiIlIxFnNEREREKsZijoiIiEjFWMwREZHNLFu2DMHBwfDw8EBoaCgSExNLXX/fvn0IDQ2Fh4cHmjZtihUrVpgsLyoqwvz589GsWTN4eHjg8ccfx44dO0zWWb58OR577DF4e3vD29sb4eHh2L59u83HRuSoWMwREZFNbNy4EVOnTsWsWbOQkpKCiIgI9OrVC+fPnze7/tmzZ9G7d29EREQgJSUFM2fOxJQpU7B582bjOrNnz8YXX3yBzz77DL/++ismTpyIAQMGICUlxbhOo0aN8Le//Q1HjhzBkSNH8Mwzz6Bfv344ceJEhY+ZyBEoQghh706oQV5eHnx8fJCbmwtvb+8Ke57xSyps0+USPdXePSBb4P5FFenJJ5/EE088geXLlxvb2rRpg/79+2PRokXF1n/77bexdetWnDx50tg2ceJEHD16FElJSQCABg0aYNasWZg8ebJxnf79+6NmzZr45z//WWJfateujQ8//BBjx461xdDIzpz1s8vS2oMzc0REVG6FhYVITk5GZGSkSXtkZCR+/PFHs49JSkoqtn7Pnj1x5MgRFBUVAQAKCgrg4eFhso6npyf2799vdps6nQ4bNmzA7du3ER4ebu1wiFSFxRwREZVbdnY2dDodAgICTNoDAgJw5coVs4+5cuWK2fW1Wi2ys7MB3C/uPv74Y6Snp0Ov1yMuLg7ff/89srKyTB53/Phx1KxZE9WqVcPEiRPxn//8B4888ogNR0jkuBy2mDt8+DB69+4NX19f1KhRAx07dsT69estfvy1a9ewaNEiDBw4EMHBwVAU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\n"
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plot_histogram(samples_for_plot)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## RecursiveMinimumEigenOptimizer"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `RecursiveMinimumEigenOptimizer` takes a `MinimumEigenOptimizer` as input and applies the recursive optimization scheme to reduce the size of the problem one variable at a time.\n",
    "Once the size of the generated intermediate problem is below a given threshold (`min_num_vars`), the `RecursiveMinimumEigenOptimizer` uses another solver (`min_num_vars_optimizer`), e.g., an exact classical solver such as CPLEX or the `MinimumEigenOptimizer` based on the `NumPyMinimumEigensolver`.\n",
    "\n",
    "In the following, we show how to use the `RecursiveMinimumEigenOptimizer` using the two `MinimumEigenOptimizer`s introduced before."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we construct the `RecursiveMinimumEigenOptimizer` such that it reduces the problem size from 3 variables to 1 variable and then uses the exact solver for the last variable. Then we call `solve` to optimize the considered problem."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:22:26.241480Z",
     "start_time": "2024-03-06T06:22:26.206441Z"
    }
   },
   "outputs": [],
   "source": [
    "rqaoa = RecursiveMinimumEigenOptimizer(\n",
    "    qaoa, min_num_vars=1, min_num_vars_optimizer=exact\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:26:28.859824Z",
     "start_time": "2024-03-06T06:22:26.245339Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/caw/Documents/GitHub/qiskit-braket-provider/qiskit_braket_provider/providers/adapter.py:438: UserWarning: The Qiskit circuit contains barrier instructions that are ignored.\n",
      "  warnings.warn(\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "objective function value: -2.0\n",
      "variable values: x=0.0, y=1.0, z=0.0\n",
      "status: SUCCESS\n"
     ]
    }
   ],
   "source": [
    "rqaoa_result = rqaoa.solve(qubo)\n",
    "print(rqaoa_result.prettyprint())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:26:28.862915Z",
     "start_time": "2024-03-06T06:26:28.860735Z"
    }
   },
   "outputs": [],
   "source": [
    "filtered_samples = get_filtered_samples(\n",
    "    rqaoa_result.samples,\n",
    "    threshold=0.005,\n",
    "    allowed_status=(OptimizationResultStatus.SUCCESS,),\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:26:28.866284Z",
     "start_time": "2024-03-06T06:26:28.863663Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "{'x=0 y=1 z=0': 1.0}"
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "samples_for_plot = {\n",
    "    \" \".join(\n",
    "        f\"{rqaoa_result.variables[i].name}={int(v)}\" for i, v in enumerate(s.x)\n",
    "    ): s.probability\n",
    "    for s in filtered_samples\n",
    "}\n",
    "samples_for_plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-03-06T06:26:28.910451Z",
     "start_time": "2024-03-06T06:26:28.867042Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": "<Figure size 700x500 with 1 Axes>",
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAoAAAAIgCAYAAAAV0djNAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy88F64QAAAACXBIWXMAAA9hAAAPYQGoP6dpAABHDklEQVR4nO3deVyVdf7//+c5HEUlOeKGuCCaW1oqaY6SiEvCpDlNy5RLi2O5TFN9rLEabVGyGb/TOuPYNjqa5TBp6UyLabgEhOFWkeUWkoCAmscFUBI4y+8Pf+eMBCgcDnLwetxvN27TeV/XeV+vy+ZGT9/v6/2+TC6XyyUAAAAYhrm+CwAAAMClRQAEAAAwGAIgAACAwRAAAQAADIYACAAAYDAEQAAAAIMhAAIAABgMARAAAMBgLPVdwOXM6XQqPz9fzZs3l8lkqu9yAADAZczlcqmoqEjt27eX2XzhMT4CYB3Kz89Xp06d6rsMAABgIIcOHVLHjh0veA4BsA41b95c0rl/EcHBwfVcDQAAuJwVFhaqU6dOnvxxIQTAOuSe9g0ODiYAAgCAS6I6j52xCAQAAMBgCIAAcAmlpKRo3Lhxat++vUwmk/773/9e9DvJyckaMGCAmjRpoq5du+qNN96o+0IBXNYIgABwCZ05c0b9+vXTokWLqnX+wYMHNWbMGEVHR+vrr7/WnDlz9PDDD2v16tV1XCmAyxnPAALAJXTjjTfqxhtvrPb5b7zxhsLDw/XXv/5VknTVVVdp586devHFF3XbbbfVUZUALneMAAKAH0tLS1NsbGy5tri4OO3cuVNlZWX1VBWAho4ACAB+7MiRIwoNDS3XFhoaKrvdLpvNVk9VAWjoCIAA4Od+vqWDy+WqtB0AqosACAB+rF27djpy5Ei5th9//FEWi0WtWrWqp6oANHQEQADwY0OGDNGGDRvKtSUmJmrgwIFq1KhRPVUFoKEjAALAJXT69Gmlp6crPT1d0rltXtLT05WTkyNJmj17tu655x7P+TNmzFB2drYeffRR7d27V0uXLtU///lPzZo1qz7KB3CZYBsYALiEdu7cqREjRng+P/roo5Kke++9V2+99ZYOHz7sCYOS1KVLF33yySd65JFH9Oqrr6p9+/ZauHAhW8AAqBWTy/00MXyusLBQVqtVBQUFvAsYAADUqZrkDqaAAQAADIYACAAAYDAEQAAAAIMhAAIAABgMARAAAMBgCIAAAAAGQwAEAAAwGAIgAACAwRAAAQAADIYACAAAYDAEQAAAAIMhAAIAABgMARAAAMBg/DIArlixQtOnT9fAgQMVGBgok8mkt956q8b9OJ1OLVq0SH379lXTpk3Vpk0b3XHHHcrIyKjyOzt27NCYMWMUEhKioKAgDRo0SAkJCbW4GwAAAP9iqe8CKvPUU08pOztbrVu3VlhYmLKzs73qZ8aMGVq8eLF69+6thx56SEePHtXKlSuVmJioL774Qr179y53flJSkuLi4tS4cWONHz9eVqtVa9as0aRJk5SVlaU5c+b44vYAAADqlV+OAC5ZskRZWVk6duyYZsyY4VUfn332mRYvXqzo6Gh99dVXev7557V8+XKtXbtWhYWF+t3vflfufLvdrvvvv18mk0kpKSlavHixXnzxRX3zzTfq06eP5s6de8GRQwAAgIbCLwPgDTfcoM6dO9eqj8WLF0uSnnvuOQUGBnraR40apbi4OKWkpOj777/3tG/evFmZmZmaOHGiIiMjPe3NmzfX008/LbvdrmXLltWqJgAAAH/glwHQF5KSkhQUFKTrr7++wrG4uDhJUnJycrnzJSk2NrbC+e62888HAABoqC7LAHjmzBkdPnxYXbp0UUBAQIXj3bt3l6RyU7ruf3YfO19ISIhat27NFDAAALgs+OUikNoqKCiQJFmt1kqPBwcHlzuvut/Jzc294HVLSkpUUlLi+VxYWChJKisrU1lZmSTJbDYrICBADodDTqfTc6673W63y+VyedoDAgJkNpurbHf362axnPtXarfbq9XeqFEjOZ1OORwOT5vJZJLFYqmyvarauSfuiXvinrgn7ol7qr97qonLMgDWlwULFig+Pr5Ce2Jiopo1ayZJCg8PV2RkpHbt2qWcnBzPOT179lSvXr20fft2HTt2zNPev39/de7cWSkpKSoqKvK0DxkyRG3bttUDrzaqopqatJtV+WBwVe0B//9Pddur+r9ZVe3cE/fEPXFPF2rnnrinhnlPi2dKNptNaWlpnrbmzZtr5MiROnTokNLT0z3tbdq0UVRUlDIyMrR//35P+4VyRPv27auoo6LLMgC6R/HOH+E7n3tk7vzRvup8p6rRQbfZs2fr0UcfLfedTp06KTY21jPq6E7offv21dVXX+05190+aNCgCn/rkKRhw4ZV2g4A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Ka8DoNVqVVlZmedzSEiIcnNzy50THBxc5buCAQAAUD+8DoBdu3ZVVlaW53NkZKQ2bNigEydOSJJ++uknffTRRwoPD691kQAAAPAdrwNgbGysNm3apOLiYknS9OnT9eOPP6pfv376zW9+o6uvvlqZmZmaPHmyr2oFAACAD3gdAGfMmKHFixd7AuCtt96qF154QadPn9bq1at15MgRPfroo3rsscd8ViwAAABqz+RyuVy+7NDhcMhms6lt27YVVgcbjXtvxIKCAgUHB9fJNab+tU66BQAAPrZ4Zt32X5PcUas3gVQmICBAoaGhvu4WAAAAPlLrAHjmzBl98MEHSk9PV0FBgaxWq/r376+bb75ZQUFBvqgRAAAAPlSrAPjvf/9bDz74oE6dOqXzZ5JNJpNatGihV199VePHj691kQAAAPAdrwPgRx99pLvuuktNmjTRAw88oOjoaIWGhuro0aNKSUnRsmXLdNddd6l58+YaO3asL2sGAABALXi9COQXv/iF9u/fr+3bt6tHjx4Vju/bt0+/+MUvdNVVV2nr1q21LrQhYhEIAABw86dFIF5vA/Ptt99q/PjxlYY/SerVq5fGjx+vXbt2eXsJAAAA1AGvA2BwcLBatGhxwXNatGghq9Xq7SUAAABQB7wOgOPGjdPHH38sh8NR6XG73a61a9fqV7/6ldfFAQAAwPe8DoAvvPCCmjRpohtvvFHbtm0rd2zr1q268cYb1bRpU/3lL3+pdZEAAADwnWqvAu7atWuFttLSUn399dfatGmTGjVqpFatWun48eMqKyuTJIWFhWnAgAHKzMz0XcUAAAColWoHQKfTWeHVbo0aNVJ4eHi5trCwsArfAwAAgP+odgDMysqqwzIAAABwqXj9DCAAAAAaplq/C1g6t+L3+++/92w82LNnT1ksPukaAAAAPlarEcCTJ09q2rRpatGiha655hoNHTpUffv2VYsWLTRt2jQdP37cV3UCAADAR7wepjt58qSGDBmi77//Xq1atVJ0dLTatWuno0ePaufOnVqyZImSk5OVlpamli1b+rJmAAAA1ILXI4Dz58/X999/r9mzZys7O1vr1q3TsmXL9Mknnyg7O1tPPvmkMjIy9Nxzz/myXgAAANSSyeVyubz5YteuXdWlSxdt2rSpynNuuOEG/fDDD/rhhx+8LrAhq8lLmb019a910i0AAPCx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TqdT11xzjf7whz/oyy+/VFxcnN5++20VFhbKZDJ5Vvo6HA41btxYknTixAmVlZWpf//+ktg0GjAqFoEAQAN3+vRpxcfH66WXXpIk9evXT2PHjlVcXJyGDh0qk8mk4uJibdu2Tffee6/atm2rnTt3VjpVDMAYCIAAcJnYvHmzXn75ZX3yySeetrZt2yoyMlL5+fn69ttv1b17d73yyisaM2aMHA6HAgIC6rFiAPWFAAgADdzPR/L279+vDz/8UP/973+1b98+NWvWTM2aNVO/fv301FNP6eqrr2YjaMDgCIAAcBk7fvy4fvzxR0VERKhx48YKCAhg6hcAARAALgdnz57VgQMHFB4eruDg4Cpf90b4AyCxChgAGjT33+F37dql6dOn691335Uk2e12ORyOCucT/gBIBEAAaNDcge7zzz9XWlqahgwZIknatm2bZsyYoW+//bY+ywPgpwiAANBAuUf/Dh8+rI0bN6p79+665pprVFpaqrVr1+qf//ynwsPD67lKAP6IAAgADdx3332nzz//XPfcc48kKTMzU5s2bVJ0dLSsVmulU8EAjI13AQNAA2UymeRwOPT555+ruLhYU6dOlSR98803+vLLL5WQkFDPFQLwV4wAAkAD5J7+zcrK0qeffqrBgwerbdu2KiwsVHJysgIDAzV+/HhJYrNnABUwAggADZB78cfXX3+tnTt3aunSpZKk77//Xhs2bNCvf/1rSedWA1ss/KoHUB6/FQCggfrpp5+UlJQki8Wiu+++W5L05Zdf6ocfftCyZcskse0LgMoxBQwADYx7+vfAgQNKTEzU2LFjZTabdfToUW3atElt2rRRdHS0JKZ/AVSOAAgADYx7VG/btm06cOCAfve730mS9u7dq88++0x33XWXpHPTvwBQGQIgADRARUVF2rp1q6644gqNHj1akrRz504dP35cM2bMkKRKXwUHABLPAAJAg+N+n290dLRiYmIkSdnZ2frggw/UpUsXde/eXS6XiwAIoEoEQABoIOx2u8rKytS0aVNdccUVuvfeez2bPNvtdnXs2FGTJ0+WJDkcDlb/AqiSyeV+mhgA4JfcW7msWLFCS5cu1bx58zRs2LAK52VnZ6tDhw4EPwAXRQAEAD/nnvLt2bOnMjIyNHr0aK1atUpWq7XK7zidTqaAAVSJ3w4A4MecTqdMJpO+++47ZWRk6Lrr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\n"
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plot_histogram(samples_for_plot)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "cqt-rl-pulse",
   "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}