Evaluate Functions#

This module provides evaluation methods for (the gradient, Hessian or Jacobian) of a function.

Core

function(fun[, wrt, ntrax, parallel])

Evaluate a function.

gradient(fun[, wrt, ntrax, parallel, ...])

Evaluate the gradient of a scalar-valued function.

hessian(fun[, wrt, ntrax, parallel, ...])

Evaluate the Hessian of a scalar-valued function.

jacobian(fun[, wrt, ntrax, parallel, ...])

Evaluate the Jacobian of a tensor-valued function.

gradient_vector_product(fun[, wrt, ntrax, ...])

Evaluate the gradient-vector-product of a scalar-valued function.

hessian_vector_product(fun[, wrt, ntrax, ...])

Evaluate the Hessian-vector-product of a scalar-valued function.

hessian_vectors_product(fun[, wrt, ntrax, ...])

Evaluate the vector-Hessian-vector- or Hessian-vectors-product of a scalar- valued function.

Detailed API Reference

tensortrax.function(fun, wrt=0, ntrax=0, parallel=False)[source]#

Evaluate a function.

Parameters:

  • fun (callable) – The function to be evaluated.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0).

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the function in parallel (threaded).

Returns:

NumPy array containing the function result.

Return type:

ndarray

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>>
>>> F.shape
(3, 3, 8, 20)

>>> W = tr.function(fun, wrt=0, ntrax=2)(F)
>>> W = tr.function(fun, wrt="F", ntrax=2)(F=F)
>>>
>>> W.shape
>>> (8, 20)
tensortrax.gradient(fun, wrt=0, ntrax=0, parallel=False, full_output=False, sym=False)[source]#

Evaluate the gradient of a scalar-valued function.

Parameters:

  • fun (callable) – The function to be evaluated.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The gradient is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the gradient in parallel (threaded).

  • full_output (bool, optional) – Return the gradient and the function (default is False).

  • sym (bool, optional) – Apply the variations only on the upper-triangle entries of a symmetric second order tensor. This is a performance feature and requires no modification of the callable fun and the input arguments, including wrt. Default is False.

Returns:

NumPy array containing the gradient result. If full_output=True, the function is also returned.

Return type:

ndarray or list of ndarray

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>>
>>> F.shape
(3, 3, 8, 20)

>>> dWdF = tr.gradient(fun, wrt=0, ntrax=2)(F)
>>> dWdF = tr.gradient(fun, wrt="F", ntrax=2)(F=F)
>>>
>>> dWdF.shape
>>> (3, 3, 8, 20)
tensortrax.hessian(fun, wrt=0, ntrax=0, parallel=False, full_output=False, sym=False)[source]#

Evaluate the Hessian of a scalar-valued function.

Parameters:

  • fun (callable) – The function to be evaluated.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The Hessian is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the Hessian in parallel (threaded).

  • full_output (bool, optional) – Return the hessian, the gradient and the function (default is False).

  • sym (bool, optional) – Apply the variations only on the upper-triangle entries of a symmetric second order tensor. This is a performance feature and requires no modification of the callable fun and the input arguments, including wrt. Default is False.

Returns:

NumPy array containing the Hessian result. If full_output=True, the gradient and the function are also returned.

Return type:

ndarray or list of ndarray

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>>
>>> F.shape
(3, 3, 8, 20)

>>> d2WdFdF = tr.hessian(fun, wrt=0, ntrax=2)(F)
>>> d2WdFdF = tr.hessian(fun, wrt="F", ntrax=2)(F=F)
>>>
>>> d2WdFdF.shape
>>> (3, 3, 3, 3, 8, 20)
tensortrax.jacobian(fun, wrt=0, ntrax=0, parallel=False, full_output=False)[source]#

Evaluate the Jacobian of a tensor-valued function.

Parameters:

  • fun (callable) – The function to be evaluated.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The Jacobian is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the Jacobian in parallel (threaded).

  • full_output (bool, optional) – Return the Jacobian and the function (default is False).

Returns:

NumPy array containing the Jacobian result.

Return type:

ndarray

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(C, mu=1):
>>>     I3 = tm.linalg.det(C)
>>>     return mu * tm.special.dev(I3 ** (-1 / 3) * C) @ tm.linalg.inv(C)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>> C = np.einsum("ki...,kj...->ij...", F, F)
>>>
>>> C.shape
(3, 3, 8, 20)

