derivkit.derivative_kit module#

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)

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")

Listing built-in aliases:

>>> from derivkit.derivative_kit import available_methods
>>> available_methods()

Adding methods:#

New engines can be registered without modifying this class by calling derivkit.derivative_kit.register_method() (see example below).

Registering a new method:

>>> from derivkit.derivative_kit import register_method
>>> from derivkit.some_new_method import NewMethodDerivative
>>> register_method(
...     name="new-method",
...     cls=NewMethodDerivative,
...     aliases=("new_method", "nm"),
... )

class derivkit.derivative_kit.DerivativeEngine(function: Callable[[float], Any], x0: float)#

Bases: 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.

Initialize the engine with a target function and expansion point.

differentiate(*args: Any, **kwargs: Any) → Any#: Compute the derivative using the engine’s algorithm.

Bases: object

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

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.

Initializes the DerivativeKit with a target function and expansion point.

Parameters:

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 tabulated_model.one_d.Tabulated1DModel.
tab_y – Optional tabulated y values for creating a tabulated_model.one_d.Tabulated1DModel.

differentiate(*, method: str | None = None, **kwargs: Any) → Any#

Compute derivatives using the chosen method.

Forwards all keyword arguments to the engine’s .differentiate().

Parameters:

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

Raises:

ValueError – If method is not recognized.

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

derivkit.derivative_kit.register_method(name: str, cls: Type[DerivativeEngine], *, aliases: Iterable[str] = ()) → None#

Adds a new derivative engine that can be referenced by name in 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.

Parameters:

name – Canonical public name of the method (e.g., "gp").
cls – Engine class implementing the derivkit.derivative_kit.DerivativeEngine protocol.
aliases – Additional accepted spellings (e.g., "gaussian-process").

Registering a new method:

>>> from derivkit.derivative_kit import register_method
>>> from derivkit.some_new_method import NewMethodDerivative
>>> register_method(
...     name="new-method",
...     cls=NewMethodDerivative,
...     aliases=("new_method", "nm"),
... )