Reference documentation for deal.II version GIT bcacb256b7 2023-01-31 02:10:01+00:00
Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType > Class Template Reference

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

Inheritance diagram for Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >:
[legend]

## Public Types

using scalar_type = typename HelperBase< ADNumberTypeCode, ScalarType >::scalar_type

## Public Member Functions

Constructor / destructor
ResidualLinearization (const unsigned int n_independent_variables, const unsigned int n_dependent_variables)

virtual ~ResidualLinearization ()=default

Dependent variables
void register_residual_vector (const std::vector< ad_type > &residual)

virtual void compute_residual (Vector< scalar_type > &residual) const override

virtual void compute_linearization (FullMatrix< scalar_type > &linearization) const override

Independent variables
void register_dof_values (const std::vector< scalar_type > &dof_values)

void register_dof_values (const VectorType &values, const std::vector<::types::global_dof_index > &local_dof_indices)

const std::vector< ad_type > & get_sensitive_dof_values () const

Operations specific to taped mode: Reusing tapes
void set_dof_values (const std::vector< scalar_type > &dof_values)

void set_dof_values (const VectorType &values, const std::vector<::types::global_dof_index > &local_dof_indices)

Interrogation of internal information
std::size_t n_independent_variables () const

std::size_t n_dependent_variables () const

void print (std::ostream &stream) const

void print_values (std::ostream &stream) const

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

Operations specific to taped mode: Recording tapes
virtual void reset (const unsigned int n_independent_variables=::numbers::invalid_unsigned_int, const unsigned int n_dependent_variables=::numbers::invalid_unsigned_int, const bool clear_registered_tapes=true)

bool is_recording () const

Types< ad_type >::tape_index active_tape_index () const

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

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

bool start_recording_operations (const typename Types< ad_type >::tape_index tape_index, const bool overwrite_tape=false, const bool keep_independent_values=true)

void stop_recording_operations (const bool write_tapes_to_file=false)

void activate_recorded_tape (const typename Types< ad_type >::tape_index tape_index)

bool recorded_tape_requires_retaping (const typename Types< ad_type >::tape_index tape_index) const

bool active_tape_requires_retaping () const

void clear_active_tape ()

## Static Public Member Functions

Operations specific to tapeless mode
static void configure_tapeless_mode (const unsigned int n_independent_variables, const bool ensure_persistent_setting=true)

## Drivers and taping

void activate_tape (const typename Types< ad_type >::tape_index tape_index, const bool read_mode)

## Independent variables

std::vector< scalar_typeindependent_variable_values

std::vector< boolregistered_independent_variable_values

std::vector< boolregistered_marked_independent_variables

void reset_registered_independent_variables ()

void set_sensitivity_value (const unsigned int index, const scalar_type &value)

void mark_independent_variable (const unsigned int index, ad_type &out) const

void finalize_sensitive_independent_variables () const

void initialize_non_sensitive_independent_variable (const unsigned int index, ad_type &out) const

unsigned int n_registered_independent_variables () const

## Dependent variables

std::vector< boolregistered_marked_dependent_variables

void reset_registered_dependent_variables (const bool flag=false)

unsigned int n_registered_dependent_variables () const

void register_dependent_variable (const unsigned int index, const ad_type &func)

## Detailed Description

A helper class that facilitates the evaluation and automated linearization of a vector of functions that represents a residual vector (as computed from some corresponding local degree of freedom values). This class would typically be used to compute the linearization of a residual vector defined on the level of a cell, or for local nonlinear equations.

