Utilities

Utility functions useful for samplers.

ising_energy(sample, h, J, offset=0.0)[source]

Calculate the energy for the specified sample of an Ising model.

Energy of a sample for a binary quadratic model is defined as a sum, offset by the constant energy offset associated with the model, of the sample multipled by the linear bias of the variable and all its interactions. For an Ising model,

\[E(\mathbf{s}) = \sum_v h_v s_v + \sum_{u,v} J_{u,v} s_u s_v + c\]

where \(s_v\) is the sample, \(h_v\) is the linear bias, \(J_{u,v}\) the quadratic bias (interactions), and \(c\) the energy offset.

Parameters:
  • sample (dict[variable, spin]) – Sample for a binary quadratic model as a dict of form {v: spin, …}, where keys are variables of the model and values are spins (either -1 or 1).
  • h (dict[variable, bias]) – Linear biases as a dict of the form {v: bias, …}, where keys are variables of the model and values are biases.
  • J (dict[(variable, variable), bias]) – Quadratic biases as a dict of the form {(u, v): bias, …}, where keys are 2-tuples of variables of the model and values are quadratic biases associated with the pair of variables (the interaction).
  • offset (numeric, optional, default=0) – Constant offset to be applied to the energy. Default 0.
Returns:

The induced energy.
Return type:

float

Notes

No input checking is performed.

Examples

This example calculates the energy of a sample representing two down spins for an Ising model of two variables that have positive biases of value 1 and are positively coupled with an interaction of value 1.

>>> import dimod
>>> sample = {1: -1, 2: -1}
>>> h = {1: 1, 2: 1}
>>> J = {(1, 2): 1}
>>> dimod.ising_energy(sample, h, J, 0.5)
-0.5

References

Ising model on Wikipedia

qubo_energy(sample, Q, offset=0.0)[source]

Calculate the energy for the specified sample of a QUBO model.

Energy of a sample for a binary quadratic model is defined as a sum, offset by the constant energy offset associated with the model, of the sample multipled by the linear bias of the variable and all its interactions. For a quadratic unconstrained binary optimization (QUBO) model,

\[E(\mathbf{x}) = \sum_{u,v} Q_{u,v} x_u x_v + c\]

where \(x_v\) is the sample, \(Q_{u,v}\) a matrix of biases, and \(c\) the energy offset.

Parameters:
  • sample (dict[variable, spin]) – Sample for a binary quadratic model as a dict of form {v: bin, …}, where keys are variables of the model and values are binary (either 0 or 1).
  • Q (dict[(variable, variable), coefficient]) – QUBO coefficients in a dict of form {(u, v): coefficient, …}, where keys are 2-tuples of variables of the model and values are biases associated with the pair of variables. Tuples (u, v) represent interactions and (v, v) linear biases.
  • offset (numeric, optional, default=0) – Constant offset to be applied to the energy. Default 0.
Returns:

The induced energy.
Return type:

float

Notes

No input checking is performed.

Examples

This example calculates the energy of a sample representing two zeros for a QUBO model of two variables that have positive biases of value 1 and are positively coupled with an interaction of value 1.

>>> import dimod
>>> sample = {1: 0, 2: 0}
>>> Q = {(1, 1): 1, (2, 2): 1, (1, 2): 1}
>>> dimod.qubo_energy(sample, Q, 0.5)
0.5

References

QUBO model on Wikipedia

ising_to_qubo(h, J, offset=0.0)[source]

Convert an Ising problem to a QUBO problem.

Map an Ising model defined on spins (variables with {-1, +1} values) to quadratic unconstrained binary optimization (QUBO) formulation \(x' Q x\) defined over binary variables (0 or 1 values), where the linear term is contained along the diagonal of Q. Return matrix Q that defines the model as well as the offset in energy between the two problem formulations:

\[s' J s + h' s = offset + x' Q x\]

See qubo_to_ising() for the inverse function.

Parameters:
  • h (dict[variable, bias]) – Linear biases as a dict of the form {v: bias, …}, where keys are variables of the model and values are biases.
  • J (dict[(variable, variable), bias]) – Quadratic biases as a dict of the form {(u, v): bias, …}, where keys are 2-tuples of variables of the model and values are quadratic biases associated with the pair of variables (the interaction).
  • offset (numeric, optional, default=0) – Constant offset to be applied to the energy. Default 0.
Returns:

A 2-tuple containing:

dict: QUBO coefficients.

float: New energy offset.
Return type:

(dict, float)

Examples

This example converts an Ising problem of two variables that have positive biases of value 1 and are positively coupled with an interaction of value 1 to a QUBO problem.

>>> import dimod
>>> h = {1: 1, 2: 1}
>>> J = {(1, 2): 1}
>>> dimod.ising_to_qubo(h, J, 0.5)  
({(1, 1): 0.0, (1, 2): 4.0, (2, 2): 0.0}, -0.5)
qubo_to_ising(Q, offset=0.0)[source]

Convert a QUBO problem to an Ising problem.

Map a quadratic unconstrained binary optimization (QUBO) problem \(x' Q x\) defined over binary variables (0 or 1 values), where the linear term is contained along the diagonal of Q, to an Ising model defined on spins (variables with {-1, +1} values). Return h and J that define the Ising model as well as the offset in energy between the two problem formulations:

\[x' Q x = offset + s' J s + h' s\]

See ising_to_qubo() for the inverse function.

Parameters:
  • Q (dict[(variable, variable), coefficient]) – QUBO coefficients in a dict of form {(u, v): coefficient, …}, where keys are 2-tuples of variables of the model and values are biases associated with the pair of variables. Tuples (u, v) represent interactions and (v, v) linear biases.
  • offset (numeric, optional, default=0) – Constant offset to be applied to the energy. Default 0.
Returns:

A 3-tuple containing:

dict: Linear coefficients of the Ising problem.

dict: Quadratic coefficients of the Ising problem.

float: New energy offset.
Return type:

(dict, dict, float)

Examples

This example converts a QUBO problem of two variables that have positive biases of value 1 and are positively coupled with an interaction of value 1 to an Ising problem.

>>> import dimod
>>> Q = {(1, 1): 1, (2, 2): 1, (1, 2): 1}
>>> dimod.qubo_to_ising(Q, 0.5)    
({1: 0.75, 2: 0.75}, {(1, 2): 0.25}, 1.75)