derivkit 1.0.0__py3-none-any.whl

derivkit/calculus/hyper_hessian.py

@@ -0,0 +1,296 @@
+"""Construct third-derivative tensors ("hyper-Hessians") for scalar- or tensor-valued functions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from functools import partial
+from itertools import permutations
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from derivkit.calculus.calculus_core import (
+    component_scalar_eval,
+    dispatch_tensor_output,
+)
+from derivkit.derivative_kit import DerivativeKit
+from derivkit.utils.concurrency import (
+    parallel_execute,
+    resolve_inner_from_outer,
+)
+from derivkit.utils.sandbox import get_partial_function
+from derivkit.utils.validate import ensure_finite
+
+__all__ = [
+    "build_hyper_hessian",
+]
+
+
+def build_hyper_hessian(
+    function: Callable[[ArrayLike], float | np.ndarray],
+    theta0: NDArray[np.float64] | Sequence[float],
+    *,
+    method: str | None = None,
+    n_workers: int = 1,
+    **dk_kwargs: Any,
+) -> NDArray[np.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.
+
+    Args:
+        function: Function to differentiate.
+        theta0: 1D Parameter vector where the derivatives are evaluated.
+        method: Derivative method name or alias. If ``None``,
+            the :class:`derivkit.DerivativeKit` default is used.
+        n_workers: Outer parallelism across output components (tensor outputs only).
+        **dk_kwargs: Extra keyword args forwarded to :meth:`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.
+    """
+    theta = np.asarray(theta0, dtype=np.float64).reshape(-1)
+    if theta.size == 0:
+        raise ValueError("theta0 must be a non-empty 1D array.")
+
+    y0 = np.asarray(function(theta))
+    ensure_finite(y0, msg="Non-finite values in model output at theta0.")
+
+    inner_override = dk_kwargs.pop("inner_workers", None)
+    outer_workers = int(n_workers) if n_workers is not None else 1
+    inner_workers = (
+        int(inner_override)
+        if inner_override is not None
+        else resolve_inner_from_outer(outer_workers)
+    )
+
+    if y0.ndim == 0:
+        out = _build_hyper_hessian_scalar(
+            function=function,
+            theta=theta,
+            method=method,
+            inner_workers=inner_workers,
+            outer_workers=outer_workers,
+            **dk_kwargs,
+        )
+
+        ensure_finite(out, msg="Non-finite values encountered in hyper-Hessian.")
+        return out
+
+    # Tensor output: compute per-component scalar hyper-Hessian and reshape it back.
+    return dispatch_tensor_output(
+        function=function,
+        theta=theta,
+        method=method,
+        outer_workers=outer_workers,
+        inner_workers=inner_workers,
+        dk_kwargs=dk_kwargs,
+        build_component=_compute_component_hyper_hessian,
+    )
+
+
+def _build_hyper_hessian_scalar(
+    function: Callable[[ArrayLike], float | np.ndarray],
+    theta: NDArray[np.float64],
+    method: str | None,
+    inner_workers: int | None,
+    outer_workers: int,
+    **dk_kwargs: Any,
+) -> NDArray[np.float64]:
+    """Returns a hyper-Hessian for a scalar-valued function.
+
+    Args:
+        function: Scalar-valued function to differentiate.
+        theta: 1D parameter vector where the derivatives are evaluated..
+        method: Derivative method name or alias. If ``None``,
+            the :class:`derivkit.DerivativeKit` default is used.
+        inner_workers: Number of inner workers for :class:`derivkit.DerivativeKit` calls.
+        outer_workers: Number of outer workers for parallelism over entries.
+        **dk_kwargs: Extra keyword args forwarded to :meth:`derivkit.DerivativeKit.differentiate`.
+
+    Returns:
+        Hyper-Hessian array with shape ``(p, p, p)`` with ``p`` the number of parameters.
+
+    Raises:
+        TypeError: If ``function`` does not return a scalar.
+    """
+    probe = np.asarray(function(theta), dtype=np.float64)
+    if probe.ndim != 0:
+        raise TypeError(
+            "Scalar hyper-Hessian path expects a scalar-valued function; "
+            f"got output with shape {probe.shape}."
+        )
+
+    p = int(theta.size)
+    iw = int(inner_workers or 1)
+
+    # Compute only unique entries i<=j<=k, then symmetrize.
+    triplets: list[tuple[int, int, int]] = [
+        (i, j, k) for i in range(p) for j in range(i, p) for k in range(j, p)
+    ]
+
+    def entry_worker(i: int, j: int, k: int) -> float:
+        """Worker to compute one hyper-Hessian entry.
+
+        Args:
+            i: First parameter index.
+            j: Second parameter index.
+            k: Third parameter index.
+
+        Returns:
+            Value of the third order derivative of the function at theta0.
+        """
+        return _third_derivative_entry(
+            function=function,
+            theta0=theta,
+            i=i,
+            j=j,
+            k=k,
+            method=method,
+            n_workers=iw,
+            dk_kwargs=dk_kwargs,
+        )
+
+    vals = parallel_execute(
+        entry_worker,
+        arg_tuples=triplets,
+        outer_workers=outer_workers,
+        inner_workers=iw,
+    )
+
+    hess = np.zeros((p, p, p), dtype=np.float64)
+    for (i, j, k), v in zip(triplets, vals, strict=True):
+        v = float(np.asarray(v).item())
+        for a, b, c in set(permutations((i, j, k), 3)):
+            hess[a, b, c] = v
+
+    ensure_finite(hess, msg="Non-finite values encountered in hyper-Hessian.")
+    return hess
+
+
+def _third_derivative_entry(
+    *,
+    function: Callable[[ArrayLike], float | np.ndarray],
+    theta0: NDArray[np.float64],
+    i: int,
+    j: int,
+    k: int,
+    method: str | None,
+    n_workers: int,
+    dk_kwargs: dict[str, Any],
+) -> float:
+    """Computes the third order derivative of ``function`` at ``theta0`` with respect to parameters ``i``, ``j``, ``k``.
+
+    Args:
+        function: Scalar-valued function to differentiate.
+        theta0: 1D parameter vector at which the derivative is evaluated.
+        i: First parameter index.
+        j: Second parameter index.
+        k: Third parameter index.
+        method: Derivative method name or alias. If ``None``,
+            the :class:`derivkit.DerivativeKit` default is used.
+        n_workers: Number of workers for :class:`derivkit.DerivativeKit` calls.
+        dk_kwargs: Extra keyword args forwarded to :meth:`derivkit.DerivativeKit.differentiate`.
+
+    Returns:
+        Value of the third order derivative of the function at ``theta0``.
+    """
+    i, j, k = int(i), int(j), int(k)
+    ii, jj, kk = sorted((i, j, k))
+
+    if ii == jj == kk:
+        f1 = get_partial_function(function, ii, theta0)
+        kit = DerivativeKit(f1, float(theta0[ii]))
+        val = kit.differentiate(order=3, method=method, n_workers=n_workers, **dk_kwargs)
+        return float(np.asarray(val).item())
+
+    def g_func(t: float) -> float:
+        """Function for derivative with respect to parameter kk.
+
+        Args:
+            t: Value of parameter kk.
+
+        Returns:
+            Second derivative with respect to ii and jj at theta0 with kk=t.
+
+        """
+        th = theta0.copy()
+        th[kk] = float(t)
+
+        if ii == jj:
+            f1 = get_partial_function(function, ii, th)
+            kit2 = DerivativeKit(f1, float(th[ii]))
+            v2 = kit2.differentiate(order=2, method=method, n_workers=n_workers, **dk_kwargs)
+            return float(np.asarray(v2).item())
+
+        # mixed second derivative via nested 1D partials
+        def h_func(yj: float) -> float:
+            """Function for derivative with respect to parameter jj.
+
+            Args:
+                yj: Value of parameter jj.
+
+            Returns:
+                First derivative with respect to ii at theta0 with jj=yj and kk fixed.
+            """
+            th2 = th.copy()
+            th2[jj] = float(yj)
+            f_ii = get_partial_function(function, ii, th2)
+            kit1 = DerivativeKit(f_ii, float(th2[ii]))
+            v1 = kit1.differentiate(order=1, method=method, n_workers=n_workers, **dk_kwargs)
+            return float(np.asarray(v1).item())
+
+        kitm = DerivativeKit(h_func, float(th[jj]))
+        vm = kitm.differentiate(order=1, method=method, n_workers=n_workers, **dk_kwargs)
+        return float(np.asarray(vm).item())
+
+    kit3 = DerivativeKit(g_func, float(theta0[kk]))
+    v3 = kit3.differentiate(order=1, method=method, n_workers=n_workers, **dk_kwargs)
+    return float(np.asarray(v3).item())
+
+
+def _compute_component_hyper_hessian(
+    idx: int,
+    theta: NDArray[np.float64],
+    method: str | None,
+    inner_workers: int | None,
+    dk_kwargs: dict[str, Any],
+    function: Callable[[ArrayLike], float | np.ndarray],
+) -> NDArray[np.float64]:
+    """Computes the hyper-Hessian for one output component of a tensor-valued function.
+
+    Args:
+        idx: Index of the output component to differentiate.
+        theta: Parameter vector where the derivatives are evaluated.
+        method: Derivative method name or alias. If ``None``,
+            the :class:`derivkit.DerivativeKit` default is used.
+        inner_workers: Number of inner workers for :class:`derivkit.DerivativeKit` calls.
+        dk_kwargs: Extra keyword args forwarded to :meth:`derivkit.DerivativeKit.differentiate`.
+        function: Original tensor-valued function.
+
+    Returns:
+        Hyper-Hessian array with shape ``(p, p, p)`` with ``p`` the number of parameters.
+    """
+    g = partial(component_scalar_eval, function=function, idx=int(idx))
+    # Use scalar builder with outer_workers=1 (parallel computation is already over components outside)
+    return _build_hyper_hessian_scalar(
+        g,
+        theta,
+        method=method,
+        inner_workers=inner_workers,
+        outer_workers=1,
+        **dk_kwargs,
+    )

