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, int>#

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.

bias_type lower_bound(index_type v) const#

Return the lower bound 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.

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.

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.

template<class UnaryPredicate>
void remove_constraints_if(UnaryPredicate p)#

Remove all constraints satisfying a certain criteria as defined by a unary predicate p which accepts a constraint reference and returns true if the constraint should be removed.

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, int>#

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.

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.

virtual void remove_variables(const std::vector<index_type> &variables)#

Remove variables.

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.

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.

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::Expression< 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.

virtual void remove_variables(const std::vector<index_type> &variables)#

Remove multiple variables from the model and reindex accordingly.

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.