derivkit 1.0.0__py3-none-any.whl

derivkit/derivatives/finite/finite_difference.py

@@ -0,0 +1,247 @@
+"""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.
+"""
+
+from collections.abc import Callable
+from functools import partial
+
+import numpy as np
+
+from derivkit.derivatives.finite.core import single_finite_step
+from derivkit.derivatives.finite.extrapolators import (
+    adaptive_gre_fd,
+    adaptive_richardson_fd,
+    adaptive_ridders_fd,
+    fixed_gre_fd,
+    fixed_richardson_fd,
+    fixed_ridders_fd,
+)
+from derivkit.derivatives.finite.stencil import (
+    TRUNCATION_ORDER,
+    validate_supported_combo,
+)
+
+
+class FiniteDifferenceDerivative:
+    """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.
+
+    Attributes:
+        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,)
+    """
+
+    def __init__(
+        self,
+        function: Callable,
+        x0: float,
+    ) -> None:
+        """Initialises the class based on function and central value.
+
+        Arguments:
+            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.
+        """
+        self.function = function
+        self.x0 = x0
+
+    def differentiate(
+        self,
+        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,
+    ) -> np.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.
+
+        Args:
+            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
+        """
+        if stepsize <= 0:
+            raise ValueError("stepsize must be positive.")
+
+        validate_supported_combo(num_points, order)
+
+        # We set up a partial function for single finite difference step
+        single = partial(
+            single_finite_step,
+            self.function,
+            self.x0,
+        )
+
+        # If we just want bare finite difference (no extrapolation)
+        if extrapolation is None:
+            value = single(order, stepsize, num_points, n_workers)
+
+            if not return_error:
+                return value
+
+            # Our secret second evaluation at h/2 to get a crude error estimate
+            r = 2.0
+            value_refined = single(order, stepsize / r, num_points, n_workers)
+
+            val_arr = np.asarray(value, dtype=float)
+            ref_arr = np.asarray(value_refined, dtype=float)
+            err_arr = np.abs(val_arr - ref_arr)
+
+            if np.isscalar(value) or np.shape(value) == ():
+                err_out: float | np.ndarray = float(err_arr)
+            else:
+                err_out = err_arr
+
+            return value, err_out
+
+        # If we wanted extrapolation, get the truncation order first
+        key = (num_points, order)
+        p = TRUNCATION_ORDER.get(key)
+        if p is None:
+            raise ValueError(
+                f"Extrapolation not configured for stencil {key}."
+            )
+
+        # Choose extrapolator function based on scheme + levels
+        if extrapolation == "richardson":
+            extrap_fn = (fixed_richardson_fd if levels is not None else adaptive_richardson_fd)
+        elif extrapolation == "ridders":
+            extrap_fn = (fixed_ridders_fd if levels is not None else adaptive_ridders_fd)
+        elif extrapolation in {"gauss-richardson", "gre"}:
+            extrap_fn = fixed_gre_fd if levels is not None else adaptive_gre_fd
+        else:
+            raise ValueError(f"Unknown extrapolation scheme: {extrapolation!r}")
+
+        # Common kwargs for all extrapolators
+        extrap_kwargs: dict = dict(
+            single_finite=single,
+            order=order,
+            stepsize=stepsize,
+            num_points=num_points,
+            n_workers=n_workers,
+            p=p,
+        )
+        if levels is not None:
+            extrap_kwargs["levels"] = levels
+
+        if return_error:
+            extrap_kwargs["return_error"] = True
+            value, err = extrap_fn(**extrap_kwargs)
+            return value, err
+
+        # If no error requested, just return value of the estimated derivative
+        return extrap_fn(**extrap_kwargs)

derivkit/derivatives/finite/stencil.py

@@ -0,0 +1,206 @@
+"""Stencil definitions and utilities for finite-difference derivative calculations."""
+
+import math
+
+import numpy as np
+from numpy.typing import NDArray
+
+FloatArray = NDArray[np.float64]
+
+__all__ = [
+    "get_finite_difference_tables",
+    "validate_supported_combo",
+    "SUPPORTED_BY_STENCIL",
+    "TRUNCATION_ORDER",
+    "STENCILS",
+    "ORDERS",
+]
+
+
+#: A list of supported stencil sizes.
+STENCILS = (3, 5, 7, 9)
+#: A list of supported derivative orders.
+ORDERS = (1, 2, 3, 4)
+
+
+def supported_orders(
+    num_points: int,
+    *,
+    max_order: int = 4,
+) -> set[int]:
+    """Creates a list of supported derivative orders for a given stencil size, and a maximum derivative order.
+
+    Args:
+        num_points: Number of points in the stencil. The supported stencil sizes are defined in :data:`STENCILS`.
+        max_order: The maximum supported derivative order.
+
+    Returns:
+        The list of supported derivative orders for the given stencil size.
+
+    Raises:
+        ValueError: If ``num_points`` is not in :data:`STENCILS`.
+        ValueError: If ``max_order < 1`` or ``max_order > 4``.
+    """
+    if num_points not in STENCILS:
+        raise ValueError(f"num_points must be one of {STENCILS}")
+    if max_order < 1:
+        raise ValueError("max_order must be at least 1")
+    if max_order > max(ORDERS):
+        raise ValueError(f"max_order must be {max(ORDERS)} or less")
+
+    return set(range(1, min(max_order, num_points - 1) + 1))
+
+
+# Dictionary containing the derivative orders by the available stencil sizes.
+SUPPORTED_BY_STENCIL = {n: supported_orders(n) for n in STENCILS}
+
+
+def _central_offsets(
+    num_points: int,
+) -> FloatArray:
+    """Creates a grid of central offset values for a desired number of points.
+
+    Args:
+        num_points: Number of points desired in the grid.
+
+    Returns:
+        An array of offset values centered at zero.
+    """
+    half = num_points // 2
+    return np.arange(-half, half + 1, dtype=np.float64)
+
+
+def truncation_order_from_coeffs(
+    offsets: FloatArray,
+    coeffs: FloatArray,
+    deriv_order: int,
+    tol: float = 1e-12,
+) -> int:
+    """Computes the truncation order from the coefficients and offsets, for some numerical tolerance.
+
+    Args:
+        offsets: Array of integer offsets for the finite difference stencil.
+        coeffs: Array of finite difference coefficients.
+        deriv_order: The requested derivative order.
+        tol: Numerical tolerance used to determine the truncation order.
+
+    Returns:
+        The truncation order for the given numerical tolerance.
+    """
+    m = deriv_order
+    max_r = 40
+
+    for r in range(m + 1, max_r + 1):
+        moment = float(np.dot(coeffs, offsets**r))
+        if abs(moment) > tol:
+            return r - m
+    raise RuntimeError("Could not detect truncation order.")
+
+
+def _finite_difference_coeffs(
+    offsets: list[int] | NDArray,
+    deriv_order: int,
+    stepsize: float,
+) -> NDArray:
+    """Compute finite difference coefficients for given offsets and derivative order.
+
+    This method solves a linear system to find the coefficients that
+    approximate the derivative of specified order using the provided offsets.
+
+    Args:
+        offsets: List or array of integer offsets for the finite difference stencil.
+        deriv_order: The order of the derivative to approximate.
+        stepsize: The stepsize used in the finite difference calculation.
+
+    Returns:
+        An array of finite difference coefficients.
+    """
+    offsets = np.asarray(offsets, dtype=float)
+    n = offsets.size
+
+    matrix = np.zeros((n, n), dtype=float)
+    b = np.zeros(n, dtype=float)
+
+    # Match Taylor expansion up to degree n-1
+    for k in range(n):
+        matrix[k, :] = offsets**k / math.factorial(k)
+    b[deriv_order] = 1.0  # enforce correct derivative of order m
+
+    coeffs = np.linalg.solve(matrix, b) / (stepsize**deriv_order)
+    return coeffs
+
+
+def _build_truncation_orders(
+) -> dict[tuple[int, int], int]:
+    """Dynamically computes the truncation orders for the supported stencil combinations.
+
+    Returns:
+        A dictionary of truncation order for the supported stencil sizes and derivative orders.
+    """
+    out: dict[tuple[int, int], int] = {}
+    h = 1.0
+    for n in STENCILS:
+        k = _central_offsets(n)
+        for m in supported_orders(n):
+            c = _finite_difference_coeffs(k, m, h)
+            out[(n, m)] = truncation_order_from_coeffs(k, c, m)
+    return out
+
+
+#: Dictionary of truncation order for the supported stencil sizes and derivative orders.
+TRUNCATION_ORDER = _build_truncation_orders()
+
+
+def get_finite_difference_tables(
+    stepsize: float,
+) -> tuple[dict[int, list[int]], dict[tuple[int, int], np.ndarray]]:
+    """Dynamically computes offset patterns and coefficient tables.
+
+    Args:
+        stepsize: The step size to use for the stencil spacing.
+
+    Returns:
+        A dictionary of offsets, and a dictionary of coefficient tables,
+        for a range of supported stencil sizes and derivative orders.
+    """
+    offsets = {n: _central_offsets(n).astype(int).tolist() for n in STENCILS}
+    coeffs_table: dict[tuple[int, int], FloatArray] = {}
+
+    for n in STENCILS:
+        k = _central_offsets(n)
+        for m in supported_orders(n):
+            coeffs_table[(n, m)] = _finite_difference_coeffs(k, m, stepsize)
+
+    return offsets, coeffs_table
+
+
+def validate_supported_combo(
+    num_points: int,
+    order: int,
+) -> None:
+    """Validates that the (stencil size, order) combo is supported.
+
+    Args:
+        num_points: Number of points in the finite difference stencil.
+        order: The order of the derivative to compute.
+
+    Raises:
+        ValueError: If the combination of num_points and order is not supported.
+    """
+    if num_points not in STENCILS:
+        raise ValueError(
+            f"[FiniteDifference] Unsupported stencil size: {num_points}. "
+            f"Must be one of {list(STENCILS)}."
+        )
+    if order not in ORDERS:
+        raise ValueError(
+            f"[FiniteDifference] Unsupported derivative order: {order}. "
+            f"Must be one of {list(ORDERS)}."
+        )
+
+    allowed = SUPPORTED_BY_STENCIL[num_points]
+    if order not in allowed:
+        raise ValueError(
+            "[FiniteDifference] Not implemented yet: "
+            f"{num_points}-point stencil for order {order}.\n"
+        )

derivkit/derivatives/fornberg.py

@@ -0,0 +1,245 @@
+"""Implementation of Fornberg's algorithm for numerical derivatives.
+
+The algorithm was published by Fornberg in:
+Bengt Fornberg, *Calculation of Weights in Finite Difference Formulas*,
+SIAM Review, vol. 40, No. 3, pp. 685–691, September 1998
+
+Examples:
+---------
+Calculating the derivative at a single value::
+>>> import numpy as np
+>>> from derivkit.derivatives.fornberg import FornbergDerivative
+>>> x0 = np.pi/4
+>>> grid = np.array([-0.3, -0.25, -0.1, 0, 0.12])
+>>> fornberg = FornbergDerivative(lambda x: np.tan(x), x0)
+>>> bool(np.isclose(
+...     fornberg.differentiate(grid=grid, order=1),
+...     2.0022106298738143,
+...     rtol=1e-14,
+...     atol=0.0,
+... ))
+True
+
+Calculating the derivative at an array of values using uniform offsets::
+>>> import numpy as np
+>>> from derivkit.derivatives.fornberg import FornbergDerivative
+>>> x0 = np.array([
+...     [[1, 2],
+...      [3, 4]],
+...     [[5, 6],
+...      [7,8]]
+... ])
+>>> grid = np.array([-0.34, -0.02, 0.1, 0.34, 0.98])
+>>> fornberg = FornbergDerivative(lambda x: np.cos(x), x0)
+>>> np.allclose(
+...     fornberg.differentiate(grid=grid, order=1),
+...     -np.sin(x0),
+...     rtol=1e-4,
+...     atol=0.0,
+... )
+True
+
+Calculating the derivative at an array of values using 5 unique offsets for
+each evaluation point::
+>>> import numpy as np
+>>> from derivkit.derivatives.fornberg import FornbergDerivative
+>>> x0 = np.array([2, 7, 10, -np.pi])
+>>> grid = np.array([
+...     [-0.34, -0.02, 0.1, 0.34, 0.98],
+...     [-0.4,  -0.2, -0.1, 0.14, 0.68],
+...     [-0.5,  -0.12, 0.15, 0.64, 0.78],
+...     [-0.1,   0,    0.06, 0.24, 0.8]
+... ]).T
+>>> fornberg = FornbergDerivative(lambda x: np.cos(x), x0)
+>>> np.allclose(
+...     fornberg.differentiate(grid=grid, order=1),
+...     -np.sin(x0),
+...     rtol=1e-4,
+...     atol=1e-4,
+... )
+True
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from derivkit.utils.types import Array
+
+
+class FornbergDerivative:
+    """Supplies the Fornberg derivative.
+
+    The Fornberg derivative relies on the interpolation of function values
+    by Lagrange polynomials. For more information see Bengt Fornberg,
+    *Calculation of Weights in Finite Difference Formulas*, SIAM Review,
+    vol. 40, No. 3, pp. 685–691, September 1998.
+
+    Attributes:
+        function: the function to be differentiated. Must accept a single float
+            and return a float, and must be vectorizable.
+        x0: the evaluation points for the derivative. Must be a float or a
+            structure castable to a Numpy array. If it castable to a Numpy array
+            the function and its derivative will be vectorized over the array.
+    """
+
+    def __init__(
+        self,
+        function: Callable[[np.floating], np.floating],
+        x0: np.float64 | NDArray[np.floating],
+    ) -> None:
+        """Initialises the class.
+
+        Args:
+            function: the function to be differentiated. Must accept a single
+                float and return a float, and must be vectorizable.
+            x0: the evaluation points for the derivative. Must be a float or a
+                structure castable to a Numpy array. If it castable to a Numpy
+                array the function and its derivative will be vectorized over
+                the array.
+        """
+        self.function = function
+
+        temp_array = np.asarray(x0)
+        self.original_shape = temp_array.shape
+        self.x0 = np.ravel(temp_array)
+
+
+    def differentiate(
+        self,
+        *,
+        grid: NDArray[np.float64],
+        order: int = 1,
+    ) -> Array:
+        """Constructs the derivative of a given order of a function at a point.
+
+        The derivative is constructed by recursively differentiating the
+        Lagrange polynomials that approximate the function around the
+        evaluation points.
+
+        Because the derivative of a given order is constructed from the
+        derivatives of lower orders (this is part of the recursion) the
+        method is capable of returning all derivatives up to the specified
+        order. However, currently only the highest derivative is returned.
+
+        See section 3 of (Fornberg 1998) for more details.
+
+        Args:
+            grid: an array of offsets relative to the evaluation points. These
+                points specify the Lagrange interpolation of the function,
+                and are used to calculate the derivatives. The following
+                forms are supported:
+
+                * If ``grid`` is a 1D array it is assumed that it contains
+                  linear offsets from the evaluation points. These
+                  are added uniformly to :data:`FornbergDerivative.x0`.
+
+                * If ``grid`` is an ND array it is assumed that it contains
+                  unique linear offsets for each evaluation point. In this
+                  case the first axis of the grid must correspond to the
+                  offsets while the remaining axes must be equal to the shape
+                  of :data:`FornbergDerivative.x0`. In brief, in this case the
+                  grid must be of shape ``(n, *x0.shape)`` for some integer
+                  ``n``.
+
+                  The advantage of this is that, in this case, the offsets can
+                  be tuned for each evaluation point, although each point must
+                  still be given the same number of offsets.
+
+            order: the order of the derivative. Must be a non-negative number.
+                The case of ``order==0`` corresponds to the Lagrange
+                interpolation of the function.
+
+        Returns:
+            The derivative of :data:`FornbergDerivative.function` evaluated at
+                :data:`FornbergDerivative.x0`.
+
+        Raises:
+            ValueError: if ``order`` is smaller than ``0``.
+            RuntimeWarning: if ``grid`` contains duplicate offsets for
+                a given point.
+        """
+        if order < 0:
+            raise ValueError(
+                "the maximum derivative order must be at least 0 "
+                f" (the function itself), but is {order}."
+            )
+
+        if grid.ndim == 1:
+            input_grid = self.x0 + grid[:, np.newaxis]
+        else:
+            input_grid = self.x0 + grid.reshape(grid.shape[0], -1)
+
+        y = self.function(input_grid)
+        try:
+            weights = np.zeros((*input_grid.shape, order+1), dtype=np.float64)
+        # If the algorithm fails then most likely the Lagrange polyonial is not
+        # defined for input_grid. This usually means that the grid has duplicate
+        # entries for a given point, so the algorithm has a divide-by-zero problem.
+        except RuntimeWarning:
+            raise RuntimeError(
+                "Fornberg derivative failed. "
+                "Normally this means that the offset grid does not allow for "
+                "valid Lagrange polynomials. Make sure that the offsets are "
+                "unique for each point."
+            )
+
+        # Numpy passes around references to the array data so the weights
+        # are updated in-place. No assignment is necessary.
+        self._get_weights(weights, input_grid, order)
+        # np.dot contracts the last axis of its first argument with the
+        # second to last index of its second argument. The axes are permuted
+        # to ensure that the function values are contracted with the
+        # coefficients corresponding with the ``order``-th order derivative.
+        # TODO: See if this can be made more transparant.
+        derivatives = np.dot(
+            y.T,
+            np.swapaxes(weights, 0, 1)
+        )[np.arange(self.x0.size), np.arange(self.x0.size), -1]
+
+        return derivatives.reshape(self.original_shape)
+
+    def _get_weights(
+        self,
+        weights: NDArray[np.float64],
+        grid: NDArray[np.float64],
+        order: int = 1,
+    ) -> None:
+        """Constructs the weights needed for derivatives up to a given order.
+
+        Args:
+            weights: the coefficients for the differentiated Lagrange
+                polynomials. The coefficients are updated in place.
+            grid: a series of offsets around the evaluation points.
+            order: the order of the derivative.
+        """
+        c1 = 1.0
+        c4 = grid[0, :] - self.x0
+        weights[0, ..., 0] = 1.0
+
+        for i in range(1, grid.shape[0]):
+            mn = min(i, order)
+            c2 = 1.0
+            c5 = c4
+            c4 = grid[i, :] - self.x0
+
+            for j in range(i):
+                c3 = grid[i, ...] - grid[j, ...]
+                c2 *= c3
+
+                if i == j + 1:
+                    for k in range(mn, 0, -1):
+                        weights[i, ..., k] = c1 * (
+                            k * weights[i-1, ..., k-1]
+                            - c5 * weights[i-1, ..., k]
+                        ) / c2
+                    weights[i, ..., 0] = -c1 * c5 * weights[i-1, ..., 0] / c2
+
+                for k in range(mn, 0, -1):
+                    weights[j, ..., k] = (c4 * weights[j, ..., k] - k * weights[j, ..., k-1]) / c3
+                weights[j, ..., 0] = c4 * weights[j, ..., 0] / c3
+
+            c1 = c2

derivkit/derivatives/local_polynomial_derivative/__init__.py

@@ -0,0 +1 @@
+"""Local polynomial derivative init."""