derivkit/calculus/jacobian.py

@@ -0,0 +1,156 @@
+"""Contains functions used to construct the Jacobian matrix."""
+
+from collections.abc import Callable
+from functools import partial
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from derivkit.derivative_kit import DerivativeKit
+from derivkit.utils.concurrency import (
+    parallel_execute,
+    resolve_inner_from_outer,
+)
+from derivkit.utils.sandbox import get_partial_function
+
+
+def build_jacobian(
+    function: Callable[[ArrayLike], ArrayLike | float],
+    theta0: ArrayLike,
+    method: str | None = None,
+    n_workers: int | None = 1,
+    **dk_kwargs: Any,
+) -> NDArray[np.floating]:
+    """Computes the Jacobian of a vector-valued function.
+
+    Each column in the Jacobian is the derivative with respect to one parameter.
+
+    Args:
+        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 :class:`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
+            :meth:`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.
+    """
+    # Validate inputs and evaluate baseline output
+    theta = np.asarray(theta0, dtype=float).ravel()
+    if theta.size == 0:
+        raise ValueError("theta0 must be a non-empty 1D array.")
+
+    y0 = np.asarray(function(theta), dtype=float)
+    if y0.ndim != 1:
+        raise TypeError(
+            f"build_jacobian expects f: R^n -> R^m with 1-D vector output; got shape {y0.shape}"
+        )
+    if not np.isfinite(y0).all():
+        raise FloatingPointError("Non-finite values in model output at theta0.")
+
+    m = int(y0.size)
+    n = int(theta.size)
+
+    # Resolve parallelism policy
+    try:
+        outer_workers = max(1, int(n_workers or 1))
+    except (TypeError, ValueError):
+        outer_workers = 1
+    inner_workers = resolve_inner_from_outer(outer_workers)
+
+    # Prepare worker
+    worker = partial(
+        _column_derivative,
+        function=function,
+        theta0=theta,
+        method=method,
+        inner_workers=inner_workers,
+        expected_m=m,
+        **dk_kwargs,
+    )
+
+    # Parallelize across parameters
+    cols = parallel_execute(
+        worker,
+        arg_tuples=[(j,) for j in range(n)],
+        outer_workers=outer_workers,
+        inner_workers=inner_workers,  # passed for context; we also pass explicitly to worker
+    )
+
+    # Stack columns → (m, n)
+    jac = np.column_stack([np.asarray(c, dtype=float).reshape(m) for c in cols])
+    return jac
+
+
+def _column_derivative(
+    j: int,
+    function: Callable[[ArrayLike], ArrayLike | float],
+    theta0: ArrayLike,
+    method: str | None,
+    inner_workers: int | None,
+    expected_m: int,
+    **dk_kwargs: Any,
+) -> NDArray[np.floating]:
+    """Derivative of function with respect to parameter j.
+
+    Args:
+        j: Index of the parameter to differentiate with respect to.
+        function: The vector-valued function to be differentiated.
+        theta0: The parameter vector at which the jacobian is evaluated.
+        method: Method name or alias (e.g., ``"adaptive"``, ``"finite"``).
+            If ``None``, the :class:`derivkit.derivative_kit.DerivativeKit`
+            default (``"adaptive"``) is used.
+        inner_workers: Number of workers used by
+            :meth:`derivkit.derivative_kit.DerivativeKit.differentiate`.
+        **dk_kwargs: Additional keyword arguments passed to
+            :meth:`derivkit.derivative_kit.DerivativeKit.differentiate`.
+        expected_m: Expected length of the derivative vector.
+
+    Returns:
+        A 1D array representing the derivative with respect to parameter j.
+
+    Raises:
+        TypeError: If the derivative does not have the expected length.
+        FloatingPointError: If non-finite values are encountered.
+    """
+    theta_x = np.asarray(theta0, dtype=float).ravel().copy()
+
+    # Single-variable view: f_j(y) where theta_x[j] = y, others fixed
+    f_j = get_partial_function(function, j, theta_x)
+
+    # Normalize method aliases for the new DK API
+    # (let DK handle validation; we only map common shorthands)
+    method_norm = None
+    if method is not None:
+        m = method.lower()
+        alias = {"auto": "adaptive", "fd": "finite"}
+        method_norm = alias.get(m, m)
+
+    # Differentiate via new unified API (passes method through)
+    kit = DerivativeKit(f_j, theta_x[j])
+    g = kit.differentiate(method=method_norm, order=1, n_workers=inner_workers, **dk_kwargs)
+
+    g = np.atleast_1d(np.asarray(g, dtype=float)).reshape(-1)
+    if g.size != expected_m:
+        raise TypeError(
+            f"Expected derivative of length {expected_m} but got {g.size} for parameter index {j}."
+        )
+    if not np.isfinite(g).all():
+        raise FloatingPointError(f"Non-finite derivative for parameter index {j}.")
+
+    return g

