CoDiPack  2.2.0
A Code Differentiation Package
SciComp TU Kaiserslautern
Loading...
Searching...
No Matches
codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation > Struct Template Reference

Helper class for the implementation of an external function in CoDiPack. More...

#include <externalFunctionHelper.hpp>

Inheritance diagram for codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >:

Public Types

using ForwardFunc
 Function interface for the forward AD call of an external function.
 
using Identifier = typename Type::Identifier
 See LhsExpressionInterface.
 
using PrimalFunc = void (*)(Real const* x, size_t m, Real* y, size_t n, ExternalFunctionUserData* d)
 Function interface for the primal call of an external function.
 
using Real = typename Type::Real
 See LhsExpressionInterface.
 
using ReverseFunc
 Function interface for the reverse AD call of an external function.
 
using Synchronization = T_Synchronization
 See ExternalFunctionHelper.
 
using Tape = typename Type::Tape
 See LhsExpressionInterface.
 
using ThreadInformation = T_ThreadInformation
 See ExternalFunctionHelper.
 
using Type = T_Type
 See ExternalFunctionHelper.
 

Public Member Functions

void addInput (Type const &input)
 Add an input value.
 
void addOutput (Type &output)
 Add an output value.
 
void addToTape (ReverseFunc reverseFunc, ForwardFunc forwardFunc=nullptr, PrimalFunc primalFunc=nullptr)
 Add the external function to the tape.
 
template<typename Data >
void addUserData (Data const &data)
 Add user data. See ExternalFunctionUserData for details.
 
void callPrimalFunc (PrimalFunc func)
 
template<typename FuncObj , typename... Args>
void callPrimalFuncWithADType (FuncObj &func, Args &&... args)
 
void disableInputPrimalStore ()
 Do not store primal input values. In function calls, pointers to primal inputs will be null.
 
void disableOutputPrimalStore ()
 Do not store primal output values. In function calls, pointers to primal outputs will be null.
 
void disableRenewOfPrimalValues ()
 Do not update the inputs and outputs from the primal values of the tape. Has no effect on Jacobian tapes.
 
void enableReallocationOfPrimalValueVectors ()
 
 ExternalFunctionHelper (bool primalFuncUsesADType=false)
 Constructor.
 
ExternalFunctionUserDatagetExternalFunctionUserData ()
 
 ~ExternalFunctionHelper ()
 Destructor.
 

Protected Attributes

EvalData * data
 External function data.
 
bool getPrimalValuesFromPrimalValueVector
 
std::vector< Type * > outputValues
 References to output values.
 
bool reallocatePrimalVectors
 
bool storeInputOutputForPrimalEval
 If a primal call with a self-implemented function will be done.
 
bool storeInputPrimals
 If input primals are stored. Can be disabled by the user.
 
bool storeOutputPrimals
 If output primals are stored. Can be disabled by the user.
 
std::vector< Realy
 Shared vector of output variables.
 

Detailed Description

template<typename T_Type, typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
struct codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >

Helper class for the implementation of an external function in CoDiPack.

The class helps the user to handle parts where the CoDiPack types cannot be applied or where a more efficient gradient computation is available.

The procedure of pushing an external function with the helper is as follows.

  1. All function inputs and outputs are specified.
  2. The primal function is called. There are two modes for this, which are explained below.
  3. The manual reverse implementation is provided to the helper, which embeds it into the tape and prepares itself for the next external function push.

The first mode of operation assumes that the primal function has an implementation without a CoDiPack type. To use this mode, invoke the primal function via callPrimalFunc. An example is:

eh.addInput(x);
eh.addOutput(y[1]);
eh.callPrimalFunc(func_prim);
eh.addToTape(func_rev);

The second mode of operation assumes that the primal function is evaluated with the CoDiPack type. To use it, the helper's constructor has to be called with the option true and the primal call is performed via callPrimalFuncWithADType. An example is:

ehP.addInput(x);
ehP.addOutput(y[2]);
ehP.callPrimalFuncWithADType(func_wrap<Real>, x, y[2]);
ehP.addToTape(func_rev);

The function implementations must follow the definitions of ExternalFunctionHelper::ReverseFunc, ExternalFunctionHelper::ForwardFunc and ExternalFunctionHelper::PrimalFunc, with an exception for the latter if the second mode is used. The implementations from the examples above are:

