Discrete Quadratic Models

Discrete quadratic models (DQMs) are described under Discrete Quadratic Models.

DQM Class

class DiscreteQuadraticModel[source]

Encodes a discrete quadratic model.

A discrete quadratic model is a polynomial over discrete variables with terms all of degree two or less.

Examples

This example constructs a map coloring with Canadian provinces. To solve the problem we penalize adjacent provinces having the same color.

>>> provinces = ["AB", "BC", "ON", "MB", "NB", "NL", "NS", "NT", "NU",
...              "PE", "QC", "SK", "YT"]
>>> borders = [("BC", "AB"), ("BC", "NT"), ("BC", "YT"), ("AB", "SK"),
...            ("AB", "NT"), ("SK", "MB"), ("SK", "NT"), ("MB", "ON"),
...            ("MB", "NU"), ("ON", "QC"), ("QC", "NB"), ("QC", "NL"),
...            ("NB", "NS"), ("YT", "NT"), ("NT", "NU")]
>>> colors = [0, 1, 2, 3]
...
>>> dqm = dimod.DiscreteQuadraticModel()
>>> for p in provinces:
...     _ = dqm.add_variable(4, label=p)
>>> for p0, p1 in borders:
...     dqm.set_quadratic(p0, p1, {(c, c): 1 for c in colors})

The next examples show how to view and manipulate the model biases.

>>> dqm = dimod.DiscreteQuadraticModel()

Add the variables to the model

>>> u = dqm.add_variable(5)  # unlabeled variable with 5 cases
>>> v = dqm.add_variable(3, label='v')  # labeled variable with 3 cases

The linear biases default to 0. They can be read by case or by batch.

>>> dqm.get_linear_case(u, 1)
0.0
>>> dqm.get_linear(u)
array([0., 0., 0., 0., 0.])
>>> dqm.get_linear(v)
array([0., 0., 0.])

The linear biases can be overwritten either by case or in a batch.

>>> dqm.set_linear_case(u, 3, 17)
>>> dqm.get_linear(u)
array([ 0.,  0.,  0., 17.,  0.])
>>> dqm.set_linear(v, [0, -1, 3])
>>> dqm.get_linear(v)
array([ 0., -1.,  3.])

The quadratic biases can also be manipulated sparsely or densely.

>>> dqm.set_quadratic(u, v, {(0, 2): 1.5})
>>> dqm.get_quadratic(u, v)
{(0, 2): 1.5}
>>> dqm.get_quadratic(u, v, array=True)  # as a NumPy array
array([[0. , 0. , 1.5],
       [0. , 0. , 0. ],
       [0. , 0. , 0. ],
       [0. , 0. , 0. ],
       [0. , 0. , 0. ]])
>>> dqm.set_quadratic_case(u, 2, v, 1, -3)
>>> dqm.get_quadratic(u, v, array=True)
array([[ 0. ,  0. ,  1.5],
       [ 0. ,  0. ,  0. ],
       [ 0. , -3. ,  0. ],
       [ 0. ,  0. ,  0. ],
       [ 0. ,  0. ,  0. ]])
>>> dqm.get_quadratic(u, v)  # doctest:+SKIP
{(0, 2): 1.5, (2, 1): -3.0}

Attributes

adj The adjacency structure of the variables.

Methods

add_variable(num_cases[, label]) Add a discrete variable.
copy() Return a copy of the discrete quadratic model.
from_file(file_like) Construct a DQM from a file-like object.
from_numpy_vectors(case_starts, …[, labels]) Construct a DQM from five numpy vectors.
get_linear(v) The linear biases associated with variable v.
get_linear_case(v, case) The linear bias associated with case case of variable v.
get_quadratic(u, v[, array]) The biases associated with the interaction between u and v.
get_quadratic_case(u, u_case, v, v_case) The bias associated with the interaction between two cases of u and v.
num_cases([v]) If v is provided, the number of cases associated with v, otherwise the total number of cases in the DQM.
num_case_interactions() The total number of case interactions.
num_variable_interactions() The total number of variable interactions
num_variables() The number of variables in the discrete quadratic model.
relabel_variables(mapping[, inplace])
relabel_variables_as_integers([inplace]) Relabel the variables of the DQM to integers.
set_linear(v, biases) Set the linear biases associated with v.
set_linear_case(v, case, bias) The linear bias associated with case case of variable v.
set_quadratic(u, v, biases) Set biases associated with the interaction between u and v.
set_quadratic_case(u, u_case, v, v_case, bias) Set the bias associated with the interaction between two cases of u and v.
to_file([compress, compressed, …]) Convert the DQM to a file-like object.
to_numpy_vectors() Convert the DQM to five numpy vectors and the labels.