Samplers

The dimod package includes several example samplers.

Other Ocean packages provide production samplers; for example, the dwave-system package provides samplers for D-Wave systems and dwave-neal provides a simulated-annealing sampler.

Exact Solver

A simple exact solver for testing and debugging code using your local CPU.

Note:

This sampler is designed for use in testing. Because it calculates the energy for every possible sample, it is very slow.

Class

class ExactSolver[source]

A simple exact solver for testing and debugging code using your local CPU.

Notes

This solver becomes slow for problems with 18 or more variables.

Examples

This example solves a two-variable Ising model.

>>> h = {'a': -0.5, 'b': 1.0}
>>> J = {('a', 'b'): -1.5}
>>> sampleset = dimod.ExactSolver().sample_ising(h, J)
>>> print(sampleset)   
   a  b energy num_oc.
0 -1 -1   -2.0       1
2 +1 +1   -1.0       1
1 +1 -1    0.0       1
3 -1 +1    3.0       1
['SPIN', 4 rows, 4 samples, 2 variables]

This example solves a two-variable QUBO.

>>> Q = {('a', 'b'): 2.0, ('a', 'a'): 1.0, ('b', 'b'): -0.5}
>>> sampleset = dimod.ExactSolver().sample_qubo(Q)
>>> sampleset.first.sample
{'a': 0, 'b': 1}

This example solves a two-variable binary quadratic model.

>>> bqm = dimod.BinaryQuadraticModel({'a': 1.5}, {('a', 'b'): -1}, 0.0, 'SPIN')
>>> sampleset = dimod.ExactSolver().sample(bqm)
>>> sampleset.first.energy
-2.5

Methods

ExactSolver.sample(bqm, **kwargs)

Sample from a binary quadratic model.

ExactSolver.sample_ising(h, J, **parameters)

Sample from an Ising model using the implemented sample method.

ExactSolver.sample_qubo(Q, **parameters)

Sample from a QUBO using the implemented sample method.

Exact DQM Solver

A simple DQM exact solver for testing and debugging code using your local CPU.

Note:

This sampler is designed for use in testing. Because it calculates the energy for every possible sample, it is very slow.

Class

class ExactDQMSolver[source]

A simple exact solver for testing and debugging code using your local CPU.

Notes

This solver calculates the energy for every possible combination of variable cases. If variable i has k_i many cases, this will be k_1 * k_2 * … * k_n which grows exponentially for constant k_i in the number of variables.

Methods

ExactDQMSolver.sample_dqm(dqm, **kwargs)

Sample from a discrete quadratic model.

Exact CQM Solver

A simple CQM exact solver for testing and debugging code using your local CPU.

Note:

This sampler is designed for use in testing. Because it calculates the energy and constraint violations for every possible sample, it is very slow.

Class

class ExactCQMSolver[source]

A simple exact solver for testing and debugging code using your local CPU.

Notes

This solver calculates the energy for every possible combination of variable cases. It becomes slow very quickly

Examples

This example solves a CQM with 3 variables and 1 constraint.

>>> from dimod import ConstrainedQuadraticModel, Binary
>>> cqm = ConstrainedQuadraticModel()
>>> x, y, z = Binary('x'), Binary('y'), Binary('z')
>>> cqm.set_objective(x*y + 2*y*z)
>>> cqm.add_constraint(x*y == 1, label='constraint_1')
'constraint_1'
>>> sampleset = dimod.ExactCQMSolver().sample_cqm(cqm)
>>> print(sampleset)      
  x y z energy num_oc. is_sat. is_fea.
0 0 0 0    0.0       1 arra...   False
1 0 1 0    0.0       1 arra...   False
2 1 0 0    0.0       1 arra...   False
4 0 0 1    0.0       1 arra...   False
6 1 0 1    0.0       1 arra...   False
3 1 1 0    1.0       1 arra...    True
5 0 1 1    2.0       1 arra...   False
7 1 1 1    3.0       1 arra...    True
['INTEGER', 8 rows, 8 samples, 3 variables]

Methods

ExactCQMSolver.sample_cqm(cqm[, rtol, atol])

Sample from a constrained quadratic model.

Identity Sampler

