C++ API

dimod

BinaryQuadraticModel

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

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

Public Types

using base_type = abc::QuadraticModelBase<Bias, Index>

The type of the base class.

using bias_type = Bias

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

BinaryQuadraticModel()

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

explicit BinaryQuadraticModel(Vartype vartype)

Create a BQM of the given vartype.

BinaryQuadraticModel(index_type n, Vartype vartype)

Create a BQM with n variables of the given vartype.

template<class T>
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.

index_type add_variable()

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

void change_vartype(Vartype vartype)

Change the vartype of the binary quadratic model.

virtual bias_type lower_bound(index_type v) const

Return the lower bound on variable v.

virtual bias_type upper_bound(index_type v) const

Return the upper bound on variable v.

virtual Vartype vartype(index_type v) const

Return the variable type of variable v.

QuadraticModel

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

Public Types

using base_type = abc::QuadraticModelBase<Bias, Index>

The type of the base class.

using bias_type = Bias

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

void change_vartype(Vartype vartype, index_type v)

Change the vartype of v, updating the biases appropriately.

virtual bias_type lower_bound(index_type v) const

Return the lower bound on variable v.

virtual size_type nbytes(bool capacity = false) const

Total bytes consumed by the biases, vartype info, bounds, and indices.

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

virtual void remove_variable(index_type v)

Remove variable v from the model.

Note that this causes a reindexing, where all variables above v have their index reduced by one.

void resize(index_type n, Vartype vartype)

Resize the model to contain n variables.

The vartype is used to any new variables added.

The vartype must be Vartype::BINARY or Vartype::SPIN.

void resize(index_type n, Vartype vartype, bias_type lb, bias_type ub)

Resize the model to contain n variables.

The vartype is used to any new variables added.

virtual bias_type upper_bound(index_type v) const

Return the upper bound on variable v.

virtual Vartype vartype(index_type v) const

Return the variable type of variable 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.

vartype_info

template<class Bias>
class vartype_info

Runtime limits by variable type.

Public Static Functions

static inline Bias default_max(Vartype vartype)
static inline Bias default_min(Vartype vartype)
static inline Bias max(Vartype vartype)
static inline Bias min(Vartype vartype)

dimod::abc

template<class Bias, class Index>
class QuadraticModelBase

Subclassed by dimod::BinaryQuadraticModel< Bias, Index >, dimod::Expression< 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.

Public Functions

void add_linear(index_type v, bias_type bias)

Add linear bias to variable v.

void add_offset(bias_type bias)

Add offset.

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.

const_quadratic_iterator cbegin_quadratic() const

todo

const_quadratic_iterator cend_quadratic() const

todo

void clear()

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

template<class Iter>
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>
void fix_variable(index_type v, T assignment)

Remove variable v from the model by fixing its value.

Note that this causes a reindexing, where all variables above v have their index reduced by one.

bool has_interaction(index_type u, index_type v) const

Check whether u and v have an interaction.

template<class B, class I>
bool is_equal(const QuadraticModelBase<B, I> &other) const

Test whether two quadratic models are equal.

bool is_linear() const

Return True if the model has no quadratic biases.

bias_type linear(index_type v) const

The linear bias of variable v.

virtual bias_type lower_bound(index_type v) const = 0

Return the lower bound on variable v.

virtual size_type nbytes(bool capacity = false) const

Total bytes consumed by the biases and indices.

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

size_type num_interactions() const

Return the number of interactions in the quadratic model.

size_type num_interactions(index_type v) const

The number of other variables v interacts with.

inline size_type num_variables() const

Return the number of variables in the quadratic model.

bias_type offset() const

Return the offset.

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.

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.

bool remove_interaction(index_type u, index_type v)

Remove the interaction between variables u and v.

virtual void remove_variable(index_type v)

Remove variable v from the model.

Note that this causes a reindexing, where all variables above v have their index reduced by one.

void scale(bias_type scalar)

Multiply all biases ‘scalar’.

void set_linear(index_type v, bias_type bias)

Set the linear bias of variable v.

void set_linear(index_type v, std::initializer_list<bias_type> biases)

Set the linear biases of of the variables beginning with v.

void set_offset(bias_type offset)

Set the offset.

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

Set the quadratic bias for the given variables.

virtual bias_type upper_bound(index_type v) const = 0

Return the upper bound on variable v.

virtual Vartype vartype(index_type v) const = 0

Return the variable type of variable v.

Protected Functions

index_type add_variable()

Increase the size of the model by one. Returns the index of the new variable.

index_type add_variables(index_type n)

Increase the size of the model by n. Returns the index of the first variable added.

void resize(index_type n)

Resize model to contain n variables.

inline virtual Vartype vartype_(index_type v) const

Protected version of vartype() that allows subclasses to distinguish between the vartype_ called by mixin functions and the public API one.

By default they are the same.

Protected Static Functions

static inline const std::vector<OneVarTerm<bias_type, index_type>> &empty_neighborhood()

Return an empty neighborhood - useful when we don’t have an adj.

dimod::utils

template<class T1, class T2>
void dimod::utils::zip_sort(std::vector<T1> &control, std::vector<T2> &response)

Sort two vectors, using control to provide the ordering.

Note that this only sorts by the control, the values of response are ignored.