C++ API¶

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

Models
Variable Type (Vartype)
dimod Abstract Base Class (dimod::abc)
dimod Utilities (dimod::utils)

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.