derivkit.derivatives.finite.finite_difference module#

Provides the FiniteDifferenceDerivative class.

The user must specify the function to differentiate and the central value at which the derivative should be evaluated. More details about available options can be found in the documentation of the methods.

class derivkit.derivatives.finite.finite_difference.FiniteDifferenceDerivative(function: Callable, x0: float)#

Bases: object

Computes numerical derivatives using central finite difference stencils.

This class supports the calculation of first to fourth-order derivatives for scalar or vector-valued functions. It uses high-accuracy central difference formulas with configurable stencil sizes (3-, 5-, 7-, or 9-point).

For scalar-valued functions, a single float is returned. For vector-valued functions, the derivative is computed component-wise and returned as a NumPy array.

function#

The function to differentiate. Must accept a single float and return either a float or a 1D array-like object.

x0#

The point at which the derivative is evaluated.

Supported Stencil and Derivative Combinations#

  • 3-point: first-order only

  • 5-point: first to fourth-order

  • 7-point: first and second-order

  • 9-point: first and second-order

Examples

>>> import numpy as np
>>> from derivkit.derivatives.finite.finite_difference import FiniteDifferenceDerivative

Basic second derivative without extrapolation:

>>> f = lambda x: x**3
>>> d = FiniteDifferenceDerivative(function=f, x0=2.0)
>>> round(float(d.differentiate(order=2)), 6)
12.0

First derivative with Ridders extrapolation and an error estimate:

>>> g = np.sin
>>> d = FiniteDifferenceDerivative(function=g, x0=0.7)
>>> val, err = d.differentiate(
...     order=1,
...     stepsize=1e-2,
...     num_points=5,
...     extrapolation="ridders",
...     levels=4,
...     return_error=True,
... )
>>> bool(np.allclose(val, np.cos(0.7), rtol=1e-6))
True

Vector-valued function with Gauss–Richardson extrapolation:

>>> def vec_func(x):
...     return np.array([np.sin(x), np.cos(x)])
>>> d = FiniteDifferenceDerivative(function=vec_func, x0=0.3)
>>> val = d.differentiate(
...     order=1,
...     stepsize=1e-2,
...     num_points=5,
...     extrapolation="gauss-richardson",
...     levels=4,
... )
>>> val.shape
(2,)

Initialises the class based on function and central value.

param function:

The function to differentiate. Must accept a single float and return either a float or a 1D array-like object.

param x0:

The point at which the derivative is evaluated.

differentiate(order: int = 1, stepsize: float = 0.01, num_points: int = 5, n_workers: int = 1, extrapolation: str | None = None, levels: int | None = None, return_error: bool = False) → ndarray[float] | float#

Computes the derivative using a central finite difference scheme.

Supports 3-, 5-, 7-, or 9-point central difference stencils for derivative orders 1 through 4 (depending on the stencil size). Derivatives are computed for scalar or vector-valued functions. Allows for optional extrapolation (Richardson or Ridders) to improve accuracy. It also returns an error estimate if requested.

Parameters:

  • order – The order of the derivative to compute. Must be supported by the chosen stencil size. Default is 1.

  • stepsize – Step size (h) used to evaluate the function around the central value. Default is 0.01.

  • num_points – Number of points in the finite difference stencil. Must be one of [3, 5, 7, 9]. Default is 5.

  • n_workers – Number of workers to use in multiprocessing. Default is 1 (no multiprocessing).

  • extrapolation –

    Extrapolation scheme to use for improving accuracy. Supported options are:

    • None: no extrapolation (single finite difference).

    • "richardson":

      • fixed-level if levels is not None

      • adaptive if levels is None

    • "ridders":

      • fixed-level if levels is not None

      • adaptive if levels is None

    • "gauss-richardson" or "gre":

      • fixed-level if levels is not None

      • adaptive if levels is None

  • levels – Number of extrapolation levels for fixed schemes. If None, the chosen extrapolation method runs in adaptive mode where supported.

  • return_error – If True, also return an error estimate from the extrapolation (or two-step) routine.

Returns:

The estimated derivative. Returns a float for scalar-valued functions, or a NumPy array for vector-valued functions.

Raises:

ValueError – If the combination of num_points and order is not supported or if an unknown extrapolation scheme is given.

Notes

The available (num_points, order) combinations are:

  • 3: order 1

  • 5: orders 1, 2, 3, 4

  • 7: orders 1, 2

  • 9: orders 1, 2