dimod.binary.BinaryQuadraticModel.to_file#

BinaryQuadraticModel.to_file(*, ignore_labels: bool = False, spool_size: int = 1000000000, version: int | Tuple[int, int] = 2) → SpooledTemporaryFile[source]#

Serialize the binary quadratic model to a file-like object.

Note that BQMs with the object data type are serialized as float64.

Parameters:

  • ignore_labels – Treat the BQM as unlabeled. This is useful for large BQMs to save on space.

  • spool_size – Defines the max_size passed to the constructor of tempfile.SpooledTemporaryFile. Determines whether the returned file-like’s contents is kept on disk or in memory.

  • version – The serialization version to use. Either as an integer defining the major version, or as a tuple, (major, minor).

Format Specification (Version 1.0):

This format is inspired by the NPY format

The first 8 bytes are a magic string: exactly “DIMODBQM”.

The next 1 byte is an unsigned byte: the major version of the file format.

The next 1 byte is an unsigned byte: the minor version of the file format.

The next 4 bytes form a little-endian unsigned int, the length of the header data HEADER_LEN.

The next HEADER_LEN bytes form the header data. This is a json-serialized dictionary. The dictionary is exactly:

dict(shape=bqm.shape,
     dtype=bqm.dtype.name,
     itype=bqm.data.index_dtype.name,
     ntype=bqm.data.index_dtype.name,
     vartype=bqm.vartype.name,
     type=type(bqm).__name__,
     variables=list(bqm.variables),
     )

It is terminated by a newline character and padded with spaces to make the entire length of the entire header divisible by 64.

The binary quadratic model data comes after the header. The number of bytes can be determined by the data types and the number of variables and number of interactions (described in the shape).

The first dtype.itemsize bytes are the offset. The next num_variables * (ntype.itemsize + dtype.itemsize) bytes are the linear data. The linear data includes the neighborhood starts and the biases. The final 2 * num_interactions * (itype.itemsize + dtype.itemsize) bytes are the quadratic data. Stored as (outvar, bias) pairs.

Format Specification (Version 2.0):

In order to make the header a more reasonable length, variable labels have been moved to the body. The variables field of the header dictionary now has a boolean value, making the dictionary:

dict(shape=bqm.shape,
     dtype=bqm.dtype.name,
     itype=bqm.data.index_dtype.name,
     ntype=bqm.data.index_dtype.name,
     vartype=bqm.vartype.name,
     type=type(bqm).__name__,
     variables=any(v != i for i,v in enumerate(bqm.variables)),
     )

If the BQM is index-labeled, then no additional data is added. Otherwise, a new section is appended after the bias data.

The first 4 bytes are exactly “VARS”.

The next 4 bytes form a little-endian unsigned int, the length of the variables array VARIABLES_LENGTH.

The next VARIABLES_LENGTH bytes are a json-serialized array. As constructed by json.dumps(list(bqm.variables)).