Skip to main content

Fast, transparent, calculations of first and second-order automatic differentiation package

Project description

Overview
========
The ``ad`` package allows you to **easily** and **transparently** perform
**first and second-order automatic differentiation**. Advanced math
involving trigonometric, logarithmic, hyperbolic, etc. functions can also
be evaluated directly using the ``admath`` sub-module.

`Automatic differentiation`_ is different from numerical and symbolic
differentiation in that it uses prior knowledge of how derivatives
are calculated, `but that's the part you don't need to worry about
while using this package`. They are then transmitted through subsequent
calculations (using the generalized `chain rule`_).

Basic examples
==============
::

>>> from ad import AD

>>> x = AD(2.0)
>>> x
ADV(2.0)

>>> square = x**2
>>> square
ADF(4.0)
>>> square.d(x) # get the first derivative wrt x
4.0
>>> square.d2(x) # get the second derivative wrt x
2.0

>>> from ad.admath import * # sin, cos, log, exp, sqrt, etc.
>>> sin(1 + x**2)
ADF(-0.958924274663)

>>> print (2*x + 1000).d() # no inputs shows dict of all derivatives
{ADV(2.0): 2.0}

>>> y = AD(3, tag='y') # tags are useful for tracking original variables
>>> y
y(3.0)
>>> y.d(x) # returns zero if the derivative doesn't exist
0.0

>>> z = x*y**2
>>> z
ADF(18.0)
>>> z.gradient([x, y]) # show the gradient in the order given
[9.0, 12.0]
>>> z.d2c(x, y) # second cross-derivatives, order doesn't matter -> (x,y) or (y,x)
6.0
>>> z.hessian([x, y])
[[0.0, 6.0], [6.0, 4.0]]

>>> import numpy as np # most numpy functions work out of the box
>>> arr = np.array(AD([1, 2, 3])) # multiple input support
>>> arr.sum()
ADF(6.0)
>>> arr.max()
ADV(3.0)
>>> arr.mean()
ADF(2.0)
>>> arr.var() # array variance
ADF(0.666666666667)
>>> sqrt(arr) # vectorized operations supported with ad operators
array([ADF(1.0), ADF(1.41421356237), ADF(1.73205080757)], dtype=object)

Main Features
=============

- **Transparent calculations with derivatives: no or little
modification of existing code** is needed, including when using
the `Numpy`_ module. The only function (that I have tested, and I
certainly haven't tested most of them) that doesn't work right
out of the box is ``numpy.std`` since it internally calls its
builtin ``sqrt`` function. Two alternatives exist to work around
this: 1) use ``**0.5`` or 2) using the ``admath.sqrt``
operator.
- **Almost all mathematical operations** are supported, including
functions from the standard `math`_ module (sin, cos, exp, erf,
etc.) with additional convenience trigonometric, hyperbolic,
and logarithmic functions (csc, acoth, ln, etc.). Comparison
operators follow the same rules as ``float`` types.
- Nearly all derivative calculations are performed **analytically**
(only the ``gamma`` and ``lgamma`` functions use a high-accuracy
finite difference formula).

Installation
============

You have several easy, convenient options to install the ``ad`` package
(administrative privileges may be required)

1. Download the package files below, unzip to any directory, and run
``python setup.py install`` from the command-line
2. Simply copy the unzipped ``ad-XYZ`` directory to any other location
that python can find it and rename it ``ad``
3. If ``setuptools`` is installed, run ``easy_install --upgrade ad``
from the command-line
4. If ``pip`` is installed, run ``pip --upgrade ad`` from the command-line

Contact
=======

Please send **feature requests, bug reports, or feedback** to
`Abraham Lee`_.

Version History
===============

Main changes:

- 1.0.1: Smashed some vectorization bugs
- 1.0: Initial release. Nearly full differentiation support for all
`math`_ module functions.

.. _NumPy: http://numpy.scipy.org/
.. _math: http://docs.python.org/library/math.html
.. _Automatic differentiation: http://en.wikipedia.org/wiki/Automatic_differentiation
.. _chain rule: http://en.wikipedia.org/wiki/Chain_rule
.. _Abraham Lee: mailto:tisimst@gmail.com

Release history Release notifications

History Node

1.3.2

History Node

1.3.1

History Node

1.3

History Node

1.2.3

History Node

1.2.2

History Node

1.2.1

History Node

1.2.0

History Node

1.1.7

History Node

1.1.6

History Node

1.1.5

History Node

1.1.3

History Node

1.1.2

History Node

1.1.1

History Node

1.1

History Node

1.0.3

History Node

1.0.2

This version
History Node

1.0.1

History Node

1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
ad-1.0.1.tar.gz (13.9 kB) Copy SHA256 hash SHA256 Source None Jun 28, 2013
ad-1.0.1.zip (16.7 kB) Copy SHA256 hash SHA256 Source None Jun 28, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page