CoDiPack  2.2.0
A Code Differentiation Package
SciComp TU Kaiserslautern
Loading...
Searching...
No Matches
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_TA 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: