Metadata-Version: 2.1
Name: jacobi
Version: 0.2.1
Summary: Compute numerical derivatives.
Home-page: https://github.com/hdembinski/jacobi
Author: Hans Dembinski
Author-email: hans.dembinski@gmail.com
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/hdembinski/jacobi/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy (>=1.10)
Provides-Extra: doc
Requires-Dist: sphinx ; extra == 'doc'
Provides-Extra: plot
Requires-Dist: numdifftools ; extra == 'plot'
Requires-Dist: matplotlib ; extra == 'plot'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-benchmark ; extra == 'test'
Requires-Dist: pre-commit ; extra == 'test'
Requires-Dist: types-setuptools ; extra == 'test'

.. |jacobi| image:: https://hdembinski.github.io/jacobi/_images/logo.svg
   :alt: jacobi

|jacobi|
========

.. image:: https://img.shields.io/pypi/v/jacobi
  :target: https://pypi.org/project/jacobi
.. image:: https://img.shields.io/badge/github-docs-success
  :target: https://hdembinski.github.io/jacobi
.. image:: https://img.shields.io/badge/github-source-blue
  :target: https://github.com/HDembinski/jacobi

Fast numerical derivatives for real analytic functions with arbitrary round-off error.

Features
--------

- Robustly compute the generalised Jacobi matrix for an arbitrary real analytic mapping ℝⁿ → ℝⁱ¹ × ... × ℝⁱⁿ
- Derivative is either computed to specified accuracy (to save computing time) or until maximum precision of function is reached
- Algorithm based on John D'Errico's `DERIVEST <https://de.mathworks.com/matlabcentral/fileexchange/13490-adaptive-robust-numerical-differentiation>`_: works even with functions that have large round-off error
- Up to 1200x faster than `numdifftools <https://pypi.org/project/numdifftools>`_ at equivalent precision
- Returns error estimates for derivatives
- Supports arbitrary auxiliary function arguments
- Perform statistical error propagation based on numerically computed jacobian
- Lightweight package, only depends on numpy

Planned features
----------------

- Compute the Hessian matrix numerically with the same algorithm
- Further generalize the calculation to support function arguments with shape (N, K), in that case compute the Jacobi matrix for each of the K vectors of length N

Examples
--------

.. code-block:: python

  from matplotlib import pyplot as plt
  import numpy as np
  from jacobi import jacobi


  # function of one variable with auxiliary argument; returns a vector
  def f(dx, x):
      y = x + dx
      return np.sin(y) / y


  x = np.linspace(-10, 10, 1000)
  fx = f(0, x)
  fdx, fdex = jacobi(f, 0, x)

  plt.plot(x, fx, label="f(x) = sin(x) / x")
  plt.plot(x, fdx, ls="--", label="f'(x)")
  plt.legend()

.. image:: https://hdembinski.github.io/jacobi/_images/example.svg

.. code-block:: python

  from jacobi import propagate
  import numpy as np


  def f(x):
      a = 1.5
      b = 3.1
      return a * np.exp(-x ** 2) + b

  x = [1.0, 2.0]
  xcov = [[1.1, 0.1], [0.1, 2.3]]
  y, ycov = propagate(f, x, xcov)


Comparison to numdifftools
--------------------------

Speed
^^^^^

Jacobi makes better use of vectorised computation than numdifftools. Smaller run-time is better (and ratio > 1).

.. image:: https://hdembinski.github.io/jacobi/_images/speed.svg

Precision
^^^^^^^^^

The machine precision is indicated by the dashed line.

.. image:: https://hdembinski.github.io/jacobi/_images/precision.svg


