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:
Returns:

A 1D array representing the gradient.

Raises:

TypeError – If function does not return a scalar value.

derivkit.calculus.build_hessian(function: Callable[[ArrayLike], 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:
Returns:

  • (p, p) if function(theta0) is scalar with p the number of parameters.

  • (*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_hessian_diag(function: Callable[[ArrayLike], float | ndarray], theta0: ndarray, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → ndarray#

Returns the diagonal of the 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 derivkit.derivative_kit.DerivativeKit default ("adaptive") is used.

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

  • **dk_kwargs – Additional keyword arguments passed to derivkit.derivative_kit.DerivativeKit.differentiate(). You may optionally pass inner_workers=<int> here to override the inner policy.

Returns:

Returns only the diagonal entries of the Hessian.

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

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

This reduction in rank is intentional to avoid computing or storing off-diagonal terms.

Raises:

  • FloatingPointError – If non-finite values are encountered.

  • ValueError – If theta0 is an empty array.

  • TypeError – If evaluating a single output component does not return a scalar.

derivkit.calculus.build_hyper_hessian(function: Callable[[ArrayLike], float | ndarray], theta0: ndarray[tuple[Any, ...], dtype[float64]] | Sequence[float], *, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns the third-derivative tensor (“hyper-Hessian”) of a function.

This function computes all third-order partial derivatives of a scalar- or vector-valued function with respect to its parameters, evaluated at a single point in parameter space. The resulting tensor generalizes the Hessian to third order and is useful for higher-order Taylor expansions, non-Gaussian approximations, and sensitivity analyses beyond quadratic order.

Parameters:

  • function – Function to differentiate.

  • theta0 – 1D Parameter vector where the derivatives are evaluated.

  • method – Derivative method name or alias. If None, the derivkit.DerivativeKit default is used.

  • n_workers – Outer parallelism across output components (tensor outputs only).

  • **dk_kwargs – Extra keyword args forwarded to derivkit.DerivativeKit.differentiate(). You may pass inner_workers=<int> here to override inner parallelism.

Returns:

Third-derivative tensor. For scalar outputs, the result has shape (p, p, p), where p is the number of parameters. For tensor-valued outputs with shape out_shape, the result has shape (*out_shape, p, p, p).

Raises:

  • ValueError – If theta0 is empty.

  • FloatingPointError – If non-finite values are encountered.

derivkit.calculus.build_jacobian(function: Callable[[ArrayLike], ArrayLike | float], theta0: ArrayLike, method: str | None = None, n_workers: int | None = 1, **dk_kwargs: Any) → 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 derivkit.derivative_kit.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 derivkit.derivative_kit.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.