# Utility Methods

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

Accessed with qubovert.utils.function_name.

## Conversions

qubovert.utils.pubo_to_puso(P)

pubo_to_puso.

Convert the specified PUBO problem into an PUSO problem. Note that PUBO {0, 1} values go to PUSO {1, -1} values in that order!

Parameters

P (dictionary, qubovert.PUBO, or qubovert.utils.PUBOMatrix object.) – Maps tuples of boolean variables indices to the P value. See help(qubovert.PUBO) and help(qubovert.utils.PUBOMatrix) for info on formatting.

Returns

H – tuple of spin labels map to PUSO values. If P is a qubovert.utils.PUBOMatrix object, then H will be a qubovert.utils.PUSOMatrix, otherwise H will be a qubovert.PUSO object..

Return type

qubovert.utils.PUSOMatrix object or qubovert.PUSO object.

Example

>>> P = {(0,): 1, (0, 1): -1, (1,): 3}
>>> H = pubo_to_puso(P)
>>> isinstance(H, qubovert.utils.PUSOMatrix)
True

>>> P = {(0,): 1, (0, 1): -1, (1,): 3}
>>> H = pubo_to_puso(P)
>>> isinstance(H, qubovert.PUSO)
True

qubovert.utils.puso_to_pubo(H)

puso_to_pubo.

Convert the specified PUSO problem into an upper triangular PUBO problem. Note that PUSO {1, -1} values go to PUBO {0, 1} values in that order!

Parameters

H (dictionary or qubovert.utils.PUSOMatrix object.) – Tuple of spin labels map to PUSO values. See help(qubovert.PUSO) and help(qubovert.utils.PUSOMatrix) for info on formatting.

Returns

P – If H is a qubovert.utils.PUSOMatrix object, then P will be a qubovert.utils.PUBOMatrix, otherwise P will be a qubovert.PUBO object. See help(qubovert.PUBO) and help(qubovert.utils.PUBOMatrix) for info on formatting.

Return type

qubovert.utils.PUBOMatrix object or qubovert.PUBO object.

Example

>>> H = {(0,): 1, (1,): -1, (0, 1): -1}
>>> P = puso_to_pubo(H)
>>> isinstance(P, qubovert.utils.PUBOMatrix)
True

>>> H = {('0',): 1, ('1',): -1, (0, 1): -1}
>>> P = puso_to_pubo(H)
>>> isinstance(P, qubovert.PUBO)
True

qubovert.utils.qubo_to_quso(Q)

qubo_to_quso.

Convert the specified QUBO problem into an QUSO problem. Note that QUBO {0, 1} values go to QUSO {1, -1} values in that order!

Parameters

Q (dictionary, qubovert.QUBO, or qubovert.utils.QUBOMatrix object.) – Maps tuples of boolean variables indices to the Q value. See help(qubovert.QUBO) and help(qubovert.utils.QUBOMatrix) for info on formatting.

Returns

L – tuple of spin labels map to QUSO values. If Q is a qubovert.utils.QUBOMatrix object, then L will be a qubovert.utils.QUSOMatrix, otherwise L will be a qubovert.QUSO object.

Return type

qubovert.QUSO or qubovert.utils.QUSOMatrix object.

Example

>>> Q = {(0,): 1, (0, 1): -1, (1,): 3}
>>> L = qubo_to_quso(Q)
>>> isinstance(L, qubovert.utils.QUSOMatrix)
True

>>> Q = {('a',): 1, ('a', 'b'): -1, ('b',): 3}
>>> L = qubo_to_quso(Q)
>>> isinstance(L, qubovert.QUSO)
True

qubovert.utils.quso_to_qubo(L)

quso_to_qubo.

Convert the specified QUSO problem into an upper triangular QUBO problem. Note that QUSO {1, -1} values go to QUBO {0, 1} values in that order!

Parameters

L (dictionary, qubovert.QUSO, or qubovert.utils.QUSOMatrix object.) – Tuple of spin labels map to QUSO values. See help(qubovert.QUSO) and help(qubovert.utils.QUSOMatrix) for info on formatting.

