Detailed Description

This class represents a sum of variables multiplied by coefficient and an optional offset constant. For example: "3*x + 2*y + 5".

All operations, including constructor, will raise an assertion if the operands involve variables from different Model objects.

Contrary to Variable type, expressions owns the linear expression their represent. Hence they are usually passed by reference to prevent unnecessary copies.

Todo

(b/169415098): add a function to remove zero terms.

(b/169415834): study if exact zeros should be automatically removed.

(b/169415103): add tests that some expressions don't compile.

Definition at line 207 of file variable_and_expressions.h.

#include <variable_and_expressions.h>

Inheritance diagram for operations_research::math_opt::LinearExpression:

Public Member Functions
	LinearExpression ()=default
	LinearExpression (const LinearExpression &other)=default
	LinearExpression (std::initializer_list< LinearTerm > terms, double offset)
	LinearExpression (double offset)
	LinearExpression (Variable variable)
	LinearExpression (const LinearTerm &term)
LinearExpression &	operator= (const LinearExpression &other)=default
	LinearExpression (LinearExpression &&other) noexcept
LinearExpression &	operator= (LinearExpression &&other) noexcept
LinearExpression &	operator+= (const LinearExpression &other)
LinearExpression &	operator+= (const LinearTerm &term)
LinearExpression &	operator+= (Variable variable)
LinearExpression &	operator+= (double value)
LinearExpression &	operator-= (const LinearExpression &other)
LinearExpression &	operator-= (const LinearTerm &term)
LinearExpression &	operator-= (Variable variable)
LinearExpression &	operator-= (double value)
LinearExpression &	operator*= (double value)
LinearExpression &	operator/= (double value)
template<typename Iterable>
void	AddSum (const Iterable &items)
	}
template<typename LeftIterable, typename RightIterable>
void	AddInnerProduct (const LeftIterable &left, const RightIterable &right)
const VariableMap< double > &	terms () const
	Returns the terms in this expression.
double	offset () const
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 LinearExpression	Sum (const Iterable &items)
template<typename LeftIterable, typename RightIterable>
static LinearExpression	InnerProduct (const LeftIterable &left, const RightIterable &right)

Public Attributes
*	this = item

Friends
LinearExpression	operator- (LinearExpression expr)
std::ostream &	operator<< (std::ostream &ostr, const LinearExpression &expression)

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

Constructor & Destructor Documentation

◆ LinearExpression() [1/7]

operations_research::math_opt::LinearExpression::LinearExpression ( )

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.

◆ LinearExpression() [2/7]

operations_research::math_opt::LinearExpression::LinearExpression ( const LinearExpression & other )

default

◆ LinearExpression() [3/7]

operations_research::math_opt::LinearExpression::LinearExpression	(	std::initializer_list< LinearTerm >	terms,
		double	offset )

inline

Usually users should use the overloads of operators to build linear expressions. For example, assuming x and y are Variable, then x + 2*y / + 5 will build a LinearExpression automatically.

The same variable may appear multiple times in the input list; we must accumulate the coefficients.

Definition at line 1335 of file variable_and_expressions.h.

◆ LinearExpression() [4/7]

operations_research::math_opt::LinearExpression::LinearExpression ( double offset )

inline

Definition at line 1349 of file variable_and_expressions.h.

◆ LinearExpression() [5/7]

operations_research::math_opt::LinearExpression::LinearExpression ( Variable variable )

inline

Definition at line 1352 of file variable_and_expressions.h.

◆ LinearExpression() [6/7]

operations_research::math_opt::LinearExpression::LinearExpression ( const LinearTerm & term )

inline

Definition at line 1355 of file variable_and_expressions.h.

◆ LinearExpression() [7/7]

operations_research::math_opt::LinearExpression::LinearExpression ( LinearExpression && 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.

LinearExpression

Definition at line 1314 of file variable_and_expressions.h.

Member Function Documentation

◆ AddInnerProduct()

template<typename LeftIterable, typename RightIterable>

void operations_research::math_opt::LinearExpression::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 1629 of file variable_and_expressions.h.

◆ AddSum()

template<typename Iterable>

void operations_research::math_opt::LinearExpression::AddSum ( const Iterable & items )

inline

}

Definition at line 1588 of file variable_and_expressions.h.

◆ Evaluate()

double operations_research::math_opt::LinearExpression::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 terms() is missing from variables_values.

Definition at line 64 of file variable_and_expressions.cc.

◆ EvaluateWithDefaultZero()

double operations_research::math_opt::LinearExpression::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 76 of file variable_and_expressions.cc.

◆ InnerProduct()

template<typename LeftIterable, typename RightIterable>

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

inlinestatic

Creates a new LinearExpression object equal to the inner product. The implementation is equivalent to: LinearExpression expr; expr.AddInnerProduct(left, right);

Definition at line 1635 of file variable_and_expressions.h.

◆ offset()

double operations_research::math_opt::LinearExpression::offset ( ) const

