Reference Samplers and Composites¶

The dimod package includes several example samplers and composed samplers.

Samplers¶

The reference samplers included in the dimod package are intended as an aid for coding and testing; they are not optimized for performance or intended for benchmarking.

Exact Sampler¶

An exact solver that calculates the energy of all possible samples.

Class¶

class ExactSolver[source]¶

A simple exact solver for testing and debugging.

Notes

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

Examples

This example solves a two-variable Ising model.

>>> import dimod
>>> response = dimod.ExactSolver().sample_ising({'a': -0.5, 'b': 1.0}, {('a', 'b'): -1})
>>> response.data_vectors['energy']
array([-1.5, -0.5, -0.5,  2.5])

Methods¶

ExactSolver.sample(bqm, **kwargs) Sample from a binary quadratic model.

Simulated Annealing¶

A reference implementation of a simulated annealing sampler.

Class¶

class SimulatedAnnealingSampler[source]¶

A simple simulated annealing sampler.

Examples

This example solves a two-variable Ising model.

>>> import dimod
>>> response = dimod.SimulatedAnnealingSampler().sample_ising(
...                  {'a': -0.5, 'b': 1.0}, {('a', 'b'): -1})
>>> response.data_vectors['energy']      
array([-1.5, -1.5, -1.5, -1.5, -1.5, -1.5, -1.5, -1.5, -1.5, -1.5])

Methods¶

SimulatedAnnealingSampler.sample(bqm[, …]) Sample from low-energy spin states using simulated annealing.

Random Sampler¶

A random sampler for unit testing and debugging.

Class¶

class RandomSampler[source]¶

A sampler that gives random samples for testing.

Examples

This example provides random samples for a two-variable QUBO model.

>>> import dimod
>>> response = dimod.RandomSampler().sample_qubo({(0, 0): -1, (1, 1): -1, (0, 1): 2}, num_reads=5)
>>> len(response)
5
>>> print(next(response.data()))      
Sample(sample={0: 1, 1: 0}, energy=-1.0)

Methods¶

RandomSampler.sample(bqm[, num_reads]) Give random samples for a binary quadratic model.

Composites¶

Spin Reversal Transform Composite¶

On the D-Wave system, coupling \(J_{i,j}\) adds a small bias to qubits \(i\) and \(j\) due to leakage. This can become significant for chained qubits. Additionally, qubits are biased to some small degree in one direction or another. Applying a spin-reversal transform can improve results by reducing the impact of possible analog and systematic errors. A spin-reversal transform does not alter the Ising problem; the transform simply amounts to reinterpreting spin up as spin down, and visa-versa, for a particular spin.

Class¶

class SpinReversalTransformComposite(child)[source]¶

Composite for applying spin reversal transform preprocessing.

Spin reversal transforms (or “gauge transformations”) are applied by flipping the spin of variables in the Ising problem. After sampling the transformed Ising problem, the same bits are flipped in the resulting sample.

Parameters:	sampler – A dimod sampler object.

children¶: list – [sampler] where sampler is the input sampler.

structure¶: Inherited from input sampler.

Examples

This example composes a dimod ExactSolver sampler with spin transforms then uses it to sample an Ising problem.

>>> import dimod
>>> # Compose the sampler
>>> base_sampler = dimod.ExactSolver()
>>> composed_sampler = dimod.SpinReversalTransformComposite(base_sampler)
>>> base_sampler in composed_sampler.children
True
>>> # Sample an Ising problem
>>> response = composed_sampler.sample_ising({'a': -0.5, 'b': 1.0}, {('a', 'b'): -1})
>>> print(next(response.data()))           
Sample(sample={'a': 1, 'b': 1}, energy=-1.5)

References

[KM]	Andrew D. King and Catherine C. McGeoch. Algorithm engineering for a quantum annealing platform. https://arxiv.org/abs/1410.2628, 2014.

Methods¶

SpinReversalTransformComposite.sample(bqm[, …]) Sample from the binary quadratic model.

Structured Composite¶

A composite that structures a sampler.

Class¶

class StructureComposite(sampler, nodelist, edgelist)[source]¶

Creates a structured composed sampler from an unstructured sampler.

Parameters:	Sampler (`Sampler`) – Unstructured sampler. nodelist (list) – Nodes/variables allowed by the sampler formatted as a list. edgelist (list[(node, node)]) – Edges/interactions allowed by the sampler, formatted as a list where each edge/interaction is a 2-tuple.

Examples

This example creates a composed sampler from the unstructure dimod ExactSolver sampler. The target structure is a square graph.

>>> import dimod
>>> base_sampler = dimod.ExactSolver()
>>> node_list = [0, 1, 2, 3]
>>> edge_list = [(0, 1), (1, 2), (2, 3), (0, 3)]
>>> structured_sampler = dimod.StructureComposite(base_sampler, node_list, edge_list)
>>> linear = {0: 0.0, 1: 0.0, 2: 0.0, 3: 0.0}
>>> quadratic = {(0, 1): 1.0, (1, 2): 1.0, (0, 3): 1.0, (2, 3): -1.0}
>>> bqm = dimod.BinaryQuadraticModel(linear, quadratic, 1.0, dimod.Vartype.SPIN)
>>> response = structured_sampler.sample(bqm)
>>> print(next(response.data()))
Sample(sample={0: 1, 1: -1, 2: -1, 3: -1}, energy=-1.0)
>>> # Try giving the composed sampler a non-square model
>>> del quadratic[(0, 1)]
>>> quadratic[(0, 2)] = 1.0
>>> bqm = dimod.BinaryQuadraticModel(linear, quadratic, 1.0, dimod.Vartype.SPIN)
>>> try: response = structured_sampler.sample(bqm)    
... except dimod.BinaryQuadraticModelStructureError as details:
...     print(details)
...
given bqm does not match the sampler's structure

Methods¶

StructureComposite.sample(bqm, **kwargs) Sample from the binary quadratic model.