#include <deal.II/differentiation/sd/symengine_number_types.h>

Public Member Functions
Constructors
	Expression ()

	Expression (const bool &value)

template<typename NumberType , typename = typename std::enable_if< std::is_arithmetic<NumberType>::value>::type>
	Expression (const NumberType &value)

template<typename NumberType , typename = typename std::enable_if< std::is_arithmetic<NumberType>::value>::type>
	Expression (const std::complex< NumberType > &value)

	Expression (const SymEngine::integer_class &value)

template<typename NumberType , typename = typename std::enable_if< std::is_integral<NumberType>::value>::type>
	Expression (const NumberType &numerator, const NumberType &denominator)

	Expression (const SymEngine::rational_class &value)

	Expression (const Expression &condition, const Expression &expression_if_true, const Expression &expression_if_false)

	Expression (const std::vector< std::pair< Expression, Expression >> &condition_expression, const Expression &expression_otherwise)

	Expression (const std::vector< std::pair< Expression, Expression >> &condition_expression)

	Expression (const char *symbol)

	Expression (const std::string &symb_expr, const bool parse_as_expression=false)

	Expression (const std::string &symbol_func, const types::symbol_vector &arguments)

	Expression (const Expression &rhs)=default

	Expression (const SymEngine::Expression &rhs)

	Expression (const SymEngine::RCP< const SymEngine::Basic > &rhs)

	Expression (Expression &&rhs)=default

	Expression (SymEngine::RCP< const SymEngine::Basic > &&rhs)

virtual	~Expression ()=default


Expression &	parse (const std::string &expression)

std::ostream &	print (std::ostream &stream) const

void	save (std::ostream &stream) const

void	load (std::istream &stream)

template<class Archive >
void	serialize (Archive &archive, const unsigned int version)

Values
const SymEngine::Expression &	get_expression () const

const SymEngine::Basic &	get_value () const

const SymEngine::RCP< const SymEngine::Basic > &	get_RCP () const

Math and relational operators with (potentially) symbolic types
Expression &	operator= (const Expression &rhs)

Expression &	operator= (Expression &&rhs)

Expression &	operator+= (const Expression &rhs)

Expression &	operator-= (const Expression &rhs)

Expression &	operator*= (const Expression &rhs)

Expression &	operator/= (const Expression &rhs)

Math and relational operators with numeric types
template<typename NumberType >
Expression &	operator= (const NumberType &rhs)

Expression	operator- () const

template<typename NumberType >
Expression &	operator+= (const NumberType &rhs)

template<typename NumberType >
Expression &	operator-= (const NumberType &rhs)

template<typename NumberType >
Expression &	operator*= (const NumberType &rhs)

template<typename NumberType >
Expression &	operator/= (const NumberType &rhs)

Differentiation
Expression	differentiate (const Expression &symbol) const

Expression	differentiate (const SymEngine::RCP< const SymEngine::Symbol > &symbol) const

Expression	differentiate (const SymEngine::RCP< const SymEngine::Basic > &symbol) const

Dictionary-based substitution
Expression	substitute (const types::substitution_map &substitution_values) const

Expression	substitute (const Expression &symbol, const Expression &value) const

template<typename NumberType >
Expression	substitute (const Expression &symbol, const NumberType &value) const

template<typename ReturnType >
ReturnType	substitute_and_evaluate (const types::substitution_map &substitution_values) const

Conversion operators
template<typename ResultType >
	operator ResultType () const

	operator const SymEngine::Expression & () const

	operator const SymEngine::RCP< const SymEngine::Basic > & () const

Protected Member Functions
SymEngine::Expression &	get_expression ()

Private Attributes
SymEngine::Expression	expression

Detailed Description

A class to wrap SymEngine expressions.

With this number type, SymEngine numbers can be used to perform scalar and tensor mathematics in deal.II. It (or the SymEngine::Expression class, of which it stores an instance) therefore forms the basis of symbolic computation via SymEngine in deal.II. With it one can perform symbolic differentiation and subsequent substitution with both scalars and deal.II's native Tensor and SymmetricTensor types.

The symbolic features that this class supports includes:

