Model¶

class Model¶

Model represents binary quadratic optimization problem.

By compiling Express object, you get a Model object. It contains the information about QUBO (or equivalent Ising Model), and it also has the function to decode the solution into the original variable structure.

Note

We do not need to create this object directly. Instead, we get this by compiling Express objects.

Generate QUBO, Ising model, and BQM

`to_qubo()`	Returns QUBO and energy offset.
`to_ising()`	Returns Ising Model and energy offset.
`to_bqm()`	Returns `dimod.BinaryQuadraticModel`.

Interpret samples returned from solvers

`energy()`	Returns energy of the sample.
`decode_sample()`	Returns Ising Model and energy offset.
`decode_sampleset()`	Decode the sample represented by `dimod.SampleSet`.

to_qubo(index_label=False, feed_dict=None)¶

Returns QUBO and energy offset.

Parameters:	index_label (bool) – If true, the keys of returned QUBO are indexed with a positive integer number. feed_dict (dict[str,float]) – If the expression contains `Placeholder` objects, you have to specify the value of them by `Placeholder`. Please refer to `Placeholder` for more details.
Returns:	Tuple of QUBO and energy offset. QUBO takes the form of `dict[(str, str), float]`.
Return type:	`tuple[QUBO, float]`

Examples:

This example creates the model from the expression, and we get the resulting QUBO by calling model.to_qubo().
>>> from pyqubo import Binary
>>> x, y, z = Binary("x"), Binary("y"), Binary("z")
>>> model = (x*y + y*z + 3*z).compile()
>>> pprint(model.to_qubo()) # doctest: +SKIP
({('x', 'x'): 0.0,
('x', 'y'): 1.0,
('y', 'y'): 0.0,
('z', 'y'): 1.0,
('z', 'z'): 3.0},
0.0)
If you want a QUBO which has index labels, specify the argument index_label=True. The mapping of the indices and the corresponding labels is stored in model.variables.
>>> pprint(model.to_qubo(index_label=True)) # doctest: +SKIP
({(0, 0): 3.0, (0, 2): 1.0, (1, 1): 0.0, (1, 2): 1.0, (2, 2): 0.0}, 0.0)
>>> model.variables
['z', 'x', 'y']

to_ising(index_label=False, feed_dict=None)¶

Returns Ising Model and energy offset.

Parameters:	index_label (bool) – If true, the keys of returned QUBO are indexed with a positive integer number. feed_dict (dict[str,float]) – If the expression contains `Placeholder` objects, you have to specify the value of them by `Placeholder`. Please refer to `Placeholder` for more details.
Returns:	Tuple of Ising Model and energy offset. Where linear takes the form of `(dict[str, float])`, and quadratic takes the form of `dict[(str, str), float]`.
Return type:	`tuple(linear, quadratic, float)`

Examples:

This example creates the model from the expression, and we get the resulting Ising model by calling to_ising().
>>> from pyqubo import Binary
>>> x, y, z = Binary("x"), Binary("y"), Binary("z")
>>> model = (x*y + y*z + 3*z).compile()
>>> pprint(model.to_ising()) # doctest: +SKIP
({'x': 0.25, 'y': 0.5, 'z': 1.75}, {('x', 'y'): 0.25, ('z', 'y'): 0.25}, 2.0)
If you want a Ising model which has index labels, specify the argument index_label=True. The mapping of the indices and the corresponding labels is stored in model.variables.
>>> pprint(model.to_ising(index_label=True)) # doctest: +SKIP
({0: 1.75, 1: 0.25, 2: 0.5}, {(0, 2): 0.25, (1, 2): 0.25}, 2.0)
>>> model.variables
['z', 'x', 'y']

to_bqm(index_label=False, feed_dict=None)¶

Returns dimod.BinaryQuadraticModel.

For more details about dimod.BinaryQuadraticModel, see dimod.BinaryQuadraticModel.

Parameters:	index_label (bool) – If true, the keys of returned QUBO are indexed with a positive integer number. feed_dict (dict[str,float]) – If the expression contains `Placeholder` objects, you have to specify the value of them by `Placeholder`.
Returns:	`dimod.BinaryQuadraticModel` with vartype set to dimod.BINARY.
Return type:	`dimod.BinaryQuadraticModel`

Examples:

>>> from pyqubo import Binary, Constraint
>>> from dimod import ExactSolver
>>> a, b = Binary('a'), Binary('b')
>>> H = Constraint(2*a-3*b, "const1") + Constraint(a+b-1, "const2")
>>> model = H.compile()
>>> bqm = model.to_bqm()
>>> sampleset = ExactSolver().sample(bqm)
>>> decoded_samples = model.decode_sampleset(sampleset)
>>> best_sample = min(decoded_samples, key=lambda s: s.energy)
>>> print(best_sample.energy)
-3.0
>>> pprint(best_sample.sample)
{'a': 0, 'b': 1}
>>> pprint(best_sample.constraints())
{'const1': (False, -3.0), 'const2': (True, 0.0)}

