_images/logo.png

Differentiable Tensors based on NumPy Arrays.#

Documentation#

Highlights

  • Write differentiable code with Tensors based on NumPy arrays

  • Forward Mode Automatic Differentiation (AD) using Hyper-Dual Tensors, up to second order derivatives

  • Efficient evaluation of batches by elementwise-operating trailing axes

  • Essential vector/tensor Hyper-Dual number math, including limited support for einsum (restricted to max. three operands)

  • Math is limited but similar to NumPy, try to use import tensortrax.math as tm instead of import numpy as np inside functions to be differentiated

  • Create functions in terms of Hyper-Dual Tensors

  • Evaluate the function, the gradient (jacobian) and the hessian of scalar-valued functions or functionals on given input arrays

  • Straight-forward definition of custom functions in variational-calculus notation

  • Stable gradient and hessian of eigenvalues obtained from eigvalsh in case of repeated equal eigenvalues

Motivation#

Gradient and hessian evaluations of functions or functionals based on tensor-valued input arguments are a fundamental repetitive and (error-prone) task in constitutive hyperelastic material formulations used in continuum mechanics of solid bodies. In the worst case, conceptual ideas are impossible to pursue because the required tensorial derivatives are not readily achievable. The Hyper-Dual number approach enables a generalized and systematic way to overcome this deficiency [2]. Compared to existing Hyper-Dual Number libaries ([3], [4]) which introduce a new (hyper-) dual dtype (treated as dtype=object in NumPy), tensortrax relies on its own Tensor class. This approach involves a re-definition of all essential math operations (and NumPy-functions), whereas the dtype-approach supports most basic math operations out of the box. However, in tensortrax, NumPy and all its underlying linear algebra functions operate on default data types (e.g. dtype=float). This allows to support functions like np.einsum(). Beside the differences concerning the underlying dtype, tensortrax is formulated on easy-to-understand (tensorial) calculus of variation. Hence, gradient- and hessian-vector products are evaluated with very little overhead compared to analytic formulations.

Important

Please keep in mind that tensortrax is not imitating a 100% full-featured NumPy, e.g. like HIPS/autograd [1]. No arbitrary-order gradients or gradients-of-gradients are supported. The capability is limited to first- and second order gradients of a given function. Also, tensortrax provides no support for dtype=complex and out-keywords are not supported.

Installation#

Install tensortrax from PyPI, the Python Package Index.

pip install tensortrax[all]

tensortrax has minimal requirements, all available at PyPI.

Dependencies#

Package

Usage

numpy

for array operations

joblib

for threaded function, gradient, hessian and jacobian evaluations

To install optional dependencies as well, add [all] to the install command: pip install tensortrax[all].

Optional Dependencies#

Package

Usage

scipy

for extended math-support

Contents:

License#

tensortrax - Math on (Hyper-Dual) Tensors with Trailing Axes (C) 2022-2024 Andreas Dutzler, Graz (Austria).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

References#

Indices and tables#