![]() |
Reference documentation for deal.II version Git c9feb145b3 2021-03-01 21:22:52 +0100
|
#include <deal.II/differentiation/sd/symengine_optimizer.h>
Public Member Functions | |
BatchOptimizer () | |
BatchOptimizer (const enum OptimizerType &optimization_method, const enum OptimizationFlags &optimization_flags=OptimizationFlags::optimize_all) | |
BatchOptimizer (const BatchOptimizer &other) | |
BatchOptimizer (BatchOptimizer &&)=default | |
~BatchOptimizer ()=default | |
template<typename Stream > | |
void | print (Stream &stream, const bool print_cse=false) const |
template<class Archive > | |
void | save (Archive &archive, const unsigned int version) const |
template<class Archive > | |
void | load (Archive &archive, const unsigned int version) |
template<class Archive > | |
void | serialize (Archive &archive, const unsigned int version) |
Independent variables | |
void | register_symbols (const types::substitution_map &substitution_map) |
void | register_symbols (const SymEngine::map_basic_basic &substitution_map) |
void | register_symbols (const types::symbol_vector &symbols) |
void | register_symbols (const SymEngine::vec_basic &symbols) |
types::symbol_vector | get_independent_symbols () const |
std::size_t | n_independent_variables () const |
Dependent variables | |
void | register_function (const Expression &function) |
template<int rank, int dim> | |
void | register_function (const Tensor< rank, dim, Expression > &function_tensor) |
template<int rank, int dim> | |
void | register_function (const SymmetricTensor< rank, dim, Expression > &function_tensor) |
void | register_functions (const types::symbol_vector &functions) |
void | register_functions (const SymEngine::vec_basic &functions) |
template<typename T > | |
void | register_functions (const std::vector< T > &functions) |
template<typename T , typename... Args> | |
void | register_functions (const T &functions, const Args &... other_functions) |
const types::symbol_vector & | get_dependent_functions () const |
std::size_t | n_dependent_variables () const |
Optimization | |
void | set_optimization_method (const enum OptimizerType &optimization_method, const enum OptimizationFlags &optimization_flags=OptimizationFlags::optimize_all) |
enum OptimizerType | optimization_method () const |
enum OptimizationFlags | optimization_flags () const |
bool | use_symbolic_CSE () const |
void | optimize () |
bool | optimized () const |
Symbol substitution | |
void | substitute (const types::substitution_map &substitution_map) const |
void | substitute (const SymEngine::map_basic_basic &substitution_map) const |
void | substitute (const types::symbol_vector &symbols, const std::vector< ReturnType > &values) const |
void | substitute (const SymEngine::vec_basic &symbols, const std::vector< ReturnType > &values) const |
bool | values_substituted () const |
Evaluation / data extraction | |
const std::vector< ReturnType > & | evaluate () const |
ReturnType | evaluate (const Expression &func) const |
std::vector< ReturnType > | evaluate (const std::vector< Expression > &funcs) const |
template<int rank, int dim> | |
Tensor< rank, dim, ReturnType > | evaluate (const Tensor< rank, dim, Expression > &funcs) const |
template<int rank, int dim> | |
SymmetricTensor< rank, dim, ReturnType > | evaluate (const SymmetricTensor< rank, dim, Expression > &funcs) const |
Private Types | |
using | map_dependent_expression_to_vector_entry_t = std::map< SD::Expression, std::size_t, SD::types::internal::ExpressionKeyLess > |
Private Member Functions | |
bool | is_valid_nonunique_dependent_variable (const SD::Expression &function) const |
bool | is_valid_nonunique_dependent_variable (const SymEngine::RCP< const SymEngine::Basic > &function) const |
void | register_scalar_function (const SD::Expression &function) |
void | register_vector_functions (const types::symbol_vector &functions) |
void | create_optimizer (std::unique_ptr< SymEngine::Visitor > &optimizer) |
void | substitute (const std::vector< ReturnType > &substitution_values) const |
Private Attributes | |
enum OptimizerType | method |
enum OptimizationFlags | flags |
types::substitution_map | independent_variables_symbols |
types::symbol_vector | dependent_variables_functions |
std::vector< ReturnType > | dependent_variables_output |
map_dependent_expression_to_vector_entry_t | map_dep_expr_vec_entry |
std::unique_ptr< SymEngine::Visitor > | optimizer |
bool | ready_for_value_extraction |
bool | has_been_serialized |
A class that facilitates the optimization of symbol expressions.
This expression will be optimized by this class; that is to say that the code path taken to substitute the set of (independent) symbols into a collection of (dependent) symbolic functions will be optimized using a chosen approach.
This snippet of pseudo-code describes the general usage of this class:
Since the call to optimize() may be quite costly, there are a few "best practices" that can be adopted in order to mitigate this cost as much as possible:
ReturnType | The number type that is to be returned after value substitution and evaluation. Floating point and complex numbers are currently supported. |
ReturnType
and optimization method are selected, then an error will be thrown at run time. Definition at line 91 of file symengine_optimizer.h.
|
private |
A map type used to indicate which dependent variable is associated with which entry in the output vector.
Definition at line 1999 of file symengine_optimizer.h.
Differentiation::SD::BatchOptimizer< ReturnType >::BatchOptimizer | ( | ) |
Default constructor.
By default, dictionary substitution will be selected when this constructor is called. In order to select a specific optimization approach, a call to set_optimization_method() is necessary.
Definition at line 36 of file symengine_optimizer.cc.
Differentiation::SD::BatchOptimizer< ReturnType >::BatchOptimizer | ( | const enum OptimizerType & | optimization_method, |
const enum OptimizationFlags & | optimization_flags = OptimizationFlags::optimize_all |
||
) |
Constructor.
[in] | optimization_method | The optimization method that is to be employed. |
[in] | optimization_flags | The optimization flags that indicate which expression manipulation mechanisms are to be employed. |
optimization_method
is not implemented for the required ReturnType
, or the desired feature is not active, then an error will be thrown. Currently the LLVM optimization method is not compatible with complex numbers. Definition at line 46 of file symengine_optimizer.cc.
Differentiation::SD::BatchOptimizer< ReturnType >::BatchOptimizer | ( | const BatchOptimizer< ReturnType > & | other | ) |
Copy constructor
The copy_initialized
flag, which is set to true
by default, determines whether or not all of the optimized data is copied over from the other
optimizer instance. Only with the flag set to false
is it possible to re-optimize the data stored in this class with a different optimization scheme.
Definition at line 57 of file symengine_optimizer.cc.
|
default |
Move constructor.
|
default |
Destructor.
void Differentiation::SD::BatchOptimizer< ReturnType >::print | ( | Stream & | stream, |
const bool | print_cse = false |
||
) | const |
Print some information on state of the internal data structures stored in the class.
Stream | The type for the output stream. |
stream | The output stream to print to. |
print_cse | A flag to indicate whether or not all common subexpressions should be printed to the stream . |
void Differentiation::SD::BatchOptimizer< ReturnType >::save | ( | Archive & | archive, |
const unsigned int | version | ||
) | const |
Write the data of this object from a stream for the purpose of serialization using the BOOST serialization library.
This effectively saves the value stored into the archive
with the given version
number into this object.
void Differentiation::SD::BatchOptimizer< ReturnType >::load | ( | Archive & | archive, |
const unsigned int | version | ||
) |
Read the data of this object from a stream for the purpose of serialization using the BOOST serialization library.
This effectively loads the value stored out of the archive
with the given version
number into this object. In doing so, the previous contents of this object are thrown away.
void Differentiation::SD::BatchOptimizer< ReturnType >::serialize | ( | Archive & | archive, |
const unsigned int | version | ||
) |
Write and read the data of this object from a stream for the purpose of serialization using the BOOST serialization library.
This effectively 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.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_symbols | ( | const types::substitution_map & | substitution_map | ) |
Register a collection of symbols that represents an independent variable. These symbols are stored as the key
to the substitution_map
.
Definition at line 148 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_symbols | ( | const SymEngine::map_basic_basic & | substitution_map | ) |
Register a collection of symbols that represents an independent variable. These symbols are stored as the key
to the substitution_map
.
Definition at line 175 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_symbols | ( | const types::symbol_vector & | symbols | ) |
Register a collection of symbols that represents independent variables.
substitution_values
vector or map matches the internal ordering of the registered symbols. This function is therefore typically used in conjunction with the substitute() function that takes in a vector of values. With this pair of functions to the class interface, the management of symbol ordering is maintained by the user. Definition at line 186 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_symbols | ( | const SymEngine::vec_basic & | symbols | ) |
Register a collection of symbols that represents independent variables.
substitution_values
vector or map matches the internal ordering of the registered symbols. This function is therefore typically used in conjunction with the substitute() function that takes in a vector of values. With this pair of functions to the class interface, the management of symbol ordering is maintained by the user. Definition at line 207 of file symengine_optimizer.cc.
SD::types::symbol_vector Differentiation::SD::BatchOptimizer< ReturnType >::get_independent_symbols | ( | void | ) | const |
Return a vector of symbols that have been registered as independent variables.
Definition at line 218 of file symengine_optimizer.cc.
std::size_t Differentiation::SD::BatchOptimizer< ReturnType >::n_independent_variables | ( | void | ) | const |
The number of independent variables that this optimizer will recognize. This is equal to the number of unique symbols passed to this class instance through the register_symbols() function.
Definition at line 227 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_function | ( | const Expression & | function | ) |
Register a scalar symbolic expression that represents a dependent variable.
Definition at line 236 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_function | ( | const Tensor< rank, dim, Expression > & | function_tensor | ) |
Register a tensor of symbolic expressions that represents a dependent variable.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_function | ( | const SymmetricTensor< rank, dim, Expression > & | function_tensor | ) |
Register a symmetric tensor of symbolic expressions that represents a dependent variable.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_functions | ( | const types::symbol_vector & | functions | ) |
Register a collection of symbolic expressions that represent dependent variables.
Definition at line 249 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_functions | ( | const SymEngine::vec_basic & | functions | ) |
Register a collection of symbolic expressions that represent multiple dependent variables.
Definition at line 263 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::register_functions | ( | const std::vector< T > & | functions | ) |
Register a collection of symbolic expressions that represent multiple dependent variables.
T | A compatible type that may be used to represent a single dependent variable. This includes scalar Expressions, Tensors of Expressions and SymmetricTensors of Expressions. |
functions | A vector of symbolic dependent variables. |
void Differentiation::SD::BatchOptimizer< ReturnType >::register_functions | ( | const T & | functions, |
const Args &... | other_functions | ||
) |
Register a collection of symbolic expressions that represent dependent variables.
T | A compatible type that may be used to represent a single dependent variable. This includes scalar Expressions, Tensors of Expressions, SymmetricTensors of Expressions, and std::vector s of Expressions. |
Args | A variadic template that represents a collection of any compatible symbolic dependent variable types. |
functions | One or more symbolic dependent variables. |
other_functions | An arbitrary collection of symbolic dependent variables. |
const SD::types::symbol_vector & Differentiation::SD::BatchOptimizer< ReturnType >::get_dependent_functions | ( | void | ) | const |
Return a vector of expressions that have been registered as dependent variables.
Definition at line 274 of file symengine_optimizer.cc.
std::size_t Differentiation::SD::BatchOptimizer< ReturnType >::n_dependent_variables | ( | void | ) | const |
The number of dependent symbolic expressions that this optimizer will optimize. This is equal to the number of unique symbolic functions / expressions passed to this class instance through the register_functions() method.
Definition at line 283 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::set_optimization_method | ( | const enum OptimizerType & | optimization_method, |
const enum OptimizationFlags & | optimization_flags = OptimizationFlags::optimize_all |
||
) |
Select the optimization_method
for the batch optimizer to employ, in conjunction with the optimization_flags
.
It is required that the this class instance is not yet optimized, i.e. that the optimize() method has not yet been called.
method
is not implemented for the required ReturnType
, or the desired feature is not active, then a safe default will be selected. Definition at line 72 of file symengine_optimizer.cc.
enum OptimizerType Differentiation::SD::BatchOptimizer< ReturnType >::optimization_method | ( | ) | const |
Return the optimization method that has been selected for use.
Definition at line 95 of file symengine_optimizer.cc.
enum OptimizationFlags Differentiation::SD::BatchOptimizer< ReturnType >::optimization_flags | ( | ) | const |
Return the optimization flags that have been selected for use.
Definition at line 104 of file symengine_optimizer.cc.
bool Differentiation::SD::BatchOptimizer< ReturnType >::use_symbolic_CSE | ( | ) | const |
State whether the internal selection of optimization methods and flags will render an optimizer that uses common subexpression elimination (CSE).
Definition at line 113 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::optimize | ( | ) |
Perform the optimization of all registered dependent functions using the registered symbols.
Definition at line 300 of file symengine_optimizer.cc.
bool Differentiation::SD::BatchOptimizer< ReturnType >::optimized | ( | ) | const |
Returns a flag which indicates whether the optimize() function has been called and the class is finalized.
Definition at line 122 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::substitute | ( | const types::substitution_map & | substitution_map | ) | const |
Perform batch substitution of all of the registered symbols into the registered functions. The result is cached and can be extracted by calls to evaluate().
substitution_map
overwrites any previously computed results. Definition at line 377 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::substitute | ( | const SymEngine::map_basic_basic & | substitution_map | ) | const |
Perform batch substitution of all of the registered symbols into the registered functions. The result is cached and can be extracted by calls to evaluate().
substitution_map
overwrites any previously computed results. Definition at line 416 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::substitute | ( | const types::symbol_vector & | symbols, |
const std::vector< ReturnType > & | values | ||
) | const |
Perform batch substitution of all of the registered symbols into the registered functions. The result is cached and can be extracted by calls to evaluate(). It is expected that there is a 1-1 correspondence between each of the symbols
and values
.
values
overwrites any previously computed results. Definition at line 427 of file symengine_optimizer.cc.
void Differentiation::SD::BatchOptimizer< ReturnType >::substitute | ( | const SymEngine::vec_basic & | symbols, |
const std::vector< ReturnType > & | values | ||
) | const |
Perform batch substitution of all of the registered symbols into the registered functions. The result is cached and can be extracted by calls to evaluate(). It is expected that there is a 1-1 correspondence between each of the symbols
and values
.
values
overwrites any previously computed results. Definition at line 441 of file symengine_optimizer.cc.
bool Differentiation::SD::BatchOptimizer< ReturnType >::values_substituted | ( | ) | const |
Returns a flag to indicate whether the substitute() function has been called and if there are meaningful values that will be returned upon evaluation.
Definition at line 139 of file symengine_optimizer.cc.
const std::vector< ReturnType > & Differentiation::SD::BatchOptimizer< ReturnType >::evaluate | ( | ) | const |
Returns the result of a value substitution into the optimized counterpart of all dependent functions. This function fetches all of those cached values.
These values were computed by substituting a substitution_values
map during substitute() call.
Definition at line 511 of file symengine_optimizer.cc.
ReturnType Differentiation::SD::BatchOptimizer< ReturnType >::evaluate | ( | const Expression & | func | ) | const |
Returns the result of a value substitution into the optimized counterpart of func
. This function fetches that one cached value.
This value was computed by substituting a substitution_values
map during substitute() call.
Definition at line 526 of file symengine_optimizer.cc.
std::vector< ReturnType > Differentiation::SD::BatchOptimizer< ReturnType >::evaluate | ( | const std::vector< Expression > & | funcs | ) | const |
Returns the result of a value substitution into the optimized counterpart of funcs
. This function fetches that subset of cached values.
This value was computed by substituting a substitution_values
map during substitute() call.
Definition at line 623 of file symengine_optimizer.cc.
Tensor<rank, dim, ReturnType> Differentiation::SD::BatchOptimizer< ReturnType >::evaluate | ( | const Tensor< rank, dim, Expression > & | funcs | ) | const |
Returns the result of a tensor value substitution into the optimized counterpart of funcs
. This function fetches those cached tensor components.
This value was computed by substituting a substitution_values
map during substitute() call.
SymmetricTensor<rank, dim, ReturnType> Differentiation::SD::BatchOptimizer< ReturnType >::evaluate | ( | const SymmetricTensor< rank, dim, Expression > & | funcs | ) | const |
Returns the result of a tensor value substitution into the optimized counterpart of funcs
. This function fetches those cached symmetric tensor components.
This value was computed by substituting a substitution_values
map during substitute() call.
|
private |
A check to see if a function is exactly equal to one of the logical results of a differentiation operation.
Definition at line 639 of file symengine_optimizer.cc.
|
private |
A check to see if a function is exactly equal to one of the logical results of a differentiation operation.
Definition at line 649 of file symengine_optimizer.cc.
|
private |
Register a single symbol that represents a dependent variable.
Definition at line 682 of file symengine_optimizer.cc.
|
private |
Register a collection of symbols that represent dependent variables.
Definition at line 710 of file symengine_optimizer.cc.
|
private |
Create an instance of the selected optimizer.
Definition at line 744 of file symengine_optimizer.cc.
|
private |
Perform batch substitution of all of the registered symbols into the registered functions. The result is cached and can be extracted by calls to evaluate().
substitution_values
overwrites any previously computed results.substitution_values
vector matches the internal ordering of the registered symbols. This function is therefore typically used in conjunction with the register_symbols() function that takes in a vector of symbols. With this pair of functions to the class interface, the management of symbol ordering is maintained by the user. Definition at line 454 of file symengine_optimizer.cc.
|
private |
The optimization methods that is to be employed.
Definition at line 1930 of file symengine_optimizer.h.
|
private |
The optimization flags that indicate which expression manipulation mechanisms are to be employed.
Definition at line 1936 of file symengine_optimizer.h.
|
private |
A map that represents the symbols that form the set of independent variables upon which optimized symbolic expressions are to be based.
Definition at line 1947 of file symengine_optimizer.h.
|
private |
A set of symbolic expressions to be optimized. It is required that the symbols on which these dependent functions are based are registered in the independent_variables_symbols
map.
Definition at line 1954 of file symengine_optimizer.h.
|
mutableprivate |
The output of substituting symbolic values with floating point values through the use of the optimizer
.
It
is necessary to use this intermediate storage mechanism to store the result of a substitution sweep as some optimizers work on all symbolic expressions in a single batch. In this way they can employ methods such as common subexpression elimination to minimize the number of terms evaluated across all symbolic functions.
This variable is marked as mutable. This facilitates the substitution functionality being used in logically constant get_*
functions.
Definition at line 1986 of file symengine_optimizer.h.
|
mutableprivate |
A map indicating which dependent variable is associated with which entry in the output vector.
Definition at line 2005 of file symengine_optimizer.h.
|
mutableprivate |
A pointer to an instance of an optimizer that will be used to reformulate the substitution of symbolic expressions in a manner that is more efficient than plain dictionary-based approach.
Definition at line 2013 of file symengine_optimizer.h.
|
mutableprivate |
A flag to record whether or not substitution has taken place and values can now be extracted.
get_*
functions. Definition at line 2023 of file symengine_optimizer.h.
|
mutableprivate |
A flag to record whether or not this class instance has been serialized in the past.
Definition at line 2029 of file symengine_optimizer.h.