Reference Documentation#

Planar#

PlanarGraphSolver#

class PlanarGraphSolver[source]#: An exact solver for planar Ising problems with no linear biases.

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	Values for parameters accepted by the sampling methods.

Methods#

`sample`(bqm[, pos])	Find a ground state of a planar Ising problem without linear biases.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Random#

RandomSampler#

class RandomSampler[source]#

A random sampler, useful as a performance baseline and for testing.

Examples

>>> from dwave.samplers import RandomSampler
>>> sampler = RandomSampler()

Create a random binary quadratic model.

>>> import dimod
>>> bqm = dimod.generators.gnp_random_bqm(100, .5, 'BINARY')

Get 20 random samples.

>>> sampleset = sampler.sample(bqm, num_reads=20)

Get the best 5 sample found in .1 seconds

>>> sampleset = sampler.sample(bqm, time_limit=.1, max_num_samples=5)

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	Information about the solver.

Methods#

`sample`(bqm, *[, num_reads, time_limit, ...])	Return random samples for a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Simulated Annealing#

SimulatedAnnealingSampler#

class SimulatedAnnealingSampler[source]#

Simulated annealing sampler for binary quadratic models.

Simulated annealing can be used for heuristic optimization or approximate Boltzmann sampling. This implementation approaches the equilibrium distribution by performing updates at a sequence of decreasing temperatures, terminating at the target \(\beta\).[1] By default each spin is updated once in a fixed order per point per \(\beta\) according to a Metropolis-Hastings update. When \(\beta\) is large the target distribution concentrates, at equilibrium, over ground states of the model. Samples are guaranteed to match the equilibrium for long, smooth \(\beta\) schedules.

For more information, see Kirkpatrick, S.; Gelatt Jr, C. D.; Vecchi, M. P. (1983). “Optimization by Simulated Annealing”. Science. 220 (4598): 671–680

Also aliased as Neal.

Examples

This example solves a simple Ising problem.

>>> from dwave.samplers import SimulatedAnnealingSampler
>>> sampler = SimulatedAnnealingSampler()
>>> h = {'a': 0.0, 'b': 0.0, 'c': 0.0}
>>> J = {('a', 'b'): 1.0, ('b', 'c'): 1.0, ('a', 'c'): 1.0}
>>> sampleset = sampler.sample_ising(h, J, num_reads=10)
>>> print(sampleset.first.energy)
-1.0

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	A dict containing any additional information about the sampler.

Methods#

`sample`(bqm[, beta_range, num_reads, ...])	Sample from a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Alias#

Neal[source]#: alias of SimulatedAnnealingSampler

Steepest Descent#

SteepestDescentSolver#

class SteepestDescentSolver[source]#

Steepest descent sampler for binary quadratic models.

Steepest descent is the discrete analogue of gradient descent, but the best move is computed using a local minimization rather rather than computing a gradient. The dimension along which to descend is determined, at each step, by the variable flip that causes the greatest reduction in energy.

Solves convex problems to optimality.

Number of downhill runs (samples produced) is determined by num_reads, number of initial_states, or a combination of the two, depending on the initial_states_generator.

For a given input model’s graph \(G = (V, E)\), \(V\) being a set of graph vertices and \(E\) a set of edges, runtime complexity of the underlying C++ implementation is \(O(|E|)\) for initialization phase and \(O(|V|)\) per downhill step.

In the large_sparse_opt mode, runtime complexity on sparse graphs is \(O(|V|*log|V|)\) for initialization and \(O(max\_degree * log|V|)\) per downhill step.

Aliased as SteepestDescentSampler.

Examples

Solve a simple Ising problem.

>>> from dwave.samplers import SteepestDescentSampler
...
>>> sampler = SteepestDescentSampler()
>>> samples = sampler.sample_ising({0: 2, 1: 2}, {(0, 1): -1})
...
>>> print(samples)      
   0  1 energy num_oc. num_st.
