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.

Public Member Functions
Action creation
inlinestatic RestoreActions	createRestoreActions (bool isInput, bool isOutput, bool isInputActive, bool primalRequired)
	Collect the restore actions for an argument in a `RestoreActions` instance.

inlinestatic 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
inlinestatic size_t	countActivitySize ()
	Return the size of the activity structure.

inlinestatic bool	getActivity (ActivityStoreType const &activity, size_t arg)
	Check the activity structure for activity of a specific argument.

inlinestatic void	restoreActivity (ByteDataView *fixedStore, ActivityStoreType &activity)
	Restore the activity structure from the data stream.

inlinestatic void	setActivity (ActivityStoreType &activity, size_t arg, bool active)
	Store the activity of an argument in the activity structure.

inlinestatic 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>

codi::LowLevelFunctionCreationUtilities::countActivitySize

inlinestatic 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:

Call setActivity for every input argument.
Write the activity of the arguments with storeActivity.
Call ActiveStoreTrait::store and PassiveArgumentStoreTraits::store for all arguments.

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:

Read the activity of the arguments with restoreActivity.
Read the data for all arguments with ActiveStoreTrait::restore() or PassiveStoreTrait::restore().

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_ActiveArguments The 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

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