Composites¶

The dimod package includes several example composed samplers.

Connected Components Composite¶

A composite that breaks the problem into sub-problems corresponding to the connected components of the binary quadratic model graph before sending to its child sampler.

Class¶

class ConnectedComponentsComposite(child_sampler)[source]¶

Composite to decompose a problem to the connected components and solve each.

Connected components of a binary quadratic model (BQM) graph are computed (if not provided), and each subproblem is passed to the child sampler. Returned samples from each child sampler are merged. Only the best solution of each response is pick and merge with others (i.e. this composite returns a single solution).

Parameters: sampler (dimod.Sampler) – A dimod sampler

Examples

This example uses ConnectedComponentsComposite to solve a simple Ising problem that can be separated into two components. This small example uses dimod.ExactSolver and is just illustrative.

>>> h = {}
>>> J1 = {(1, 2): -1.0, (2, 3): 2.0, (3, 4): 3.0}
>>> J2 = {(12, 13): 6}
>>> sampler = dimod.ExactSolver()
>>> sampler_ccc = dimod.ConnectedComponentsComposite(sampler)
>>> e1 = sampler.sample_ising(h, J1).first.energy
>>> e2 = sampler.sample_ising(h, J2).first.energy
>>> e_ccc = sampler_ccc.sample_ising(h, {**J1, **J2}).first.energy
>>> e_ccc == e1 + e2
True

Properties¶

`ConnectedComponentsComposite.child`	The child sampler.
`ConnectedComponentsComposite.children`	List of child samplers that that are used by this composite.
`ConnectedComponentsComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`ConnectedComponentsComposite.properties`	A dict containing any additional information about the sampler.

Methods¶

`ConnectedComponentsComposite.sample`(bqm[, …])	Sample from the provided binary quadratic model.
`ConnectedComponentsComposite.sample_ising`(h, …)	Sample from an Ising model using the implemented sample method.
`ConnectedComponentsComposite.sample_qubo`(Q, …)	Sample from a QUBO using the implemented sample method.

Clip Composite¶

A composite that clips problem variables below and above threshold. if lower and upper bounds is not given it does nothing.

Class¶

class ClipComposite(child_sampler)[source]¶

Composite to clip variables of a problem.

Clips the variables of a binary quadratic model (BQM) and modifies linear and quadratic terms accordingly.

Parameters: sampler (dimod.Sampler) – A dimod sampler.

Examples

This example uses ClipComposite to instantiate a composed sampler that submits a simple Ising problem to a sampler. The composed sampler clips linear and quadratic biases as indicated by options.

>>> h = {'a': -4.0, 'b': -4.0}
>>> J = {('a', 'b'): 3.2}
>>> sampler = dimod.ClipComposite(dimod.ExactSolver())
>>> response = sampler.sample_ising(h, J, lower_bound=-2.0, upper_bound=2.0)

Properties¶

`ClipComposite.child`	The child sampler.
`ClipComposite.children`	List of child samplers that that are used by this composite.
`ClipComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`ClipComposite.properties`	A dict containing any additional information about the sampler.

Methods¶

`ClipComposite.sample`(bqm[, lower_bound, …])	Clip and sample from the provided binary quadratic model.
`ClipComposite.sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`ClipComposite.sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Fixed Variable Composite¶

A composite that fixes the variables provided and removes them from the binary quadratic model before sending to its child sampler.

Class¶

class FixedVariableComposite(child_sampler)[source]¶

Composite to fix variables of a problem to provided.

Fixes variables of a binary quadratic model (BQM) and modifies linear and quadratic terms accordingly. Returned samples include the fixed variable

Parameters: sampler (dimod.Sampler) – A dimod sampler

Examples

This example uses FixedVariableComposite to instantiate a composed sampler that submits a simple Ising problem to a sampler. The composed sampler fixes a variable and modifies linear and quadratic biases according.

>>> h = {1: -1.3, 4: -0.5}
>>> J = {(1, 4): -0.6}
>>> sampler = dimod.FixedVariableComposite(dimod.ExactSolver())
>>> sampleset = sampler.sample_ising(h, J, fixed_variables={1: -1})

Properties¶