Returns

Q – If L is a qubovert.utils.QUSOMatrix object, then Q will be a qubovert.utils.QUBOMatrix, otherwise Q will be a qubovert.QUBO object. See help(qubovert.QUBO) and help(qubovert.utils.QUBOMatrix) for info on formatting.

Return type

qubovert.QUBO or qubovert.utils.QUBOMatrix object.

Example

>>> L = {(0,): 1, (1,): -1, (0, 1): -1}
>>> Q = quso_to_qubo(L)
>>> isinstance(Q, qubovert.utils.QUBOMatrix)
True

>>> L = {('a',): 1, ('b',): -1, (0, 1): -1}
>>> Q = quso_to_qubo(L)
>>> isinstance(Q, qubovert.QUBO)
True

qubovert.utils.matrix_to_qubo(matrix)

matrix_to_qubo.

Convert a matrix to a QUBO dictionary.

Parameters

matrix (list of lists or 2-dimensional numpy array.) – matrix[i][j] is equal to $$Q_{ij}$$.

Returns

Q – The upper triangular QUBO dictionary. See help(qubovert.utils.QUBOMatrix).

Return type

qubovert.utils.QUBOMatrix object.

qubovert.utils.qubo_to_matrix(Q, symmetric=False, array=True)

qubo_to_matrix.

Convert a QUBO dictionary to its matrix form. The indices of the Q dictionary should be integers from 0 to n-1, where there are n binary variables in the QUBO problem.

Parameters
• Q (dict or qubovert.utils.QUBOMatrix object.) – Input QUBO dictionary, where Q[(i, j)] corresponds to $$Q_{ij}$$.

• symmetric (bool (optional, defaults to False)) – Whether the returned matrix should be symmetric or upper-triangular. If symmetric is True, then the matrix will be symmetric, ie matrix[i][j] == matrix[j][i]. Otherwise, it will be upper-triangular, ie marix[i][j] == 0 if i > j.

• array (bool (optional, defaults to True)) – Whether the returned matrix should be a numpy array or list of lists. If array is True, then it will be a numpy array, otherwise, it will be a list of lists.

Returns

matrix – The matrix representing the QUBO. See the arguments symmetric and array for info on the return type of matrix.

Return type

numpy array or list of lists.

qubovert.utils.boolean_to_spin(x)

boolean_to_spin.

Convert a boolean number in {0, 1} to a spin in {1, -1}, in that order.

Parameters

x (int, iterable of ints, or dict mapping labels to ints.) – Each integer is either 0 or 1.

Returns

z – Each integer is either 1 or -1.

Return type

int, iterable of ints, or dict mapping labels to ints.

Example

>>> boolean_to_spin(0)  # will print 1
>>> boolean_to_spin(1)  # will print -1
>>> boolean_to_spin([0, 1, 1])  # will print [1, -1, -1]
>>> boolean_to_spin({"a": 0, "b": 1})  # will print {"a": 1, "b": -1}

qubovert.utils.spin_to_boolean(z)

spin_to_boolean.

Convert a spin in {1, -1} to a boolean variable in {0, 1}, in that order.

Parameters

z (int, iterable of ints, or dict mapping labels to ints.) – Each integer is either 1 or -1.

Returns

x – Each integer is either 0 or 1.

Return type

int, iterable of ints, or dict mapping labels to ints.

Example

>>> spin_to_boolean(-1)  # will print 1
>>> spin_to_boolean(1)  # will print 0
>>> spin_to_boolean([-1, 1, 1])  # will print [1, 0, 0]
>>> spin_to_boolean({"a": -1, "b": 1})  # will print {"a": 1, "b": 0}

qubovert.utils.decimal_to_boolean(d, num_bits=None)

decimal_to_boolean.

Convert the integer d to its boolean representation.

Parameters
• d (int >= 0.) – Number to convert to binary.

• num_bits (int >= 0 (optional, defaults to None)) – Number of bits in the representation. If num_bits is None, then the minimum number of bits required will be used.

