Parent Classes

Note that the utils module will not be imported with from qubovert import *. You must import qubovert.utils explicitly.

Accessed with qubovert.utils.class_name

DictArithmetic

class qubovert.utils.DictArithmetic(*args, **kwargs)

DictArithmetic.

A class to handle dictionaries. It is the same thing as a dictionary with some methods modified.

One method is that values will always default to 0. Consider the following example:

>>> d = DictArithmetic()
>>> print(d[(0, 0)]) # will print 0
>>> d[(0, 0)] += 1
>>> print(d) # will print {(0, 0): 1}

Compared to an ordinary dictionary.

>>> g = dict()
>>> print(g[(0, 0)]) # will raise KeyError
>>> g[(0, 0)] += 1 # will raise KeyError, since (0, 0) was never set

One method is that if we set an item to 0, it will be removed. Consider the following example:

>>> d = DictArithmetic()
>>> d[(0, 0)] += 1
>>> d[(0, 0)] -= 1
>>> print(d) # will print {}

One method is that if we initialize DictArithmetic with a previous dictionary it will be reinitialized to ensure that the DictArithmetic contains no zero values. Consider the following example:

>>> d = DictArithmetic({0: 1, (1, 0): 2, (2, 0): 0})
>>> print(d) # will print {0: 1, (1, 0): 2}

We also change the update method so that it follows all the conventions.

>>> d = DictArithmetic({'a': 1, (0, 1): 2})
>>> d.update({'a': 0, (1, 1): -1})
>>> print(d)  # will print {(0, 1): 2, (1, 1): -1}

We also include arithmetic, addition, subtraction, scalar division, scalar multiplication, and all those in place. For example,

>>> d = DictArithmetic({(0, 0): 1, (0, 1): -2})
>>> g = d + {(0, 0): -1}
>>> print(g) # will print {(0, 1): -2}
>>> g *= 4
>>> print(g) # will print {(0, 1): -8}
>>> g -= {(0, 1): -8}
>>> print(g) # will print {}

Adding or subtracting constants will update the () element of the dict.

>>> d = DictArithmetic()
>>> d += 5
>>> print(d)
{(): 5}

You can give it a name.

>>> d = DictArithmetic()
>>> d.name
None
>>> d.name = 'd'
>>> d.name
'd'

__init__.

Initialize the object. If you supply args and kwargs that represent a dictionary, they will be reinitialized to follow the conventions set in __setitem__.

Parameters: arguments (define a dictionary with dict(*args, **kwargs).) – The dictionary will be initialized to follow all the convensions of the class.

clear() → None. Remove all items from D.

copy()

copy.

Same as dict.copy, but we adjust the method so that it returns a DictArithmetic object, or whatever object is the subclass.

Returns: d – Same as self.__class__.
Return type: DictArithmetic object, or subclass of.

classmethod create_var(name)

create_var.

Create the variable with name name.

Parameters: name (hashable object allowed as a key.) – Name of the variable.
Returns: res – The model representing the variable with type cls.
Return type: cls object.

Examples

>>> from qubovert.utils import DictArithmetic
>>>
>>> x = DictArithmetic.create_var('x')
>>> x == DictArithmetic({('x',): 1})
True
>>> isinstance(x, DictArithmetic)
True
>>> x.name
'x'

>>> from qubovert import QUSO
>>>
>>> z = QUSO.create_var('z')
>>> print(z)
{('z',): 1}
>>> print(isinstance(z, QUSO))
True
>>> print(z.name)
'z'

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

property name

name.

Return the name of the object.

Returns: name
Return type: object.

Example

>>> d = DictArithmetic()
>>> d.name
None
>>> d.name = 'd'
>>> d.name
'd'

normalize(value=1)

normalize.

Normalize the coefficients to a maximum magnitude.

Parameters: value (float (optional, defaults to 1)) – Every coefficient value will be normalized such that the coefficient with the maximum magnitude will be +/- 1.

Examples

>>> from qubovert.utils import DictArithmetic
>>> d = DictArithmetic({(0, 1): 1, (1, 2, 'x'): 4})
>>> d.normalize()
>>> print(d)
{(0, 1): 0.25, (1, 2, 'x'): 1}

