Constitutive Models and Tensor Conversion

These utilities are shared by modern weak-form formulations, even though the energy-based implementations live in nonlinear.jl. The dedicated nonlinear assembly routines are legacy.

Isotropic linear elasticity

LowLevelFEM.ConstitutiveMatrix — Function
ConstitutiveMatrix(type::Symbol)
ConstitutiveMatrix(type::Symbol, mat::Material)
ConstitutiveMatrix(type::Symbol, E, ν)

Return the isotropic elastic constitutive matrix for the selected model.

Supported models:

  • :PlaneStress
  • :PlaneStrain
  • :Axisymmetric
  • :Solid

Engineering shear strain convention is used.

Alias

D is a shorthand alias for ConstitutiveMatrix and accepts the same arguments.

D(:Solid, mat)
D(:PlaneStress, E, ν)
source
LowLevelFEM.D — Function
D(args...)

Shorthand alias for ConstitutiveMatrix.

Accepts the same arguments and returns the same constitutive matrix.

Examples

D(:Solid, mat)
D(:PlaneStress, 210e3, 0.3)
source

The material-matrix selector is :Axisymmetric, while the predefined problem type is spelled :AxiSymmetric. The coefficient alone does not add the axisymmetric hoop strain or radial integration weight to a Cartesian DSL form.

Energy-based material response

Load Tensors explicitly for differentiation of an energy function ψ(C,p). C is the right Cauchy–Green tensor. Stress and tangent are material response fields; these functions do not run a nonlinear equilibrium iteration.

LowLevelFEM.energyMaterial — Function
energyMaterial(ψ, C::TensorField; params=NamedTuple())

Compute the constitutive response from a strain energy density function.

The function evaluates the second Piola–Kirchhoff stress tensor and the consistent material tangent matrix in a fully elementwise manner.

Arguments

  • ψ: strain energy density function of the form ψ(C,p)
  • C: right Cauchy–Green tensor field (TensorField)
  • params: named tuple containing material parameters

Material parameters may be:

  • Number
  • ScalarField

ScalarField parameters are internally converted to elementwise form if needed.

Returns

A named tuple:

(; S, D)

where:

  • S is an elementwise TensorField
  • D is a 6×6 matrix whose entries are elementwise ScalarFields

The tangent uses the same Voigt order as SymGrad and tensorToVector and can be used directly in DSL expressions.

Optional extension and conventions

Load Tensors before calling this energy-based interface. The energy function ψ(C, params) must support the tensor values and automatic differentiation provided by that extension. C is the right Cauchy–Green tensor, not a Voigt strain vector. Parameters are a named tuple of numbers or compatible ScalarFields; element/column support must match C (one-column parameters can be reused across columns). Nodal input is converted to element-wise data.

Notes

The tangent order is [xx, yy, zz, xy, yz, zx], shared with SymGrad and tensorToVector. It maps engineering Green-strain increments [δE_xx, δE_yy, δE_zz, 2δE_xy, 2δE_yz, 2δE_zx] to stress increments. No component permutation or additional shear scaling is needed before DSL use.

Earlier versions returned [xx, yy, zz, yz, xz, xy]. Remove any manual [1, 2, 3, 6, 4, 5] permutation when updating existing code. The stress field retains full column-major tensor storage.

This function computes stress and tangent simultaneously for efficiency.

source
LowLevelFEM.IIPiolaKirchhoff — Function
IIPiolaKirchhoff(ψ, C::TensorField; params=NamedTuple())

Compute the second Piola–Kirchhoff stress tensor from a strain energy density function.

Arguments

  • ψ: strain energy density function of the form ψ(C,p)
  • C: right Cauchy–Green tensor field (TensorField)
  • params: named tuple containing material parameters

Returns

An elementwise TensorField containing the second Piola–Kirchhoff stress.

Optional extension and conventions

Load Tensors before calling this energy-based interface. The energy function ψ(C, params) must support the tensor values and automatic differentiation provided by that extension. C is the right Cauchy–Green tensor, not a Voigt strain vector. Parameters are a named tuple of numbers or compatible ScalarFields; element/column support must match C (one-column parameters can be reused across columns). Nodal input is converted to element-wise data.

Notes

This function internally uses the same constitutive kernel as energyMaterial, but computes only the stress tensor.

source
LowLevelFEM.tangentMatrix — Function
tangentMatrix(ψ, C::TensorField; params=NamedTuple())

Compute the consistent material tangent matrix from a strain energy density function.

Arguments

  • ψ: strain energy density function of the form ψ(C,p)
  • C: right Cauchy–Green tensor field (TensorField)
  • params: named tuple containing material parameters

Returns

A 6×6 matrix whose entries are elementwise ScalarFields.

The tangent uses the same Voigt order as SymGrad and tensorToVector and can be used directly in DSL expressions.

Optional extension and conventions

Load Tensors before calling this energy-based interface. The energy function ψ(C, params) must support the tensor values and automatic differentiation provided by that extension. C is the right Cauchy–Green tensor, not a Voigt strain vector. Parameters are a named tuple of numbers or compatible ScalarFields; element/column support must match C (one-column parameters can be reused across columns). Nodal input is converted to element-wise data.

Notes

The tangent order is [xx, yy, zz, xy, yz, zx], shared with SymGrad and tensorToVector. It maps engineering Green-strain increments [δE_xx, δE_yy, δE_zz, 2δE_xy, 2δE_yz, 2δE_zx] to stress increments. No component permutation or additional shear scaling is needed before DSL use.

Earlier versions returned [xx, yy, zz, yz, xz, xy]. Remove any manual [1, 2, 3, 6, 4, 5] permutation when updating existing code. The stress field retains full column-major tensor storage.

This function internally uses the same constitutive kernel as energyMaterial, but computes only the tangent matrix.

source

Stress extraction, the energy-based tangent and SymGrad share the order [xx,yy,zz,xy,yz,zx]. The tangent maps engineering Green-strain increments to stress increments; use it directly without permutation or extra shear factors.

Earlier versions of the Tensors extension used `[xx,yy,zz,yz,xz,xy]`.
Remove the old manual permutation `p=[1,2,3,6,4,5]` from existing code;
applying it again now changes the material response.
`materialTangentMatrix` also accepts the shared order on both matrix axes.
For a manually supplied matrix stored in its old `[xx,yy,zz,yz,xz,xy]` order,
convert that matrix once with `p=[1,2,3,6,4,5]; C=C[p,p]`.

Tensor components

LowLevelFEM.tensorToMatrix — Function
tensorToMatrix(T::TensorField)

Convert a tensor field to a matrix of scalar fields.

Arguments

  • T: tensor field

Returns

A 3×3 matrix whose entries are ScalarFields corresponding to the tensor components.

Examples

M = tensorToMatrix(S)

The returned matrix can be used directly in DSL matrix-chain expressions.

source
LowLevelFEM.tensorToVector — Function
tensorToVector(T::TensorField)

Extract tensor entries in Voigt order. Symmetry is assumed by the physical interpretation, but is not checked or imposed. Shear components are copied without an engineering-strain factor of two.

Arguments

  • T: symmetric tensor field

Returns

A vector of ScalarFields in the ordering:

[xx, yy, zz, xy, yz, zx]

Examples

v = tensorToVector(S)
source

Voigt extraction does not impose symmetry or multiply shear entries by two. Use constitutive and kinematic conventions consistently, especially for anisotropic materials.