dlinear  0.0.1
Delta-complete SMT solver for linear programming
Loading...
Searching...
No Matches
dlinear::drake::symbolic::Expression Class Reference

Represents a symbolic form of an expression. More...

#include <symbolic_expression.h>

Public Member Functions

 Expression ()
 Default constructor.
 
 Expression (const mpq_class &d)
 Constructs a constant (rational).
 
 Expression (const Variable &var)
 Constructs an expression from var.
 
ExpressionKind get_kind () const
 Returns expression kind.
 
size_t get_hash () const
 Returns hash value.
 
const VariablesGetVariables () const
 Collects variables in expression.
 
bool EqualTo (const Expression &e) const
 Checks structural equality.
 
bool Less (const Expression &e) const
 Provides lexicographical ordering between expressions.
 
bool is_polynomial () const
 Checks if this symbolic expression is convertible to Polynomial.
 
bool include_ite () const
 Returns true if this symbolic expression includes an ITE (If-Then-Else) expression.
 
mpq_class Evaluate (const Environment &env=Environment{}) const
 Evaluates under a given environment (by default, an empty environment).
 
Expression EvaluatePartial (const Environment &env) const
 Partially evaluates this expression using an environment env.
 
Expression Expand () const
 Expands out products and positive integer powers in expression.
 
Expression Substitute (const Variable &var, const Expression &e) const
 Returns a copy of this expression replacing all occurrences of var with e.
 
Expression Substitute (const ExpressionSubstitution &expr_subst, const FormulaSubstitution &formula_subst) const
 Returns a copy of this expression replacing all occurrences of the variables in expr_subst with corresponding expressions in expr_subst and all occurrences of the variables in formula_subst with corresponding formulas in formula_subst.
 
Expression Substitute (const ExpressionSubstitution &expr_subst) const
 Returns a copy of this expression replacing all occurrences of the variables in expr_subst with corresponding expressions in expr_subst.
 
Expression Substitute (const FormulaSubstitution &formula_subst) const
 Returns a copy of this expression replacing all occurrences of the variables in formula_subst with corresponding formulas in formula_subst.
 
Expression Differentiate (const Variable &x) const
 Differentiates this symbolic expression with respect to the variable var.
 
std::string to_string () const
 Returns string representation of Expression.
 