Returns

b – Each element of b is a 0 or 1.

Return type

tuple of length num_bits.

Example

>>> decimal_to_boolean(10, 7)
(0, 0, 0, 1, 0, 1, 0)

>>> decimal_to_boolean(10)
(1, 0, 1, 0)

qubovert.utils.decimal_to_spin(d, num_spins=None)

decimal_to_spin.

Convert the integer d to its spin representation (ie its binary representation, but with 1 and -1 instead of 0 and 1).

Parameters
• d (int >= 0.) – Number to convert to binary.

• num_spins (int >= 0 (optional, defaults to None)) – Number of bits in the representation. If num_spins is None, then the minimum number of bits required will be used.

Returns

b – Each element of b is a 0 or 1.

Return type

tuple of length num_spins.

Example

>>> decimal_to_spin(10, 7)
(1, 1, 1, -1, 1, -1, 1)

>>> decimal_to_spin(10)
(-1, 1, -1, 1)

qubovert.utils.boolean_to_decimal(b)

boolean_to_decimal.

Convert a bit string to its decimal form.

Parameters

b (tuple or list of 0s and 1s.) – The binary bit string.

Returns

d

Return type

int.

Examples

>>> boolean_to_decimal((1, 1, 0))
6

qubovert.utils.spin_to_decimal(b)

spin_to_decimal.

Convert a spin string to its decimal form.

Parameters

b (tuple or list of 1s and -1s.) – The spin bit string.

Returns

d

Return type

int.

Examples

>>> spin_to_decimal((-1, -1, 1))
6


## Values

qubovert.utils.pubo_value(x, P)

pubo_value.

Find the value of the PUBO for a given assignment of the boolean variables x.

Parameters
• x (dict or iterable.) – Maps boolean variable indices to their boolean values, 0 or 1. Ie x[i] must be the boolean value of variable i.

• P (dict, or any object in qv.BOOLEAN_MODELS.) – Maps tuples of boolean variables indices to the P value.

Returns

value – The value of the PUBO with the given assignment x. Ie

Return type

float.

Example

>>> P = {(0,): 1, (0, 1): -1}
>>> x = {0: 1, 1: 0}
>>> pubo_value(x, P)
1

qubovert.utils.puso_value(z, H)

puso_value.

Find the value of the PUSO for a given assignment of the spin variables z.

Parameters
• z (dict or iterable.) – Maps variable labels to their values, 1 or -1. Ie z[i] must be the value of variable i.

• H (dict, or any object in qv.SPIN_MODELS.) – Maps spin labels to values.

Returns

value – The value of the PUSO with the given assignment z.

Return type

float.

Example

>>> H = {(0, 1): -1, (0,): 1}
>>> z = {0: -1, 1: 1}
>>> puso_value(z, H)
0

qubovert.utils.qubo_value(x, Q)

qubo_value.

Find the value of the QUBO for a given assignment of the boolean variables x.

Please note that THIS FUNCTION WILL NOT RAISE AN EXCEPTION IF Q IS NOT A QUBO!! If you input a Q that is, for example, degree 3 instead of degree 2, then this function will return an incorrect value!

Parameters
• x (dict or iterable.) – Maps boolean variable indices to their boolean values, 0 or 1. Ie x[i] must be the boolean value of variable i.

• Q (dict or qubovert.utils.QUBOMatrix object.) – Maps tuples of boolean variables indices to the Q value.

Returns

value – The value of the QUBO with the given assignment x. Ie

Return type

float.

Example

>>> Q = {(0,): 1, (0, 1): -1}
>>> x = {0: 1, 1: 0}
>>> qubo_value(x, Q)
1

qubovert.utils.quso_value(z, L)

quso_value.

Find the value of the QUSO for a given assignment of the spin variables z.

Please note that THIS FUNCTION WILL NOT RAISE AN EXCEPTION IF L IS NOT A QUSO!! If you input a L that is, for example, degree 3 instead of degree 2, then this function will return an incorrect value!

