![]() |
Reference documentation for deal.II version 9.6.0
|
#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 &&) noexcept=default | |
~BatchOptimizer ()=default | |
void | copy_from (const BatchOptimizer &other) |
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 |
ReturnType | extract (const Expression &func, const std::vector< ReturnType > &cached_evaluation) const |
std::vector< ReturnType > | extract (const std::vector< Expression > &funcs, const std::vector< ReturnType > &cached_evaluation) const |
template<int rank, int dim> | |
Tensor< rank, dim, ReturnType > | extract (const Tensor< rank, dim, Expression > &funcs, const std::vector< ReturnType > &cached_evaluation) const |
template<int rank, int dim> | |
SymmetricTensor< rank, dim, ReturnType > | extract (const SymmetricTensor< rank, dim, Expression > &funcs, const std::vector< ReturnType > &cached_evaluation) const |
Private Types | |
using | map_dependent_expression_to_vector_entry_t |
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 1433 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 2063 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 35 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 45 of file symengine_optimizer.cc.
Differentiation::SD::BatchOptimizer< ReturnType >::BatchOptimizer | ( | const BatchOptimizer< ReturnType > & | other | ) |
Copy constructor.
other
optimizer instance are not copied over. It is therefore necessary to re-optimize the data stored in this class, and it is possible to do so with a different optimization scheme. Definition at line 56 of file symengine_optimizer.cc.
|
defaultnoexcept |
Move constructor.
|
default |
Destructor.
void Differentiation::SD::BatchOptimizer< ReturnType >::copy_from | ( | const BatchOptimizer< ReturnType > & | other | ) |
Duplicate the data stored in an other
BatchOptimizer instance.
other
optimizer instance are not copied over. It is therefore necessary to call optimize() before it is possible to substitute() values and evaluate() data. One may, however, still extract() values using this
optimizer instance if those results are stored elsewhere. Definition at line 72 of file symengine_optimizer.cc.
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 165 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 192 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 203 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 224 of file symengine_optimizer.cc.
SD::types::symbol_vector Differentiation::SD::BatchOptimizer< ReturnType >::get_independent_symbols | ( | ) | const |
Return a vector of symbols that have been registered as independent variables.
Definition at line 235 of file symengine_optimizer.cc.
std::size_t Differentiation::SD::BatchOptimizer< ReturnType >::n_independent_variables | ( | ) | 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 244 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 253 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 266 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 280 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 | ( | ) | const |
Return a vector of expressions that have been registered as dependent variables.
Definition at line 291 of file symengine_optimizer.cc.
std::size_t Differentiation::SD::BatchOptimizer< ReturnType >::n_dependent_variables | ( | ) | 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 300 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 89 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 112 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 121 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 130 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 317 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 139 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 394 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 433 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 444 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 458 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 156 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. If these results are stored elsewhere, and you want to use this optimizer to extract components of the cached results then you can make use of the extract() functions listed below.
These values were computed by substituting a substitution_values
map during substitute() call.
Definition at line 528 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 636 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 668 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.
ReturnType Differentiation::SD::BatchOptimizer< ReturnType >::extract | ( | const Expression & | func, |
const std::vector< ReturnType > & | cached_evaluation ) const |
Returns the result of a value substitution into the optimized counterpart of func
. This function fetches that one value stored in the cached_evaluation
vector. This vector is, most typically, first attained by a call to the evaluate() variant that takes no arguments.
Definition at line 543 of file symengine_optimizer.cc.
std::vector< ReturnType > Differentiation::SD::BatchOptimizer< ReturnType >::extract | ( | const std::vector< Expression > & | funcs, |
const std::vector< ReturnType > & | cached_evaluation ) const |
Returns the result of a value substitution into the optimized counterpart of funcs
. This function fetches that subset of values stored in the cached_evaluation
vector. This vector is, most typically, first attained by a call to the evaluate() variant that takes no arguments.
Definition at line 651 of file symengine_optimizer.cc.
Tensor< rank, dim, ReturnType > Differentiation::SD::BatchOptimizer< ReturnType >::extract | ( | const Tensor< rank, dim, Expression > & | funcs, |
const std::vector< ReturnType > & | cached_evaluation ) const |
Returns the result of a tensor value substitution into the optimized counterpart of funcs
. This function fetches those tensor components stored in the cached_evaluation
vector. This vector is, most typically, first attained by a call to the evaluate() variant that takes no arguments.
SymmetricTensor< rank, dim, ReturnType > Differentiation::SD::BatchOptimizer< ReturnType >::extract | ( | const SymmetricTensor< rank, dim, Expression > & | funcs, |
const std::vector< ReturnType > & | cached_evaluation ) const |
Returns the result of a tensor value substitution into the optimized counterpart of funcs
. This function fetches those symmetric tensor components stored in the cached_evaluation
vector. This vector is, most typically, first attained by a call to the evaluate() variant that takes no arguments.
|
private |
A check to see if a function is exactly equal to one of the logical results of a differentiation operation.
Definition at line 683 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 693 of file symengine_optimizer.cc.
|
private |
Register a single symbol that represents a dependent variable.
Definition at line 726 of file symengine_optimizer.cc.
|
private |
Register a collection of symbols that represent dependent variables.
Definition at line 754 of file symengine_optimizer.cc.
|
private |
Create an instance of the selected optimizer.
Definition at line 788 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 471 of file symengine_optimizer.cc.
|
private |
The optimization methods that is to be employed.
Definition at line 1997 of file symengine_optimizer.h.
|
private |
The optimization flags that indicate which expression manipulation mechanisms are to be employed.
Definition at line 2003 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 2014 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 2021 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 2053 of file symengine_optimizer.h.
|
mutableprivate |
A map indicating which dependent variable is associated with which entry in the output vector.
Definition at line 2072 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 2080 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 2090 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 2096 of file symengine_optimizer.h.