bob-carpenter / ad-handbook Goto Github PK

View Code? Open in Web Editor NEW

141.0 11.0 18.0 889 KB

Automatic Differentiation Handbook

License: Other

TeX 18.23% R 17.75% C++ 62.51% Shell 1.50%

numerical-analysis

ad-handbook's Introduction

ad-handbook

This is the source repository for the Automatic Differentiation Handbook.

Pre-built pdf

Here's a pre-built pdf of a recent (but perhaps not the latest) DRAFT:

ad-handbook-draft.pdf.

I don't have a pre-built version of the HTML yet, but I'll try to figure out how to push that to my GitHub pages repo automatically one of these days.

Contributing

Please create

issues for feature requests or reporting bugs/typos/brainos
pull requests for contributions

If you contribute and want to be listed by name rather than GitHub handle, please include that in the PR. Also, if you'd rather not be listed, say that, too!

The C++ reference implementation

C++ reference code directory: cpp/
Example directory: cpp/examples/

Licensing

The code is licensed under BSD-3 and the text under CC-BY-ND-NC 4.0. All contributions are made in accorance with this license under the terms of use for GitHub.

Building the book

Prerequisites

The following system package must be installed:

pandoc
pandoc-citeproc

See the instructions for installing pandoc.

The following R packages must be installed in order to build the book:

bookdown
tufte
reshape
ggplot2
gridExtra
formatR

They can be installed using, e.g.,

> install.pacakges('tufte')

Build steps

To build the HTML version of the book from R using the bookdown package,

> library(bookdown)
> render_book('index.Rmd')

The first page of the book can then be found in the file _book/index.html.

A web connection is required to render the mathematics in the web version because it uses MathJax.

To build the PDF version of the book using a shell script,

> ./build-pdf.sh

and to build the HTML version,

> ./build-html.sh

ad-handbook's People

Contributors

Stargazers

Watchers

Forkers

syclik volpatto adamhaber noobsz ivanyashchuk jiamim shanliwa1 foocker liangdaojun axmat xrosliang jayefo mortonjt pciodyuc stevebronder anhnguyendepocen talanton

ad-handbook's Issues

Small issue in the intro

Saw your post on discourse and was checking this out. I noticed in the index.Rmd you write:

Automatic differentiation is a general technique for lifting a function computing values to one that also computes derivatives.

Two small issues that impact the understanding. 1) Could you explain or use different terminology for what "lifting" means (I found some references to lifting a function below) and 2) I see the dependent clause after 'function' was used to loosely define this, maybe just expand into a new sentence such as

Automatic differentiation is a general technique for lifting a function from computing values to also computing derivatives.

Contribution: section on implicit functions

Restating my post on https://discourse.mc-stan.org/t/help-write-an-autodiff-handbook/12640/13.

I propose grouping the chapters on ODEs, algebraic equations, and integrals, into one section on implicit functions. This is in part because for all these methods, we can apply the adjoint method to construct differentiation algorithms.

The content would be as follows:

Automatic differentiation for implicit functions

Algebraic equations: implicit function theorem, adjoint method, practical considerations
Optimization problems: extending results from the algebraic equations, equality constraint, inequality constraints, conditions for existence of derivatives and diagnostics
Ordinary differential equations: full Jacobian, adjoint method, tricks for users
Action of matrix exponential: adjoint method based on ODE case
Differential algebraic equations: adjoint method
Discrete sequences: adjoint method

We've already written a lot of this down, it's just matter of putting it together.

Prereqs for building the book

I needed to install these packages in R:

tufte
reshape

I'm sure I have a bunch already installed.

Where's a good place to put this info? I was originally going to modify the README.md with a ## Before building the book subsection, but then thought it could be useful to have an install.R script or something else programmatic.

Formatting for derivatives, adjoints, tangents etc. and some more matrix results?

Looking over the collection of known derivatives etc. should that section have a header and a little, "Hey these are some common cases if you want to use these."?

It might also be nice to format them as a list

[Operation]:

Derivative:
Adjoint:
Tangent:

There's also a few matrix algebra ops I can write here if you want them.

Additional R build dependencies, possible missing file

Working on building the book. So far I've needed these R packages in addition to the ones in the README:

ggplot2
gridExtra
rstan
formatR

Now I'm getting this error:
! LaTeX Error: File 'tufte-book.cls' not found.
Maybe an uncommitted file?