energy(solution, vartype, feed_dict=None)¶

Returns energy of the sample.

Parameters:	sample (list[int]/dict[str,int]) – The sample returned from solvers. vartype (str) – Variable type of the solution. Specify either `'BINARY'` or `'SPIN'`. feed_dict (dict[str,float]) – Specify the placeholder values.
Returns:	Calculated energy.
Return type:	float

decode_sample(sample, vartype, feed_dict=None)¶

Decode sample from solvers.

Parameters:	sample (list[int]/dict[str,int]) – The sample returned from solvers. vartype (str) – Variable type of the solution. Specify either `'BINARY'` or `'SPIN'`. feed_dict (dict[str,float]) – Specify the placeholder values.
Returns:	`DecodedSample` object.
Return type:	`DecodedSample`

Examples

>>> from pyqubo import Binary, SubH
>>> a, b = Binary('a'), Binary('b')
>>> H = SubH(a+b-2, "subh1") + 2*a + b
>>> model = H.compile()
>>> decoded_sample = model.decode_sample({'a': 1, 'b': 0}, vartype='BINARY')
>>> print(decoded_sample.energy)
1.0
>>> pprint(decoded_sample.sample)
{'a': 1, 'b': 0}
>>> print(decoded_sample.subh)
{'subh1': -1.0}

decode_sampleset(sampleset, feed_dict=None)¶

Decode the sample represented by dimod.SampleSet.

For more details about dimod.SampleSet, see dimod.SampleSet.

Parameters:	sample (dimod.SampleSet) – The solution returned from dimod sampler. feed_dict (dict[str,float]) – Specify the placeholder values. Default=None
Returns:	`DecodedSample` object.
Return type:	`DecodedSample`

Examples

>>> from pyqubo import Binary, Constraint
>>> from dimod import ExactSolver
>>> a, b = Binary('a'), Binary('b')
>>> H = Constraint(2*a-3*b, "const1") + Constraint(a+b-1, "const2")
>>> model = H.compile()
>>> bqm = model.to_bqm()
>>> sampleset = ExactSolver().sample(bqm)
>>> decoded_samples = model.decode_sampleset(sampleset)
>>> best_sample = min(decoded_samples, key=lambda s: s.energy)
>>> print(best_sample.energy)
-3.0
>>> pprint(best_sample.sample)
{'a': 0, 'b': 1}
>>> pprint(best_sample.constraints())
{'const1': (False, -3.0), 'const2': (True, 0.0)}

DecodedSample¶

class DecodedSample¶

DecodedSample contains the informatin like whether the constraint is satisfied or not, or the value of the SubHamiltonian.

Examples

>>> from pyqubo import Binary, SubH
>>> a, b = Binary('a'), Binary('b')
>>> H = SubH(a+b-2, "subh1") + 2*a + b
>>> model = H.compile()
>>> decoded_sample = model.decode_sample({'a': 1, 'b': 0}, vartype='BINARY')
>>> print(decoded_sample.energy)
1.0
>>> pprint(decoded_sample.sample)
{'a': 1, 'b': 0}
>>> print(decoded_sample.subh)
{'subh1': -1.0}

Methods

`array()`	Get the value of the array element specified.
`constraints()`	Returns the information about constraints.

array(array_name, index)¶

Get the value of the array specified by array_name and index.

Parameters:	array_name (str) – The name of the array. index (int/tuple) – The index of the array.
Returns:	The value of the array calculated by the sample.
Return type:	float

Examples

>>> from pyqubo import Array
>>> x = Array.create('x', shape=(2, 1), vartype="BINARY")
>>> H = (x[0, 0] + x[1, 0] - 1)**2
>>> model = H.compile()
>>> qubo, offset = model.to_qubo()
>>> pprint(qubo)
{('x[0][0]', 'x[0][0]'): -1.0,
('x[0][0]', 'x[1][0]'): 2.0,
('x[1][0]', 'x[1][0]'): -1.0}
>>> dec = model.decode_sample({'x[0][0]': 1, 'x[1][0]': 0}, vartype='BINARY')
>>> print(dec.array('x', (0, 0)))
1
>>> print(dec.array('x', (1, 0)))
0

constraints(only_broken)¶

Get the value of the array specified by array_name and index.

Parameters:	only_broken (bool) – Whether to select only broken constraints.
Returns:	Dictionary with the key being the label of the constraint and the value being the boolean and the corresponding energy value. The boolean value indicates whether the constraint is satisfied or not.
Return type:	dict[str, tuple[bool, float]]

Examples

>>> from pyqubo import Binary, Constraint
>>> a, b = Binary('a'), Binary('b')
>>> H = Constraint(a+b-2, "const1") + Constraint(a+b-1, "const2")
>>> model = H.compile()
>>> dec = model.decode_sample({'a': 1, 'b': 0}, vartype='BINARY')
>>> pprint(dec.constraints())
{'const1': (False, -1.0), 'const2': (True, 0.0)}
>>> pprint(dec.constraints(only_broken=True))
{'const1': (False, -1.0)}