Parameters
• z (dict or iterable.) – Maps variable labels to their values, 1 or -1. Ie z[i] must be the value of variable i.

• L (dict, qubovert.utils.QUSOMatrix, or qubovert.QUSO object.) – Maps spin labels to values.

Returns

value – The value of the QUSO with the given assignment z.

Return type

float.

Example

>>> L = {(0, 1): -1, (0,): 1}
>>> z = {0: -1, 1: 1}
>>> quso_value(z, L)
0


## Bruteforce Solvers

qubovert.utils.solve_pubo_bruteforce(P, all_solutions=False, valid=<function <lambda>>)

solve_pubo_bruteforce.

Iterate through all the possible solutions to a PUBO formulated problem and find the best one (the one that gives the minimum objective value). Do not use for large problem sizes! This is meant only for testing very small problems.

Parameters
• P (dict, qubovert.utils.PUBOMatrix, or qubovert.PUBO object.) – Maps boolean variables labels to the P value.

• all_solutions (boolean (optional, defaults to False)) – If all_solutions is set to True, all the best solutions to the PUBO will be returned rather than just one of the best. If the problem is very big, then it is best if all_solutions is False, otherwise this function will use a lot of memory.

• valid (function (optional, defaults to lambda x: True).) – valid takes in a bitstring and outputs a boolean indicating whether that bitstring is a valid solutions.

Returns

res

if all_solutions is False:
objectivefloat.

The best value of the PUBO.

solutiondict.

Maps the boolean variable label to its solution value, {0, 1}.

if all_solutions is True:
objectivefloat.

The best value of the PUBO.

solutionlist of dicts.

Each dictionary maps the label to the value of each boolean variable. Ie each s in solution is a solution that gives the best objective function value.

Return type

tuple (objective, solution)

Example

To find the minimum of the problem $$obj = x_0x_1 + x_1x_2 - x_1 - 2x_2$$, the P dictionary is

>>> P = {(0, 1): 1, (1, 2): 1, (1,): -1, (2,): -2}


Then to solve this P, run

>>> obj_val, solution = solve_pubo_bruteforce(Q)
>>> obj_val
-2
>>> solution
{0: 0, 1: 0, 2: 1}


obj_val will be the smallest value of obj. solution will be a dictionary that indicates what each of $$x_0$$, $$x_1$$, and $$x_2$$ are for the solution. In this case, x = {0: 0, 1: 0, 2: 1}, indicating that $$x_0$$ is 0, $$x_1$$ is 0, $$x_2$$ is 1.

qubovert.utils.solve_puso_bruteforce(H, all_solutions=False, valid=<function <lambda>>)

solve_puso_bruteforce.

Iterate through all the possible solutions to an PUSO formulated problem and find the best one (the one that gives the minimum objective value). Do not use for large problem sizes! This is meant only for testing very small problems.

Parameters
• H (dict, qubovert.utils.PUSOMatrix, or qubovert.PUSO object.) – Maps spin labels to values.

• all_solutions (boolean (optional, defaults to False)) – If all_solutions is set to True, all the best solutions to the QUSO will be returned rather than just one of the best. If the problem is very big, then it is best if all_solutions is False, otherwise this function will use a lot of memory.

• valid (function (optional, defaults to lambda x: True).) – valid takes in a spinstring and outputs a boolean indicating whether that spinstring is a valid solutions.

Returns

res

if all_solutions is False:
objectivefloat.

The best value of the PUSO.

solutiondict.

Maps the spin variable label to its solution value, {-1, 1}.

if all_solutions is True:
objectivefloat.

The best value of the PUSO.

solutionlist of dicts.

Each dictionary maps the label to the value of each variable. Ie each s in solution is a solution that gives the best objective function value.

Return type

tuple (objective, solution)

Example

To find the minimum of the problem $$obj = z_0z_1 + z_1z_2 - z_1 - 2z_2$$, we have

>>> H = {(0, 1): 1, (1, 2): 1, (1,): -1, (2,): -2}


Then to solve this, run

