derivkit.calculus package

Submodules

Module contents

Calculus utilities.

Provides constructors for gradient, Jacobian, and Hessian computations.

derivkit.calculus.build_gradient(function: Callable, theta0: ndarray, method: str | None = None, n_workers=1, **dk_kwargs: dict) → ndarray

Returns the gradient of a scalar-valued function.

Parameters:

  • function (Callable) – The function to be differentiated.

  • theta0 (array-like) – The parameter vector at which the gradient is evaluated.

  • method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.

  • n_workers (int) – Number of workers used by DerivativeKit.adaptive.differentiate. This setting does not parallelize across parameters. Default is 1.

  • dk_kwargs (dict, optional) – Additional keyword arguments passed to DerivativeKit.differentiate.

Returns:

A 1D array representing the gradient.

Raises:

TypeError – If function does not return a scalar value.

derivkit.calculus.build_hessian(function: Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]], float | ndarray], theta0: ndarray, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → ndarray[tuple[Any, ...], dtype[floating]]

Returns the full Hessian of a function.

Parameters:

  • function – The function to be differentiated.

  • theta0 – The parameter vector at which the Hessian is evaluated.

  • method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.

  • n_workers – Parallel tasks across output components / Hessian entries.

  • **dk_kwargs – Extra options forwarded to DerivativeKit.differentiate.

Returns:

  • (p, p) if function(theta0) is scalar.

  • (*out_shape, p, p) if function(theta0) has shape out_shape.

The output shape is fixed; use build_hessian_diag() if only the diagonal is needed.

Return type:

Always returns the full Hessian with shape

Raises:

  • FloatingPointError – If non-finite values are encountered.

  • ValueError – If theta0 is an empty array.

  • TypeError – If a single output component (flattened scalar subpath) does not return a scalar.

derivkit.calculus.build_jacobian(function: Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]], Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | float], theta0: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], method: str | None = None, n_workers: int | None = 1, dk_kwargs: dict | None = None) → ndarray[tuple[Any, ...], dtype[floating]]

Computes the Jacobian of a vector-valued function.

Each column in the Jacobian is the derivative with respect to one parameter.

Parameters:

  • function – The vector-valued function to be differentiated. It should accept a list or array of parameter values as input and return an array of observable values.

  • theta0 – The parameter vector at which the jacobian is evaluated.

  • method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.

  • n_workers – Number of workers used to parallelize across parameters. If None or 1, no parallelization is used. If greater than 1, this many threads will be used to compute derivatives with respect to different parameters in parallel.

  • dk_kwargs – Additional keyword arguments passed to DerivativeKit.differentiate.

Returns:

A 2D array representing the jacobian. Each column corresponds to

the derivative with respect to one parameter.

Raises:

  • FloatingPointError – If non-finite values are encountered.

  • ValueError – If theta0 is an empty array.

  • TypeError – If function does not return a vector value.