Defining Atomic Functions: Third Generation

@(@\newcommand{\W}[1]{ \; #1 \; } \newcommand{\R}[1]{ {\rm #1} } \newcommand{\B}[1]{ {\bf #1} } \newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} } \newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} } \newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} } \newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }@)@This is cppad-20221105 documentation. Here is a link to its current documentation . Defining Atomic Functions: Third Generation
Syntax

Define Class

class atomic_user : public CppAD::atomic_three<Base> {

    ...

};

Construct Atomic Function
atomic_user afun(ctor_arg_list)

Use Atomic Function
afun(ax, ay)

Class Member Callbacks

ok = afun.for_type(

    parameter_x, type_x, type_y

)

ok = afun.forward(

    parameter_x, type_x,

    need_y, order_low, order_up, taylor_x, taylor_y

)

ok = afun.reverse(

    parameter_x, type_x,

    order_up, taylor_x, taylor_y, partial_x, partial_y

)

ok = afun.jac_sparsity(

    parameter_x, type_x, dependency, select_x select_y, pattern_out

)

ok = afun.hes_sparsity(

    parameter_x, type_x, select_x select_y, pattern_out

)

ok = afun.rev_depend(

    parameter_x, type_x, depend_x, depend_y

)

See Also
chkpoint_two , atomic_two

Purpose

Speed
In some cases, it is possible to compute derivatives of a function @[@ y = g(x) \; {\rm where} \; g : \B{R}^n \rightarrow \B{R}^m @]@ more efficiently than by coding it using AD<Base> atomic operations and letting CppAD do the rest. The class atomic_three<Base> is used to create a new atomic operation corresponding to a function @(@ g(x) @)@ where the user specifies how to compute the derivatives and sparsity patterns for @(@ g(x) @)@.

Reduce Memory
If the function @(@ g(x) @)@ is used many times during the recording of an ADFun object, using an atomic version of @(@ g(x) @)@ removes the need for repeated copies of the corresponding AD<Base> operations and variables in the recording.

ad_type
The type CppAD::ad_type_enum is used to specify if an AD object is a constant parameter dynamic parameter or variable . It has the following possible values:

`ad_type_enum`	Meaning
`constant_enum`	constant parameter
`dynamic_enum`	dynamic parameter
`variable_enum`	variable

In addition, constant_enum < dynamic_enum < variable_enum.

Virtual Functions
The callback functions are implemented by defining the virtual functions in the atomic_user class. These functions compute derivatives, sparsity patterns, and dependency relations. Each virtual function has a default implementation that returns ok == false . The for_type and forward function (for the case order_up == 0 ) must be implemented. Otherwise, only those functions and orders required by the your calculations need to be implemented. For example, forward for the case order_up == 2 can just return ok == false unless you require forward mode calculation of second derivatives.

Base
This is the base type of the elements of ax and ay in the corresponding afun(ax, ay) call; i.e., the elements of ax and ay have type AD<Base> .

parameter_x
All the virtual functions include this argument which has prototype



    const CppAD::vector<Base> parameter_x

Its size is equal to n = ax.size() in corresponding afun(ax, ay) call.

Constant
For j =0,...,n-1 , if ax[j] is a constant parameter,



    parameter_x[j] == ax[j]

Dynamic
If ax[j] is a dynamic parameter, parameter_x[j] value of ax[j] corresponding to the previous call to new_dynamic for the corresponding function object.

Variable
If ax[j] is a variable, the value of parameter_x[j] is not specified. See the atomic_three_mat_mul.hpp for an example using parameter_x .

type_x
All the virtual functions include this argument. Its size is equal to n = ax.size() in corresponding afun(ax, ay) call. For j =0,...,n-1 , if ax[j] is a constant parameter,



    type_x[j] == CppAD::constant_enum

if ax[j] is a dynamic parameter,



    type_x[j] == CppAD::dynamic_enum

if ax[j] is a variable,



    type_x[j] == CppAD::variable_enum

See the atomic_three_mat_mul.hpp for an example using type_x .

Contents

atomic_three_ctor	Atomic Function Constructor
atomic_three_afun	Using AD Version of an Atomic Function
atomic_three_for_type	Atomic Function Forward Type Calculation
atomic_three_forward	Atomic Function Forward Mode
atomic_three_reverse	Atomic Function Reverse Mode
atomic_three_jac_sparsity	Atomic Function Jacobian Sparsity Patterns
atomic_three_hes_sparsity	Atomic Function Hessian Sparsity Patterns
atomic_three_rev_depend	Atomic Function Reverse Dependency Calculation

Input File: include/cppad/core/atomic/three/atomic.hpp