C++ API¶
BinaryQuadraticModel¶
-
template<class Bias, class Index = int>
class dimod::BinaryQuadraticModel : public dimod::QuadraticModelBase<Bias, Index>¶ A Binary Quadratic Model is a quadratic polynomial over binary variables.
Internally, BQMs are stored in a vector-of-vectors adjacency format.
Public Types
-
using base_type = QuadraticModelBase<Bias, Index>¶
The type of the base class.
Public Functions
-
inline BinaryQuadraticModel()¶
Empty constructor. The vartype defaults to
Vartype::BINARY
.
-
inline BinaryQuadraticModel(index_type n, Vartype vartype)¶
Create a BQM with
n
variables of the givenvartype
.
-
template<class T>
inline 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, then the values on the diagonal are added to the offset. If the BQM is BINARY-valued, then the values on the diagonal are added as linear biases.
-
template<class B, class I>
inline void add_bqm(const BinaryQuadraticModel<B, I> &bqm)¶ Add the variables, interactions and biases from another BQM.
The size of the updated BQM will be adjusted appropriately.
If the other BQM does not have the same vartype, the biases are adjusted accordingly.
-
template<class B, class I, class T>
inline void add_bqm(const BinaryQuadraticModel<B, I> &bqm, const std::vector<T> &mapping)¶ Add the variables, interactions and biases from another BQM.
The size of the updated BQM will be adjusted appropriately.
If the other BQM does not have the same vartype, the biases are adjusted accordingly.
mapping
must be a vector at least as long as the given BQM. It should map the variables ofbqm
to new labels.
-
inline void add_quadratic(index_type u, index_type v, bias_type bias)¶
Add quadratic bias for the given variables.
-
template<class ItRow, class ItCol, class ItBias>
inline 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.
-
inline index_type add_variable()¶
Add one (disconnected) variable to the BQM and return its index.
-
inline size_type num_interactions() const¶
Return the number of interactions in the quadratic model.
O(num_variables)
complexity.
-
inline size_type num_interactions(index_type v) const¶
The number of other variables
v
interacts with.
-
inline void set_quadratic(index_type u, index_type v, bias_type bias)¶
Set the quadratic bias for the given variables.
-
inline void swap(BinaryQuadraticModel<bias_type, index_type> &other)¶
Exchange the contents of the binary quadratic model with the contents of
other
.
-
inline const Vartype &vartype(index_type v) const¶
Return the vartype of
v
.
-
using base_type = QuadraticModelBase<Bias, Index>¶
Vartype¶
Base Classes¶
Neighborhood¶
-
template<class Bias, class Index>
class dimod::Neighborhood¶ Used internally by QuadraticModelBase to sparsely encode the neighborhood of a variable.
Internally, Neighborhoods keep two vectors, one of neighbors and the other of biases. Neighborhoods are designed to make access more like a standard library map.
Public Types
-
using size_type = std::size_t¶
Unsigned integral type that can represent non-negative values.
-
using value_type = typename std::pair<index_type, bias_type>¶
Exactly
pair<index_type, bias_type>
.
-
using iterator = typename std::vector<value_type>::iterator¶
A random access iterator to
pair<index_type, bias_type>
.
-
using const_iterator = typename std::vector<value_type>::const_iterator¶
A random access iterator to
const pair<index_type, bias_type>.
Public Functions
-
inline bias_type at(index_type v) const¶
Return a reference to the bias associated with
v
.This function automatically checks whether
v
is a variable in the neighborhood and throws astd::out_of_range
exception if it is not.
-
inline const_iterator cbegin() const¶
Returns a const_iterator to the beginning.
-
inline const_iterator cend() const¶
Returns a const_iterator to the end.
-
inline void emplace_back(index_type v, bias_type bias)¶
Insert a neighbor, bias pair at the end of the neighborhood.
Note that this does not keep the neighborhood self-consistent and should only be used when you know that the neighbor is greater than the current last element.
-
inline size_type erase(index_type v)¶
Erase an element from the neighborhood.
Returns the number of element removed, either 0 or 1.
-
inline iterator lower_bound(index_type v)¶
Return an iterator to the first element that does not come before
v
.
-
inline const_iterator lower_bound(index_type v) const¶
Return an iterator to the first element that does not come before
v
.
-
inline size_type nbytes(bool capacity = false) const noexcept¶
Total bytes consumed by the biases and indices.
If
capacity
is true, use the capacity of the underlying vectors rather than the size.
-
inline bias_type get(index_type v, bias_type value = 0) const¶
Return the bias at neighbor
v
or the default value.Return the bias of
v
ifv
is in the neighborhood, otherwise return thevalue
provided without insertingv
.
-
inline void reserve(index_type n)¶
Request that the neighborhood capacity be at least enough to contain
n
elements.
-
inline void sort_and_sum()¶
Sort the neighborhood and sum the biases of duplicate variables.
-
inline bias_type &operator[](index_type v)¶
Access the bias of
v
.If
v
is in the neighborhood, the function returns a reference to its bias. Ifv
is not in the neighborhood, it is inserted and a reference is returned to its bias.
-
using size_type = std::size_t¶
QuadraticModelBase¶
-
template<class Bias, class Index = int>
class dimod::QuadraticModelBase¶ Subclassed by dimod::BinaryQuadraticModel< Bias, Index >, dimod::QuadraticModel< Bias, Index >
Public Types
-
using size_type = std::size_t¶
Unsigned integral type that can represent non-negative values.
-
using const_neighborhood_iterator = typename Neighborhood<bias_type, index_type>::const_iterator¶
A random access iterator to
pair<const index_type&, const bias_type&>
Public Functions
-
inline void add_quadratic(index_type u, index_type v, bias_type bias)¶
Add quadratic bias for the given variables.
-
inline bool is_linear() const¶
Return True if the model has no quadratic biases.
-
template<class Iter>
inline bias_type energy(Iter sample_start)¶ Return the energy of the given sample.
The
sample_start
must be 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>
inline bias_type energy(const std::vector<T> &sample)¶ Return the energy of the given sample.
The
sample
must be a vector containing the sample.The behavior of this function is undefined when the sample is not
num_variables()
long.
-
inline bias_type &linear(index_type v)¶
Return a reference to the linear bias associated with
v
.
-
inline const bias_type &linear(index_type v) const¶
Return a reference to the linear bias associated with
v
.
-
inline std::pair<const_neighborhood_iterator, const_neighborhood_iterator> neighborhood(index_type u) const¶
Return a pair of iterators - the start and end of the neighborhood.
-
inline std::pair<const_neighborhood_iterator, const_neighborhood_iterator> neighborhood(index_type u, index_type start) const¶
The neighborhood of variable
v
.- Parameters
A – variable
v
.The – neighborhood will start with the first out variable that does not compare less than
start
.
- Returns
A pair of iterators pointing to the start and end of the neighborhood.
-
inline bias_type quadratic(index_type u, index_type v) const¶
Return the quadratic bias associated with
u
,v
.If
u
andv
do not have a quadratic bias, returns 0.Note that this function does not return a reference, this is because each quadratic bias is stored twice.
-
inline bias_type quadratic_at(index_type u, index_type v) const¶
Return the quadratic bias associated with
u
,v
.Note that this function does not return a reference, this is because each quadratic bias is stored twice.
Raises an
out_of_range
error if eitheru
orv
are not variables or if they do not have an interaction then the function throws an exception.
-
inline size_type nbytes(bool capacity = false) const noexcept¶
Total bytes consumed by the biases and indices.
If
capacity
is true, use the capacity of the underlying vectors rather than the size.
-
inline size_type num_interactions() const¶
Return the number of interactions in the quadratic model.
O(num_variables*log(num_variables))
complexity.
-
inline size_type num_interactions(index_type v) const¶
The number of other variables
v
interacts with.
-
inline bool remove_interaction(index_type u, index_type v)¶
Remove the interaction if it exists.
-
inline void resize(index_type n)¶
Resize model to contain n variables.
-
inline void scale(double scale_factor)¶
Scale offset, linear biases, and interactions by a factor.
-
inline void swap(QuadraticModelBase<bias_type, index_type> &other)¶
Exchange the contents of the quadratic model with the contents of
other
.
-
inline void swap_variables(index_type u, index_type v)¶
Swap the linear and quadratic biases between two variables.
-
using size_type = std::size_t¶