>>> from qubovert.utils import DictArithmetic
>>> d = DictArithmetic({(0, 1): 1, (1, 2, 'x'): -4})
>>> d.normalize()
>>> print(d)
{(0, 1): 0.25, (1, 2, 'x'): -1}

>>> from qubovert import PUBO
>>> d = PUBO({(0, 1): 1, (1, 2, 'x'): 4})
>>> d.normalize()
>>> print(d)
{(0, 1): 0.25, (1, 2, 'x'): 1}

>>> from qubovert.utils import PUBO
>>> d = PUBO({(0, 1): 1, (1, 2, 'x'): -4})
>>> d.normalize()
>>> print(d)
{(0, 1): 0.25, (1, 2, 'x'): -1}

property num_terms

num_terms.

Return the number of terms in the dictionary.

Returns: n – Number of terms in the dictionary.
Return type: int.

pop(k[, d]) → v, remove specified key and return the corresponding value.: If key is not found, d is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

pretty_str(var_prefix='x')

pretty_str.

Return a pretty string representation of the model.

Parameters: var_prefix (str (optional, defaults to 'x').) – The prefix for the variables.
Returns: res
Return type: str.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

simplify()

simplify.

If self has any symbolic expressions, this will go through and simplify them. This will also make everything a float!

Returns
Return type: None. Updates it in place.

subgraph(nodes, connections=None)

subgraph.

Create the subgraph of self that only includes vertices in nodes, and external nodes are given the values in connections.

Parameters

nodes (set.) – Nodes of self to include in the subgraph.
connections (dict (optional, defaults to {})) – For each node in self that is not in nodes, we assign a value given by connections.get(node, 0).

Returns

D – The subgraph of self with nodes in nodes and the values of the nodes not included given by connections.

Return type

same as type(self)

Notes

Any offset value included in self (ie {(): 1}) will be ignored, however there may be an offset in the output D.

Examples

>>> G = DictArithmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2}
>>> )
>>> D = G.subgraph({0, 2}, {1: 5})
>>> D
{(0,): -17, (0, 2): -1, (): 10}

>>> G = DictArithmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2}
>>> )
>>> D = G.subgraph({0, 2})
>>> D
{(0, 2): -1, (0,): 3}

>>> G = DictArithmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2}
>>> )
>>> D = G.subgraph({0, 1}, {2: -10})
>>> D
{(0, 1): -4, (0,): 13, (1,): 2}

>>> G = DictArithmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2}
>>> )
>>> D = G.subgraph({0, 1})
>>> D
{(0, 1): -4, (0,): 3, (1,): 2}

subs(*args, **kwargs)

subs.

Replace any sympy symbols that are used in the dict with values. Please see help(sympy.Symbol.subs) for more info.

Parameters: arguments (substitutions.) – Same parameters as are inputted into sympy.Symbol.subs.
Returns: res – Same as self but with all the symbols replaced with values.
Return type: DictArithmetic object.

subvalue(values)

subvalue.

Replace each element in self with a value in values if it exists.

Parameters: values (dict.) – For each node v in self that is in values, we replace the node with values[v].
Returns: D
Return type: same as type(self)

Examples

>>> G = DictArithmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2
>>> }
>>> D = G.subvalue({0: 2})
>>> D
{(1,): -6, (2,): -2, (): 8}

>>> G = DictArtihmetic(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2
>>> }
>>> D = G.subvalue({2: -3})
>>> D
{(0, 1): -4, (0,): 6, (1,): 2, (): 2}

>>> G = PUBO(
>>>     {(0, 1): -4, (0, 2): -1, (0,): 3, (1,): 2, (): 2
>>> }
>>> D = G.subvalue({2: -3})
>>> D
{(0, 1): -4, (0,): 6, (1,): 2, (): 2}

update(*args, **kwargs)

update.

Update the dictionary but following all the conventions of this class.

Parameters: arguments (defines a dictionary, ie d = dict(*args, **kwargs).) – Each element in d will be added in place to this instance following all the required convensions.

values() → an object providing a view on D's values

BO

class qubovert.utils.BO(*args, **kwargs)

BO.

Parent class for some Binary Optimization classes, such as qubovert.QUBO, qubovert.QUSO, etc.

BO inherits some methods and attributes the DictArithmetic class. See help(qubovert.utils.DictArithmetic).

BO inherits some methods and attributes the Conversions class. See help(qubovert.utils.Conversions).

__init__.

This class deals with Binary Optimization models. See child classes for info on inputs.

Parameters: arguments (Defined in child classes.) –

property mapping

mapping.

Return a copy of the mapping dictionary that maps the provided labels to integers from 0 to n-1, where n is the number of variables in the problem.

Returns: mapping – Dictionary that maps provided labels to integer labels.
Return type: dict.

property max_index

max_index.

Return the maximum label of the integer labeled version of the problem.

Returns: m
Return type: int.

property reverse_mapping

reverse_mapping.

Return a copy of the reverse_mapping dictionary that maps the integer labels to the provided labels. Opposite of mapping.

Returns: reverse_mapping – Dictionary that maps integer labels to provided labels.
Return type: dict.

set_mapping(*args, **kwargs)

set_mapping.

BO sublcasses automatically create a mapping from variable names to integers as they are being built. However, the mapping is based on the order in which elements are entered and therefore may not be as desired. Of course, the convert_solution method keeps track of the mapping and can/should always be used. But if you want a consistent mapping, then set_mapping can be used.

Consider the following examples (we use the qubovert.QUBO class for the examples, which is a subclass of BO).

Example 1:

>>> from qubovert import QUBO
>>> Q = QUBO()
>>> Q[(0,)] += 1
>>> Q[(1,)] += 2
>>> Q.mapping
{0: 0, 1: 1}
>>> Q.to_qubo()
{(0,): 1, (1,): 2}

Example 2:

>>> from qubovert import QUBO
>>> Q = QUBO()
>>> Q[(1,)] += 2
>>> Q[(0,)] += 1
>>> Q.mapping
{0: 1, 1: 0}
>>> Q.to_qubo()
{(0,): 2, (1,): 1}

To ensure consistency in mappings, you can provide your own mapping with set_mapping. See the following modified examples.

Modified example 1:

>>> from qubovert import QUBO
>>> Q = QUBO()
>>> Q[(0,)] += 1
>>> Q[(1,)] += 2
>>> Q.set_mapping({0: 0, 1: 1})
>>> Q.mapping
{0: 0, 1: 1}
>>> Q.to_qubo()
{(0,): 1, (1,): 2}

Modified example 2:

>>> from qubovert import QUBO
>>> Q = QUBO()
>>> Q[(1,)] += 2
>>> Q[(0,)] += 1
>>> Q.set_mapping({0: 0, 1: 1})
>>> Q.mapping
{0: 0, 1: 1}
>>> Q.to_qubo()
{(0,): 1, (1,): 2}

Parameters: arguments (defines a dictionary with d = dict(*args, **kwargs).) – d will become the mapping. See help(self.mapping)

Notes

Using set_mapping to set the mapping will also automatically set the reverse_mapping, so there is no need to call both set_mapping and set_reverse_mapping.

set_reverse_mapping(*args, **kwargs)

set_reverse_mapping.

Same as set_mapping but reversed. See help(self.reverse_mapping) and help(self.set_mapping).

Parameters: arguments (defines a dictionary with d = dict(*args, **kwargs).) – d will become the reverse mapping. See help(self.reverse_mapping).

Notes

Using set_reverse_mapping to set the mapping will also automatically set the mapping, so there is no need to call both set_mapping and set_reverse_mapping.

to_enumerated()

to_enumerated.

Return the default enumerated Matrix object.

If self is a QUBO, self.to_enumerated() is equivalent to self.to_qubo().

If self is a QUSO, self.to_enumerated() is equivalent to self.to_quso().

If self is a PUBO or PCBO, self.to_enumerated() is equivalent to self.to_pubo().

If self is a PUSO or PCSO, self.to_enumerated() is equivalent to self.to_puso().

Returns: res – If self is a QUBO type, then this method returns the corresponding QUBOMatrix type. If self is a QUSO type, then this method returns the corresponding QUSOMatrix type. If self is a PUBO or PCBO type, then this method returns the corresponding PUBOMatrix type. If self is a PUSO or PCSO type, then this method returns the corresponding PUSOMatrix type.
Return type: QUBOMatrix, QUSOMatrix, PUBOMatrix, or PUSOMatrix object.

to_pubo(*args, **kwargs)

to_pubo.

Create and return upper triangular PUBO representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_puso or to_qubo and converts the puso or QUBO formulations to a PUBO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUBO.

Returns

P – The upper triangular PUBO matrix, a PUBOMatrix object. For most practical purposes, you can use PUBOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.PUBOMatrix).