>>> obj_val, solution = solve_puso_bruteforce(H)
>>> obj_val
-3
>>> solution
{0: 1, 1: -1, 2: 1}


obj_val will be the smallest value of obj. solution will be a dictionary that indicates what each of $$z_0, z_1$$, and $$z_2$$ are for the solution. In this case, z = {0: 1, 1: -1, 2: 1}, indicating that $$z_0$$ is 1, $$z_1$$ is -1, $$z_2$$ is 1.

qubovert.utils.solve_qubo_bruteforce(Q, all_solutions=False, valid=<function <lambda>>)

solve_qubo_bruteforce.

Iterate through all the possible solutions to a QUBO formulated problem and find the best one (the one that gives the minimum objective value). Do not use for large problem sizes! This is meant only for testing very small problems.

Parameters
• Q (dict, qubovert.utils.QUBOMatrix, or qubovert.QUBO object.) – Maps boolean variables labels to the Q value.

• all_solutions (boolean (optional, defaults to False)) – If all_solutions is set to True, all the best solutions to the QUBO will be returned rather than just one of the best. If the problem is very big, then it is best if all_solutions is False, otherwise this function will use a lot of memory.

• valid (function (optional, defaults to lambda x: True).) – valid takes in a bitstring and outputs a boolean indicating whether that bitstring is a valid solutions.

Returns

res

if all_solutions is False:
objectivefloat.

The best value of the QUBO.

solutiondict.

Maps the boolean variable label to its solution value, {0, 1}.

if all_solutions is True:
objectivefloat.

The best value of the QUBO. Equal to sum(Q[(i, j)] * solution[x][i] * solution[x][j]) + offset where solution[x] is one of the solutions to the QUBO.

solutionlist of dicts.

Each dictionary maps the label to the value of each boolean variable. Ie each s in solution is a solution that gives the best objective function value.

Return type

tuple (objective, solution)

Example

To find the minimum of the problem $$obj = x_0x_1 + x_1x_2 - x_1 - 2x_2$$, the P dictionary is

>>> Q = {(0, 1): 1, (1, 2): 1, (1,): -1, (2,): -2}


Then to solve this Q, run

>>> obj_val, solution = solve_qubo_bruteforce(Q)
>>> obj_val
-2
>>> solution
{0: 0, 1: 0, 2: 1}


obj_val will be the smallest value of obj. solution will be a dictionary that indicates what each of $$x_0$$, $$x_1$$, and $$x_2$$ are for the solution. In this case, x = {0: 0, 1: 0, 2: 1}, indicating that $$x_0$$ is 0, $$x_1$$ is 0, $$x_2$$ is 1.

qubovert.utils.solve_quso_bruteforce(L, all_solutions=False, valid=<function <lambda>>)

solve_quso_bruteforce.

Iterate through all the possible solutions to an QUSO formulated problem and find the best one (the one that gives the minimum objective value). Do not use for large problem sizes! This is meant only for testing very small problems.

Parameters
• L (dict, qubovert.utils.QUSOMatrix, or qubovert.QUSO object.) – Maps spin labels to values.

• all_solutions (boolean (optional, defaults to False)) – If all_solutions is set to True, all the best solutions to the QUSO will be returned rather than just one of the best. If the problem is very big, then it is best if all_solutions is False, otherwise this function will use a lot of memory.

• valid (function (optional, defaults to lambda x: True).) – valid takes in a spinstring and outputs a boolean indicating whether that spinstring is a valid solutions.

Returns

res

if all_solutions is False:
objectivefloat.

The best value of the QUSO.

solutiondict.

Maps the spin variable label to its solution value, {-1, 1}.

if all_solutions is True:
objectivefloat.

The best value of the PUSO.

solutionlist of dicts.

Each dictionary maps the label to the value of each variable. Ie each s in solution is a solution that gives the best objective function value.

Return type

tuple (objective, solution)

Example

To find the minimum of the problem $$obj = z_0z_1 + z_1z_2 - z_1 - 2z_2$$, we have

