Reference documentation for deal.II version Git 500a7ed831 2022-01-17 20:04:17 -0700

#include <deal.II/differentiation/ad/ad_drivers.h>

[legend]

## Public Member Functions

Taping
bool is_recording () const

Types< ADNumberType >::tape_index active_tape_index () const

bool is_registered_tape (const typename Types< ADNumberType >::tape_index tape_index) const

bool keep_independent_values () const

void set_tape_buffer_sizes (const typename Types< ADNumberType >::tape_buffer_sizes obufsize=64 *1024 *1024, const typename Types< ADNumberType >::tape_buffer_sizes lbufsize=64 *1024 *1024, const typename Types< ADNumberType >::tape_buffer_sizes vbufsize=64 *1024 *1024, const typename Types< ADNumberType >::tape_buffer_sizes tbufsize=64 *1024 *1024)

void start_taping (const typename Types< ADNumberType >::tape_index tape_index, const bool keep_independent_values)

void stop_taping (const typename Types< ADNumberType >::tape_index active_tape_index, const bool write_tapes_to_file)

std::vector< typename Types< ADNumberType >::tape_index > get_registered_tape_indices () const

void activate_tape (const typename Types< ADNumberType >::tape_index tape_index)

bool requires_retaping (const typename Types< ADNumberType >::tape_index tape_index) const

bool last_action_requires_retaping () const

void remove_tape (const typename Types< ADNumberType >::tape_index tape_index)

void reset (const bool clear_registered_tapes)

void print (std::ostream &stream) const

void print_tape_stats (const typename Types< ADNumberType >::tape_index tape_index, std::ostream &stream) const

Drivers for scalar functions (one dependent variable)
ScalarType value (const typename Types< ADNumberType >::tape_index active_tape_index, const std::vector< ScalarType > &independent_variables) const

void gradient (const typename Types< ADNumberType >::tape_index active_tape_index, const std::vector< ScalarType > &independent_variables, Vector< ScalarType > &gradient) const

void hessian (const typename Types< ADNumberType >::tape_index active_tape_index, const std::vector< ScalarType > &independent_variables, FullMatrix< ScalarType > &hessian) const

Drivers for vector functions (multiple dependent variables)
void values (const typename Types< ADNumberType >::tape_index active_tape_index, const unsigned int n_dependent_variables, const std::vector< ScalarType > &independent_variables, Vector< ScalarType > &values) const

void jacobian (const typename Types< ADNumberType >::tape_index active_tape_index, const unsigned int n_dependent_variables, const std::vector< ScalarType > &independent_variables, FullMatrix< ScalarType > &jacobian) const

## Detailed Description

A prototype driver class for taped auto-differentiable numbers.

It is intended that this class be specialized for the valid combinations of auto-differentiable numbers and output scalar number types.

Template Parameters
 ADNumberType A type corresponding to a supported auto-differentiable number. ScalarType A real or complex floating point number type that is the scalar value type used for input to, and output from, operations performed with auto-differentiable numbers. T An arbitrary type resulting from the application of the SFINAE idiom to selectively specialize this class.

Definition at line 148 of file ad_drivers.h.

## ◆ is_recording()

Return whether or not this class is tracking calculations performed with its marked independent variables.

Definition at line 58 of file ad_drivers.cc.

## ◆ active_tape_index()

Return the tape number which is currently activated for recording or reading.

Definition at line 67 of file ad_drivers.cc.

## ◆ is_registered_tape()

Return whether or not a tape number has already been used or registered.

Definition at line 76 of file ad_drivers.cc.

## ◆ keep_independent_values()

Return whether or not the numerical values of all independent variables are recorded in the tape buffer.

Definition at line 86 of file ad_drivers.cc.

## ◆ set_tape_buffer_sizes()

 void Differentiation::AD::TapedDrivers< ADNumberType >::set_tape_buffer_sizes ( const typename Types< ADNumberType >::tape_buffer_sizes obufsize = 64 * 1024 * 1024, const typename Types< ADNumberType >::tape_buffer_sizes lbufsize = 64 * 1024 * 1024, const typename Types< ADNumberType >::tape_buffer_sizes vbufsize = 64 * 1024 * 1024, const typename Types< ADNumberType >::tape_buffer_sizes tbufsize = 64 * 1024 * 1024 )

