jaxmat.tensors.tensor_utils module

jaxmat.tensors.tensor_utils module#

jaxmat/tensors/tensor_utils.py

Functional utilities for second-rank tensor algebra.

All functions here either return Tensor2 / SymmetricTensor2 objects, or require tensor-specific knowledge (e.g. the Kelvin dot product in norm(), the custom JVP in eigenvalues()).

Array-level operations — including isotropic matrix functions (expm(), logm(), etc.) — live in jaxmat.tensors.linear_algebra and accept tensor objects directly via __jax_array__, so no explicit wrapping is needed.

sym(A)[source]#

Symmetric part \((\mathbf{A} + \mathbf{A}^{\mathsf{T}}) / 2\).

Parameters:

A (Tensor2)

Return type:

SymmetricTensor2

skw(A)[source]#

Skew-symmetric part \((\mathbf{A} - \mathbf{A}^{\mathsf{T}}) / 2\).

Parameters:

A (Tensor2)

Return type:

Tensor2

vol(A)[source]#

Volumetric (spherical) part \(\tfrac{1}{3}\operatorname{tr}(\mathbf{A})\,\mathbf{I}\).

Complement of dev(): vol(A) + dev(A) == A for symmetric A.

Parameters:

A (Tensor2 or SymmetricTensor2)

Return type:

SymmetricTensor2

dev(A)[source]#

Deviatoric part \(\mathbf{A} - \tfrac{1}{3}\operatorname{tr}(\mathbf{A})\,\mathbf{I}\).

Parameters:

A (Tensor2 or SymmetricTensor2)

Return type:

SymmetricTensor2

tr(A)[source]#

Trace \(\operatorname{tr}(\mathbf{A}) = A_{ii}\).

Parameters:

A (Tensor2)

Returns:

Scalar (or batch of scalars).

Return type:

jax.Array

norm(A)[source]#

Frobenius norm \(\|\mathbf{A}\| = \sqrt{\mathbf{A}:\mathbf{A}}\).

For SymmetricTensor2 operands the double contraction is evaluated as a Kelvin dot product with no dense intermediate.

Parameters:

A (Tensor2 or SymmetricTensor2)

Returns:

Scalar (or batch of scalars).

Return type:

jax.Array

von_mises(sig)[source]#

Von Mises equivalent stress.

\[\sigma_\text{VM} = \sqrt{\tfrac{3}{2}\,\mathbf{s}:\mathbf{s}}, \qquad \mathbf{s} = \operatorname{dev}(\boldsymbol{\sigma})\]
Parameters:

sig (Tensor2 or SymmetricTensor2) – Cauchy stress tensor.

Returns:

Scalar (or batch of scalars).

Return type:

jax.Array

axl(A)[source]#

Axial vector of a skew-symmetric tensor.

The axial vector \(\mathbf{w}\) associated with \(\mathbf{W} = \operatorname{skw}(\mathbf{A})\) satisfies \(\mathbf{W}\mathbf{v} = \mathbf{w} \times \mathbf{v}\) and is given by \(w_i = -\tfrac{1}{2}\,\varepsilon_{ijk}\,W_{jk}\).

Parameters:

A (Tensor2)

Returns:

Shape (..., 3).

Return type:

jax.Array

polar(F, mode='RU')[source]#

Polar decomposition \(\mathbf{F} = \mathbf{R}\mathbf{U}\) or \(\mathbf{F} = \mathbf{V}\mathbf{R}\).

Parameters:

  • F (Tensor2) – Deformation gradient.

  • mode ({"RU", "VR"}, optional) – Selects the right polar decomposition ("RU", default) or the left polar decomposition ("VR").

Returns:

(R, U) for mode="RU" where R is a Tensor2 (rotation) and U a SymmetricTensor2 (right stretch), or (V, R) for mode="VR" where V is a SymmetricTensor2 (left stretch).

Return type:

tuple

stretch_tensor(F)[source]#

Right stretch tensor \(\mathbf{U} = (\mathbf{F}^{\mathsf{T}}\mathbf{F})^{1/2}\).

Convenience wrapper around polar().

Parameters:

F (Tensor2) – Deformation gradient.

Return type:

SymmetricTensor2

Contents