ad

This is an automatic differentiation library written in D supporting one-dimensional, real-valued derivatives of arbitrary order. It is not a high performance library. It could become one; I'm not against that by any means! It's just that I originally built this library after learning about automatic differentiation. The elegance of the concept struct me. I had to implement it.

Features

• supports all of D's arithmetic operators
• supports the same set of functions as core.math
• supports the same set of functions as std.math
• supports the same set of functions as std.mathspecial
• supports arbitrary order differentiation, must be fixed at compile time

Overview

This library consists of a handful of modules. ad provides the generalized dual number type GDN and its basic arithmetic operations that are available to the floating point type real. The remaining modules provide implementations for GDN objects of all of the mathematical operations defined for real values in the phobos modules core.math, std.math, and std.mathspecial. They are organized similarly to the modules in the std.math package. Here is the mapping.

• ad.core.math → core.math
• ad.math → std.math
• ad.math.algebraic → std.math.algebraic
• ad.math.constants → std.math.constants
• ad.math.exponential → std.math.exponential
• ad.math.operations → std.math.operations
• ad.math.remainder → std.math.remainder
• ad.math.rounding → std.math.rounding
• ad.math.traits → std.math.traits
• ad.math.trigonometry → std.math.trigonometry
• ad.mathspecial → std.mathspecial

The module ad.math aggregates and exposes all of the functions defined in its submodules in the same way the Phobos package std.math does.

Examples

Here are some examples of using this library.

Basic Usage

To differentiate a function, create a GDN variable with the desired derivative degree and evaluate your function:

import ad;

void main()
do {
   // Create a variable x = 3 that can track up to first order
   // derivatives
   const x = GDN!1(3);

   // Evaluate a function: f(x) = 2x + 1
   const f = 2 * x + 1;

   // The value and first derivative
   assert(f == 7);    // f(3)
   assert(f.d == 2);  // f'(3), f'(x) = 2
}

Computing Higher-Order Derivatives

Specify a higher degree to compute multiple orders of derivatives:

import ad;

void main()
do {
   // Create a variable x = 2 that tracks up to third order
   // derivatives
   const x = GDN!3(2);

   // Evaluate a function: f(x) = x³
   const f = x ^^ 3;

   // Access derivatives of different orders
   assert(f == 8);       // f(2)
   assert(f.d == 12);    // f'(2), f'(x) = 3x²
   assert(f.d!2 == 12);  // f''(2), f''(x) = 6x
   assert(f.d!3 == 6);   // f'''(2), f'''(x) = 6
}

Using with Math Functions

The library supports standard math functions from core.math, std.math, and std.mathspecial:

import std.math : E;
import std.mathspecial : digamma;

import ad;
import ad.math;
import ad.mathspecial;

void main()
do {
   // Differentiate trigonometric functions
   const x = GDN!1(0);
   const y = sin(x);
   assert(y == 0);    // sin(0) = 0
   assert(y.d == 1);  // sin'(x) = cos(x)

   // Differentiate exponential functions
   const u = exp(GDN!1(1));
   assert(u == E);
   assert(u.d == E);  // (d/dx)eˣ = eˣ

   // Differentiate the Gamma function
   const q = gamma(GDN!1(2));
   assert(q == 1);             // Γ(2) = 1
   assert(q.d == digamma(2));  // Γ'(x) = Γ(x)Ψ(x)
}

Combining Operations

GDN objects can be freely mixed with arithmetic operations and math functions:

import std.math : E, cos;

import ad;
import ad.math;

void main()
do {
   // x is the result of evaluating a function whose value is 1
   // and derivative is 2.
   const x = GDN!1(1, 2);

   // Evaluate f(x) = eˣsin(x)
   const f = exp(x) * sin(x);
   assert(f == E * sin(1.0L));

   // f'(x) = eˣx'sin(x) + eˣcos(x)x'
   //       = x'eˣ[cos(x) + sin(x)]
   assert(f.d == 2*E*(cos(1.0L) + sin(1.0L)));
}

Building

This library is built with DUB.

To build the library, run:

dub build

To build the API documentation from the DDoc configuration, run:

dub build --config=docs

This command will generate a docs/ folder with HTML reference pages.

Using the library in an application

Add ad github repository as a dependency in your application's dub.json or dub.sdl.

Example dub.json dependency:

"dependencies": {
   "ad": {
      "repository": "git+https://github.com/tedgin/ad.git"
   }
}

Future Work

The implementations of the regularized lower incomplete gamma function $P(s,x)$ and the regularized incomplete beta function $I_x(a,b)$ don't support differentiation of their parameters. I would like to extend the library to support this.

For the regularized lower incomplete gamma function $P(s,x)$, implementing $\frac{∂P}{∂s}$ looks possible. $\frac{∂P}{∂s} = -\frac{∂Q}{∂s}$, where $Q(s,x)$ is the regularized upper incomplete gamma function. $\frac{∂Q}{∂s} = \frac{1}{𝛤(s)}\frac{∂𝛤}{∂s}(s,x) - \frac{𝛤(s,x)}{𝛤(s)^2}\frac{d𝛤}{ds}(s)$, where $𝛤(s)$ is the gamma function, and $𝛤(s,x)$ is the upper incomplete gamma function. $\frac{∂𝛤}{∂s}(s,x) = ln(x)𝛤(s,x) + xT(3,s,x)$, where $T(m,s,x) = G^{m,0}_{m-1,m}(0,0,…,0; s-1,-1,…,-1 |x)$, and $G$ is the Meijer G-function. $T$ has recurrent derivative formulas for both $s$ and $x$: $\frac{∂T}{∂s}(m,s,x) = ln(x)T(m,s,x) + (m-1)T(m+1,s,x)$, and $\frac{∂T}{∂x}(m,s,x) = -\frac{T(m-1,s,x) + T(m,s,x)}{x}$.

For the regularized incomplete beta function $I_x(a,b)$, I haven't found any recurrent derivative formulas for computing $\frac{∂^nI_x}{∂a^n}$ and $\frac{∂^nI_x}{∂b^n}$, so it may not be possible to implement these.