C++ API

This page describes the dimod package’s C++ API.

Models

For the Python API and descriptions of the various models, see Models: BQM, CQM, QM, Others.

Binary Quadratic Model (BQM)

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

A binary quadratic model (BQM) is a quadratic polynomial over binary-valued variables.

Public Types

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

Type of the base class.

using bias_type = Bias

First template parameter (Bias).

using index_type = Index

Second template parameter (Index).

using size_type = typename base_type::size_type

Unsigned integer that can represent non-negative values.

Public Functions

BinaryQuadraticModel()

Empty constructor. The variable type 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, values on the diagonal are added to the offset. If the BQM is BINARY-valued, values on the diagonal are added as linear biases.

template<class ItRow, class ItCol, class ItBias>
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.

index_type add_variable()

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

void change_vartype(Vartype vartype)

Change the variable type of the BQM.

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.

Constrained Quadratic Model (CQM)

template<class Bias, class Index>
class ConstrainedQuadraticModel

A constrained quadratic model (CQM) can include an objective and constraints as polynomials with one or two variables per term.

Public Types

using bias_type = Bias

First template parameter (Bias).

using index_type = Index

Second template parameter (Index).

using size_type = std::size_t

Unsigned integer type that can represent non-negative values.

Public Functions

index_type add_constraint(Constraint<bias_type, index_type> constraint)

Add a constraint.

Parameters

constraint – As created by ConstrainedQuadraticModel::new_constraint()

Throws

Throws – std::logic_error If the constraint’s parent is not this model. If an exception is thrown, there are no changes to the model.

index_type add_constraints(index_type n)

Add n constraints.

index_type add_linear_constraint(std::initializer_list<index_type> variables, std::initializer_list<bias_type> biases, Sense sense, bias_type rhs)

Add a constraint with only linear coefficients.

index_type add_variable(Vartype vartype, bias_type lb, bias_type ub)

Add variable of type vartype with lower bound lb and upper bound ub.

index_type add_variable(Vartype vartype)

Add variable of type vartype.

index_type add_variables(Vartype vartype, index_type n)

Add n variables of type vartype.

index_type add_variables(Vartype vartype, index_type n, bias_type lb, bias_type ub)

Add n variables of type vartype with lower bound lb and upper bound ub.

void change_vartype(Vartype vartype, index_type v)

Change the variable type of variable v to vartype, updating the biases appropriately.

ConstraintsView<ConstrainedQuadraticModel<bias_type, index_type>> constraints()

Return a view over the constraints.

The view can be iterated over.

for (auto& constraint : cqm.constraints()) {}

const ConstraintsView<const ConstrainedQuadraticModel<bias_type, index_type>> constraints() const

Return a view over the constraints.

The view can be iterated over.

for (auto& constraint : cqm.constraints()) {}

template<class T>
void fix_variable(index_type v, T assignment)

Fix variable v in the model to value assignment.

template<class VarIter, class AssignmentIter>
ConstrainedQuadraticModel fix_variables(VarIter first, VarIter last, AssignmentIter assignment) const

Create a new model by fixing many variables.

template<class T>
ConstrainedQuadraticModel fix_variables(std::initializer_list<index_type> variables, std::initializer_list<T> assignments) const

Create a new model by fixing many variables.

bias_type lower_bound(index_type v) const

Return the lower bound on variable v.

Constraint<bias_type, index_type> new_constraint() const

Return a new constraint without adding it to the model.

size_type num_constraints() const

Return the number of constraints in the model.

size_type num_variables() const

Return the number of variables in the model.

void remove_constraint(index_type c)

Remove a constraint from the model.

void remove_variable(index_type v)

Remove variable v from the model.

void set_lower_bound(index_type v, bias_type lb)

Set a lower bound of lb on variable v.

template<class B, class I>
void set_objective(const abc::QuadraticModelBase<B, I> &objective)

Set an objective for the model.

template<class B, class I, class T>
void set_objective(const abc::QuadraticModelBase<B, I> &objective, const std::vector<T> &mapping)

Set an objective for the model using a mapping.

void set_upper_bound(index_type v, bias_type ub)

Set an upper bound of ub on variable v.

bias_type upper_bound(index_type v) const

Return the upper bound on variable v.

Vartype vartype(index_type v) const

