Google OR-Tools v9.14
a fast and portable software suite for combinatorial optimization
Loading...
Searching...
No Matches
operations_research::math_opt::QuadraticExpression Class Referencefinal

Detailed Description

This class represents a sum of quadratic terms, linear terms, and constant offset. For example: "3*x*y + 2*x + 1".

Mixing terms involving variables from different ModelStorage objects will lead to CHECK fails, including from the constructors.

The type owns the associated data representing the terms, and so should usually be passed by (const) reference to avoid unnecessary copies.

Note for implementers: Care must be taken to ensure that linear_terms_.storage() and quadratic_terms_.storage() do not disagree. That is, it is forbidden that both are non-null and not equal. Use CheckModelsAgree() and the initializer_list constructor to enforce this invariant in any class or friend method.

Definition at line 714 of file variable_and_expressions.h.

#include <variable_and_expressions.h>

Inheritance diagram for operations_research::math_opt::QuadraticExpression:
operations_research::math_opt::ModelStorageItemContainer

Public Member Functions

 QuadraticExpression ()=default
 QuadraticExpression (const QuadraticExpression &other)=default
 QuadraticExpression (std::initializer_list< QuadraticTerm > quadratic_terms, std::initializer_list< LinearTerm > linear_terms, double offset)
 QuadraticExpression (double offset)
 QuadraticExpression (Variable variable)
 QuadraticExpression (const LinearTerm &term)
 QuadraticExpression (LinearExpression expr)
 QuadraticExpression (const QuadraticTerm &term)
QuadraticExpressionoperator= (const QuadraticExpression &other)=default
 QuadraticExpression (QuadraticExpression &&other) noexcept
QuadraticExpressionoperator= (QuadraticExpression &&other) noexcept
double offset () const
const VariableMap< double > & linear_terms () const
const QuadraticTermMap< double > & quadratic_terms () const
QuadraticExpressionoperator+= (double value)
QuadraticExpressionoperator+= (Variable variable)
QuadraticExpressionoperator+= (const LinearTerm &term)
QuadraticExpressionoperator+= (const LinearExpression &expr)
QuadraticExpressionoperator+= (const QuadraticTerm &term)
QuadraticExpressionoperator+= (const QuadraticExpression &expr)
QuadraticExpressionoperator-= (double value)
QuadraticExpressionoperator-= (Variable variable)
QuadraticExpressionoperator-= (const LinearTerm &term)
QuadraticExpressionoperator-= (const LinearExpression &expr)
QuadraticExpressionoperator-= (const QuadraticTerm &term)
QuadraticExpressionoperator-= (const QuadraticExpression &expr)
QuadraticExpressionoperator*= (double value)
QuadraticExpressionoperator/= (double value)
template<typename Iterable>
void AddSum (const Iterable &items)
 }
template<typename LeftIterable, typename RightIterable>
void AddInnerProduct (const LeftIterable &left, const RightIterable &right)
double Evaluate (const VariableMap< double > &variable_values) const
double EvaluateWithDefaultZero (const VariableMap< double > &variable_values) const
Public Member Functions inherited from operations_research::math_opt::ModelStorageItemContainer
NullableModelStorageCPtr storage () const

Static Public Member Functions

template<typename Iterable>
static QuadraticExpression Sum (const Iterable &items)
static RightIterable QuadraticExpression InnerProduct (const LeftIterable &left, const RightIterable &right)

Public Attributes

this = item

Friends

QuadraticExpression operator- (QuadraticExpression expr)
std::ostream & operator<< (std::ostream &ostr, const QuadraticExpression &expr)

Additional Inherited Members

Protected Member Functions inherited from operations_research::math_opt::ModelStorageItemContainer
 ModelStorageItemContainer (const NullableModelStorageCPtr storage=nullptr)
 ModelStorageItemContainer (const ModelStorageItemContainer &other)=default
ModelStorageItemContaineroperator= (const ModelStorageItemContainer &other)=default
 ModelStorageItemContainer (ModelStorageItemContainer &&other)
ModelStorageItemContaineroperator= (ModelStorageItemContainer &&other)
void SetOrCheckStorage (const ModelStorageItem &item)
void SetOrCheckStorage (const ModelStorageItemContainer &container)

Constructor & Destructor Documentation

