Utilities

Decorators

bqm_index_labels(f)

Decorator to convert a BQM to index-labels and relabel the sample set output.

bqm_structured(f)

Decorator to raise an error if the given BQM does not match the sampler's structure.

forwarding_method(func)

Improve the performance of a forwarding method by avoiding an attribute lookup.

graph_argument(*arg_names, **options)

Decorator to coerce given graph arguments into a consistent form.

nonblocking_sample_method(f)

Decorator to create non-blocking sample methods.

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 binary quadratic models (BQMs).

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

Note

This format works only for BQMs 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

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

Load from a COO string. You must specify a Vartype if absent from the input string.

>>> 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}, {(1, 0): 1.0, (2, 1): -4.5}, 0.0, 'BINARY')

You can provide the Vartype as a header in the string.

>>> 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}, {(1, 0): 1.0, (2, 1): -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 binary quadratic model from a COOrdinate-formatted file.

loads(s[, cls, vartype])

Load a binary quadratic model from a COOrdinate-formatted string.

FileView

FileView(bqm[, version, ignore_labels])

Deprecated.

load(fp[, cls])

Load a model from a file.

JSON

JSON-encoding of dimod objects.

Examples

>>> 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
DimodEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Subclass of json.JSONEnecoder for dimod objects.

DimodDecoder(*args, **kwargs)[source]

Subclass of json.JSONDecoder for dimod objects.

Uses the dimod_object_hook() function.

dimod_object_hook(obj)[source]

JSON-decoding for dimod objects.

See also

json.JSONDecoder for using custom decoders.

LP

lp.dump(cqm, file_like)

Serialize a constrained quadratic model as an LP file.

lp.dumps(cqm)

Serialize a constrained quadratic model as an LP file.

lp.load(file_like)

Construct a constrained quadratic model from a LP file.

lp.loads(obj)

Construct a constrained quadratic model from a string formatted as a LP file.

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.