symnum.diffops.symbolic module#

Autograd-style functional differential operators for symbolic functions.

symnum.diffops.symbolic.grad(func, *, wrt=0, return_aux=False)#

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

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

Parameters:

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

  • 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).

Returns:

Generated gradient function.

Return type:

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

symnum.diffops.symbolic.gradient(func, *, wrt=0, return_aux=False)[source]#

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

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

Parameters:

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

  • 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).

Returns:

Generated gradient function.

Return type:

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

symnum.diffops.symbolic.hessian(func, *, wrt=0, return_aux=False)[source]#

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

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

Parameters:

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

  • 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).

Returns:

Generated Hessian function.

Return type:

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

symnum.diffops.symbolic.hessian_vector_product(func, *, wrt=0, return_aux=False)[source]#

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

The passed function should take as arguments symbolic arrays and return a symbolic scalar, and likewise the returned operator will take symbolic 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.

  • 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).

Returns:

Generated Hessian-vector-product operator.

Return type:

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

symnum.diffops.symbolic.jacobian(func, *, wrt=0, return_aux=False)[source]#

Generate a function to evaluate the Jacobian of a function.

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

Parameters:

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

  • 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).

Returns:

Generated Jacobian function.

Return type:

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

symnum.diffops.symbolic.jacobian_vector_product(func, *, wrt=0, return_aux=False)[source]#

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

The passed function should take as arguments and return symbolic array(s), and likewise the returned operator will take symbolic 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.

  • 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).

Returns:

Generated Jacobian-vector-product operator.

Return type:

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

symnum.diffops.symbolic.matrix_hessian_product(func, *, wrt=0, return_aux=False)[source]#

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

The passed function should take as arguments and return symbolic array(s), and likewise the returned function will act on symbolic 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.

  • 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).

Returns:

Generated matrix-Hessian-product operator.

Return type:

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

symnum.diffops.symbolic.matrix_tressian_product(func, *, wrt=0, return_aux=False)[source]#

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

The passed function should take as arguments symbolic arrays and return a symbolic scalar, and likewise the returned operator will take symbolic 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.

  • 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).

Returns:

Generated matrix-Tressian-product operator.

Return type:

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

symnum.diffops.symbolic.vector_jacobian_product(func, *, wrt=0, return_aux=False)[source]#

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

The passed function should take as arguments and return symbolic array(s), and likewise the returned function will act on symbolic 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.

  • 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).

Returns:

Generated vector-Jacobian-product operator.

Return type:

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

On this page
Show Source