expression parsing,
comparison operations,
logical operations,
math operations,
conditional expression construction,
differentiation,
substitution (partial and complete), and
serialization.

A simple example of how this class may be used is as follows:

// Constructing a symbolic expression:
// This is a symbol, which we will treat as an argument to a symbolic
// function.
const Expression x("x");
const Expression y("y");
// This is a symbolic expression, which is an expression constructed
// from individual symbols.
const Expression f = (x + y)*(x + y);
// Value substitution
types::substitution_map substitution_map;
substitution_map[x] = Expression(1);
substitution_map[y] = Expression(2.5);
const double evaluated_f =
  f.substitute_and_evaluate<double>(substitution_map);
// We could also have performed substitution of each individual
// argument, if we wanted to. This means that one can partially
// substitute an expression at any time.

A more intricate example of conditional evaluation is as follows:

// Construct symbolic expressions
const Expression x("x");
const Expression y("y");
const Expression f_plus = (x + y)*(x + y);
// Parsing expressions from a string is also possible. Its arguments
// must have been previously declared through (and in scope).
const Expression f_minus ("(x-y)*(x-y)", true);
// Constructing a conditional expression
const SD_number_t f((x > Expression(0.0)), f_plus, f_minus);
// Value substitution
types::substitution_map substitution_map;
substitution_map[x] = Expression(1);
substitution_map[y] = Expression(2.5);
const double evaluated_f =
  f.substitute_and_evaluate<double>(substitution_map);
// Since the substituted value for x was greater than zero, we expect
// that the returned result now in evaluated_f was evaluated from
// the function f_plus.

Lastly, here is an example using symbolic differentiation:

// Construct symbolic expressions
const Expression x("x");
const Expression f("x**2", true);
// Now perform differentiation. Specifically, we differentiate the
// function "f" with respect to the symbolic variable "x".
// The result should be the expression "2*x".
const Expression df_dx = f.differentiate(x);
// Value substitution
types::substitution_map substitution_map;
substitution_map[x] = Expression(10.0);
const double evaluated_df_dx =
  evaluated_df_dx.substitute_and_evaluate<double>(substitution_map);
// We can expect the above to evaluate to "2*10" which is,
// of course, the numeric value 20.

Author: Jean-Paul Pelteret, 2019

Definition at line 177 of file symengine_number_types.h.

Constructor & Destructor Documentation

◆ Expression() [1/18]

Differentiation::SD::Expression::Expression ( )

Default constructor.

Definition at line 48 of file symengine_number_types.cc.

◆ Expression() [2/18]

Differentiation::SD::Expression::Expression ( const bool & value )

explicit

Constructor for boolean types.

Note: This constructor is marked as explicit so that there are no potential ambiguities related to implicit conversions in either user code or math functions that are loaded into the standard namespace.

Definition at line 53 of file symengine_number_types.cc.

◆ Expression() [3/18]

template<typename NumberType , typename = typename std::enable_if< std::is_arithmetic<NumberType>::value>::type>

Differentiation::SD::Expression::Expression ( const NumberType & value )

explicit

Constructor for arithmetic number types.

Note: This constructor is marked as explicit so that there are no potential ambiguities related to implicit conversions in either user code or math functions that are loaded into the standard namespace.

◆ Expression() [4/18]

template<typename NumberType , typename = typename std::enable_if< std::is_arithmetic<NumberType>::value>::type>

Differentiation::SD::Expression::Expression ( const std::complex< NumberType > & value )

explicit

Constructor for complex numbers templated on arithmetic number types.

Note: This constructor is marked as explicit so that there are no potential ambiguities related to implicit conversions in either user code or math functions that are loaded into the standard namespace.

◆ Expression() [5/18]

Differentiation::SD::Expression::Expression ( const SymEngine::integer_class & value )

Constructor for integer types.

◆ Expression() [6/18]

template<typename NumberType , typename = typename std::enable_if< std::is_integral<NumberType>::value>::type>

Differentiation::SD::Expression::Expression	(	const NumberType &	numerator,
		const NumberType &	denominator
	)

Constructor for rational types.

It is expected that both the numerator and denominator be integral types.

◆ Expression() [7/18]

