# Samplers¶

The dimod package includes several example samplers.

## 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)   # doctest: +SKIP
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) 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.

## 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()
>>> 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.