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.

template<class Filter> size_type remove_interactions(Filter filter)#

Remove all interactions for which filter returns true.

Returns the number of interactions removed. filter must be symmetric. That is filter(u, v, bias) must equal filter(v, u, bias).

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.