symnum.diffops.numpy module#

Autograd-style functional differential operators for NumPy functions.

symnum.diffops.numpy.grad(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate a function to evaluate the gradient of a scalar-valued function.

The passed function should take as arguments NumPy arrays and return a NumPy scalar, and likewise the returned function will take NumPy array arguments.

Parameters:

  • func (Callable[..., ScalarLike]) – Function which takes one or more arrays as arguments and returns a scalar.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form gradient(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated gradient function returns both the gradient and value of func as a 2-tuple (True) or just the gradient (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated gradient function.

Return type:

Callable[…, Union[ArrayLike, tuple[ArrayLike, ScalarLike]]]

symnum.diffops.numpy.gradient(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate a function to evaluate the gradient of a scalar-valued function.

The passed function should take as arguments NumPy arrays and return a NumPy scalar, and likewise the returned function will take NumPy array arguments.

Parameters:

  • func (Callable[..., ScalarLike]) – Function which takes one or more arrays as arguments and returns a scalar.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form gradient(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated gradient function returns both the gradient and value of func as a 2-tuple (True) or just the gradient (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated gradient function.

Return type:

Callable[…, Union[ArrayLike, tuple[ArrayLike, ScalarLike]]]

symnum.diffops.numpy.hessian(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate a function to evaluate the Hessian of a scalar-valued function.

The passed function should take as arguments NumPy arrays and return a NumPy scalar, and likewise the returned function will take NumPy array arguments.

Parameters:

  • func (Callable[..., ScalarLike]) – Function which takes one or more arrays as arguments and returns a scalar.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form hessian(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated Hessian function returns the Hessian, gradient and value of func as a 3-tuple (True) or just the Hessian (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated Hessian function.

Return type:

Callable[…, Union[ArrayLike, tuple[ArrayLike, ArrayLike, ScalarLike]]]

symnum.diffops.numpy.hessian_vector_product(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate an operator to evaluate Hessian-vector-products for a function.

The passed function should take as arguments NumPy arrays and return a NumPy scalar, and likewise the returned operator will take NumPy array arguments.

For a single argument function func, n-dimensional input array x and n-dimensional ‘vector’ array v of the same shape as x then we have the following equivalence

hessian_vector_product(func)(x)(v) == tensordot(hessian(func)(x), v, n)

where tensordot follows its NumPy semantics, i.e. tensordot(a, b, n) sums the products of components of a and b over the last n axes (dimensions) of a and first n dimensions of b.

Parameters:

  • func (Callable[..., ScalarLike]) – Function which takes one or more arrays as arguments and returns a scalar.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form hessian_vector_product(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated operator returns the Hessian-vector-product function, gradient and value of func as a 3-tuple (True) or just the Hessian-vector-product function (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated Hessian-vector-product operator.

Return type:

Callable[…, Union[Callable[[ArrayLike], ArrayLike], tuple[Callable[[ArrayLike], ArrayLike], ArrayLike, ScalarLike]]]

symnum.diffops.numpy.jacobian(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate a function to evaluate the Jacobian of a function.

The passed function should take as arguments and return NumPy array(s), and likewise the returned function will take NumPy array arguments.

Parameters:

  • func (Callable[..., ArrayLike]) – Function which takes one or more arrays as arguments and returns an array.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form jacobian(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated Jacobian function returns both the Jacobian and value of func as a 2-tuple (True) or just the Jacobian (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated Jacobian function.

Return type:

Callable[…, Union[ArrayLike, tuple[ArrayLike, ArrayLike]]]

symnum.diffops.numpy.jacobian_vector_product(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate an operator to evaluate Jacobian-vector-products for a function.

The passed function should take as arguments and return NumPy array(s), and likewise the returned operator will take NumPy array arguments.

For a single argument function func, n-dimensional input array x and n-dimensional ‘vector’ array v of the same shape as x then we have the following equivalence

jacobian_vector_product(func)(x)(v) == tensordot(jacobian(func)(x), v, n)

where tensordot follows its NumPy semantics, i.e. tensordot(a, b, n) sums the products of components of a and b over the last n axes (dimensions) of a and first n dimensions of b.

Parameters:

  • func (Callable[..., ArrayLike]) – Function which takes one or more arrays as arguments and returns an array.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form jacobian_vector_product(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated operator returns the Jacobian-vector-product function and value of func as a 2-tuple (True) or just the Jacobian-vector-product function (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated Jacobian-vector-product operator.

Return type:

Callable[…, Union[Callable[[ArrayLike], ArrayLike], tuple[Callable[[ArrayLike], ArrayLike], ArrayLike]]]

symnum.diffops.numpy.matrix_hessian_product(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate an operator to evaluate matrix-Hessian-products for a function.

The passed function should take as arguments and return NumPy array(s), and likewise the returned function will act on NumPy arrays.

For a single argument function func, n-dimensional input array x and k + n-dimensional ‘matrix’ array m with shape func(x).shape + x.shape then we have the following equivalence

matrix_hessian_product(func)(x)(m) == (
    tensordot(m, jacobian(jacobian(func))(x), k + n)
)

where tensordot follows its NumPy semantics, i.e. tensordot(a, b, n) sums the products of components of a and b over the last n axes (dimensions) of a and first n dimensions of b.

Parameters:

  • func (Callable[..., ArrayLike]) – Function which takes one or more arrays as arguments and returns an array.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form matrix_hessian_product(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated operator return the matrix-Hessian-product function, Jacobian and value of func as a 3-tuple (True) or just the matrix-Hessian-product function (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated matrix-Hessian-product operator.

Return type:

Callable[…, Union[Callable[[ArrayLike], ArrayLike], tuple[Callable[[ArrayLike], ArrayLike], ArrayLike, ArrayLike]]]

symnum.diffops.numpy.matrix_tressian_product(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate an operator to evaluate matrix-Tressian-products for a function.

The passed function should take as arguments NumPy arrays and return a NumPy scalar, and likewise the returned operator will take NumPy array arguments.

For a single argument function func, n-dimensional input array x and (2 * n)-dimensional ‘matrix’ array m of shape x.shape + x.shape then we have the following equivalence

matrix_tressian_product(func)(x)(m) == (
    tensordot(jacobian(hessian(func))(x), 2 * n)
)

where tensordot follows its NumPy semantics, i.e. tensordot(a, b, n) sums the products of components of a and b over the last n axes (dimensions) of a and first n dimensions of b.

Parameters:

  • func (Callable[..., ScalarLike]) – Function which takes one or more arrays as arguments and returns a scalar.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form matrix_tressian_product(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated operator returns the matrix-Tressian-product function, Hessian, gradient and value of func as a 4-tuple (True) or just the matrix-Tressian-product function (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated matrix-Tressian-product operator.

Return type:

Callable[…, Union[Callable[[ArrayLike], ArrayLike], tuple[Callable[[ArrayLike], ArrayLike], ArrayLike, ArrayLike, ScalarLike]]]

symnum.diffops.numpy.vector_jacobian_product(func, *arg_shapes, wrt=0, return_aux=False, **kwargs)#

Generate an operator to evaluate vector-Jacobian-products for a function.

The passed function should take as arguments and return NumPy array(s), and likewise the returned function will act on NumPy arrays.

For a single argument function func, input array x and n-dimensional ‘vector’ array v of the same shape as func(x) then we have the following equivalence

vector_jacobian_product(func)(x)(v) == tensordot(v, jacobian(func)(x), n)

where tensordot follows its NumPy semantics, i.e. tensordot(a, b, n) sums the products of components of a and b over the last n axes (dimensions) of a and first n dimensions of b.

Parameters:

  • func (Callable[..., ArrayLike]) – Function which takes one or more arrays as arguments and returns an array.

  • *arg_shapes (tuple[int, ...]) – Variable length list of tuples defining shapes of array arguments to func, e.g. if func takes two arguments x and y with x an array with shape (2, 2) and y an array with shape (2, 4, 3) the call signature would be of the form vector_jacobian_product(func, (2, 2), (2, 4, 3), ...).

  • wrt (int) – Index of argument to take derivatives with respect to.

  • return_aux (bool) – Whether the generated operator returns the vector-Jacobian-product function and value of func as a 2-tuple (True) or just the vector-Jacobian-product function (False).

  • **kwargs – Any keyword arguments to the NumPy code generation function symnum.codegen.generate_func().

Returns:

Generated vector-Jacobian-product operator.

Return type:

Callable[…, Union[Callable[[ArrayLike], ArrayLike], tuple[Callable[[ArrayLike], ArrayLike], ArrayLike]]]

On this page
Show Source