Utilities

Contents

• Utilities
  • Energy Calculations
  • Decorators
  • Graph-like
  • Serialization
    • JSON
  • Testing
    • API Asserts
    • Correctness Asserts
  • Vartype Conversion

Energy Calculations

ising_energy(sample, h, J[, offset])	Calculate the energy for the specified sample of an Ising model.
qubo_energy(sample, Q[, offset])	Calculate the energy for the specified sample of a QUBO model.

Decorators

Decorators can be imported from the dimod.decorators namespace. For example:

>>> from dimod.decorators import vartype_argument

bqm_index_labels(f)	Decorator to convert a BQM to index-labels and relabel the sample set output.
bqm_index_labelled_input(…)	Returns a decorator that ensures BQM variable labeling and specified sample_like inputs are index labeled and consistent.
bqm_structured(f)	Decorator to raise an error if the given BQM does not match the sampler’s structure.
graph_argument(*arg_names, **options)	Decorator to coerce given graph arguments into a consistent form.
vartype_argument(*arg_names)	Ensures the wrapped function receives valid vartype argument(s).

Graph-like

child_structure_dfs(sampler[, seen])

Return the structure of a composed sampler using a depth-first search on its children.

Serialization

JSON

JSON-encoding of dimod objects.

Examples

>>> import json
>>> from dimod.serialization.json import DimodEncoder, DimodDecoder
...
>>> bqm = dimod.BinaryQuadraticModel.from_ising({}, {('a', 'b'): -1})
>>> s = json.dumps(bqm, cls=DimodEncoder)
>>> new = json.loads(s, cls=DimodDecoder)
>>> bqm == new
True

>>> import json
>>> from dimod.serialization.json import DimodEncoder, DimodDecoder
...
>>> sampleset = dimod.SampleSet.from_samples({'a': -1, 'b': 1}, dimod.SPIN, energy=5)
>>> s = json.dumps(sampleset, cls=DimodEncoder)
>>> new = json.loads(s, cls=DimodDecoder)
>>> sampleset == new
True

>>> import json
>>> from dimod.serialization.json import DimodEncoder, DimodDecoder
...
>>> # now inside a list
>>> s = json.dumps([sampleset, bqm], cls=DimodEncoder)
>>> new = json.loads(s, cls=DimodDecoder)
>>> new == [sampleset, bqm]
True

class DimodEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None)

Subclass the JSONEncoder for dimod objects.

class DimodDecoder(*args, **kwargs)

Subclass the JSONDecoder for dimod objects.

Uses dimod_object_hook().

Functions

dimod_object_hook(obj)

JSON-decoding for dimod objects.

Testing

The testing subpackage contains functions for verifying and testing dimod objects. Testing objects/functions can be imported from the dimod.testing namespace. For example:

>>> from dimod.testing import assert_sampler_api

API Asserts

assert_composite_api(composed_sampler)	Assert that an instantiated composed sampler exposes correct composite properties and methods.
assert_sampler_api(sampler)	Assert that an instantiated sampler exposes correct properties and methods.
assert_structured_api(sampler)	Assert that an instantiated structured sampler exposes correct composite properties and methods.

Correctness Asserts

assert_bqm_almost_equal(actual, desired[, …])	Test if two binary quadratic models have almost equal biases.
assert_response_energies(response, bqm[, …])	Assert that each sample in the given response has the correct energy.
assert_sampleset_energies(sampleset, bqm[, …])	Assert that each sample in the given sample set has the correct energy.

Vartype Conversion

ising_to_qubo(h, J[, offset])	Convert an Ising problem to a QUBO problem.
qubo_to_ising(Q[, offset])	Convert a QUBO problem to an Ising problem.