CoDiPack  2.2.0
A Code Differentiation Package
SciComp TU Kaiserslautern
Loading...
Searching...
No Matches
codi::ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier > Struct Template Reference

Add user defined functions to the tape evaluation. More...

#include <externalFunctionTapeInterface.hpp>

Inheritance diagram for codi::ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier >:

Public Types

using Gradient = T_Gradient
 See ExternalFunctionTapeInterface.
 
using Identifier = T_Identifier
 See ExternalFunctionTapeInterface.
 
using Real = T_Real
 See ExternalFunctionTapeInterface.
 

Public Member Functions

Interface definition
template<typename Lhs , typename Tape >
Real registerExternalFunctionOutput (LhsExpressionInterface< Real, Gradient, Tape, Lhs > &value)
 
void pushExternalFunction (ExternalFunction< ExternalFunctionTapeInterface > const &extFunc)
 

Detailed Description

template<typename T_Real, typename T_Gradient, typename T_Identifier>
struct codi::ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier >

Add user defined functions to the tape evaluation.

See Tape Interface Design for a general overview of the tape interface design in CoDiPack.

External functions allow the user to evaluate custom operations during a tape evaluation. Each external function has pointers for the reverse, forward and primal evaluation of a tape. A function pointer may be null if the corresponding mode is not called on the tape. Otherwise, if the corresponding pointer is null and the corresponding mode is called on the tape, then a CODI_EXCEPTION is thrown.

What kind of operations are evaluated in the external function is up to the user. They are usually used to define derivative computations for libraries that cannot be differentiated with operator overloading.

Variables that are outputs of external functions have to be registered with registerExternalFunctionOutput. This will ensure that the variable is considered as active in CoDiPack. For primal value tapes, the return value of this function provides the old value stored under the identifier that the variable has received. This old value has to be restored with a call to adjointInterface.setPrimal() during the evaluation of the external function in reverse mode.

Here is an example (documentation/examples/externalFunctionTapeInterface.cpp):

using Tape = typename Real::Tape;
void printSomething(Tape* tape, void* data, VAI* vai) {
std::cout << "Hello from the reverse run." << std::endl;
int index = *((int*)data);
std::cout << "Adjoint of x is " << vai->getAdjoint(index, 0) << std::endl;
}
void deleteSomething(Tape* tape, void* data) {
std::cout << "Hello from the cleanup crew." << std::endl;
int* index = (int*)data;
delete index;
}
int main(int nargs, char** args) {
Tape& tape = Real::getTape();
// Recording
Real x = 10.0;
tape.setActive();
tape.registerInput(x);
tape.pushExternalFunction(codi::ExternalFunction<Tape>::create(printSomething, new int(x.getIdentifier()), deleteSomething));
Real y = 42.0 * x * x;
tape.pushExternalFunction(codi::ExternalFunction<Tape>::create(printSomething, new int(x.getIdentifier()), deleteSomething));
tape.registerOutput(y);
tape.setPassive();
// Reverse evaluation
y.setGradient(1.0);
tape.evaluate();
std::cout << "Gradient of dy/dx: " << x.getGradient() << std::endl;
tape.reset();
}
Template Parameters
T_RealThe computation type of a tape, usually chosen as ActiveType::Real.
T_GradientThe gradient type of a tape, usually chosen as ActiveType::Gradient.
T_IdentifierThe adjoint/tangent identification type of a tape, usually chosen as ActiveType::Identifier.

Member Function Documentation

◆ pushExternalFunction()

template<typename T_Real , typename T_Gradient , typename T_Identifier >
void codi::ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier >::pushExternalFunction ( ExternalFunction< ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier > > const & extFunc)

Push an external function to the tape.

The external function class can be created via the helper ExternalFunction::create.

◆ registerExternalFunctionOutput()

template<typename T_Real , typename T_Gradient , typename T_Identifier >
template<typename Lhs , typename Tape >
Real codi::ExternalFunctionTapeInterface< T_Real, T_Gradient, T_Identifier >::registerExternalFunctionOutput ( LhsExpressionInterface< Real, Gradient, Tape, Lhs > & value)

Register an external function output on the tape.

Returns
For primal value tapes, the return value has to be stored by the external function. The value has to be restored with a call to adjointInterface.setPrimal() during the evaluation of the external function in reverse mode. For this purpose, the primal value is identified by the index which the variable received when it was registered with registerExternalFunctionOutput.
Template Parameters
LhsClass that implements the LhsExpressionInterface. See also LhsExpressionInterface.
TapeTape implementation used in the LhsExpressionInterface. See also LhsExpressionInterface.

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