template<typename Type>
Type func(Type const& v) {
return 42.0 * v * v;
}
template<typename Type>
void func_wrap(Type const& v, Type& w) {
w = func(v);
}
void func_prim(double const* x, size_t m, double* y, size_t n, codi::ExternalFunctionUserData* d) {
y[0] = 42.0 * x[0] * x[0];
}
void func_rev(double const* x, double* x_b, size_t m, double const* y, double const* y_b, size_t n, codi::ExternalFunctionUserData* d) {
x_b[0] = y_b[0] * x[0] * 84.0;
}

The ExternalFunctionHelper works with all tapes. It is also able to handle situations where the tape is currently not recording. All necessary operations are performed in such a case but no external function is recorded. If disableRenewOfPrimalValues is called, primal values are no longer recovered from the tape. If enableReallocationOfPrimalValueVectors is called, the primal values vector for the input and output values are reallocated each time the external function is called. They are freed afterwards, reducing the memory footprint.

The storing of primal inputs and outputs can be disabled. Outputs can be discarded if they are recomputed in the derivative computation or if the derivative does not depend on them. Inputs can be discarded if the derivative does not depend on them.

By means of the T_Synchronization and T_ThreadInformation template parameters, a thread-safe external function helper can be instantiated. The default instantiation yields an external function helper ready for serial applications, either in serial code or locally within threads. Non-default instantiations are required for external functions that multiple threads jointly work on. Shared data, such as external function inputs and outputs, are always prepared and finalized by one thread only, whereas the external function is worked on by all threads. All threads are synchronized between serial and parallel parts. The synchronization pattern can be seen in the implementation of ExternalFunctionHelper::addToTape, where the workflow is annotated with comments.

Template Parameters
T_TypeThe CoDiPack type that is used outside of the external function.
T_SynchronizationSynchronization facilities for thread-safety. See SynchronizationInterface.
T_ThreadInformationThread information facilities. See ThreadInformationInterface.

Member Typedef Documentation

◆ ForwardFunc

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
using codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::ForwardFunc
Initial value:
void (*)(Real const* x, Real const* x_d, size_t m, Real* y, Real* y_d, size_t n,
ExternalFunctionUserData* d)
Represents a concrete lvalue in the CoDiPack expression tree.
Definition activeType.hpp:52
std::vector< Real > y
Shared vector of output variables.
Definition externalFunctionHelper.hpp:397

Function interface for the forward AD call of an external function.

◆ ReverseFunc

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
using codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::ReverseFunc
Initial value:
void (*)(Real const* x, Real* x_b, size_t m, Real const* y, Real const* y_b, size_t n,
ExternalFunctionUserData* d)

Function interface for the reverse AD call of an external function.

Member Function Documentation

◆ callPrimalFunc()

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
void codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::callPrimalFunc ( PrimalFunc func)
inline

Call the primal function with the values extracted from the inputs. The output values are set on the specified outputs and registered as outputs of this external functions.

◆ callPrimalFuncWithADType()

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
template<typename FuncObj , typename... Args>
void codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::callPrimalFuncWithADType ( FuncObj & func,
Args &&... args )
inline

This is intended for primal functions that are implemented with the AD type. It is ensured that no data is recorded on the tape. All output values are registered as outputs of this external function.

◆ enableReallocationOfPrimalValueVectors()

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
void codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::enableReallocationOfPrimalValueVectors ( )
inline

Reallocates the primal value vectors for the input and output values every time the external function is called. The vectors are freed after the external function is finished. Has no effect on Jacobian tapes.

◆ getExternalFunctionUserData()

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
ExternalFunctionUserData & codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::getExternalFunctionUserData ( )
inline

Get a reference to the full user data created for this external function. See ExternalFunctionUserData for details.

Member Data Documentation

◆ getPrimalValuesFromPrimalValueVector

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
bool codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::getPrimalValuesFromPrimalValueVector
protected

Extract primal values from the primal value vector each time the external function is called.

◆ reallocatePrimalVectors

template<typename T_Type , typename T_Synchronization = DefaultSynchronization, typename T_ThreadInformation = DefaultThreadInformation>
bool codi::ExternalFunctionHelper< T_Type, T_Synchronization, T_ThreadInformation >::reallocatePrimalVectors
protected

If the primal vectors are reallocated every time the external function is called


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