Reference documentation for deal.II version Git d902c8c1aa 2019-12-15 00:36:45 -0500

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

[legend]

## Public Types

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

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

## Public Member Functions

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

virtual ~VectorFunction ()=default

PointLevelFunctionsBase (const unsigned int n_independent_variables, const unsigned int n_dependent_variables)

virtual ~PointLevelFunctionsBase ()=default

void set_independent_variables (const std::vector< scalar_type > &values)

template<typename ValueType , typename ExtractorType >
void set_independent_variable (const ValueType &value, const ExtractorType &extractor)

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) override

void register_independent_variables (const std::vector< scalar_type > &values)

template<typename ValueType , typename ExtractorType >
void register_independent_variable (const ValueType &value, const ExtractorType &extractor)

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

template<typename ExtractorType >
internal::Extractor< dim, ExtractorType >::template tensor_type< ad_typeget_sensitive_variables (const ExtractorType &extractor) const

HelperBase (const unsigned int n_independent_variables, const unsigned int n_dependent_variables)

virtual ~HelperBase ()=default

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

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 ()

## Dependent variables

void register_dependent_variables (const std::vector< ad_type > &funcs)

template<typename ValueType , typename ExtractorType >
void register_dependent_variable (const ValueType &funcs, const ExtractorType &extractor)

void compute_values (Vector< scalar_type > &values) const

void compute_jacobian (FullMatrix< scalar_type > &jacobian) const

template<typename ExtractorType_Row >
static internal::VectorFieldValue< dim, scalar_type, ExtractorType_Row >::type extract_value_component (const Vector< scalar_type > &values, const ExtractorType_Row &extractor_row)

template<typename ExtractorType_Row , typename ExtractorType_Col >
static internal::VectorFieldJacobian< dim, scalar_type, ExtractorType_Row, ExtractorType_Col >::type extract_jacobian_component (const FullMatrix< scalar_type > &jacobian, const ExtractorType_Row &extractor_row, const ExtractorType_Col &extractor_col)

static Tensor< 0, dim, scalar_typeextract_jacobian_component (const FullMatrix< scalar_type > &jacobian, const FEValuesExtractors::Scalar &extractor_row, const FEValuesExtractors::Scalar &extractor_col)

static SymmetricTensor< 4, dim, scalar_typeextract_jacobian_component (const FullMatrix< scalar_type > &jacobian, const FEValuesExtractors::SymmetricTensor< 2 > &extractor_row, const FEValuesExtractors::SymmetricTensor< 2 > &extractor_col)

static void configure_tapeless_mode (const unsigned int n_independent_variables, const bool ensure_persistent_setting=true)

static const unsigned int dimension = dim

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

bool is_symmetric_independent_variable (const unsigned int index) const

unsigned int n_symmetric_independent_variables () const

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

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)

std::vector< scalar_typeindependent_variable_values

std::vector< bool > registered_independent_variable_values

std::vector< bool > registered_marked_independent_variables

std::vector< bool > registered_marked_dependent_variables

## Detailed Description

A helper class that facilitates the evaluation of a vector of functions, typically one that represents a collection of coupled, multi-dimensional fields. This class would typically be used to compute the linearization of a set of kinetic field variables defined at the quadrature point level.

An example of its usage in the case of linearizing the kinetic variables derived from a multi-field constitutive law might be as follows:

