user_guide#

View page source

cppad-20240328: CppAD User’s Manual#

_images/coin.png

CppAD is distributed by COIN-OR with the Eclipse Public License EPL-2.0 or the GNU General Public License GPL-2.0 or later.

Algorithmic Differentiation#

We refer to the automatic creation of an algorithm that computes derivative values from an algorithm that computes function values as Algorithmic Differentiation , also referred to as Automatic Differentiation or just AD. A brief introduction to AD can be found in wikipedia. The web site autodiff.org is dedicated to research about, and promoting the use of, AD.

Features#

Operator Overloading#

CppAD uses operator overloading of the C++ template class AD to compute derivatives of algorithms defined using AD objects; see the Introduction for a description of how this is accomplished.

Base Type#

The operator overloading uses a templated base type that can be user defined; see base_require . The required definitions for AD<float> and AD<double> are included as part of CppAD.

Recording Operations#

A sequence of AD < Base > operations can be recorded and stored in an AD function object . This object can then be used to evaluate function values and arbitrary order derivatives, and sparsity patterns of derivative values using the Base type.

Multi-Threading#

CppAD supports an arbitrary multi threading environment. Examples are provided using Boost threads, Posix threads, and Openmp threads.

Optimizing Operations Sequences#

During the recording of a function, the Independent variables are know and a forward dependency analysis is used to determine which operations should be recorded. Once the Dependent variables are determined, a reverse dependency analysis can be preformed. This optimize routine uses a reverse dependency analysis, and other techniques, to remove unnecessary operations.

Dynamic Parameters#

CppAD enables one to specify a vector of Dynamic parameters. The value of the function and derivatives can depend on these parameters, but no derivatives are taken with respect to these parameters. This enables CppAD to reduce the derivative calculations; e.g., the derivative of variable times a variable has two terms while a variable times a parameter only has one.

Derivative Calculations#

Arbitrary order Forward and Reverse mode derivative calculations can be preformed using an ADFun object. Easy to user drivers that compute the entire Jacobian and a specific Hessian are included.

Sparsity#

Both forward and reverse mode can be used to calculation the sparsity pattern for Jacobians and Hessians; see sparsity_pattern . Where a Jacobian or Hessian is sparse, both forward and reverse mode can be combined with the sparsity pattern to speed up the calculation of sparse derivatives . In addition, a subgraph method, that does not require a sparsity pattern, can be used to speed up these derivative calculations.

Recording Derivative Operations#

A ADFun object can be converted into an object that evaluates derivatives using the type AD < Base > ; see base2ad . This enables one to record new functions that are expressed using derivatives of other functions.

Atomic Functions#

User defined derivative calculations for arbitrary functions can also be included in a recording using atomic functions . A special checkpoint class is included which allows one to record a function and reuse it as an atomic operation in other functions. There also is a special interface for user defined unary discrete functions ; i.e., functions that depend on the independent variables but which have identically zero derivatives (e.g., a step function).

Logical Comparisons#

Logical comparisons can be included in an operation sequence using AD conditional expressions .

Vectors#

The CppAD API allows one to use any SimpleVector class. The preprocessor symbol CPPAD_TESTVECTOR is template vector class which is used for correctness testing. Many of the correctness tests use this template vector class which you can choose during the cmake configuration command.

Software Engineering#

CppAD is developed using the software engineering procedures described on the project manager’s software web page.

Testing#

Correctness#

There is an extensive set of correctness tests; see cmake_check .

Speed#

A set of programs for doing speed comparisons between Adolc, CppAD, Fadbad, and Sacado are included.

Utilities#

CppAD includes a set of C++ utilities that are useful for general operator overloaded numerical methods.

Release Notes#

This whats_new for a list of recent extensions and bug fixes.

Example#

The file get_started.cpp contains an example and test of using CppAD to compute the derivative of a polynomial. There are many other examples . All of the examples are also correctness tests, which ensures that they work properly.

Contents#