Composites#

The dwave-preprocessing package includes several composites:

Connected Components Composite#

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 selected and merged 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.

>>> from dimod import ExactSolver
>>> from dwave.preprocessing.composites import ConnectedComponentsComposite
>>> h = {}
>>> J1 = {(1, 2): -1.0, (2, 3): 2.0, (3, 4): 3.0}
>>> J2 = {(12, 13): 6}
>>> sampler = ExactSolver()
>>> sampler_ccc = 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#

`child`	The child sampler.
`children`	List of child samplers that that are used by this composite.
`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.
`properties`	Properties as a dict containing any additional information about the sampler.

Methods#

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

Clip Composite#

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.

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

Properties#

`child`	The child sampler.
`children`	List of child samplers that that are used by this composite.
`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.
`properties`	Properties as a dict containing any additional information about the sampler.

Methods#

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

Fix Variables Composite#

Class#

class FixVariablesComposite(child_sampler, *, algorithm='explicit')[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:

child_sampler (dimod.Sampler) – A dimod sampler
algorithm (str, optional, default='explicit') –
Determines how fixed_variables are found.

’explicit’: fixed_variables should be passed in a call to .sample(). If not, no fixing occurs and the problem is directly passed to the child sampler.

’roof_duality’: Roof duality algorithm is used to find fixed_variables. strict may be passed in a call to .sample() to determine what variables the algorithm will fix. For details, see roof_duality().

Examples

This example uses the FixVariablesComposite 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 accordingly.

>>> from dimod import ExactSolver
>>> from dwave.preprocessing.composites import FixVariablesComposite
>>> h = {1: -1.3, 4: -0.5}
>>> J = {(1, 4): -0.6}
>>> sampler = FixVariablesComposite(ExactSolver())
>>> sampleset = sampler.sample_ising(h, J, fixed_variables={1: -1})

This next example involves the same problem but calculates fixed_variables using the ‘roof_duality’ algorithm.

>>> sampler = FixVariablesComposite(ExactSolver(), algorithm='roof_duality')
>>> sampleset = sampler.sample_ising(h, J, strict=False)

Properties#

`child`	The child sampler.
`children`	List of child samplers that that are used by this composite.
`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.
`properties`	Properties as a dict containing any additional information about the sampler.

Methods#

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

Scale Composite#

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.

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

Properties#

`child`	The child sampler.
`children`	List of child samplers that that are used by this composite.
`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.
`properties`	Properties as a dict containing any additional information about the sampler.

Methods#

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

Spin Reversal Transform Composite#

Class#

class SpinReversalTransformComposite(child: Sampler, *, seed=None)[source]#

Composite for applying spin reversal transform preprocessing.

A spin-reversal transform can improve sample statistics when the sampler is a physical object with asymmetries such as a QPU. The technique works as follows: given an \(n\)-variable Ising problem, the composite selects a random \(g\in\{\pm1\}^n\) and transforms the problem via \(h_i\mapsto h_ig_i\) and \(J_{ij}\mapsto J_{ij}g_ig_j\). Solutions \(s\) of the original problem and \(s^\prime\) of the transformed problem are related by \(s^\prime_i=s_ig_i\) and have identical energies. [1]

Note

If you are configuring an anneal schedule, be mindful that this composite does not recognize the initial_state parameter used by dimod’s DWaveSampler for reverse annealing (composites do not generally process all keywords of child samplers) and does not flip any of the configured initial states.

Parameters:

sampler – A dimod sampler object.
seed – As passed to numpy.random.default_rng().

Examples

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

>>> from dimod import ExactSolver
>>> from dwave.preprocessing.composites import SpinReversalTransformComposite
>>> base_sampler = ExactSolver()
>>> composed_sampler = 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

Properties#

`child`	The child sampler.
`children`	List of child samplers that that are used by this composite.
`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.
`properties`	Properties as a dict containing any additional information about the sampler.

Methods#

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