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\)