Table of contents

Section contents

Documentation license

Creative Commons License

Welcome to the ad package

The ad package is a free, cross-platform python library that transparently handles calculations of first- and second-order derivatives of nearly any mathematical expression, regardless of the base numeric type (int, float, complex, etc.).

Calculations of derivatives, can be performed either in an interactive session (as with a calculator), or in programs written in the Python programming language. Existing calculation code can run with little or no change.

An easy-to-use calculator

Calculations involving differentiation can be performed even without knowing anything about the Python programming language. After installing this package and invoking the Python interpreter, calculations with automatic differentation can be performed transparently (i.e., through the usual syntax for mathematical formulas):

>>> from ad import adnumber
>>> from ad.admath import *  # sin(), etc.
>>> x = adnumber(1)
>>> print 2*x
>>> sin(2*x)  # In a Python shell, "print" is optional

So far, there shouldn’t be anything unexpected, but first and second derivatives can now be accessed through intuitive methods:

>>> y = sin(2*x)
>>> y.d(x)  # dy/dx at x=1
>>> y.d2(x)  # d2y/dx2 at x=1

Thus, existing calculation code designed for regular numbers can run with numbers that track derivatives with no or little modification.

Arrays of numbers that track derivatives are transparently handled too.

Available documentation

The User Guide details many of the features of this package.

Additional information is available through the pydoc command, which gives access to many of the documentation strings included in the code.

Installation and download

Important note

The installation commands below should be run in a DOS or Unix command shell (not in a Python shell).

Under Windows (version 7 and earlier), a command shell can be obtained by running cmd.exe (through the Run… menu item from the Start menu). Under Unix (Linux, Mac OS X,…), a Unix shell is available when opening a terminal (in Mac OS X, the Terminal program is found in the Utilities folder, which can be accessed through the Go menu in the Finder).

Automatic install or upgrade

One of the automatic installation or upgrade procedures below might work on your system, if you have a Python package installer or use certain Linux distributions.

Under Unix, it may be necessary to prefix the commands below with sudo, so that the installation program has sufficient access rights to the system.

If you have pip, you can try to install the latest version with

pip install --upgrade ad

If you have setuptools, you can try to automatically install or upgrade this package with

easy_install --upgrade ad

Manual download and install

Alternatively, you can simply download the package archive from the Python Package Index (PyPI) and unpack it. The package can then be installed by going into the unpacked directory (ad-...), and running the provided program with

python install

or, for an installation in the user Python library (no additional access rights needed):

python install --user

or, for an installation in a custom directory my_directory:

python install --install-lib my_directory

or, if additional access rights are needed (Unix):

sudo python install

You can also simply move the ad-py* directory that corresponds best to your version of Python to a location that Python can import from (directory in which scripts using ad are run, etc.); the chosen ad-py* directory should then be renamed ad. Python 3 users should then run 2to3 -w . from inside this directory so as to automatically adapt the code to Python 3.

Source code

The latest, bleeding-edge but working code and documentation source are available on GitHub. The ad package is written in pure Python and has no external dependency (the NumPy package is optional). This makes ad a lightweight, portable package.

Future developments

Possible future developments include:

  • increased support for NumPy: new linear algebra methods (eigenvalue and QR decompositions, determinant, etc.), more convenient matrix creation, etc.;
  • addition of new functions from the math module;
  • arbitrary order differentiation.


Feature requests, bug reports, or feedback are much welcome. They can be sent to the creator of ad, Abraham Lee.

How to cite this package

If you use this package for a publication (in a journal, on the web, etc.), please cite it by including as much information as possible from the following: ad: a Python package for first- and second-order automatic differentation, Abraham D. Lee, Adding the version number is optional.


  • Eric O. LEBIGOT (EOL), author of the uncertainties package, for providing code insight and inspiration
  • Stephen Marks, professor at Pomona College, for useful feedback concerning the interface with optimization routines in scipy.optimize.
  • Wendell Smith, for updating testing functionality and numerous other useful function updates
  • Jonathan Terhorst, for catching a bug that made derivatives of logarithmic functions (base != e) give the wrong answers.
  • GitHub user fhgd for catching a mis-calculation in admath.atan2


This software is released under a dual license; one of the following options can be chosen:

  1. The Revised BSD License (© 2013, Abraham Lee).
  2. Any other license, as long as it is obtained from the creator of this package.