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 Real = codi::RealReverse;
using Tape = typename Real::Tape;
using VAI = codi::VectorAccessInterface<typename Real::Real, typename Real::Identifier>;
 
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_Real	The computation type of a tape, usually chosen as ActiveType::Real.
T_Gradient	The gradient type of a tape, usually chosen as ActiveType::Gradient.
T_Identifier	The 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

Lhs	Class that implements the LhsExpressionInterface. See also LhsExpressionInterface.
Tape	Tape implementation used in the LhsExpressionInterface. See also LhsExpressionInterface.

---

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

• include/codi/tapes/interfaces/externalFunctionTapeInterface.hpp