Set the buffer sizes for the next active tape.

This function must be called before start_recording_operations() for it to have any influence on the memory allocated to the next recorded tape.

Note
This function only has an effect when using ADOL-C numbers. As stated by the ADOL-C manual, it may be desirable to create a file ".adolcrc" in the program run directory and set the buffer size therein. Alternatively, this function can be used to override the settings for any given tape, or can be used in the event that no ".adolcrc" file exists. The default value for each buffer is set at 64 megabytes, a heuristically chosen value thought to be appropriate for use within the context of finite element analysis when considering coupled problems with multiple vector-valued fields discretised by higher order shape functions, as well as complex constitutive laws.
Parameters
 [in] obufsize ADOL-C operations buffer size [in] lbufsize ADOL-C locations buffer size [in] vbufsize ADOL-C value buffer size [in] tbufsize ADOL-C Taylor buffer size

Definition at line 95 of file ad_drivers.cc.

## ◆ start_taping()

Enable the recording mode for a given tape.

Parameters
 [in] tape_index The index of the tape to be written. [in] keep_independent_values Determines whether the numerical values of all independent variables are recorded in the tape buffer.

Definition at line 107 of file ad_drivers.cc.

## ◆ stop_taping()

Disable the recording mode for a given tape.

Parameters
 [in] active_tape_index The index of the (currently active) tape to be finalized and potentially written to file. [in] write_tapes_to_file A flag that specified whether the tape should be written to file or kept in memory.

Definition at line 117 of file ad_drivers.cc.

## ◆ get_registered_tape_indices()

Return a list of registered tape indices.

Definition at line 127 of file ad_drivers.cc.

## ◆ activate_tape()

Select a tape to record to or read from.

This function activates a tape, but depending on whether read_mode is set, the tape is either taken as previously written to (and put into read-only mode), or cleared for (re-)taping.

Parameters
 [in] tape_index The index of the tape to be written to/read from.
Note
The chosen tape index must be greater than Numbers<ADNumberType>::invalid_tape_index and less than Numbers<ADNumberType>::max_tape_index.

Definition at line 137 of file ad_drivers.cc.

## ◆ requires_retaping()

Return a flag that, when true, indicates that the retaping of the dependent function for the chosen tape_index is necessary for a reliable computation to be performed. This may be necessary if a sign comparison within branched operations yields different results to those computed at the original tape evaluation point.

This issue, known as "branch switching", can be clarified by means of a trivial, contrived example:

{
if (x < y)
return y;
else
return x*z;
}

During taping, the conditional statement may be either true or false, and the result (with its sensitivities) returned by this function. The AD library doesn't just record the parse tree of the operations applied on the branch chosen at the time to taping, but also checks that the condition continues to be satisfied. For some other evaluation of the tape (i.e. for some different inputs x and y), the other branch of the conditional check may be chosen. The result of following this code path has not been recorded on the tape, and therefore cannot be evaluated. In such a case, the underlying AD library will be able to tell you that it is necessary to re-record the tape at the new evaluation point in order to resolve the new code branch. This function can be used to find out whether this is so.

Note
The chosen tape index must be greater than Numbers<ADNumberType>::invalid_tape_index and less than Numbers<ADNumberType>::max_tape_index.

Definition at line 146 of file ad_drivers.cc.

## ◆ last_action_requires_retaping()

Return a flag that, when true, indicates that the retaping of the dependent function is necessary for a reliable computation to be performed on the currently active tape. This may be necessary if a sign comparison within branched operations yields different results to those computed at the original tape evaluation point.

This issue, known as "branch switching", can be clarified by means of a trivial, contrived example:

{
if (x < y)
return y;
else
return x*z;
}

During taping, the conditional statement may be either true or false, and the result (with its sensitivities) returned by this function. The AD library doesn't just record the parse tree of the operations applied on the branch chosen at the time to taping, but also checks that the condition continues to be satisfied. For some other evaluation of the tape (i.e. for some different inputs x and y), the other branch of the conditional check may be chosen. The result of following this code path has not been recorded on the tape, and therefore cannot be evaluated. In such a case, the underlying AD library will be able to tell you that it is necessary to re-record the tape at the new evaluation point in order to resolve the new code branch. This function can be used to find out whether this is so.

