Model

class Model(compiled_qubo, structure, constraints)[source]

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.

Parameters:
  • compiled_qubo (CompiledQubo) – Compiled QUBO. If we want to get the final QUBO, we need to evaluate this QUBO by specifying the value of placeholders. See CompiledQubo.eval().
  • structure (dict[label, Tuple(key1, key2, key3, …)]) – It defines the mapping of the variable used in decode_solution(). A solution of label is mapped to decoded_solution[key1][key2][key3][...]. For more details, see decode_solution().
  • constraints (dict[label, polynomial_term]) – It contains constraints of the problem. label is each constraint name and polynomial_term is corresponding polynomial which should be zero when the constraint is satisfied.
variable_order

The list of labels. The order is corresponds to the index of QUBO or Ising model.

Type:list
index2label

The dictionary which maps an index to a label.

Type:dict[int, label]
label2index

The dictionary which maps a label to an index.

Type:dict[label, index]
decode_dimod_response(response, topk=None, feed_dict=None)[source]

Decode the solution of dimod.Response.

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

Parameters:
  • response (dimod.Response) – The solution returned from dimod sampler.
  • topk (int, default=None) – Decode only top-k (energy is smaller) solutions.
  • feed_dict (dict[str, float]) – Specify the placeholder values. Default=None
Returns:

List of tuple of the decoded solution and broken constraints and energy. Solutions are sorted by energy. Structure of decoded_solution is defined by structure.

Return type:

list[tuple(dict, dict, float)]

decode_solution(**kwargs)[source]

Returns decoded solution.

Parameters:
  • solution (list[bit]/dict[label, bit]/dict[index, bit]) – The solution returned from solvers.
  • vartype (dimod.Vartype/str/set, optional) –

    Variable type of the solution. Accepted input values:

    • Vartype.SPIN, 'SPIN', {-1, 1}
    • Vartype.BINARY, 'BINARY', {0, 1}
  • feed_dict (dict[str, float]) – Specify the placeholder values.
Returns:

Tuple of the decoded solution, broken constraints and energy. Structure of decoded_solution is defined by structure.

Return type:

tuple(dict, dict, float)

energy(**kwargs)[source]

Returns energy of the solution.

Parameters:
  • solution (list[bit]/dict[label, bit]/dict[index, bit]) – The solution returned from solvers.
  • vartype (dimod.Vartype/str/set, optional) –

    Variable type of the solution. Accepted input values:

    • Vartype.SPIN, 'SPIN', {-1, 1}
    • Vartype.BINARY, 'BINARY', {0, 1}
  • feed_dict (dict[str, float]) – Specify the placeholder values.
Returns:

energy of the solution.

Return type:

float

to_dimod_bqm(feed_dict=None)[source]

Returns dimod.BinaryQuadraticModel.

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

Parameters: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.
to_ising(index_label=False, feed_dict=None)[source]

Returns Ising Model and energy offset.

Parameters:
  • index_label (bool) – If true, the keys of returned Ising model 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:

Tuple of Ising Model and energy offset. Where linear takes the form of (dict[label, value]), and quadratic takes the form of dict[(label, label), value].

Return type:

tuple(linear, quadratic, float)

Examples

This example creates the model from the expression, and we get the resulting Ising model by calling model.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, ('y', 'z'): 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: 0.25, 1: 0.5, 2: 1.75}, {(0, 1): 0.25, (1, 2): 0.25}, 2.0)
>>> model.variable_order
['x', 'y', 'z']
to_qubo(index_label=False, feed_dict=None)[source]

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.
Returns:

Tuple of QUBO and energy offset. QUBO takes the form of dict[(label, label), value].

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,
  ('y', 'z'): 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.variable_order.

>>> pprint(model.to_qubo(index_label=True)) # doctest: +SKIP
({(0, 0): 0.0, (0, 1): 1.0, (1, 1): 0.0, (1, 2): 1.0, (2, 2): 3.0}, 0.0)
>>> model.variable_order
['x', 'y', 'z']