Anneal Results

These objects are defined to deal with the output of the annealing functions.

class qubovert.sim.AnnealResults(iterable=())

AnnealResults.

An object to manage accessing the results of the simulated annealing functions. AnnealResults is a subclass of list.

Let res be the output of one of the simulated annealing functions. Then a user can access the best result with res.best. The best state will be res.best.state and its corresponding value res.best.value.

The user can iterate through all of the results with

>>> for r in res:
>>>     print(r.state, r.value)

The user can sort the results from best to worst with res.sort(). Then iterating through res will be in that order.

The user can also convert each result state to/from boolean and spin states.

__init__.

Parameters: iterable (any iterable (optional, defaults to ()).) – The iterable should contain only qubovert.sim.AnnealResult objects.

add_state(state, value, spin)

add_state.

Add the state to the record.

Parameters

state (dict.) – Maps variable labels to their values.
value (number.) – The value of the model with state.
spin (bool.) – Whether it is from a spin or boolean model.

Returns

Return type

None.

append(result)

append.

Add the result to the record at the end and update the best attribute if needed.

Parameters: result (AnnealResult object.) – See help(qubovert.sim.AnnealResult).
Returns
Return type: None.

apply_function(func)

apply_function.

Apply the function func to each element in self to create a new version of self.

Parameters: func (function.) – func takes in a qubovert.sim.AnnealResult object and returns a qubovert.sim.AnnealResult object.
Returns: res
Return type: qubovert.sim.AnnealResults object.

Example

>>> import qubovert as qv
>>>
>>> model = qv.boolean_var('a') * qv.boolean_var('b')
>>> qubo = model.to_qubo()
>>> anneal_res = qv.sim.anneal_qubo(qubo, num_anneals=3)
>>> anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]
>>> new_res = anneal_res.apply_function(
        lambda x: qv.sim.AnnealResult(
            model.convert_solution(x.state), x.value, x.spin
        )
    )
>>> new_res
[AnnealResult(state={'a': 0, 'b': 1}, value=0, spin=False),
 AnnealResult(state={'a': 0, 'b': 0}, value=0, spin=False),
 AnnealResult(state={'a': 0, 'b': 0}, value=0, spin=False)]

clear()

clear.

Override list.clear so that it also removes self.best.

convert_states(func)

convert_states.

Apply the function func to each state in self to create a new version of self.

Parameters: func (function.) – func takes in a dict that maps variable names to their values, and returns a dict.
Returns: res
Return type: qubovert.sim.AnnealResults object.

Example

>>> import qubovert as qv
>>>
>>> model = qv.boolean_var('a') * qv.boolean_var('b')
>>> qubo = model.to_qubo()
>>> anneal_res = qv.sim.anneal_qubo(qubo, num_anneals=3)
>>> anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]
>>> new_res = anneal_res.convert_states(model.convert_solution)
>>> new_res
[AnnealResult(state={'a': 0, 'b': 1}, value=0, spin=False),
 AnnealResult(state={'a': 0, 'b': 0}, value=0, spin=False),
 AnnealResult(state={'a': 0, 'b': 0}, value=0, spin=False)]

copy()

copy.

Returns: res – A deep copy of self.
Return type: AnnealResults object.

count(value, /): Return number of occurrences of value.

extend(other)

extend.

Override list.extend to keep track of best attribute. Updates in place.

Parameters: other (qubovert.sim.AnnealResults object or iterable.) –

filter(func)

filter.

Return a new AnnealResults object whose elements are filtered by the function func. func takes in a qubovert.sim.AnnealResult object and returns a boolean indicating whether it should remain in the filtered results.

Parameters: func (function.) – func takes in a qubovert.sim.AnnealResult object and returns a boolean indicating whether it should remain in the filtered results.
Returns: res
Return type: qubovert.sim.AnnealResults object.

Example

>>> import qubovert as qv
>>>
>>> model = qv.boolean_var(0) * qv.boolean_var(1)
>>> anneal_res = qv.sim.anneal_qubo(model, num_anneals=3)
>>>
>>> anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 1, 1: 0}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]
>>> filtered_anneal_res = anneal_res.filter(
>>>     lambda x: x.state[0] == 0
>>> )
>>> filtered_anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]

filter_states(func)

filter_states.

Return a new AnnealResults object whose states are filtered by the function func. func takes in a dict representing a state and returns a boolean indicating whether it should remain in the filtered results.

Parameters: func (function.) – func takes in a dict representing a state and returns a boolean indicating whether it should remain in the filtered results.
Returns: res
Return type: qubovert.sim.AnnealResults object.

Example

>>> import qubovert as qv
>>>
>>> model = qv.boolean_var(0) * qv.boolean_var(1)
>>> anneal_res = qv.sim.anneal_qubo(model, num_anneals=3)
>>>
>>> anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 1, 1: 0}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]
>>> filtered_anneal_res = anneal_res.filter_states(
>>>     lambda x: x[0] == 0
>>> )
>>> filtered_anneal_res
[AnnealResult(state={0: 0, 1: 1}, value=0, spin=False),
 AnnealResult(state={0: 0, 1: 0}, value=0, spin=False)]

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, result)

insert.

Add the result to the record at index index and update the best attribute if needed.

Parameters: result (AnnealResult object.) – See help(qubovert.sim.AnnealResult).
Returns
Return type: None.

pop(index)

pop.

Override list.pop so we also update the best attribute. Remove and return the element in the index index, or raise an IndexError.

Parameters: index (int.) –
Returns: res – The element at index.
Return type: AnnealResult object.

remove(result)

remove.

Override list.remove so we also update the best attribute. Remove the first occurrence of result, or raise ValueError.

Parameters: result (AnnealResult object.) – See help(qubovert.sim.AnnealResult).
Returns
Return type: None

reverse(): Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_boolean()

to_boolean.

Convert each result to a boolean result. Note that if self.spin is False, then this function will just return a copy of self.

Returns: res
Return type: AnnealResults object.

to_spin()

to_spin.

Convert each result to a spin result. Note that if self.spin is True, then this function will just return a copy of self.

Returns: res
Return type: AnnealResults object.

class qubovert.sim.AnnealResult(state, value, spin)

AnnealResult.

This class deals with an individual result from an anneal. See the below example.

Example

In this example, res represents a state the gives value -2, and is part of a spin model.

>>> from qubovert.sim import AnnealResult
>>>
>>> res = AnnealResult({0: 1, 1: -1, 2: -1}, -2, True)
>>> print(res.state)
{0: 1, 1: -1, 2: -1}
>>> print(res.value)
-2
>>> print(res.spin)
True

We can convert it to a boolean state with

>>> boolean_res = res.to_boolean()
>>> print(boolean_res.state)
{0: 0, 1: 1, 2: 1}
>>> print(boolean_res.value)
-2
>>> print(boolean_res.spin)
False

__init__.

Parameters

state (dict.) – Maps binary labels to their values.
value (number.) – The value of the model with state.
spin (bool.) – Indicates whether state came from a boolean or spin model.

copy()

copy.

Return a copy of self.

Returns: res
Return type: AnnealResult.

to_boolean()

to_boolean.

Convert the result to a boolean result.

Returns: res – A boolean version of self. If self.spin == False, then res will be the same as self.
Return type: AnnealResult object.

to_spin()

to_spin.

Convert the result to a spin result.

Returns: res – A spin version of self. If self.spin == True, then res will be the same as self.
Return type: AnnealResult object.