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

Inheritance diagram for Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >:

[legend]

Public Types
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
	HelperBase (const unsigned int n_independent_variables, const unsigned int n_dependent_variables)

virtual	~HelperBase ()=default

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
TapedDrivers< ad_type, scalar_type >	taped_driver

TapelessDrivers< ad_type, scalar_type >	tapeless_driver

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

Independent variables
std::vector< scalar_type >	independent_variable_values

std::vector< ad_type >	independent_variables

std::vector< bool >	registered_independent_variable_values

std::vector< bool >	registered_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< ad_type >	dependent_variables

std::vector< bool >	registered_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

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

A base helper class that facilitates the evaluation of the derivative(s) of a number of user-defined dependent variables \(\mathbf{f}(\mathbf{X})\) with respect to a set of independent variables \(\mathbf{X}\), that is \(\dfrac{d^{i} \mathbf{f}(\mathbf{X})}{d \mathbf{X}^{i}}\).

This class is templated on the floating point type scalar_type of the number that we'd like to differentiate, as well as an enumeration indicating the ADNumberTypeCode . The ADNumberTypeCode dictates which auto-differentiation library is to be used, and what the nature of the underlying auto-differentiable number is. Refer to the Automatic and symbolic differentiation topic for more details in this regard.

For all of the classes derived from this base class, there are two possible ways that the code in which they are used can be structured. The one approach is effectively a subset of the other, and which might be necessary to use depends on the nature of the chosen auto-differentiable number.

When "tapeless" numbers are employed, the most simple code structure would be of the following form:

// Initialize AD helper
ADHelperType<tapeless_AD_typecode> ad_helper (...);
 
// Register independent variables
ad_helper.register_independent_variable(...);
 
// Extract the sensitive equivalent of the independent variables.
// They are the auto-differentiable counterparts to the values
// used as arguments to the register_independent_variable() function.
// The operations conducted with these AD numbers will be tracked.
const auto ad_independent_variables
  = ad_helper.get_sensitive_variables(...);
 
// Use the sensitive variables to compute the dependent variables.
const auto ad_dependent_variables = func(sensitive_variables);
 
// Register the dependent variables with the helper class
ad_helper.register_dependent_variables(ad_dependent_variables);
 
// Compute derivatives of the dependent variables
const auto derivatives = ad_helper.compute_gradients();

Note that since the specialized classes interpret the independent variables in different ways, above represents only an outline of the steps taken to compute derivatives. More specific examples are outlined in the individual classes that specialize this base class.

When "taped" numbers are to be used, the above code should be wrapped by a few more lines of code to manage the taping procedure:

// Initialize AD helper
ADHelperType<taped_or_tapeless_AD_typecode> ad_helper (...);
 
// An optional call to set the amount of memory to be allocated to
// storing taped data
ad_helper.set_tape_buffer_sizes();
 
 // Select a tape number to record to
const typename Types<ad_type>::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);
if (is_recording == true)
{
  // This is the "recording" phase of the operations.
  // In this block one places the majority of the operations described
  // in the previous code block. The set of operations that are
  // conducted here therefore includes the following steps:
  // - Register independent variables
  // - Extract the sensitive equivalent of the independent variables
  // - Use the sensitive variables to compute the dependent variables
  // - Register the dependent variables with the helper class
 
  // Indicate that 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 revaluate 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_no);
 
  // 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(...);
}
 
// Compute derivatives of the dependent variables
const auto derivatives = ad_helper.compute_gradients();

The second approach outlined here is more general than the first, and will work equally well for both taped and tapeless auto-differentiable numbers.

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.

Todo:: Make this class thread safe for Sacado number and ADOL-C tapeless numbers (if supported).

Definition at line 168 of file ad_helpers.h.

Member Typedef Documentation

◆ scalar_type

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

using Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::scalar_type = typename AD::NumberTraits<ScalarType, ADNumberTypeCode>::scalar_type

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

Definition at line 175 of file ad_helpers.h.

◆ ad_type

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

using Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::ad_type = typename AD::NumberTraits<ScalarType, ADNumberTypeCode>::ad_type

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

Definition at line 182 of file ad_helpers.h.

Constructor & Destructor Documentation

◆ HelperBase()

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

Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::HelperBase	(	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 37 of file ad_helpers.cc.

◆ ~HelperBase()

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

virtual Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::~HelperBase ( )

virtualdefault

Destructor

Member Function Documentation

◆ n_independent_variables()

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

std::size_t Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::n_independent_variables ( ) const

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

Definition at line 240 of file ad_helpers.cc.

◆ n_dependent_variables()

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

std::size_t Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::n_dependent_variables ( ) const

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

Definition at line 261 of file ad_helpers.cc.

◆ print()

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

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

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

◆ print_values()

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

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

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

◆ print_tape_stats()

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

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

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

◆ configure_tapeless_mode()

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

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

static

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

◆ reset()

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

void Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::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`
	)

virtual

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.

Reimplemented in Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, ScalarType >, and Differentiation::AD::PointLevelFunctionsBase< dim, ADNumberTypeCode, double >.

Definition at line 389 of file ad_helpers.cc.

◆ is_recording()

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

bool Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::is_recording ( ) const

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

Definition at line 270 of file ad_helpers.cc.

◆ active_tape_index()

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

Types< typenameHelperBase< ADNumberTypeCode, ScalarType >::ad_type >::tape_index Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::active_tape_index ( ) const

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

Definition at line 283 of file ad_helpers.cc.

◆ is_registered_tape()

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

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

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

Definition at line 295 of file ad_helpers.cc.

◆ set_tape_buffer_sizes()

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

void Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::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`
	)

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

