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

Adding methods

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

Examples

Basic usage:

>>> import numpy as np
>>> from derivkit.derivative_kit import DerivativeKit
>>> dk = DerivativeKit(function=np.cos, x0=1.0)
>>> # First derivative via the adaptive-fit method:
>>> # dk.differentiate(method="adaptive", order=1)

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

Notes

  • Method names are case/spacing/punctuation insensitive; aliases like "adaptive-fit" or "finite_difference" are supported when registered.

  • For available canonical method names at runtime, call available_methods().

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.

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

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). You only need to supply a function and the point x0 at which to compute the derivative. By default, the adaptive-fit method is used.

Example

>>> import numpy as np
>>> from derivkit.derivative_kit import DerivativeKit
>>> d = DerivativeKit(np.cos, x0=1.0)
>>> d.differentiate(order=1)  # uses the default "adaptive" method
function

The callable to differentiate.

x0

The point at which the derivative is evaluated.

DEFAULT_METHOD

The default 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 at which to evaluate the derivative.

differentiate(*, method: str = 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.

Raises:

ValueError – If method is not recognized.

derivkit.derivative_kit.available_methods() → list[str]

List canonical method names exposed by this API.

Returns:

List of method names.

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

  • aliases – Additional accepted spellings (e.g., “gaussian-process”).

Example

>>> from derivkit.derivative_api import register_method
>>> from derivkit.gp.gp_derivative import GPDerivative
>>> register_method(
...     name="gp",
...     cls=GPDerivative,
...     aliases=("gaussian-process", "gaussproc"),
... )
>>> # After registration, it can be used via:
>>> # DerivativeKit(f, x0).differentiate(method="gp")