specular.calculation.jacobian

Copy

jacobian(f, x, h=None)

Evaluate a specular Jacobian with the selected backend. Also available as specular.jacobian.

Parameters

Name	Description
f	Callable taking a one-dimensional real vector and returning a nonempty one-dimensional real vector of fixed shape.
x	Nonempty one-dimensional array-like of finite real coordinates.
h	Finite, positive, concrete real scalar shared by all coordinates, or None for automatic coordinatewise selection. Default: None.

Returns

A matrix of shape (m, n), where n is the input dimension and m is the output dimension. Entry (i, j) is the specular derivative of output component i with respect to input coordinate j. NumPy and Numba return NumPy arrays; JAX returns JAX arrays.

Notes

The center value is evaluated once, with two additional samples per input coordinate. Automatic steps are selected separately for each coordinate. Validation and backend constraints match those of gradient.

The JAX backend samples coordinates in bounded batches. The returned matrix still requires storage proportional to m * n. See the backend guide for dtype and callback requirements.

Examples

Copy

import numpy as np
from specular.calculation import jacobian

def f(x):
    return np.array([x[0] + 2.0 * x[1], 3.0 * x[0] - x[1]])

print(jacobian(f, [1.0, 2.0]))
# approximately [[1, 2], [3, -1]]

Source code in specular/calculation.py

Copy

def jacobian(f: Any, x: Any, h: Any = None) -> Any:
    """Evaluate a specular Jacobian with the selected backend.

    If ``h`` is omitted, a separate step is selected for each coordinate from
    the backend dtype and coordinate scale. An explicit ``h`` must be a
    concrete, finite, positive real scalar and is validated before ``f`` is
    evaluated.
    """

    validated_h = None if h is None else _positive_step(h)
    backend = _get_selected_backend()
    return backend.jacobian(f, x, validated_h)