Return type

qubovert.utils.PUBOMatrix object.

Raises

RecursionError` if neither to_pubo nor to_puso are define –
in the subclass. –

to_puso(*args, **kwargs)

to_puso.

Create and return PUSO model representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_pubo or to_quso and converts to a PUSO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUSO model.

Returns

H – For most practical purposes, you can use PUSOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.PUSOMatrix).

Return type

qubovert.utils.PUSOMatrix object.

Raises

RecursionError` if neither to_pubo nor to_puso are define –
in the subclass. –

to_qubo(*args, **kwargs)

to_qubo.

Create and return upper triangular QUBO representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_quso and converts the quso formulation to a QUBO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUBO.

Returns

Q – The upper triangular QUBO matrix, a QUBOMatrix object. For most practical purposes, you can use QUBOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.QUBOMatrix).

Return type

qubovert.utils.QUBOMatrix object.

Raises

RecursionError` if neither to_qubo nor to_quso are define –
in the subclass. –

to_quso(*args, **kwargs)

to_quso.

Create and return QUSO model representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_qubo and converts the QUBO formulation to an QUSO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUSO model.

Returns

L – The upper triangular coupling matrix, where two element tuples represent couplings and one element tuples represent fields. For most practical purposes, you can use IsingCoupling in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.QUSOMatrix).

Return type

qubovert.utils.QUSOMatrix object.

Raises

RecursionError` if neither to_qubo nor to_quso are define –
in the subclass. –

Conversions

class qubovert.utils.Conversions

Conversions.

This is a parent class that defines the functions to_qubo, to_quso, to_pubo, and to_puso. Any subclass that inherits from Conversions must supply at least one of to_qubo or to_quso. And at least one of to_pubo or to_puso.

to_pubo(*args, **kwargs)

to_pubo.

Create and return upper triangular PUBO representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_puso or to_qubo and converts the puso or QUBO formulations to a PUBO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUBO.

Returns

P – The upper triangular PUBO matrix, a PUBOMatrix object. For most practical purposes, you can use PUBOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.PUBOMatrix).

Return type

qubovert.utils.PUBOMatrix object.

Raises

RecursionError` if neither to_pubo nor to_puso are define –
in the subclass. –

to_puso(*args, **kwargs)

to_puso.

Create and return PUSO model representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_pubo or to_quso and converts to a PUSO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUSO model.

Returns

H – For most practical purposes, you can use PUSOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.PUSOMatrix).

Return type

qubovert.utils.PUSOMatrix object.

Raises

RecursionError` if neither to_pubo nor to_puso are define –
in the subclass. –

to_qubo(*args, **kwargs)

to_qubo.

Create and return upper triangular QUBO representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_quso and converts the quso formulation to a QUBO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUBO.

Returns

Q – The upper triangular QUBO matrix, a QUBOMatrix object. For most practical purposes, you can use QUBOMatrix in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.QUBOMatrix).

Return type

qubovert.utils.QUBOMatrix object.

Raises

RecursionError` if neither to_qubo nor to_quso are define –
in the subclass. –

to_quso(*args, **kwargs)

to_quso.

Create and return QUSO model representing the problem. Should be implemented in child classes. If this method is not implemented in the child class, then it simply calls to_qubo and converts the QUBO formulation to an QUSO formulation.

Parameters

arguments (Defined in the child class.) – They should be parameters that define lagrange multipliers or factors in the QUSO model.

Returns

L – The upper triangular coupling matrix, where two element tuples represent couplings and one element tuples represent fields. For most practical purposes, you can use IsingCoupling in the same way as an ordinary dictionary. For more information, see help(qubovert.utils.QUSOMatrix).

Return type

qubovert.utils.QUSOMatrix object.

Raises

RecursionError` if neither to_qubo nor to_quso are define –
in the subclass. –