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

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