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

BasisElement = MonomialBasisElement
BasisElement = ChebyshevBasisElement
Template Parameters

BasisElement Must be a subclass of PolynomialBasisElement.

#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 Variables &	indeterminates () const
	Returns the indeterminates of this generic polynomial. More...

const Variables &	decision_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 MapType &	basis_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

GenericPolynomial &	operator= (const GenericPolynomial &)=default

	GenericPolynomial (GenericPolynomial &&)=default

GenericPolynomial &	operator= (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::exception if 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::exception if 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::exception if 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::exception if 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::exception if 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_tol A positive scalar.

Return values

polynomial_cleaned A 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:

drake/common/symbolic/generic_polynomial.h

Detailed Description

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

Public Types

Public Member Functions

Friends

Member Typedef Documentation

◆ MapType

Constructor & Destructor Documentation

◆ GenericPolynomial() [1/8]

◆ GenericPolynomial() [2/8]

◆ GenericPolynomial() [3/8]

◆ GenericPolynomial() [4/8]

◆ GenericPolynomial() [5/8]

◆ GenericPolynomial() [6/8]

◆ GenericPolynomial() [7/8]

◆ GenericPolynomial() [8/8]

Member Function Documentation

◆ AddProduct()

◆ basis_element_to_coefficient_map()

◆ CoefficientsAlmostEqual()

◆ decision_variables()

◆ Degree()

◆ Differentiate()

◆ EqualTo()

◆ EqualToAfterExpansion()

◆ Evaluate()

◆ EvaluatePartial() [1/2]

◆ EvaluatePartial() [2/2]

◆ indeterminates()

◆ Jacobian()

◆ operator *=() [1/4]

◆ operator *=() [2/4]

◆ operator *=() [3/4]

◆ operator *=() [4/4]

◆ 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]

◆ operator==()

◆ RemoveTermsWithSmallCoefficients()

◆ SetIndeterminates()

◆ ToExpression()

◆ TotalDegree()

Friends And Related Function Documentation

◆ hash_append

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