examples/evqe_optimization.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:29:42.332448Z",
     "start_time": "2024-07-22T09:29:42.318161Z"
    }
   },
   "source": [
    "from pathlib import Path\n",
    "import os\n",
    "import sys\n",
    "\n",
    "main_directory = Path(os.path.abspath(\"\")).parent\n",
    "sys.path.append(str(main_directory))"
   ],
   "outputs": [],
   "execution_count": 1
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Create a quadratic model in docplex"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:29:42.981452Z",
     "start_time": "2024-07-22T09:29:42.337474Z"
    }
   },
   "source": [
    "from docplex.mp.model import Model\n",
    "\n",
    "# set up the model for optimization in docplex\n",
    "optimization_problem = Model()\n",
    "\n",
    "# add the needed variables\n",
    "x = optimization_problem.integer_var(0, 15, \"x\")\n",
    "y = optimization_problem.integer_var(0, 15, \"y\")\n",
    "a = optimization_problem.binary_var(\"a\")\n",
    "b = optimization_problem.binary_var(\"b\")\n",
    "\n",
    "# formally describe the minimization task\n",
    "optimization_problem.minimize((2*x-y)**2 + 100*a*x - 100*b*y + (a + b - 1)**2)"
   ],
   "outputs": [],
   "execution_count": 2
  },
  {
   "cell_type": "markdown",
   "source": [],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Convert the docplex model to a qiskit hamiltonian"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:29:44.752369Z",
     "start_time": "2024-07-22T09:29:42.985548Z"
    }
   },
   "source": [
    "from qiskit_optimization.translators import from_docplex_mp, to_ising\n",
    "from qiskit_optimization.converters import IntegerToBinary\n",
    "\n",
    "# convert to a quadratic program\n",
    "quadratic_program = from_docplex_mp(model=optimization_problem)\n",
    "\n",
    "# some variables are still integers, convert them to binary variables\n",
    "integer_converter = IntegerToBinary()\n",
    "quadratic_program = integer_converter.convert(problem=quadratic_program)\n",
    "\n",
    "# convert the quadratic program to an ising hamiltonian\n",
    "hamiltonian, offset = to_ising(quad_prog=quadratic_program)"
   ],
   "outputs": [],
   "execution_count": 3
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Setup the configuration for the EVQEMinimumEigensolver"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:29:46.724069Z",
     "start_time": "2024-07-22T09:29:44.754549Z"
    }
   },
   "source": [
    "from qiskit_aer.primitives import SamplerV2, EstimatorV2\n",
    "from qiskit_algorithms.optimizers import SPSA\n",
    "\n",
    "from queasars.circuit_evaluation.configured_primitives import ConfiguredEstimatorV2, ConfiguredSamplerV2\n",
    "from queasars.minimum_eigensolvers.base.termination_criteria import BestIndividualRelativeChangeTolerance\n",
    "from queasars.minimum_eigensolvers.evqe.evqe import EVQEMinimumEigensolverConfiguration\n",
    "\n",
    "# The EVQEMinimumEigensolver needs a sampler and can also use an estimator.\n",
    "# Here we use the sampler and estimator provided by the qiskit_aer simulator.\n",
    "configured_sampler = ConfiguredSamplerV2(\n",
    "    sampler=SamplerV2(),\n",
    "    shots=4000,\n",
    ")\n",
    "configured_estimator = ConfiguredEstimatorV2(\n",
    "    estimator=EstimatorV2(),\n",
    "    precision=0.01,\n",
    ")\n",
    "\n",
    "# A PassManager can be given to specify the transpilation process.\n",
    "# This is important if running on real quantum hardware!\n",
    "pass_manager = None\n",
    "\n",
    "# The EVQEMinimumEigensolver also needs a qiskit optimizer. It should be\n",
    "# configured to terminate quickly, so that mutations are not overtly expensive.\n",
    "# Here we use the SPSA optimizer with a limited amount of iterations and a\n",
    "# large step size.\n",
    "optimizer = SPSA(maxiter=33, perturbation=0.35, learning_rate=0.43, trust_region=True)\n",
    "\n",
    "# To help the EVQEMinimumEigensolver deal correctly with terminations based\n",
    "# on the amount of circuit evaluations used, an estimate can be given for how\n",
    "# many circuit evaluations the optimizer uses per optimization run.\n",
    "# SPSA makes two measurements per iteration, which means in total it will\n",
    "# need 66 circuit evaluations for 33 iterations.\n",
    "optimizer_n_circuit_evaluations = 66\n",
    "\n",
    "# To specify when the EVQEMinimumEigensolver should terminate either max_generations,\n",
    "# max_circuit_evaluations or a termination_criterion should be given.\n",
    "# Here we choose to terminate once the expectation value of the best individual of a generation\n",
    "# changes by less than 1% between generations for two consecutive generations.\n",
    "max_generations = None\n",
    "max_circuit_evaluations = None\n",
    "termination_criterion = BestIndividualRelativeChangeTolerance(minimum_relative_change=0.01, allowed_consecutive_violations=1)\n",
    "\n",
    "# A random seed can be provided to control the randomness of the evolutionary process.\n",
    "random_seed = 0\n",
    "\n",
    "# The population size determines how many individuals are evaluated each generation.\n",
    "# With a higher population size, fewer generations might be needed, but this also\n",
    "# makes each generation more expensive to evaluate. A reasonable range might be\n",
    "# 10 - 100 individuals per population. Here we use a population size of 10.\n",
    "population_size = 10\n",
    "\n",
    "# The initial individuals in the starting population can be initialized with\n",
    "# an arbitrary amount of layers and fully randomized parameter values. This\n",
    "# can be particularly useful if the state |0 .. 0> is a local minima and\n",
    "# the individuals should not start in that state\n",
    "n_initial_layers = 2\n",
    "randomize_initial_parameter_values = True\n",
    "\n",
    "# Determines how many circuit layers apart two individuals need to be, to be considered to\n",
    "# be of a different species. Reasonable values might be in the range 1 - 5. Here we use 1.\n",
    "speciation_genetic_distance_threshold = 1\n",
    "\n",
    "# This implementation of EVQE offers both roulette wheel selection and tournament selection.\n",
    "# Since tournament selection is more robust, we use it here.\n",
    "use_tournament_selection = True\n",
    "tournament_size = 2\n",
    "\n",
    "# The alpha and beta penalties penalize quantum circuits of increasing depth (alpha) and\n",
    "# increasing amount of controlled rotations (beta). increase them if the quantum circuits get to\n",
    "# deep or complicated.\n",
    "selection_alpha_penalty = 0.15\n",
    "selection_beta_penalty = 0.02\n",
    "\n",
    "# The parameter search probability determines how likely an individual is mutated by optimizing\n",
    "# all it's parameter values. This should not be too large as this is costly. Here we will use\n",
    "# a probability of 0.39.\n",
    "parameter_search_probability = 0.39\n",
    "\n",
    "# The topological search probability determines how likely a circuit layer is added to an individual\n",
    "# as a mutation. This should be a higher probability to encourage exploration of different circuits.\n",
    "# Here we will use a likelihood of 0.79\n",
    "topological_search_probability = 0.79\n",
    "\n",
    "# The layer removal probability determines how likely circuit layers are removed from an individual\n",
    "# as a mutation. This is a very disruptive mutation and should only be used sparingly to counteract\n",
    "# circuit growth. Here we will use a probability of 0.02\n",
    "layer_removal_probability = 0.02\n",
    "\n",
    "# An executor for launching parallel computation can be specified.\n",
    "# This can be a dask Client or a python ThreadPoolExecutor. If None is\n",
    "# specified a ThreadPoolExecutor with population_size many threads will\n",
    "# be used\n",
    "parallel_executor = None\n",
    "\n",
    "# Discerns whether to only allow mutually exclusive access to the Sampler and\n",
    "# Estimator primitive respectively. This is needed if the Sampler or Estimator are not threadsafe and\n",
    "# a ThreadPoolExecutor with more than one thread or a Dask Client with more than one thread per process is used.\n",
    "# For safety reasons this is enabled by default. If the sampler and estimator are threadsafe disabling this\n",
    "# option may lead to performance improvements\n",
    "mutually_exclusive_primitives = False\n",
    "\n",
    "configuration = EVQEMinimumEigensolverConfiguration(\n",
    "    configured_sampler=configured_sampler,\n",
    "    configured_estimator=configured_estimator,\n",
    "    pass_manager=pass_manager,\n",
    "    optimizer=optimizer,\n",
    "    optimizer_n_circuit_evaluations=optimizer_n_circuit_evaluations,\n",
    "    max_generations=max_generations,\n",
    "    max_circuit_evaluations=max_circuit_evaluations,\n",
    "    termination_criterion=termination_criterion,\n",
    "    random_seed=random_seed,\n",
    "    population_size=population_size,\n",
    "    randomize_initial_population_parameters=randomize_initial_parameter_values,\n",
    "    n_initial_layers=n_initial_layers,\n",
    "    speciation_genetic_distance_threshold=speciation_genetic_distance_threshold,\n",
    "    use_tournament_selection=use_tournament_selection,\n",
    "    tournament_size=tournament_size,\n",
    "    selection_alpha_penalty=selection_alpha_penalty,\n",
    "    selection_beta_penalty=selection_beta_penalty,\n",
    "    parameter_search_probability=parameter_search_probability,\n",
    "    topological_search_probability=topological_search_probability,\n",
    "    layer_removal_probability=layer_removal_probability,\n",
    "    parallel_executor=parallel_executor,\n",
    "    mutually_exclusive_primitives=mutually_exclusive_primitives,\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 4
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Setup the EVQEMinimumEigensolver"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:29:48.187803Z",
     "start_time": "2024-07-22T09:29:46.728071Z"
    }
   },
   "source": [
    "from queasars.minimum_eigensolvers.evqe.evqe import EVQEMinimumEigensolver\n",
    "\n",
    "eigensolver = EVQEMinimumEigensolver(configuration=configuration)"
   ],
   "outputs": [],
   "execution_count": 5
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Solve the problem as posed in the hamiltonian"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:31:55.029998Z",
     "start_time": "2024-07-22T09:29:48.188815Z"
    }
   },
   "source": [
    "import logging\n",
    "\n",
    "logger = logging.getLogger(\"queasars.minimum_eigensolvers.base.evolving_ansatz_minimum_eigensolver\")\n",
    "handler = logging.StreamHandler()\n",
    "logger.setLevel(logging.INFO)\n",
    "logger.addHandler(handler)\n",
    "\n",
    "result = eigensolver.compute_minimum_eigenvalue(operator=hamiltonian)\n",
    "quasi_distribution = result.eigenstate.binary_probabilities()\n"
   ],
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Starting evolution!\n",
      "Results for generation: 0\n",
      "Current best expectation value: -1284.271595\n",
      "Current median expectation value: -703.162166\n",
      "Current average expectation value: -655.842839\n",
      "Results for generation: 1\n",
      "Current best expectation value: -1612.895173\n",
      "Current median expectation value: -1367.653941\n",
      "Current average expectation value: -1320.791436\n",
      "Results for generation: 2\n",
      "Current best expectation value: -1622.270008\n",
      "Current median expectation value: -1521.649648\n",
      "Current average expectation value: -1482.536990\n",
      "Results for generation: 3\n",
      "Current best expectation value: -1632.443528\n",
      "Current median expectation value: -1570.370227\n",
      "Current average expectation value: -1541.901151\n"
     ]
    }
   ],
   "execution_count": 6
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Plot the distribution"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "ExecuteTime": {
     "end_time": "2024-07-22T09:31:56.265223Z",
     "start_time": "2024-07-22T09:31:55.031510Z"
    }
   },
   "source": [
    "from qiskit.visualization import plot_distribution\n",
    "\n",
    "plot_distribution(quasi_distribution, number_to_keep=10)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Figure size 700x500 with 1 Axes>"
      ],
      "image/png": "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iWN63XaOiWMCCn9Mhamwx1SYCvv7VJjksu+Z089TttfLU68cKBQKk+1CCMTHx2Pnzp2vfdWolZUVfHx8jC5eyLqY4eUjdf80bdo0TJgwAbt27YKvr6/RY927d8f58+cRExNj+M/V1RVDhw7F7t27XysfERERkTl5rRJcqVQaFXDjxo3DuHHjcuwvhMDw4cNfO1R4eDh69uwJX19fNGrUCLNnz0Z6ejrCwsIAAD169ICbmxsmT54M4MX5cGPHjsXq1avh6emJxMREAC/uH1uiRAk4ODjAwcHB6DUsLS3h7OwMLy+v185HREREZC5eq5hr3ry5oZg7fPgw3N3dTS5HolKpUKZMGbRu3Rp9+vR57VChoaFITk7G2LFjkZiYCG9vb+zatctwUUR8fLzR4csFCxYgMzMTH330kdF2IiIici02iYiIiOTutYq5gwcPGv6tVCoRFhaW6wUQb6J///7o37//K3MAMHnO26vk5zlERERE5ibfZzq+fNUFEREREUmjcFcCJCIiIqJClecjc5988gkUCgUmTZoEJycnfPLJJ3l6nkKhwOLFi/MdkIiIiIhyludibtmyZVAoFBg+fDicnJywbNmyPD2PxRwRERFR4clzMXfz5k0AgJubm9HXRERERCSdPBdzHh4euX5NREREREWPF0AQERERyViej8zFx8fn+0VevicqERERERWcPBdznp6eOd6LNTcKhQJarfa1n0dEREREr5bnYq5Hjx75KuaIiIiIqPC81tIkRERERGReeAEEERERkYyxmCMiIiKSMd7Oi4iIiEjGeDsvIiIiIhnj7byIiIiIZIy38yIiIiKSMV4AQURERCRjb1zMbdq0CZ06dYK7uzvs7e3h7u6O4OBgbN68uQDiEREREVFu8vwx6z9ptVr85z//wYYNGyCEgIWFBRwcHJCYmIgtW7Zg69at6Ny5M1avXg0Li3y/DBERERHlIt9H5iZPnoz169ejWbNm+OOPP5CRkYF79+4hIyMDhw8fRtOmTbFhwwZMmTKlIPMSERER0UvyXcwtXboU1atXx759+9CkSRMolS82pVQq0bRpU+zbtw/VqlXDkiVLCiwsERERERnLdzF37949vP/++zl+hGppaYn3338f9+7dy3c4IiIiIspdvou5ChUq4OnTp7n2SU9Ph7u7e35fgoiIiIheId/F3Keffoq1a9fmeOQtISEBkZGR+PTTT/MdjoiIiIhyl+fLTOPj442+7tKlC44cOYL69etj0KBBaNq0KZycnJCUlIQ//vgDc+bMQdOmTRESElLgoYmIiIjohTwXc56enlAoFNnahRAYPXq0yfYtW7Zg27Zt0Gq1b5aSiIiIiEzKczHXo0cPk8UcEREREUknz8XcsmXLCjEGEREREeUH781KREREJGMs5oiIiIhk7I1umpqWloZ58+Zh3759uHv3LtRqdbY+CoUC169ff5OXISIiIqIc5LuYS05ORkBAAK5fvw47Ozs8efIE9vb2yMzMxPPnzwEArq6usLS0LLCwRERERGQs3x+zjhs3DtevX8evv/6Khw8fAgAGDx6M9PR0HD9+HI0aNYKnpycuXrxYYGGJiIiIyFi+i7kdO3agTZs2+O9//5ttyZKGDRti586diIuLw/jx4984JBERERGZlu9i7t69e6hfv77ha5VKZfh4FQBKly6Nd999F2vXrn2zhERERESUo3wXc/b29tBoNIavS5cujTt37hj1sbOzQ1JSUv7TEREREVGu8l3MVapUCXFxcYav69evj7179+LBgwcAgOfPn2Pr1q1wd3d/45BEREREZFq+i7m2bdsiKioKz549AwB89tlnuH//PurVq4eQkBDUrl0b169fR69evQoqKxERERH9Q76LuX79+uHnn382FHMffvghpk+fjvT0dGzYsAGJiYkIDw/H0KFDCywsERERERnL9zpzLi4uCA0NNWr7+uuvMWjQIKSkpKBcuXLZrnIlIiIiooL1RneAMEWlUsHJyamgN0tEREREJrxxMXfv3j2sWbMGZ8+exePHj2Fvb4/69evj448/houLS0FkJCIiIqIcvFExN3/+fAwdOhRqtRpCCEP7ypUrMXr0aMyYMQNffPHFG4ckIiIiItPyXcytWbMGAwYMgKOjI0aPHo1mzZrByckJSUlJOHz4MObMmWN4vEuXLgWZmYiIiIj+X76LuWnTpsHR0RExMTFwdXU1tHt5eaF58+bo1asX6tevj6lTp7KYIyIiIiok+V6a5NKlS+jSpYtRIfey8uXLIyQkBJcuXcp3OCIiIiLKXb6LuVKlSqF48eK59ilRogRKlSqV35cgIiIiolfIdzHXsWNHbN26FVqt1uTjGo0GW7duRadOnfIdjoiIiIhyl+9ibtq0aShevDjatm2LY8eOGT0WHR2Ntm3bomTJkpgyZcobhyQiIiIi0/J8AUSlSpWytWVmZuLMmTNo0qQJLCws4OjoiJSUFMPROhcXFzRo0ADXr18vuMREREREZJDnYk6v12e7PZelpSXc3d2N2v55QYRer3+DeERERESUmzwXc3FxcYUYg4iIiIjyI9/nzBERERGR9N743qwAoNVqERsbiydPnsDOzg5eXl6wsCiQTRMRERFRLt7oyFxqair69OkDe3t71K1bF02bNkXdunVRqlQp9O3bFw8ePCionERERERkQr4Pn6WmpqJx48a4du0aypQpg2bNmsHFxQWJiYk4deoUfvnlFxw6dAjR0dEoU6ZMQWYmIiIiov+X7yNzEyZMwLVr1zB06FDcunULu3btwtKlS7Fz507cunULw4cPx9WrVzFx4sSCzEtEREREL8l3Mff777+jZcuWmDp1arbbetna2mLy5Mlo2bIlNm3a9MYhiYiIiMi0fBdzd+/ehb+/f659/P39cffu3fy+BBERERG9Qr6LOXt7e9y6dSvXPrdu3YK9vX1+X4KIiIiIXiHfxVyLFi2wbt067Nu3z+TjUVFRWLduHVq2bJnflyAiIiKiV8j31awRERHYvn07goKC0L59e7Ro0QJOTk5ISkrCwYMHsXPnTtja2mLs2LEFmZeIiIiIXpLvYq5WrVrYvXs3evXqhe3bt2P79u1QKBQQQgAAKleujGXLlqFWrVoFFpaIiIiIjL3RbRqaNm2Kq1ev4siRIzh79qzhDhD169dHkyZNoFAoCionEREREZmQ72Luk08+QZ06dTB48GA0bdoUTZs2LchcRERERJQH+b4AYvXq1bh//35BZiEiIiKi15TvYq5y5cq4d+9eQWYhIiIioteU72Luk08+wfbt25GQkFCQeYiIiIjoNeT7nLnOnTvjwIEDCAgIwLBhw9CwYUM4OTmZvOjB3d39jUISERERkWn5LuYqVapkWIpk4MCBOfZTKBTQarX5fRkiIiIiykW+i7kePXpw6REiIiIiieW7mFu2bFkBxiAiIiKi/Mj3BRBEREREJL03ugMEAKjVauzYsQNnz57F48ePYW9vj/r166N9+/awtrYuiIxERERElIM3Kua2bNmCvn37Ijk52XBPVuDFRQ/lypXDokWL8P77779xSCIiIiIyLd8fs0ZFRaFz58549OgRPvnkEyxbtgw7d+7EsmXL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4MGDJtsVCgVKly6Ntm3bIjw8HO+8805+X4KIiIiIXuGN1pkjIiIiImm98b1Z79+/j4SEBOj1eri5ucHZ2bkgchERERFRHuTrAgi1Wo1p06ahatWqcHFxga+vLxo1agQ3Nzc4Ojpi8ODBuS4qTEREREQF47WLudu3b6Nhw4YYOXIkrl+/DhcXFzRq1AiNGjWCi4sLUlNTMWfOHPj6+mLfvn2G5927d49rzhEREREVsNcq5jQaDdq3b48LFy6ga9euuHTpEu7cuYPo6GhER0fjzp07uHTpErp164bU1FQEBwcjLi4O169fR9OmTXH58uXCGgcRERHRW+m1zpn76aefcPHiRURERCAiIsJkHy8vL6xYsQLVqlVDREQEunXrhri4OKSkpMDHx6dAQhMRERHRC691ZG7t2rWoUqVKntaOGzNmDKpWrYro6GhkZGRg9+7d6NChQ76DEhEREVF2r1XM/f3332jbti0UCsUr+yoUCkPf48ePo2XLlvnNSEREREQ5eK1i7unTp7C3t89zfzs7O1hYWKBKlSqvHYyIiIiIXu21irly5crh2rVree5//fp1lCtX7rVDEREREVHevFYx5+/vj507dyIxMfGVfRMTE7F9+3Y0bdo03+GIiIiIKHevVcz169cPT58+xQcffICUlJQc+z148AAffPABnj17hs8+++yNQxIRERGRaa+1NEmrVq3Qp08f/Pzzz6hRowY+++wztG7dGhUqVADwYkHhqKgo/Pzzz0hJSUHfvn154QMRERFRIXrte7P++OOPsLOzw6xZszB58mRMnjzZ6HEhBJRKJYYMGZLtMSIiIiIqWK9dzKlUKkyfPh19+/bFsmXLEB0dbTiHztnZGQEBAejZsyeqVq1a4GGJiIiIyNhrF3NZqlatiokTJxZkFiIiIiJ6Ta91AQQRERERmRcWc0REREQyxmKOiIiISMZYzBERERHJGIs5IiIiIhljMUdEREQkYyzmiIiIiGSMxRwRERGRjLGYIyIiIpIxFnNEREREMsZijoiIiEjGWMwRERERyRiLOSIiIiIZYzFHREREJGMs5oiIiIhkjMUcERERkYyZbTE3f/58eHp6wsbGBn5+fjhx4kSu/detW4fq1avDxsYGderUwY4dO4wef/r0Kfr374/y5cujWLFiqFmzJhYuXFiYQyAiIiIqdGZZzEVGRiI8PBwRERE4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"
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 7
  },
  {
   "cell_type": "markdown",
   "source": [
    "## use the integer translator to retrieve your variables"
   ],
   "metadata": {
    "collapsed": false
   }
  },
  {
   "cell_type": "code",
   "source": [
    "for bitstring, probability in quasi_distribution.items():\n",
    "    if probability < 0.05:\n",
    "        continue\n",
    "\n",
    "    bitlist = [int(char) for char in bitstring][::-1]\n",
    "    converted_variables = integer_converter.interpret(bitlist)\n",
    "    print(\"probability: \", probability)\n",
    "    print(\"variable values: \", converted_variables)\n",
    "    print(\"\")"
   ],
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-07-22T09:31:56.279075Z",
     "start_time": "2024-07-22T09:31:56.268351Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "probability:  0.28825\n",
      "variable values:  [ 5. 15.  0.  1.]\n",
      "\n",
      "probability:  0.3225\n",
      "variable values:  [ 6. 15.  0.  1.]\n",
      "\n",
      "probability:  0.2955\n",
      "variable values:  [ 7. 15.  0.  1.]\n",
      "\n"
     ]
    }
   ],
   "execution_count": 8
  }
 ],
 "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.11.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}