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 the variable with maximum contribution to energy for the given sample.

>>> 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})[0][1]
'd'