Utilities

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).

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.

Graph-like

child_structure_dfs(sampler[, seen]) Return the structure of a composed sampler using a depth-first search on its children.

Serialization

COOrdinate

A simple text encoding of dimod BQMs.

The COOrdinate list is a sparse matrix representation which can be used to store binary quadratic models. This format is best used when readability is important.

Note that this format only works for BQMs that are labelled with positive integers.

Examples

>>> from dimod.serialization import coo

Serialize a QUBO.

>>> Q = {(0, 0): -1, (0, 1): 1, (1, 2): -4.5}
>>> bqm = dimod.BinaryQuadraticModel.from_qubo(Q)
>>> print(coo.dumps(bqm))
0 0 -1.000000
0 1 1.000000
1 2 -4.500000

We can also include the vartype as a header.

>>> Q = {(0, 0): -1, (0, 1): 1, (1, 2): -4.5}
>>> bqm = dimod.BinaryQuadraticModel.from_qubo(Q)
>>> print(coo.dumps(bqm, vartype_header=True))
# vartype=BINARY
0 0 -1.000000
0 1 1.000000
1 2 -4.500000

Loading from a COO string. Note that you must specify a vartype.

>>> coo_string = '''
... 0 0 -1
... 0 1 1
... 1 2 -4.5
... '''
>>> coo.loads(coo_string, vartype=dimod.BINARY)
BinaryQuadraticModel({0: -1.0, 1: 0.0, 2: 0.0}, {(0, 1): 1.0, (1, 2): -4.5}, 0.0, 'BINARY')

Or provide the vartype as a header.

>>> coo_string = '''
... # vartype=BINARY
... 0 0 -1
... 0 1 1
... 1 2 -4.5
... '''
>>> coo.loads(coo_string)
BinaryQuadraticModel({0: -1.0, 1: 0.0, 2: 0.0}, {(0, 1): 1.0, (1, 2): -4.5}, 0.0, 'BINARY')
dump(bqm, fp[, vartype_header]) Dump a binary quadratic model to a file 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.