Return the variable type of variable v.

Constraints

template<class Bias, class Index>
class Constraint : public dimod::Expression<Bias, Index>

A constrained quadratic model (CQM) can include hard or soft constraints as polynomials with one or two variables per term.

Public Types

using base_type = Expression<Bias, Index>

Type of the base class.

using bias_type = Bias

First template parameter (Bias).

using index_type = Index

Second template parameter (Index).

Public Functions

void clear()

Clear the constraint by changing it to a 0 == 0 constraint.

The weight and/or discrete markers are also cleared if present.

bool is_onehot() const

Return true for a one-hot constraint of discrete variables.

bool is_soft() const

Return true for a soft constraint with a finite weight that can be violated.

void mark_discrete(bool mark = true)

Mark the constraint as encoding a discrete variable.

bool marked_discrete() const

Return true if the constraint encodes a discrete variable.

Penalty penalty() const

Return the penalty set for a soft constraint.

bias_type rhs() const

Return a constraint’s right-hand side.

void scale(bias_type scalar)

Scale by multiplying by scalar.

Sense sense() const

Sense (greater or equal, less or equal, equal) of a constraint.

void set_penalty(Penalty penalty)

Set the penalty for a soft constraint.

void set_rhs(bias_type rhs)

Set a constraint’s right-hand side.

void set_sense(Sense sense)

Set the sense (greater or equal, less or equal, equal) of a constraint.

void set_weight(bias_type weight)

Set the weight for a soft constraint.

bias_type weight() const

Return a soft constraint’s weight.

Quadratic Model (QM)

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

A quadratic model (QM) is a polynomial with one or two variables per term.

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 integer that can represent non-negative values.

Public Functions

index_type add_variable(Vartype vartype)

Add variable of type vartype.

index_type add_variable(Vartype vartype, bias_type lb, bias_type ub)

Add n variables of type vartype with lower bound lb and upper bound ub.

index_type add_variables(Vartype vartype, index_type n)

Add n variables of type vartype.

index_type add_variables(Vartype vartype, index_type n, bias_type lb, bias_type ub)

Add n variables of type vartype with lower bound lb and upper bound ub.

void change_vartype(Vartype vartype, index_type v)

Change the vartype of v, updating the biases appropriately.

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.

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.

void resize(index_type n, Vartype vartype)

Resize the model to contain n variables.

Any added variables are of type vartype (value 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.

Any added variables are of type vartype (value must be Vartype::BINARY or Vartype::SPIN) and have lower bound lb and upper bound ub.

void set_lower_bound(index_type v, bias_type lb)

Set a lower bound of lb on variable v.

void set_upper_bound(index_type v, bias_type ub)

Set an upper bound of ub on variable v.

void set_vartype(index_type v, Vartype vartype)

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

Variable Type (Vartype)

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)

Default upper bound.

static inline Bias default_min(Vartype vartype)

Default lower bound.

static inline Bias max(Vartype vartype)

Maximum supported value.

static inline Bias min(Vartype vartype)

Minimum supported value.

vartype_limits

template<class Bias, Vartype vartype>
class vartype_limits

Compile-time limits by variable type.

dimod Abstract Base Class (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 integer 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(index_type u, index_type v, bias_type bias)

Add interaction between variables v and u.

void add_quadratic(std::initializer_list<index_type> row, std::initializer_list<index_type> col, std::initializer_list<bias_type> biases)

Add interactions between row row and column col.

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

Add quadratic bias for the given variables at the end of each other’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_neighborhood_iterator cbegin_neighborhood(index_type v) const

Return an iterator to the beginning of the neighborhood of v.

const_neighborhood_iterator cend_neighborhood(index_type v) const

Return an iterator to the end of the neighborhood of v.

const_quadratic_iterator cbegin_quadratic() const

Return an iterator to the beginning of the quadratic interactions.

const_quadratic_iterator cend_quadratic() const

Return an iterator to the end of the quadratic interactions.

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 a 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

Test whether 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

Return the number of other variables that 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 and v.

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

Note that this function does not return a reference 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 and v.

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

Raises an out_of_range error if either u or v are not variables; if they do not have an interaction, 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 by the value of 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 between variables u and v.

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 a variable does not have an adjacency.

dimod Utilities (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.