symnum package

Symbolically construct NumPy functions and their derivatives.

symnum.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.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.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.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.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.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.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.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.named_array(name, shape, dtype=None)

Create a symbolic array with common name prefix to elements.

Parameters:

• name (str) – Name prefix to use for symbolic array elements.

• shape (ShapeLike) – Dimensions of array.

• dtype (Optional[DTypeLike]) – NumPy dtype to use for array.

Returns:

Symbolic array with elements name[index_list] for index_list iterating over strings of valid comma-separated indices, for example calling with name=”a” and shape=(2, 2) would give a symbolic array of shape (2, 2) with elements a[0, 0], a[0, 1], a[1, 0] and a[1, 1].

Return type:

SymbolicArray

symnum.numpify(*arg_shapes, **kwargs)

Decorator to convert SymPy symbolic array function to a NumPy function.

Parameters:

• *arg_shapes (tuple[int]) – Variable length list of tuples and integers 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 numpify((2, 2), (2, 4, 3))(func).

• **kwargs – Any keyword arguments to generate_func().

Returns:

Decorator which takes a SymPy function of which accepts one or more SymbolicArray as arguments and returns a symbolic scalar or SymbolicArray value, and returns a corresponding NumPy function which accepts one or more numpy.ndarray arguments and returns a scalar or numpy.ndarray.

Return type:

Callable[[Callable[…, Union[sympy.Expr, SymbolicArray]]], Callable[…, Union[ScalarLike, NDArray]]]

symnum.numpify_func(sympy_func, *arg_shapes, **kwargs)

Generate a NumPy function from a SymPy symbolic array function.

Parameters:

• sympy_func (Callable[..., Union[sympy.Expr, SymbolicArray]]) – Function which takes one or more SymbolicArray as arguments and returns a symbolic scalar expression or SymbolicArray value.

• *arg_shapes (tuple[int]) – Variable length list of tuples or integers 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 numpify_func(func, (2, 2), (2, 4, 3)).

• **kwargs – Any keyword arguments to generate_func().

Returns:

Generated NumPy function which takes one or more numpy.ndarray arguments and return a scalar or numpy.ndarray value.

Return type:

Callable[…, Union[ScalarLike, NDArray]]

symnum.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]]]

Subpackages

• symnum.diffops package
  • Submodules

Submodules

• symnum.array module
  • SymbolicArray
  • as_symbolic_array()
  • binary_broadcasting_func()
  • infer_array_dtype()
  • infer_scalar_dtype()
  • is_array()
  • is_scalar()
  • is_sympy_array()
  • is_valid_shape()
  • named_array()
  • unary_elementwise_func()
• symnum.codegen module
  • FunctionExpression
  • TupleArrayPrinter
  • generate_func()
  • numpify()
  • numpify_func()
• symnum.numpy module
  • abs()
  • absolute()
  • add()
  • angle()
  • arccos()
  • arccosh()
  • arcsin()
  • arcsinh()
  • arctan()
  • arctan2()
  • arctanh()
  • array()
  • ceil()
  • concatenate()
  • conj()
  • conjugate()
  • cos()
  • cosh()
  • divide()
  • exp()
  • expm1()
  • eye()
  • floor()
  • full()
  • identity()
  • imag()
  • iscomplex()
  • isfinite()
  • isinf()
  • isnan()
  • isneginf()
  • isposinf()
  • isreal()
  • log()
  • log10()
  • log1p()
  • log2()
  • logical_and()
  • logical_not()
  • logical_or()
  • logical_xor()
  • matmul()
  • maximum()
  • minimum()
  • multiply()
  • ones()
  • power()
  • prod()
  • real()
  • sign()
  • sin()
  • sinh()
  • sqrt()
  • subtract()
  • sum()
  • tan()
  • tanh()
  • zeros()