docs/tutorial/en/001-openjij_introduction.ipynb
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Introduction to OpenJij\n",
"OpenJij is a heuristic optimization library for the Ising model and QUBO.\n",
"The core of the optimization calculation is implemented in C++, but it has a Python interface that allows easy optimization coding with Python.\n",
"\n",
"The first step is to install the OpenJij and the NumPy library if it is not installed yet. This can be achieved using the pip python package manager; for example:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Requirement already satisfied: numpy in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (1.23.4)\n"
]
}
],
"source": [
"!pip install numpy -U"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Requirement already satisfied: openjij in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (0.5.40)\n",
"Requirement already satisfied: numpy<1.24.0,>=1.17.3 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (1.23.4)\n",
"Requirement already satisfied: jij-cimod<1.5.0,>=1.4.6 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (1.4.40)\n",
"Requirement already satisfied: dimod<0.12.0 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (0.11.6)\n",
"Requirement already satisfied: typing-extensions<4.3.0,>=4.2.0 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (4.2.0)\n",
"Requirement already satisfied: requests<2.29.0,>=2.28.0 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (2.28.1)\n",
"Requirement already satisfied: scipy<1.10.0,>=1.7.3 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from openjij) (1.9.3)\n",
"Requirement already satisfied: certifi>=2017.4.17 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from requests<2.29.0,>=2.28.0->openjij) (2022.9.24)\n",
"Requirement already satisfied: idna<4,>=2.5 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from requests<2.29.0,>=2.28.0->openjij) (3.4)\n",
"Requirement already satisfied: charset-normalizer<3,>=2 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from requests<2.29.0,>=2.28.0->openjij) (2.1.1)\n",
"Requirement already satisfied: urllib3<1.27,>=1.21.1 in /Users/maruomei/miniconda3/envs/jij/lib/python3.10/site-packages (from requests<2.29.0,>=2.28.0->openjij) (1.26.12)\n"
]
}
],
"source": [
"!pip install openjij"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Name: openjij\n",
"Version: 0.5.40\n",
"Summary: Framework for the Ising model and QUBO.\n",
"Home-page: https://www.openjij.org\n",
"Author: Jij Inc.\n",
"Author-email: info@openjij.org\n",
"License: Apache License 2.0\n",
"Location: /Users/xxx/miniconda3/envs/jij/lib/python3.10/site-packages\n",
"Requires: dimod, jij-cimod, numpy, requests, scipy, typing-extensions\n",
"Required-by: \n"
]
}
],
"source": [
"# This shows the OpenJij information. \n",
"# The output will vary depending on the execution environment.\n",
"!pip show openjij"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Optimization Computation with Ising Model using OpenJij\n",
"\n",
"As described in [0-Introduction: Combinatorial optimization and the Ising model](./000-combinatorial_optimization_and_Ising_model.ipynb),\n",
"the Ising model is a model proposed to understand the behavior of magnetic materials and is written as follows:\n",
"\n",
"$$H(\\{\\sigma_i\\}) = \\sum_{i > j} J_{ij}\\sigma_i \\sigma_j + \\sum_{i=1}^N h_i \\sigma_i$$\n",
"$$\\sigma_i \\in \\{-1, 1\\}, i=1,\\cdots N$$\n",
"\n",
"where $H(\\{\\sigma_i\\})$ is called the Hamiltonian which can be interpreted as an energy or a cost function.\n",
"$\\sigma_i$ is a variable that takes either $1$ or $-1$. \n",
"\n",
"> $\\sigma_i$ is sometimes called a spin variable or simply spin because it corresponds to a physical quantity called spin in physics. \n",
"> Spin is described as a small magnet. $-1$ corresponds to a magnet facing up, and $1$ corresponds to a magnet facing down.\n",
"\n",
"\n",
"$H$ depends on the combination of variables $\\{\\sigma_i\\} = \\{\\sigma_1, \\sigma_2, \\cdots, \\sigma_N\\}$.\n",
"$J_{ij}$ and $h_i$ represent the given problem, and they are called interaction coefficients and longitudinal magnetic fields, respectively.\n",
"\n",
"OpenJij is a numerical library that performs simulated annealing or simulated quantum annealing given $J_{ij}$ and $h_i$ as inputs.\n",
"We use OpenJij to find the spin variable combination $\\{\\sigma_i\\}$ that minimizes $H(\\{\\sigma_i\\})$.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### How to Solve Problems with OpenJij\n",
"First, let's look at how OpenJij can be used in a simple example.\n",
"Let the number of variables be $N=5$ and the longitudinal fields and the interaction coefficients as:\n",
"\n",
"$$h_i = -1~\\text{for} ~\\forall i, ~ J_{ij} = -1~\\text{for} ~\\forall i, j$$\n",
"\n",
"Since all interactions are negative, we know that each spin variable should take the same value to have a lower energy state.\n",
"Also, since all longitudinal magnetic fields are negative, each spin variable should take the value of 1 to have lower energy. \n",
"Thus, the optimal solution to this problem is $\\{\\sigma_i\\} = \\{1, 1, 1, 1, 1, 1\\}$.\n",
"\n",
"Now, let's see if we can obtain this result using OpenJij."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First, we prepare $h_i$ and $J_{ij}$ as input data.\n",
"Here, we create a dictionary with the respective indexes as keys and values as values."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"h_i: {0: -1, 1: -1, 2: -1, 3: -1, 4: -1}\n",
"Jij: {(0, 1): -1, (0, 2): -1, (0, 3): -1, (0, 4): -1, (1, 2): -1, (1, 3): -1, (1, 4): -1, (2, 3): -1, (2, 4): -1, (3, 4): -1}\n"
]
}
],
"source": [
"import openjij as oj\n",
"\n",
"# Define the vertical field and the interaction coefficient. \n",
"# OpenJij accepts problems in a dictionary form.\n",
"N = 5\n",
"h = {i: -1 for i in range(N)}\n",
"J = {(i, j): -1 for i in range(N) for j in range(i+1, N)}\n",
"\n",
"print('h_i: ', h)\n",
"print('Jij: ', J)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we perform the optimization calculation.\n",
"Here, we define an instance of `oj.SASampler` to perform the annealing method.\n",
"The annealing method is executed by passing $h_i$ and $J_{ij}$ as arguments of the `sample_ising` method.\n",
"\n",
"Details of `oj.SASampler` and `sample_ising` and their return values are described at the end of this note."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[1 1 1 1 1]]\n",
"[{0: 1, 1: 1, 2: 1, 3: 1, 4: 1}]\n"
]
}
],
"source": [
"# First define the instance of the sampler that solves the problem.\n",
"# The algorithm for solving the problem can be determined by which instance is selected.\n",
"sampler = oj.SASampler(num_reads=1)\n",
"# Solve the problem by adding (h, J) to the sampler's method.\n",
"response = sampler.sample_ising(h, J)\n",
"\n",
"# The result of the calculation (state) is stored in `response.states`.\n",
"print(response.states)\n",
"\n",
"# See the result with subscripts by using the samples function.\n",
"print([s for s in response.samples()])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Indeed, we obtained a state in which all spins were 1, as expected."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Above we passed $h_i$ and $J_{ij}$ as dictionaries, but NumPy-based input can be more convenient with huge problems.\n",
"OpenJij provides `oj.BinaryQuadraticModel.from_numpy_matrix` that converts the following form of a NumPy matrix to a form that OpenJij can solve.\n",
"\n",
"$$ \\begin{pmatrix}\n",
"h_{0} & J_{0,1} & \\cdots & J_{0,N-1}\\\\\n",
"J_{1,0} & h_{1} & \\cdots & J_{1,N-1}\\\\\n",
"\\vdots & \\vdots & \\vdots & \\vdots\\\\\n",
"J_{N-1,0} & J_{N-1,1} & \\cdots & h_{N-1}\\\\\n",
"\\end{pmatrix} $$"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[-1. -0.5 -0.5 -0.5]\n",
" [-0.5 -1. -0.5 -0.5]\n",
" [-0.5 -0.5 -1. -0.5]\n",
" [-0.5 -0.5 -0.5 -1. ]]\n",
"BinaryQuadraticModel({3: -1.0, 2: -1.0, 1: -1.0, 0: -1.0}, {(1, 2): -1.0, (0, 2): -1.0, (1, 3): -1.0, (0, 3): -1.0, (2, 3): -1.0, (0, 1): -1.0}, 0.0, Vartype.SPIN, sparse=False)\n",
"[[1 1 1 1]]\n"
]
}
],
"source": [
"import numpy as np\n",
"mat = np.array([\n",
" [-1,-0.5,-0.5,-0.5],\n",
" [-0.5,-1,-0.5,-0.5],\n",
" [-0.5,-0.5,-1,-0.5],\n",
" [-0.5,-0.5,-0.5,-1]\n",
" ])\n",
"print(mat)\n",
"\n",
"# Use oj.BinaryQuadraticModel with the variable type (vartype) set to 'SPIN'.\n",
"bqm = oj.BinaryQuadraticModel.from_numpy_matrix(mat, vartype='SPIN')\n",
"# Each element for J_{ij} and J_{ji} are grouped together internally.\n",
"print(bqm)\n",
"\n",
"sampler = oj.SASampler(num_reads=1)\n",
"response = sampler.sample(bqm)\n",
"\n",
"print(response.states)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When the data were given in a dictionary form, only the upper triangle portions of the interaction matrix were given, but when given in a NumPy matrix, the lower triangles are also included. Note that therefore the off-diagonal elements of the interaction matrix are given as -0.5, half of -1, to make the problem consistent with the case given in the dictionary."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Optimization Computation with QUBO using OpenJij\n",
"\n",
"When solving a real problem in society, it is often more straightforward to formulate the problem into a form called Quadratic Unconstrained Binary Optimization (QUBO) than to the Ising model.\n",
"\n",
"QUBO is written as follows:\n",
"\n",
"$$H(\\{q_i\\}) = \\sum_{i\\geq j} Q_{ij}q_i q_j$$\n",
"$$q_i \\in \\{0, 1\\}$$\n",
"\n",
"The difference from the Ising model is that the binary variables are either 0 or 1.\n",
"There are various possible ranges of how to take the sum of $\\sum Q_{ij}$ (e.g. let Q be a symmetric matrix and summing over all ranges of i, j), but here we define it as above.\n",
"\n",
"> The transformation formula $Q_i = (\\sigma_i + 1)/2$ allows the Ising model and QUBO to be interconverted, and in that sense the two models are equivalent.\n",
"\n",
"In QUBO, $Q_{ij}$ is given as an input, and the problem is to find the combination $\\{q_i\\}$ of 0 and 1 that minimizes $H(\\{q_i\\})$.\n",
"It is almost the same as the Ising model case mentioned earlier.\n",
"\n",
"Also, since $q_i$ is a binary variable, we know that $q_i^2 = q_i$. Therefore, we can rewrite the above equation as follows:\n",
"\n",
"$$H(\\{q_i\\}) = \\sum_{i > j} Q_{ij}q_i q_j + \\sum_i Q_{ii} q_i$$\n",
"\n",
"Note that $Q_{ij}$ with the same subscripts corresponds to the coefficient of the first-order term of $q_i$.\n",
"\n",
"Let us solve this in OpenJij."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[1 1 0]]\n"
]
}
],
"source": [
"# Define Q_ij in a dictionary type.\n",
"Q = {(0, 0): -1, (0, 1): -1, (1, 2): 1, (2, 2): 1}\n",
"sampler = oj.SASampler()\n",
"# Use .sample_qubo to solve QUBO problems.\n",
"response = sampler.sample_qubo(Q)\n",
"print(response.states)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Since the variables are 0, 1 in QUBO, we see that the solution is also output as 0, 1. \n",
"Thus, the optimization problem can be solved using OpenJij for both the Ising model and QUBO."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## OpenJij Features\n",
"\n",
"In this section, we explain the details of the above code.\n",
"OpenJij currently has two interfaces, and the one used above is the same interface as D-Wave Ocean. Therefore, being familiar with OpenJij, one can handle D-Wave Ocean easily.\n",
"\n",
"> The other interface is not described here, but it has an ease of extension by directly using OpenJij's mechanism `graph, method, algorithm`. It should be sufficient here to use the interfaces covered in the cells above.\n",
"\n",
"### Sampler\n",
"\n",
"Above we defined an instance of a sampler after defining a dictionary-type problem as shown below:\n",
"```python\n",
"sampler = oj.SASampler(num_reads=1)\n",
"```\n",
"Here we specify what algorithm this sampler instance uses.\n",
"To try other algorithms, change this sampler to use a different algorithm.\n",
"For example, the `SASampler` used in the example above is a sampler that samples the solution using an algorithm called simulated annealing. \n",
"Another `SQASampler` is available to use simulated quantum annealing (SQA), an algorithm to simulate quantum annealing on a classical computer.\n",
"\n",
"> The algorithm handled by OpenJij is a heuristic stochastic algorithm. The solution returned is different each time the problem is solved, and it is not always possible to obtain the optimal solution.\n",
"> Therefore, we solve the problem multiple times and look for the best solution among them. For this reason, we call it a \"sampler\" to express the idea of sampling the solution.\n",
"\n",
"In the above code, the `num_reads` argument is specified as the argument.\n",
"By putting an integer in this argument, you can specify the number of times to solve the puzzle per iteration.\n",
"When the value of `num_reads` is not specified, it will be executed with the default value `num_reads=1`.\n",
"\n",
"\n",
"### sample_ising(h, J), sample_qubo(Q)\n",
"As mentioned above, when solving a problem, the longitudinal magnetic fields `h` and the interaction coefficients `J` are set as variables and substituted, as in `.sample_ising(h, J)`.\n",
"\n",
"When performing optimization calculations for QUBO, we use `.sample_qubo(Q)`.\n",
"\n",
"### Response\n",
"\n",
"`.sample_ising(h, J)` returns the response class, which contains the solution obtained through the sampler and the energy of each solution.\n",
"The response class has various properties, and the main ones are:\n",
"\n",
"- `.states`: list[list[int]]]\n",
" - The number of num_reads count solutions is stored.\n",
" > In physics, an array of spins (solutions) is called a state. We use .states to show that multiple (num_reads times) states are stored.\n",
"- `.energies`: list[float]\n",
" - The energies of each solution for the num_reads times are stored.\n",
"- `.indices`: list[object]\n",
" - The solution is stored in .states, and the corresponding indices of each spin are stored in .indices.\n",
"- `.first.sample`: dict\n",
" - The minimum energy state is stored.\n",
"- `.first.energy`: float\n",
" - The minimum energy value is stored.\n",
"\n",
"> The response class inherits from the sample set class of D-Wave's dimod. More detailed information is described in the following link. \n",
"> [dimod documentation, SampleSet](https://docs.ocean.dwavesys.com/en/stable/docs_dimod/reference/sampleset.html#dimod.SampleSet)\n",
"\n",
"Let us take a look at an actual code.\n",
"Here, we try `num_reads=10` to get 10 solutions, and we use `SQASampler`, which is a sampler for simulated quantum annealing, instead of simulated annealing."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{'a': 1, 'b': 1, 'c': -1}\n",
"-4.0\n"
]
}
],
"source": [
"# The dictionary key which indicates the subscripts of h and J can also handle non-numeric values.\n",
"h = {'a': -1, 'b': -1}\n",
"J = {('a', 'b'): -1, ('b', 'c'): 1}\n",
"# By substituting 10 to the num_reads argument, we solve the calculation for 10 attempts with SQA in a single run.\n",
"sampler = oj.SQASampler(num_reads=10) \n",
"response = sampler.sample_ising(h, J)\n",
"print(response.first.sample)\n",
"print(response.first.energy)"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]\n",
" [ 1 1 -1]]\n"
]
}
],
"source": [
"# response.states contains 10 solutions.\n",
"print(response.states)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"> Parameters passed in the constructor, such as num_reads, can be overwritten by methods that perform sampling, such as ``.sample_ising``.\n",
"> ```\n",
"> response = sampler.sample_ising(h, J, num_reads=2)\n",
"> response.states\n",
"> > [[1, 1, -1],[1, 1, -1]]\n",
"> ```\n",
"\n",
"Since this problem is simple, we see the answer to be [1,1,-1] for all 10 times."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([-4., -4., -4., -4., -4., -4., -4., -4., -4., -4.])"
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Check energies.\n",
"response.energies"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"For all 10 times, the energy values are the same. \n",
"Since the solution in `response.states` is a list, we do not know how it corresponds to the string `a, b, c`. To find out, `response.variables` is useful."
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Variables(['a', 'b', 'c'])"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"response.variables"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To know the state with the smallest energy value, `.first` works well."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Sample(sample={'a': 1, 'b': 1, 'c': -1}, energy=-4.0, num_occurrences=1)"
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"response.first"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Optimization Calculations for Random QUBO Matrices\n",
"\n",
"Since the problems solved above are too easy, let us try to solve a slightly more difficult problem to end this tutorial.\n",
"\n",
"Here we solve a QUBO with 50 variables and randomly assigned $Q_{ij}$."
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [],
"source": [
"N = 50\n",
"# Randomly define Qij.\n",
"import random\n",
"Q = {(i, j): random.uniform(-1, 1) for i in range(N) for j in range(i+1, N)}\n",
"\n",
"# Solve with OpenJij.\n",
"sampler = oj.SASampler()\n",
"response = sampler.sample_qubo(Q, num_reads=100)"
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([-54.36073531, -54.48521983, -54.48521983, -54.48521983,\n",
" -54.48521983])"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Check the first couple of energies.\n",
"response.energies[:5]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When looking at the energy, we see that it takes on a different value than in the previous example.\n",
"If we give $Q_{ij}$ randomly, the problem generally becomes more difficult. Therefore, the SA sampler gives different solutions every time. \n",
"Let us visualize what kind of solution we get with a histogram of the energies."
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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b1KPgPUNAEBF8/bvt89XcAAAAIKNTwFn0KBB/hoHAACA3/CyTQAAYDl+ednmiRMntHz5cm3YsEG//PKL2rVrp8GDB0uS9u/fr19++UUtWrRQlSp+e7cnAABAuXxOHF988YXuuOMO5efnyxgjm82m48ePuwNOTk6O/va3v2nJkiXq06ePzwMGAAA4E5++otq6dau6deumAwcOaNiwYVq8eHGpJ6p69uypatWq6e233/ZpoAAAAN7y6QrO008/rZKSEq1YsUI33HBDmXXCwsJ0xRVX6Ouvv/alKwAAAK/5dAXnk08+Udu2bcsNN6dceOGF2r9/vy9dAQAAeM2ngFNUVKSEhIQz1jty5IiOHz/uS1cAAABe8yng1K1bV7t37z5jvW3btnkVhAAAAPzBp4DTuXNnbdq0SZ988km5dZYuXardu3erS5cuvnQFAADgNZ8CztixYxUWFqbevXtrxowZKigocK/7/fffNXv2bA0ZMkTVq1fXqFGjfB4sAACAN3wKOMnJyXrzzTflcrmUlpamCy+8UDabTXPnztUFF1yge+65R06nUwsWLFBSUpK/xgwAAHBaPr+qoXfv3vr22281bNgwJScnKyIiQmFhYWrUqJHuu+8+bdmyRTfddJM/xgoAAOAVv7yLqkGDBpo6daq+++47HTlyREePHtWuXbs0ffp0NW7c2Ke2J02aJJvNphEjRrjLSkpKNHToUNWuXVs1atRQ3759VVhY6ONeAAAAqwjql21u3LhRr732mi699FKP8pEjR+r999/XkiVLlJ2drf379/MaCAAA4Ba0Aefw4cMaMGCA3njjDdWqVctdXlxcrFmzZumll15S586d1bp1a2VmZmrt2rVat25dAEcMAACChU8BJzQ01OvlbN8kPnToUPXo0UOpqake5bm5uTp+/LhHeXJyshITE5WTk1Nue06nUw6Hw2MBAADW5NO7qBISEmSz2UqVu1wuFRQUuH+9uEGDBmfV7qJFi/TVV19p48aNpdYVFBQoLCxM0dHRHuWxsbEej6n/VUZGhp566qmzGgcAAKicfAo4eXl55a5zuVxavXq1hg8frksuuURvvvmmV23m5+dr+PDhWrVqlSIiInwZnof09HSP3+JxOBz8ujIAABZVYffghISEKDU1VR988IGWL1+uyZMne7Vdbm6uDh48qCuuuEJVqlRRlSpVlJ2drZdf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CDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByqgR6AAAAoOI0HLs8IP3mTeoRkH5PqdRXcKZNm6aGDRsqIiJC7dq104YNGwI9JAAAEAQqbcB56623NGrUKI0fP15fffWVWrVqpa5du+rgwYOBHhoAAAiwShtwXnrpJd1zzz26++671aJFC7366quqVq2aZs+eHeihAQCAAKuU9+AcO3ZMubm5Sk9Pd5eFhIQoNTVVOTk5ZW7jdDrldDrdn4uLiyVJDofD7+NzOf/we5veqoj9AWBtgTpncb46P6z273uqXWPMaetVyoDzyy+/6OTJk4qNjfUoj42N1fbt28vcJiMjQ0899VSp8oSEhAoZY6DYpwZ6BADgHc5X1lbR/76HDh2S3W4vd32lDDjnIj09XaNGjXJ/drlc+u2331S7dm3ZbLYAjuzcORwOJSQkKD8/X1FRUYEeTkAwB39iHpgDiTk4hXmw9hwYY3To0CHFx8eftl6lDDgXXHCBQkNDVVhY6FFeWFiouLi4MrcJDw9XeHi4R1l0dHRFDfG8ioqKstwBfLaYgz8xD8yBxBycwjxYdw5Od+XmlEp5k3FYWJhat26trKwsd5nL5VJWVpZSUlICODIAABAMKuUVHEkaNWqUBg0apDZt2qht27aaOnWqjhw5orvvvjvQQwMAAAFWaQNO//799fPPP2vcuHEqKCjQZZddppUrV5a68djKwsPDNX78+FJfvf03YQ7+xDwwBxJzcArzwBxIks2c6TkrAACASqZS3oMDAABwOgQcAABgOQQcAABgOQQcAABgOQScAGrYsKFsNpvHMmnSpDLr7t69WzVr1jyrHyf89ddfVb9+fdlsNhUVFbnL77rrrlL92mw2tWzZ0l3nySefLLU+OTn5XHe1XIGag08//bTMOSgoKPDYftq0aWrYsKEiIiLUrl07bdiw4Vx287QCNQfvvPOOunTpojp16igqKkopKSn68MMPPbY9X8eBFLh5kP48Hq644gqF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MM2bNzdXXXVVqfasek7wZg6C5ZxgTGDnIZjOC74i4ARIbm6uadeunbHb7SYiIsI0b97cTJw40f39alnKOoAzMzPN6XJqeQGnqKjIREZGmtdff73M7fr372/q1atnwsLCzIUXXmj69+9vdu/e7fX+eSOQczB58mTTuHFjExERYWJiYkynTp3M6tWrS237yiuvmMTERBMWFmbatm1r1q1bd9b7eTqBnINrr722zHsABg0a5K5zPo4DYwL/v4dPPvnEXHbZZSYsLMw0atTIZGZmltq2sh4Lq1evNikpKe52mzZtasaMGfNfdU7wZg6C5ZxgTGDnIZjOC76yGWPMebtcBAAAcB7wOzgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgAAMByCDgA/MZms51xueuuuwI9TAD/BXgXFQC/GzRoULnrrr766vM4EgD/rfglYwB+Y7PZJEmcVgAEGl9RAQAAyyHgAAgom82mhg0b6uTJk5o8ebIuuugihYeHKyEhQWPGjJHT6Sxzuz/++EMZGRm6/PLLVaNGDdWoUUPt27fX3LlzT9vPsWPHNGHCBCUnJys8PFy9e/d218nLy9Ptt9+uOnXqqHr16mrTpo0WLVqkvLw82Ww2derUyV03LS1NNptNr7/+ern71qxZM4WEhOj7778/p7kBcO4IOACCwu23365nnnlGzZo10w033KBDhw7pueee05AhQ0rVPXjwoFJSUvSPf/xDBQUFuvbaa9WxY0dt375dd911l4YNG1ZmHy6XS71799Zzzz2nxo0bq1evXqpXr54kaffu3Wrbtq3efPNNRUdH66abblL16tV1++23a+rUqaXauu+++yRJb7zxRpl9ZWdna+fOnbr++uvVqFGjc5wVAOcsoO8yB2ApkszZnlZObdO8eXNz4MABd/n3339voqOjjSSze/duj23+53/+x0gyw4cPNyUlJe7ygoIC06ZNGyPJ/Pvf/y6znyZNmpgff/yx1Diuv/56I8ncf//95sSJE+7ylStXmqpVqxpJ5tprr/XYpkOHDkaS+frrr0u1N2DAACPJvPXWW2czHQD8hIADwG9OhYjTLUuXLi1zm1WrVpVqLy0tzUgymZmZ7rKvv/7aSDJXXnmlOXnyZKltvvrqKyPJ3HTTTWX2s2TJklLb7Nq1y0gy0dHR5tChQ6XWnworfw048+bNM5LMgw8+6FH+22+/mYiICFOnTh3jdDpLtQeg4vGYOAC/O91j4omJiaXKqlatquuuu65U+UUXXSRJOnDggLvso48+kiT17t1bISGlv2U/dU/Ohg0bSq2z2Wzq2bNnqfI1a9ZIkrp166YaNWqUWt+/f38tWLCgVHm/fv00cuRILViwQM8//7yqVasmSZo/f75KSkqUlpamsLCwUtsBqHgEHAB+N2fOnLOqHxcXp9DQ0FLlNWvWlCSPG43z8vIkSY899pgee+yxctssKSkpVVa3bl2Fh4eXKj8VoBISEspsq6xQJkkREREaNGiQXnrpJS1ZssQd7GbOnClJ+vvf/17u+ABULAIOgIAr60pMeVwul6Q/fzCwcePGZ9VPRETEWdX3xn333acpU6bojTfe0KBBg7RhwwZt2bJFHTt2VLNmzfzeHwDvEHAAVCr169eX9OdXVA8//LBf2jz1JFV+fn6Z68srl/78Gu26667T6tWrtW3bNvdTVffee69fxgbg3PCYOIBKpUuXLpKkpUuX+q3NDh06SJI+/PBDHTlypNT6xYsXn3b7+++/X5L00ksvadGiRapVq5b69u3rt/EBOHsEHACVSrt27dSlSxetWbNGQ4cOlcPhKFVn8+bNWrlypddtNm3aVNdff71+//13jRkzxv01mCStWrVKixYtOu32vXv3VlxcnGbOnKnDhw/rzjvvrJCvwwB4j6+oAPjd6d4YnpiYqAkTJvjU/vz589WtWzdNnz5dCxcu1GWXXab4+HgVFxdry5Ytys/P1/Dhw9WtWzev25wxY4auuuoqTZs2TR999JHatGmj/fv36/PPP9eDDz6of/3rX+U+EVW1alUNHjxYEydOlMTXU0AwIOAA8LvyXpcgSa1atfI54NStW1dr167VG2+8oUWLFunrr7/W2rVrFRsbq0aNGumhhx7SrbfeelZtNm3aVOvXr9djjz2mjz76SMuWLVNycrLmzp2rpKQk/etf/1Lt2rXL3b5z586aOHGiUlJS1LJlS5/2D4DveJs4AJzBpEmTlJ6erkmTJmnMmDFl1rnvvvv0+uuvKzMz87RXsACcHwQcANCfv5vz/fffq0WLFh7ln3zyiXr16qWjR49q9+7datCgQaltf/jhBzVv3lzVq1fXvn37FBkZeb6GDaAcfEUFAJKKiorUsmVLNWvWTE2bNlVERIR27dqlzZs3S5JeeOGFUuHm+eef15YtW7Rq1SodPXpUGRkZhBsgSHAFBwAkHT16VOPGjdOqVauUn58vh8Oh6OhoXXnllRo2bJi6d+9eaptOnTopOztb8fHxuueeezR+/HjZbLYAjB7AXxFwAACA5fA7OAAAwHIIOAAAwHIIOAAAwHIIOAAAwHIIOAAAwHIIOAAAwHIIOAAAwHIIOAAAwHIIOAAAwHL+HxeGEe2GhqfIAAAAAElFTkSuQmCC\n",
"text/plain": [
"<Figure size 640x480 with 1 Axes>"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"import matplotlib.pyplot as plt\n",
"plt.hist(response.energies, bins=15)\n",
"plt.xlabel('Energy', fontsize=15)\n",
"plt.ylabel('Frequency', fontsize=15)\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Lower energy represents a better state. The histogram above shows that in some cases, a high energy state is also calculated, but the majority of the results represent the lowest energy states.\n",
"The lowest energy state of the solved (sampled) states should be the closest to the optimal solution, and that solution can be found in `.states`.\n",
"> Note: SA does not necessarily lead to the optimal solution. Therefore, there is no guarantee that the solution with the lowest energy is the optimal solution. It is only an approximate solution."
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Sample(sample={0: 0, 1: 0, 2: 0, 3: 1, 4: 1, 5: 1, 6: 1, 7: 1, 8: 1, 9: 0, 10: 1, 11: 1, 12: 0, 13: 1, 14: 1, 15: 0, 16: 1, 17: 0, 18: 1, 19: 0, 20: 0, 21: 0, 22: 1, 23: 1, 24: 0, 25: 0, 26: 0, 27: 1, 28: 0, 29: 1, 30: 1, 31: 1, 32: 1, 33: 1, 34: 1, 35: 1, 36: 0, 37: 1, 38: 0, 39: 1, 40: 1, 41: 0, 42: 1, 43: 0, 44: 1, 45: 0, 46: 0, 47: 0, 48: 1, 49: 0}, energy=-54.48521983429423, num_occurrences=1)"
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import numpy as np\n",
"\n",
"min_samples = response.first\n",
"min_samples"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We now have the solution with the lowest energy. The state in `.first` is the approximate solution obtained this time. This means that we have \"approximately solved the problem.\"\n",
"\n",
"Here `num_occurrences` is the number of times the state was output as a result of the calculation."
]
}
],
"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.9.15"
},
"vscode": {
"interpreter": {
"hash": "2e8d7574d7ec71e14cb1575cf43673432d6fae464c836a7b3733d4f6c20243fb"
}
}
},
"nbformat": 4,
"nbformat_minor": 4
}