jaxmat.tensors.linear_algebra module

dim(A)

Dimension dim of a n-rank matrix \(\bA\), assuming shape=(dim, dim, ..., dim).

tr(A)

Trace of a matrix \(\bA\).

\[\tr(\bA)=A_{ii}\]

dev(A)

Deviatoric part of a \(d\times d\) matrix \(\bA\).

\[\dev(\bA) = \bA - \dfrac{1}{d}\bI\]

det33(A)

Determinant \(\det(\bA)\) of a 3x3 matrix \(\bA\), computed using explicit formula.

inv33(A)

Inverse \(\bA^{-1}\) of a 3x3 matrix \(\bA\), explicitly computed using cofactor formula.

principal_invariants(A)

Principal invariants of a 3x3 matrix \(\bA\).

\[\begin{split}\begin{align*} I_1 &= \tr(\bA)\\ I_2 &= \frac{1}{2}(\tr(\bA)^2-\tr(\bA^2))\\ I_3 &= \det(\bA) \end{align*}\end{split}\]

main_invariants(A)

Main invariants of a 3x3 matrix \(\bA\):

\[\tr(\bA),\: \tr(\bA^2),\: \tr(\bA^3)\]

.

pq_invariants(sig)

Hydrostatic/deviatoric equivalent stresses \((p,q)\). Typically used in soil mechanics.

\[p = - \tr(\bsig)/3 = -I_1/3\]

\[q = \sqrt{\frac{3}{2}\bs:\bs} = \sqrt{3 J_2}\]

eig33(A, rtol=1e-16)

Computes the eigenvalues and eigenvalue derivatives of a 3 x 3 real symmetric matrix.

This function implements a numerically stable eigendecomposition for 3 x 3 symmetric matrices based on the method by Harari & Albocher (2023)

The implementation avoids catastrophic cancellation and loss of precision in cases where two or more eigenvalues are nearly equal.

Parameters:

• A (array_like of shape (3, 3)) – Real symmetric matrix whose eigenvalues (and optionally eigenvalue dyads) are to be computed.

• rtol (float, optional) – Relative tolerance used to determine near-isotropic or nearly repeated eigenvalue cases. Default is 1e-16.

Returns:

• eigvals (jax.Array of shape (3,)) – Eigenvalues of ``A`, ordered in a consistent but unspecified order.

• eigendyads (jax.Array of shape (3, 3, 3)) – Derivatives of the eigenvalues with respect to the components of ``A`, obtained via forward-mode automatic differentiation (jax.jacfwd).

Notes

• The method distinguishes three cases:

  1. Near-isotropic case (s < rtol * ||A||): all eigenvalues are nearly equal.

  2. Two nearly equal eigenvalues: handled by a special branch to ensure stability.

  3. Three distinct eigenvalues: computed via trigonometric relations.

• The implementation uses safe_norm and safe_sqrt for numerical safety.

• Input A must be symmetric; asymmetry may lead to inaccurate results.

References

Harari, I., & Albocher, U. (2023). Computation of eigenvalues of a real, symmetric 3 x 3 matrix with particular reference to the pernicious case of two nearly equal eigenvalues. International Journal for Numerical Methods in Engineering, 124(5), 1089-1110.

sqrtm(A)

Matrix square-root \(\bA^{1/2}\) of a symmetric 3x3 matrix \(\bA\). Computed using the unified square root and inverse square root formula, see Simo & Hughes, 1998.

References

Simo, J. C., & Hughes, T. J. (1998). Computational inelasticity., p.244

inv_sqrtm(A)

Matrix inverse square-root \(\bA^{-1/2}\) of a symmetric 3x3 matrix \(\bA\).

Computed using the unified square root and inverse square root formula, see Simo & Hughes, 1998.

References

Simo, J. C., & Hughes, T. J. (1998). Computational inelasticity., p.244

isotropic_function(fun, A)

Computes an isotropic function of a symmetric 3x3 matrix \(\bA\).

Parameters:

• fun (callable) – A scalar function \(f(x)\)

• A (jax.Array) – A symmetric 3x3 matrix

Returns:

A new 3x3 matrix \(f_{\bA}\) such that

\[f_{\bA} = \sum_{i=1}^3 f(\lambda_i) \bn_i \otimes \bn_i\]

where \(\lambda_i\) and \(\bn_i\) are the eigenvalues and eigenvectors of \(\bA\).

Return type:

jax.Array

expm(A)

Matrix exponential \(\exp(\bA)\) of a symmetric 3x3 matrix \(\bA\).

logm(A)

Matrix logarithm \(\log(\bA)\) of a symmetric 3x3 matrix \(\bA\).

powm(A, m)

Matrix power \(\bA^m\) of exponent \(m\) of a symmetric 3x3 matrix \(\bA\).