Higher-Order Composites

The dimod package includes several example higher-order composed samplers.

HigherOrderComposite

Composites that convert binary quadratic model samplers into polynomial samplers or that work with binary polynomials.

Higher-order composites implement three sampling methods (similar to Sampler):

class HigherOrderComposite(child_sampler)[source]

Convert a binary quadratic model sampler to a binary polynomial sampler.

Energies of the returned samples do not include the penalties.

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

Example

This example uses HigherOrderComposite to instantiate a composed sampler that submits a simple Ising problem to a sampler. The composed sampler creates a bqm from a higher order problem.

>>> sampler = dimod.HigherOrderComposite(dimod.ExactSolver())
>>> h = {0: -0.5, 1: -0.3, 2: -0.8}
>>> J = {(0, 1, 2): -1.7}
>>> sampleset = sampler.sample_hising(h, J, discard_unsatisfied=True)
>>> sampleset.first # doctest: +SKIP
Sample(sample={0: 1, 1: 1, 2: 1},
       energy=-3.3,
       num_occurrences=1,
       penalty_satisfaction=True)

Methods

HigherOrderComposite.sample_poly(poly[, …]) Sample from the given binary polynomial.
HigherOrderComposite.sample_hising(h, J, …) Sample from a higher-order Ising model.
HigherOrderComposite.sample_hubo(H, **kwargs) Sample from a higher-order unconstrained binary optimization problem.

PolyFixedVariableComposite

Composites that convert binary quadratic model samplers into polynomial samplers or that work with binary polynomials.

Higher-order composites implement three sampling methods (similar to Sampler):

class PolyFixedVariableComposite(child_sampler)[source]

Composite to fix variables of a problem to provided.

Fixes variables of a binary polynomial and modifies linear and k-local terms accordingly. Returned samples include the fixed variable

Parameters:sampler (dimod.PolySampler) – A dimod polynomial sampler.

Examples

This example uses PolyFixedVariableComposite to instantiate a composed sampler that submits a simple high order Ising problem to a sampler. The composed sampler fixes a variable and modifies linear and k-local terms biases according.

>>> h = {1: -1.3, 2: 1.2, 3: -3.4, 4: -0.5}
>>> J = {(1, 4): -0.6, (1, 2, 3): 0.2, (1, 2, 3, 4): -0.1}
>>> poly = dimod.BinaryPolynomial.from_hising(h, J, offset=0)
>>> sampler = dimod.PolyFixedVariableComposite(dimod.ExactPolySolver())
>>> sampleset = sampler.sample_poly(poly, fixed_variables={3: -1, 4: 1})

Methods

PolyFixedVariableComposite.sample_poly(poly) Sample from the provided binary quadratic model.
PolyFixedVariableComposite.sample_hising(h, …) Sample from a higher-order Ising model.
PolyFixedVariableComposite.sample_hubo(H, …) Sample from a higher-order unconstrained binary optimization problem.

PolyScaleComposite

class PolyScaleComposite(child)[source]

Composite to scale biases of a binary polynomial.

Parameters:child (PolySampler) – A binary polynomial sampler.

Examples

>>> linear = {'a': -4.0, 'b': -4.0}
>>> quadratic = {('a', 'b'): 3.2, ('a', 'b', 'c'): 1}
>>> sampler = dimod.PolyScaleComposite(dimod.HigherOrderComposite(dimod.ExactSolver()))
>>> response = sampler.sample_hising(linear, quadratic, scalar=0.5,
...                ignored_terms=[('a','b')])

Methods

PolyScaleComposite.sample_poly(poly[, …]) Scale and sample from the given binary polynomial.
PolyScaleComposite.sample_hising(h, J, **kwargs) Sample from a higher-order Ising model.
PolyScaleComposite.sample_hubo(H, **kwargs) Sample from a higher-order unconstrained binary optimization problem.

PolyTruncateComposite

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

Composite to truncate the returned samples

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.PolySampler) – A dimod binary polynomial 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.

Methods

PolyTruncateComposite.sample_poly(poly, **kwargs) Sample from the binary polynomial and truncate output.
PolyTruncateComposite.sample_hising(h, J, …) Sample from a higher-order Ising model.
PolyTruncateComposite.sample_hubo(H, **kwargs) Sample from a higher-order unconstrained binary optimization problem.