# Utilities¶

## Converting Between Models¶

Converting between BQM models:

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

Converting CQMs to BQMs:

 `cqm_to_bqm`(cqm[, lagrange_multiplier]) Construct a binary quadratic model from a constrained quadratic model.

Converting higher-order models to BQMs:

 `make_quadratic`(poly, strength[, vartype, bqm]) Create a binary quadratic model from a higher order polynomial. `make_quadratic_cqm`(poly[, vartype, cqm]) Create a constrained quadratic model from a higher order polynomial. Reduce a binary polynomial to linear and quadratic terms, plus constraints.

## Decorators¶

 Decorator to convert a BQM to index-labels and relabel the sample set output. Decorator to raise an error if the given BQM does not match the sampler's structure. 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. Decorator to create non-blocking sample methods. `vartype_argument`(*arg_names) Ensures the wrapped function receives valid vartype argument(s).

## Energy Calculations¶

BQM energy:

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

Higher-order model energy:

 `poly_energies`(samples_like, poly) Calculates energy of samples from a higher order polynomial. `poly_energy`(sample_like, poly) Calculate energy of a sample from a higher order polynomial.

## Fixing Variables (Moved)¶

 `fix_variables`(*args, **kwargs) Removed

## Graph Functions¶

Converting between BQMs and NetworkX graph:

 `to_networkx_graph`(bqm[, ...]) Convert a binary quadratic model to NetworkX graph format. `from_networkx_graph`(G[, vartype, ...]) Create a binary quadratic model from a NetworkX graph.

Traversing BQMs as a graph:

 Yields sets of connected variables. `bfs_variables`(bqm, source) Yields variables in breadth-first search order.

## 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}
>>> 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}
# 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
... '''
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
... '''
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)
>>> 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.

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

## Structure of Composed Sampler¶

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

## Summing Models¶

Fast summation on models:

 `quicksum`(iterable) Sum iterable's items.

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

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