Differentiation::SD::Expression::Expression ( const SymEngine::rational_class & value )

Constructor for rational types.

◆ Expression() [8/18]

Differentiation::SD::Expression::Expression	(	const Expression &	condition,
		const Expression &	expression_if_true,
		const Expression &	expression_if_false
	)

Constructor for a piecewise defined function.

The generated expression may be interpreted as the result of the teniary operator, i.e. (condition ? expression_if_true : expression_if_false).

The condition can be any expression that renders an expression that is convertible to a SymEngine::Boolean operator. This includes:

the logical operators of the deal.II Expression class
SymEngine::boolean()
SymEngine::contains()
SymEngine::Eq()
SymEngine::Ne()
SymEngine::Ge()
SymEngine::Gt()
SymEngine::Le()
SymEngine::Lt()
SymEngine::logical_and()
SymEngine::logical_nand()
SymEngine::logical_or()
SymEngine::logical_not()
SymEngine::logical_nor()
SymEngine::logical_xor()
SymEngine::logical_xnor()
...

An example of this constructor's use is as follows:

const Expression x("x");
const Expression y("y");
// Construct a conditional expression using the symbolic variables.
const Expression f ((x < Expression(0.0)), x+y, x-y);

Definition at line 68 of file symengine_number_types.cc.

◆ Expression() [9/18]

Differentiation::SD::Expression::Expression	(	const std::vector< std::pair< Expression, Expression >> &	condition_expression,
		const Expression &	expression_otherwise
	)

Constructor for a piecewise defined function.

The generated expression may be interpreted as the result of the set of nested if-elseif-else statements, i.e. (in pseudo-code)

if (condition_expression[0].first == true)
  return condition_expression[0].second;
else if (condition_expression[1].first == true)
  return condition_expression[1].second;
else if (...)
  return ...;
else
  return expression_otherwise;

if the input vector has more than 2 elements.

This variant takes the piecewise evaluated conditions and its results as the first argument, and the default return value as the second argument.

Definition at line 84 of file symengine_number_types.cc.

◆ Expression() [10/18]

Differentiation::SD::Expression::Expression ( const std::vector< std::pair< Expression, Expression >> & condition_expression )

Constructor for a piecewise defined function.

The generated expression may be interpreted as the result of the set of nested if-elseif statements, i.e. (in pseudo-code)

if (condition_expression[0].first == true)
  return condition_expression[0].second;
else if (condition_expression[1].first == true)
  return condition_expression[1].second;
else if (...)
  return ...;

if the input vector has more than 2 elements.

This variant takes only the piecewise evaluated conditions and its results. If none of the conditions are met upon evaluation then the returned result will be NaN.

Definition at line 111 of file symengine_number_types.cc.

◆ Expression() [11/18]

Differentiation::SD::Expression::Expression ( const char * symbol )

Constructor for symbolic types.

This constructor initializes a symbolic type with a character array representing its symbolic value.

Definition at line 122 of file symengine_number_types.cc.

◆ Expression() [12/18]

Differentiation::SD::Expression::Expression	(	const std::string &	symb_expr,
		const bool	parse_as_expression = `false`
	)

Constructor for symbolic types.

This constructor initializes a symbolic type with a string representing its symbolic value. If the parse_as_expression flag is false, then the symb_expr (potentially composed of multiple characters) will be interpreted as a single symbol. If the parse_as_expression flag is true, then the symb_expr will be parsed as a symbolic expression (potentially composed of multiple symbols, constants, etc.).

Definition at line 127 of file symengine_number_types.cc.

◆ Expression() [13/18]

Differentiation::SD::Expression::Expression	(	const std::string &	symbol_func,
		const types::symbol_vector &	arguments
	)

Constructor for function symbol types.

This constructor initializes a function symbol with a string representing its symbolic name.

Definition at line 145 of file symengine_number_types.cc.

◆ Expression() [14/18]

Differentiation::SD::Expression::Expression ( const Expression & rhs )

default

Copy constructor.

◆ Expression() [15/18]

Differentiation::SD::Expression::Expression ( const SymEngine::Expression & rhs )

explicit

Copy constructor.

