Provides file IO, information about internal tape vectors and allows to clear tape data. More...

#include <dataManagementTapeInterface.hpp>

Inheritance diagram for codi::DataManagementTapeInterface< T_Real, T_Identifier >:

[legend]

Public Types
using	Identifier = T_Identifier
	See DataManagementTapeInterface.

using	Real = T_Real
	See DataManagementTapeInterface.

Public Member Functions
Interface: File IO
void	writeToFile (std::string const &filename) const
	See File IO functions.

void	readFromFile (std::string const &filename)
	See File IO functions.

void	deleteData ()
	See File IO functions.

Interface: Parameters
std::set< TapeParameters > const &	getAvailableParameters () const
	See Parameters functions.

size_t	getParameter (TapeParameters parameter) const
	See Parameters functions.

bool	hasParameter (TapeParameters parameter) const
	See Parameters functions.

void	setParameter (TapeParameters parameter, size_t value)
	See Parameters functions.

Interface: Adjoint vector access
VectorAccessInterface< Real, Identifier > *	createVectorAccess ()
	See Adjoint vector access.

template<typename Adjoint >
VectorAccessInterface< Real, Identifier > *	createVectorAccessCustomAdjoints (Adjoint *data)
	See Adjoint vector access.

void	deleteVectorAccess (VectorAccessInterface< Real, Identifier > *access)
	See Adjoint vector access.

Interface: Adjoint vector management
void	resizeAdjointVector ()
	Explicitly trigger resizing of the adjoint vector. See Adjoint vector management.

void	deleteAdjointVector ()
	Delete the adjoint vector. See Adjoint vector management.

void	beginUseAdjointVector ()
	Declare that the adjoint vector is being used. See Adjoint vector management.

void	endUseAdjointVector ()
	Declare that the adjoint vector is no longer used. See Adjoint vector management.

Interface: Misc
void	swap (DataManagementTapeInterface &other)
	Swap all data with an other tape.

void	resetHard ()
	Delete everything and return to the state after construction, as far as possible.

Detailed Description

template<typename T_Real, typename T_Identifier>
struct codi::DataManagementTapeInterface< T_Real, T_Identifier >

Provides file IO, information about internal tape vectors and allows to clear tape data.

See Tape Interface Design for a general overview of the tape interface design in CoDiPack.

File IO functions

This interface offers advanced data management capabilities for the tape. The file IO routines provide the capability to write the internal tape data to the disk. The goal of this is moving the tape temporarily from RAM to disk. After writing the tape with writeToFile(), a call to deleteData() ensures that all internal data that was written to disk is freed so that the RAM footprint is minimized. Usually, neither management data nor external function data are exported. This means that the same tape that called writeToFile() has to call readFromFile() and that offloaded tapes are not meaningful across multiple executions of the application.

Parameters functions

The parameter functions provide access to the sizes of the internal tape implementations. For most of the parameters, they also allow the resizing of the underlying data. There are a few parameters that are read only and a CODI_EXCEPTION is thrown if the user tries to set them. See the documentation of the enumerators in TapeParameters for details about each parameters.

getParameter() and setParameter() will throw a CODI_EXCEPTION if the parameter is not defined for the tape. Which parameters are defined can either be checked with hasParameter() or looked up in the list returned by getAvailableParameters().

Adjoint vector access

The function createVectorAccess() provides access to the internal vectors of the tape, usually the adjoint vector and if available the primal value vector. If a generalized adjoint vector should be used, then the function createCustomAdjointVectorAccess() is used. This is the same functionality that is also used in external functions called from an evaluation with a custom adjoint vector.

Instances of both methods have to be deleted with the deleteVectorAccess().

Implementations may return different types that implement the same interface. Capturing these with auto may improve the performance by eliminating virtual function calls.

Adjoint vector management

Tapes manage their internal adjoint vector automatically. This covers all routines offered by the tape itself. This interface exposes parts of this adjoint vector management for external algorithms that build on top of a tape. See also codi::AdjointsManagement.

The functions resizeAdjointVector() and deleteAdjointVector() allow for memory optimizations. resizeAdjointVector() can be used to guarantee a sufficient adjoint vector size for subsequent access without bounds checking. deleteAdjointVector() frees the memory consumed by the adjoints.

beginUseAdjointVector() and endUseAdjointVector() allow for guarding the adjoint vector against resizing, in a way that is consistent with the internal adjoint vector safeguarding. See codi::InternalAdjointsInterface for a description of the "in use" mechanism. In particular, the adjoint vector is "in use" whenever there is read or write access to adjoint variables. As long as the adjoint vector is "in use", we cannot reallocate it. This is important in multithreaded applications where multiple tapes compete for using and resizing the same adjoint vector. Multiple threads can use the adjoint vector simultaneously. Attempts to use and resize the adjoint vector from different threads will be resolved by means of this safeguarding mechanism. An attempt to resize the adjoint vector from a thread while it has also declared usage results in a deadlock. The user of this interface is responsible for avoiding this, that is, after a thread calls beginUseAdjointVector(), this thread must not call tape methods that involve resizing and must not call resizeAdjointVector() until after a call to endUseAdjointVector().

Misc. functions

Some other functions for tape data management. Please see the function documentation.

Template Parameters

T_Real	The computation type of a tape, usually chosen as ActiveType::Real.
T_Identifier	The adjoint/tangent identification type of a tape, usually chosen as ActiveType::Identifier.

Member Function Documentation

◆ resetHard()

template<typename T_Real , typename T_Identifier >

void codi::DataManagementTapeInterface< T_Real, T_Identifier >::resetHard ( )

Delete everything and return to the state after construction, as far as possible.

Unlike other reset methods, this methods involves resizing the adjoint vector, this is not optional. Therefore, no codi::AdjointsManagement parameter is offered.

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

include/codi/tapes/interfaces/dataManagementTapeInterface.hpp

Public Types

Public Member Functions