derivkit/calculus_kit.py

@@ -0,0 +1,128 @@
+"""Provides the CalculusKit class.
+
+A wrapper around the calculus helpers that exposes the gradient, Jacobian, and Hessian functions.
+
+Typical usage examples:
+
+>>> import numpy as np
+>>> from derivkit.calculus_kit import CalculusKit
+>>>
+>>> def sin_function(x):
+...     # scalar-valued function: f(x) = sin(x[0])
+...     return np.sin(x[0])
+>>>
+>>> def identity_function(x):
+...     # vector-valued function: f(x) = x
+...     return np.asarray(x, dtype=float)
+>>>
+>>> calc = CalculusKit(sin_function, x0=np.array([0.5]))
+>>> grad = calc.gradient()
+>>> hess = calc.hessian()
+>>>
+>>> jac = CalculusKit(identity_function, x0=np.array([1.0, 2.0])).jacobian()
+"""
+
+from collections.abc import Callable
+from typing import Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from derivkit.calculus import (
+    build_gradient,
+    build_hessian,
+    build_hessian_diag,
+    build_hyper_hessian,
+    build_jacobian,
+)
+
+
+class CalculusKit:
+    """Provides access to gradient, Jacobian, and Hessian tensors."""
+
+    def __init__(
+        self,
+        function: Callable[[Sequence[float] | np.ndarray], float | NDArray[np.floating]],
+        x0: Sequence[float] | np.ndarray,
+    ):
+        """Initialises class with function and expansion point.
+
+        Args:
+            function: The function to be differentiated. Accepts a 1D
+                array-like. Must return either a scalar (for gradient/Hessian)
+                or a 1D array (for Jacobian).
+            x0: Point at which to evaluate derivatives (shape ``(p,)``) for
+                ``p`` input parameters.
+        """
+        self.function = function
+        self.x0 = np.asarray(x0, dtype=float)
+
+    def gradient(self, *args, **kwargs) -> NDArray[np.floating]:
+        """Returns the gradient of a scalar-valued function.
+
+        This is a wrapper around :func:`derivkit.calculus.build_gradient`,
+        with the ``function`` and ``theta0`` arguments fixed to the values
+        provided at initialization of :class:`CalculusKit`. Any additional
+        positional or keyword arguments are forwarded to
+        :func:`derivkit.calculus.build_gradient`.
+
+        Refer to the documentation of
+        :func:`derivkit.calculus.build_gradient` for available options.
+        """
+        return build_gradient(self.function, self.x0, *args, **kwargs)
+
+    def jacobian(self, *args, **kwargs) -> NDArray[np.floating]:
+        """Returns the Jacobian of a vector-valued function.
+
+        This is a wrapper around :func:`derivkit.calculus.build_jacobian`,
+        with the ``function`` and ``theta0`` arguments fixed to the values
+        provided at initialization of :class:`CalculusKit`. Any additional
+        positional or keyword arguments are forwarded to
+        :func:`derivkit.calculus.build_jacobian`.
+
+        Refer to the documentation of
+        :func:`derivkit.calculus.build_jacobian` for available options.
+        """
+        return build_jacobian(self.function, self.x0, *args, **kwargs)
+
+    def hessian(self, *args, **kwargs) -> NDArray[np.floating]:
+        """Returns the Hessian of a scalar-valued function.
+
+        This is a wrapper around :func:`derivkit.calculus.build_hessian`,
+        with the ``function`` and ``theta0`` arguments fixed to the values
+        provided at initialization of :class:`CalculusKit`. Any additional
+        positional or keyword arguments are forwarded to
+        :func:`derivkit.calculus.build_hessian`.
+
+        Refer to the documentation of
+        :func:`derivkit.calculus.build_hessian` for available options.
+        """
+        return build_hessian(self.function, self.x0, *args, **kwargs)
+
+    def hessian_diag(self, *args, **kwargs) -> NDArray[np.floating]:
+        """Returns the diagonal of the Hessian of a scalar-valued function.
+
+        This is a wrapper around :func:`derivkit.calculus.build_hessian_diag`,
+        with the ``function`` and ``theta0`` arguments fixed to the values
+        provided at initialization of :class:`CalculusKit`. Any additional
+        positional or keyword arguments are forwarded to
+        :func:`derivkit.calculus.build_hessian_diag`.
+
+        Refer to the documentation of
+        :func:`derivkit.calculus.build_hessian_diag` for available options.
+        """
+        return build_hessian_diag(self.function, self.x0, *args, **kwargs)
+
+    def hyper_hessian(self, *args, **kwargs) -> NDArray[np.floating]:
+        """Returns the third-derivative tensor of a function.
+
+        This is a wrapper around :func:`derivkit.calculus.build_hyper_hessian`,
+        with the ``function`` and ``theta0`` arguments fixed to the values
+        provided at initialization of :class:`CalculusKit`. Any additional
+        positional or keyword arguments are forwarded to
+        :func:`derivkit.calculus.build_hyper_hessian`.
+
+        Refer to the documentation of
+        :func:`derivkit.calculus.build_hyper_hessian` for available options.
+        """
+        return build_hyper_hessian(self.function, self.x0, *args, **kwargs)