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

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]

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 CQM Solver

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 assignments. It becomes slow very quickly

Examples

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

>>> from dimod import ConstrainedQuadraticModel, Binaries, ExactCQMSolver
>>> cqm = ConstrainedQuadraticModel()
>>> x, y, z = Binaries(['x', 'y', 'z'])
>>> cqm.set_objective(x*y + 2*y*z)
>>> cqm.add_constraint(x*y == 1, label='constraint_1')
'constraint_1'
>>> sampleset = 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.

Exact DQM Solver

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\) cases, this results in \(k_1 * k_2 * ... * k_n\) cases, which grows exponentially for constant \(k_i\) in the number of variables.

Methods

ExactDQMSolver.sample_dqm(dqm, **kwargs)

Sample from a discrete quadratic model.

Identity Sampler

class IdentitySampler[source]

A sampler that can return, expand, or truncate the provided initial states.

Examples:

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

Add randomly generated samples:

>>> sampleset = sampler.sample_qubo(Q, initial_states=samples, num_reads=4)
>>> print(sampleset)                                  
   a  b energy num_oc.
2  1  1   -1.0       1
3  1  1   -1.0       1
0  1  0    0.0       1
1  0  1    0.0       1
['BINARY', 4 rows, 4 samples, 2 variables]

Note that in the above output, the specified initial states are printed after the generated lower-energy samples but are the first samples in the record.

Properties

IdentitySampler.parameters

Keyword arguments accepted by the sampling methods.

Methods

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

Return, expand, or truncate 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

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

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])

Return 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

Tip

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

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.