This directory contains examples to demonstrate various features of
Adept. Type "make check" from the directory above to compile
them. 

Note that unlike in the rest of this package, the Makefile in this
directory was not generated by automake; it is well commented and so
may assist in understanding how to build software that uses Adept.


TEST 1: BASIC FEATURES

Executable: test_adept

Source files: test_adept.cpp, algorithm.cpp, algorithm.h

Demonstrates: basic use of Adept, reverse-mode automatic
differentiation, computing the Jacobian matrix, printing diagnostic
information, verifying results by comparing to numerical calculations,
pausing and continuing recordings

Synopsis: This program demonstrates how to differentiate a simple
function (in algorithm.cpp), comparing the results from automatic
differentiation with numerical differentiation. The function used is
the contrived example from the Adept paper.


TEST 2: COMPILING SOURCE FILES TWICE, WITH AND WITHOUT AUTOMATIC
DIFFERENTIATION

Executable: test_adept_with_and_without_ad

Source files: test_adept_with_and_without_ad.cpp, algorithm.cpp,
algorithm.h, algorithm_with_and_without_ad.h

Demonstrates: most of the same features as TEST_ADEPT, plus compiling
a source file twice

Synopsis: This program is the same as in Test 1, except that
algorithm.cpp is compiled twice, once with automatic differentiation
(producing the object file algorithm.o) and once without (producing
the object file algorithm_noad.o). This is achieved in the Makefile
using the -DADEPT_NO_AUTOMATIC_DIFFERENTIATION flag. This provides two
overloaded versions of the "algorithm" function, one that takes active
"adouble" arguments, and the other that takes inactive "double"
arguments. The two versions are declared in the
algorithm_with_and_without_ad.h header file.


TEST 3: RADIANCE SIMULATION

Executable: test_radiances

Source files: test_radiances.cpp, simulate_radiances.cpp,
simulate_radiances.h

Demonstrates: activation and deactivation of an Adept stack, using
more than one Adept stack in the same program (but not at the same
time), how to interface Adept with software that computes its own
Jacobian

Synopsis: The "main" function is in test_radiances.cpp, and
demonstrates how to interface Adept to an algorithm that does not have
an Adept interface, but which provides its own Jacobian. The algorithm
in this case is in simulate_radiances.cpp; while it does not have an
Adept interface, it does use Adept internally to compute the Jacobian
that it returns. It therefore needs to temporarily deactivate the
calling function's Adept stack (where derivative information is
stored) while using its own.  This example is from the Adept
documentation.


TEST 4: GSL MINIMIZATION INTERFACE

Executable: test_gsl_interface

Command-line arguments: optionally, the executable name can be
followed by an integer (which should be 2 or greater) expressing the
number of dimensions of the minimization problem.  The default is 2.

Source files: test_gsl_interface.cpp, rosenbrock_banana_function.cpp,
state.cpp, state.h

Pre-requisites: the GNU Scientific Library should be installed; on an
RPM-based system you want the "gsl" and "gsl-devel" packages. If this
is not available at the time the configure script is run, this
executable will not be built.

Demonstrates: interface with the multi-dimensional minimization
capability of the GNU Scientific Library, use of Adept to minimize a
real function, an object-oriented way to store Adept data for a
minimization problem

Synopsis: The "main" function is in test_gsl_interface.cpp and is
fairly self-explanatory. The state.cpp and state.h files show how
Adept data can be stored and accessed in an object-oriented way. The
function to be minimized is the N-dimensional Rosenbrock banana
function, given in rosenbrock_banana_function.cpp.


TEST 5: TRIVIAL EXAMPLE IN ADEPT PAPER

Executable: test_misc

Source files: test_misc.cpp, algorithm.cpp, algorithm.h

Demonstrates: basic use of Adept, reverse-mode automatic
differentiation

Synopsis: This program is simply the trivial example in the Adept
paper, using the same algorithm as in Test 1.


TEST 6: CHECKPOINTING

Executable: test_checkpointing

Source files: test_checkpoint.cpp

Demonstrates: checkpointing

Synopsis: Large algorithms, particularly those that involve
time-dependent simulations, can require a lot of memory when used with
an automatic-differentiation tool. Even if enough memory is available,
the speed may be sub-optimal.  This program demonstrates the
checkpointing technique, where a simulation using the "Toon" algorithm
in the Adept paper is first run with 10,000 timesteps, and then in 100
blocks of 100 timesteps (the checkpointed simulation), with the output
stored after each block so that the reverse pass of the automatic
differentiation needs 100 times less memory. The resulting gradients
are output to verify that the two versions produce the results, and
the timings of the two are presented as well.


TEST 7: THREAD SAFETY

Executable: test_thread_safe

Source files: test_thread_safe.cpp

Demonstrates: use of Adept in multi-threaded applications, thread
safety, comparison of Jacobian matrices computed using the forward and
reverse methods

