C++ API

BinaryQuadraticModel

template<class Bias, class Index = int>
class BinaryQuadraticModel : public dimod::QuadraticModelBase<Bias, Index>

A Binary Quadratic Model is a quadratic polynomial over binary variables.

Internally, BQMs are stored in a vector-of-vectors adjacency format.

Public Types

using base_type = QuadraticModelBase<Bias, Index>

The type of the base class.

using bias_type = typename base_type::bias_type

The first template parameter (Bias).

using index_type = Index

The second template parameter (Index).

using size_type = typename base_type::size_type

Unsigned integral that can represent non-negative values.

Public Functions

inline BinaryQuadraticModel()

Empty constructor. The vartype defaults to Vartype::BINARY.

inline explicit BinaryQuadraticModel(Vartype vartype)

Create a BQM of the given vartype.

inline BinaryQuadraticModel(index_type n, Vartype vartype)

Create a BQM with n variables of the given vartype.

template<class T>
inline BinaryQuadraticModel(const T dense[], index_type num_variables, Vartype vartype)

Create a BQM from a dense matrix.

dense must be an array of length num_variables^2.

Values on the diagonal are treated differently depending on the variable type. If the BQM is SPIN-valued, then the values on the diagonal are added to the offset. If the BQM is BINARY-valued, then the values on the diagonal are added as linear biases.

template<class B, class I>
inline void add_bqm(const BinaryQuadraticModel<B, I> &bqm)

Add the variables, interactions and biases from another BQM.

The size of the updated BQM will be adjusted appropriately.

If the other BQM does not have the same vartype, the biases are adjusted accordingly.

template<class B, class I, class T>
inline void add_bqm(const BinaryQuadraticModel<B, I> &bqm, const std::vector<T> &mapping)

Add the variables, interactions and biases from another BQM.

The size of the updated BQM will be adjusted appropriately.

If the other BQM does not have the same vartype, the biases are adjusted accordingly.

mapping must be a vector at least as long as the given BQM. It should map the variables of bqm to new labels.

inline void add_quadratic(index_type u, index_type v, bias_type bias)

Add quadratic bias for the given variables.

template<class ItRow, class ItCol, class ItBias>
inline void add_quadratic(ItRow row_iterator, ItCol col_iterator, ItBias bias_iterator, index_type length)

Construct a BQM from COO-formated iterators.

A sparse BQM encoded in COOrdinate format is specified by three arrays of (row, column, value).

row_iterator must be a random access iterator pointing to the beginning of the row data. col_iterator must be a random access iterator pointing to the beginning of the column data. bias_iterator must be a random access iterator pointing to the beginning of the bias data. length must be the number of (row, column, bias) entries.

inline index_type add_variable()

Add one (disconnected) variable to the BQM and return its index.

inline void change_vartype(Vartype vartype)

Change the vartype of the binary quadratic model.

inline size_type num_interactions() const

Return the number of interactions in the quadratic model.

O(num_variables) complexity.

inline size_type num_interactions(index_type v) const

The number of other variables v interacts with.

inline void set_quadratic(index_type u, index_type v, bias_type bias)

Set the quadratic bias for the given variables.

inline void swap(BinaryQuadraticModel<bias_type, index_type> &other)

Exchange the contents of the binary quadratic model with the contents of other.

inline const Vartype &vartype() const

Return the vartype of the binary quadratic model.

inline const Vartype &vartype(index_type v) const

Return the vartype of v.

Vartype

enum dimod::Vartype

Encode the domain of a variable.

Values:

enumerator BINARY

Variables that are either 0 or 1.

enumerator SPIN

Variables that are either -1 or 1.

enumerator INTEGER

Variables that are integer valued.

enumerator REAL

Variables that are real valued.

Base Classes

Neighborhood

template<class Bias, class Index>
class Neighborhood

Used internally by QuadraticModelBase to sparsely encode the neighborhood of a variable.

Internally, Neighborhoods keep two vectors, one of neighbors and the other of biases. Neighborhoods are designed to make access more like a standard library map.

Public Types

using bias_type = Bias

The first template parameter (Bias).

using index_type = Index

The second template parameter (Index).

using size_type = std::size_t

Unsigned integral type that can represent non-negative values.

using value_type = typename std::pair<index_type, bias_type>

Exactly pair<index_type, bias_type>.

using iterator = typename std::vector<value_type>::iterator

A random access iterator to pair<index_type, bias_type>.

using const_iterator = typename std::vector<value_type>::const_iterator

A random access iterator to const pair<index_type, bias_type>.

Public Functions

inline bias_type at(index_type v) const

Return a reference to the bias associated with v.

This function automatically checks whether v is a variable in the neighborhood and throws a std::out_of_range exception if it is not.

inline iterator begin()

Returns an iterator to the beginning.

inline iterator end()

Returns an iterator to the end.

inline const_iterator cbegin() const

Returns a const_iterator to the beginning.

inline const_iterator cend() const

Returns a const_iterator to the end.

inline void emplace_back(index_type v, bias_type bias)

Insert a neighbor, bias pair at the end of the neighborhood.

Note that this does not keep the neighborhood self-consistent and should only be used when you know that the neighbor is greater than the current last element.

