Reference documentation for deal.II version Git c9feb145b3 20210301 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 pseudocode 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 reoptimize 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 11 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 11 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 dictionarybased 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.