◆ start_recording_operations()

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

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

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

◆ stop_recording_operations()

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

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

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

◆ activate_recorded_tape()

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

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

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

◆ recorded_tape_requires_retaping()

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

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

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:

ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
{
  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 483 of file ad_helpers.cc.

◆ active_tape_requires_retaping()

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

bool Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::active_tape_requires_retaping ( ) const

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:

ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
{
  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 496 of file ad_helpers.cc.

◆ clear_active_tape()

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

void Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::clear_active_tape ( )

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

◆ activate_tape()

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

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

protected

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

◆ reset_registered_independent_variables()

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

void Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::reset_registered_independent_variables ( )

protected

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

◆ set_sensitivity_value()

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

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

protected

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

◆ mark_independent_variable()

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

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

protected

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

◆ finalize_sensitive_independent_variables()

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

void Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::finalize_sensitive_independent_variables ( ) const

protected

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

◆ initialize_non_sensitive_independent_variable()

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

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

protected

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

◆ n_registered_independent_variables()

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

unsigned int Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::n_registered_independent_variables ( ) const

protected

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

Definition at line 229 of file ad_helpers.cc.

◆ reset_registered_dependent_variables()

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

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

protected

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

◆ n_registered_dependent_variables()

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

unsigned int Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::n_registered_dependent_variables ( ) const

protected

The number of dependent variables that have been registered.

Definition at line 249 of file ad_helpers.cc.

◆ register_dependent_variable()

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

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

protected

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

Member Data Documentation

◆ taped_driver

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

TapedDrivers<ad_type, scalar_type> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::taped_driver

protected

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 590 of file ad_helpers.h.

◆ tapeless_driver

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

TapelessDrivers<ad_type, scalar_type> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::tapeless_driver

protected

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 598 of file ad_helpers.h.

◆ independent_variable_values

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

std::vector<scalar_type> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::independent_variable_values

mutableprotected

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 634 of file ad_helpers.h.

◆ independent_variables

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

std::vector<ad_type> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::independent_variables

mutableprotected

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 644 of file ad_helpers.h.

◆ registered_independent_variable_values

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

std::vector<bool> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::registered_independent_variable_values

protected

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

Definition at line 650 of file ad_helpers.h.

◆ registered_marked_independent_variables

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

std::vector<bool> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::registered_marked_independent_variables

mutableprotected

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

Definition at line 656 of file ad_helpers.h.

◆ dependent_variables

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

std::vector<ad_type> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::dependent_variables

protected

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 748 of file ad_helpers.h.

◆ registered_marked_dependent_variables

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

std::vector<bool> Differentiation::AD::HelperBase< ADNumberTypeCode, ScalarType >::registered_marked_dependent_variables

protected

A list of registered dependent variables.

Definition at line 753 of file ad_helpers.h.

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

include/deal.II/differentiation/ad/ad_helpers.h
source/differentiation/ad/ad_helpers.cc

Public Types

Public Member Functions

Static Public Member Functions

Drivers and taping

Independent variables

Dependent variables

Detailed Description

Member Typedef Documentation

◆ scalar_type

◆ ad_type

Constructor & Destructor Documentation

◆ HelperBase()

◆ ~HelperBase()

Member Function Documentation

◆ n_independent_variables()

◆ n_dependent_variables()

◆ print()

◆ print_values()

◆ print_tape_stats()

◆ configure_tapeless_mode()

◆ reset()

◆ is_recording()

◆ active_tape_index()

◆ is_registered_tape()

◆ set_tape_buffer_sizes()

◆ start_recording_operations()

◆ stop_recording_operations()

◆ activate_recorded_tape()

◆ recorded_tape_requires_retaping()

◆ active_tape_requires_retaping()

◆ clear_active_tape()

◆ activate_tape()

◆ reset_registered_independent_variables()

◆ set_sensitivity_value()

◆ mark_independent_variable()

◆ finalize_sensitive_independent_variables()

◆ initialize_non_sensitive_independent_variable()

◆ n_registered_independent_variables()

◆ reset_registered_dependent_variables()

◆ n_registered_dependent_variables()

◆ register_dependent_variable()

Member Data Documentation

◆ taped_driver

◆ tapeless_driver

◆ independent_variable_values

◆ independent_variables

◆ registered_independent_variable_values

◆ registered_marked_independent_variables

◆ dependent_variables

◆ registered_marked_dependent_variables