Adept C++ Software Library: User Guide
Total Page:16
File Type:pdf, Size:1020Kb
Adept C++ Software Library: User Guide Robin J. Hogan European Centre for Medium Range Weather Forecasts, Reading, UK and School of Mathematical, Physical and Computational Sciences, University of Reading, UK, Document version 2.1 (February 2021) applicable to Adept version 2.1 This document is copyright c Robin J. Hogan 2013–2021. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation. This license may be found at http://www.gnu.org/copyleft/fdl.html. As an exception, no copyright is asserted for the code fragments in this document (indicated in the text with a light-grey background); these code fragments are hereby placed in the Public Domain, and accordingly may be copied, modified and distributed without restriction. If you have any queries about Adept that are not answered by this document or by the information on the Adept web site (http://www.met.reading.ac.uk/clouds/adept/) then please email me at [email protected]. Contents 1 Introduction 3 1.1 What is Adept? ...................................................................................................................................... 3 1.2 Installing Adept and compiling your code to use it ............................................................................... 3 1.2.1 Unix-like platforms................................................................................................................... 4 1.2.2 Non-Unix platforms, and compiling Adept applications without linking to an external library6 2 Using Adept for automatic differentiation7 2.1 Introduction............................................................................................................................................ 7 2.2 Code preparation.................................................................................................................................... 8 2.3 Applying reverse-mode differentiation.................................................................................................. 9 2.3.1 Set-up stack to record derivative information........................................................................... 9 2.3.2 Initialize independent variables and start recording ................................................................. 10 2.3.3 Perform calculations to be differentiated.................................................................................. 10 2.3.4 Perform reverse-mode differentiation....................................................................................... 10 2.3.5 Extract the final gradients ......................................................................................................... 11 2.4 Computing Jacobian matrices................................................................................................................ 11 2.5 Real-world usage: interfacing Adept to a minimization library ............................................................ 12 2.6 Calling an algorithm with and without automatic differentiation from the same program ................... 15 2.6.1 Function templates.................................................................................................................... 15 2.6.2 Pausable recording.................................................................................................................... 16 2.6.3 Multiple object files per source file........................................................................................... 16 2.7 Interfacing with software containing hand-coded Jacobians................................................................. 17 2.8 Member functions of the Stack class.................................................................................................. 19 2.9 Member functions of the adouble object ........................................................................................... 22 3 Using Adept’s array functionality 24 3.1 Introduction............................................................................................................................................ 24 3.2 The Array class ................................................................................................................................... 25 3.3 Operators and mathematical functions .................................................................................................. 28 3.4 Array slicing .......................................................................................................................................... 28 3.5 Passing arrays to and from functions..................................................................................................... 30 3.6 Array reduction operations .................................................................................................................... 32 3.7 Array expansion operations ................................................................................................................... 32 3.8 Conditional operations........................................................................................................................... 33 3.9 Fixed-size arrays.................................................................................................................................... 33 3.10 Special square matrices.......................................................................................................................... 34 3.11 Matrix multiplication............................................................................................................................. 35 3.12 Linear algebra ........................................................................................................................................ 36 3.13 Bounds and alias checking..................................................................................................................... 37 3.14 Automatic differentiation capabilities specific to arrays ....................................................................... 38 3.15 Array thread safety ................................................................................................................................ 38 3.16 Writing an array to a stream .................................................................................................................. 38 3.17 Fortran interoperability.......................................................................................................................... 39 3.17.1 Passing arrays from C++/Adept to Fortran............................................................................... 39 3.17.2 Passing arrays from Fortran to C++/Adept............................................................................... 40 4 Using Adept’s optimization functionality 42 4.1 Background............................................................................................................................................ 42 4.2 Adept interface....................................................................................................................................... 42 4.3 Other member functions of the Minimizer class................................................................................. 45 1 CONTENTS 2 4.4 Return status for minimization .............................................................................................................. 46 5 General considerations 47 5.1 Setting and checking the global configuration....................................................................................... 47 5.2 Parallelizing Adept programs................................................................................................................. 47 5.3 The fast exponential function ................................................................................................................ 48 5.4 Tips for the best performance ................................................................................................................ 48 5.5 Exceptions thrown by the Adept library ................................................................................................ 49 5.5.1 General exceptions.................................................................................................................... 50 5.5.2 Automatic-differentiation exceptions ....................................................................................... 50 5.5.3 Array exceptions ....................................................................................................................... 51 5.6 Configuring the behaviour of Adept ...................................................................................................... 51 5.6.1 Modifications not requiring a library recompile ....................................................................... 51 5.6.2 Modifications requiring a library recompile ............................................................................. 53 5.7 Frequently asked questions.................................................................................................................... 53 5.8 Copyright and license for Adept software ............................................................................................. 55 Chapter 1 Introduction 1.1 What is Adept? Adept (Automatic Differentiation using Expression Templates) is a C++ software library that enables