Composites¶
dimod composites that provide layers of pre and postprocessing (e.g., minorembedding) when using the DWave system.
Contents
CutOffs¶
Prunes the binary quadratic model (BQM) submitted to the child sampler by retaining only interactions with values commensurate with the sampler’s precision.
CutOffComposite¶

class
CutOffComposite
(child_sampler, cutoff, cutoff_vartype=<Vartype.SPIN: frozenset({1, 1})>, comparison=<builtin function lt>)[source]¶ Composite to remove interactions below a specified cutoff value.
Prunes the binary quadratic model (BQM) submitted to the child sampler by retaining only interactions with values commensurate with the sampler’s precision as specified by the cutoff argument. Also removes variables isolated post or preremoval of these interactions from the BQM passed on to the child sampler, setting these variables to values that minimize the original BQM’s energy for the returned samples.
Parameters:  sampler (
dimod.Sampler
) – A dimod sampler.  cutoff (number) – Lower bound for absolute value of interactions. Interactions with absolute values lower than cutoff are removed. Isolated variables are also not passed on to the child sampler.
 cutoff_vartype (
Vartype
/str/set, default=’SPIN’) –Variable space to execute the removal in. Accepted input values:
Vartype.SPIN
,'SPIN'
,{1, 1}
Vartype.BINARY
,'BINARY'
,{0, 1}
 comparison (function, optional) – A comparison operator for comparing interaction values to the cutoff