>>> dSdC = tr.jacobian(fun, wrt=0, ntrax=2)(C)
>>> dSdC = tr.jacobian(fun, wrt="C", ntrax=2)(C=C)
>>>
>>> dSdC.shape
>>> (3, 3, 3, 3, 8, 20)
tensortrax.gradient_vector_product(fun, wrt=0, ntrax=0, parallel=False)[source]#

Evaluate the gradient-vector-product of a scalar-valued function.

Parameters:

  • fun (callable) – The function to be evaluated. Its signature is extended to fun(*args, δx, **kwargs)(), where the added δx-argument is the vector of the gradient-vector product.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The gradient-vector-product is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the gradient-vector-product in parallel (threaded).

Returns:

NumPy array containing the gradient-vector-product result.

Return type:

ndarray

Notes

The vector \(\delta x\) and the tensor-argument wrt must have equal or broadcast-compatible shapes. This means that the vector is not restricted to be a one-dimensional array but must be an array with compatible shape instead.

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>> F.shape
(3, 3, 8, 20)

>>> np.random.seed(63254)
>>> δF = np.random.rand(3, 3, 8, 20) / 10
>>> δF.shape
(3, 3, 8, 20)

>>> dW = tr.gradient_vector_product(fun, wrt=0, ntrax=2)(F, δx=δF)
>>> dW.shape
>>> (8, 20)
tensortrax.hessian_vector_product(fun, wrt=0, ntrax=0, parallel=False)[source]#

Evaluate the Hessian-vector-product of a scalar-valued function.

Parameters:

  • fun (callable) – The function to be evaluated. Its signature is extended to fun(*args, δx, **kwargs)(), where the added δx-argument is the vector of the Hessian-vector product.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The Hessian-vector-product is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the gradient-vector-product in parallel (threaded).

Returns:

NumPy array containing the Hessian-vector-product result.

Return type:

ndarray

Notes

The vector \(\delta x\) and the tensor-argument wrt must have equal or broadcast-compatible shapes. This means that the vector is not restricted to be a one-dimensional array but must be an array with compatible shape instead.

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>> F.shape
(3, 3, 8, 20)

>>> np.random.seed(63254)
>>> δF = np.random.rand(3, 3, 8, 20) / 10
>>> δF.shape
(3, 3, 8, 20)

>>> dP = tr.hessian_vector_product(fun, wrt=0, ntrax=2)(F, δx=δF)
>>> dP.shape
>>> (3, 3, 8, 20)
tensortrax.hessian_vectors_product(fun, wrt=0, ntrax=0, parallel=False)[source]#

Evaluate the vector-Hessian-vector- or Hessian-vectors-product of a scalar- valued function.

Parameters:

  • fun (callable) – The function to be evaluated. Its signature is extended to fun(*args, δx, Δx, **kwargs)(), where the added δx- and Δx- arguments are the vectors of the Hessian-vectors product.

  • wrt (int or str, optional) – The input argument which will be treated as Tensor (default is 0). The Hessian-vectors-product is carried out with respect to this argument.

  • ntrax (int, optional) – Number of elementwise-operating trailing axes (batch dimensions). Default is 0.

  • parallel (bool, optional) – Flag to evaluate the gradient-vector-product in parallel (threaded).

Returns:

NumPy array containing the Hessian-vectors-product result.

Return type:

ndarray

Notes

The vectors \(\delta x\) and \(\Delta x\) as well as the tensor-argument wrt must have equal or broadcast-compatible shapes. This means that the vectors are not restricted to be one-dimensional arrays but must be arrays with compatible shapes instead.

Examples

>>> import numpy as np
>>> import tensortrax as tr
>>> import tensortrax.math as tm
>>>
>>> def fun(F, mu=1):
>>>     C = F.T @ F
>>>     I1 = tm.trace(C)
>>>     J = tm.linalg.det(F)
>>>     return mu / 2 * (J ** (-2 / 3) * I1 - 3)
>>>
>>> np.random.seed(125161)
>>> F = (np.eye(3) + np.random.rand(20, 8, 3, 3) / 10).T
>>> F.shape
(3, 3, 8, 20)

>>> np.random.seed(63254)
>>> δF = np.random.rand(3, 3, 8, 20) / 10
>>> δF.shape
(3, 3, 8, 20)

>>> np.random.seed(85476)
>>> ΔF = np.random.rand(3, 3, 8, 20) / 10
>>> ΔF.shape
(3, 3, 8, 20)

>>> ΔδW = tr.hessian_vectors_product(fun, wrt=0, ntrax=2)(F, δx=δF, Δx=ΔF)
>>> ΔδW.shape
>>> (8, 20)