Drake
GenericPolynomial< BasisElement > Class Template Reference

Detailed Description

template<typename BasisElement>
class drake::symbolic::GenericPolynomial< BasisElement >

Represents symbolic generic polynomials using a given basis (for example, monomial basis, Chebyshev basis, etc).

A generic symbolic polynomial keeps a mapping from a basis element of indeterminates to its coefficient in a symbolic expression. A generic polynomial p has to satisfy an invariant such that p.decision_variables() ∩ p.indeterminates() = ∅. We have CheckInvariant() method to check the invariant. For polynomials using different basis, you could refer to section 3.1.5 of Semidefinite Optimization and Convex Algebraic Geometry on the pros/cons of each basis.

We provide two instantiations of this template

#include <drake/common/symbolic_generic_polynomial.h>

Public Types

using MapType = std::map< BasisElement, Expression >
 Type of mapping from basis element to coefficient. More...
 

Public Member Functions

 GenericPolynomial ()=default
 Constructs a zero polynomial. More...
 
 GenericPolynomial (std::nullptr_t)
 Constructs a default value. More...
 
 GenericPolynomial (MapType init)
 Constructs a generic polynomial from a map, basis_element → coefficient. More...
 
 GenericPolynomial (const BasisElement &m)
 Constructs a generic polynomial from a single basis element m. More...
 
 GenericPolynomial (const Expression &e)
 Constructs a polynomial from an expression e. More...
 
 GenericPolynomial (const Expression &e, Variables indeterminates)
 Constructs a polynomial from an expression e by decomposing it with respect to indeterminates. More...
 
const Variablesindeterminates () const
 Returns the indeterminates of this generic polynomial. More...
 
const Variablesdecision_variables () const
 Returns the decision variables of this generic polynomial. More...
 
void SetIndeterminates (const Variables &new_indeterminates)
 Sets the indeterminates to new_indeterminates. More...
 
const MapTypebasis_element_to_coefficient_map () const
 Returns the map from each basis element to its coefficient. More...
 
int Degree (const Variable &v) const
 Returns the highest degree of this generic polynomial in an indeterminate v. More...
 
int TotalDegree () const
 Returns the total degree of this generic polynomial. More...
 
Expression ToExpression () const
 Returns an equivalent symbolic expression of this generic polynomial. More...
 
GenericPolynomial< BasisElement > Differentiate (const Variable &x) const
 Differentiates this generic polynomial with respect to the variable x. More...
 
template<typename Derived >
Eigen::Matrix< GenericPolynomial< BasisElement >, 1, Derived::RowsAtCompileTime > Jacobian (const Eigen::MatrixBase< Derived > &vars) const
 Computes the Jacobian matrix J of the generic polynomial with respect to vars. More...
 
double Evaluate (const Environment &env) const
 Evaluates this generic polynomial under a given environment env. More...
 
GenericPolynomial< BasisElement > EvaluatePartial (const Environment &env) const
 Partially evaluates this generic polynomial using an environment env. More...
 
GenericPolynomial< BasisElement > EvaluatePartial (const Variable &var, double c) const
 Partially evaluates this generic polynomial by substituting var with c. More...
 
GenericPolynomial< BasisElement > & AddProduct (const Expression &coeff, const BasisElement &m)
 Adds coeff * m to this generic polynomial. More...
 
GenericPolynomial< BasisElement > RemoveTermsWithSmallCoefficients (double coefficient_tol) const
 Removes the terms whose absolute value of the coefficients are smaller than or equal to coefficient_tol. More...
 
GenericPolynomial< BasisElement > & operator+= (const GenericPolynomial< BasisElement > &p)
 
GenericPolynomial< BasisElement > & operator+= (const BasisElement &m)
 
GenericPolynomial< BasisElement > & operator+= (double c)
 
GenericPolynomial< BasisElement > & operator+= (const Variable &v)
 
GenericPolynomial< BasisElement > & operator-= (const GenericPolynomial< BasisElement > &p)
 
GenericPolynomial< BasisElement > & operator-= (const BasisElement &m)
 
GenericPolynomial< BasisElement > & operator-= (double c)
 
GenericPolynomial< BasisElement > & operator-= (const Variable &v)
 
GenericPolynomial< BasisElement > & operator *= (const GenericPolynomial< BasisElement > &p)
 
GenericPolynomial< BasisElement > & operator *= (const BasisElement &m)
 
GenericPolynomial< BasisElement > & operator *= (double c)
 
GenericPolynomial< BasisElement > & operator *= (const Variable &v)
 
GenericPolynomial< BasisElement > & operator/= (double c)
 
bool EqualTo (const GenericPolynomial< BasisElement > &p) const
 Returns true if this and p are structurally equal. More...
 
bool EqualToAfterExpansion (const GenericPolynomial< BasisElement > &p) const
 Returns true if this generic polynomial and p are equal after expanding the coefficients. More...
 
