derivkit 1.0.0__py3-none-any.whl

derivkit/derivatives/finite/__init__.py

@@ -0,0 +1,5 @@
+"""Finite difference derivatives package.
+
+Provides implementations of numerical derivative calculations
+using finite difference methods.
+"""

derivkit/derivatives/finite/batch_eval.py

@@ -0,0 +1,91 @@
+"""Batch evaluation utilities for finite-difference methods."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Sequence
+
+import numpy as np
+
+from derivkit.utils.concurrency import (
+    parallel_execute,
+    resolve_inner_from_outer,
+)
+
+__all__ = ["eval_points"]
+
+
+def _all_scalar_like(xs: Sequence[Any]) -> bool:
+    """Returns ``True`` if all entries in ``xs`` are scalar-like.
+
+    Scalar-like means:
+    - Python scalar, or
+    - 0-dim numpy array.
+    """
+    for x in xs:
+        if np.isscalar(x):
+            continue
+        if isinstance(x, np.ndarray) and x.shape == ():
+            continue
+        return False
+    return True
+
+
+def eval_points(
+    func: Callable[[Any], Any],
+    xs: Sequence[Any],
+    n_workers: int | None = None,
+) -> np.ndarray:
+    """Evaluates ``func`` at a sequence of points.
+
+    Args:
+        func: Callable taking a single argument (scalar or array-like).
+        xs: 1D sequence of points at which to evaluate ``func``.
+            Entries may be scalars or array-like objects (e.g. vectors/tensors).
+        n_workers: Number of parallel outer workers. If ``None`` or <=1,
+            runs serially. If greater than the number of points, capped to
+            that number.
+
+    Returns:
+        An array of function values at the specified points.
+    """
+    xs_list = list(xs)
+    if not xs_list:
+        return np.asarray([], dtype=float)
+
+    scalar_like = _all_scalar_like(xs_list)
+    args = _to_eval_args(xs_list, scalar_like)
+
+    outer_workers = _cap_outer_workers(n_workers, len(args))
+    inner_workers = resolve_inner_from_outer(outer_workers)
+
+    # parallel_execute handles both outer >1 and outer == 1 paths.
+    arg_tuples = [(x,) for x in args]
+    vals = parallel_execute(
+        worker=func,
+        arg_tuples=arg_tuples,
+        outer_workers=outer_workers,
+        inner_workers=inner_workers,
+    )
+
+    return np.asarray(vals)
+
+
+def _to_eval_args(xs: Sequence[Any], scalar_like: bool) -> list[Any]:
+    """Prepare arguments for evaluation.
+
+    If all entries are scalar-like, cast to float (legacy behaviour).
+    Otherwise, pass through as-is to support tensor/array inputs.
+    """
+    if scalar_like:
+        return [float(x) for x in xs]
+    return list(xs)
+
+
+def _cap_outer_workers(n_workers: int | None, n_tasks: int) -> int:
+    """Cap outer workers by number of tasks; ensure at least ``1``."""
+    if n_workers is None or n_workers <= 1:
+        return 1
+    n = int(n_workers)
+    if n_tasks <= 0:
+        return 1
+    return max(1, min(n, int(n_tasks)))

derivkit/derivatives/finite/core.py

@@ -0,0 +1,84 @@
+"""Finite difference derivative estimation with a single step size."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .batch_eval import eval_points
+from .stencil import get_finite_difference_tables
+
+__all__ = [
+    "single_finite_step",
+]
+
+
+def single_finite_step(
+    function,
+    x0: float,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+) -> NDArray | float:
+    """Returns one central finite-difference estimate at a given step size h.
+
+    Args:
+        function:
+            The function whose derivative is to be estimated. Must accept
+            a float or NumPy array and return a float or NumPy array.
+        x0:
+            The point at which to evaluate the derivative.
+        order:
+            The order of the derivative to compute.
+        stepsize:
+            The step size (h) used to evaluate the function around x0.
+        num_points:
+            The number of points in the finite difference stencil. Must be
+            one of [3, 5, 7, 9].
+        n_workers:
+            The number of workers to use in multiprocessing. Default is ``1``.
+
+    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.
+    """
+    offsets, coeffs_table = get_finite_difference_tables(stepsize)
+    key = (num_points, order)
+    if key not in coeffs_table:
+        raise ValueError(
+            f"[FiniteDifference] Internal table missing coefficients for "
+            f"stencil={num_points}, order={order}."
+        )
+
+    stencil = np.array(
+        [x0 + i * stepsize for i in offsets[num_points]],
+        dtype=float,
+    )
+
+    # values shape: (n_stencil,) for scalar outputs, (n_stencil, *out_shape) otherwise
+    values = eval_points(function, stencil, n_workers=n_workers)
+    values = np.asarray(values, dtype=float)
+
+    coeff = np.asarray(coeffs_table[key], dtype=float)  # shape (n_stencil,)
+
+    if values.ndim == 1:  # this is the scalar-valued case
+        deriv = float(np.dot(coeff, values))
+        return deriv
+
+    # In the case of vector and tensor outputs, use tensordot to contract
+    # the leading stencil dimension with the coeffs.
+    # coeff shape: (n_stencil,)
+    # values shape: (n_stencil, ... )
+    # deriv shape: (...) after contraction.
+    deriv = np.tensordot(coeff, values, axes=(0, 0))
+
+    if np.ndim(deriv) == 0:
+        return float(deriv)
+
+    # Otherwise flatten trailing dims in C order to match the rest of DerivKit.
+    return np.ravel(deriv, order="C")