Note: This constructor is marked as explicit to prevent any ambiguities from implicit conversion when both the deal.II and SymEngine namespaces are imported.

◆ Expression() [16/18]

Differentiation::SD::Expression::Expression ( const SymEngine::RCP< const SymEngine::Basic > & rhs )

Copy constructor.

This allows us to create our class straight from the results of SymEngine operations. This is especially important for operations like "diff", because the returned result is not primitive, but rather a set of compound operations.

◆ Expression() [17/18]

Differentiation::SD::Expression::Expression ( Expression && rhs )

default

Move constructor.

◆ Expression() [18/18]

Differentiation::SD::Expression::Expression ( SymEngine::RCP< const SymEngine::Basic > && rhs )

Move constructor.

This allows us to create our class straight from the results of SymEngine operations. This is especially important for operations like "diff", because the returned result is not primitive, but rather a set of compound operations.

◆ ~Expression()

virtual Differentiation::SD::Expression::~Expression ( )

virtualdefault

Destructor.

Member Function Documentation

◆ parse()

Expression & Differentiation::SD::Expression::parse ( const std::string & expression )

Utilities Parse an expression from a string representing a symbolic expression. This overwrites any existing value or expression that this object represents.

Definition at line 172 of file symengine_number_types.cc.

◆ print()

std::ostream & Differentiation::SD::Expression::print ( std::ostream & stream ) const

Print the value stored by this object.

Since the stored value could be one of a number of types, we leave SymEngine to cast and output the correct representation of the data.

Definition at line 180 of file symengine_number_types.cc.

◆ save()

void Differentiation::SD::Expression::save ( std::ostream & stream ) const

Save the value stored by this object to the stream.

Each expression will be saved on a new line of the stream.

Definition at line 188 of file symengine_number_types.cc.

◆ load()

void Differentiation::SD::Expression::load ( std::istream & stream )

Load the value stored in the stream into this object.

It is expected that each expression appears on its own on single line of stream.

Note: When loading a symbolic expression, it is imperative that you first create or load all of the symbolic variables used in the saved expression.

Definition at line 198 of file symengine_number_types.cc.

◆ serialize()

template<class Archive >

void Differentiation::SD::Expression::serialize	(	Archive &	archive,
		const unsigned int	version
	)

Write and read the data of this object from a stream for the purpose of serialization.

This effecively saves or loads the value stored into/out of the archive with the given version number into this object. If deserializing data, then the previous contents of this object are thrown away.

Note: When deserializing a symbolic expression, it is imperative that you first create or deserialize all of the symbolic variables used in the serialized expression.

◆ get_expression() [1/2]

const SE::Expression & Differentiation::SD::Expression::get_expression ( ) const

Return the value or expression that this class instance represents.

Definition at line 213 of file symengine_number_types.cc.

◆ get_value()

const SE::Basic & Differentiation::SD::Expression::get_value ( ) const

Return the primitive SymEngine data type that stores the value or expression represented by this object.

Definition at line 227 of file symengine_number_types.cc.

◆ get_RCP()

const SE::RCP< const SE::Basic > & Differentiation::SD::Expression::get_RCP ( ) const

Return the pointer to the primitive SymEngine data type that stores the value or expression represented by this object.

Definition at line 234 of file symengine_number_types.cc.

◆ operator=() [1/3]

Expression & Differentiation::SD::Expression::operator= ( const Expression & rhs )

Assignment operator.

Sets the data of this object's expression equal to that of the rhs object.

Definition at line 310 of file symengine_number_types.cc.

◆ operator=() [2/3]

Expression & Differentiation::SD::Expression::operator= ( Expression && rhs )

Assignment operator.

Sets the data of this object's expression equal to that of the rhs object.

Definition at line 320 of file symengine_number_types.cc.

◆ operator+=() [1/2]

Expression & Differentiation::SD::Expression::operator+= ( const Expression & rhs )

Addition assignment.

The rhs expression is added in-place to that of this object's expression.

Definition at line 337 of file symengine_number_types.cc.

◆ operator-=() [1/2]

Expression & Differentiation::SD::Expression::operator-= ( const Expression & rhs )