value. Defaults to
operator.lt()
.
Examples
This example removes one interaction, ‘ac’: 0.7, before embedding on a DWave system. Note that the lowestenergy sample for the embedded problem is {‘a’: 1, ‘b’: 1, ‘c’: 1} but with a large enough number of samples (here num_reads=1000), the lowestenergy solution to the complete BQM is likely found and its energy recalculated by the composite.
>>> import dimod >>> sampler = DWaveSampler(solver={'qpu': True}) >>> bqm = dimod.BinaryQuadraticModel({'a': 1, 'b': 1, 'c': 1}, ... {'ab': 0.8, 'ac': 0.7, 'bc': 1}, ... 0, ... dimod.SPIN) >>> CutOffComposite(AutoEmbeddingComposite(sampler), 0.75).sample(bqm, ... num_reads=1000).first.energy 3.5
 sampler (
Properties¶
CutOffComposite.child 
The child sampler. 
CutOffComposite.children 
List of child samplers that that are used by this composite. 
CutOffComposite.properties 
A dict containing any additional information about the sampler. 
CutOffComposite.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. 
Methods¶
CutOffComposite.sample (bqm, **parameters) 
Cut off interactions and sample from the provided binary quadratic model. 
CutOffComposite.sample_ising (h, J, **parameters) 
Sample from an Ising model using the implemented sample method. 
CutOffComposite.sample_qubo (Q, **parameters) 
Sample from a QUBO using the implemented sample method. 
PolyCutOffComposite¶
Prunes the polynomial submitted to the child sampler by retaining only interactions with values commensurate with the sampler’s precision.

class
PolyCutOffComposite
(child_sampler, cutoff, cutoff_vartype=<Vartype.SPIN: frozenset({1, 1})>, comparison=<builtin function lt>)[source]¶ Composite to remove polynomial interactions below a specified cutoff value.
Prunes the binary polynomial submitted to the child sampler by retaining only interactions with values commensurate with the sampler’s precision as specified by the cutoff argument. Also removes variables isolated post or preremoval of these interactions from the polynomial passed on to the child sampler, setting these variables to values that minimize the original polynomial’s energy for the returned samples.
Parameters:  sampler (
dimod.PolySampler
) – A dimod binary polynomial sampler.  cutoff (number) – Lower bound for absolute value of interactions. Interactions with absolute values lower than cutoff are removed. Isolated variables are also not passed on to the child sampler.
 cutoff_vartype (
Vartype
/str/set, default=’SPIN’) –Variable space to do the cutoff in. Accepted input values:
Vartype.SPIN
,'SPIN'
,{1, 1}
Vartype.BINARY
,'BINARY'
,{0, 1}
 comparison (function, optional) – A comparison operator for comparing the interaction value to the cutoff
value. Defaults to
operator.lt()
.
Examples
This example removes one interaction, ‘ac’: 0.2, before submitting the polynomial to child sampler ExactSolver().
>>> import dimod >>> sampler = dimod.HigherOrderComposite(dimod.ExactSolver()) >>> poly = dimod.BinaryPolynomial({'a': 3, 'abc':4, 'ac': 0.2}, dimod.SPIN) >>> PolyCutOffComposite(sampler, 1).sample_poly(poly).first.sample['a'] 1
 sampler (
Properties¶
PolyCutOffComposite.child 
The child sampler. 
PolyCutOffComposite.children 
List of child samplers that that are used by this composite. 
PolyCutOffComposite.properties 
A dict containing any additional information about the sampler. 
PolyCutOffComposite.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. 
Methods¶
PolyCutOffComposite.sample_poly (poly, **kwargs) 
Cutoff and sample from the provided binary polynomial. 
PolyCutOffComposite.sample_hising (h, J, **kwargs) 
Sample from a higherorder Ising model. 
PolyCutOffComposite.sample_hubo (H, **kwargs) 
Sample from a higherorder unconstrained binary optimization problem. 
Embedding¶
Minorembed a problem BQM into a DWave system.
Embedding composites for various types of problems and application. For example:
EmbeddingComposite
for a problem with arbitrary structure that likely requires hueristic embedding.AutoEmbeddingComposite
can save unnecessary embedding for problems that might have a structure similar to the child sampler.LazyFixedEmbeddingComposite
can benefit applications that resubmit a BQM with changes in some values.
AutoEmbeddingComposite¶

class
AutoEmbeddingComposite
(child_sampler, **kwargs)[source]¶ Maps problems to a structured sampler, embedding if needed.
This composite first tries to submit the binary quadratic model directly to the child sampler and only embeds if a
dimod.exceptions.BinaryQuadraticModelStructureError
is raised.Parameters:  sampler (
dimod.Sampler
) – Structured dimod sampler, such as aDWaveSampler()
.  find_embedding (function, optional) – A function find_embedding(S, T, **kwargs) where S and T
are edgelists. The function can accept additional keyword arguments.
Defaults to
minorminer.find_embedding()
.  kwargs – See the
EmbeddingComposite
class for additional keyword arguments.
 sampler (
Properties¶
AutoEmbeddingComposite.child 
The child sampler. 
AutoEmbeddingComposite.parameters 

AutoEmbeddingComposite.properties 
Methods¶
AutoEmbeddingComposite.sample (bqm, **parameters) 
Sample from the provided binary quadratic model. 
AutoEmbeddingComposite.sample_ising (h, J, …) 
Sample from an Ising model using the implemented sample method. 
AutoEmbeddingComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 
EmbeddingComposite¶

class
EmbeddingComposite
(child_sampler, find_embedding=<function find_embedding>, embedding_parameters=None, scale_aware=False, child_structure_search=<function child_structure_dfs>)[source]¶ Maps problems to a structured sampler.
Automatically minorembeds a problem into a structured sampler such as a DWave system. A new minorembedding is calculated each time one of its sampling methods is called.
Parameters:  child_sampler (
dimod.Sampler
) – A dimod sampler, such as aDWaveSampler
, that accepts only binary quadratic models of a particular structure.  find_embedding (function, optional) – A function find_embedding(S, T, **kwargs) where S and T
are edgelists. The function can accept additional keyword arguments.
Defaults to
minorminer.find_embedding()
.  embedding_parameters (dict, optional) – If provided, parameters are passed to the embedding method as keyword arguments.
 scale_aware (bool, optional, default=False) – Pass chain interactions to child samplers that accept an ignored_interactions parameter.
 child_structure_search (function, optional) – A function child_structure_search(sampler) that accepts a sampler
and returns the
dimod.Structured.structure
. Defaults todimod.child_structure_dfs()
.
Examples
>>> from dwave.system import DWaveSampler, EmbeddingComposite ... >>> sampler = EmbeddingComposite(DWaveSampler()) >>> h = {'a': 1., 'b': 2} >>> J = {('a', 'b'): 1.5} >>> sampleset = sampler.sample_ising(h, J, num_reads=100) >>> sampleset.first.energy 4.5
 child_sampler (
Properties¶
EmbeddingComposite.child 
The child sampler. 
EmbeddingComposite.parameters 
Parameters in the form of a dict. 
EmbeddingComposite.properties 
Properties in the form of a dict. 
EmbeddingComposite.return_embedding_default 
Defines the default behaviour for sample() ’s return_embedding kwarg. 
EmbeddingComposite.warnings_default 
Defines the default behabior for sample() ’s warnings kwarg. 
Methods¶
EmbeddingComposite.sample (bqm[, …]) 
Sample from the provided binary quadratic model. 
EmbeddingComposite.sample_ising (h, J, …) 
Sample from an Ising model using the implemented sample method. 
EmbeddingComposite.sample_qubo (Q, **parameters) 
Sample from a QUBO using the implemented sample method. 
FixedEmbeddingComposite¶

class
FixedEmbeddingComposite
(child_sampler, embedding=None, source_adjacency=None, **kwargs)[source]¶ Maps problems to a structured sampler with the specified minorembedding.
Parameters:  sampler (dimod.Sampler) – Structured dimod sampler such as a DWave system.
 embedding (dict[hashable, iterable], optional) – Mapping from a source graph to the specified sampler’s graph (the target graph).
 source_adjacency (dict[hashable, iterable]) – Deprecated. Dictionary to describe source graph. Ex. {node: {node neighbours}}.
 kwargs – See the
EmbeddingComposite
class for additional keyword arguments. Note that find_embedding and embedding_parameters keyword arguments are ignored.
Examples
>>> from dwave.system import DWaveSampler, FixedEmbeddingComposite ... >>> embedding = {'a': [0, 4], 'b': [1, 5], 'c': [2, 6]} >>> sampler = FixedEmbeddingComposite(DWaveSampler(), embedding) >>> sampler.nodelist ['a', 'b', 'c'] >>> sampler.edgelist [('a', 'b'), ('a', 'c'), ('b', 'c')] >>> sampleset = sampler.sample_ising({'a': .5, 'c': 0}, {('a', 'c'): 1}, num_reads=500) >>> sampleset.first.energy 1.5
Properties¶
FixedEmbeddingComposite.properties 

FixedEmbeddingComposite.parameters 

FixedEmbeddingComposite.children 

FixedEmbeddingComposite.child 
The child sampler. 
FixedEmbeddingComposite.nodelist 
Nodes available to the composed sampler. 
FixedEmbeddingComposite.edgelist 
Edges available to the composed sampler. 
FixedEmbeddingComposite.adjacency 
Adjacency structure for the composed sampler. 
FixedEmbeddingComposite.structure 
Structure of the structured sampler formatted as a namedtuple , Structure(nodelist, edgelist, adjacency), where the 3tuple values are the nodelist , edgelist and adjacency attributes. 
Methods¶
FixedEmbeddingComposite.sample (bqm, **parameters) 
Sample the binary quadratic model. 
FixedEmbeddingComposite.sample_ising (h, J, …) 
Sample from an Ising model using the implemented sample method. 
FixedEmbeddingComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 
LazyFixedEmbeddingComposite¶

class
LazyFixedEmbeddingComposite
(child_sampler, find_embedding=<function find_embedding>, embedding_parameters=None, scale_aware=False, child_structure_search=<function child_structure_dfs>)[source]¶ Maps problems to the structure of its first given problem.
This composite reuses the minorembedding found for its first given problem without recalculating a new minorembedding for subsequent calls of its sampling methods.
Parameters:  sampler (dimod.Sampler) – Structured dimod sampler.
 find_embedding (function, default=:func:minorminer.find_embedding) – A function find_embedding(S, T, **kwargs) where S and T are edgelists. The function can accept additional keyword arguments. The function is used to find the embedding for the first problem solved.
 embedding_parameters (dict, optional) – If provided, parameters are passed to the embedding method as keyword arguments.
Examples
>>> from dwave.system import LazyFixedEmbeddingComposite, DWaveSampler ... >>> sampler = LazyFixedEmbeddingComposite(DWaveSampler()) >>> sampler.nodelist is None # no structure prior to first sampling True >>> __ = sampler.sample_ising({}, {('a', 'b'): 1}) >>> sampler.nodelist # has structure based on given problem ['a', 'b']
Properties¶
LazyFixedEmbeddingComposite.parameters 

LazyFixedEmbeddingComposite.properties 

LazyFixedEmbeddingComposite.nodelist 
Nodes available to the composed sampler. 
LazyFixedEmbeddingComposite.edgelist 
Edges available to the composed sampler. 
LazyFixedEmbeddingComposite.adjacency 
Adjacency structure for the composed sampler. 
LazyFixedEmbeddingComposite.structure 
Structure of the structured sampler formatted as a namedtuple , Structure(nodelist, edgelist, adjacency), where the 3tuple values are the nodelist , edgelist and adjacency attributes. 
Methods¶
LazyFixedEmbeddingComposite.sample (bqm, …) 
Sample the binary quadratic model. 
LazyFixedEmbeddingComposite.sample_ising (h, …) 
Sample from an Ising model using the implemented sample method. 
LazyFixedEmbeddingComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 
TilingComposite¶

class
TilingComposite
(sampler, sub_m, sub_n, t=4)[source]¶ Composite to tile a small problem across a Chimerastructured sampler.
Enables parallel sampling for small problems (problems that are minorembeddable in a small part of a DWave solver’s Chimera graph).
Notation CN refers to a Chimera graph consisting of an NxN grid of unit cells, where each unit cell is a bipartite graph with shores of size t. The DWave 2000Q QPU supports a C16 Chimera graph: its 2048 qubits are logically mapped into a 16x16 matrix of unit cell of 8 qubits (t=4).
A problem that can be minorembedded in a single unit cell, for example, can therefore be tiled across the unit cells of a DWave 2000Q as 16x16 duplicates. This enables sampling 256 solutions in a single call.
Parameters:  sampler (
dimod.Sampler
) – Structured dimod sampler such as aDWaveSampler()
.  sub_m (int) – Number of rows of Chimera unit cells for minorembedding the problem once.
 sub_n (int) – Number of columns of Chimera unit cells for minorembedding the problem once.
 t (int, optional, default=4) – Size of the shore within each Chimera unit cell.
Examples
This example submits a twovariable QUBO problem representing a logical NOT gate to a DWave system. The QUBO—two nodes with biases of 1 that are coupled with strength 2—needs only any two coupled qubits and so is easily minorembedded in a single unit cell. Composite
TilingComposite
tiles it multiple times for parallel solution: the two nodes should typically have opposite values.>>> from dwave.system import DWaveSampler, EmbeddingComposite >>> from dwave.system import TilingComposite ... >>> sampler = EmbeddingComposite(TilingComposite(DWaveSampler(), 1, 1, 4)) >>> Q = {(1, 1): 1, (1, 2): 2, (2, 1): 0, (2, 2): 1} >>> sampleset = sampler.sample_qubo(Q) >>> len(sampleset)> 1 True
See Ocean Glossary for explanations of technical terms in descriptions of Ocean tools.
 sampler (
Properties¶
TilingComposite.properties 
Properties in the form of a dict. 
TilingComposite.parameters 
Parameters in the form of a dict. 
TilingComposite.children 
The single wrapped structured sampler. 
TilingComposite.child 
The child sampler. 
TilingComposite.nodelist 
List of active qubits for the structured solver. 
TilingComposite.edgelist 
List of active couplers for the DWave solver. 
TilingComposite.adjacency 
Adjacency structure formatted as a dict, where keys are the nodes of the structured sampler and values are sets of all adjacent nodes for each key node. 
TilingComposite.structure 
Structure of the structured sampler formatted as a namedtuple , Structure(nodelist, edgelist, adjacency), where the 3tuple values are the nodelist , edgelist and adjacency attributes. 
Methods¶
TilingComposite.sample (bqm, **kwargs) 
Sample from the specified binary quadratic model. 
TilingComposite.sample_ising (h, J, **parameters) 
Sample from an Ising model using the implemented sample method. 
TilingComposite.sample_qubo (Q, **parameters) 
Sample from a QUBO using the implemented sample method. 
VirtualGraphComposite¶

class
VirtualGraphComposite
(sampler, embedding, chain_strength=None, flux_biases=None, flux_bias_num_reads=1000, flux_bias_max_age=3600)[source]¶ Composite to use the DWave virtual graph feature for minorembedding.
Calibrates qubits in chains to compensate for the effects of biases and enables easy creation, optimization, use, and reuse of an embedding for a given working graph.
Inherits from
dimod.ComposedSampler
anddimod.Structured
.Parameters:  sampler (
DWaveSampler
) – A dimoddimod.Sampler
. Typically aDWaveSampler
or derived composite sampler; other samplers may not work or make sense with this composite layer.  embedding (dict[hashable, iterable]) – Mapping from a source graph to the specified sampler’s graph (the target graph).
 chain_strength (float, optional, default=None) – Desired chain coupling strength. This is the magnitude of couplings between qubits in a chain. If None, uses the maximum available as returned by a SAPI query to the DWave solver.
 flux_biases (list/False/None, optional, default=None) – Perqubit flux bias offsets in the form of a list of lists, where each sublist is of length 2 and specifies a variable and the flux bias offset associated with that variable. Qubits in a chain with strong negative J values experience a Jinduced bias; this parameter compensates by recalibrating to remove that bias. If False, no flux bias is applied or calculated. If None, flux biases are pulled from the database or calculated empirically.
 flux_bias_num_reads (int, optional, default=1000) – Number of samples to collect per flux bias value to calculate calibration information.
 flux_bias_max_age (int, optional, default=3600) – Maximum age (in seconds) allowed for a previously calculated flux bias offset to be considered valid.
Attention
DWave’s virtual graphs feature can require many seconds of DWave system time to calibrate qubits to compensate for the effects of biases. If your account has limited DWave system access, consider using FixedEmbeddingComposite() instead.
Examples
This example uses
VirtualGraphComposite
to instantiate a composed sampler that submits a QUBO problem to a DWave solver. The problem represents a logical AND gate using penalty function \(P = xy  2(x+y)z +3z\), where variables x and y are the gate’s inputs and z the output. This simple threevariable problem is manually minorembedded to a single Chimera unit cell: variables x and y are represented by qubits 1 and 5, respectively, and z by a twoqubit chain consisting of qubits 0 and 4. The chain strength is set to the maximum allowed found from querying the solver’s extended J range. In this example, the ten returned samples all represent valid states of the AND gate.>>> from dwave.system import DWaveSampler, VirtualGraphComposite >>> embedding = {'x': {1}, 'y': {5}, 'z': {0, 4}} >>> DWaveSampler().properties['extended_j_range'] [2.0, 1.0] >>> sampler = VirtualGraphComposite(DWaveSampler(), embedding, chain_strength=2) # doctest: +SKIP >>> Q = {('x', 'y'): 1, ('x', 'z'): 2, ('y', 'z'): 2, ('z', 'z'): 3} >>> sampleset = sampler.sample_qubo(Q, num_reads=10) # doctest: +SKIP >>> print(sampleset) # doctest: +SKIP x y z energy num_oc. chain_. 0 1 0 0 0.0 2 0.0 1 0 1 0 0.0 3 0.0 2 1 1 1 0.0 3 0.0 3 0 0 0 0.0 2 0.0 ['BINARY', 4 rows, 10 samples, 3 variables]
See Ocean Glossary for explanations of technical terms in descriptions of Ocean tools.
 sampler (
Properties¶
VirtualGraphComposite.properties 

VirtualGraphComposite.parameters 

VirtualGraphComposite.children 

VirtualGraphComposite.child 
The child sampler. 
VirtualGraphComposite.nodelist 
Nodes available to the composed sampler. 
VirtualGraphComposite.edgelist 
Edges available to the composed sampler. 
VirtualGraphComposite.adjacency 
Adjacency structure for the composed sampler. 
VirtualGraphComposite.structure 
Structure of the structured sampler formatted as a namedtuple , Structure(nodelist, edgelist, adjacency), where the 3tuple values are the nodelist , edgelist and adjacency attributes. 
Methods¶
VirtualGraphComposite.sample (bqm[, …]) 
Sample from the given Ising model. 
VirtualGraphComposite.sample_ising (h, J, …) 
Sample from an Ising model using the implemented sample method. 
VirtualGraphComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 
Reverse Anneal¶
Composites that do batch operations for reverse annealing based on sets of initial states or anneal schedules.
ReverseBatchStatesComposite¶

class
ReverseBatchStatesComposite
(child_sampler)[source]¶ Composite that reverse anneals from multiple initial samples. Each submission is independent from one another.
Parameters: sampler ( dimod.Sampler
) – A dimod sampler.
Properties¶
ReverseBatchStatesComposite.child 
The child sampler. 
ReverseBatchStatesComposite.children 
List of child samplers that that are used by this composite. 
ReverseBatchStatesComposite.properties 
A dict containing any additional information about the sampler. 
ReverseBatchStatesComposite.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. 
Methods¶
ReverseBatchStatesComposite.sample (bqm, …) 
Sample the binary quadratic model using reverse annealing from multiple initial states. 
ReverseBatchStatesComposite.sample_ising (h, …) 
Sample from an Ising model using the implemented sample method. 
ReverseBatchStatesComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 
ReverseAdvanceComposite¶

class
ReverseAdvanceComposite
(child_sampler)[source]¶  Composite that reverse anneals an initial sample through a sequence of anneal
schedules.
If you do not specify an initial sample, a random sample is used for the first submission. By default, each subsequent submission selects the mostfound lowestenergy sample as its initial state. If you set reinitialize_state to False, which makes each submission behave like a random walk, the subsequent submission selects the last returned sample as its initial state.
Parameters: sampler ( dimod.Sampler
) – A dimod sampler.
Properties¶
ReverseAdvanceComposite.child 
The child sampler. 
ReverseAdvanceComposite.children 
List of child samplers that that are used by this composite. 
ReverseAdvanceComposite.properties 
A dict containing any additional information about the sampler. 
ReverseAdvanceComposite.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. 
Methods¶
ReverseAdvanceComposite.sample (bqm[, …]) 
Sample the binary quadratic model using reverse annealing along a given set of anneal schedules. 
ReverseAdvanceComposite.sample_ising (h, J, …) 
Sample from an Ising model using the implemented sample method. 
ReverseAdvanceComposite.sample_qubo (Q, …) 
Sample from a QUBO using the implemented sample method. 