Composites

The dimod package includes several example composed samplers:

The dwave-system package provides additional composites for D-Wave systems such as those used for minor-embedding.

Structure Composite

A composite that structures a sampler.

Class

class StructureComposite(sampler, nodelist, edgelist)

Creates a structured composed sampler from an unstructured sampler.

Useful for simulation; for example testing a QPU’s working graph with the SimulatedAnnealingSampler class.

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 unstructured dimod ExactSolver sampler. The target structure is a square graph.

>>> 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)
>>> response.first.energy
-1.0

The next part of the example tries 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 contains an interaction, (0, 2), not supported by the structured solver

Properties

StructureComposite.child	The child sampler.
StructureComposite.children
StructureComposite.parameters	Parameters as a dict, where keys are keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
StructureComposite.properties	Properties as a dict containing any additional information about the sampler.

Methods

StructureComposite.sample(bqm, **sample_kwargs)	Sample from the binary quadratic model.
StructureComposite.sample_ising(h, J, ...)	Sample from an Ising model using the implemented sample method.
StructureComposite.sample_qubo(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Tracking Composite

A composite that tracks inputs and outputs.

Class

class TrackingComposite(child, copy=False)

Composite that tracks inputs and outputs for debugging and testing.

Parameters:

• child (dimod.Sampler) – A dimod sampler.

• copy (bool, optional, default=False) – If True, the inputs/outputs are copied (with copy.deepcopy()) before they are stored. This is useful if the child sampler mutates the values.

Examples

>>> sampler = dimod.TrackingComposite(dimod.RandomSampler())
>>> sampleset = sampler.sample_ising({'a': -1}, {('a', 'b'): 1},
...                                  num_reads=5)
>>> sampler.input
OrderedDict([('h', {'a': -1}), ('J', {('a', 'b'): 1}), ('num_reads', 5)])
>>> sampleset == sampler.output
True

If we make additional calls to the sampler, the most recent input/output are stored in input and output respectively. However, all are tracked in inputs and outputs.

>>> sampleset = sampler.sample_qubo({('a', 'b'): 1})
>>> sampler.input
OrderedDict([('Q', {('a', 'b'): 1})])
>>> sampler.inputs 
[OrderedDict([('h', {'a': -1}), ('J', {('a', 'b'): 1}), ('num_reads', 5)]),
 OrderedDict([('Q', {('a', 'b'): 1})])]

In the case that you want to nest the tracking composite, there are two patterns for retrieving the data

>>> from dimod import TruncateComposite, TrackingComposite, ExactSolver
...
>>> sampler = TruncateComposite(TrackingComposite(ExactSolver()), 10)
>>> sampler.child.inputs  # empty because we haven't called sample
[]

>>> intermediate_sampler = TrackingComposite(ExactSolver())
>>> sampler = TruncateComposite(intermediate_sampler, 10)
>>> intermediate_sampler.inputs
[]

Properties

TrackingComposite.input	The most recent input to any sampling method.
TrackingComposite.inputs	All of the inputs to any sampling methods.
TrackingComposite.output	The most recent output of any sampling method.
TrackingComposite.outputs	All of the outputs from any sampling methods.
TrackingComposite.parameters	Parameters as a dict, where keys are keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
TrackingComposite.properties	Properties as a dict containing any additional information about the sampler.

Methods

TrackingComposite.clear()	Clear all the inputs/outputs.
TrackingComposite.sample(bqm, **parameters)	Sample from the child sampler and store the given inputs/outputs.
TrackingComposite.sample_ising(h, J, ...)	Sample from the child sampler and store the given inputs/outputs.
TrackingComposite.sample_qubo(Q, **parameters)	Sample from the child sampler and store the given inputs/outputs.

Truncate Composite

A composite that truncates the returned dimod.SampleSet based on options specified by the user.

Class

class TruncateComposite(child_sampler, n, sorted_by='energy', aggregate=False)

Composite to truncate the returned sample set.

Inherits from dimod.ComposedSampler.

Post-processing can be expensive and sometimes you might want to only handle the lowest-energy samples. This composite layer allows you to pre-select the samples within a multi-composite pipeline.

Parameters:

• child_sampler (dimod.Sampler) – A dimod sampler.

• n (int) – Maximum number of rows in the returned sample set.

• sorted_by (str/None, optional, default='energy') – Selects the record field used to sort the samples before truncating. Note that sample order is maintained in the underlying array.

• aggregate (bool, optional, default=False) – If True, aggregates the samples before truncating and sets the value of the num_occurrences field in the returned SampleSet to the number of accumulated samples for each occurrence.

Examples

>>> sampler = dimod.TruncateComposite(dimod.RandomSampler(), n=2, aggregate=True)
>>> bqm = dimod.BinaryQuadraticModel.from_ising({"a": 1, "b": 2}, {("a", "b"): -1})
>>> sampleset = sampler.sample(bqm, num_reads=100)
>>> print(sampleset)                                 
   a  b energy num_oc.
0 -1 -1   -4.0      16
1 +1 -1    0.0      22
['SPIN', 2 rows, 38 samples, 2 variables]

Properties

TruncateComposite.child	The child sampler.
TruncateComposite.children	List of child samplers that that are used by this composite.
TruncateComposite.parameters	Parameters as a dict, where keys are keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
TruncateComposite.properties	Properties as a dict containing any additional information about the sampler.

Methods

TruncateComposite.sample(bqm, **kwargs)	Sample from the binary quadratic model and truncate returned sample set.
TruncateComposite.sample_ising(h, J, ...)	Sample from an Ising model using the implemented sample method.
TruncateComposite.sample_qubo(Q, **parameters)	Sample from a QUBO using the implemented sample method.