derivkit.calculus.hessian module#

Utilities for constructing Hessians of scalar- or vector-valued functions.

derivkit.calculus.hessian.build_hessian(function: Callable[[ArrayLike], float | ndarray], theta0: ndarray, method: str | None = None, n_workers: int = 1, dk_init_kwargs: dict[str, Any] | None = None, **dk_diff_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 derivkit.derivative_kit.DerivativeKit default ("adaptive") is used.

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

  • dk_init_kwargs – Optional keyword arguments passed to derivkit.derivative_kit.DerivativeKit during initialization. This can include cache-related settings.

  • **dk_diff_kwargs – Additional keyword arguments passed to derivkit.derivative_kit.DerivativeKit.differentiate().

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 function does not return a scalar or a 1D vector.

derivkit.calculus.hessian.build_hessian_diag(function: Callable[[ArrayLike], float | ndarray], theta0: ndarray, method: str | None = None, n_workers: int = 1, dk_init_kwargs: dict[str, Any] | None = None, **dk_diff_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_init_kwargs – Optional keyword arguments passed to derivkit.derivative_kit.DerivativeKit during initialization. This can include cache-related settings.

  • **dk_diff_kwargs – Additional keyword arguments passed to derivkit.derivative_kit.DerivativeKit.differentiate().

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 function does not return a scalar or a 1D vector.