Reference documentation for deal.II version Git 423cd11810 2020-05-28 01:07:25 +0200

#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
ScalarFunction (const unsigned int n_independent_variables)

virtual ~ScalarFunction ()=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

scalar_type compute_value () const

void compute_hessian (FullMatrix< scalar_type > &hessian) const

template<typename ExtractorType_Row >

template<typename ExtractorType_Row , typename ExtractorType_Col >
static internal::ScalarFieldHessian< dim, scalar_type, ExtractorType_Row, ExtractorType_Col >::type extract_hessian_component (const FullMatrix< scalar_type > &hessian, const ExtractorType_Row &extractor_row, const ExtractorType_Col &extractor_col)

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

static SymmetricTensor< 4, dim, scalar_typeextract_hessian_component (const FullMatrix< scalar_type > &hessian, 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< boolregistered_independent_variable_values

std::vector< boolregistered_marked_independent_variables

std::vector< boolregistered_marked_dependent_variables

## Detailed Description

A helper class that facilitates the evaluation of a scalar function, its first derivatives (gradient), and its second derivatives (Hessian). This class would typically be used to compute the first and second derivatives of a stored energy function defined at a quadrature point. It can also be used to compute derivatives of any other scalar field so long as all its dependencies on the independent variables are explicit (that is to say, no independent variables may have some implicit dependence on one another).

An example of its usage in the case of 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 =
// 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.
// 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 = ...;
// 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 material stored energy function.
// This example is sufficiently complex to warrant the use of AD to,
// at the very least, verify an unassisted implementation.
const double mu_e = 10; // Shear modulus
const double lambda_e = 15; // Lam&eacute; parameter
const double mu_0 = 4*M_PI*1e-7; // Magnetic permeability constant
const double mu_r = 5; // Relative magnetic permeability
(trace(C_AD) - dim - 2*std::log(J)) +
lambda_e*std::log(J)*std::log(J) -
// Register the definition of the total stored energy
// 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 gradient vector and Hessian
// matrix. In this example, we use them to compute the Piola-Kirchhoff
// stress tensor and its associated tangent, defined by thermodynamic
// arguments as S = 2*dpsi/dC and HH = 2*dS/dC...
// ... the magnetic induction and its associated tangent defined
// as B = -dpsi/dH and BB = dB/dH...
const Tensor<1,dim> B =
// ... and finally the magnetoelastic coupling tangent, defined
// as PP = -dS/dH = -d/dH(2*dpsi/dC). Here the order of the extractor
// arguments is especially important, as it dictates the order in which
// the directional derivatives are taken.
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 3087 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 3096 of file ad_helpers.h.

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

Definition at line 3103 of file ad_helpers.h.

## ◆ ScalarFunction()

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.

Definition at line 1326 of file ad_helpers.cc.

virtualdefault

Destructor.

## ◆ register_dependent_variable()

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

Parameters
 [in] func The recorded function that defines a dependent variable.
Note
For this class that expects only one dependent variable, this function must only be called once per tape.
For taped AD numbers, this operation is only valid in recording mode.

Definition at line 1340 of file ad_helpers.cc.

## ◆ compute_value()

Compute the value of the scalar field $$\Psi(\mathbf{X})$$ using the tape as opposed to executing the source code.

Returns
A scalar object with the value for the scalar field evaluated at the point defined by the independent variable values.

Definition at line 1353 of file ad_helpers.cc.

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

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

Parameters
 [out] gradient A Vector with the values for the scalar field gradient (first derivatives) evaluated at the point defined by the independent variable values. The output gradient vector has a length corresponding to n_independent_variables.

Definition at line 1403 of file ad_helpers.cc.

## ◆ compute_hessian()

 void Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::compute_hessian ( FullMatrix< scalar_type > & hessian ) const

Compute the Hessian (second derivative) of the scalar field with respect to all independent variables, i.e.

$\frac{\partial^{2}\Psi(\mathbf{X})}{\partial\mathbf{X} \otimes \partial\mathbf{X}}$

Parameters
 [out] hessian A FullMatrix with the values for the scalar field Hessian (second derivatives) evaluated at the point defined by the independent variable values. The output hessian matrix has dimensions corresponding to n_independent_variables $$\times$$n_independent_variables.

Definition at line 1477 of file ad_helpers.cc.

template<typename ExtractorType_Row >
static

Extract the function gradient for a subset of independent variables $$\mathbf{A} \subset \mathbf{X}$$, i.e.

$\frac{\partial\Psi(\mathbf{X})}{\partial\mathbf{A}}$

Parameters
 [in] gradient The gradient of the scalar function with respect to all independent variables, i.e., that returned by compute_gradient(). [in] extractor_row An extractor associated with the input field variables. This effectively defines which components of the global set of independent variables this field is associated with.
Returns
A Tensor or SymmetricTensor with its rank and symmetries determined by the extractor_row. This corresponds to subsetting a whole set of rows of the gradient vector, scaling those entries to take account of tensor symmetries, and then reshaping the (sub-)vector 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_hessian_component() [1/3]

template<typename ExtractorType_Row , typename ExtractorType_Col >
 static internal::ScalarFieldHessian::type Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::extract_hessian_component ( const FullMatrix< scalar_type > & hessian, const ExtractorType_Row & extractor_row, const ExtractorType_Col & extractor_col )
static

Extract the function Hessian for a subset of independent variables $$\mathbf{A},\mathbf{B} \subset \mathbf{X}$$, i.e.

$\frac{}{\partial\mathbf{B}} \left[ \frac{\partial\Psi(\mathbf{X})}{\partial\mathbf{A}} \right] = \frac{\partial^{2}\Psi(\mathbf{X})}{\partial\mathbf{B} \otimes \partial\mathbf{A}}$

Parameters
 [in] hessian The Hessian of the scalar function with respect to all independent variables, i.e., that returned by compute_hessian(). [in] extractor_row An extractor associated with the input field variables for which the first index of the Hessian is extracted. [in] extractor_col An extractor associated with the input field variables for which the second index of the Hessian is extracted.
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 Hessian 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_hessian_component() [2/3]

 Tensor< 0, dim, typename ScalarFunction< dim, ADNumberTypeCode, ScalarType >::scalar_type > Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::extract_hessian_component ( const FullMatrix< scalar_type > & hessian, const FEValuesExtractors::Scalar & extractor_row, const FEValuesExtractors::Scalar & extractor_col )
static

Extract the function Hessian for a subset of independent variables $$\mathbf{A},\mathbf{B} \subset \mathbf{X}$$, i.e.

$\frac{}{\partial\mathbf{B}} \left[ \frac{\partial\Psi(\mathbf{X})}{\partial\mathbf{A}} \right]$

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

Definition at line 1576 of file ad_helpers.cc.

## ◆ extract_hessian_component() [3/3]

Extract the function Hessian for a subset of independent variables $$\mathbf{A},\mathbf{B} \subset \mathbf{X}$$, i.e.
$\frac{}{\partial\mathbf{B}} \left[ \frac{\partial\Psi(\mathbf{X})}{\partial\mathbf{A}} \right]$