Introduction

The NAG AD Library implements Automatic Differentiation (AD)
on a variety of algorithms from the NAG Library. It builds on the
functionality of dco/c++ and delivers first and second order
derivatives via forward and reverse mode AD
(see NAG and Algorithmic Differentiation). A subset of the supported AD
algorithms has been optimized by using symbolic differentiation (see
Section 3.3.2), which gives substantial savings in runtime and
memory consumption. The NAG AD Library comes with C++ interfaces which
allow seamless use with dco/c++. Read about Algorithmic Differentiation in More Depth on the NAG website.

The NAG AD Library can be used from other languages and with
other AD tools. For details, please contact NAG. Though
this documentation is meant to be self-contained, full details of
how to use the NAG Library and its documentation may be of
interest and can be found in How to Use the NAG Library.

The Library is designed to work seamlessly with dco/c++, however being a compiled
library, it only supports a subset of the features. The following data types are supported to
compute the primal (the underlying non-AD algorithm) and first and second order derivatives:

Primal (or passive values) | double |

First order tangent | dco::gt1s<double>::type |

First order adjoint | dco::ga1s<double>::type |

Second order tangent | dco::gt1s<dco::gt1s<double>::type>::type |

Second order adjoint | dco::ga1s<dco::gt1s<double>::type>::type |

First order vector types | types listed in individual routine documentation |

Second order vector types | types listed in individual routine documentation |

Not all routines have second order or vector versions. However where these exist, they can be found
highlighted on the Chapter Contents
pages.

Additionally, the Library supports chunk and blob tapes (see the dco/c++ documentation for more details) by setting a preprocessor define:

Preprocessor define | |
---|---|

blob tape | none |

chunk tape | -DDCO_CHUNK_TAPE |

Blob tape gives the best performance but requires the user to set the maximum tape size upfront. On
Linux, huge tape sizes can be specified safely since the operating system only allocates memory when it is
used.

When using the NAG AD Library by including nagad.h, dco.hpp gets included as well.
In case you want to use the interface of the NAG AD Library without dco/c++, you can define
NAGAD_SKIP_DCO_HPP_INCLUDE to skip the include of dco.hpp.

On Windows, the operating system allocates and initializes memory in debug builds, when the program requests it,
hence requesting huge tape sizes is not advised. Windows users are advised to start with chunk tape, and
then consider switching to blob tape as a performance optimization.

Linux users should also consider enabling huge pages if the program ends up using a lot of tape
memory. Performance can be improved when dco/c++ uses huge pages (see the corresponding sections in
the dco/c++ documentation).

All dco/c++ features with the data types listed in the
table above can be used. These include, for example, checkpointing, Jacobian preaccumulation, or
external adjoint vectors. For more information on these and other features of dco/c++,
see the NAG website. If you
require dco/c++ features which are currently not supported by the NAG AD Library, e.g., modulo adjoint
vector, please email your suggestions to NAG.

The package consists of a set of C++ headers and precompiled libraries. Details on how to build and
link an executable are given in the **Users' Note**.

The C++ interfaces of the routines are overloaded and can be used to compute primal values (the
underlying non-AD algorithm) with double type, as well as first and second
order derivatives with dco/c++ data types (the supported types are
in Section 2). Every routine comes with an example using each
of the types. See f07ca for an example.

All routines take as the first argument a nag::ad::handle_t object. This can be used to switch
between algorithmic and symbolic differentiation strategies. The same object is also forwarded as the first
argument to any user-supplied callbacks. The callback should only need to interact with this object if
users are implementing a nag::ad::symbolic_expert strategy (see
below). Otherwise, the nag::ad::handle_t object can be ignored inside the user callback.

nag::ad::handle_t has constructors (default, copy, move) as well as assignment operators
(copy, move). Default constructor and copy operations may throw exceptions of
type std::bad_alloc or nag::ad::exception_t which derives
from std::exception. When the default constructor detects incompatibility between
the included dco/c++ and the Library backend, it will throw
a nag::ad::exception_t.

In addition, nag::ad::handle_t has the following member functions:

void set_strategy(strategy_e strategy) |
Sets the differentiation strategy to be used with the following enum:
enum nag::ad::strategy_e { algorithmic, symbolic, symbolic_expert };See Section 3.3.3 for more details. |