>>> L = {(0, 1): 1, (1, 2): 1, (1,): -1, (2,): -2}


Then to solve this, run

>>> obj_val, solution = solve_quso_bruteforce(L)
>>> obj_val
-3
>>> solution
{0: 1, 1: -1, 2: 1}


obj_val will be the smallest value of obj. solution will be a dictionary that indicates what each of $$z_0, z_1$$, and $$z_2$$ are for the solution. In this case, z = {0: 1, 1: -1, 2: 1}, indicating that $$z_0$$ is 1, $$z_1$$ is -1, $$z_2$$ is 1.

## Approximate Extrema

qubovert.utils.approximate_pubo_extrema(P)

approximate_pubo_extrema.

Find the approximate minimum and maximum possible values that a PUBO can take. This is very approximate! The estimated minimum value that this function returns will definitely be less than or equal to the true minimum (most likely, it will be much less). Similarly, the estimated maximum value that this function returns will definitely be greater than or equal to the true maximum (most likely, it will be much more).

Parameters

P (dict, PUBO, or PUBOMatrix object.) – P represents a PUBO. Please see qubovert.PUBO or qubovert.utils.PUBOMatrix.

Returns

bounds – The approximate minimum and maximum of the PUBO.

Return type

tuple (min, max)

qubovert.utils.approximate_puso_extrema(H)

approximate_puso_extrema.

Find the approximate minimum and maximum possible values that a PUSO can take. This is very approximate! The estimated minimum value that this function returns will definitely be less than or equal to the true minimum (most likely, it will be much less). Similarly, the estimated maximum value that this function returns will definitely be greater than or equal to the true maximum (most likely, it will be much more).

Parameters

H (dict, PUSO, or PUSOMatrix object.) – H represents a PUSO. Please see qubovert.PUSO or qubovert.utils.PUSOMatrix.

Returns

bounds – The approximate minimum and maximum of the PUSO.

Return type

tuple (min, max)

qubovert.utils.approximate_qubo_extrema(Q)

approximate_qubo_extrema.

Find the approximate minimum and maximum possible values that a QUBO can take. This is very approximate! The estimated minimum value that this function returns will definitely be less than or equal to the true minimum (most likely, it will be much less). Similarly, the estimated maximum value that this function returns will definitely be greater than or equal to the true maximum (most likely, it will be much more).

Parameters

Q (dict, QUBO, or QUBOMatrix object.) – Q represents a QUBO. Please see qubovert.QUBO or qubovert.utils.QUBOMatrix.

Returns

bounds – The approximate minimum and maximum of the QUBO.

Return type

tuple (min, max)

qubovert.utils.approximate_quso_extrema(L)

approximate_quso_extrema.

Find the approximate minimum and maximum possible values that a QUSO can take. This is very approximate! The estimated minimum value that this function returns will definitely be less than or equal to the true minimum (most likely, it will be much less). Similarly, the estimated maximum value that this function returns will definitely be greater than or equal to the true maximum (most likely, it will be much more).

Parameters

L (dict, QUSO, or QUSOMatrix object.) – L represents a QUSO. Please see qubovert.QUSO or qubovert.utils.QUSOMatrix.

Returns

bounds – The approximate minimum and maximum of the QUSO.

Return type

tuple (min, max)

## Useful functions

qubovert.utils.sum(iterable, start=0)

sum.

A utility for summing qubovert types. This will perform way faster than Python’s built-in sum function when you use it with qubovert types.

Parameters
• iterable (any iterable.) –

• start (numeric or qubovert type (optional, defaults to 0)) –

Returns

res

Return type

same type as sum(iterable, start) with Python’s builtin sum.

Examples

>>> import time
>>> import qubovert as qv
>>>
>>> xs = [qv.boolean_var(i) for i in range(1000)]

>>> t0 = time.time()
>>> sum(xs)
>>> print(time.time() - t0)
3.345559597015381

>>> t0 = time.time()
>>> qv.utils.sum(xs)
>>> print(time.time() - t0)
0.011152505874633789

qubovert.utils.subgraph(G, nodes, connections=None)