Subtraction assignment.

The rhs expression is subtracted in-place from that of this object's expression.

Definition at line 345 of file symengine_number_types.cc.

◆ operator*=() [1/2]

Expression & Differentiation::SD::Expression::operator*= ( const Expression & rhs )

Multiplication assignment.

This object's expression is multiplied in-place by that of the rhs expression.

Definition at line 353 of file symengine_number_types.cc.

◆ operator/=() [1/2]

Expression & Differentiation::SD::Expression::operator/= ( const Expression & rhs )

Division assignment.

This object's expression is divided in-place by that of the rhs expression.

Definition at line 361 of file symengine_number_types.cc.

◆ operator=() [3/3]

template<typename NumberType >

Expression& Differentiation::SD::Expression::operator= ( const NumberType & rhs )

Assignment operator.

Set the data of this object's expression equal to the numerical value of the rhs.

◆ operator-()

Expression Differentiation::SD::Expression::operator- ( ) const

Negation operator.

Return a the result of pre-multipying this object's expression by -1.

Note: This operation is not performed in-place.

Definition at line 330 of file symengine_number_types.cc.

◆ operator+=() [2/2]

template<typename NumberType >

Expression& Differentiation::SD::Expression::operator+= ( const NumberType & rhs )

Addition assignment.

The numerical value of the rhs is added in-place to that of this object's expression.

◆ operator-=() [2/2]

template<typename NumberType >

Expression& Differentiation::SD::Expression::operator-= ( const NumberType & rhs )

Subtraction assignment.

The numerical value of the rhs is subtracted in-place from that of this object's expression.

◆ operator*=() [2/2]

template<typename NumberType >

Expression& Differentiation::SD::Expression::operator*= ( const NumberType & rhs )

Multiplication assignment.

This object's expression is multiplied in-place by that of the numerical value of the rhs.

◆ operator/=() [2/2]

template<typename NumberType >

Expression& Differentiation::SD::Expression::operator/= ( const NumberType & rhs )

Division assignment.

This object's expression is divided in-place by that of the numerical value of the rhs.

◆ differentiate() [1/3]

Expression Differentiation::SD::Expression::differentiate ( const Expression & symbol ) const

Return the derivative of this object's expression with respect to the given symbol.

Definition at line 259 of file symengine_number_types.cc.

◆ differentiate() [2/3]

Expression Differentiation::SD::Expression::differentiate ( const SymEngine::RCP< const SymEngine::Symbol > & symbol ) const

Return the derivative of this object's expression with respect to the given symbol.

◆ differentiate() [3/3]

Expression Differentiation::SD::Expression::differentiate ( const SymEngine::RCP< const SymEngine::Basic > & symbol ) const

Return the derivative of this object's expression with respect to the potential symbol.

◆ substitute() [1/3]

Expression Differentiation::SD::Expression::substitute ( const types::substitution_map & substitution_values ) const

Perform substitution of all symbols found in this object's expression that match a key in the substitution_values map.

Note: The replacement value (the entry in the substitution_values that is paired with a key) need not necessarily be numerical, but may also be another symbolic type.; With dictionary substitution, partial substitution is allowed (i.e. an incomplete substitution map can be used and the return type can be symbolic).

Definition at line 284 of file symengine_number_types.cc.

◆ substitute() [2/3]

Expression Differentiation::SD::Expression::substitute	(	const Expression &	symbol,
		const Expression &	value
	)		const

Perform substitution of all symbols found in this object's expression that match the symbol. Each symbol will be substituted with the given value.

Note: With dictionary substitution, partial substitution is allowed (i.e. an incomplete substitution map can be used and the return type can be symbolic).

Definition at line 293 of file symengine_number_types.cc.

◆ substitute() [3/3]

template<typename NumberType >

Expression Differentiation::SD::Expression::substitute	(	const Expression &	symbol,
		const NumberType &	value
	)		const

Perform substitution of all symbols found in this object's expression that match the symbol. Each symbol will be substituted with the given value.

Note: With dictionary substitution, partial substitution is allowed (i.e. an incomplete substitution map can be used and the return type can be symbolic).

◆ substitute_and_evaluate()

