effective_field(bqm, samples=None, current_state_energy=False) -> (<class 'numpy.ndarray'>, <class 'list'>)[source]

Returns the effective field for all variables and all samples.

The effective field with current_state_energy = False is the energy attributable to setting a variable to value 1, conditioned on fixed values for all neighboring variables (relative to exclusion of the variable, and associated energy terms, from the problem).

The effective field with current_state_energy = True is the energy gained by flipping the variable state against its current value (from say -1 to 1 in the Ising case, or 0 to 1 in the QUBO case). A positive value indicates that the energy can be decreased by flipping the variable, hence the variable is in a locally excited state. If all values are negative (positive) within a sample, that sample is a local minima (maxima).

Any BQM can be converted to an Ising model with

\[H(s) = Constant + \sum_i h_i s_i + 0.5 \sum_{i,j} J_{i,j} s_i s_j\]

with unique values of \(J\) (symmetric) and \(h\). The sample dependent effect field on variable i, \(f_i(s)\), is then defined

if current_state_energy == False:
\[f_i(s) = h_i + \sum_j J_{i,j} s_j\]
\[f_i(s) = 2 s_i [h_i + \sum_j J_{i,j} s_j]\]
  • bqm (dimod.BinaryQuadraticModel) – Binary quadratic model.

  • samples (samples_like or SampleSet,optional) – A collection of raw samples. samples_like is an extension of NumPy’s array like structure. See dimod.sampleset.as_samples(). By default, a single sample with all +1 assignments is used.

  • current_state_energy (bool, optional, default=False) – By default, returns the effective field (the energy contribution associated to a state assignment of 1). When set to True, returns the energy lost in flipping the value of each variable. Note current_state_energy is typically negative for positive temperature samples, meaning energy is not decreased by flipping the spin against its current assignment.


A Tuple of the effective_fields, and the variable labels. Effective fields are returned as a numpy.ndarray. Rows index samples, and columns index variables in the order returned by variable labels.

Return type



For a ferromagnetic Ising chain \(H = - 0.5 \sum_i s_i s_{i+1}\) and for a ground state sample (all +1), the energy lost when flipping any spin is equal to the number of couplers frustrated: -2 in the center of the chain (variables 1,2,..,N-2), and -1 at the end (variables 0 and N-1).

>>> import dimod
>>> import numpy as np
>>> from dwave.system.temperatures import effective_field
>>> N = 5
>>> bqm = dimod.BinaryQuadraticModel.from_ising({}, {(i,i+1) : -0.5 for i in range(N-1)})
>>> var_labels = list(range(N))
>>> samples = (np.ones(shape=(1,N)), var_labels)
>>> E = effective_field(bqm,samples,current_state_energy=True)
>>> print('Cost to flip spin against current assignment', E)
Cost to flip spin against current assignment (array([[-1., -2., -2., -2., -1.]]), [0, 1, 2, 3, 4])