// Define some extractors that will help us set independent variables
// and later get the computed values related to the dependent
// variables. Each of these extractors is related to the gradient of a
// component of the solution field (in this case, displacement and
// magnetic scalar potential). Here "C" is the right Cauchy-Green
// tensor and "H" is the magnetic field.
const unsigned int n_independent_variables =
Tensor<1,dim>::n_independent_components;
// Declare how many dependent variables we expect to compute.
// In this case, we will be computing a stress field (a symmetric
// rank-2 tensor) and the magnetic induction (a vector field).
// At the same time we define some additional extractors associated
// with these kinetic fields. In general, these need not be of the same
// layout as the independent variables.
const unsigned int n_dependent_variables =
Tensor<1,dim>::n_independent_components;
// Define the helper that we will use in the AD computations for our
// scalar energy function. Note that we expect it to return values of
// type double.
n_dependent_variables);
// Compute the fields that provide the independent values.
// When the tape is being replayed, these should be set to something
// meaningful.
const Tensor<1,dim> H = ...;
const SymmetricTensor<2,dim> C = ...;
// If using a taped AD number, then at this point we would initiate
// taping of the expression for the material stored energy function
// for this particular set of material parameters:
// Select a tape number to record to
const typename Types<ADNumberType>::tape_index tape_index = ...;
// Indicate that we are about to start tracing the operations for
// function evaluation on the tape. If this tape has already been
// used (i.e. the operations are already recorded) then we
// (optionally) load the tape and reuse this data.
const bool is_recording
// The steps that follow in the recording phase are required for
// tapeless methods as well.
if (is_recording == true)
{
// This is the "recording" phase of the operations.
// First, we set the values for all fields.
// These could happily be set to anything, unless the function will
// be evaluated along a branch not otherwise traversed during later
// use. For this reason, in this example instead of using some dummy
// values, we'll actually map out the function at the same point
// around which we'll later linearize it.
// NOTE: We have to extract the sensitivities in the order we wish to
// introduce them. So this means we have to do it by logical order
// of the extractors that we've created.
// Here we define the stress and magnetic induction in terms
// Register the definition of the kinetic fields. The second
// argument to the function provides a non-overlapping ordering
// of the
// Indicate that we have completed tracing the operations onto
// the tape.
}
else
{
// This is the "tape reuse" phase of the operations.
// Here we will leverage the already traced operations that reside
// on a tape, and simply re-evaluate the tape at a different point
// to get the function values and their derivatives.
// Load the existing tape to be reused
// Set the new values of the independent variables where the
// recorded dependent functions are to be evaluated (and
// differentiated around).
}
// Play the tape and store the output function value, its gradient and
// linearization. These are expensive to compute, so we'll do this once
// and extract the desired values from these intermediate outputs.
// Extract the desired components of the value vector and its Jacobian
// matrix. In this example, we use them to compute the Piola-Kirchhoff
// stress tensor S and its associated tangent, defined
// as HH = 2*dS/dC...
// ... the magnetic induction B and its associated tangent defined
// as BB = dB/dH...
const Tensor<1,dim> B =
// ... and finally the magnetoelastic coupling tangent, defined
// as PP = -dS/dH. Here the order of the extractor arguments is
// especially important, as it dictates the field that is being
// differentiated, and which the directional derivatives are being
// computed.
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 3487 of file ad_helpers.h.

## ◆ scalar_type

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

Definition at line 3496 of file ad_helpers.h.

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

Definition at line 3503 of file ad_helpers.h.

