codi::ActiveArgumentStoreTraits< T_T, typename > Struct Template Reference

Traits for storing active arguments in byte streams. More...

#include <activeArgumentStoreTraits.hpp>

Public Types
using	ArgumentStore = ActiveArgumentStoreInterface<Real, Identifier, Gradient>
	Data for holding all necessary values.
using	Gradient = Real
	The type that can represent the gradient values.
using	Identifier = int
	The type for holding the identifiers.
using	Real = double
	The type with no CoDiPack values.
using	T = T_T
	See ActiveArgumentStoreTraits.

Static Public Member Functions
static size_t	countSize (T const &value, size_t size, StoreActions const &actions)
	Counts the binary size for the data stream.
static void	getGradients (VectorAccessInterface< Real, Identifier > *data, size_t size, bool reset, Identifier &identifier, Gradient &gradient, size_t dim)
	Get the gradients from data and store them in gradient.
static void	getPrimalsFromVector (VectorAccessInterface< Real, Identifier > *data, size_t size, Identifier &identifier, Real &primal)
	Get the primal values from data and store them in primal.
static bool	isActive (T const &value, size_t size)
	Should return true when one element in the type is active.
static void	restore (ByteDataView *store, TemporaryMemory &allocator, size_t size, RestoreActions const &actions, ArgumentStore &data)
	Restore the data for this type.
static void	setExternalFunctionOutput (bool tapeActive, T &value, size_t size, Identifier &identifier, Real &primal, Real &oldPrimals)
static void	setGradients (VectorAccessInterface< Real, Identifier > *data, size_t size, bool update, Identifier &identifier, Gradient &gradient, size_t dim)
	Extract the gradients from gradient and store them in data.
static void	setPrimalsIntoVector (VectorAccessInterface< Real, Identifier > *data, size_t size, Identifier &identifier, Real &primal)
	Extract the primal values from primal and store them in data.
static void	store (ByteDataView *dataStore, TemporaryMemory &allocator, T const &value, size_t size, StoreActions const &actions, ArgumentStore &data)
	Store all data for this type.

Detailed Description

template<typename T_T, typename = void>
struct codi::ActiveArgumentStoreTraits< T_T, typename >

Traits for storing active arguments in byte streams.

There is one data stream available for storing the data of a type. The size and layout of the data can be arbitrary. The only limitation is the maximum size of the data, which is defined by Config::LowLevelFunctionDataSizeMax. This limit holds for the whole external function. If more data is required, it should be allocated dynamically.

Example data layout for matrix matrix multiplications.

The required data for a matrix is the size, the values of the entries, and the identifiers from CoDiPack. The data could then be stored like:

stream data: | n | m | n * m values | n * m identifiers |

The sizes n and m are the necessary information for the dynamic data. Therefore, they are stored first. Afterwards, the dynamic sized data is stored.

Call process

Recording

The first function that is usually called is the isActive function. It should return true if one CoDiPack entry in the type is active. Afterwards, the countSize function is called to determine the required byte size for the data stream. This count needs to be exact since the data is preallocated and cannot be shortened afterwards. The call to store initiates the storing of the type in the stream and therefore on the tape. The stored data needs to be smaller or equal to the size returned in countSize. Finally, the setExternalFunctionOutput method is called on output arguments. Here, the vectors created in store need to be updated if necessary. Usually, these are vectors for the identifiers of the output value and old primal values.

CoDiPack performs an online activity analysis. The default behavior for the low level function helper sets all CoDiPack values of the output arguments to active. The user can control this behavior by modifying the identifiers of the output arguments. All values different than zero are treated as an active output and a valid identifier will be generated. The specialization for the CoDiPack values implements this by initializing the output identifiers with -1. If they are not modified then they are treated as active.

Tape evaluation

During a reverse, forward, primal, etc. evaluation of a tape, the restore method is called first. It should read all data written in store.

Afterwards, the functions getPrimalsFromVector, setPrimalsIntoVector, getGradients, and setGradients are called to populate the vectors created in the restore functions.

Store actions

• StoreAction::PrimalCreateOnTape : Create a primal vector in the data streams.
• StoreAction::PrimalExtract : Extract the primal from the value. If PrimalCreateOnTape is not requested, create a temporary vector for it.
• StoreAction::InputIdentifierCreateAndStore : Create a vector for the input identifiers and store the current ones from the value.
• StoreAction::OutputIdentifierCreate : Create a vector for the output identifiers. They are populated during the call to setExternalFunctionOutput after the low level function has been evaluated.

Restore actions

• RestoreAction::PrimalCreate : Create a vector for the primal output values of this argument.
• RestoreAction::PrimalRestore : Restore the primal input values from the data stream.
• RestoreAction::InputIdentifierRestore : Read a vector for the input identifiers from the data stream.
• RestoreAction::OutputIdentifierRestore : Read a vector for the output identifiers from the data stream.
• RestoreAction::InputGradientCreate : Create a vector for the input gradients. They are then populated/used during a call to getGradients/setGradients.
• RestoreAction::OutputGradientCreate : Create a vector for the output gradients. They are then populated/used during a call to getGradients/setGradients.

Template Parameters

T_T	A type that contains CoDiPack values.

Member Function Documentation

countSize()

template<typename T_T , typename = void>

static size_t codi::ActiveArgumentStoreTraits< T_T, typename >::countSize ( T const & value, size_t size, StoreActions const & actions )

inlinestatic

Counts the binary size for the data stream.

This value needs to define the maximum size required to store all data for the type. It should be exact since the allocated memory cannot be reduced afterwards.

actions describe what needs to be done for this argument. size is a hint for the implementation, e.g., the size of arrays addressed by pointers.

restore()

template<typename T_T , typename = void>

static void codi::ActiveArgumentStoreTraits< T_T, typename >::restore ( ByteDataView * store, TemporaryMemory & allocator, size_t size, RestoreActions const & actions, ArgumentStore & data )

inlinestatic

Restore the data for this type.

actions describe what needs to be done for this argument. size is a hint for the implementation, e.g., the size of arrays addressed by pointers. data can be used to store data and pointers from the streams.

setExternalFunctionOutput()

template<typename T_T , typename = void>

static void codi::ActiveArgumentStoreTraits< T_T, typename >::setExternalFunctionOutput ( bool tapeActive, T & value, size_t size, Identifier & identifier, Real & primal, Real & oldPrimals )

inlinestatic

Called after the primal evaluation. All active values in value need to be registered as outputs of an external function. value needs to be populated with the primal values from primal. The identifiers need to be stored in identifiers.

store()

template<typename T_T , typename = void>

static void codi::ActiveArgumentStoreTraits< T_T, typename >::store ( ByteDataView * dataStore, TemporaryMemory & allocator, T const & value, size_t size, StoreActions const & actions, ArgumentStore & data )

inlinestatic

Store all data for this type.

The amount of data cannot be greater than the amount reported by countSize().

actions describe what needs to be done for this argument. size is a hint for the implementation, e.g., the size of arrays addressed by pointers. data can be used to store data and pointers from the streams.

If dataStore is a null pointer then only the StoreAction::PrimalExtract action is allowed.

---

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

• include/codi/tools/lowlevelFunctions/traits/activeArgumentStoreTraits.hpp