CoDiPack  2.2.0
A Code Differentiation Package
SciComp TU Kaiserslautern
Loading...
Searching...
No Matches
codi::LowLevelFunctionCreationUtilities< T_ActiveArguments > Struct Template Reference

Helper structure for storing low level functions and their arguments on a tape. More...

#include <lowLevelFunctionCreationUtilities.hpp>

Public Types

template<typename T >
using ActiveStoreTrait = ActiveArgumentStoreTraits<T>
 Utilities for handling an active argument.
 
using ActivityStoreType
 Type for the activity store. Currently limited to 64 variables.
 
template<typename T , typename S = T>
using PassiveStoreTrait = PassiveArgumentStoreTraits<T, S>
 Functionality for handling a passive argument.
 

Static Public Member Functions

Action creation
static RestoreActions createRestoreActions (bool isInput, bool isOutput, bool isInputActive, bool primalRequired)
 Collect the restore actions for an argument in a RestoreActions instance.
 
static StoreActions createStoreActions (bool tapeActive, bool isInput, bool isOutput, bool isInputActive, bool primalRequired)
 Collect the store actions for an argument in a StoreActions instance.
 
Argument activity
static size_t countActivitySize ()
 Return the size of the activity structure.
 
static bool getActivity (ActivityStoreType const &activity, size_t arg)
 Check the activity structure for activity of a specific argument.
 
static void restoreActivity (ByteDataView *fixedStore, ActivityStoreType &activity)
 Restore the activity structure from the data stream.
 
static void setActivity (ActivityStoreType &activity, size_t arg, bool active)
 Store the activity of an argument in the activity structure.
 
static void storeActivity (ByteDataView *fixedStore, ActivityStoreType const &activity)
 Store the activity structure in the data stream.
 

Static Public Attributes

static size_t constexpr ActiveArguments
 See LowLevelFunctionCreationUtilities.
 
static size_t constexpr TokenSize = sizeof(codi::Config::LowLevelFunctionToken)
 Token size for the low level function token.
 

Detailed Description

template<size_t T_ActiveArguments>
struct codi::LowLevelFunctionCreationUtilities< T_ActiveArguments >

Helper structure for storing low level functions and their arguments on a tape.

Storing on the tape

The process of storing the data for a low level function consists of several steps:

  • Determine if the tape is active and if the arguments of the function are active.
  • Count the size of the data that needs to be stored.
  • Allocate the data on the tape.
  • Write the data to the tape.
  • Evaluate the function either in a passive taping context or with different types than the CoDiPack ones.
  • Register the active outputs of the function.

In the following sections, the steps are explained. For an example implementation, see codi::ExtFunc_matrixMatrixMultiplication.

Determine activity

If the tape is not active, then no low level function should be created. Otherwise, each active argument can be checked with ActiveStoreTrait::isActive(). If all active arguments are passive, that is, all underlying CoDiPack types are passive, then the low level function should also not be created.

Currently the number of low-level function arguments is limited to 64. Note that the limit applies to the number of arguments passed to the low-level function, which is in general much smaller than the number of active CoDiPack values passed to the function. Matrix-matrix multiplication, for example, has two arguments (two matrices), but each matrix consists of multiple CoDiPack values.

Count size

The required size for storing all arguments can be determined with ActiveStoreTrait::countSize() and PassiveStoreTrait::countSize().

The total size is then:

size = countActivitySize() + <size from all arguments>
static size_t countActivitySize()
Return the size of the activity structure.
Definition lowLevelFunctionCreationUtilities.hpp:211

Depending on the activity of the arguments and if the primal values of the arguments are required for the derivative computation, the required size may vary.

Allocate data on the tape

A call to LowLevelFunctionTapeInterface::pushLowLevelFunction() adds the low level function to the tape and populates the codi::ByteDataView for the fixed and dynamic data.

Write data

Usually, the following needs to be done:

Evaluation of the low level function

There are two options.

  • The tape can be set to passive and the arguments with the CoDiPack types can be used for the evaluation.
  • The store traits can be configured such that the primal values are always extracted. These are available via ActiveStoreTrait::ArgumentStore::value() and can be used to call a passive version of the low level function.

Register output arguments

After the low level function is evaluated, each active output argument needs to be registered on the tape with a call to ActiveStoreTrait::setExternalFunctionOutput().

Restoring for reverse and forward evaluation

The restoring process needs to read the data in the same order as it was written. The following needs to be done:

Data deletion

Currently, it is assumed that all data is stored in the binary data stream of the tape. This data stream is automatically reset during a tape reset, which releases the data. There is currently no mechanism to automatically delete heap allocated data in the store methods.

Template Parameters
T_ActiveArgumentsThe number of active input arguments.

Member Typedef Documentation

◆ ActivityStoreType

template<size_t T_ActiveArguments>
using codi::LowLevelFunctionCreationUtilities< T_ActiveArguments >::ActivityStoreType
Initial value:
typename std::conditional<ActiveArguments <= 8, uint8_t,
typename std::conditional<ActiveArguments <= 16, uint16_t,
typename std::conditional<ActiveArguments <= 32, uint32_t,
typename std::conditional<ActiveArguments <= 64, uint64_t,
void>::type>::type>::type>::type
static size_t constexpr ActiveArguments
See LowLevelFunctionCreationUtilities.
Definition lowLevelFunctionCreationUtilities.hpp:129

Type for the activity store. Currently limited to 64 variables.

Member Data Documentation

◆ ActiveArguments

template<size_t T_ActiveArguments>
size_t constexpr codi::LowLevelFunctionCreationUtilities< T_ActiveArguments >::ActiveArguments
staticconstexpr
Initial value:
=
T_ActiveArguments

See LowLevelFunctionCreationUtilities.


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