0 -1 -1   -5.0       1       2
['SPIN', 1 rows, 1 samples, 2 variables]

Post-processes samples generated by another sampler (simulated annealing in this example):

>>> from dwave.samplers import SteepestDescentSampler, SimulatedAnnealingSampler
>>> import dimod
...
>>> bqm = dimod.generators.ran_r(5, 3)
>>> samples = SimulatedAnnealingSampler().sample(bqm)
>>> postprocessed = SteepestDescentSampler().sample(bqm, initial_states=samples)

For additional examples, see sample().

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	Values for parameters accepted by the sampling methods.

Methods#

`sample`(bqm[, num_reads, initial_states, ...])	Find minima of a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Alias#

SteepestDescentSampler[source]#: alias of SteepestDescentSolver

SteepestDescentComposite#

class SteepestDescentComposite(child_sampler)[source]#

Runs greedy local optimization (steepest descent) on input problem, seeded with samples from the sampler.

Parameters:: child_sampler (dimod.Sampler) – A dimod sampler, such as a DWaveSampler.

Attributes#

`parameters`	Parameters in the form of a dict.
`properties`	Properties in the form of a dict.

Methods#

`sample`(bqm, **parameters)	Find minima of a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Tabu#

TabuSampler#

class TabuSampler[source]#

A tabu-search sampler.

Tabu search is a heuristic that employs local search and can escape local minima by maintaining a “tabu list” of recently explored states that it does not revisit. This sampler implements the MST2 multistart tabu search algorithm. for quadratic unconstrained binary optimization (QUBO) problems.

Examples

This example solves a two-variable Ising model.

>>> from dwave.samplers import TabuSampler
>>> sampleset = TabuSampler().sample_ising({'a': -0.5, 'b': 1.0}, {'ab': -1}, num_restarts=0)
>>> print(sampleset)
   a  b energy num_oc. num_re.
0 -1 -1   -1.5       1       0
['SPIN', 1 rows, 1 samples, 2 variables]

Attributes#

`parameters`
`properties`

Methods#

`sample`(bqm[, initial_states, ...])	Run a multistart tabu search on a given binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Tree Decomposition#

TreeDecompositionSolver#

class TreeDecompositionSolver[source]#

Tree decomposition-based solver for binary quadratic models.

The tree decomposition solver uses tree decomposition to find ground states of the given binary quadratic model.

Important

The performance of this sampler is highly dependant on the treewidth of the problem.

Examples

Create a solver:

>>> from dwave.samplers import TreeDecompositionSolver
>>> solver = TreeDecompositionSolver()

Create a simple Ising problem:

>>> h = {'a': .1, 'b': 0}
>>> J = {('a', 'b') : -1}

Find the ground state.

>>> sampleset = solver.sample_ising(h, J)
>>> print(sampleset)
   a  b energy num_oc.
0 -1 -1   -1.1       1
['SPIN', 1 rows, 1 samples, 2 variables]

Take multiple reads to find states of increasing energy.

>>> sampleset = solver.sample_ising(h, J, num_reads=3)
>>> print(sampleset)
   a  b energy num_oc.
0 -1 -1   -1.1       1
1 +1 +1   -0.9       1
2 -1 +1    0.9       1
['SPIN', 3 rows, 3 samples, 2 variables]

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	Information about the solver.

Methods#

`sample`(bqm[, num_reads, elimination_order])	Find ground states of a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

TreeDecompositionSampler#

class TreeDecompositionSampler[source]#

Tree decomposition-based sampler for binary quadratic models.

The tree decomposition sampler uses tree decomposition to sample from a Boltzmann distribution defined by the given binary quadratic model.

Important

The performance of this sampler is highly dependant on the treewidth of the problem.

Attributes#

`parameters`	Keyword arguments accepted by the sampling methods.
`properties`	Information about the sampler.

Methods#

`sample`(bqm[, num_reads, elimination_order, ...])	Draw samples and compute marginals of a binary quadratic model.
`sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.