dwave.system.temperatures.effective_field#

effective_field(bqm: BinaryQuadraticModel, samples: None | SampleSet | Tuple[ndarray, list] = None, current_state_energy: bool = False) → Tuple[ndarray, list][source]#

Returns the effective field for all variables and all samples.

Depending on the value you set for the current_state_energy parameter, the effective field is one of the following:

  • False: 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).

  • True: The energy difference from flipping the variable state from its current value (e.g., from -1 to 1, for an Ising model, or 0 to 1, for a QUBO). 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) for a sample, that sample is a local minima (maxima).

As shown in the Ising-QUBO Transformations section, any binary quadratic model (BQM) can be converted to an Ising model using

\[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 effective field on variable \(i\), \(f_i(s)\), is then defined as

  • current_state_energy == False:

    \[f_i(s) = h_i + \sum_j J_{i, j} s_j\]

  • current_state_energy == True:

    \[f_i(s) = 2 s_i [h_i + \sum_j J_{i, j} s_j]\]
Parameters:

  • bqm – A dimod binary quadratic model.

  • samples – Either a SampleSet or a samples_like object (an extension of the NumPy array_like structure); see as_samples(). By default, a single sample with all +1 assignments is used.

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

Returns:

A tuple of the effective fields and the variable labels. Effective fields are returned as a numpy.ndarray object and variable labels are returned as a list. Rows index samples and columns index variables in the order returned by variable labels.

Return type:

samples_like

Examples

For a ferromagnetic Ising chain \(H = - 0.5 \sum_i s_i s_{i+1}\) and for a ground state sample (all +1 values), the energy lost when flipping any spin is equal to the number of couplers frustrated: -2 for most the chain (variables 1,2,..,N-2), and -1 at the ends (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])