Reference documentation for deal.II version 9.1.1
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
Public Types | List of all members
Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType > Class Template Reference

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

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

Public Types

using scalar_type = typename HelperBase< ADNumberTypeCode, ScalarType >::scalar_type
 
using ad_type = typename HelperBase< ADNumberTypeCode, ScalarType >::ad_type
 
- Public Types inherited from Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, ScalarType >
using scalar_type = typename HelperBase< ADNumberTypeCode, ScalarType >::scalar_type
 
using ad_type = typename HelperBase< ADNumberTypeCode, ScalarType >::ad_type
 
- Public Types inherited from Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >
using scalar_type = typename AD::NumberTraits< ScalarType, ADNumberTypeCode >::scalar_type
 
using ad_type = typename AD::NumberTraits< ScalarType, ADNumberTypeCode >::ad_type
 

Public Member Functions

Constructor / destructor
 ScalarFunction (const unsigned int n_independent_variables)
 
virtual ~ScalarFunction ()=default
 
- Public Member Functions inherited from Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, ScalarType >
 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
 
- Public Member Functions inherited from Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >
 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_variable (const ad_type &func)
 
scalar_type compute_value () const
 
void compute_gradient (Vector< scalar_type > &gradient) const
 
void compute_hessian (FullMatrix< scalar_type > &hessian) const
 
template<typename ExtractorType_Row >
static internal::ScalarFieldGradient< dim, scalar_type, ExtractorType_Row >::type extract_gradient_component (const Vector< scalar_type > &gradient, const ExtractorType_Row &extractor_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)
 

Additional Inherited Members

- Static Public Member Functions inherited from Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >
static void configure_tapeless_mode (const unsigned int n_independent_variables, const bool ensure_persistent_setting=true)
 
- Static Public Attributes inherited from Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, ScalarType >
static const unsigned int dimension = dim
 
- Protected Member Functions inherited from Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, ScalarType >
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
 
- Protected Member Functions inherited from Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >
void activate_tape (const typename Types< ad_type >::tape_index tape_index, const bool read_mode)
 
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)
 
- Protected Attributes inherited from Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >
TapedDrivers< ad_type, scalar_typetaped_driver
 
TapelessDrivers< ad_type, scalar_typetapeless_driver
 
std::vector< scalar_typeindependent_variable_values
 
std::vector< ad_typeindependent_variables
 
std::vector< bool > registered_independent_variable_values
 
std::vector< bool > registered_marked_independent_variables
 
std::vector< ad_typedependent_variables
 
std::vector< bool > registered_marked_dependent_variables
 

Detailed Description

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
class Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >

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.
using ADNumberType = typename ADHelper::ad_type;
// 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
= ad_helper.start_recording_operations(tape_index);
// 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.
ad_helper.register_independent_variable(H, H_dofs);
ad_helper.register_independent_variable(C, C_dofs);
// 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.
ad_helper.get_sensitive_variables(C_dofs);
ad_helper.get_sensitive_variables(H_dofs);
// 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; // Lame parameter
const double mu_0 = 4*M_PI*1e-7; // Magnetic permeability constant
const double mu_r = 5; // Relative magnetic permeability
const ADNumberType J = std::sqrt(determinant(C_AD));
const ADNumberType psi =
0.5*mu_e*(1.0+std::tanh((H_AD*H_AD)/100.0))*
(trace(C_AD) - dim - 2*std::log(J)) +
lambda_e*std::log(J)*std::log(J) -
0.5*mu_0*mu_r*J*H_AD*C_inv_AD*H_AD;
// Register the definition of the total stored energy
ad_helper.register_dependent_variable(psi_CH);
// Indicate that we have completed tracing the operations onto
// the tape.
ad_helper.stop_recording_operations(false); // write_tapes_to_file
}
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
ad_helper.activate_recorded_tape(tape_index);
// Set the new values of the independent variables where the
// recorded dependent functions are to be evaluated (and
// differentiated around).
ad_helper.set_independent_variable(C, C_dofs);
ad_helper.set_independent_variable(H, H_dofs);
}
// 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.
Vector<double> Dpsi (ad_helper.n_dependent_variables());
FullMatrix<double> D2psi (ad_helper.n_dependent_variables(),
ad_helper.n_independent_variables());
const double psi = ad_helper.compute_value();
ad_helper.compute_gradient(Dpsi);
ad_helper.compute_hessian(D2psi);
// 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...
2.0*ad_helper.extract_gradient_component(Dpsi,C_dofs);
4.0*ad_helper.extract_hessian_component(D2psi,C_dofs,C_dofs);
// ... the magnetic induction and its associated tangent defined
// as B = -dpsi/dH and BB = dB/dH...
const Tensor<1,dim> B =
-ad_helper.extract_gradient_component(Dpsi,H_dofs);
-symmetrize(ad_helper.extract_hessian_component(D2psi,H_dofs,H_dofs));
// ... 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.
-2.0*ad_helper.extract_hessian_component(D2psi,C_dofs,H_dofs)
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.
Author
Jean-Paul Pelteret, 2016, 2017, 2018

