Adept: Automatic Differentiation using Expression Templates
Version: 2.0, September 2017
By Robin Hogan <r.j.hogan@ecmwf.int>


INTRODUCTION

The Adept version 2 software library provides two different
functionalities:

- Its array capability provides support for vectors, matrices, arrays
  of up to 7 dimensions and linear algebra.

- Its automatic differentiation capability enables algorithms written
  in C++ to be differentiated with little code modification, very
  useful for a wide range of applications that involve mathematical
  optimization. It is backwards compatible with and as fast as Adept
  1.1.

Adept 2 uses a single expression template framework under the hood to
get good performance for both of these aspects. The web site is at
http://www.met.reading.ac.uk/clouds/adept/ where you can find the
latest version of the code.

The web site for Adept version
1.1. (http://www.met.reading.ac.uk/clouds/adept/) includes a link to
the paper describing how the automatic differentiation capability
works:

Hogan, R. J., 2014: Fast reverse-mode automatic differentiation using
expression templates in C++. ACM Trans. Math. Soft., 40, 26:1-26:16.


INSTALLING

Full installation instructions are provided in section 1.2 of the
Adept User Guide, which is on the Adept web site and in the "doc"
directory (type "make" to create the PDF).

First ensure you have a BLAS library installed (e.g. OpenBLAS from
http://www.openblas.net), needed for matrix multiplication and linear
algebra.  Install LAPACK to also provide linear algebra capabilities
such as matrix inversion and solving linear systems of equations.

To create the Makefiles, type

	./configure

Aspects of the configuration can be configured via both arguments to
the script and environment variables.  Here we focus on options that
are more likely to be useful in the case of Adept. To set the
destination root directory to your home directory and to change the
C++ compiler options, type this instead:

	./configure "CXXFLAGS=-O3 -g" --prefix=$HOME

Note that by default the compiler flags are "-O2 -g", but you may find
measurable speed-up in using the "-O3" optimization flag (the "-g"
option stores debugging information in the library, which shouldn't
affect execution speed).

In addition to BLAS and LAPACK, the configure script also looks for
the other automatic-differentiation libraries ADOL-C, CppAD and
Sacado, since the benchmarking code has the capability to compile the
test algorithms using these libraries.  If any of these are in
non-standard directories, for example your home directory, you can
specify them with

	./configure CPPFLAGS=-I$HOME/include LDFLAGS="-L$HOME/lib -Wl,-rpath,$HOME/lib"

Note that the rpath argument is needed if the BLAS or LAPACK libraries
are in non-standard locations: in ensures that the Adept shared
library knows where to find BLAS and LAPACK so that executables
compiled against Adept do not need to specify the LD_LIBRARY_PATH
environment variable.

If you don't have these libraries then the benchmarking code will
simply be compiled without the capability to use them.  Similarly, the
configure script looks for the GNU Scientific Library (GSL) used by
the test program "test_gsl_interface" but if it is not found this test
program will not be built.

For more information on the use of the configure script, see the
INSTALL file, type "./configure --help", or see the User Guide.

Once you've configured the build, you can build the Adept library with

	make

You can install the library with 

	make install

Note that you will need to log in with super-user access before this
step if you are installing to a system directory (e.g. the default
/usr/local).  The files installed are the C++ header file
<prefix>/include/adept.h, the static library <prefix>/lib/libadept.a
along with the shared version of the library.

This code has been tested under Linux using the GNU C++ compiler.


TESTING AND BENCHMARKING

Once the code has been compiled, type

	make check

to build and run the example programs in the test directory and the
benchmarking program benchmark/autodiff_benchmark.  The test programs
test different aspects of the library; for more information, see
test/README.  The benchmarking program is useful to test the speed of
Adept and also compare it to other automatic differentiation libraries
on the Lax-Wendroff and Toon algorithms used by Hogan (2014). See
benchmark/README for details. Note that in order for these programs to
work without Adept being installed, they have been linked statically,
which means that the executables may be rather large.

Version 1.0 of Adept included the "Multiscatter" algorithm adapted to
use Adept, which provided a further two benchmarks ("PVC" and "TDTS")
used by Hogan (2014). However, this used GNU C++ extensions and I
don't have the resources to time maintain it in the Adept package, so
it has been removed from Adept version 1.1. Note that version 1.0 is
still available from the Adept web site.


DOCUMENTATION

See the User Guide, which may be created from the LaTeX source by
typing "make" in the doc/ directory. It is available under the GNU
Free Documentation License (in doc/COPYING).

If this documentation, the Hogan (2014) paper and the information on
the Adept web site do not answer your questions, then feel free to
email me with queries, or send an email to the mailing list.  I'm also
interested to know of successful uses of the code, comments and bug
fixes.


LICENSE AND COPYRIGHT

The code in this package has a mix of copyright reflecting my change
of employment during the course of developing Adept:

Copyright (C) 2012-2015 University of Reading
Copyright (C) 2015-2017 European Centre for Medium-Range Weather Forecasts

Two licenses are used for the code in this package:

1) The files that form the Adept library are distributed under the
conditions of the Apache License, Version 2 - see the COPYING file for
details.  This is a permissive free-software license but one that does
impose a few conditions if you intend to distribute derivative works.
The files this license applies to are those in the include/ and adept/
directories, and the subdirectories below them.

2) All code in the test/ and benchmark/ directories is subject to the
terms of the GNU all-permissive license, given at the top of those
files - basically you can do what you like with the code from these
files.

If you use Adept in published scientific work then I request that you
cite the paper above, but this is not a condition of the license.
