Numerical derivatives of functors and parameters#

The escape.core.derivative module approximates derivatives of ESCAPE expressions using finite differences. You pick what to differentiate (fun) and what to differentiate with respect to (x); the result is a new functor, complex functor, or parameter object that you can evaluate like the original.

The module provides:

derivative() — first derivative \(\partial fun / \partial x\)
derivative2() — second derivative (uses a dedicated stencil; prefer this over nesting two derivative calls for better accuracy)
derivative3() — third derivative (same idea as derivative2)

What you can combine

A real functor (or a variable/expression that becomes a functor) with respect to a variable
A complex functor with respect to a variable
A complex functor with respect to a parameter
A parameter expression with respect to a parameter
A real functor with respect to a parameter

Examples#

Derivative of \(x^2\) with respect to \(x\) at \(x=2\) (expect ~4):

>>> import escape as esc
>>> x = esc.var("x")
>>> f = x * x
>>> df = esc.derivative(f, x)
>>> df(2.0)
3.999999999657255

Second derivative of \(x^3\) at \(x=1\) (expect ~6):

>>> d2f = esc.derivative2(x * x * x, x)
>>> round(d2f(1.0), 3)
6.0

First derivative of fun with respect to x (finite differences).

Parameters:

fun: functor_obj, variable_obj, cplx_functor_obj, or parameter_obj: expression to differentiate; type must pair correctly with x (functor-like with a variable, complex functor with a variable, parameter with a parameter, or functor-like with a parameter)
x: variable_obj or parameter_obj: differentiation variable or independent parameter
calculate_error - bool: if True, the implementation may record status and error estimates for the last step;
maxerr - float: maximum error tolerance(default: 0.0) if maxerr>0, then the error will be calculated and exception will be thrown if the error is greater than maxerr
name: str: optional name for the resulting object
notes: str: optional notes string

Returns:

functor_obj, cplx_functor_obj, or parameter_obj representing \(\partial fun / \partial x\), depending on the argument types

Second derivative of fun with respect to x (dedicated stencil).

Prefer derivative2(f, x) over derivative(derivative(f, x), x) for better numerical behaviour.

Parameters:

fun: functor_obj, variable_obj, cplx_functor_obj, or parameter_obj: expression to differentiate (valid combinations as for derivative)
x: variable_obj or parameter_obj: differentiation variable or independent parameter
calculate_error - bool: enable error/status recording for the stencil step
name: str: optional name for the resulting object
notes: str: optional notes string

Returns:

functor_obj, cplx_functor_obj, or parameter_obj representing \(\partial^2 fun / \partial x^2\)

Third derivative of fun with respect to x (dedicated stencil).

Parameters:

fun: functor_obj, variable_obj, cplx_functor_obj, or parameter_obj: expression to differentiate (valid combinations as for derivative)
x: variable_obj or parameter_obj: differentiation variable or independent parameter
calculate_error - bool: enable error/status recording for the stencil step
name: str: optional name for the resulting object
notes: str: optional notes string

Returns:

functor_obj, cplx_functor_obj, or parameter_obj representing \(\partial^3 fun / \partial x^3\)