Primitives

Basic building-block classes and superclasses for hybrid workflows.

Classes

class State(*args, **kwargs)

Computation state passed along a branch between connected components.

State is a dict subclass and usually contains at least two keys: samples and problem.

Examples

>>> import dimod           # Create a binary quadratic model
>>> bqm = dimod.BinaryQuadraticModel({0: -1, 1: -1}, {(0, 1): 2}, 0.0, dimod.BINARY)
>>> hybrid.core.State.from_sample(hybrid.utils.min_sample(bqm), bqm)   
{'problem': BinaryQuadraticModel({0: -1, 1: -1}, {(0, 1): 2}, 0.0, Vartype.BINARY),
 'samples': SampleSet(rec.array([([0, 0], 0., 1)],
    dtype=[('sample', 'i1', (2,)), ('energy', '<f8'), ('num_occurrences', '<i4')]), [0, 1], {}, 'BINARY')}

class States(*args)

List of states.

class SampleSet(*args, **kwargs)

The dimod.SampleSet class extended with a few helper methods.

Note: this is basically a staging area for new dimod.SampleSet features before merging these upstream.

class Runnable(**runopts)

Components such as samplers and branches that can be run for an iteration.

Parameters:

**runopts (dict) – Keyword arguments passed down to each Runnable.run call.

Note

The base class Runnable does not enforce traits validation. To enable validation, derive your subclass from one of the state structure, I/O dimensionality, or I/O validation mixins in traits.

Examples

This example runs a tabu search on a binary quadratic model. An initial state is manually set to \(x=y=0, z=1; a=b=1, c=0\) and an updated state is created by running the sampler for one iteration.

>>> import dimod           # Create a binary quadratic model
>>> bqm = dimod.BinaryQuadraticModel({'x': 0.0, 'y': 0.0, 'z': 8.0, 'a': 2.0, 'b': 0.0, 'c': 6.0},
...                                  {('y', 'x'): 2.0, ('z', 'x'): -4.0, ('z', 'y'): -4.0,
...                                  ('b', 'a'): 2.0, ('c', 'a'): -4.0, ('c', 'b'): -4.0, ('a', 'z'): -4.0},
...                                  -1.0, 'BINARY')
>>> # Set up the sampler runnable
>>> sampler = TabuProblemSampler(tenure=2, timeout=5)
>>> # Run one iteration of the sampler
>>> new_state = sampler.next(State.from_sample({'x': 0, 'y': 0, 'z': 1, 'a': 1, 'b': 1, 'c': 0}, bqm))
>>> print(new_state.samples)      
      a  b  c  x  y  z  energy  num_occ.
   0  1  1  1  1  1  1    -1.0         1
   [ 1 rows, 6 variables ]

Properties

Runnable.name	Return the Runnable class name.
SampleSet.first	Sample with the lowest-energy.

Methods

Runnable.dispatch(future, **kwargs)	Dispatch state from resolving future to either next or error methods.
Runnable.error(exc)	Execute one blocking iteration of an instantiated Runnable with an exception as input.
Runnable.init(state, **runopts)	Run prior to the first next/run, with the first state received.
Runnable.halt()	Called by stop().
Runnable.next(state, **runopts)	Execute one blocking iteration of an instantiated Runnable with a valid state as input.
Runnable.run(state, **kwargs)	Execute the next step/iteration of an instantiated Runnable.
Runnable.stop()	Terminate an iteration of an instantiated Runnable.
SampleSet.empty()
SampleSet.hstack(*others)	Combine the first sample in this SampleSet with first samples in all other SampleSets.
SampleSet.vstack(*others)
State.copy()	Simple deep copy of itself.
State.updated(**kwargs)	Return a (deep) copy of the state, updated from kwargs.
State.result()	Implement concurrent.Future-compatible result resolution interface.
State.from_problem(bqm[, samples])	Convenience method for constructing a state from (possibly only) a BQM.
State.from_subproblem(bqm[, subsamples])	Convenience method for constructing a state from (possibly only) a subproblem BQM.
State.from_sample(sample, bqm, **kwargs)	Convenience method for constructing a state from a raw (dict) sample.
State.from_samples(samples, bqm, **kwargs)	Convenience method for constructing a state from raw (dict) samples.
State.from_subsample(subsample, bqm, **kwargs)	Similar to from_sample(), but initializes subproblem and subsamples.
State.from_subsamples(subsamples, bqm, **kwargs)	Similar to from_samples(), but initializes subproblem and subsamples.
States.first
States.updated(**kwargs)	Return a (deep) copy of the states, updated from kwargs.