active_inputs_e active_inputs() |
In symbolic expert mode, the user-supplied callback implementation needs to provide specific code paths depending on which set of inputs is “active” (see Section 3.3.3 below). The callback can call this function to see which set of inputs is currently “active”. The following enum is returned:
enum nag::ad::active_inputs_e { none, state, params, all };Explaining these values in an abstract setting leads to rather abstract documentation. Instead, we have documented these values in the example programs of the routines which support a symbolic expert strategy. This provides the most concrete advice on how these values should be used. |

It is not necessary to create a new handle object each time a NAG routine is called. The same handle
object can be reused when calling different routines. In this case, please ensure the correct/desired
settings (e.g., AD strategy) are set.

AD strategy refers to the method for computing the derivatives. The handle object is used
to configure the AD strategy to be used (see Section 3.2).

Since we use dco/c++ internally to generate the AD routines, by default, all routines
compute algorithmic derivatives. This refers to the case where dco/c++ is used on a
scalar operation level to facilitate the calculation of the derivatives.

For some routines, properties of the underlying mathematical problem can be exploited, yielding a more
efficient implementation for the derivative computation. We call this a symbolic derivative. The
efficiency gains depend on the specific routine. Examples of cases with huge benefits are the linear and
nonlinear solvers. For more on the symbolic treatment of linear solvers see Giles (2008) and for
nonlinear solvers see Naumann et al. (2015). Descriptions of how the derivative is computed symbolically
are provided in the respective routine documentation.
The Chapter Contents
pages highlight routines that offer symbolic derivatives.

The AD strategy can be set via the handle object (see Section 3.2) with one
of the supported enum values:

nag::ad::algorithmic |
This is the default strategy, see Section 3.3.1. |

nag::ad::symbolic |
This enables the symbolic derivative implementation, if available. No further changes are required compared to the algorithmic case. |

nag::ad::symbolic_expert |
For routines with user-supplied callbacks, users can take advantage of this strategy. Derivatives are
computed symbolically here as well, but the callback must provide a more specialised implementation which usually improves overall performance. The symbolic implementation of a
nonlinear solver, for example, first needs to solve the nonlinear system passively, i.e., without
propagating derivatives (neither in forward mode, nor in reverse mode). This means the callback could
call lower-order arithmetic while in this stage (double in first
and dco::gt1s<double>::type in second order), which is usually more efficient. The set of inputs is
partitioned into two groups, ‘state’ and ‘parameters’, and the solver will tell the callback which group
is currently active. Full details on how to implement this more specialised callback can be found in
the example programs of the routines which support the symbolic expert strategy. |

When using reverse mode AD, program variables store a virtual
address to their derivative component. This virtual address changes
when a variable gets overwritten. If a variable x is overwritten,
and derivatives with respect to it are required (by
calling dco::derivative(x)), then a copy of x must be stored so
that correct derivatives can be retrieved at the end of the
program (e.g., f07ca example program).
This is not NAG AD Library specific but is a feature of many AD tools including dco/c++.

NAG AD Library routines use the same error reporting mechanism as the main Library (described
in Section 4 in the Introduction to the NAG Library FL Interface). AD routines have additional error exits, which
are either related to dco/c++ or to cases where the derivatives could not be computed accurately. All exit
codes specific to a routine are described in its corresponding documentation.

Dunford N, Schwartz J T, Bade W G and Bartle R G (1971) *Linear Operators* Wiley Interscience, New York

Giles M (2008) *Collected Matrix Derivative Results for Forward and Reverse Mode Algorithmic Differentiation* Springer

Griewank A and Walther A (2008) Evaluating Derivatives: Principles and Techniques of Algorithmic Differentiation (2nd Edition) *SIAM*

Hascoët L, Naumann U and Pascual V (2005) ‘To be Recorded’ Analysis in Reverse-Mode Automatic Differentiation *Future Generation Computer Systems* **21(8)** 299–304 Elsevier

Naumann U (2012) The Art of Differentiating Computer Programs: An Introduction to Algorithmic Differentiation *SIAM*

Naumann U, Lotz J, Leppkes K, Towara M (2015) Algorithmic Differentiation of Numerical Methods: Tangent and Adjoint Solvers for Parameterized Systems of Nonlinear Equations *ACM Trans. Math. Softw.*