derivkit.calculus.hessian module

Contains functions used in constructing the Hessian of a scalar-valued function.

derivkit.calculus.hessian.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.hessian.build_hessian_diag(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

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 DerivativeKit default (“adaptive”) is used.

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

  • **dk_kwargs – Additional keyword arguments passed to 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.