derivkit 1.0.0__py3-none-any.whl

derivkit/derivative_kit.py

@@ -0,0 +1,315 @@
+"""Provides the DerivativeKit API.
+
+This class is a lightweight front end over DerivKit’s derivative engines.
+You provide the function to differentiate and the expansion point `x0`,
+then choose a backend by name (e.g., ``"adaptive"`` or ``"finite"``).
+
+Examples:
+---------
+Basic usage:
+
+    >>> import numpy as np
+    >>> from derivkit.derivative_kit import DerivativeKit
+    >>> dk = DerivativeKit(function=np.cos, x0=1.0)
+    >>> dk.differentiate(method="adaptive", order=1)  # doctest: +SKIP
+
+Using tabulated data directly:
+
+    >>> import numpy as np
+    >>> from derivkit.derivative_kit import DerivativeKit
+    >>>
+    >>> x_tab = np.array([0.0, 1.0, 2.0, 3.0])
+    >>> y_tab = x_tab**2
+    >>> dk = DerivativeKit(x0=0.5, tab_x=x_tab, tab_y=y_tab)
+    >>> dk.differentiate(order=1, method="finite", extrapolation="ridders")  # doctest: +SKIP
+
+Listing built-in aliases:
+
+    >>> from derivkit.derivative_kit import available_methods
+    >>> available_methods()  # doctest: +SKIP
+
+Adding methods:
+---------------
+New engines can be registered without modifying this class by calling
+:func:`derivkit.derivative_kit.register_method` (see example below).
+
+Registering a new method:
+
+    >>> from derivkit.derivative_kit import register_method  # doctest: +SKIP
+    >>> from derivkit.some_new_method import NewMethodDerivative  # doctest: +SKIP
+    >>> register_method(  # doctest: +SKIP
+    ...     name="new-method",
+    ...     cls=NewMethodDerivative,
+    ...     aliases=("new_method", "nm"),
+    ... )  # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Any, Callable, Iterable, Mapping, Protocol, Type
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from derivkit.derivatives.adaptive.adaptive_fit import AdaptiveFitDerivative
+from derivkit.derivatives.finite.finite_difference import (
+    FiniteDifferenceDerivative,
+)
+from derivkit.derivatives.fornberg import FornbergDerivative
+from derivkit.derivatives.local_polynomial_derivative.local_polynomial_derivative import (
+    LocalPolynomialDerivative,
+)
+from derivkit.derivatives.tabulated_model.one_d import Tabulated1DModel
+
+
+class DerivativeEngine(Protocol):
+    """Protocol each derivative engine must satisfy.
+
+    This defines the minimal interface expected by DerivKit’s derivative
+    backends. Any class registered as a derivative engine must be
+    constructible with a target function ``function`` and an expansion
+    point ``x0``, and must provide a ``.differentiate(...)`` method that
+    performs the actual derivative computation. It serves only as a
+    structural type check (similar to an abstract base class) and carries
+    no runtime behavior. In other words, this is a template for derivative
+    engine implementations.
+    """
+    def __init__(self, function: Callable[[float], Any], x0: float):
+        """Initialize the engine with a target function and expansion point."""
+        ...
+    def differentiate(self, *args: Any, **kwargs: Any) -> Any:
+        """Compute the derivative using the engine’s algorithm."""
+        ...
+
+
+# These are the built-in derivative methods available by default.
+# For each method we allow up to five aliases:
+#   - 3 obvious spelling / punctuation variants
+#   - 2 common short-hands users are likely to type
+# This keeps the interface flexible without bloating the lookup table
+# or introducing ambiguous scheme-level names.
+_METHOD_SPECS: list[tuple[str, Type[DerivativeEngine], list[str]]] = [
+    ("adaptive", AdaptiveFitDerivative, ["adaptive-fit", "adaptive_fit", "ad", "adapt"]),
+    ("finite", FiniteDifferenceDerivative, ["finite-difference", "finite_difference", "fd", "findiff", "finite_diff"]),
+    ("local_polynomial", LocalPolynomialDerivative, ["local-polynomial", "local_polynomial", "lp", "localpoly", "local_poly"]),
+    ("fornberg", FornbergDerivative, ["fb", "forn", "fornberg-fd", "fornberg_fd", "fornberg_weights"]),
+]
+
+
+def _norm(s: str) -> str:
+    """Normalize a method string for robust matching (case/spacing/punct insensitive).
+
+    Args:
+        s: Input string.
+
+    Returns:
+        Normalized string.
+    """
+    return re.sub(r"[^a-z0-9]+", "", s.lower())
+
+
+@lru_cache(maxsize=1)
+def _method_maps() -> tuple[Mapping[str, Type[DerivativeEngine]], tuple[str, ...]]:
+    """Construct and cache lookup tables for derivative methods.
+
+    This function builds the internal mappings that link user-provided method
+    names (and their aliases) to the corresponding derivative engine classes.
+    It also records the canonical method names used for display in help and
+    error messages. The result is cached after the first call for efficiency.
+    Caching means that any changes to the registered methods (via
+    ``register_method``) will not be reflected until the cache is cleared.
+
+    Returns:
+        A tuple containing:
+            A pair ``(method_map, canonical_names)`` where:
+                - ``method_map`` maps normalized names and aliases to engine classes.
+                - ``canonical_names`` lists the sorted canonical method names.
+    """
+    method_map: dict[str, Type[DerivativeEngine]] = {}
+    canonical: set[str] = set()
+    for name, cls, aliases in _METHOD_SPECS:
+        k = _norm(name)
+        method_map[k] = cls
+        canonical.add(k)
+        for a in aliases:
+            method_map[_norm(a)] = cls
+    return method_map, tuple(sorted(canonical))
+
+
+def register_method(
+    name: str,
+    cls: Type[DerivativeEngine],
+    *,
+    aliases: Iterable[str] = (),
+) -> None:
+    """Register a new derivative method.
+
+    Adds a new derivative engine that can be referenced by name in
+    :class:`derivkit.derivative_kit.DerivativeKit`. This function can be called
+    from anywhere in the package (for example, inside a submodule’s
+    ``__init__.py``) and is safe regardless of import order. The internal cache
+    is automatically cleared and rebuilt on the next lookup.
+
+    Args:
+        name: Canonical public name of the method (e.g., ``"gp"``).
+        cls: Engine class implementing the
+            :class:`derivkit.derivative_kit.DerivativeEngine` protocol.
+        aliases: Additional accepted spellings (e.g., ``"gaussian-process"``).
+
+    Registering a new method:
+
+        >>> from derivkit.derivative_kit import register_method  # doctest: +SKIP
+        >>> from derivkit.some_new_method import NewMethodDerivative  # doctest: +SKIP
+        >>> register_method(  # doctest: +SKIP
+        ...     name="new-method",
+        ...     cls=NewMethodDerivative,
+        ...     aliases=("new_method", "nm"),
+        ... )  # doctest: +SKIP
+    """
+    _METHOD_SPECS.append((name, cls, list(aliases)))
+    _method_maps.cache_clear()
+
+
+def _resolve(method: str) -> Type[DerivativeEngine]:
+    """Resolve a user-provided method name or alias to an engine class.
+
+    Args:
+        method: User-provided method name or alias.
+
+    Returns:
+        Corresponding derivative engine class.
+    """
+    method_map, canon = _method_maps()
+    try:
+        return method_map[_norm(method)]
+    except KeyError:
+        opts = ", ".join(canon)
+        raise ValueError(f"Unknown derivative method '{method}'. Choose one of {{{opts}}}.") from None
+
+
+class DerivativeKit:
+    """Unified interface for computing numerical derivatives.
+
+    The class provides a simple way to evaluate derivatives using any of
+    DerivKit’s available backends (e.g., adaptive fit or finite difference).
+    By default, the adaptive-fit method is used.
+
+    You can supply either a function and x0, or tabulated tab_x/tab_y and x0
+    in case you want to differentiate a tabulated function.
+    The chosen backend is invoked when you call the ``.differentiate()`` method.
+
+    Example:
+        >>> import numpy as np
+        >>> from derivkit.derivative_kit import DerivativeKit
+        >>> dk = DerivativeKit(np.cos, x0=1.0)
+        >>> deriv = dk.differentiate(order=1)  # uses the default "adaptive" method
+
+    Attributes:
+        function: The callable to differentiate.
+        x0: The point or points at which the derivative is evaluated.
+        default_method: The backend used when no method is specified.
+    """
+
+    def __init__(
+            self,
+            function: Callable[[float | np.ndarray], Any] | None = None,
+            x0: float | np.ndarray | None = None,
+            *,
+            tab_x: ArrayLike | None = None,
+            tab_y: ArrayLike | None = None,
+    ) -> None:
+        """Initializes the DerivativeKit with a target function and expansion point.
+
+        Args:
+            function: The function to be differentiated. Must accept a single float
+                      and return a scalar or array-like output.
+            x0: Point or array of points at which to evaluate the derivative.
+            tab_x: Optional tabulated x values for creating a
+                :class:`tabulated_model.one_d.Tabulated1DModel`.
+            tab_y: Optional tabulated y values for creating a
+                :class:`tabulated_model.one_d.Tabulated1DModel`.
+        """
+        # Enforce "either function or tabulated", not both.
+        if function is not None and (tab_x is not None or tab_y is not None):
+            raise ValueError("Pass either `function` or (`tab_x`, `tab_y`), not both.")
+
+        if function is not None:
+            self.function = function
+
+        elif tab_x is not None or tab_y is not None:
+            if tab_x is None or tab_y is None:
+                raise ValueError("Both `tab_x` and `tab_y` must be provided for tabulated mode.")
+            model = Tabulated1DModel(tab_x, tab_y)
+            self.function = model
+
+        else:
+            raise ValueError("Need either `function` or (`tab_x`, `tab_y`).")
+
+        if x0 is None:
+            raise ValueError("`x0` must be provided.")
+        self.x0 = x0
+        self.default_method = "adaptive"
+
+    def differentiate(
+            self,
+            *,
+            method: str | None = None,
+            **kwargs: Any,
+    ) -> Any:
+        """Compute derivatives using the chosen method.
+
+        Forwards all keyword arguments to the engine’s ``.differentiate()``.
+
+        Args:
+            method: Method name or alias (e.g., ``"adaptive"``, ``"finite"``,
+                ``"fd"``). Default is ``"adaptive"``.
+            **kwargs: Passed through to the chosen engine.
+
+        Returns:
+            The derivative result from the underlying engine.
+
+            If ``x0`` is a single value, returns the usual derivative output.
+
+            If ``x0`` is an array of points, returns an array where the first
+            dimension indexes the points in ``x0``. For example, if you pass
+            5 points and each derivative has shape ``(2, 3)``, the result has
+            shape ``(5, 2, 3)``.
+
+        Notes:
+            Thread-level parallelism across derivative evaluations can be
+            controlled by passing ``n_workers`` via ``**kwargs``. Note that
+            this does not launch separate Python processes. All work occurs
+            within a single process using worker threads.
+
+        Raises:
+            ValueError: If ``method`` is not recognized.
+        """
+        chosen = method or self.default_method  # use default if None
+        Engine = _resolve(chosen)
+
+        x0_arr = np.asarray(self.x0)
+
+        # scalar x0
+        if x0_arr.ndim == 0:
+            return Engine(self.function, float(x0_arr)).differentiate(**kwargs)
+
+        # array of x0 values
+        results = []
+        for xi in x0_arr.ravel():
+            res = Engine(self.function, float(xi)).differentiate(**kwargs)
+            results.append(res)
+
+        return np.stack(results, axis=0).reshape(
+            x0_arr.shape + np.shape(results[0])
+        )
+
+
+def available_methods() -> dict[str, list[str]]:
+    """Lists derivative methods exposed by this API, including aliases.
+
+    Returns:
+        Dict mapping canonical method name -> list of accepted aliases.
+    """
+    return {name: list(aliases) for name, _, aliases in _METHOD_SPECS}

derivkit/derivatives/__init__.py

@@ -0,0 +1,6 @@
+"""Derivative calculation module.
+
+This module provides various methods for calculating derivatives of functions,
+including finite difference methods, polynomial interpolation, and
+automatic differentiation using JAX.
+"""

derivkit/derivatives/adaptive/__init__.py

@@ -0,0 +1,5 @@
+"""Adaptive numerical differentiation utilities.
+
+Provides batch evaluation, spacing policies, polynomial fitting helpers,
+and an adaptive single-fit derivative estimator for scalar and vector outputs.
+"""

derivkit/derivatives/adaptive/adaptive_fit.py

@@ -0,0 +1,238 @@
+"""Adaptive polynomial-fit derivatives for estimating derivatives from function samples spaced around x0."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from derivkit.derivatives.adaptive.batch_eval import eval_function_batch
+from derivkit.derivatives.adaptive.diagnostics import (
+    fit_is_obviously_bad,
+    make_derivative_diag,
+    print_derivative_diagnostics,
+)
+from derivkit.derivatives.adaptive.grid import (
+    ensure_min_samples_and_maybe_rebuild,
+    make_domain_aware_chebyshev_grid,
+)
+from derivkit.derivatives.adaptive.polyfit_utils import (
+    assess_polyfit_quality,
+    fit_with_headroom_and_maybe_minimize,
+    pullback_derivative_from_fit,
+    scale_offsets,
+)
+from derivkit.utils.logger import derivkit_logger
+
+
+class AdaptiveFitDerivative:
+    """Derivative estimation via a single local polynomial fit around x0."""
+
+    def __init__(self, func, x0: float):
+        """Initialize the estimator.
+
+        Args:
+            func: Callable mapping a float to a scalar or 1D array-like output.
+            x0: Expansion point about which derivatives are computed.
+        """
+        self.func = func
+        self.x0 = float(x0)
+
+    def differentiate(
+            self,
+            order: int,
+            *,
+            n_points: int = 10,
+            spacing: float | str | None = "auto",
+            base_abs: float | None = None,
+            n_workers: int = 1,
+            grid: tuple[str, np.ndarray] | None = None,  # ('offsets'|'absolute', array)
+            domain: "tuple[float | None, float | None] | None" = None,
+            ridge: float = 0.0,
+            return_error: bool = False,
+            diagnostics: bool = False,
+            meta: dict | None = None,
+    ):
+        """Compute the derivative of specified order at x0 using an adaptive polynomial fit.
+
+        Sampling strategy:
+            - grid=None: symmetric Chebyshev offsets around x0 with half-width from `spacing`.
+            - grid=("offsets", arr): explicit offsets t; samples at x = x0 + t (0 inserted if missing).
+            - grid=("absolute", arr): explicit absolute x positions; samples at x = arr.
+
+        Args:
+            order: Derivative order (>=1).
+            n_points: Number of sample points when building the default grid. Default is 10.
+            spacing: Scale for the default symmetric grid around ``x0`` (ignored when ``grid`` is provided).
+
+                Accepted forms:
+
+                - float: interpreted as an absolute half-width ``h``; samples in ``[x0 - h, x0 + h]``.
+                - "<pct>%": percentage string; ``h`` is that fraction of a local scale
+                  set by ``abs(x0)`` with a floor ``base_abs`` near zero.
+                - "auto": choose ``h`` adaptively. DerivKit picks a half-width based on
+                  the local scale of ``x0`` with a minimum of ``base_abs``; if ``domain``
+                  is given, the interval is clipped to stay inside ``(lo, hi)``. The
+                  default grid uses Chebyshev nodes on that interval and always includes
+                  the center point.
+
+            base_abs: Absolute spacing floor used by "auto"/percentage near x0≈0. Defaults to ``1e-3`` if not set.
+            n_workers: Parallel workers for batched function evals (1 = serial).
+            grid: Either ("offsets", array) or ('absolute', array), or None for default.
+
+                This lets the user supply their own sampling points instead of using the
+                automatically built Chebyshev grid. With ``("offsets", arr)``, the array
+                gives relative offsets from ``x0`` (samples at ``x = x0 + t``). With
+                ``('absolute', arr)``, the array gives absolute ``x`` positions. If
+                ``None``, the method builds a symmetric default grid around ``x0``.
+
+            domain: Optional (lo, hi) used to trigger domain-aware transforms in default mode.
+            ridge: Ridge regularization for polynomial fit. Defaults to 0.0.
+
+                This term adds a small penalty to the fit to keep the coefficients from
+                becoming too large when the Vandermonde matrix is nearly singular.
+                Increasing ``ridge`` makes the fit more stable but slightly smoother;
+                setting it to 0 disables the regularization. Default is 0.0.
+
+            return_error: If True, also returns an error proxy based on the RMS residual
+                of the polynomial fit (same shape as the derivative for multi-component outputs).
+
+            diagnostics: If True, return (derivative, diagnostics_dict).
+            meta: Extra metadata to carry in diagnostics.
+
+        Returns:
+            The derivative estimate at x0, optionally accompanied by an error proxy and/or
+            a diagnostics dictionary depending on the flags:
+
+            - If ``return_error`` is False and ``diagnostics`` is False:
+              returns ``deriv``.
+            - If ``return_error`` is True and ``diagnostics`` is False:
+              returns ``(deriv, err)``.
+            - If ``return_error`` is False and ``diagnostics`` is True:
+              returns ``(deriv, diag)``.
+            - If both ``return_error`` and ``diagnostics`` are True:
+              returns ``(deriv, err, diag)``.
+
+        Raises:
+            ValueError: If inputs are invalid or not enough samples are provided.
+        """
+        if order < 1:
+            raise ValueError("order must be >= 1")
+
+        # 1) Choose sample locations (x, t)
+        if grid is not None:
+            if not (isinstance(grid, tuple) and len(grid) == 2 and isinstance(grid[0], str)):
+                raise ValueError("grid must be ('offsets'|'absolute', numpy_array) or None.")
+            kind, arr = grid
+            arr = np.asarray(arr, dtype=float).ravel()
+            match kind:
+                case "offsets":
+                    t = np.sort(np.unique(np.append(arr, 0.0)))  # ensure center; sorted for stability
+                    x = self.x0 + t
+                case "absolute":
+                    x = np.sort(arr)
+                    t = x - self.x0
+                case _:
+                    raise ValueError("grid kind must be 'offsets' or 'absolute'.")
+            mode, spacing_resolved, sign_used = "x", float("nan"), None
+        else:
+            mode, x, t, spacing_resolved, sign_used = make_domain_aware_chebyshev_grid(
+                self.x0,
+                n_points=n_points,
+                spacing=spacing,
+                base_abs=base_abs,
+                domain=domain,
+                max_cheby_points=30,
+            )
+
+        # 1b) Ensure enough samples (rebuild default Chebyshev grids if needed)
+        mode, x, t, spacing_resolved, sign_used = ensure_min_samples_and_maybe_rebuild(
+            mode=mode,
+            x=x,
+            t=t,
+            spacing_resolved=spacing_resolved,
+            sign_used=sign_used,
+            x0=self.x0,
+            order=order,
+            n_points=n_points,
+            spacing=spacing,
+            base_abs=base_abs,
+            max_cheby_points=30,
+        )
+
+        # 2) Evaluate function on the grid
+        ys = eval_function_batch(self.func, x, n_workers=n_workers)
+        if ys.ndim == 1:
+            ys = ys[:, None]
+        n_components = ys.shape[1]
+
+        # 3) Polynomial fit (scaled offsets) with headroom + optional minimal-degree swap
+        u, factor = scale_offsets(t)
+        coeffs, rrms, deg = fit_with_headroom_and_maybe_minimize(
+            u, ys, order=order, mode=mode, ridge=ridge, factor=factor
+        )
+
+        # 3b) Fit quality (soft warnings only)
+        metrics, suggestions = assess_polyfit_quality(
+            u, ys, coeffs, deg, ridge=ridge, factor=factor, order=order
+        )
+        bad, msg = fit_is_obviously_bad(metrics)
+        if bad:
+            pretty_suggestions = "\n  ".join(suggestions)
+            derivkit_logger.info(
+                msg
+                + "\nTo improve this derivative, try:\n  "
+                + pretty_suggestions
+            )
+
+        # 4) Derivative (mode-aware pullback)
+        deriv = pullback_derivative_from_fit(
+            mode=mode,
+            order=order,
+            coeffs=coeffs,
+            factor=factor,
+            x0=self.x0,
+            sign_used=sign_used,
+        )
+        out = deriv.item() if n_components == 1 else deriv
+
+        # error proxy: rrms is just a rough uncertainty indicator from the fit residual.
+        if np.isscalar(rrms) or np.ndim(rrms) == 0:
+            err = float(rrms)
+        else:
+            err = rrms
+
+        if not diagnostics:
+            return (out, err) if return_error else out
+
+        # 5) Diagnostics (optional)
+        degree_out = int(deg) if n_components == 1 else [int(deg)] * n_components
+        diag = make_derivative_diag(
+            x=x,
+            t=t,
+            u=u,
+            y=ys,
+            degree=degree_out,
+            spacing_resolved=spacing_resolved,
+            rrms=rrms,
+            coeffs=coeffs,
+            ridge=ridge,
+            order=order,
+        )
+        meta_payload = {
+            "x0": self.x0,
+            "order": order,
+            "n_points": len(x),
+            "spacing": spacing,
+            "base_abs": base_abs,
+            "spacing_resolved": spacing_resolved,
+            "n_workers": n_workers,
+            "domain": domain,
+            "mode": mode,
+            "ridge": ridge,
+            **(meta or {}),
+        }
+        print_derivative_diagnostics(diag, meta=meta_payload)
+        diag_out = {**diag, "x0": self.x0, "meta": meta_payload}
+
+        if return_error:
+            return out, err, diag_out
+        return out, diag_out