x10ba: FL CL CPP AD

NAG AD Library
x10ba_a1w_f (callback_object_create_a1w)

Note: a1w denotes that first order adjoints are computed in working precision; this has the corresponding argument type nagad_a1w_w_rtype. Further implementations, for example for higher order differentiation or using the tangent linear approach, may become available at later marks of the NAG AD Library. The method of codifying AD implementations in the routine name and corresponding argument types is described in the NAG AD Library Introduction.

Keyword Search:

NAG Library Manual, Mark 27.1

Interfaces: FL CL CPP AD

NAG AD Interface Introduction

X10 (Adutils) Chapter Contents

X10 (Adutils) Chapter Introduction

x10ba: FL CL CPP AD

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

1 Purpose

x10ba_a1w_f creates a data object that can be used to pass data between procedure arguments (callbacks) of NAG AD Library computational routines and companion callbacks.

2 Specification

Fortran Interface

Subroutine x10ba_a1w_f (

cb_handle, ifail)

Integer, Intent (Inout)	::	ifail
Type (c_ptr), Intent (Out)	::	cb_handle

C++ Header Interface

#include <nagad.h>

extern "C" {

void	x10ba_a1w_f_ (void *&cb_handle, Integer &ifail)

}

The routine may be called by the names x10ba_a1w_f or nagf_adutils_callback_object_create_a1w.

3 Description

If a NAG AD Library routine contains a procedure argument (callback) which performs an operation on active variables, then that operation must also be differentiated. When the algorithmic computational mode is being used and the operation involves standard arithmetic operators and intrinsic functions then the differentiation is performed automatically. Similarly, even when in symbolic mode, algorithmic differentiation will be performed automatically for simple operators and functions used in supplied callbacks.

However, there are circumstances in which the algorithmic differentiation of a callback operation needs to be circumvented. Such a case would be where the symbolic differential of the operation is readily available and to be preferred to one calculated algorithmically. Another case is where the operation involves calls to, for example, NAG Library routines for which there is not yet a NAG AD Library equivalent routine. In such cases, algorithmic differentiation is circumvented by pushing the operations into a fixed interface companion callback; there can be several such companion callbacks. These companion callbacks have a single argument: a handle to a callback data object. x10ba_a1w_f creates this callback data object.

A callback data object created by x10ba_a1w_f is used to: pass data to the companion callback; set primal calculation values or derivatives; and, pass the location of the companion callback so that it may be called internally during adjoint evaluations.

Within a user-supplied procedure argument, the companion callbacks perform different tasks as requested: primal evaluation of output arguments; differentiation of output arguments with respect to real-valued input arguments; and, differentiation with respect to any user-supplied values (i.e., in the ruser array in c05ay_a1w_f).

Where algorithmic differentiation is to be circumvented with a supplied procedure argument, x10ba_a1w_f should be called to create a callback data object inside the supplied procedure. x10bd_a1w_f will return which mode of operation should be performed. A separate companion callback can be created for each mode of operation or the mode can be passed to a single companion callback to handle all three (potentially) cases.

Input data should be written to the callback data object using one of x10be_a1w_f, x10bf_a1w_f or x10bj_a1w_f depending on input data type. The companion callback will extract data from the callback data object, perform the required operations, and update the global data object with primal values or derivative increments.

4 References

None.

5 Arguments

1: $cb_handle$ – Type (c_ptr) Output: On exit: will contain a handle to the callback data object.
2: $ifail$ – Integer Input/Output: On entry: ifail must be set to $0$ , $- 1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $- 1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $- 1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit: $ifail = 0$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

x10ba_a1w_f is not threaded in any implementation.

9 Further Comments

None.

10 Example

The following example shows the procedure for calling a NAG AD Library routine (s01ba_a1w_f). x10aa_a1w_f is called to initialize the ad_handle; x10ac_a1w_f and x10ad_a1w_f are called to set and get the computational mode from the handle; and x10ab_a1w_f is called to destroy the handle.