bool CoefficientsAlmostEqual (const GenericPolynomial< BasisElement > &p, double tol) const
 Returns true if this polynomial and p are almost equal (the difference in the corresponding coefficients are all less than tol), after expanding the coefficients. More...
 
Formula operator== (const GenericPolynomial< BasisElement > &p) const
 Returns a symbolic formula representing the condition where this polynomial and p are the same. More...
 
Formula operator!= (const GenericPolynomial< BasisElement > &p) const
 Returns a symbolic formula representing the condition where this polynomial and p are not the same. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 GenericPolynomial (const GenericPolynomial &)=default
 
GenericPolynomialoperator= (const GenericPolynomial &)=default
 
 GenericPolynomial (GenericPolynomial &&)=default
 
GenericPolynomialoperator= (GenericPolynomial &&)=default
 

Friends

template<class HashAlgorithm >
void hash_append (HashAlgorithm &hasher, const GenericPolynomial< BasisElement > &item) noexcept
 Implements the hash_append generic hashing concept. More...
 

Member Typedef Documentation

◆ MapType

using MapType = std::map<BasisElement, Expression>

Type of mapping from basis element to coefficient.

Constructor & Destructor Documentation

◆ GenericPolynomial() [1/8]

GenericPolynomial ( )
default

Constructs a zero polynomial.

◆ GenericPolynomial() [2/8]

GenericPolynomial ( const GenericPolynomial< BasisElement > &  )
default

◆ GenericPolynomial() [3/8]

GenericPolynomial ( GenericPolynomial< BasisElement > &&  )
default

◆ GenericPolynomial() [4/8]

GenericPolynomial ( std::nullptr_t  )
explicit

Constructs a default value.

This overload is used by Eigen when EIGEN_INITIALIZE_MATRICES_BY_ZERO is enabled.

◆ GenericPolynomial() [5/8]

GenericPolynomial ( MapType  init)
explicit

Constructs a generic polynomial from a map, basis_element → coefficient.

For example

GenericPolynomial<MonomialBasiElement>(
{{MonomialBasisElement(x, 2), a}, {MonomialBasisElement(x, 3), a+b}})

constructs a polynomial ax²+(a+b)x³.

◆ GenericPolynomial() [6/8]

GenericPolynomial ( const BasisElement &  m)

Constructs a generic polynomial from a single basis element m.

Note
that all variables in m are considered as indeterminates. Namely the constructed generic polynomial contains the map with a single key m, with the coefficient being 1.

◆ GenericPolynomial() [7/8]

GenericPolynomial ( const Expression e)
explicit

Constructs a polynomial from an expression e.

Note that all variables in e are considered as indeterminates.

Exceptions
std::runtime_errorif e is not a polynomial.

◆ GenericPolynomial() [8/8]

GenericPolynomial ( const Expression e,
Variables  indeterminates 
)

Constructs a polynomial from an expression e by decomposing it with respect to indeterminates.

Note
The indeterminates for the polynomial are indeterminates. Even if a variable in indeterminates does not show up in e, that variable is still registered as an indeterminate in this polynomial, as this->indeterminates() be the same as indeterminates.
Exceptions
std::runtime_errorif e is not a polynomial in indeterminates.

Member Function Documentation

◆ AddProduct()

GenericPolynomial<BasisElement>& AddProduct ( const Expression coeff,
const BasisElement &  m 
)

Adds coeff * m to this generic polynomial.

◆ basis_element_to_coefficient_map()

const MapType& basis_element_to_coefficient_map ( ) const

Returns the map from each basis element to its coefficient.

◆ CoefficientsAlmostEqual()

bool CoefficientsAlmostEqual ( const GenericPolynomial< BasisElement > &  p,
double  tol 
) const

Returns true if this polynomial and p are almost equal (the difference in the corresponding coefficients are all less than tol), after expanding the coefficients.

◆ decision_variables()

const Variables& decision_variables ( ) const

Returns the decision variables of this generic polynomial.

◆ Degree()

int Degree ( const Variable v) const

Returns the highest degree of this generic polynomial in an indeterminate v.

◆ Differentiate()

GenericPolynomial<BasisElement> Differentiate ( const Variable x) const

Differentiates this generic polynomial with respect to the variable x.

Note that a variable x can be either a decision variable or an indeterminate.

◆ EqualTo()

bool EqualTo ( const GenericPolynomial< BasisElement > &  p) const

Returns true if this and p are structurally equal.

◆ EqualToAfterExpansion()

bool EqualToAfterExpansion ( const GenericPolynomial< BasisElement > &  p) const

Returns true if this generic polynomial and p are equal after expanding the coefficients.

◆ Evaluate()

double Evaluate ( const Environment env) const

Evaluates this generic polynomial under a given environment env.

Exceptions
std::invalid_argumentif there is a variable in this generic polynomial whose assignment is not provided by env.

◆ EvaluatePartial() [1/2]

GenericPolynomial<BasisElement> EvaluatePartial ( const Environment env) const

Partially evaluates this generic polynomial using an environment env.