inline

Definition at line 1650 of file variable_and_expressions.h.

◆ operator*=()

LinearExpression & operations_research::math_opt::LinearExpression::operator*= ( double value )

inline

Definition at line 1571 of file variable_and_expressions.h.

◆ operator+=() [1/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator+= ( const LinearExpression & other )

inline

Here we know that each key in other.terms_ has already been checked and thus we don't need to compare in the loop. Of course this only applies if the other has terms.

Definition at line 1513 of file variable_and_expressions.h.

◆ operator+=() [2/4]

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

inline

Definition at line 1527 of file variable_and_expressions.h.

◆ operator+=() [3/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator+= ( double value )

inline

Definition at line 1538 of file variable_and_expressions.h.

◆ operator+=() [4/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator+= ( Variable variable )

inline

Definition at line 1533 of file variable_and_expressions.h.

◆ operator-=() [1/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator-= ( const LinearExpression & other )

inline

See operator+=.

Definition at line 1543 of file variable_and_expressions.h.

◆ operator-=() [2/4]

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

inline

Definition at line 1555 of file variable_and_expressions.h.

◆ operator-=() [3/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator-= ( double value )

inline

Definition at line 1566 of file variable_and_expressions.h.

◆ operator-=() [4/4]

LinearExpression & operations_research::math_opt::LinearExpression::operator-= ( Variable variable )

inline

Definition at line 1561 of file variable_and_expressions.h.

◆ operator/=()

LinearExpression & operations_research::math_opt::LinearExpression::operator/= ( double value )

inline

Definition at line 1579 of file variable_and_expressions.h.

◆ operator=() [1/2]

LinearExpression & operations_research::math_opt::LinearExpression::operator= ( const LinearExpression & other )

default

◆ operator=() [2/2]

LinearExpression & operations_research::math_opt::LinearExpression::operator= ( LinearExpression && other )

inlinenoexcept

Definition at line 1325 of file variable_and_expressions.h.

◆ Sum()

template<typename Iterable>

LinearExpression operations_research::math_opt::LinearExpression::Sum ( const Iterable & items )

inlinestatic

Creates a new LinearExpression object equal to the sum. The implementation is equivalent to: LinearExpression expr; expr.AddSum(items);

Definition at line 1595 of file variable_and_expressions.h.

◆ terms()

const VariableMap< double > & operations_research::math_opt::LinearExpression::terms ( ) const

inline

Returns the terms in this expression.

Definition at line 1648 of file variable_and_expressions.h.

◆ operator-

LinearExpression operator- ( LinearExpression expr )

friend

We intentionally pass one of the LinearExpression argument by value so that we don't make unnecessary copies of temporary objects by using the move constructor and the returned values optimization (RVO).

Definition at line 1358 of file variable_and_expressions.h.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	ostr,
		const LinearExpression &	expression )

friend

Todo

(b/169415597): improve linear expression format:

make sure to quote the variable name so that we support:

Definition at line 86 of file variable_and_expressions.cc.

Member Data Documentation

◆ this

* operations_research::math_opt::LinearExpression::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}; LinearExpression expr(8.0); expr.AddSum(vars); Results in expr having the value a + b + 8.0.

Compile time requirements:

Iterable is a sequence (an array or object with begin() and end()).
The type of an element of items is one of double, Variable, LinearTerm or LinearExpression (or is implicitly convertible to one of these types, e.g. int).

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> left = {a, b}; const std::vector<double> right = {10.0, 2.0}; LinearExpression expr(3.0); expr.AddInnerProduct(left, right) Results in expr having the value 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 a type of either double, Variable, LinearTerm or LinearExpression (or type implicitly convertible to one of these types, e.g. int).
At least one of left or right has elements with type double (or a type implicitly convertible, e.g. int). Runtime requirements (or CHECK fails):
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 268 of file variable_and_expressions.h.

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

ortools/math_opt/cpp/variable_and_expressions.h
ortools/math_opt/cpp/variable_and_expressions.cc

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ LinearExpression() [1/7]

◆ LinearExpression() [2/7]

◆ LinearExpression() [3/7]

◆ LinearExpression() [4/7]

◆ LinearExpression() [5/7]

◆ LinearExpression() [6/7]

◆ LinearExpression() [7/7]

Member Function Documentation

◆ AddInnerProduct()

◆ AddSum()

◆ Evaluate()

◆ EvaluateWithDefaultZero()

◆ InnerProduct()

◆ offset()

◆ operator*=()

◆ operator+=() [1/4]

◆ operator+=() [2/4]

◆ operator+=() [3/4]

◆ operator+=() [4/4]

◆ operator-=() [1/4]

◆ operator-=() [2/4]

◆ operator-=() [3/4]

◆ operator-=() [4/4]

◆ operator/=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Sum()

◆ terms()

Friends And Related Symbol Documentation

◆ operator-

◆ operator<<

Member Data Documentation

◆ this