## ◆ VectorFunction()

 Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::VectorFunction ( 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{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.

Definition at line 1655 of file ad_helpers.cc.

virtualdefault

Destructor.

## ◆ register_dependent_variables()

Register the definition of the vector field $$\boldsymbol{\Psi}(\mathbf{X})$$.

Parameters
 [in] funcs A vector of recorded functions that defines the dependent variables.
Note
For this class that expects only vector field 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 1670 of file ad_helpers.cc.

## ◆ register_dependent_variable()

template<typename ValueType , typename ExtractorType >
 void Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::register_dependent_variable ( const ValueType & funcs, const ExtractorType & extractor )

Register the definition of the vector field $$\hat{\mathbf{g}}(\mathbf{X}) \subset \boldsymbol{\Psi}(\mathbf{X})$$ that may represent a subset of the dependent variables.

Parameters
 [in] funcs The recorded functions that define a set of dependent variables. [in] extractor An extractor associated with the input field variables. This effectively defines which components of the global set of dependent variables this field is associated with.
Note
The input extractor must correspond to the input ValueType. So, for example, if a value is a rank-1 tensor (i.e. of type Tensor<1,dim,scalar_type>), then the extractor must be an FEValuesExtractors::Vector or FEValuesExtractors::Tensor<1>.
For taped AD numbers, this operation is only valid in recording mode.

## ◆ compute_values()

 void Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::compute_values ( Vector< scalar_type > & values ) const

Compute the value of the vector field $$\boldsymbol{\Psi}(\mathbf{X})$$.

Parameters
 [out] values A Vector object with the value for each component of the vector field evaluated at the point defined by the independent variable values. The output values vector has a length corresponding to n_dependent_variables.

Definition at line 1686 of file ad_helpers.cc.

## ◆ compute_jacobian()

 void Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::compute_jacobian ( FullMatrix< scalar_type > & jacobian ) const

Compute the Jacobian (first derivative) of the vector field with respect to all independent variables, i.e.

$\mathbf{J}(\boldsymbol{\Psi}) = \frac{\partial\boldsymbol{\Psi}(\mathbf{X})}{\partial\mathbf{X}}$

Parameters
 [out] jacobian A FullMatrix with the gradient of each component of the vector field evaluated at the point defined by the independent variable values. The output jacobian matrix has dimensions corresponding to n_dependent_variables $$\times$$n_independent_variables.

Definition at line 1742 of file ad_helpers.cc.

## ◆ extract_value_component()

template<typename ExtractorType_Row >
 static internal:: VectorFieldValue::type Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::extract_value_component ( const Vector< scalar_type > & values, const ExtractorType_Row & extractor_row )
static

Extract the set of functions' values for a subset of dependent variables $$\mathbf{g} \subset \boldsymbol{\Psi}(\mathbf{X})$$.

Parameters
 [in] values A Vector object with the value for each component of the vector field evaluated at the point defined by the independent variable values. [in] extractor_row An extractor associated with the input field variables. This effectively defines which components of the global set of dependent variables this field is associated with.

## ◆ extract_jacobian_component() [1/3]

template<typename ExtractorType_Row , typename ExtractorType_Col >
 static internal::VectorFieldJacobian::type Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::extract_jacobian_component ( const FullMatrix< scalar_type > & jacobian, const ExtractorType_Row & extractor_row, const ExtractorType_Col & extractor_col )
static

Extract the Jacobian of the subset of dependent functions $$\mathbf{g} \subset \boldsymbol{\Psi}(\mathbf{X})$$ for a subset of independent variables $$\mathbf{A} \subset \mathbf{X}$$, i.e.

$\mathbf{J}(\mathbf{g}) = \frac{\partial\mathbf{g}(\mathbf{X})}{\partial\mathbf{A}}$

The first index of the Jacobian matrix $$\mathbf{J}(\mathbf{g})$$ relates to the dependent variables, while the second index relates to the independent variables.

Parameters
 [in] jacobian The Jacobian of the vector function with respect to all independent variables, i.e., that returned by compute_jacobian(). [in] extractor_row An extractor associated with the input field variables for which the first index of the Jacobian is extracted. This effectively defines the correspondence between components of the global set of dependent variables and the field (representing a subset of dependent functions) associated with the extractor. [in] extractor_col An extractor associated with the input field variables for which the second index of the Jacobian is extracted. This effectively defines the correspondence between components of the global set of independent variables and the field (representing a subset of independent variables) associated with the extractor.
Returns
A Tensor or SymmetricTensor with its rank and symmetries determined by the extractor_row and extractor_col . This corresponds to subsetting a whole set of rows and columns of the Jacobian matrix, scaling those entries to take account of tensor symmetries, and then reshaping the (sub-)matrix so obtained into a tensor, the final result. For example, if extractor_row is a FEValuesExtractors::Vector and extractor_col is a FEValuesExtractors::Tensor, then the returned object is a Tensor of rank 3, with its first index associated with the field corresponding to the row extractor and the second and third indices associated with the field corresponding to the column extractor. Similarly, if extractor_row is a FEValuesExtractors::SymmetricTensor and extractor_col is a FEValuesExtractors::SymmetricTensor, then the returned object is a SymmetricTensor of rank 4, with its first two indices associated with the field corresponding to the row extractor and the last two indices associated with the field corresponding to the column extractor.

## ◆ extract_jacobian_component() [2/3]

 Tensor< 0, dim, typename VectorFunction< dim, ADNumberTypeCode, ScalarType >::scalar_type > Differentiation::AD::VectorFunction< dim, ADNumberTypeCode, ScalarType >::extract_jacobian_component ( const FullMatrix< scalar_type > & jacobian, const FEValuesExtractors::Scalar & extractor_row, const FEValuesExtractors::Scalar & extractor_col )
static

Extract the Jacobian of the subset of dependent functions $$\mathbf{g} \subset \boldsymbol{\Psi}(\mathbf{X})$$ for a subset of independent variables $$\mathbf{A} \subset \mathbf{X}$$, i.e.

$\mathbf{J}(\mathbf{g}) = \frac{\partial\mathbf{g}(\mathbf{X})}{\partial\mathbf{A}}$

This function is a specialization of the above for rank-0 tensors (scalars). This corresponds to extracting a single entry of the Jacobian matrix because both extractors imply selection of just a single row or column of the matrix.

Definition at line 1821 of file ad_helpers.cc.

## ◆ extract_jacobian_component() [3/3]

Extract the Jacobian of the subset of dependent functions $$\mathbf{g} \subset \boldsymbol{\Psi}(\mathbf{X})$$ for a subset of independent variables $$\mathbf{A} \subset \mathbf{X}$$, i.e.
$\mathbf{J}(\mathbf{g}) = \frac{\partial\mathbf{g}(\mathbf{X})}{\partial\mathbf{A}}$