`FixedVariableComposite.child`	The child sampler.
`FixedVariableComposite.children`	List of child samplers that that are used by this composite.
`FixedVariableComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`FixedVariableComposite.properties`	A dict containing any additional information about the sampler.

Methods¶

`FixedVariableComposite.sample`(bqm[, …])	Sample from the provided binary quadratic model.
`FixedVariableComposite.sample_ising`(h, J, …)	Sample from an Ising model using the implemented sample method.
`FixedVariableComposite.sample_qubo`(Q, …)	Sample from a QUBO using the implemented sample method.

Roof Duality Composite¶

A composite that uses the roof duality algorithm 1 2 to fix some variables in the binary quadratic model before passing it on to its child sampler.

1: Boros, E., P.L. Hammer, G. Tavares. Preprocessing of Unconstrained Quadratic Binary Optimization. Rutcor Research Report 10-2006, April, 2006.
2: Boros, E., P.L. Hammer. Pseudo-Boolean optimization. Discrete Applied Mathematics 123, (2002), pp. 155-225

Class¶

class RoofDualityComposite(child_sampler)[source]¶

Uses roof duality to assign some variables before invoking child sampler.

Uses the fix_variables() function to determine variable assignments, then fixes them before calling the child sampler. Returned samples include the fixed variables.

Parameters: child (dimod.Sampler) – A dimod sampler. Used to sample the binary quadratic model after variables have been fixed.

Properties¶

`RoofDualityComposite.child`	The child sampler.
`RoofDualityComposite.children`	List of child samplers that that are used by this composite.
`RoofDualityComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`RoofDualityComposite.properties`	A dict containing any additional information about the sampler.

Methods¶

`RoofDualityComposite.sample`(bqm[, sampling_mode])	Sample from the provided binary quadratic model.
`RoofDualityComposite.sample_ising`(h, J, …)	Sample from an Ising model using the implemented sample method.
`RoofDualityComposite.sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

Scale Composite¶

A composite that scales problem variables as directed. If a scaling value is not specified, calculates it based on quadratic and bias ranges.

Class¶

class ScaleComposite(child_sampler)[source]¶

Composite that scales variables of a problem.

Scales the variables of a binary quadratic model (BQM) and modifies linear and quadratic terms accordingly.

Parameters: sampler (dimod.Sampler) – A dimod sampler.

Examples

This example uses ScaleComposite to instantiate a composed sampler that submits a simple Ising problem to a sampler. The composed sampler scales linear biases, quadratic biases, and offset as indicated by options.

>>> h = {'a': -4.0, 'b': -4.0}
>>> J = {('a', 'b'): 3.2}
>>> sampler = dimod.ScaleComposite(dimod.ExactSolver())
>>> response = sampler.sample_ising(h, J, scalar=0.5,
...                ignored_interactions=[('a','b')])

Properties¶

`ScaleComposite.child`	The child sampler.
`ScaleComposite.children`	List of child samplers that that are used by this composite.
`ScaleComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`ScaleComposite.properties`	A dict containing any additional information about the sampler.

Methods¶

`ScaleComposite.sample`(bqm[, scalar, …])	Scale and sample from the provided binary quadratic model.
`ScaleComposite.sample_ising`(h, J, **parameters)	Sample from an Ising model using the implemented sample method.
`ScaleComposite.sample_qubo`(Q, **parameters)	Sample from a QUBO using the implemented sample method.

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

Parameters: sampler – A dimod sampler object.

Examples

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

>>> base_sampler = dimod.ExactSolver()
>>> composed_sampler = dimod.SpinReversalTransformComposite(base_sampler)
... # Sample an Ising problem
>>> response = composed_sampler.sample_ising({'a': -0.5, 'b': 1.0}, {('a', 'b'): -1})
>>> response.first.sample
{'a': -1, 'b': -1}

References

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

Properties¶

`SpinReversalTransformComposite.child`	The child sampler.
`SpinReversalTransformComposite.children`
`SpinReversalTransformComposite.parameters`
`SpinReversalTransformComposite.properties`

Methods¶

`SpinReversalTransformComposite.sample`(bqm[, …])	Sample from the binary quadratic model.
`SpinReversalTransformComposite.sample_ising`(h, …)	Sample from an Ising model using the implemented sample method.
`SpinReversalTransformComposite.sample_qubo`(Q, …)	Sample from a QUBO using the implemented sample method.

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.

>>> 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 does not match the sampler's structure

Properties¶

`StructureComposite.child`	The child sampler.
`StructureComposite.children`
`StructureComposite.parameters`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`StructureComposite.properties`	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)[source]¶

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 ScaleComposite, TrackingComposite, ExactSolver
...
>>> sampler = ScaleComposite(TrackingComposite(ExactSolver()))
>>> sampler.child.inputs  # empty because we haven't called sample
[]

>>> intermediate_sampler = TrackingComposite(ExactSolver())
>>> sampler = ScaleComposite(intermediate_sampler)
>>> 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`	A dict where keys are the keyword parameters accepted by the sampler methods and values are lists of the properties relevent to each parameter.
`TrackingComposite.properties`	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 response based on options provided by the user.

Class¶

class TruncateComposite(child_sampler, n, sorted_by='energy', aggregate=False)[source]¶

Composite to truncate the returned samples

Inherits from dimod.ComposedSampler.

Post-processing is expensive and sometimes one might want to only treat the lowest energy samples. This composite layer allows one 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, aggregate the samples before truncating.

Note

If aggregate is True SampleSet.record.num_occurrences are accumulated but no other fields are.

Properties¶

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

Methods¶

`TruncateComposite.sample`(bqm, **kwargs)	Sample from the problem provided by BQM and truncate output.
`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.