An example of its usage in the case of a residual linearization might be as follows (in this case we'll compute the linearization of a finite-strain magneto-elastic solid from the residual, as constructed from the Piola-Kirchoff stress and magnetic induction assuming the magnetic scalar potential formulation):

// Existing data structures:
Vector<double> solution (...); // Or another vector type
std::vector<types::global_dof_index> local_dof_indices (...);
const FEValuesExtractors::Vector u_fe (...);
const FEValuesExtractors::Scalar msp_fe (...);
const unsigned int u_block (...);
const unsigned int msp_block (...);
FEValues<dim> fe_values (...);
const unsigned int n_q_points (...);
Vector<double> cell_rhs (...);
// Assembly loop:
for (auto &cell : ...)
{
cell->get_dof_indices(local_dof_indices);
const unsigned int n_independent_variables
= local_dof_indices.size();
const unsigned int n_dependent_variables
= local_dof_indices.size();
// Create some aliases for the AD helper.
// In this example, we strictly assume that we're using tapeless
// AD types, and so the AD_typecode used in the template argument
// must refer to one of these types. See the example for the
// EnergyFunctional for details on how to extend
// support to taped AD numbers.
// Create and initialize an instance of the helper class.
// Initialize the local data structures for assembly.
// This is also taken care of by the ADHelper, so this step could
// be skipped.
cell_rhs.reinit(n_dependent_variables);
// This next code block corresponds to the "recording" phase, where
// the operations performed with the AD numbers are tracked and
// differentiation is performed.
{
// First, we set the values for all DoFs.
// Then we get the complete set of degree of freedom values as
// represented by auto-differentiable numbers.
// Then we do some problem specific tasks, the first being to
// compute all values, gradients, etc. based on sensitive AD DoF
// values. Here we are fetching the displacement gradients at each
// quadrature point, as well as the gradients of the magnetic
// scalar potential field.
// This variable stores the cell residual vector contributions.
// IMPORTANT: Note that each entry is hand-initialized with a value
// of zero. This is a highly recommended practise, as some AD
// numbers appear not to safely initialize their internal data
// structures.
// Compute the cell total residual
// = (internal + external) contributions
for (unsigned int q_point = 0; q_point < n_q_points; ++q_point)
{
// Calculate the deformation gradient and magnetic field at this
const Tensor<1, dim, ADNumberType> H = -Grad_msp[q_point];
ExcMessage("Negative determinant of the deformation "
// Extract some configuration dependent variables from our
// nonlinear constitutive law for the current quadrature point.
// In this way they only have to be computed once per quadrature
// point.
const SymmetricTensor<2,dim,ad_type> S = get_S(F,H);
const Tensor<1,dim,ad_type> B = get_B(F,H);
// Define some position-dependent aliases, to make the assembly
// process easier to follow.
const double JxW = fe_values.JxW(q_point);
// Add contribution of the internal forces:
// Note that we assemble the residual contribution directly
// as it is this vector that is to be automatically linearized.
for (unsigned int I = 0; I < n_dofs_per_cell; ++I)
{
// Determine the component and block associated with
// the I'th local degree of freedom.
const unsigned int block_I =
fe.system_to_base_index(I).first.first;
if (block_I == u_block) // u-terms
{
// Variation of the Green-Lagrange strain tensor
// associated with the I'th vector-valued basis function.
residual_ad[I] += (dE_I*S) * JxW;
}
else if (block_I == msp_block)
{
// Variation of the magnetic field vector associated with
// the I'th scalar-valued basis function
residual_ad[I] -= (dH_I*B) * JxW;
}
}
}
// Add contribution from external sources. If these contributions
// are also solution dependent then they will also be consistently
// linearized.
// Loop over faces and accumulate external contributions into the
// cell total residual.
for (unsigned int face : ...)
if (cell->face(face)->at_boundary())
// Register the definition of the cell residual
}
// Compute the residual values and their Jacobian at the
// evaluation point
cell_rhs *= -1.0; // RHS = - residual
}
Definition: tensor.h:503
DerivativeForm< 1, spacedim, dim, Number > transpose(const DerivativeForm< 1, dim, spacedim, Number > &DF)
#define Assert(cond, exc)
Definition: exceptions.h:1509
static ::ExceptionBase & ExcMessage(std::string arg1)
void cell_matrix(FullMatrix< double > &M, const FEValuesBase< dim > &fe, const FEValuesBase< dim > &fetest, const ArrayView< const std::vector< double >> &velocity, const double factor=1.)
Tensor< 2, dim, Number > F(const Tensor< 2, dim, Number > &Grad_u)
bool value_is_greater_than(const Number1 &value_1, const Number2 &value_2)
Definition: numbers.h:995
constexpr SymmetricTensor< 2, dim, Number > symmetrize(const Tensor< 2, dim, Number > &t)
constexpr Number determinant(const SymmetricTensor< 2, dim, Number > &)

In most use cases, and in particular in the code example shown above, both the number of independent and dependent variables equals the number of dofs_per_cell for the used finite element.

Warning
ADOL-C does not support the standard threading models used by deal.II, so this class should not be embedded within a multithreaded function when using ADOL-C number types. It is, however, suitable for use in both serial and MPI routines.

Definition at line 1528 of file ad_helpers.h.

## ◆ scalar_type

template<enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
 using Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::scalar_type = typename HelperBase::scalar_type

Type definition for the floating point number type that is used in, and results from, all computations.

Definition at line 1536 of file ad_helpers.h.

template<enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>

Type definition for the auto-differentiation number type that is used in all computations.

Definition at line 1543 of file ad_helpers.h.

## ◆ ResidualLinearization()

 Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::ResidualLinearization ( const unsigned int n_independent_variables, const unsigned int n_dependent_variables )

The constructor for the class.

Parameters
 [in] n_independent_variables The number of independent variables that will be used in the definition of the functions that it is desired to compute the sensitivities of. In the computation of $$\mathbf{r}(\mathbf{X})$$, this will be the number of inputs $$\mathbf{X}$$, i.e., the dimension of the domain space. [in] n_dependent_variables The number of scalar functions to be defined that will have a sensitivity to the given independent variables. In the computation of $$\mathbf{r}(\mathbf{X})$$, this will be the number of outputs $$\mathbf{r}$$, i.e., the dimension of the image space.

Definition at line 1006 of file ad_helpers.cc.

## ◆ ~ResidualLinearization()

template<enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
 virtual Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::~ResidualLinearization ( )
virtualdefault

Destructor

## ◆ register_residual_vector()

 void Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::register_residual_vector ( const std::vector< ad_type > & residual )

Register the definition of the cell residual vector $$\mathbf{r}(\mathbf{X})$$.

Parameters
 [in] residual A vector of recorded functions that defines the residual. The components of this vector represents the dependent variables.
Note
For this class that expects only vector fields of dependent variables, this function must only be called once per tape.
For taped AD numbers, this operation is only valid in recording mode.

Definition at line 1017 of file ad_helpers.cc.

## ◆ compute_residual()

 void Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::compute_residual ( Vector< scalar_type > & residual ) const
overridevirtual

Evaluation of the residual for a chosen set of degree of freedom values. This corresponds to the computation of the residual vector, i.e.

$\mathbf{r}(\mathbf{X}) \vert_{\mathbf{X}}$

The values at the evaluation point $$\mathbf{X}$$ are obtained by calling CellLevelBase::set_dof_values().

Parameters
 [out] residual A Vector object, for which the value for each entry represents the residual value for the corresponding local degree of freedom. The output residual vector has a length corresponding to n_dependent_variables.

Definition at line 1032 of file ad_helpers.cc.

## ◆ compute_linearization()

 void Differentiation::AD::ResidualLinearization< ADNumberTypeCode, ScalarType >::compute_linearization ( FullMatrix< scalar_type > & linearization ) const
overridevirtual

Compute the linearization of the residual vector around a chosen set of degree of freedom values. Underlying this is the computation of the gradient (first derivative) of the residual vector $$\mathbf{r}$$ with respect to all independent variables, i.e.

$\frac{\partial\mathbf{r}(\mathbf{X})}{\partial\mathbf{X}}$

The values at the evaluation point $$\mathbf{X}$$ are obtained by calling CellLevelBase::set_dof_values().

Parameters
 [out] linearization A FullMatrix representing the linearization of the residual vector. The output linearization matrix has dimensions corresponding to n_dependent_variables $$\times$$n_independent_variables.

Definition at line 1086 of file ad_helpers.cc.

## ◆ register_dof_values() [1/2]

 void Differentiation::AD::CellLevelBase< ADNumberTypeCode, double >::register_dof_values ( const std::vector< scalar_type > & dof_values )
inherited

Register the complete set of independent variables $$\mathbf{X}$$ that represent the local degree of freedom values.

Parameters
 [in] dof_values A vector field associated with local degree of freedom values on the current finite element. These define the values of all independent variables. When considering taped AD numbers with branching functions, to avoid potential issues with branch switching it may be a good idea to choose these values close or equal to those that will be later evaluated and linearized around.
Note
The input value type must correspond to this class's scalar_type. Depending on the selected ADNumberTypeCode, this may or may not correspond with the ScalarType prescribed as a template argument.
For taped AD numbers, this operation is only valid in recording mode.

Definition at line 904 of file ad_helpers.cc.

## ◆ register_dof_values() [2/2]

 void Differentiation::AD::CellLevelBase< ADNumberTypeCode, double >::register_dof_values ( const VectorType & values, const std::vector<::types::global_dof_index > & local_dof_indices )
inherited

Register the complete set of independent variables $$\mathbf{X}$$ that represent the local degree of freedom values.

Parameters
 [in] values A global field from which the values of all independent variables will be extracted. This typically will be the solution vector around which point a residual vector is to be computed and around which linearization is to occur. When considering taped AD numbers with branching functions, to avoid potential issues with branch switching it may be a good idea to choose these values close or equal to those that will be later evaluated and linearized around. [in] local_dof_indices A vector of degree of freedom indices from which to extract the local degree of freedom values. This would typically obtained by calling cell->get_dof_indices().
Note
For taped AD numbers, this operation is only valid in recording mode.

## ◆ get_sensitive_dof_values()

inherited

Return the complete set of degree of freedom values as represented by auto-differentiable numbers. These are the independent variables $$\mathbf{X}$$ about which the solution is linearized.

This function indicates to the AD library that implements the auto-differentiable number type that operations performed on these numbers are to be tracked so they are considered "sensitive" variables. This is, therefore, the set of variables with which one would then perform computations, and based on which one can then extract both the value of the function and its derivatives with the member functions below. The values of the components of the returned object are initialized to the values set with register_independent_variable().

Returns
An array of auto-differentiable type numbers representing the local degree of freedom values.
Note
For taped AD numbers, this operation is only valid in recording mode.

Definition at line 951 of file ad_helpers.cc.

## ◆ set_dof_values() [1/2]

 void Differentiation::AD::CellLevelBase< ADNumberTypeCode, double >::set_dof_values ( const std::vector< scalar_type > & dof_values )
inherited

Set the values for the independent variables $$\mathbf{X}$$, i.e., the linearization point.

Parameters
 [in] dof_values A vector field associated with local degree of freedom values on the current finite element. These define the values of all independent variables.
Note
The input value type must correspond to this class's scalar_type. Depending on the selected ADNumberTypeCode, this may or may not correspond with the ScalarType prescribed as a template argument.
If the keep_independent_values flag has been set when HelperBase::start_recording_operations() is called then the tape is immediately usable after creation, and the values of the independent variables set by register_dof_values() are those at which the function is to be evaluated. In this case, a separate call to this function is not strictly necessary.

Definition at line 980 of file ad_helpers.cc.

## ◆ set_dof_values() [2/2]

 void Differentiation::AD::CellLevelBase< ADNumberTypeCode, double >::set_dof_values ( const VectorType & values, const std::vector<::types::global_dof_index > & local_dof_indices )
inherited

Set the values for the independent variables $$\mathbf{X}$$, i.e., the linearization point.

Parameters
 [in] values A vector field from which the values of all independent variables is to be extracted. [in] local_dof_indices A vector of degree of freedom indices from which to extract the local degree of freedom values. This would typically obtained by calling cell->get_dof_indices().
Note
If the keep_independent_values flag has been set when HelperBase::start_recording_operations() is called then the tape is immediately usable after creation, and the values of the independent variables set by register_dof_values() are those at which the function is to be evaluated. In this case, a separate call to this function is not strictly necessary.

## ◆ n_independent_variables()

inherited

Return the number of independent variables that this object expects to work with. This is the dimension of the domain space.

Definition at line 225 of file ad_helpers.cc.

## ◆ n_dependent_variables()

inherited

Return the number of dependent variables that this object expects to operate on. This is the dimension of the image space.

Definition at line 232 of file ad_helpers.cc.

## ◆ print()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::print ( std::ostream & stream ) const
inherited

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 243 of file ad_helpers.cc.

## ◆ print_values()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::print_values ( std::ostream & stream ) const
inherited

Print the values currently assigned to the independent variables.

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

Definition at line 252 of file ad_helpers.cc.

## ◆ print_tape_stats()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::print_tape_stats ( const typename Types< ad_type >::tape_index tape_index, std::ostream & stream ) const
inherited

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.
Note
This function only produces meaningful output when ad_type is a taped auto-differentiable number.

Definition at line 265 of file ad_helpers.cc.

## ◆ configure_tapeless_mode()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::configure_tapeless_mode ( const unsigned int n_independent_variables, const bool ensure_persistent_setting = true )
staticinherited

Pre-specify the number of independent_variables to be used in tapeless mode.

Although this function is called internally in the HelperBase constructor, there may be occasions when ADOL-C tapeless numbers (adtl::adoubles) are created before an instance of this class is created. This function therefore allows one to declare at the earliest possible instance how many directional derivatives will be considered in tapeless mode.

Warning
With ensure_persistent_setting set to true when the ad_type is an ADOL-C tapeless number, calling this function leaves the set number of directional derivatives in a persistent state. It will therefore not be possible to further modify the number of directional derivatives to be tracked by adtl::adoubles's during course of the program's execution.

Definition at line 294 of file ad_helpers.cc.

## ◆ reset()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::reset ( const unsigned int n_independent_variables = ::numbers::invalid_unsigned_int, const unsigned int n_dependent_variables = ::numbers::invalid_unsigned_int, const bool clear_registered_tapes = true )
virtualinherited

Reset the state of the helper class.

When an instance of an HelperBase is stored as a class member object with the intention to reuse its instance, it may be necessary to reset the state of the object before use. This is because, internally, there is error checking performed to ensure that the correct auto-differentiable data is being tracked and used only when appropriate. This function clears all member data and, therefore, allows the state of all internal flags to be safely reset to their initial state.

In the rare case that the number of independent or dependent variables has changed, this can also reconfigured by passing in the appropriate arguments to the function.

Parameters
 [in] n_independent_variables The number of independent variables that will be used in the definition of the functions that it is desired to compute the sensitivities of. In the computation of $$\mathbf{f}(\mathbf{X})$$, this will be the number of inputs $$\mathbf{X}$$, i.e., the dimension of the domain space. [in] n_dependent_variables The number of scalar functions to be defined that will have a sensitivity to the given independent variables. In the computation of $$\mathbf{f}(\mathbf{X})$$, this will be the number of outputs $$\mathbf{f}$$, i.e., the dimension of the image space. [in] clear_registered_tapes A flag that indicates the that list of registered_tapes must be cleared. If set to true then the data structure that tracks which tapes have been recorded is cleared as well. It is then expected that any preexisting tapes be re-recorded.
Note
This also resets the active tape number to an invalid number, and deactivates the recording mode for taped variables.

Definition at line 340 of file ad_helpers.cc.

## ◆ is_recording()

inherited

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

Definition at line 351 of file ad_helpers.cc.

## ◆ active_tape_index()

inherited

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

Definition at line 358 of file ad_helpers.cc.

## ◆ is_registered_tape()

 bool Differentiation::AD::HelperBase< ADNumberTypeCode, double >::is_registered_tape ( const typename Types< ad_type >::tape_index tape_index ) const
inherited

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

Definition at line 365 of file ad_helpers.cc.

## ◆ set_tape_buffer_sizes()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::set_tape_buffer_sizes ( const typename Types< ad_type >::tape_buffer_sizes obufsize = 64 * 1024 * 1024, const typename Types< ad_type >::tape_buffer_sizes lbufsize = 64 * 1024 * 1024, const typename Types< ad_type >::tape_buffer_sizes vbufsize = 64 * 1024 * 1024, const typename Types< ad_type >::tape_buffer_sizes tbufsize = 64 * 1024 * 1024 )
inherited

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 394 of file ad_helpers.cc.

## ◆ start_recording_operations()

 bool Differentiation::AD::HelperBase< ADNumberTypeCode, double >::start_recording_operations ( const typename Types< ad_type >::tape_index tape_index, const bool overwrite_tape = false, const bool keep_independent_values = true )
inherited

Enable recording mode for a given tape. The use of this function is mandatory if the auto-differentiable number is a taped type. However, for the purpose of developing generic code, it can also be safely called for tapeless auto-differentiable numbers.

The operations that take place between this function call and that of stop_recording_operations() are recorded to the tape and can be replayed and reevaluated as necessary.

The typical set of operations to be performed during this "recording" phase (between the calls to start_recording_operations() and stop_recording_operations() ) are:

• Definition of some independent variables via register_independent_variable() or register_independent_variables(). These define the branch of operations tracked by the tape. If the keep flag is set to true then these represent precisely the point about which the function derivatives are to be computed. If the keep flag is set to false then these only represent dummy values, and the point at which the function derivatives are to be computed must be set by calling set_independent_variables() again.
• Extraction of a set of independent variables of auto-differentiable type using get_sensitive_variables(). These are then tracked during later computations.
• Defining the dependent variables via register_dependent_variable() or register_dependent_variables(). These are the functions that will be differentiated with respect to the independent variables.
Parameters
 [in] tape_index The index of the tape to be written [in] overwrite_tape Express whether tapes are allowed to be overwritten. If true then any existing tape with a given tape_index will be destroyed and a new tape traced over it. [in] keep_independent_values Determines whether the numerical values of all independent variables are recorded in the tape buffer. If true, then the tape can be immediately used to perform computations after recording is complete.
Note
During the recording phase, no value(), gradient(), hessian(), or jacobian() operations can be performed.
The chosen tape index must be greater than Numbers<ad_type>::invalid_tape_index and less than Numbers<ad_type>::max_tape_index.

Definition at line 450 of file ad_helpers.cc.

## ◆ stop_recording_operations()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::stop_recording_operations ( const bool write_tapes_to_file = false )
inherited

Disable recording mode for a given tape. The use of this function is mandatory if the auto-differentiable number is a taped type. However, for the purpose of developing generic code, it can also be safely called for tapeless auto-differentiable numbers.

Note
After this function call, the tape is considered ready for use and operations such as value(), gradient() or hessian() can be executed.
For taped AD numbers, this operation is only valid in recording mode.

Definition at line 467 of file ad_helpers.cc.

## ◆ activate_recorded_tape()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::activate_recorded_tape ( const typename Types< ad_type >::tape_index tape_index )
inherited

Select a pre-recorded tape to read from.

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

Definition at line 479 of file ad_helpers.cc.

## ◆ recorded_tape_requires_retaping()

 bool Differentiation::AD::HelperBase< ADNumberTypeCode, double >::recorded_tape_requires_retaping ( const typename Types< ad_type >::tape_index tape_index ) const
inherited

Return a flag that, when true, indicates that the retaping of the dependent function is necessary for a reliable computation to be performed on a tape with the given tape_index. 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.

For the output of this function to be meaningful, it must be called after activate_recorded_tape() is called and the new evaluation point for the tape (i.e. values of the independent variables) have been set and subsequently used (i.e. in the determination of the values or derivatives of the dependent variables).

Definition at line 522 of file ad_helpers.cc.

## ◆ active_tape_requires_retaping()

inherited

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.

For the output of this function to be meaningful, it must be called after activate_recorded_tape() is called and the new evaluation point for the tape (i.e. values of the independent variables) have been set and subsequently used (i.e. in the determination of the values or derivatives of the dependent variables).

Definition at line 565 of file ad_helpers.cc.

## ◆ clear_active_tape()

inherited

Clears and removes the currently active tape.

This is typically only necessary when branch switching is detected on the original tape at evaluation point. This state can be checked using the active_tape_requires_retaping() function.

Definition at line 575 of file ad_helpers.cc.

## ◆ activate_tape()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::activate_tape ( const typename Types< ad_type >::tape_index tape_index, const bool read_mode )
protectedinherited

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. [in] read_mode A flag that marks whether or not we expect to read data from a preexisting tape.
Note
The chosen tape index must be greater than Numbers<ad_type>::invalid_tape_index and less than Numbers<ad_type>::max_tape_index.

Definition at line 618 of file ad_helpers.cc.

## ◆ reset_registered_independent_variables()

protectedinherited

Reset the boolean vector registered_independent_variable_values that indicates which independent variables we've been manipulating for the current set of operations.

Definition at line 665 of file ad_helpers.cc.

## ◆ set_sensitivity_value()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::set_sensitivity_value ( const unsigned int index, const scalar_type & value )
protectedinherited

Set the actual value of the independent variable $$X_{i}$$.

Parameters
 [in] index The index in the vector of independent variables. [in] value The value to set the index'd independent variable to.

Definition at line 674 of file ad_helpers.cc.

## ◆ mark_independent_variable()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::mark_independent_variable ( const unsigned int index, ad_type & out ) const
protectedinherited

Initialize an independent variable $$X_{i}$$ such that subsequent operations performed with it are tracked.

Note
Care must be taken to mark each independent variable only once.
The order in which the independent variables are marked defines the order of all future internal operations. They must be manipulated in the same order as that in which they are first marked. If not then, for example, ADOL-C won't throw an error, but rather it might complain nonsensically during later computations or produce garbage results.
Parameters
 [in] index The index in the vector of independent variables. [out] out An auto-differentiable number that is ready for use in computations. The operations that are performed with it are recorded on the tape and will be considered in the computation of dependent variable values.

Definition at line 695 of file ad_helpers.cc.

## ◆ finalize_sensitive_independent_variables()

protectedinherited

Finalize the state of the independent variables before use.

This step and the storage of the independent variables is done separately because some derived classes may offer the capability to add independent variables in a staggered manner. This function is to be triggered when these values are considered finalized and we can safely initialize the sensitive equivalents of those values.

Definition at line 708 of file ad_helpers.cc.

## ◆ initialize_non_sensitive_independent_variable()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::initialize_non_sensitive_independent_variable ( const unsigned int index, ad_type & out ) const
protectedinherited

Initialize an independent variable $$X_{i}$$.

Parameters
 [out] out An auto-differentiable number that is ready for use in standard computations. The operations that are performed with it are not recorded on the tape, and so should only be used when not in recording mode. [in] index The index in the vector of independent variables.

Definition at line 720 of file ad_helpers.cc.

## ◆ n_registered_independent_variables()

protectedinherited

The number of independent variables that have been manipulated within a set of operations.

Definition at line 728 of file ad_helpers.cc.

## ◆ reset_registered_dependent_variables()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::reset_registered_dependent_variables ( const bool flag = false )
protectedinherited

Reset the boolean vector registered_marked_dependent_variables that indicates which independent variables have been manipulated by the current set of operations. All entries in the vector are set to the value of the flag.

Definition at line 763 of file ad_helpers.cc.

## ◆ n_registered_dependent_variables()

protectedinherited

The number of dependent variables that have been registered.

Definition at line 769 of file ad_helpers.cc.

## ◆ register_dependent_variable()

 void Differentiation::AD::HelperBase< ADNumberTypeCode, double >::register_dependent_variable ( const unsigned int index, const ad_type & func )
protectedinherited

Register the definition of the index'th dependent variable $$f(\mathbf{X})$$.

Parameters
 [in] index The index of the entry in the global list of dependent variables that this function belongs to. [in] func The recorded function that defines a dependent variable.
Note
Each dependent variable must only be registered once.

Definition at line 783 of file ad_helpers.cc.

## ◆ taped_driver

protectedinherited

An object used to help manage stored tapes.

In the event that the ad_type is a tapeless AD type, then the object constructed here is, effectively, a dummy one.

Definition at line 591 of file ad_helpers.h.

## ◆ tapeless_driver

protectedinherited

An object used to help manage tapeless data structures.

In the event that the ad_type is a taped AD type, then the object constructed here is, effectively, a dummy one.

Definition at line 599 of file ad_helpers.h.

## ◆ independent_variable_values

mutableprotectedinherited

A set of independent variables $$\mathbf{X}$$ that differentiation will be performed with respect to.

The gradients and Hessians of dependent variables will be computed at these finite values.

Definition at line 635 of file ad_helpers.h.

## ◆ independent_variables

mutableprotectedinherited

A set of sensitive independent variables $$\mathbf{X}$$ that differentiation will be performed with respect to.

The gradients and Hessians of dependent variables will be computed using these configured AD numbers. Note that only reverse-mode AD requires that the sensitive independent variables be stored.

Definition at line 645 of file ad_helpers.h.

## ◆ registered_independent_variable_values

protectedinherited

A list of registered independent variables that have been manipulated for a given set of operations.

Definition at line 651 of file ad_helpers.h.

## ◆ registered_marked_independent_variables

mutableprotectedinherited

A list of registered independent variables that have been extracted and their sensitivities marked.

Definition at line 657 of file ad_helpers.h.

## ◆ dependent_variables

protectedinherited

The set of dependent variables $$\mathbf{f}(\mathbf{X})$$ of which the derivatives with respect to $$\mathbf{X}$$ will be computed.

The gradients and Hessians of these dependent variables will be computed at the values $$\mathbf{X}$$ set with the set_sensitivity_value() function.

Note
These are stored as an ad_type so that we can use them to compute function values and directional derivatives in the case that tapeless numbers are used

Definition at line 749 of file ad_helpers.h.