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.
Public Functions
-
BinaryQuadraticModel()¶
Empty constructor. The variable type defaults to
Vartype::BINARY
.
-
BinaryQuadraticModel(index_type n, Vartype vartype)¶
Create a BQM with
n
variables of the givenvartype
.
-
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 lengthnum_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.
-
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
.
-
using base_type = abc::QuadraticModelBase<Bias, Index>¶
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 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 boundlb
and upper boundub
.
-
index_type add_variable(Vartype vartype)¶
Add variable of type
vartype
.
-
index_type add_variables(Vartype vartype, index_type n)¶
Add
n
variables of typevartype
.
-
index_type add_variables(Vartype vartype, index_type n, bias_type lb, bias_type ub)¶
Add
n
variables of typevartype
with lower boundlb
and upper boundub
.
-
void change_vartype(Vartype vartype, index_type v)¶
Change the variable type of variable
v
tovartype
, 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 valueassignment
.
-
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.
-
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 variablev
.
-
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 variablev
.
-
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
.
-
using size_type = std::size_t¶
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
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.
-
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_sense(Sense sense)¶
Set the sense (greater or equal, less or equal, equal) of a constraint.
-
void clear()¶
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.
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 typevartype
with lower boundlb
and upper boundub
.
-
index_type add_variables(Vartype vartype, index_type n)¶
Add
n
variables of typevartype
.
-
index_type add_variables(Vartype vartype, index_type n, bias_type lb, bias_type ub)¶
Add
n
variables of typevartype
with lower boundlb
and upper boundub
.
-
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 beVartype::BINARY
orVartype::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 beVartype::BINARY
orVartype::SPIN
) and have lower boundlb
and upper boundub
.
-
void set_lower_bound(index_type v, bias_type lb)¶
Set a lower bound of
lb
on variablev
.
-
void set_upper_bound(index_type v, bias_type ub)¶
Set an upper bound of
ub
on variablev
.
-
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
.
-
using base_type = abc::QuadraticModelBase<Bias, Index>¶
Variable Type (Vartype)¶
vartype_info¶
-
template<class Bias>
class vartype_info¶ Runtime 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 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_quadratic(index_type u, index_type v, bias_type bias)¶
Add interaction between variables
v
andu
.
-
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 columncol
.
-
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 withu
andv
.
Exceptions
When
u
is less than the largest neighbor inv
’s neighborhood,v
is less than the largest neighbor inu
’s neighborhood, or eitheru
orv
is greater thannum_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
andv
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(index_type v) const¶
Return the number of other variables that
v
interacts with.
-
bias_type quadratic(index_type u, index_type v) const¶
Return the quadratic bias associated with
u
andv
.If
u
andv
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
andv
.Note that this function does not return a reference because each quadratic bias is stored twice.
Raises an
out_of_range
error if eitheru
orv
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
andv
.
-
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 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_quadratic(index_type u, index_type v, bias_type bias)¶
Set the quadratic bias between variables
u
andv
.
-
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.
-
using size_type = std::size_t¶