Definition at line 3094 of file ad_helpers.h.

Member Typedef Documentation

◆ scalar_type

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

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

Definition at line 3103 of file ad_helpers.h.

◆ ad_type

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
using Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::ad_type = typename HelperBase<ADNumberTypeCode, ScalarType>::ad_type

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

Definition at line 3110 of file ad_helpers.h.

Constructor & Destructor Documentation

◆ ScalarFunction()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::ScalarFunction ( const unsigned int  n_independent_variables)

The constructor for the class.

Parameters
[in]n_independent_variablesThe 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 1330 of file ad_helpers.cc.

◆ ~ScalarFunction()

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

Destructor.

Member Function Documentation

◆ register_dependent_variable()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
void Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::register_dependent_variable ( const ad_type func)

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

Parameters
[in]funcThe 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 1344 of file ad_helpers.cc.

◆ compute_value()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
ScalarFunction< dim, ADNumberTypeCode, ScalarType >::scalar_type Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::compute_value ( ) const

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

◆ compute_gradient()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
void Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::compute_gradient ( Vector< scalar_type > &  gradient) const

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]gradientA 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 1407 of file ad_helpers.cc.

◆ compute_hessian()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
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]hessianA 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 1481 of file ad_helpers.cc.

◆ extract_gradient_component()

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
template<typename ExtractorType_Row >
static internal:: ScalarFieldGradient<dim, scalar_type, ExtractorType_Row>::type Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::extract_gradient_component ( const Vector< scalar_type > &  gradient,
const ExtractorType_Row &  extractor_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]gradientThe gradient of the scalar function with respect to all independent variables, i.e., that returned by compute_gradient().
[in]extractor_rowAn 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<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType = double>
template<typename ExtractorType_Row , typename ExtractorType_Col >
static internal::ScalarFieldHessian<dim, scalar_type, ExtractorType_Row, ExtractorType_Col>::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]hessianThe Hessian of the scalar function with respect to all independent variables, i.e., that returned by compute_hessian().
[in]extractor_rowAn extractor associated with the input field variables for which the first index of the Hessian is extracted.
[in]extractor_colAn 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]

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
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 1580 of file ad_helpers.cc.

◆ extract_hessian_component() [3/3]

template<int dim, enum AD::NumberTypes ADNumberTypeCode, typename ScalarType >
SymmetricTensor< 4, dim, typename ScalarFunction< dim, ADNumberTypeCode, ScalarType >::scalar_type > Differentiation::AD::ScalarFunction< dim, ADNumberTypeCode, ScalarType >::extract_hessian_component ( const FullMatrix< scalar_type > &  hessian,
const FEValuesExtractors::SymmetricTensor< 2 > &  extractor_row,
const FEValuesExtractors::SymmetricTensor< 2 > &  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-4 symmetric tensors.

Definition at line 1617 of file ad_helpers.cc.


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