template<typename ReturnType >

ReturnType Differentiation::SD::Expression::substitute_and_evaluate ( const types::substitution_map & substitution_values ) const

Full substitution and evaluation. This creates a Expression by symbol substitution and then immediately computes its numerical value.

Note: All symbols must be resolved by the substitution map in order for this function to return successfully.

◆ operator ResultType()

template<typename ResultType >

Differentiation::SD::Expression::operator ResultType ( ) const

explicit

Conversion operator for real integer or floating point values, and complex integer or floating point values.

Note: This function is marked explicit so that the conversion must be performed using a static_cast. In normal use, one would have expected (Expression)*(double) –> (Expression) If this function were not marked as explicit, then we could potentially have (Expression)*(double) –> (double) So, to get out a value on needs to do the following:

const NumberType val = static_cast<NumberType>(Expression);

or, probably less desirably,

const NumberType val = NumberType(Expression);

Note: If the underlying number is a custom type (i.e. encapsulated by a NumberWrapper), then it is necessary to derive a new class from Expression and define a specialized conversion operator that calls an Evaluator that is specialized for this custom number type. This could be achieved with an overriding conversion function in the base class, for example:

  class MyNumber : public Expression
  {
    ...
    template <typename ResultType>
    explicit operator ResultType() const
    {
      if (this->get_value()->get_type_code() ==
SymEngine::NUMBER_WRAPPER)
      {
        // Implement custom evaluation function
        const ResultType result = ...;
        return result;
      }
      else
        // Call base class conversion operator
        return Expression::operator ResultType();
    }
  }

◆ operator const SymEngine::Expression &()

Differentiation::SD::Expression::operator const SymEngine::Expression & ( ) const

explicit

Conversion operator that returns the value or expression that this class instance represents.

◆ operator const SymEngine::RCP< const SymEngine::Basic > &()

Differentiation::SD::Expression::operator const SymEngine::RCP< const SymEngine::Basic > & ( ) const

Conversion operator that returns a SymEngine reference counted pointer to the fundamental type.

◆ get_expression() [2/2]

SE::Expression & Differentiation::SD::Expression::get_expression ( )

protected

Return the value or expression that this class instance represents.

Definition at line 220 of file symengine_number_types.cc.

Member Data Documentation

◆ expression

SymEngine::Expression Differentiation::SD::Expression::expression

private

The value or expression that this instance of this class is to represent.

Definition at line 800 of file symengine_number_types.h.

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

deal.II/differentiation/sd/symengine_number_types.h
source/differentiation/sd/symengine_number_types.cc

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Expression() [1/18]

◆ Expression() [2/18]

◆ Expression() [3/18]

◆ Expression() [4/18]

◆ Expression() [5/18]

◆ Expression() [6/18]

◆ Expression() [7/18]

◆ Expression() [8/18]

◆ Expression() [9/18]

◆ Expression() [10/18]

◆ Expression() [11/18]

◆ Expression() [12/18]

◆ Expression() [13/18]

◆ Expression() [14/18]

◆ Expression() [15/18]

◆ Expression() [16/18]

◆ Expression() [17/18]

◆ Expression() [18/18]

◆ ~Expression()

Member Function Documentation

◆ parse()

◆ print()

◆ save()

◆ load()

◆ serialize()

◆ get_expression() [1/2]

◆ get_value()

◆ get_RCP()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator+=() [1/2]

◆ operator-=() [1/2]

◆ operator*=() [1/2]

◆ operator/=() [1/2]

◆ operator=() [3/3]

◆ operator-()

◆ operator+=() [2/2]

◆ operator-=() [2/2]

◆ operator*=() [2/2]

◆ operator/=() [2/2]

◆ differentiate() [1/3]

◆ differentiate() [2/3]

◆ differentiate() [3/3]

◆ substitute() [1/3]

◆ substitute() [2/3]

◆ substitute() [3/3]

◆ substitute_and_evaluate()

◆ operator ResultType()

◆ operator const SymEngine::Expression &()

◆ operator const SymEngine::RCP< const SymEngine::Basic > &()

◆ get_expression() [2/2]

Member Data Documentation

◆ expression