Definition at line 156 of file ad_drivers.cc.

## ◆ remove_tape()

Completely erases the tape with the given tape_index.

Definition at line 166 of file ad_drivers.cc.

## ◆ reset()

Reset the state of the class.

Note
This also resets the active tape number to an invalid number, and deactivates the recording mode for taped variables.

Definition at line 175 of file ad_drivers.cc.

## ◆ print()

Print the status of all queryable data. Exactly what is printed and its format depends on the ad_type, as is determined by the ADNumberTypeCode template parameter.

Parameters
 [in] stream The output stream to which the values are to be written.

Definition at line 183 of file ad_drivers.cc.

## ◆ print_tape_stats()

Print the statistics regarding the usage of the tapes.

Parameters
 [in] tape_index The index of the tape to get the statistics of. [out] stream The output stream to which the values are to be written.

Definition at line 191 of file ad_drivers.cc.

## ◆ value()

template<typename ADNumberType , typename ScalarType , typename T >

Compute the value of the scalar field.

Parameters
 [in] active_tape_index The index of the tape on which the dependent function is recorded. [in] independent_variables The scalar values of the independent variables whose sensitivities were tracked.
Returns
The scalar value of the function.

Definition at line 201 of file ad_drivers.cc.

template<typename ADNumberType , typename ScalarType , typename T >

Compute the gradient of the scalar field with respect to all independent variables.

Parameters
 [in] active_tape_index The index of the tape on which the dependent function is recorded. [in] independent_variables The scalar values of the independent variables whose sensitivities were tracked. [out] gradient The values of the dependent function's gradients. It is expected that this vector be of the correct size (with length n_independent_variables).

Definition at line 212 of file ad_drivers.cc.

## ◆ hessian()

template<typename ADNumberType , typename ScalarType , typename T >
 void Differentiation::AD::TapedDrivers< ADNumberType >::hessian ( const typename Types< ADNumberType >::tape_index active_tape_index, const std::vector< ScalarType > & independent_variables, FullMatrix< ScalarType > & hessian ) const

Compute the Hessian of the scalar field with respect to all independent variables.

Parameters
 [in] active_tape_index The index of the tape on which the dependent function is recorded. [in] independent_variables The scalar values of the independent variables whose sensitivities were tracked. [out] hessian The values of the dependent function's Hessian. It is expected that this matrix be of the correct size (with dimensions n_independent_variables $$\times$$n_independent_variables).

Definition at line 223 of file ad_drivers.cc.

## ◆ values()

template<typename ADNumberType , typename ScalarType , typename T >
 void Differentiation::AD::TapedDrivers< ADNumberType >::values ( const typename Types< ADNumberType >::tape_index active_tape_index, const unsigned int n_dependent_variables, const std::vector< ScalarType > & independent_variables, Vector< ScalarType > & values ) const

Compute the values of the vector field.

Parameters
 [in] active_tape_index The index of the tape on which the dependent function is recorded. [in] n_dependent_variables The number of dependent variables. [in] independent_variables The scalar values of the independent variables whose sensitivities were tracked. [out] values The component values of the dependent functions. It is expected that this vector be of the correct size (with length n_dependent_variables).

Definition at line 234 of file ad_drivers.cc.

## ◆ jacobian()

template<typename ADNumberType , typename ScalarType , typename T >
 void Differentiation::AD::TapedDrivers< ADNumberType >::jacobian ( const typename Types< ADNumberType >::tape_index active_tape_index, const unsigned int n_dependent_variables, const std::vector< ScalarType > & independent_variables, FullMatrix< ScalarType > & jacobian ) const

Compute the Jacobian of the vector field.

The Jacobian of a vector field is in essence the gradient of each dependent variable with respect to all independent variables. This operation is therefore analogous to the gradient() operation performed on a collection of scalar valued fields.

Parameters
 [in] active_tape_index The index of the tape on which the dependent function is recorded. [in] n_dependent_variables The number of dependent variables. [in] independent_variables The scalar values of the independent variables whose sensitivities were tracked. [out] jacobian The component values of the dependent functions' Jacobian. It is expected that this matrix be of the correct size (with dimensions n_dependent_variables $$\times$$n_independent_variables).

Definition at line 246 of file ad_drivers.cc.

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