◆ QuadraticExpression() [1/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( )
default

For unit testing purpose, we define optional counters. We have to explicitly define the default constructor, copy constructor and assignment operators in that case. Else we use the defaults.

◆ QuadraticExpression() [2/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( const QuadraticExpression & other)
default

◆ QuadraticExpression() [3/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( std::initializer_list< QuadraticTerm > quadratic_terms,
std::initializer_list< LinearTerm > linear_terms,
double offset )
inline

Users should prefer the default constructor and operator overloads to build expressions.

Definition at line 2094 of file variable_and_expressions.h.

◆ QuadraticExpression() [4/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( double offset)
inline

Definition at line 2112 of file variable_and_expressions.h.

◆ QuadraticExpression() [5/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( Variable variable)
inline

Definition at line 2115 of file variable_and_expressions.h.

◆ QuadraticExpression() [6/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( const LinearTerm & term)
inline

Definition at line 2118 of file variable_and_expressions.h.

◆ QuadraticExpression() [7/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( LinearExpression expr)
inline

Definition at line 2121 of file variable_and_expressions.h.

◆ QuadraticExpression() [8/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( const QuadraticTerm & term)
inline

Definition at line 2130 of file variable_and_expressions.h.

◆ QuadraticExpression() [9/9]

operations_research::math_opt::QuadraticExpression::QuadraticExpression ( QuadraticExpression && other)
inlinenoexcept

A moved-from LinearExpression is the zero expression: it's not associated to a storage, has no terms and its offset is zero.

QuadraticExpression (no arithmetic)

Definition at line 2069 of file variable_and_expressions.h.

Member Function Documentation

◆ AddInnerProduct()

template<typename LeftIterable, typename RightIterable>
void operations_research::math_opt::QuadraticExpression::AddInnerProduct ( const LeftIterable & left,
const RightIterable & right )
inline

} In particular, the multiplication will be performed on the types of the elements in left and right (take care with low precision types), but the addition will always use double precision.

Definition at line 2680 of file variable_and_expressions.h.

◆ AddSum()

template<typename Iterable>
void operations_research::math_opt::QuadraticExpression::AddSum ( const Iterable & items)
inline

}

Definition at line 2666 of file variable_and_expressions.h.

◆ Evaluate()

double operations_research::math_opt::QuadraticExpression::Evaluate ( const VariableMap< double > & variable_values) const

Compute the numeric value of this expression when variables are substituted by their values in variable_values.

Will CHECK fail if a variable in linear_terms() or quadratic_terms() is missing from variables_values.

Definition at line 123 of file variable_and_expressions.cc.

◆ EvaluateWithDefaultZero()

double operations_research::math_opt::QuadraticExpression::EvaluateWithDefaultZero ( const VariableMap< double > & variable_values) const

Compute the numeric value of this expression when variables are substituted by their values in variable_values, or zero if missing from the map.

This function won't check that the variables in the input map are indeed in the same model as the ones of the expression.

Definition at line 145 of file variable_and_expressions.cc.

◆ InnerProduct()

QuadraticExpression operations_research::math_opt::QuadraticExpression::InnerProduct ( const LeftIterable & left,
const RightIterable & right )
inlinestatic

Definition at line 2686 of file variable_and_expressions.h.

◆ linear_terms()

const VariableMap< double > & operations_research::math_opt::QuadraticExpression::linear_terms ( ) const
inline

Definition at line 2135 of file variable_and_expressions.h.

◆ offset()

double operations_research::math_opt::QuadraticExpression::offset ( ) const
inline

Definition at line 2133 of file variable_and_expressions.h.

◆ operator*=()

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator*= ( double value)
inline
Note
Not adding/removing/altering variables in expression, just modifying coefficients, so no need to check that models agree.

Definition at line 2632 of file variable_and_expressions.h.

◆ operator+=() [1/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( const LinearExpression & expr)
inline

See comment in LinearExpression::operator+=.

Definition at line 2533 of file variable_and_expressions.h.

◆ operator+=() [2/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( const LinearTerm & term)
inline

Definition at line 2527 of file variable_and_expressions.h.

◆ operator+=() [3/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( const QuadraticExpression & expr)
inline

See comment in LinearExpression::operator+=.

Definition at line 2554 of file variable_and_expressions.h.

◆ operator+=() [4/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( const QuadraticTerm & term)
inline

Definition at line 2546 of file variable_and_expressions.h.

◆ operator+=() [5/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( double value)
inline

In-place arithmetic operators.

These must guarantee that the underlying model storages for linear_terms_ and quadratic_terms_ agree upon exit of the function, using CheckModelsAgree(), the list initializer constructor for QuadraticExpression, or similar logic.

Note
Not touching terms, no need to check models

Definition at line 2515 of file variable_and_expressions.h.

◆ operator+=() [6/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator+= ( Variable variable)
inline

Definition at line 2521 of file variable_and_expressions.h.

◆ operator-=() [1/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( const LinearExpression & expr)
inline

See comment in LinearExpression::operator+=.

Definition at line 2588 of file variable_and_expressions.h.

◆ operator-=() [2/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( const LinearTerm & term)
inline

Definition at line 2582 of file variable_and_expressions.h.

◆ operator-=() [3/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( const QuadraticExpression & expr)
inline

See comment in LinearExpression::operator+=.

Definition at line 2609 of file variable_and_expressions.h.

◆ operator-=() [4/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( const QuadraticTerm & term)
inline

Definition at line 2601 of file variable_and_expressions.h.

◆ operator-=() [5/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( double value)
inline
Note
Not touching terms, no need to check models

Definition at line 2570 of file variable_and_expressions.h.

◆ operator-=() [6/6]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator-= ( Variable variable)
inline

Definition at line 2576 of file variable_and_expressions.h.

◆ operator/=()

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator/= ( double value)
inline
Note
Not adding/removing/altering variables in expression, just modifying coefficients, so no need to check that models agree.

Definition at line 2652 of file variable_and_expressions.h.

◆ operator=() [1/2]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator= ( const QuadraticExpression & other)
default

◆ operator=() [2/2]

QuadraticExpression & operations_research::math_opt::QuadraticExpression::operator= ( QuadraticExpression && other)
inlinenoexcept

Definition at line 2082 of file variable_and_expressions.h.

◆ quadratic_terms()

const QuadraticTermMap< double > & operations_research::math_opt::QuadraticExpression::quadratic_terms ( ) const
inline

Definition at line 2139 of file variable_and_expressions.h.

◆ Sum()

template<typename Iterable>
QuadraticExpression operations_research::math_opt::QuadraticExpression::Sum ( const Iterable & items)
inlinestatic

Returns the sum of the elements of items.

Specifically, letting (i_1, i_2, ..., i_n) = items returns i_1 + i_2 + ... + i_n.

Example: const Variable a = ...; const Variable b = ...; const std::vector<QuadraticTerm> terms = {a * a, 2 * a * b, 3 * b * a}; QuadraticExpression::Sum(vars) => a^2 + 5 a * b Note, instead of: QuadraticExpression expr(3.0); expr += QuadraticExpression::Sum(items); Prefer: expr.AddSum(items);

See QuadraticExpression::AddSum() for a precise contract on the type Iterable.

Definition at line 2673 of file variable_and_expressions.h.

◆ operator-

QuadraticExpression operator- ( QuadraticExpression expr)
friend

We have 6 types that we must consider arithmetic among:

  1. double (scalar value)
  2. Variable (affine value)
  3. LinearTerm (affine value)
  4. LinearExpression (affine value)
  5. QuadraticTerm (quadratic value)
  6. QuadraticExpression (quadratic value) We care only about those methods that result in a QuadraticExpression. For example, multiplying a linear value with a linear value, or adding a scalar to a quadratic value. The single unary method is:
Note
A friend of QuadraticExpression, but does not touch variables

Definition at line 2266 of file variable_and_expressions.h.

◆ operator<<

std::ostream & operator<< ( std::ostream & ostr,
const QuadraticExpression & expr )
friend
Todo
(b/169415597): improve quadratic expression formatting. See b/170991498 for desired improvements for LinearExpression streaming which are also applicable here.

Definition at line 160 of file variable_and_expressions.cc.

Member Data Documentation

◆ this

* operations_research::math_opt::QuadraticExpression::this = item

Adds each element of items to this.

Specifically, letting (i_1, i_2, ..., i_n) = items adds i_1 + i_2 + ... + i_n to this.

Example: const Variable a = ...; const Variable b = ...; const std::vector<Variable> vars = {a, b}; const std::vector<QuadraticTerm> terms = {2 * a * b}; QuadraticExpression expr = 8; expr.AddSum(vars); expr.AddSum(terms); Results in expr having the value 2 * a * b + a + b + 8.0.

Compile time requirements:

Note
The implementation is equivalent to: for(const auto item : items) {

Adds the inner product of left and right to this.

Specifically, letting (l_1, l_2 ..., l_n) = left, (r_1, r_2, ..., r_n) = right, adds l_1 * r_1 + l_2 * r_2 + ... + l_n * r_n to this.

Example: const Variable a = ...; const Variable b = ...; const std::vector<Variable> vars = {a, b}; const std::vector<double> coeffs = {10.0, 2.0}; QuadraticExpression expr = 3.0; expr.AddInnerProduct(coeffs, vars); expr.AddInnerProduct(vars, vars); Results in expr having the value a^2 + b^2 + 10.0 * a + 2.0 * b + 3.0.

Compile time requirements:

  • LeftIterable and RightIterable are both sequences (arrays or objects with begin() and end())
  • For both left and right, their elements are of type double, Variable, LinearTerm, LinearExpression, QuadraticTerm, or QuadraticExpression (or is implicitly convertible to one of these types, e.g. int). Runtime requirements (or CHECK fails):
  • The inner product value, and its constitutive intermediate terms, can be represented as a QuadraticExpression (potentially through an implicit conversion).
  • left and right have an equal number of elements.
Note
The implementation is equivalent to the following pseudocode: for(const auto& [l, r] : zip(left, right)) {

Definition at line 787 of file variable_and_expressions.h.


The documentation for this class was generated from the following files: