Jacobi: Numerical Derivatives

0.9.2 · active · verified Sun Apr 12

Jacobi is a lightweight Python library designed for fast and robust computation of generalized Jacobi matrices (numerical derivatives) for arbitrary real analytic mappings. It supports functions with large round-off errors and offers significant speed improvements over other numerical differentiation tools. The current version is 0.9.2, and it typically releases updates as needed.

Warnings

gotcha The `jacobi` function is designed for real analytic mappings. While robust, its accuracy can be affected by highly non-smooth or non-analytic functions. Ensure the function you are differentiating is suitable for numerical differentiation methods.
Fix: Verify the mathematical properties of the function being differentiated. For highly non-smooth functions, other techniques like automatic differentiation (if applicable) or specialized numerical methods might be more appropriate.
gotcha When differentiating a function that returns a 1D array where the Jacobian is known to be diagonal (e.g., an element-wise operation), passing `diagonal=True` to the `jacobi` function can significantly speed up computation. Omitting this for such cases will still yield correct results but might be less efficient.
Fix: For functions `f(x)` where `f[i]` only depends on `x[i]`, pass `diagonal=True` as an argument to `jacobi(f, x, diagonal=True)` to optimize performance.
gotcha The `jacobi` library relies on `numpy` for its numerical operations. Performance can be influenced by how efficiently `numpy` handles the function being differentiated. Vectorized functions tend to perform better.
Fix: Where possible, define the function to be differentiated using vectorized `numpy` operations to maximize performance.

Install

pip install jacobi Install stable version

Imports

jacobi
```
from jacobi import jacobi
```
propagate
```
from jacobi import propagate
```
Used for statistical error propagation based on numerically computed Jacobians.

Quickstart

This quickstart demonstrates how to compute the generalized Jacobi matrix for a vector-valued function and a scalar-valued function with an auxiliary argument using `jacobi.jacobi`. It returns both the derivative and its error estimate.

import numpy as np
from jacobi import jacobi

def my_function(x):
    return np.array([np.sin(x[0]) * x[1], np.exp(x[0] + x[1])])

# Point at which to compute the Jacobian
x0 = np.array([1.0, 2.0])

# Compute the Jacobian matrix and its error estimate
jacobian_matrix, error_estimate = jacobi(my_function, x0)

print(f"Function: f(x) = [sin(x[0]) * x[1], exp(x[0] + x[1])]")
print(f"Point x0: {x0}")
print(f"Computed Jacobian matrix:\n{jacobian_matrix}")
print(f"Error estimate for Jacobian:\n{error_estimate}")

# Example with a function returning a scalar and an auxiliary argument
def scalar_func(param, x):
    return np.sin(x * param)

aux_param = 0.5
x_scalar = np.array([np.pi / 2])
scalar_derivative, scalar_error = jacobi(scalar_func, aux_param, x_scalar)

print(f"\nFunction: g(param, x) = sin(x * param) where param={aux_param}")
print(f"Point x_scalar: {x_scalar}")
print(f"Derivative w.r.t. param: {scalar_derivative}")
print(f"Error estimate: {scalar_error}")

view raw JSON →