A sampler that returns the provided initial states.

Class

class IdentitySampler[source]

A sampler that returns the provided initial states.

Examples:

>>> samples = [{'a': -1, 'b': +1}, {'a': +1, 'b': +1}]
>>> Q = {('a', 'b'): -1}
>>> sampler = dimod.IdentitySampler()
>>> sampleset = sampler.sample_qubo(Q, initial_states=samples)
>>> print(sampleset)
   a  b energy num_oc.
1  1  1   -1.0       1
0  0  1    0.0       1
['BINARY', 2 rows, 2 samples, 2 variables]

Properties

IdentitySampler.parameters

Keyword arguments accepted by the sampling methods.

Methods

IdentitySampler.sample(bqm, *args, **kwargs)

Return exactly the provided initial states.

IdentitySampler.sample_ising(h, J, **parameters)

Sample from an Ising model using the implemented sample method.

IdentitySampler.sample_qubo(Q, **parameters)

Sample from a QUBO using the implemented sample method.

Null Sampler

A sampler that always returns an empty sample set.

Class

class NullSampler(parameters=None)[source]

A sampler that always returns an empty sample set.

This sampler is useful for writing unit tests where the result is not important.

Parameters

parameters (iterable/dict, optional) – If provided, sets the parameters accepted by the sample methods. The values given in these parameters are ignored.

Examples

>>> bqm = dimod.BinaryQuadraticModel.from_qubo({('a', 'b'): 1})
>>> sampler = dimod.NullSampler()
>>> sampleset = sampler.sample(bqm)
>>> len(sampleset)
0

The next example shows how to enable additional parameters for the null sampler.

>>> bqm = dimod.BinaryQuadraticModel.from_qubo({('a', 'b'): 1})
>>> sampler = dimod.NullSampler(parameters=['a'])
>>> sampleset = sampler.sample(bqm, a=5)

Properties

NullSampler.parameters

Keyword arguments accepted by the sampling methods

Methods

NullSampler.sample(bqm, **kwargs)

Return an empty sample set.

NullSampler.sample_ising(h, J, **parameters)

Sample from an Ising model using the implemented sample method.

NullSampler.sample_qubo(Q, **parameters)

Sample from a QUBO using the implemented sample method.

Random Sampler

A sampler that gives random samples.

Class

class RandomSampler[source]

A sampler that gives random samples for testing.

Examples

This example produces 10 samples for a two-variable problem.

>>> bqm = dimod.BinaryQuadraticModel.from_qubo({('a', 'b'): 1})
>>> sampler = dimod.RandomSampler()
>>> sampleset = sampler.sample(bqm, num_reads=10)
>>> len(sampleset)
10

Properties

RandomSampler.parameters

Keyword arguments accepted by the sampling methods.

Methods

RandomSampler.sample(bqm[, num_reads, seed])

Give random samples for a binary quadratic model.

RandomSampler.sample_ising(h, J, **parameters)

Sample from an Ising model using the implemented sample method.

RandomSampler.sample_qubo(Q, **parameters)

Sample from a QUBO using the implemented sample method.

Simulated Annealing Sampler

A reference implementation of a simulated annealing sampler.

neal.sampler.SimulatedAnnealingSampler is a more performant implementation of simulated annealing you can use for solving problems.

Class

class SimulatedAnnealingSampler[source]

A simple simulated annealing sampler for testing and debugging code.

Examples

This example solves a two-variable Ising model.

>>> h = {'a': -0.5, 'b': 1.0}
>>> J = {('a', 'b'): -1.5}
>>> sampleset = dimod.SimulatedAnnealingSampler().sample_ising(h, J)
>>> sampleset.first.sample
{'a': -1, 'b': -1}

Properties

SimulatedAnnealingSampler.parameters

Keyword arguments accepted by the sampling methods.

Methods

SimulatedAnnealingSampler.sample(bqm[, ...])

Sample from low-energy spin states using simulated annealing.

SimulatedAnnealingSampler.sample_ising(h, J, ...)

Sample from an Ising model using the implemented sample method.

SimulatedAnnealingSampler.sample_qubo(Q, ...)

Sample from a QUBO using the implemented sample method.