Synopsis: This program computes the 128-128 Jacobian matrix of an
algorithm 16 times with different inputs.  The Jacobian matrix is
actually computed twice, once with 128 forward passes through the
derivative statements and once with 128 reverse passes through the
derivative statements, and a check is performed to see that the
root-mean-squared difference is within some tolerance.
  The default behaviour (and if the "-parallel" command-line argument
is provided) is to use OpenMP to run the 16 computations in parallel.
In this instance the 128 passes required to compute the Jacobian
matrices will be computed using just a single thread. If the "-serial"
command-line argument is provided then the 16 computations are carried
out in series.  In this instance, the Adept library is able to run the
Jacobian-matrix calculation in parallel (this behaviour is automatic
if the program is compiled with the -fopenmp option).
  If the program is compiled with the ADEPT_STACK_THREAD_UNSAFE
preprocessor variable defined, or on platforms that don't support
thread-local variables (e.g. some Mac platforms), then the program
should abort in the "-parallel" case ONLY.



TEST 8: COMPILING WITHOUT EXTERNAL ADEPT LIBRARY

Executable: test_no_lib

Source files: test_no_lib.cpp algorithm.cpp algorithm.h

Demonstrates: use of adept_source.h to create an executable without
the need to the external Adept library

Synopsis: This is basically the same as test_misc.cpp, but one of the
source files includes adept_source.h (rather than adept.h), which
contains the source code for the Adept library. This means that no
linking to an external Adept library (via -ladept) is required. This
capability makes it easier to distribute a package that can be used on
the widest range of operating systems, particularly those like
Microsoft Windows that cannot natively run the configure shell script.



TEST 9a,b,c,d: ARRAY FUNCTIONALITY

Executables: (a) test_arrays, (b) test_arrays_active, (c)
test_arrays_active_pausable, (d) test_complex_arrays

Source files: test_arrays.cpp

Demonstrates: array functionality for (a) passive arrays, (b) active
arrays, (c) active arrays but with stack recording "paused", (d)
complex arrays.



TEST 10: ARRAY SPEED

Executable: test_array_speed

Source files: test_array_speed.cpp

Demonstrates: speed of arrays versus for loops



TEST 11: RADIANCE SIMULATION WITH ARRAYS

Executable: test_radiances_array

Source files: test_radiances_array.cpp, simulate_radiances.cpp,
simulate_radiances.h

Demonstrates: use of arrays with add/append_derivative_dependence



TEST 12a,b: FIXED-ARRAY FUNCTIONALITY

Executables: (a) test_fixed_arrays, (b) test_fixed_arrays_active

Source file: test_fixed_arrays.cpp

Demonstrates: functionality of fixed arrays, i.e. those whose
dimensions are set at compile time: (a) passive version, and (b)
active version.



TEST 13: ARRAY CONSTRUCTORS

Executable: test_constructors

Source file: test_constructors.cpp

Demonstrates: different ways of constructing, assigning and linking
arrays, and passing them to and from functions.



TEST 14: DERIVATIVES

Exeutable: test_derivatives

Source file: test_derivatives.cpp

Demonstrates: validity of the automatic differentiation of all
mathematical functions supported by Adept, via finite differencing.



TEST 15: ARRAY DERIVATIVES

Exeutable: test_array_derivatives

Source file: test_array_derivatives.cpp

Demonstrates: validity of the automatic differentiation of selected
array operations, on both Array types and FixedArray types.



TEST 16: THREAD-SAFE ARRAYS

Executable: test_thread_safe_arrays

Source file: test_thread_safe_arrays.cpp

Demonstrates: two ways to make accessing arrays thread safe: use the
soft_link() member function of Array and SpecialMatrix, OR compile
with ADEPT_STORAGE_THREAD_SAFE (C++11 only).



TEST 17: PACKET OPERATIONS

Executable: test_packet_operations

Source file: test_packet_operations.cpp

Demonstrates: Use of Intel or ARM intrinsics is mathematically
consistent regardless of whether code is compiled with SSE2, NEON,
AVX2 or AVX512.  You will need to recompile with (e.g. for g++)
-msse2, -mavx2 or -mavx512f (or simply march=native to use the best
instruction set available) and check that the output is the same each
time.


TEST 18: FAST EXPONENTIAL OPERATIONS

Executable: test_fastexp

Source file: test_fastexp.cpp

Demonstrates: Correctness of Adept's fast exponential function.


TEST 19: ACTIVE REDUCE OPERATIONS

Executable: test_reduce_active

Source file: test_reduce_active.cpp

Demonstrates: differentiation of reduction operations (sum, product,
maxval etc).


TEST 20: MINIMIZER

Executable: test_minimizer

Source file: test_minimizer.cpp

Demonstrates: Adept's various minimization algorithms on the
N-dimensional Rosenbrock banana function, where the (optional)
arguments are:
 1. number of dimensions, default 2
 2. minimization algorithm string, default "Levenberg-Marquardt" (also
 available: Levenberg, L-BFGS, Conjugate-Gradient,
 Conjugate-Gradient-FR; additionally, the "Newton-Levenberg-Marquardt"
 and "Newton-Levenberg" will use the exact Hessian, rather than an
 approximation
 3. maximum number of iterations, default 100
 4. gradient-norm to indicate convergence, default 0.1

The cost function value and gradient norm are reported to standard
output each iteration. To standard error is written a table of
numbers, one line per call to the function being minimized.  The first
on each line is the number of the sub-iteration, usually the number of
the call to the line-search algorithm, starting at 0. Then follows the
N values of the state vector, followed by the value of the cost
function. This can be used to plot how each minimizer progresses to
the solution.