subgraph.

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

Parameters
• G (dict or any subclass of dict.) – G must contain tuple keys.

• nodes (set.) – Nodes of G to include in the subgraph.

• connections (dict (optional, defaults to {})) – For each node in G that is not in nodes, we assign a value given by connections.get(node, 0).

Returns

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

Return type

same as type(G)

Notes

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

Examples

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

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

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

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

qubovert.utils.subvalue(values, G)

subvalue.

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

Parameters
• values (dict.) – For each node v in G that is in values, we replace the node with values[v].

• G (dict or any subclass of dict.) – G must contain tuple keys.

Returns

D

Return type

same as type(G)

Examples

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

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

qubovert.utils.normalize(D, value=1)

normalize.

Normalize the coefficients to a maximum magnitude.

Parameters
• D (dict or subclass of dict.) –

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

Returns

resD but with coefficients that are normalized to be within +/- value.

Return type

same as type(D)

Examples

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

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

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

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

qubovert.utils.num_bits(val, log_trick=True)

num_bits.

Find the number of bits needed to represent the value val.

Parameters
• val (numeric.) –

• log_trick (bool (optional, defaults to True)) – Whether or not to use a log encoding.

Returns

num – The number of bits needed to encode the number val.

Return type

int.

Examples

>>> num_bits(7)
3
>>> num_bits(8)
4
>>> num_bits(7, log_trick=False)
7
>>> num_bits(8, log_trick=False)
8

qubovert.utils.get_info(model)

get_info.

Create a basic representation of the qubovert object encoded by model. This basic representation is easily shareable. It works so that model == qv.utils.create_from_info(qv.utils.get_info(model)) is True.

Parameters

model (type in qubovert.BOOLEAN_MODELS or qubovert.SPIN_MODELS.) –

Returns

resres will have many fields. The first is type which will indicate which qubovert type model is. Then there will be a terms field which indicates the terms in the model. Then there may be a name field which will be set to model.name. Depending on the input type, there may be mapping, num_ancillas, and constraints fields.

Return type

dict.

Example

>>> import qubovert as qv
>>>
>>> pcbo = qv.PCBO({(0,): 1}).add_constraint_eq_zero({(0,): 1}, lam=0)
>>> pcbo
{(0,): 1}
>>> pcbo.constraints
{"eq": [{(0,): 1}]}
>>> print(pcbo.name)
None
>>> info = qv.utils.get_info(pcbo)
>>> info
{"type"="PCBO", "name"=None, "terms"={(0,): 1}, "mapping"={0: 0},
num_ancillas=0, "constraints"={"eq": [{(0,): 1}]}}
>>> qv.utils.create_from_info(info) == pcbo
True

qubovert.utils.create_from_info(info)

create_from_info.

Create a qubovert object encoded by the information stored in info. It works so that info == qv.utils.get_info(qv.utils.create_from_info(info)) is True.

Parameters

info (dict.) – Same as the output of qubovert.utils.get_info. info can have many fields. The first is type which will indicate which qubovert type model is. Then there will be a terms field which indicates the terms in the model. Then there may be a name field which will be set to model.name. Depending on the input type, there may be mapping, num_ancillas, and constraints fields.

Returns

res – The qubovert object that info is describing.

Return type

a type in qubovert.BOOLEAN_MODELS or qubovert.SPIN_MODELS.

Example

>>> import qubovert as qv
>>>
>>> pcbo = qv.PCBO({(0,): 1}).add_constraint_eq_zero({(0,): 1}, lam=0)
>>> pcbo
{(0,): 1}
>>> pcbo.constraints
{"eq": [{(0,): 1}]}
>>> print(pcbo.name)
None
>>> info = qv.utils.get_info(pcbo)
>>> info
{"type"="PCBO", "name"=None, "terms"={(0,): 1}, "mapping"={0: 0},
num_ancillas=0, "constraints"={"eq": [{(0,): 1}]}}
>>> qv.utils.create_from_info(info) == pcbo
True


qubovert.utils.get_info