Exceptions
std::runtime_errorif NaN is detected during evaluation.

◆ EvaluatePartial() [2/2]

GenericPolynomial<BasisElement> EvaluatePartial ( const Variable var,
double  c 
) const

Partially evaluates this generic polynomial by substituting var with c.

Exceptions
std::runtime_errorif NaN is detected at any point during evaluation.

◆ indeterminates()

const Variables& indeterminates ( ) const

Returns the indeterminates of this generic polynomial.

◆ Jacobian()

Eigen::Matrix<GenericPolynomial<BasisElement>, 1, Derived::RowsAtCompileTime> Jacobian ( const Eigen::MatrixBase< Derived > &  vars) const

Computes the Jacobian matrix J of the generic polynomial with respect to vars.

J(0,i) contains ∂f/∂vars(i). vars should be an Eigen column vector of symbolic variables.

◆ operator *=() [1/4]

GenericPolynomial<BasisElement>& operator *= ( const GenericPolynomial< BasisElement > &  p)

◆ operator *=() [2/4]

GenericPolynomial<BasisElement>& operator *= ( const BasisElement &  m)

◆ operator *=() [3/4]

GenericPolynomial<BasisElement>& operator *= ( double  c)

◆ operator *=() [4/4]

GenericPolynomial<BasisElement>& operator *= ( const Variable v)

◆ operator!=()

Formula operator!= ( const GenericPolynomial< BasisElement > &  p) const

Returns a symbolic formula representing the condition where this polynomial and p are not the same.

◆ operator+=() [1/4]

GenericPolynomial<BasisElement>& operator+= ( const GenericPolynomial< BasisElement > &  p)

◆ operator+=() [2/4]

GenericPolynomial<BasisElement>& operator+= ( const BasisElement &  m)

◆ operator+=() [3/4]

GenericPolynomial<BasisElement>& operator+= ( double  c)

◆ operator+=() [4/4]

GenericPolynomial<BasisElement>& operator+= ( const Variable v)

◆ operator-=() [1/4]

GenericPolynomial<BasisElement>& operator-= ( const GenericPolynomial< BasisElement > &  p)

◆ operator-=() [2/4]

GenericPolynomial<BasisElement>& operator-= ( const BasisElement &  m)

◆ operator-=() [3/4]

GenericPolynomial<BasisElement>& operator-= ( double  c)

◆ operator-=() [4/4]

GenericPolynomial<BasisElement>& operator-= ( const Variable v)

◆ operator/=()

GenericPolynomial<BasisElement>& operator/= ( double  c)

◆ operator=() [1/2]

GenericPolynomial& operator= ( GenericPolynomial< BasisElement > &&  )
default

◆ operator=() [2/2]

GenericPolynomial& operator= ( const GenericPolynomial< BasisElement > &  )
default

◆ operator==()

Formula operator== ( const GenericPolynomial< BasisElement > &  p) const

Returns a symbolic formula representing the condition where this polynomial and p are the same.

◆ RemoveTermsWithSmallCoefficients()

GenericPolynomial<BasisElement> RemoveTermsWithSmallCoefficients ( double  coefficient_tol) const

Removes the terms whose absolute value of the coefficients are smaller than or equal to coefficient_tol.

For example, if the generic polynomial is 2x² + 3xy + 10⁻⁴x - 10⁻⁵, then after calling RemoveTermsWithSmallCoefficients(1e-3), the returned polynomial becomes 2x² + 3xy.

Parameters
coefficient_tolA positive scalar.
Return values
polynomial_cleanedA generic polynomial whose terms with small coefficients are removed.

◆ SetIndeterminates()

void SetIndeterminates ( const Variables new_indeterminates)

Sets the indeterminates to new_indeterminates.

Changing the indeterminates will change basis_element_to_coefficient_map(), and also potentially the degree of the polynomial. Here is an example.

// p is a quadratic polynomial with x being the only indeterminate.
symbolic::GenericPolynomial<MonomialBasisElement> p(a * x * x + b * x + c,
{x});
// p.basis_element_to_coefficient_map() contains {1: c, x: b, x*x:a}.
std::cout << p.TotalDegree(); // prints 2.
// Now set (a, b, c) to the indeterminates. p becomes a linear
// polynomial of a, b, c.
p.SetIndeterminates({a, b, c});
// p.basis_element_to_coefficient_map() now is {a: x * x, b: x, c: 1}.
std::cout << p.TotalDegree(); // prints 1.

This function can be expensive, as it potentially reconstructs the polynomial (using the new indeterminates) from the expression.

◆ ToExpression()

Expression ToExpression ( ) const

Returns an equivalent symbolic expression of this generic polynomial.

◆ TotalDegree()

int TotalDegree ( ) const

Returns the total degree of this generic polynomial.

Friends And Related Function Documentation

◆ hash_append

void hash_append ( HashAlgorithm &  hasher,
const GenericPolynomial< BasisElement > &  item 
)
friend

Implements the hash_append generic hashing concept.


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