derivkit.calculus.calculus_core module#

Core utilities for calculus-based derivative computations.

This module provides shared helper functions for building derivative objects (gradients, Jacobians, Hessians, higher-order tensors) of scalar- and tensor-valued functions using DerivativeKit.

derivkit.calculus.calculus_core.component_scalar_eval(theta_vec: ndarray[tuple[Any, ...], dtype[float64]], *, function: Callable[[ArrayLike], float | ndarray], idx: int) → float#

Evaluates a single element of the model output function(theta_vec) as a scalar.

This helper is used internally when building derivatives of models that return multiple outputs (e.g. vectors or arrays). Derivative routines operate on scalar-valued functions, so one output component is selected and treated as a scalar function of the parameters.

Parameters:

  • theta_vec – 1D parameter vector.

  • function – Original function.

  • idx – Index of the output component to differentiate, where the output is first flattened with NumPy C-order (i.e. np.ravel(y, order="C")).

Returns:

Scalar value of the specified output component.

Raises:

IndexError – If idx is out of bounds for the model output.

derivkit.calculus.calculus_core.dispatch_tensor_output(function: Callable[[ArrayLike], float | ndarray], theta: ndarray[tuple[Any, ...], dtype[float64]], *, method: str | None, outer_workers: int, inner_workers: int | None, dk_kwargs: dict[str, Any], build_component: Callable[[int, ndarray[tuple[Any, ...], dtype[float64]], str | None, int | None, dict[str, Any], Callable[[ArrayLike], float | ndarray]], ndarray[tuple[Any, ...], dtype[float64]]]) → ndarray[tuple[Any, ...], dtype[float64]]#

Computes per-output-component derivative objects for tensor-valued outputs and reshapes back.

This helper is intended for functions whose output has one or more dimensions (i.e. function(theta) returns an array). Scalar-valued functions should be handled by the scalar derivative routines (e.g. gradient, hessian, or derivative) and must not be routed through this dispatcher.

The function uses the following strategy:

  1. Evaluate y0 = function(theta)

  2. Flatten tensor output into m scalar components

  3. For each component idx, compute a scalar-output derivative object

  4. Stack and reshape to (*out_shape, *derivative_object_shape)

Parameters:

  • function – Original function.

  • theta – 1D parameter vector.

  • method – Derivative method name or alias.

  • outer_workers – Parallelism across output components.

  • inner_workers – Parallelism forwarded to DerivativeKit inside each component calculation.

  • dk_kwargs – Keyword args forwarded to DerivativeKit.differentiate (already stripped of inner_workers).

  • build_component – Per-component builder with signature: (idx, theta, method, inner_workers, dk_kwargs, function) -> ndarray

Returns:

Array with shape (*out_shape, *derivative_object_shape).

Raises:

  • FloatingPointError – If non-finite values are encountered.

  • ValueError – If function(theta) is scalar (use scalar path in caller).