# 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
>>> x, y, z = Binaries(['x', 'y', 'z'])
>>> cqm.set_objective(x*y + 2*y*z)
'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]


>>> 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()
>>> 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. Sample from an Ising model using the implemented sample method. Sample from a QUBO using the implemented sample method.