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 = void()(Real const x, Real const x_d, size_t m, Real y, Real y_d, size_t n, ExternalFunctionUserData d)
	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 = 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.

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.

ExternalFunctionUserData &	getExternalFunctionUserData ()

	~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< Real >	y
	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.

All function inputs and outputs are specified.
The primal function is called. There are two modes for this, which are explained below.
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:

  codi::ExternalFunctionHelper<Real> eh;
 
  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:

  codi::ExternalFunctionHelper<Real> ehP(true);
 
  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_Type	The CoDiPack type that is used outside of the external function.
T_Synchronization	Synchronization facilities for thread-safety. See SynchronizationInterface.
T_ThreadInformation	Thread information facilities. See ThreadInformationInterface.