Utilities

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

COOrdinate

dump(bqm, fp[, vartype_header]) Dump a binary quadratic model to a string in COOrdinate format.
dumps(bqm[, vartype_header]) Dump a binary quadratic model to a string in COOrdinate format.
load(fp[, cls, vartype]) Load a COOrdinate formatted binary quadratic model from a file.
loads(s[, cls, vartype]) Load a COOrdinate formatted binary quadratic model from a string.

FileView

FileView(bqm) A seekable, readable view into a binary quadratic model.

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
DimodEncoder(*[, skipkeys, ensure_ascii, …]) Subclass the JSONEncoder for dimod objects.
DimodDecoder(*args, **kwargs) Subclass the JSONDecoder for dimod objects.
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.

Test Case Loader

load_sampler_bqm_tests(sampler[, …]) Populate the decorated TestCase with sampler tests using small BQMs.

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.