jaxmat.tensors.symmetry_classes module

jaxmat.tensors.symmetry_classes module#

jaxmat/tensors/symmetry_classes.py

Symmetry-reduced fourth-rank tensor classes for solid mechanics.

Each class stores only its coefficient vector (the unique JAX leaf). No materialised (6,6) Kelvin matrix is stored as a leaf.

All shared behaviour lives in AbstractStructuredTensor4:

  • array property via tensordot with the precomputed basis stack

  • to_symmetric(), fourth_contract(), rotate() (materialise fallback)

  • All scalar arithmetic via _rebuild()

  • Binary + / -: same-type stays same-type, cross-type materialises

  • @ default: (6,6) @ (6,) on the materialised Kelvin matrix

  • __rmatmul__ fallback

Each subclass provides only:

  • __init__ (parameter parsing and _basis_arrays assignment)

  • _rebuild() — factory for a new same-type instance with updated coefficients

  • inv — class-specific inversion

  • __matmul__ override for same-class composition (coefficient-space algebra)

  • project() classmethod

Projector algebra#

Every \(G\)-invariant fourth-rank tensor decomposes as $\mathbb{C} = \sum_\alpha c_\alpha \mathbb{P}_\alpha$ where the \(\mathbb{P}_\alpha\) are fixed orthogonal (or block-orthogonal) projectors determined by the symmetry group \(G\).

Symmetry class

Coeffs

Projectors

Composition rule

Isotropic

2

J, K

elementwise (orthogonal)

Cubic

3

J, Kₐ, K_b

elementwise (orthogonal)

Transverse isotropic

6

Walpole

2x2 block + scalar pairs
class AbstractStructuredTensor4[source]#

Bases: Module

Abstract base for symmetry-reduced fourth-rank tensors.

Concrete subclasses store a coefficient vector _coeffs of shape (..., n) (the unique JAX leaf) and a precomputed basis stack _basis_arrays of shape (n, 6, 6) (static). Every shared operation is derived from these two objects alone.

The tensor is represented as

\[\mathbb{C} = \sum_{\alpha=1}^n c_\alpha \mathbb{P}_\alpha\]

where \(\mathbb{P}_\alpha\) are the basis projectors (stored in _basis_arrays) and \(c_\alpha\) are the coefficients (stored in _coeffs).

Subclasses must implement#

_rebuild()

Factory: return a new instance of the same class from updated coefficients.

inv

Class-specific inversion (coefficient-wise or block-matrix).

property inv: AbstractStructuredTensor4#

Inverse of the tensor operator.

Returns:

The inverse \(\mathbb{C}^{-1}\) within the same symmetry class.

Return type:

AbstractStructuredTensor4

property coeffs: Array#

Expansion coefficients \(c_\alpha\) in the symmetry projector basis.

Returns:

Shape (..., n).

Return type:

jax.Array

property array: Array#

Materialised \((6, 6)\) Kelvin matrix.

Computed as $sum_alpha c_alpha {P_alpha}$ via a single tensordot with the precomputed basis stack. Supports arbitrary batch dimensions in _coeffs.

Returns:

Shape (..., 6, 6).

Return type:

jax.Array

to_symmetric()[source]#

Materialise to a general SymmetricTensor4.

Returns:

The same tensor stored as a full \((6, 6)\) Kelvin matrix.

Return type:

SymmetricTensor4

fourth_contract(other)[source]#

Full fourth-order contraction \(\mathbb{C}::\mathbb{D} = C_{ijkl}D_{ijkl}\).

Computed analytically as $sum_alpha c_\alpha (\mathbb{P}_\alpha :: \mathbb{D})\( without materialising the full \)(6,6)$ matrix.

Parameters:

other (SymmetricTensor4 or array_like, shape (..., 6, 6)) – Second operand \(\mathbb{D}\).

Returns:

Scalar (or batch of scalars).

Return type:

jax.Array

rotate(R)[source]#

Rotate the tensor by an orthogonal matrix \(\mathbf{R}\).

The default implementation materialises to SymmetricTensor4 and applies the rotation there. Subclasses may override this when the class is closed under rotation (e.g. isotropic tensors).

Parameters:

R (array_like, shape (3, 3)) – Orthogonal rotation matrix.

Return type:

SymmetricTensor4

isotropic_projectors()#

Construct isotropic fourth-rank projectors.

Returns:

  • J (SymmetricTensor4) – Volumetric projector \(\mathbb{J}_{ijkl} = \frac{1}{3}\delta_{ij}\delta_{kl}\).

  • K (SymmetricTensor4) – Deviatoric projector \(\mathbb{K} = \mathbb{I}^s - \mathbb{J}\).

Notes

The projectors satisfy \(\mathbb{J}:\mathbb{J}=\mathbb{J}\), \(\mathbb{K}:\mathbb{K}=\mathbb{K}\), \(\mathbb{J}:\mathbb{K}=0\), and \(\mathbb{J}+\mathbb{K}=\mathbb{I}^s\).

cubic_projectors()#

Construct cubic-symmetry fourth-rank projectors.

Returns:

  • J (SymmetricTensor4) – Volumetric projector.

  • Ka (SymmetricTensor4) – Diagonal deviatoric projector (cubic anisotropic part of the diagonal).

  • Kb (SymmetricTensor4) – Off-diagonal shear projector.

Notes

The three projectors are mutually orthogonal and partition the identity: \(\mathbb{J}+\mathbb{K}_a+\mathbb{K}_b = \mathbb{I}^s\).

transverse_isotropic_projectors(axis)#

Construct transverse-isotropic (Walpole) fourth-rank projectors.

Parameters:

axis (array_like, shape (3,)) – Unit symmetry axis \(\hat{\mathbf{a}}\).

Returns:

E1, E2, E3, E4, F, G – Six Walpole basis tensors spanning the transverse-isotropic subspace. E1 and E2 are projectors; E3, E4 are their cross terms; F and G are the remaining orthogonal complements.

Return type:

SymmetricTensor4

Notes

The Walpole basis is not orthogonal in the usual sense: composition follows a \(2\times 2\) block rule for E1..E4 and scalar inversion for F and G. See TransverseIsotropicTensor4 for the inversion formula.

Contents