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.