inline size_type erase(index_type v)

Erase an element from the neighborhood.

Returns the number of element removed, either 0 or 1.

inline void erase(iterator first, iterator last)

Erase elements from the neighborhood.

inline iterator lower_bound(index_type v)

Return an iterator to the first element that does not come before v.

inline const_iterator lower_bound(index_type v) const

Return an iterator to the first element that does not come before v.

inline size_type nbytes(bool capacity = false) const noexcept

Total bytes consumed by the biases and indices.

If capacity is true, use the capacity of the underlying vectors rather than the size.

inline bias_type get(index_type v, bias_type value = 0) const

Return the bias at neighbor v or the default value.

Return the bias of v if v is in the neighborhood, otherwise return the value provided without inserting v.

inline void reserve(index_type n)

Request that the neighborhood capacity be at least enough to contain n elements.

inline size_type size() const

Return the size of the neighborhood.

inline void sort_and_sum()

Sort the neighborhood and sum the biases of duplicate variables.

inline bias_type &operator[](index_type v)

Access the bias of v.

If v is in the neighborhood, the function returns a reference to its bias. If v is not in the neighborhood, it is inserted and a reference is returned to its bias.

QuadraticModelBase

template<class Bias, class Index = int>
class QuadraticModelBase

Subclassed by dimod::BinaryQuadraticModel< Bias, Index >, dimod::QuadraticModel< Bias, Index >

Public Types

using bias_type = Bias

The first template parameter (Bias)

using index_type = Index

The second template parameter (Index).

using size_type = std::size_t

Unsigned integral type that can represent non-negative values.

using const_neighborhood_iterator = typename Neighborhood<bias_type, index_type>::const_iterator

A random access iterator to pair<const index_type&, const bias_type&>

using const_quadratic_iterator = ConstQuadraticIterator<Bias, Index>

A forward iterator pointing to the quadratic biases.

Public Functions

inline void add_quadratic(index_type u, index_type v, bias_type bias)

Add quadratic bias for the given variables.

inline void add_quadratic_back(index_type u, index_type v, bias_type bias)

Add quadratic bias for the given variables at the end of eachother’s neighborhoods.

Parameters

• u - a variable.

• v - a variable.

• bias - the quadratic bias associated with u and v.

Exceptions

When u is less than the largest neighbor in v’s neighborhood, v is less than the largest neighbor in u’s neighborhood, or either u or v is greater than num_variables() then the behavior of this method is undefined.

inline void clear()

Remove the offset and all variables and interactions from the model.

inline bool is_linear() const

Return True if the model has no quadratic biases.

template<class Iter>
inline bias_type energy(Iter sample_start) const

Return the energy of the given sample.

The sample_start must be random access iterator pointing to the beginning of the sample.

The behavior of this function is undefined when the sample is not num_variables() long.

template<class T>
inline bias_type energy(const std::vector<T> &sample) const

Return the energy of the given sample.

The sample must be a vector containing the sample.

The behavior of this function is undefined when the sample is not num_variables() long.

inline bias_type &linear(index_type v)

Return a reference to the linear bias associated with v.

inline const bias_type &linear(index_type v) const

Return a reference to the linear bias associated with v.

inline std::pair<const_neighborhood_iterator, const_neighborhood_iterator> neighborhood(index_type u) const

Return a pair of iterators - the start and end of the neighborhood.

inline std::pair<const_neighborhood_iterator, const_neighborhood_iterator> neighborhood(index_type u, index_type start) const

The neighborhood of variable v.

Parameters

• A – variable v.

• The – neighborhood will start with the first out variable that does not compare less than start.

Returns

A pair of iterators pointing to the start and end of the neighborhood.

inline bias_type quadratic(index_type u, index_type v) const

Return the quadratic bias associated with u, v.

If u and v do not have a quadratic bias, returns 0.

Note that this function does not return a reference, this is because each quadratic bias is stored twice.

inline bias_type quadratic_at(index_type u, index_type v) const

Return the quadratic bias associated with u, v.

Note that this function does not return a reference, this is because each quadratic bias is stored twice.

Raises an out_of_range error if either u or v are not variables or if they do not have an interaction then the function throws an exception.

inline size_type nbytes(bool capacity = false) const noexcept

Total bytes consumed by the biases and indices.

If capacity is true, use the capacity of the underlying vectors rather than the size.

inline size_type num_variables() const

Return the number of variables in the quadratic model.

inline size_type num_interactions() const

Return the number of interactions in the quadratic model.

O(num_variables*log(num_variables)) complexity.

inline size_type num_interactions(index_type v) const

The number of other variables v interacts with.

inline bias_type &offset()

Return a reference to the offset.

inline const bias_type &offset() const

Return a reference to the offset.

inline bool remove_interaction(index_type u, index_type v)

Remove the interaction if it exists.

inline void resize(index_type n)

Resize model to contain n variables.

inline void scale(double scale_factor)

Scale offset, linear biases, and interactions by a factor.

inline void swap(QuadraticModelBase<bias_type, index_type> &other)

Exchange the contents of the quadratic model with the contents of other.

inline void swap_variables(index_type u, index_type v)

Swap the linear and quadratic biases between two variables.