derivkit.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.

Typical usage example:

>>>  derivative = FiniteDifferenceDerivative(
>>>    function_to_differentiate,
>>>    1
>>>  ).compute()

derivative is the derivative of function_to_differerentiate at value 1.

class derivkit.finite_difference.FiniteDifferenceDerivative(function, central_value, log_file=None, debug=False)

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

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

central_value

float The point at which the derivative is evaluated.

log_file

str, optional Path to a file where debug information may be logged.

debug

bool, optional If True, debug information will be printed or logged.

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:

>>> f = lambda x: x**3
>>> d = FiniteDifferenceDerivative(function=f, central_value=2.0)
>>> d.compute(derivative_order=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.

type function:

callable

param central_value:

The point at which the derivative is evaluated.

type central_value:

float

param log_file:

Path to a file where debug information may be logged.

type log_file:

str, optional

param debug:

If True, debug information will be printed or logged.

type debug:

bool, optional

compute(derivative_order=1, stepsize=0.01, num_points=5, n_workers=1)

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.

Parameters:

  • derivative_order (int, optional) – The order of the derivative to compute. Must be supported by the chosen stencil size. Default is 1.

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

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

  • n_workers (int, optional) – Number of worker to use in multiprocessing. Default is 1 (no multiprocessing).

Returns:

The estimated derivative. Returns a float for

scalar-valued functions, or a NumPy array for vector-valued functions.

Return type:

float or np.ndarray

Raises:

ValueError – If the combination of num_points and derivative_order is not supported.

Notes

The available (num_points, derivative_order) combinations are:

  • 3: order 1

  • 5: orders 1, 2, 3, 4

  • 7: orders 1, 2

  • 9: orders 1, 2

get_finite_difference_tables(stepsize)

Returns offset patterns and coefficient tables.

Parameters:

stepsize (float) – Stepsize for finite difference calculation.

Returns:

A tuple of two dictionaries. The first maps from

stencil size to symmetric offsets. The second mapps from (stencil_size, derivative_order) to coefficient arrays.

Return type:

(dict, dict)