forked from tisimst/ad
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
120 lines (89 loc) · 4.8 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
``ad`` Package Documentation
============================
.. image:: https://travis-ci.org/tisimst/ad.png?branch=master
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.
**All base numeric types are supported** (``int``, ``float``, ``complex``,
etc.). This package is designed so that the underlying numeric types will
interact with each other *as they normally do* when performing any
calculations. Thus, this package acts more like a "wrapper" that simply helps
keep track of derivatives while **maintaining the original functionality** of
the numeric calculations.
From the Wikipedia entry on `Automatic differentiation`_ (AD):
"AD exploits the fact that every computer program, no matter how
complicated, executes a sequence of elementary arithmetic operations
(addition, subtraction, multiplication, division, etc.) and elementary
functions (exp, log, sin, cos, etc.). By applying the chain rule
repeatedly to these operations, derivatives of arbitrary order can be
computed automatically, and accurate to working precision."
See the `package documentation`_ for details and examples.
Main Features
-------------
- **Transparent calculations with derivatives: no or little
modification of existing code** is needed, including when using
the `Numpy`_ module.
- **Almost all mathematical operations** are supported, including
functions from the standard math_ module (sin, cos, exp, erf,
etc.) and cmath_ module (phase, polar, etc.) with additional convenience
trigonometric, hyperbolic, and logarithmic functions (csc, acoth, ln, etc.).
Comparison operators follow the **same rules as the underlying numeric
types**.
- **Real and complex** arithmetic handled seamlessly. Treat objects as you
normally would using the `math`_ and `cmath`_ functions, but with their new
``admath`` counterparts.
- **Automatic gradient and hessian function generator** for optimization
studies using `scipy.optimize`_ routines with ``gh(your_func_here)``.
- **Compatible Linear Algebra Routines** in the ``ad.linalg`` submodule,
similar to those found in NumPy's ``linalg`` submodule, that are not
dependent on LAPACK. There are currently:
a. Decompositions
1. ``chol``: Cholesky Decomposition
2. ``lu``: LU Decomposition
3. ``qr``: QR Decomposition
b. Solving equations and inverting matrices
1. ``solve``: General solver for linear systems of equations
2. ``lstsq``: Least-squares solver for linear systems of equations
3. ``inv``: Solve for the (multiplicative) inverse of a matrix
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 install --upgrade ad`` from the
command-line.
5. Download the *bleeding-edge* version on GitHub_
Contact
-------
Please send **feature requests, bug reports, or feedback** to
`Abraham Lee`_.
Acknowledgements
----------------
The author expresses his thanks to :
- `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``
.. _NumPy: http://numpy.scipy.org/
.. _math: http://docs.python.org/library/math.html
.. _cmath: http://docs.python.org/library/cmath.html
.. _Automatic differentiation: http://en.wikipedia.org/wiki/Automatic_differentiation
.. _Eric O. LEBIGOT (EOL): http://www.linkedin.com/pub/eric-lebigot/22/293/277
.. _uncertainties: http://pypi.python.org/pypi/uncertainties
.. _scipy.optimize: http://docs.scipy.org/doc/scipy/reference/optimize.html
.. _Abraham Lee: mailto:[email protected]
.. _package documentation: http://pythonhosted.org/ad
.. _GitHub: https://github.com/tisimst/ad