adept-debianize: A Shell repository from ohai

Adept: Automatic Differentiation using Expression Templates
Version: 1.1, June 2015
By Robin Hogan <r.j.hogan@reading.ac.uk>


INTRODUCTION

The Adept software library provides the capability to automatically
differentiate an algorithm written in C or C++.  It uses expression
templates in a way that allows it to compute adjoints significantly
faster than the leading current tools that use the same approach of
operator overloading. Benchmark calculations found that Adept was
significantly faster than ADOL-C, CppAD and Sacado for adjoint
calculations, and often not much slower than hand-written adjoint
code. The code to run these benchmarks on your platform is provided in
this package.

The web site is at http://www.met.reading.ac.uk/clouds/adept/ where
you can find the latest version of the code as well as a paper
describing how it works:

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


INSTALLING

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).

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 they are in non-standard
directories, for example your home directory, you can specify them
with

	./configure CPPFLAGS=-I$HOME/include LDFLAGS=-L$HOME/lib 

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
doc/adept_documentation.pdf file.

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

	make

and install it 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 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 are 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

This is a PDF file in the doc/ directory, along with the latex source
file 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 Adept library and all code in this package has the same copyright: 

Copyright (C) 2012-2015 University of Reading

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:
      include/adept.h
      adept/adept.cpp
      adept/adept_openmp.cpp

2) All other code 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.
ohai/adept-debianize