Expressionoperator++ ()
 Provides prefix increment operator (i.e.
 
Expression operator++ (int)
 Provides postfix increment operator (i.e.
 
Expressionoperator-- ()
 Provides prefix decrement operator (i.e.
 
Expression operator-- (int)
 Provides postfix decrement operator (i.e.
 

Static Public Member Functions

static Expression Zero ()
 Returns zero.
 
static Expression One ()
 Returns one.
 
static Expression Pi ()
 Returns Pi, the ratio of a circle’s circumference to its diameter.
 
static Expression E ()
 Return e, the base of natural logarithms.
 
static Expression NaN ()
 Returns NaN (Not-a-Number).
 
static Expression Infty ()
 Returns positive infinity.
 
static Expression NInfty ()
 Returns negative infinity.
 

Friends

Expression operator+ (const Expression &e)
 Provides unary plus operator.
 
Expression operator- (const Expression &e)
 Provides unary minus operator.
 
Expression log (const Expression &e)
 Creates an real-constant expression represented by [lb, ub].
 
Expression if_then_else (const Formula &f_cond, const Expression &e_then, const Expression &e_else)
 Constructs if-then-else expression.
 
Expression uninterpreted_function (const std::string &name, const Variables &vars)
 Constructs an uninterpreted-function expression with name and vars.
 
bool is_constant (const Expression &e)
 Checks if e is a rational constant expression.
 
bool is_variable (const Expression &e)
 Checks if e is a variable expression.
 
bool is_addition (const Expression &e)
 Checks if e is an addition expression.
 
bool is_multiplication (const Expression &e)
 Checks if e is a multiplication expression.
 
bool is_division (const Expression &e)
 Checks if e is a division expression.
 
bool is_log (const Expression &e)
 Checks if e is a log expression.
 
bool is_abs (const Expression &e)
 Checks if e is an abs expression.
 
bool is_exp (const Expression &e)
 Checks if e is an exp expression.
 
bool is_sqrt (const Expression &e)
 Checks if e is a square-root expression.
 
bool is_pow (const Expression &e)
 Checks if e is a power-function expression.
 
bool is_sin (const Expression &e)
 Checks if e is a sine expression.
 
bool is_cos (const Expression &e)
 Checks if e is a cosine expression.
 
bool is_tan (const Expression &e)
 Checks if e is a tangent expression.
 
bool is_asin (const Expression &e)
 Checks if e is an arcsine expression.
 
bool is_acos (const Expression &e)
 Checks if e is an arccosine expression.
 
bool is_atan (const Expression &e)
 Checks if e is an arctangent expression.
 
bool is_atan2 (const Expression &e)
 Checks if e is an arctangent2 expression.
 
bool is_sinh (const Expression &e)
 Checks if e is a hyperbolic-sine expression.
 
bool is_cosh (const Expression &e)
 Checks if e is a hyperbolic-cosine expression.
 
bool is_tanh (const Expression &e)
 Checks if e is a hyperbolic-tangent expression.
 
bool is_min (const Expression &e)
 Checks if e is a min expression.
 
bool is_max (const Expression &e)
 Checks if e is a max expression.
 
bool is_if_then_else (const Expression &e)
 Checks if e is an if-then-else expression.
 
bool is_uninterpreted_function (const Expression &e)
 Checks if e is an uninterpreted-function expression.
 
const ExpressionConstantto_constant (const Expression &e)
 Casts e of Expression to const ExpressionConstant*.
 
const ExpressionInftyto_infty (const Expression &e)
 Casts e of Expression to const ExpressionInfty*.
 
const ExpressionVarto_variable (const Expression &e)
 Casts e of Expression to const ExpressionVar*.
 
const UnaryExpressionCellto_unary (const Expression &e)
 Casts e of Expression to const UnaryExpressionCell*.
 
const BinaryExpressionCellto_binary (const Expression &e)
 Casts e of Expression to const BinaryExpressionCell*.
 
const ExpressionAddto_addition (const Expression &e)
 Casts e of Expression to const ExpressionAdd*.
 
ExpressionAddto_addition (Expression &e)
 Casts e of Expression to ExpressionAdd*.
 
const ExpressionMulto_multiplication (const Expression &e)
 Casts e of Expression to const ExpressionMul*.
 
ExpressionMulto_multiplication (Expression &e)
 Casts e of Expression to ExpressionMul*.
 
const ExpressionDivto_division (const Expression &e)
 Casts e of Expression to const ExpressionDiv*.
 
const ExpressionLogto_log (const Expression &e)
 Casts e of Expression to const ExpressionLog*.
 
const ExpressionAbsto_abs (const Expression &e)
 Casts e of Expression to const ExpressionAbs*.
 
const ExpressionExpto_exp (const Expression &e)
 Casts e of Expression to const ExpressionExp*.
 
const ExpressionSqrtto_sqrt (const Expression &e)
 Casts e of Expression to const ExpressionSqrt*.
 
const ExpressionPowto_pow (const Expression &e)
 Casts e of Expression to const ExpressionPow*.
 
const ExpressionSinto_sin (const Expression &e)
 Casts e of Expression to const ExpressionSin*.
 
const ExpressionCosto_cos (const Expression &e)
 Casts e of Expression to const ExpressionCos*.
 
const ExpressionTanto_tan (const Expression &e)
 Casts e of Expression to const ExpressionTan*.
 
const ExpressionAsinto_asin (const Expression &e)
 Casts e of Expression to const ExpressionAsin*.
 
const ExpressionAcosto_acos (const Expression &e)
 Casts e of Expression to const ExpressionAcos*.
 
const ExpressionAtanto_atan (const Expression &e)
 Casts e of Expression to const ExpressionAtan*.
 
const ExpressionAtan2to_atan2 (const Expression &e)
 Casts e of Expression to const ExpressionAtan2*.
 
const ExpressionSinhto_sinh (const Expression &e)
 Casts e of Expression to const ExpressionSinh*.
 
const ExpressionCoshto_cosh (const Expression &e)
 Casts e of Expression to const ExpressionCosh*.
 
const ExpressionTanhto_tanh (const Expression &e)
 Casts e of Expression to const ExpressionTanh*.
 
const ExpressionMinto_min (const Expression &e)
 Casts e of Expression to const ExpressionMin*.
 
const ExpressionMaxto_max (const Expression &e)
 Casts e of Expression to const ExpressionMax*.
 
const ExpressionIfThenElseto_if_then_else (const Expression &e)
 Casts e of Expression to const ExpressionIfThenElse*.
 
const ExpressionUninterpretedFunctionto_uninterpreted_function (const Expression &e)
 Casts e of Expression to const ExpressionUninterpretedFunction*.
 

Detailed Description

Represents a symbolic form of an expression.

Its syntax tree is as follows:

    E := Var | Constant(mpq_class)
       | E + ... + E | E * ... * E | E / E | log(E)
       | abs(E) | exp(E) | sqrt(E) | pow(E, E) | sin(E) | cos(E) | tan(E)
       | asin(E) | acos(E) | atan(E) | atan2(E, E) | sinh(E) | cosh(E) | tanh(E)
       | min(E, E) | max(E, E) | if_then_else(F, E, E) | NaN | infinity
       | uninterpreted_function(name, {v_1, ..., v_n})

In the implementation, Expression is a simple wrapper including a pointer to ExpressionCell class which is a super-class of different kinds of symbolic expressions (i.e. ExpressionAdd, ExpressionMul, ExpressionLog, ExpressionSin).

Note
The sharing of sub-expressions is not yet implemented.
-E is represented as -1 * E internally.
A subtraction E1 - E2 is represented as E1 + (-1 * E2) internally.

The following simple simplifications are implemented:

    E + 0             ->  E
    0 + E             ->  E
    E - 0             ->  E
    E - E             ->  0
    E * 1             ->  E
    1 * E             ->  E
    E * 0             ->  0
    0 * E             ->  0
    E / 1             ->  E
    E / E             ->  1
    pow(E, 0)         ->  1
    pow(E, 1)         ->  E
    E * E             ->  E^2 (= pow(E, 2))
    sqrt(E * E)       ->  |E| (= abs(E))
    sqrt(E) * sqrt(E) -> E

Constant folding is implemented:

    E(c1) + E(c2)  ->  E(c1 + c2)    // c1, c2 are constants
    E(c1) - E(c2)  ->  E(c1 - c2)
    E(c1) * E(c2)  ->  E(c1 * c2)
    E(c1) / E(c2)  ->  E(c1 / c2)
    f(E(c))        ->  E(f(c))       // c is a constant, f is a math function

For the math functions which are only defined over a restricted domain (namely, log, sqrt, pow, asin, acos), we check the domain of argument(s), and throw std::domain_error exception if a function is not well-defined for a given argument(s).

Relational operators over expressions (==, !=, <, >, <=, >=) return symbolic::Formula instead of bool. Those operations are declared in symbolic_formula.h file. To check structural equality between two expressions a separate function, Expression::EqualTo, is provided.

Definition at line 162 of file symbolic_expression.h.

Constructor & Destructor Documentation

◆ Expression() [1/2]

dlinear::drake::symbolic::Expression::Expression ( )

Default constructor.

It constructs Zero().

◆ Expression() [2/2]

dlinear::drake::symbolic::Expression::Expression ( const Variable & var)

Constructs an expression from var.

Precondition
var is neither a dummy nor a BOOLEAN variable.

Member Function Documentation

◆ Differentiate()

Expression dlinear::drake::symbolic::Expression::Differentiate ( const Variable & x) const

Differentiates this symbolic expression with respect to the variable var.

Exceptions
std::runtime_errorif it is not differentiable.

◆ EqualTo()

bool dlinear::drake::symbolic::Expression::EqualTo ( const Expression & e) const

Checks structural equality.

Two expressions e1 and e2 are structurally equal when they have the same internal AST(abstract-syntax tree) representation. Please note that we can have two computationally (or extensionally) equivalent expressions which are not structurally equal. For example, consider:

e1 = 2 * (x + y) e2 = 2x + 2y

Obviously, we know that e1 and e2 are evaluated to the same value for all assignments to x and y. However, e1 and e2 are not structurally equal by the definition. Note that e1 is a multiplication expression (is_multiplication(e1) is true) while e2 is an addition expression (is_addition(e2) is true).

One main reason we use structural equality in EqualTo is due to Richardson's Theorem. It states that checking ∀x. E(x) = F(x) is undecidable when we allow sin, asin, log, exp in E and F. Read https://en.wikipedia.org/wiki/Richardson%27s_theorem for details.

Note that for polynomial cases, you can use Expand method and check if two polynomial expressions p1 and p2 are computationally equal. To do so, you check the following:

(p1.Expand() - p2.Expand()).EqualTo(0).

◆ Evaluate()

mpq_class dlinear::drake::symbolic::Expression::Evaluate ( const Environment & env = Environment{}) const

Evaluates under a given environment (by default, an empty environment).

Exceptions
std::runtime_errorif NaN is detected during evaluation.

◆ EvaluatePartial()

Expression dlinear::drake::symbolic::Expression::EvaluatePartial ( const Environment & env) const

Partially evaluates this expression using an environment env.

Internally, this method promotes env into a substitution (VariableExpression) and call Evaluate::Substitute with it.

Exceptions
std::runtime_errorif NaN is detected during evaluation.

◆ Expand()

Expression dlinear::drake::symbolic::Expression::Expand ( ) const

Expands out products and positive integer powers in expression.

For example, (x + 1) * (x - 1) is expanded to x^2 - 1 and (x + y)^2 is expanded to x^2 + 2xy + y^2. Note that Expand applies recursively to sub-expressions. For instance, sin(2 * (x + y)) is expanded to sin(2x + 2y). It also simplifies "division by constant" cases. See "symbolic/test/symbolic_expansion_test.cc" to find the examples.

Exceptions
std::runtime_errorif NaN is detected during expansion.

◆ Less()

bool dlinear::drake::symbolic::Expression::Less ( const Expression & e) const

Provides lexicographical ordering between expressions.

This function is used as a compare function in map<Expression> and set<Expression> via std::less<dlinear::drake::symbolic::Expression>.

◆ operator++() [1/2]

Expression & dlinear::drake::symbolic::Expression::operator++ ( )

Provides prefix increment operator (i.e.

++x).

◆ operator++() [2/2]

Expression dlinear::drake::symbolic::Expression::operator++ ( int )

Provides postfix increment operator (i.e.

x++).

◆ operator--() [1/2]

Expression & dlinear::drake::symbolic::Expression::operator-- ( )

Provides prefix decrement operator (i.e.

–x).

◆ operator--() [2/2]

Expression dlinear::drake::symbolic::Expression::operator-- ( int )

Provides postfix decrement operator (i.e.

x–).

◆ Substitute() [1/4]

Expression dlinear::drake::symbolic::Expression::Substitute ( const ExpressionSubstitution & expr_subst) const

Returns a copy of this expression replacing all occurrences of the variables in expr_subst with corresponding expressions in expr_subst.

Note
This is equivalent to Substitute(expr_subst, {}).
Exceptions
std::runtime_errorif NaN is detected during substitution.

◆ Substitute() [2/4]

Expression dlinear::drake::symbolic::Expression::Substitute ( const ExpressionSubstitution & expr_subst,
const FormulaSubstitution & formula_subst ) const

Returns a copy of this expression replacing all occurrences of the variables in expr_subst with corresponding expressions in expr_subst and all occurrences of the variables in formula_subst with corresponding formulas in formula_subst.

Note that the substitutions occur simultaneously. For example, (x / y).Substitute({{x, y}, {y, x}}, {}) gets (y / x).

Exceptions
std::runtime_errorif NaN is detected during substitution.

◆ Substitute() [3/4]

Expression dlinear::drake::symbolic::Expression::Substitute ( const FormulaSubstitution & formula_subst) const

Returns a copy of this expression replacing all occurrences of the variables in formula_subst with corresponding formulas in formula_subst.

Note
This is equivalent to Substitute({}, formula_subst).
Exceptions
std::runtime_errorif NaN is detected during substitution.

◆ Substitute() [4/4]

Expression dlinear::drake::symbolic::Expression::Substitute ( const Variable & var,
const Expression & e ) const

Returns a copy of this expression replacing all occurrences of var with e.

Exceptions
std::runtime_errorif NaN is detected during substitution.

Friends And Related Symbol Documentation

◆ if_then_else

Expression if_then_else ( const Formula & f_cond,
const Expression & e_then,
const Expression & e_else )
friend

Constructs if-then-else expression.

  if_then_else(cond, expr_then, expr_else)

The value returned by the above if-then-else expression is expr_then if cond is evaluated to true. Otherwise, it returns expr_else.

The semantics is similar to the C++'s conditional expression constructed by its ternary operator, ?:. However, there is a key difference between the C++'s conditional expression and our if_then_else expression in a way the arguments are evaluated during the construction.

  • In case of the C++'s conditional expression, cond ? expr_then : expr_else, the then expression expr_then (respectively, the else expression expr_else) is only evaluated when the conditional expression cond is evaluated to true (respectively, when cond is evaluated to false).
  • In case of the symbolic expression, if_then_else(cond, expr_then, expr_else), however, both arguments expr_then and expr_else are evaluated first and then passed to the if_then_else function.
Note
This function returns an expression and it is different from the C++'s if-then-else statement.
While it is still possible to define min, max, abs math functions using if_then_else expression, it is highly recommended to use the provided native definitions for them because it allows solvers to detect specific math functions and to have a room for special optimizations.
More information about the C++'s conditional expression and ternary operator is available at http://en.cppreference.com/w/cpp/language/operator_other#Conditional_operator.

◆ log

Expression log ( const Expression & e)
friend

Creates an real-constant expression represented by [lb, ub].

use_lb_as_representative is used to select its representative value. If it is true, lb is used. Otherwise, ub is used.

◆ to_abs

const ExpressionAbs * to_abs ( const Expression & e)
friend

Casts e of Expression to const ExpressionAbs*.

Precondition
*(e.ptr_) is of ExpressionAbs.

◆ to_acos

const ExpressionAcos * to_acos ( const Expression & e)
friend

Casts e of Expression to const ExpressionAcos*.

Precondition
*(e.ptr_) is of ExpressionAcos.

◆ to_addition [1/2]

const ExpressionAdd * to_addition ( const Expression & e)
friend

Casts e of Expression to const ExpressionAdd*.

Precondition
*(e.ptr_) is of ExpressionAdd.

◆ to_addition [2/2]

ExpressionAdd * to_addition ( Expression & e)
friend

Casts e of Expression to ExpressionAdd*.

Precondition
*(e.ptr_) is of ExpressionAdd.

◆ to_asin

const ExpressionAsin * to_asin ( const Expression & e)
friend

Casts e of Expression to const ExpressionAsin*.

Precondition
*(e.ptr_) is of ExpressionAsin.

◆ to_atan

const ExpressionAtan * to_atan ( const Expression & e)
friend

Casts e of Expression to const ExpressionAtan*.

Precondition
*(e.ptr_) is of ExpressionAtan.

◆ to_atan2

const ExpressionAtan2 * to_atan2 ( const Expression & e)
friend

Casts e of Expression to const ExpressionAtan2*.

Precondition
*(e.ptr_) is of ExpressionAtan2.

◆ to_binary

const BinaryExpressionCell * to_binary ( const Expression & e)
friend

Casts e of Expression to const BinaryExpressionCell*.

Precondition
*(e.ptr_) is of BinaryExpressionCell.

◆ to_constant

const ExpressionConstant * to_constant ( const Expression & e)
friend

Casts e of Expression to const ExpressionConstant*.

Precondition
*(e.ptr_) is of ExpressionConstant.

◆ to_cos

const ExpressionCos * to_cos ( const Expression & e)
friend

Casts e of Expression to const ExpressionCos*.

Precondition
*(e.ptr_) is of ExpressionCos.

◆ to_cosh

const ExpressionCosh * to_cosh ( const Expression & e)
friend

Casts e of Expression to const ExpressionCosh*.

Precondition
*(e.ptr_) is of ExpressionCosh.

◆ to_division

const ExpressionDiv * to_division ( const Expression & e)
friend

Casts e of Expression to const ExpressionDiv*.

Precondition
*(e.ptr_) is of ExpressionDiv.

◆ to_exp

const ExpressionExp * to_exp ( const Expression & e)
friend

Casts e of Expression to const ExpressionExp*.

Precondition
*(e.ptr_) is of ExpressionExp.

◆ to_if_then_else

const ExpressionIfThenElse * to_if_then_else ( const Expression & e)
friend

Casts e of Expression to const ExpressionIfThenElse*.

Precondition
*(e.ptr_) is of ExpressionIfThenElse.

◆ to_infty

const ExpressionInfty * to_infty ( const Expression & e)
friend

Casts e of Expression to const ExpressionInfty*.

Precondition
*(e.ptr_) is of ExpressionInfty.

◆ to_log

const ExpressionLog * to_log ( const Expression & e)
friend

Casts e of Expression to const ExpressionLog*.

Precondition
*(e.ptr_) is of ExpressionLog.

◆ to_max

const ExpressionMax * to_max ( const Expression & e)
friend

Casts e of Expression to const ExpressionMax*.

Precondition
*(e.ptr_) is of ExpressionMax.

◆ to_min

const ExpressionMin * to_min ( const Expression & e)
friend

Casts e of Expression to const ExpressionMin*.

Precondition
*(e.ptr_) is of ExpressionMin.

◆ to_multiplication [1/2]

const ExpressionMul * to_multiplication ( const Expression & e)
friend

Casts e of Expression to const ExpressionMul*.

Precondition
*(e.ptr_) is of ExpressionMul.

◆ to_multiplication [2/2]

ExpressionMul * to_multiplication ( Expression & e)
friend

Casts e of Expression to ExpressionMul*.

Precondition
*(e.ptr_) is of ExpressionMul.

◆ to_pow

const ExpressionPow * to_pow ( const Expression & e)
friend

Casts e of Expression to const ExpressionPow*.

Precondition
*(e.ptr_) is of ExpressionPow.

◆ to_sin

const ExpressionSin * to_sin ( const Expression & e)
friend

Casts e of Expression to const ExpressionSin*.

Precondition
*(e.ptr_) is of ExpressionSin.

◆ to_sinh

const ExpressionSinh * to_sinh ( const Expression & e)
friend

Casts e of Expression to const ExpressionSinh*.

Precondition
*(e.ptr_) is of ExpressionSinh.

◆ to_sqrt

const ExpressionSqrt * to_sqrt ( const Expression & e)
friend

Casts e of Expression to const ExpressionSqrt*.

Precondition
*(e.ptr_) is of ExpressionSqrt.

◆ to_tan

const ExpressionTan * to_tan ( const Expression & e)
friend

Casts e of Expression to const ExpressionTan*.

Precondition
*(e.ptr_) is of ExpressionTan.

◆ to_tanh

const ExpressionTanh * to_tanh ( const Expression & e)
friend

Casts e of Expression to const ExpressionTanh*.

Precondition
*(e.ptr_) is of ExpressionTanh.

◆ to_unary

const UnaryExpressionCell * to_unary ( const Expression & e)
friend

Casts e of Expression to const UnaryExpressionCell*.

Precondition
*(e.ptr_) is of UnaryExpressionCell.

◆ to_uninterpreted_function

const ExpressionUninterpretedFunction * to_uninterpreted_function ( const Expression & e)
friend

Casts e of Expression to const ExpressionUninterpretedFunction*.

Precondition
*(e.ptr_) is of ExpressionUninterpretedFunction.

◆ to_variable

const ExpressionVar * to_variable ( const Expression & e)
friend

Casts e of Expression to const ExpressionVar*.

Precondition
*(e.ptr_) is of ExpressionVar.

◆ uninterpreted_function

Expression uninterpreted_function ( const std::string & name,
const Variables & vars )
friend

Constructs an uninterpreted-function expression with name and vars.

An uninterpreted function is an opaque function that has no other property than its name and a set of its arguments. This is useful to applications where it is good enough to provide abstract information of a function without exposing full details. Declaring sparsity of a system is a typical example.

See also FunctionalForm::Arbitrary(Variables v) which shares the same motivation.


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