atomic_three_define¶

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
)

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¶

Name	Title
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