derivkit/derivatives/finite/extrapolators.py

@@ -0,0 +1,511 @@
+"""Finite difference extrapolation utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from derivkit.utils.extrapolation import (
+    gauss_richardson_extrapolate,
+    richardson_extrapolate,
+    ridders_extrapolate,
+)
+
+__all__ = [
+    "fixed_richardson_fd",
+    "fixed_ridders_fd",
+    "adaptive_richardson_fd",
+    "adaptive_ridders_fd",
+    "fixed_gre_fd",
+    "adaptive_gre_fd",
+]
+
+
+def fixed_richardson_fd(
+    single_finite: Callable[[int, float, int, int], NDArray | float],
+    *,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+    levels: int,
+    p: int = 2,
+    r: float = 2.0,
+    return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns fixed-level Richardson extrapolation for finite differences.
+
+    Fixed level means we compute m base estimates with step sizes h, h/r, h/r^2, ..., h/r^(m-1)
+    and then apply Richardson extrapolation to get the final estimate.
+
+    Args:
+        single_finite: Function that computes a single finite difference estimate.
+        order: The order of the derivative to compute.
+        stepsize: The initial step size h.
+        num_points: Number of points in the finite difference stencil.
+        n_workers: Number of parallel workers to use.
+        levels: Number of levels (m) for Richardson extrapolation.
+        p: The order of the leading error term in the finite difference
+            approximation. Default is ``2``.
+        r: The step-size reduction factor between successive levels
+            (default is ``2.0``).
+        return_error: Whether to return an error estimate along with the
+            value (default is ``False``).
+
+    Returns:
+        The Richardson-extrapolated finite difference estimate. If `return_error` is True,
+        also returns an error estimate.
+    """
+    if levels < 2:
+        raise ValueError("fixed_richardson_fd requires levels >= 2 for Richardson extrapolation.")
+
+    base_values: list[NDArray | float] = []
+    h = float(stepsize)
+
+    for _ in range(levels):
+        base_values.append(single_finite(order, h, num_points, n_workers))
+        h /= r
+
+    est = richardson_extrapolate(base_values, p=p, r=r)
+
+    if not return_error:
+        return est
+
+    est_arr = np.asarray(est, dtype=float)
+
+    # With only two levels, we can’t form a previous Richardson estimate; use zeros.
+    if levels == 2:
+        err = np.zeros_like(est_arr)
+        return est, err
+
+    prev_est = richardson_extrapolate(base_values[:-1], p=p, r=r)
+    prev_arr = np.asarray(prev_est, dtype=float)
+    err = np.abs(est_arr - prev_arr)
+    return est, err
+
+
+def fixed_ridders_fd(
+    single_finite: Callable[[int, float, int, int], NDArray | float],
+    *,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+    levels: int,
+    p: int = 2,
+    r: float = 2.0,
+    return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns a fixed-level Ridders extrapolation for finite differences.
+
+    Fixed level means we compute m base estimates with step sizes h, h/r, h/r^2, ..., h/r^(m-1)
+    and then apply Ridders extrapolation to get the final estimate.
+
+    Args:
+        single_finite:
+            Function that computes a single finite difference estimate.
+        order:
+            The order of the derivative to compute.
+        stepsize:
+            The initial step size h.
+        num_points:
+            Number of points in the finite difference stencil.
+        n_workers:
+            Number of parallel workers to use.
+        levels:
+            Number of levels (m) for Ridders extrapolation.
+        p:
+            The order of the leading error term in the finite difference
+            approximation (default is ``2``).
+        r:
+            The step-size reduction factor between successive levels
+            (default is ``2.0``).
+        return_error:
+            Whether to return an error estimate along with the value
+            (default is ``False``).
+
+    Returns:
+        The Ridders-extrapolated finite difference estimate. If `return_error` is True,
+        also returns an error estimate.
+    """
+    base_values: list[NDArray | float] = []
+    h = float(stepsize)
+
+    for _ in range(levels):
+        base_values.append(single_finite(order, h, num_points, n_workers))
+        h /= r
+
+    value, err = ridders_extrapolate(base_values, r=r, p=p)
+    return (value, err) if return_error else value
+
+
+def adaptive_richardson_fd(
+    single_finite: Callable[[int, float, int, int], NDArray | float],
+    *,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+    p: int,
+    max_levels: int = 6,
+    min_levels: int = 2,
+    r: float = 2.0,
+    rtol: float = 1e-8,
+    atol: float = 1e-12,
+    return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns an adaptive Richardson extrapolation for finite differences.
+
+    This function computes finite difference estimates at decreasing step sizes
+    and applies Richardson extrapolation iteratively until convergence is achieved
+    based on specified tolerances.
+
+    Args:
+        single_finite: Function that computes a single finite difference
+            estimate.
+        order: The order of the derivative to compute.
+        stepsize: The initial step size h.
+        num_points: Number of points in the finite difference stencil.
+        n_workers: Number of parallel workers to use.
+        p: The order of the leading error term in the finite difference
+            approximation.
+        max_levels: Maximum number of levels of extrapolation to perform
+            (default is ``6``).
+        min_levels: Minimum number of levels of extrapolation before checking
+            for convergence. Default is ``2``.
+        r: The step-size reduction factor between successive levels
+            (default is ``2.0``).
+        rtol: Relative tolerance for convergence (default is ``1e-8``).
+        atol: Absolute tolerance for convergence (default is ``1e-12``).
+        return_error: Whether to return an error estimate along with the value
+            (default is ``False``).
+
+    Returns: The Richardson-extrapolated finite difference estimate.
+    """
+    base_values: list[NDArray | float] = []
+    h = float(stepsize)
+
+    best = None
+    best_est = None
+    last_err = None
+
+    for level in range(max_levels):
+        val = single_finite(order, h, num_points, n_workers)
+        base_values.append(val)
+        h /= r
+
+        if level + 1 < min_levels:
+            continue
+
+        est = richardson_extrapolate(base_values, p=p, r=r)
+
+        if best_est is None:
+            best_est = est
+            best = est
+            continue
+
+        est_arr = np.asarray(est, dtype=float)
+        best_arr = np.asarray(best_est, dtype=float)
+
+        diff = np.max(np.abs(est_arr - best_arr))
+        scale = np.max([1.0, np.max(np.abs(est_arr)), np.max(np.abs(best_arr))])
+        err_arr = np.full_like(est_arr, diff)
+
+        if diff <= atol + rtol * scale:
+            if not return_error:
+                return est
+            err = np.zeros_like(est_arr) if last_err is None else last_err
+            return est, err
+
+        if diff > 10.0 * (atol + rtol * scale):
+            if not return_error:
+                return best
+            return best, err_arr
+
+        last_err = err_arr
+        best_est = est
+        best = est
+
+    if best_est is None:
+        best_est = base_values[-1]
+        last_err = np.zeros_like(np.asarray(best_est, dtype=float))
+
+    if not return_error:
+        return best_est
+    return best_est, last_err
+
+
+def adaptive_ridders_fd(
+        single_finite: Callable[[int, float, int, int], NDArray | float],
+        *,
+        order: int,
+        stepsize: float,
+        num_points: int,
+        n_workers: int,
+        p: int,
+        max_levels: int = 6,
+        min_levels: int = 2,
+        r: float = 2.0,
+        rtol: float = 1e-8,
+        atol: float = 1e-12,
+        return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns an adaptive Ridders extrapolation for finite differences.
+
+    This function computes finite difference estimates at decreasing step sizes,
+    building up a sequence of base values and repeatedly applying Ridders
+    extrapolation until convergence is achieved based on specified tolerances.
+
+    Args:
+        single_finite: Function that computes a single finite difference
+            estimate for a given derivative order and step size
+            ``single_finite(order, h, num_points, n_workers)``.
+        order: The order of the derivative to compute.
+        stepsize: The initial step size ``h``.
+        num_points: Number of points in the finite difference stencil.
+        n_workers: Number of parallel workers to use.
+        p: The order of the leading error term in the finite difference
+            approximation.
+        max_levels: Maximum number of levels of extrapolation to perform
+            (default is ``6``).
+        min_levels: Minimum number of levels of extrapolation before checking
+            for convergence (default is ``2``).
+        r: Step-size reduction factor between successive levels
+            (default is ``2.0``).
+        rtol: Relative tolerance for convergence (default is 1e-8).
+        atol: Absolute tolerance for convergence (default is 1e-12).
+        return_error: Whether to return an error estimate along with the value
+            (default is ``False``).
+
+    Returns:
+        The Ridders-extrapolated finite difference estimate.
+    """
+    base_values: list[NDArray | float] = []
+    h = float(stepsize)
+
+    best_est: NDArray | float | None = None
+    best_err: NDArray | float | None = None
+
+    for level in range(max_levels):
+        val = single_finite(order, h, num_points, n_workers)
+        base_values.append(val)
+        h /= r
+
+        if level + 1 < min_levels:
+            continue
+
+        est, err = ridders_extrapolate(base_values, p=p, r=r)
+
+        if best_est is None:
+            best_est = est
+            best_err = err
+            continue
+
+        est_arr = np.asarray(est, dtype=float)
+        best_arr = np.asarray(best_est, dtype=float)
+
+        diff = np.max(np.abs(est_arr - best_arr))
+        scale = np.max([1.0, np.max(np.abs(est_arr)), np.max(np.abs(best_arr))])
+        thresh = atol + rtol * scale
+        diff_arr = np.full_like(est_arr, diff)
+
+        # Converged: we accept latest estimate
+        if diff <= thresh:
+            if not return_error:
+                return est
+            out_err = err if err is not None else diff_arr
+            return est, out_err
+
+        # Diverged badly: we fall back to previous best
+        if diff > 10.0 * thresh:
+            if not return_error:
+                return best_est
+            out_err = best_err if best_err is not None else diff_arr
+            return best_est, out_err
+
+        best_est = est
+        best_err = err
+
+    if best_est is None:
+        best_est = base_values[-1]
+        best_err = np.zeros_like(np.asarray(best_est, dtype=float))
+
+    if not return_error:
+        return best_est
+    return best_est, best_err
+
+
+def fixed_gre_fd(
+    single_finite: Callable[[int, float, int, int], NDArray | float],
+    *,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+    p: int,
+    levels: int,
+    r: float = 2.0,
+    return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns a fixed-level Gauss–Richardson extrapolation for finite differences.
+
+    Fixed level means we compute m base estimates with step sizes h, h/r, h/r^2, ..., h/r^(m-1)
+    and then apply Gauss–Richardson extrapolation to get the final estimate.
+
+    Args:
+        single_finite: Function that computes a single finite difference
+            estimate.
+        order: The order of the derivative to compute.
+        stepsize: The initial step size h.
+        num_points: Number of points in the finite difference stencil.
+        n_workers: Number of parallel workers to use.
+        p: The order of the leading error term in the finite difference
+            approximation.
+        levels: Number of levels (m) for Gauss–Richardson extrapolation.
+        r: The step-size reduction factor between successive levels
+            (default is ``2.0``).
+        return_error: Whether to return an error estimate along with the
+            value (default is ``False``).
+
+    Returns:
+        The Gauss–Richardson-extrapolated finite difference estimate. If
+        `return_error` is True, also returns an error estimate.
+
+    Raises:
+        ValueError: If the combination of ``num_points`` and ``order`` is not
+        supported or if levels < 2.
+    """
+    if levels < 2:
+        raise ValueError("fixed_gre_fd requires levels >= 2.")
+
+    base_values: list[NDArray | float] = []
+    h_values: list[float] = []
+    h = float(stepsize)
+
+    for _ in range(levels):
+        base_values.append(single_finite(order, h, num_points, n_workers))
+        h_values.append(h)
+        h /= r
+
+    value, err = gauss_richardson_extrapolate(base_values, h_values=h_values, p=p)
+    return (value, err) if return_error else value
+
+
+def adaptive_gre_fd(
+    single_finite: Callable[[int, float, int, int], NDArray | float],
+    *,
+    order: int,
+    stepsize: float,
+    num_points: int,
+    n_workers: int,
+    p: int,
+    max_levels: int = 6,
+    min_levels: int = 2,
+    r: float = 2.0,
+    rtol: float = 1e-8,
+    atol: float = 1e-12,
+    return_error: bool = False,
+) -> NDArray | float | tuple[NDArray | float, NDArray | float]:
+    """Returns an adaptive Gauss–Richardson extrapolation for finite differences.
+
+    This function computes finite-difference estimates at decreasing step sizes,
+    builds up sequences of base values and corresponding step sizes, and applies
+    Gauss–Richardson extrapolation iteratively until convergence based on the
+    change between successive estimates.
+
+    Args:
+        single_finite: Function that computes a single finite-difference
+            estimate for a given derivative order and step size
+            ``single_finite(order, h, num_points, n_workers)``.
+        order: The order of the derivative to compute.
+        stepsize: The initial step size ``h``.
+        num_points: Number of points in the finite-difference stencil.
+        n_workers: Number of parallel workers to use.
+        p: The order of the leading error term in the finite difference
+            approximation.
+        max_levels: Maximum number of levels of extrapolation to perform
+            (default is ``6``).
+        min_levels: Minimum number of levels of extrapolation before checking
+            for convergence (default is ``2``).
+        r: Step-size reduction factor between successive levels
+            (default is ``2.0``).
+        rtol: Relative tolerance for convergence
+            (default is ``1e-8``).
+        atol: Absolute tolerance for convergence
+            (default is ``1e-12``).
+        return_error: Whether to return an error estimate along with the value
+            (default is ``False``).
+
+    Returns:
+        The Gauss–Richardson-extrapolated finite-difference estimate. If
+        ``return_error`` is True, also returns an error estimate with the
+        same shape as the estimate.
+    """
+    base_values: list[NDArray | float] = []
+    h_values: list[float] = []
+    h = float(stepsize)
+
+    best_est: NDArray | float | None = None
+    last_err: NDArray | float | None = None
+
+    result_est: NDArray | float | None = None
+    result_err: NDArray | float | None = None
+
+    for level in range(max_levels):
+        val = single_finite(order, h, num_points, n_workers)
+        base_values.append(val)
+        h_values.append(h)
+        h /= r
+
+        if level + 1 < min_levels:
+            continue
+
+        est, _ = gauss_richardson_extrapolate(
+            base_values,
+            h_values=h_values,
+            p=p,
+        )
+
+        if best_est is None:
+            best_est = est
+            continue
+
+        est_arr = np.asarray(est, dtype=float)
+        best_arr = np.asarray(best_est, dtype=float)
+
+        diff = np.max(np.abs(est_arr - best_arr))
+        scale = np.max([1.0, np.max(np.abs(est_arr)), np.max(np.abs(best_arr))])
+        thresh = atol + rtol * scale
+        err_arr = np.full_like(est_arr, diff)
+
+        # Converged: accept latest estimate
+        if diff <= thresh:
+            result_est = est
+            # if we have a previous error, keep it; otherwise use this diff
+            result_err = last_err if last_err is not None else err_arr
+            break
+
+        # Diverged badly: fall back to previous best
+        if diff >= 10.0 * thresh:
+            result_est = best_est
+            result_err = err_arr
+            break
+
+        # Continue refining
+        best_est = est
+        last_err = err_arr
+
+    if result_est is None:
+        if best_est is None:
+            best_est = base_values[-1]
+            last_err = np.zeros_like(np.asarray(best_est, dtype=float))
+        result_est = best_est
+        if last_err is None:
+            last_err = np.zeros_like(np.asarray(result_est, dtype=float))
+        result_err = last_err
+
+    if not return_error:
+        return result_est
+    return result_est, result_err