hybrid.utils.flip_energy_gains

flip_energy_gains(bqm, sample, variables=None, min_gain=None)[source]

Order variable flips by descending contribution to energy changes in a BQM.

Parameters:
  • bqm (dimod.BinaryQuadraticModel) – Binary quadratic model (BQM).
  • sample (list/dict) – Sample values as returned by dimod samplers (0 or 1 values for dimod.BINARY and -1 or +1 for dimod.SPIN)
  • variables (sequence, optional, default=None) – Consider only flips of these variables. If undefined, consider all variables in sample.
  • min_gain (float, optional, default=None) – Minimum required energy increase from flipping a sample value to return its corresponding variable.
Returns:

Energy changes in descending order, in the format of tuples

(energy_gain, variable), for flipping the given sample value for each variable.
Return type:

list

Examples

This example returns connecting edges between 3 nodes of a BQM based on a 4-variable path graph.

>>> import dimod
>>> bqm = dimod.BQM({}, {'ab': 0, 'bc': 1, 'cd': 2}, 0, 'SPIN')
>>> flip_energy_gains(bqm, {'a': -1, 'b': 1, 'c': 1, 'd': -1})
[(4, 'd'), (2, 'c'), (0, 'a'), (-2, 'b')]