derivkit.adaptive.adaptive_fit module

Adaptive polynomial-fit derivatives for estimating derivatives from function samples spaced around x0.

class derivkit.adaptive.adaptive_fit.AdaptiveFitDerivative(func, x0: float)

Bases: object

Derivative estimation via a single local polynomial fit around x0.

Initialize the estimator.

Parameters:

  • func – Callable mapping a float to a scalar or 1D array-like output.

  • x0 – Expansion point about which derivatives are computed.

differentiate(order: int, *, n_points: int = 10, spacing: float | str | None = 'auto', base_abs: float | None = None, n_workers: int = 1, grid: tuple[str, ndarray] | None = None, domain: tuple[float | None, float | None] | None = None, ridge: float = 0.0, 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.

Parameters:

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

  • diagnostics – If True, return (derivative, diagnostics_dict).

  • meta – Extra metadata to carry in diagnostics.

Returns:

Derivative at x0 (scalar or 1D array). If diagnostics=True, also returns a dict.

Raises:

ValueError – If inputs are invalid or not enough samples are provided.