Annealing
These function interface with C source code to provide fast execution of the simulated annealing algorithm. Note that the sim
module will not be imported with from qubovert import *
. You must import qubovert.sim
explicitly. Here we show some functions to use the boolean and spin simulation to run simulated annealing on the models.
Please note that the qv.sim.anneal_qubo
and qv.sim.anneal_quso
functions perform faster than the qv.sim.anneal_pubo
and qv.sim.anneal_puso
functions. If your system has degree 2 or less, then you should use the QUBO or QUSO anneal functions!
Anneal PUBO
- qubovert.sim.anneal_pubo(P, num_anneals=1, anneal_duration=1000, initial_state=None, temperature_range=None, schedule='geometric', in_order=True, seed=None)
anneal_pubo.
Run a simulated annealing algorithm to try to find the minimum of the PUBO given by
P
.anneal_pubo
convertsP
to a PUSO and then usesqubovert.sim.anneal_quso
. Please see all the parameters for details.Please note that the
qv.sim.anneal_qubo
function performs faster than theqv.sim.anneal_pubo
function. If your system has degree 2 or less, then you should use theqv.sim.anneal_qubo
function.- Parameters
P (dict, or any type in
qubovert.BOOLEAN_MODELS
.) – Maps boolean labels to their values in the objective function. Please see the docstrings of any of the objects inqubovert.BOOLEAN_MODELS
to see howP
should be formatted.num_anneals (int >= 1 (optional, defaults to 1)) – The number of times to run the simulated annealing algorithm.
anneal_duration (int >= 1 (optional, defaults to 1000)) – The total number of updates to the simulation during the anneal. This is related to the amount of time we spend in the cooling schedule. If an explicit schedule is provided, then
anneal_duration
will be ignored.initial_state (dict (optional, defaults to None)) – The initial state to start the anneal in.
initial_state
must map the spin label names to their values in {0, 1}. Ifinitial_state
is None, then a random state will be chosen to start each anneal. Otherwise,initial_state
will be the starting state for all of the anneals.temperature_range (tuple (optional, defaults to None)) – The temperature to start and end the anneal at.
temperature = (T0, Tf)
.T0
must be >=Tf
. To see more details on picking a temperature range, please see the functionqubovert.sim.anneal_temperature_range
. Iftemperature_range
is None, then it will by default be set toT0, Tf = qubovert.sim.anneal_temperature_range(P, spin=False)
.schedule (str or iterable of tuple (optional, defaults to
'geometric'
)) – What type of cooling schedule to use. Ifschedule == 'linear'
, then the cooling schedule will be a linear interpolation between the values intemperature_range
. Ifschedule == 'geometric'
, then the cooling schedule will be a geometric interpolation between the values intemperature_range
. Otherwise, you can supply an explicit schedule. In this case,schedule
should be an iterable of tuples, where each tuple is a(T, n)
pair, whereT
denotes the temperature to update the simulation, andn
denote the number of times to update the simulation at that temperature. This schedule will be sent directly into thequbovert.sim.PUBOSimulation.schedule_update
method.in_order (bool (optional, defaults to True)) – Whether to iterate through the variables in order or randomly during an update step. When
in_order
is False, the simulation is more physically realistic, but when using the simulation for annealing, often it is better to havein_order = True
.seed (number (optional, defaults to None)) – The number to seed Python’s builtin
random
module with. Ifseed is None
, thenrandom.seed
will not be called.
- Returns
res –
res
contains information on the final states of the simulations. See Examples below for an example of how to read fromres
. Seehelp(qubovert.sim.AnnealResults)
for more info.- Return type
qubovert.sim.AnnealResults object.
- Raises
ValueError – If the
schedule
argument provided is formatted incorrectly. See the Parameters section.ValueError – If the initial temperature is less than the final temperature.
- Warns
qubovert.utils.QUBOVertWarning – If both the
temperature_range
and explicitschedule
arguments are provided.qubovert.utils.QUBOVertWarning – If the degree of the model is 2 or less then a warning is issued that says you should use the
anneal_qubo
oranneal_quso
functions.
Example
Consider the example of finding the ground state of the 1D antiferromagnetic Ising chain of length 5 in boolean form.
>>> import qubovert as qv >>> >>> H = sum(qv.spin_var(i) * qv.spin_var(i+1) for i in range(4)) >>> P = H.to_pubo() >>> anneal_res = qv.sim.anneal_pubo(P, num_anneals=3) >>> >>> print(anneal_res.best.value) -4 >>> print(anneal_res.best.state) {0: 0, 1: 1, 2: 0, 3: 1, 4: 0} >>> # now sort the results >>> anneal_res.sort() >>> >>> # now iterate through all of the results in the sorted order >>> for res in anneal_res: >>> print(res.value, res.state) -4, {0: 0, 1: 1, 2: 0, 3: 1, 4: 0} -4, {0: 1, 1: 0, 2: 1, 3: 0, 4: 1} -4, {0: 0, 1: 1, 2: 0, 3: 1, 4: 0}
Anneal PUSO
- qubovert.sim.anneal_puso(H, num_anneals=1, anneal_duration=1000, initial_state=None, temperature_range=None, schedule='geometric', in_order=True, seed=None)
anneal_puso.
Run a simulated annealing algorithm to try to find the minimum of the PUSO given by
H
. Please see all of the parameters for details.Please note that the
qv.sim.anneal_quso
function performs faster than theqv.sim.anneal_puso
function. If your system has degree 2 or less, then you should use theqv.sim.anneal_quso
function.- Parameters
H (dict, or any type in
qubovert.SPIN_MODELS
.) – Maps spin labels to their values in the Hamiltonian. Please see the docstrings of any of the objects inqubovert.SPIN_MODELS
to see howH
should be formatted.num_anneals (int >= 1 (optional, defaults to 1)) – The number of times to run the simulated annealing algorithm.
anneal_duration (int >= 1 (optional, defaults to 1000)) – The total number of updates to the simulation during the anneal. This is related to the amount of time we spend in the cooling schedule. If an explicit schedule is provided, then
anneal_duration
will be ignored.initial_state (dict (optional, defaults to None)) – The initial state to start the anneal in.
initial_state
must map the spin label names to their values in {1, -1}. Ifinitial_state
is None, then a random state will be chosen to start each anneal. Otherwise,initial_state
will be the starting state for all of the anneals.temperature_range (tuple (optional, defaults to None)) – The temperature to start and end the anneal at.
temperature = (T0, Tf)
.T0
must be >=Tf
. To see more details on picking a temperature range, please see the functionqubovert.sim.anneal_temperature_range
. Iftemperature_range
is None, then it will by default be set toT0, Tf = qubovert.sim.anneal_temperature_range(H, spin=True)
. Note that a temperature can only be zero ifschedule
is explicitly given or ifschedule
is linear.schedule (str, or list of floats (optional, defaults to
'geometric'
).) – What type of cooling schedule to use. Ifschedule == 'linear'
, then the cooling schedule will be a linear interpolation between the values intemperature_range
. Ifschedule == 'geometric'
, then the cooling schedule will be a geometric interpolation between the values intemperature_range
. Otherwise,schedule
must be an iterable of floats being the explicit temperature schedule for the anneal to follow.in_order (bool (optional, defaults to True)) – Whether to iterate through the variables in order or randomly during an update step. When
in_order
is False, the simulation is more physically realistic, but when using the simulation for annealing, often it is better to havein_order = True
.seed (number (optional, defaults to None)) – The number to seed Python’s builtin
random
module with. Ifseed is None
, thenrandom.seed
will not be called.
- Returns
res –
res
contains information on the final states of the simulations. See Examples below for an example of how to read fromres
. Seehelp(qubovert.sim.AnnealResults)
for more info.- Return type
qubovert.sim.AnnealResults object.
- Raises
ValueError – If the
schedule
argument provided is formatted incorrectly. See the Parameters section.ValueError – If the initial temperature is less than the final temperature.
- Warns
qubovert.utils.QUBOVertWarning – If both the
temperature_range
and explicitschedule
arguments are provided.qubovert.utils.QUBOVertWarning – If the degree of the model is 2 or less then a warning is issued that says you should use the
anneal_qubo
oranneal_quso
functions.
Example
Consider the example of finding the ground state of the 1D antiferromagnetic Ising chain of length 5.
>>> import qubovert as qv >>> >>> H = sum(qv.spin_var(i) * qv.spin_var(i+1) for i in range(4)) >>> anneal_res = qv.sim.anneal_puso(H, num_anneals=3) >>> >>> print(anneal_res.best.value) -4 >>> print(anneal_res.best.state) {0: 1, 1: -1, 2: 1, 3: -1, 4: 1} >>> # now sort the results >>> anneal_res.sort() >>> >>> # now iterate through all of the results in the sorted order >>> for res in anneal_res: >>> print(res.value, res.state) -4, {0: 1, 1: -1, 2: 1, 3: -1, 4: 1} -4, {0: -1, 1: 1, 2: -1, 3: 1, 4: -1} -4, {0: 1, 1: -1, 2: 1, 3: -1, 4: 1}
Anneal QUBO
- qubovert.sim.anneal_qubo(Q, num_anneals=1, anneal_duration=1000, initial_state=None, temperature_range=None, schedule='geometric', in_order=True, seed=None)
anneal_qubo.
Run a simulated annealing algorithm to try to find the minimum of the QUBO given by
Q
.anneal_qubo
convertsQ
to a QUSO and then usesqubovert.sim.anneal_quso
. Please see all of the parameters for details.- Parameters
Q (dict,
qubovert.utils.QUBOMatrix
orqubovert.QUBO
.) – Maps boolean labels to their values in the objective function. Please see the docstring ofqubovert.QUBO
for more info on how to formatQ
.num_anneals (int >= 1 (optional, defaults to 1)) – The number of times to run the simulated annealing algorithm.
anneal_duration (int >= 1 (optional, defaults to 1000)) – The total number of updates to the simulation during the anneal. This is related to the amount of time we spend in the cooling schedule. If an explicit schedule is provided, then
anneal_duration
will be ignored.initial_state (dict (optional, defaults to None)) – The initial state to start the anneal in.
initial_state
must map the spin label names to their values in {0, 1}. Ifinitial_state
is None, then a random state will be chosen to start each anneal. Otherwise,initial_state
will be the starting state for all of the anneals.temperature_range (tuple (optional, defaults to None)) – The temperature to start and end the anneal at.
temperature = (T0, Tf)
.T0
must be >=Tf
. To see more details on picking a temperature range, please see the functionqubovert.sim.anneal_temperature_range
. Iftemperature_range
is None, then it will by default be set toT0, Tf = qubovert.sim.anneal_temperature_range(Q, spin=False)
.schedule (str or iterable of tuple (optional, defaults to
'geometric'
)) – What type of cooling schedule to use. Ifschedule == 'linear'
, then the cooling schedule will be a linear interpolation between the values intemperature_range
. Ifschedule == 'geometric'
, then the cooling schedule will be a geometric interpolation between the values intemperature_range
. Otherwise, you can supply an explicit schedule. In this case,schedule
should be an iterable of tuples, where each tuple is a(T, n)
pair, whereT
denotes the temperature to update the simulation, andn
denote the number of times to update the simulation at that temperature. This schedule will be sent directly into thequbovert.sim.PUBOSimulation.schedule_update
method.in_order (bool (optional, defaults to True)) – Whether to iterate through the variables in order or randomly during an update step. When
in_order
is False, the simulation is more physically realistic, but when using the simulation for annealing, often it is better to havein_order = True
.seed (number (optional, defaults to None)) – The number to seed Python’s builtin
random
module with. Ifseed is None
, thenrandom.seed
will not be called.
- Returns
res –
res
contains information on the final states of the simulations. See Examples below for an example of how to read fromres
. Seehelp(qubovert.sim.AnnealResults)
for more info.- Return type
qubovert.sim.AnnealResults object.
- Raises
ValueError – If the
schedule
argument provided is formatted incorrectly. See the Parameters section.ValueError – If the initial temperature is less than the final temperature.
- Warns
qubovert.utils.QUBOVertWarning – If both the
temperature_range
and explicitschedule
arguments are provided.
Example
Consider the example of finding the ground state of the 1D antiferromagnetic Ising chain of length 5 in boolean form.
>>> import qubovert as qv >>> >>> H = sum(qv.spin_var(i) * qv.spin_var(i+1) for i in range(4)) >>> Q = H.to_qubo() >>> anneal_res = qv.sim.anneal_qubo(Q, num_anneals=3) >>> >>> print(anneal_res.best.value) -4 >>> print(anneal_res.best.state) {0: 0, 1: 1, 2: 0, 3: 1, 4: 0} >>> # now sort the results >>> anneal_res.sort() >>> >>> # now iterate through all of the results in the sorted order >>> for res in anneal_res: >>> print(res.value, res.state) -4, {0: 0, 1: 1, 2: 0, 3: 1, 4: 0} -4, {0: 1, 1: 0, 2: 1, 3: 0, 4: 1} -4, {0: 0, 1: 1, 2: 0, 3: 1, 4: 0}
Anneal QUSO
- qubovert.sim.anneal_quso(L, num_anneals=1, anneal_duration=1000, initial_state=None, temperature_range=None, schedule='geometric', in_order=True, seed=None)
anneal_quso.
Run a simulated annealing algorithm to try to find the minimum of the QUSO given by
L
. Please see all of the parameters for details.- Parameters
L (dict,
qubovert.utils.QUSOMatrix
orqubovert.QUSO
.) – Maps spin labels to their values in the objective function. Please see the docstring ofqubovert.QUSO
for more info on how to formatL
.num_anneals (int >= 1 (optional, defaults to 1)) – The number of times to run the simulated annealing algorithm.
anneal_duration (int >= 1 (optional, defaults to 1000)) – The total number of updates to the simulation during the anneal. This is related to the amount of time we spend in the cooling schedule. If an explicit schedule is provided, then
anneal_duration
will be ignored.initial_state (dict (optional, defaults to None)) – The initial state to start the anneal in.
initial_state
must map the spin label names to their values in {1, -1}. Ifinitial_state
is None, then a random state will be chosen to start each anneal. Otherwise,initial_state
will be the starting state for all of the anneals.temperature_range (tuple (optional, defaults to None)) – The temperature to start and end the anneal at.
temperature = (T0, Tf)
.T0
must be >=Tf
. To see more details on picking a temperature range, please see the functionqubovert.sim.anneal_temperature_range
. Iftemperature_range
is None, then it will by default be set toT0, Tf = qubovert.sim.anneal_temperature_range(L, spin=True)
.schedule (str, or list of floats (optional, defaults to
'geometric'
).) – What type of cooling schedule to use. Ifschedule == 'linear'
, then the cooling schedule will be a linear interpolation between the values intemperature_range
. Ifschedule == 'geometric'
, then the cooling schedule will be a geometric interpolation between the values intemperature_range
. Otherwise,schedule
must be an iterable of floats being the explicit temperature schedule for the anneal to follow.in_order (bool (optional, defaults to True)) – Whether to iterate through the variables in order or randomly during an update step. When
in_order
is False, the simulation is more physically realistic, but when using the simulation for annealing, often it is better to havein_order = True
.seed (number (optional, defaults to None)) – The number to seed Python’s builtin
random
module with. Ifseed is None
, thenrandom.seed
will not be called.
- Returns
res –
res
contains information on the final states of the simulations. See Examples below for an example of how to read fromres
. Seehelp(qubovert.sim.AnnealResults)
for more info.- Return type
qubovert.sim.AnnealResults object.
- Raises
ValueError – If the
schedule
argument provided is formatted incorrectly. See the Parameters section.ValueError – If the initial temperature is less than the final temperature.
ValueError – If
L
is not degree 2 or less.
- Warns
qubovert.utils.QUBOVertWarning – If both the
temperature_range
and explicitschedule
arguments are provided.
Example
Consider the example of finding the ground state of the 1D antiferromagnetic Ising chain of length 5.
>>> import qubovert as qv >>> >>> H = sum(qv.spin_var(i) * qv.spin_var(i+1) for i in range(4)) >>> anneal_res = qv.sim.anneal_quso(H, num_anneals=3) >>> >>> print(anneal_res.best.value) -4 >>> print(anneal_res.best.state) {0: 1, 1: -1, 2: 1, 3: -1, 4: 1} >>> # now sort the results >>> anneal_res.sort() >>> >>> # now iterate through all of the results in the sorted order >>> for res in anneal_res: >>> print(res.value, res.state) -4, {0: 1, 1: -1, 2: 1, 3: -1, 4: 1} -4, {0: -1, 1: 1, 2: -1, 3: 1, 4: -1} -4, {0: 1, 1: -1, 2: 1, 3: -1, 4: 1}
Anneal temperature range
The following function is used to determine the default annealing temperatures to start and stop at for the above anneal functions if the user does not supply a range themselves.
- qubovert.sim.anneal_temperature_range(model, start_flip_prob=0.5, end_flip_prob=0.01, spin=False)
anneal_temperature_range.
Calculate the temperature to start and end an anneal of
model
, such that at the start of the anneal there is astart_flip_prob
probability that a bit is flipped despite it being energetically unfavorable, and at the end of the anneal there is aend_flip_prob
probability that a bit is flipped despite it being energetically unfavorable.- Parameters
model (dict, or any type in
qubovert.SPIN_MODELS
orBOOLEAN_MODELS
) – Dictionary mapping tuples of binary labels to their values. See any of the docstrings of a type inqubovert.SPIN_MODELS
orBOOLEAN_MODELS
for more info.start_flip_prob (float in [0, 1) (optional, defaults to 0.5)) – The desired probability that a bit flips despite it being energetically unfavorable at the start of the anneal.
start_flip_prob
must be greater thanend_flip_prob
.end_flip_prob (float in [0, 1) (optional, defaults to 0.01)) – The desired probability that a bit flips despite it being energetically unfavorable at the end of the anneal.
end_flip_prob
must be less thanstart_flip_prob
.spin (bool (optional, default to False)) –
spin
should be True ifmodel
is a spin model (ieisinstance(model, qubovert.SPIN_MODELS)
) and should be False ifmodel
is a boolean model (ieisinstance(model, qubovert.BOOLEAN_MODELS)
).
- Returns
temp_range – The
hot
temperature is the temperature to start the anneal at, and thecold
temperature is the temperature to end the anneal at. Note thathot >= cold
.- Return type
tuple (hot, cold)