Legacy Nonlinear Assembly API

Dedicated total-Lagrangian assembly, stress and follower-load routines retained for compatibility. Modern constitutive response and tensor conversion and DSL nonlinear formulations are documented separately.

Kinematics and Constitutive Terms

LowLevelFEM.nodePositionVector — Function
nodePositionVector(problem)

Returns the position vectors of all mesh nodes as a VectorField (initial configuration). Returning vector is always a 3D vector.

Returns: R

Types:

  • problem: Problem
  • R: VectorField
source
LowLevelFEM.materialTangentMatrix — Function
materialTangentMatrix(problem::Problem; 
                      F::TensorField, 
                      C::Union{AbstractMatrix,Nothing}=nothing, 
                      energy::Union{Nothing,Function}=nothing, 
                      params=nothing)

Assembles the material (constitutive) tangent stiffness matrix for a 3D solid under finite deformation (Total Lagrange formulation), using a user-provided deformation gradient field F and a material tangent matrix C given in 6×6 engineering Voigt form. Alternatively, it can compute the material tangent from a free-energy density energy (hyperelastic formulation) via Tensors.jl.

This function builds the matrix


K_mat = ∫_Ω B(F)ᵀ · C · B(F) dΩ

where B(F) is the nonlinear strain–displacement matrix associated with the Green–Lagrange strain, and C is the material tangent ∂S/∂E expressed in engineering Voigt notation, ordered [xx, yy, zz, xy, yz, zx].

The routine is material-agnostic: it does not assume any specific constitutive law. The material behavior is entirely defined by the supplied C, which may be spatially varying.


Arguments

  • problem::Problem The finite element problem definition. Must satisfy:
    • problem.dim == 3
    • problem.pdim == 3

Keyword arguments

  • F::TensorField Nodal deformation gradient field. Each node stores the full 3×3 deformation gradient F, which is interpolated to Gauss points during integration.

  • C::AbstractMatrix (size 6×6) Material tangent matrix in engineering Voigt order [xx, yy, zz, xy, yz, zx].

    Each entry C[i,j] may be either:

    • a Number (constant material tangent), or
    • a ScalarField (spatially varying material tangent component).

    All entries must satisfy:


C[i,j] isa Number || C[i,j] isa ScalarField
  • energy::Function Free-energy density ψ(C, params) of a hyperelastic material, evaluated at the right Cauchy–Green tensor C = FᵀF. If provided, the tangent is computed at Gauss points via Tensors.jl and C must be omitted.

  • params Optional parameter container passed through to energy.


Mathematical formulation

  • Strain measure: Green–Lagrange strain

E = 1/2 (FᵀF − I)
  • Variation:

δE = sym(Fᵀ δF)
  • Tangent contribution:

δS = C : δE
  • Element stiffness contribution:

K_e = ∫ B(F)ᵀ · C · B(F) dΩ

The strain–displacement matrix B(F) uses engineering Green strain: [E11, E22, E33, 2E12, 2E23, 2E31]. This is not Mandel scaling. The supplied C uses [xx, yy, zz, xy, yz, zx] on both axes, matching energyMaterial and the DSL. Older versions used [xx, yy, zz, yz, xz, xy]; convert a manually supplied old-order matrix with p=[1,2,3,6,4,5]; C=C[p,p].


Notes

  • This function assembles only the material part of the tangent

stiffness matrix. The geometric stiffness (stress-dependent part) must be assembled separately.

  • The formulation is suitable for:
  • hyperelastic materials,
  • finite rotations,
  • finite strains,

provided that C is consistent with the stress measure used elsewhere.

  • If energy is supplied, the routine constructs C = FᵀF at Gauss points and obtains the constitutive tangent from the free-energy function using Tensors.jl. This enables arbitrary hyperelastic laws without providing a closed-form C.

  • The material tangent C is evaluated at Gauss points by interpolating

nodal ScalarField values when necessary.


Returns

  • SystemMatrix

Sparse global material tangent stiffness matrix of size (ndof × ndof).


Typical usage

Kmat = materialTangentMatrix(
  problem;
  F = Ffield,
  C = Cvoigt   # 6×6 matrix of Number / ScalarField
)

K = Kint + Kmat

See also

  • initialStressMatrix

  • internalForceVector

  • externalTangentFollower

  • TensorField

  • ScalarField

source
LowLevelFEM.initialStressMatrix — Function
initialStressMatrix(problem::Problem; 
                    S::Union{TensorField,Nothing}=nothing, 
                    energy::Union{Nothing,Function}=nothing, 
                    C::Union{Nothing,TensorField}=nothing,
                    params=nothing)

Assembles the geometric (initial stress) stiffness matrix associated with a given stress field, for finite deformation analysis in a Total Lagrange–type formulation.

The function computes the matrix


K_geo = ∫_Ω G(S) dΩ

where G(S) represents the geometric stiffness contribution induced by the supplied stress tensor field stress. The stress measure itself (P, S, or σ) is not interpreted by the routine; it is treated purely as a second-order tensor field whose contraction with displacement gradients yields the geometric stiffness.


Arguments

  • problem::Problem Finite element problem definition. Must satisfy:
    • problem.dim == problem.pdim

Keyword arguments

  • S::TensorField Nodal stress tensor field.

    Each node stores a full dim×dim tensor, which is interpolated to Gauss points using standard Lagrange shape functions. The physical meaning of the tensor is left to the caller; typical choices include:

    • First Piola–Kirchhoff stress P,
    • Second Piola–Kirchhoff stress S,
    • Cauchy stress σ,

    provided that the chosen stress measure is consistent with the kinematic description used elsewhere in the formulation.

  • energy::Function Free-energy density ψ(C, params) of a hyperelastic material. If provided, the stress field is computed at Gauss points via Tensors.jl from the supplied C and stress must be omitted.

  • C::TensorField Nodal field of the right Cauchy–Green tensor C = FᵀF. Required when using the energy-based path.

  • params Optional parameter container passed through to energy.


Mathematical formulation

At each Gauss point, the stress tensor S_gp is obtained by interpolation from nodal values. The geometric stiffness contribution is computed as


g_ab = (∇N_a)ᵀ · S_gp · (∇N_b)

and distributed to the displacement components as


(K_geo)_ai,bi = g_ab

with no coupling between different displacement directions (i = i only).

The element contribution reads


K_e = ∫ (∇N)ᵀ · S · (∇N) dΩ

and is assembled into the global matrix.


Notes

  • This function assembles only the geometric (stress-dependent) part of the tangent stiffness matrix. The material (constitutive) tangent must be assembled separately, e.g. via materialTangentMatrix.

  • The routine is stress-measure agnostic: it does not enforce symmetry or specific push-forward/pull-back operations. Ensuring energetic and kinematic consistency between the stress field and the rest of the formulation is the responsibility of the caller.

  • If energy is supplied, C is interpolated to Gauss points and the stress is obtained from the free-energy function using Tensors.jl. This enables arbitrary hyperelastic laws without explicitly providing a stress field.

  • The formulation corresponds to the classical initial stress stiffness encountered in large-deformation and stability (buckling) analyses.


Returns

  • SystemMatrix Sparse global geometric stiffness matrix of size (ndof × ndof).

Typical usage

Kgeo = initialStressMatrix(
    problem;
    stress = Sfield   # TensorField (P, S, or σ)
)

K = Kmat + Kgeo

See also

  • materialTangentMatrix
  • internalForceVector
  • TensorField
source
LowLevelFEM.IIPiolaKirchhoffStress — Function
IIPiolaKirchhoffStress(energy, C::TensorField, params)

Computes the nodal Second Piola–Kirchhoff (II PK) stress tensor field from a given nodal Right Cauchy–Green deformation tensor field.

For each time step and each node, the II PK stress is evaluated as

S = ∂ψ(C, params) / ∂C

using the provided free energy function energy and material parameters params. The stress evaluation is performed directly at the nodal values of C, without Gauss-point integration or spatial averaging.

This function is intended for post-processing, visualization, and diagnostic purposes. The resulting stress field is energy-consistent with the constitutive model but is not suitable for assembling internal forces or tangents, which require Gauss-point evaluation.

Arguments:

  • energy::Function: Free energy density ψ(C, params).
  • C::TensorField: Nodal Right Cauchy–Green deformation tensor field.
  • params::NamedTuple: Material parameters passed to energy.

Requirements:

  • The problem must be three-dimensional (dim = pdim = 3).
  • The input field C must be defined nodally.

Returns:

  • TensorField: Nodal Second Piola–Kirchhoff stress field with the same time steps and model as C.

Notes:

  • The stress is computed independently at each node and time step.
  • No interpolation, integration, or smoothing is performed.
  • For use in weak forms or Newton iterations, Gauss-point evaluation should be used instead.
source

Nonlinear Assembly

LowLevelFEM.externalTangentFollower — Function
externalTangentFollower(
    problem::Problem,
    loads::Vector{LoadCondition};
    F::TensorField
)

Assembles the external tangent stiffness matrix associated with follower (configuration-dependent) surface loads for a finite deformation analysis.

The function computes the linearization of the external force vector with respect to the displacement field when the applied tractions rotate and/or stretch together with the deforming body.


Arguments

  • problem::Problem Finite element problem definition.

  • loads::Vector{LoadCondition} Boundary conditions defining surface tractions or pressures acting on the current configuration. Supported load types:

    • surface traction components (fx, fy, fz),
    • surface pressure (p, only for 3D solids).

    Each boundary condition is interpreted as a follower load, i.e. its direction and/or magnitude may depend on the deformation.


Keyword arguments

  • F::TensorField Nodal deformation gradient field. Each node stores the full deformation gradient F, which is interpolated to Gauss points and used to:
    • rotate the applied tractions,
    • compute the Jacobian and inverse deformation gradient,
    • form the consistent external tangent matrix.

Mathematical formulation

The external force vector for follower tractions may be written as


f_ext = ∫_Γ Nᵀ · t(F) dΓ

where the traction vector depends on the deformation gradient, typically through a relation of the form


t = J F⁻ᵀ t₀    or    t = F · t_loc

The present implementation linearizes this expression consistently, leading to an external tangent contribution


K_ext = ∂f_ext / ∂u

which includes:

  • the variation of the Jacobian and inverse deformation gradient,
  • the variation of the traction due to rotation/stretching with F.

Both pressure loads and vector-valued surface tractions are supported.


Notes

  • This function assembles only the tangent contribution of follower loads. The corresponding external force vector must be assembled separately, e.g. using loadVector with deformation-dependent tractions.

  • Dead loads (loads fixed in the reference configuration) must not be passed to this function. For dead loads, the external tangent is identically zero.

  • The formulation assumes a Total Lagrange–type description and is intended for large-rotation and large-deformation problems.

  • For pressure loads, the reference normal vector is obtained from the undeformed geometry and appropriately transformed.


Returns

  • SystemMatrix Sparse global external tangent stiffness matrix of size (ndof × ndof).

Typical usage

Kext = externalTangentFollower(
    problem,
    loads;
    F = Ffield
)

K = Kmat + Kgeo - Kext

See also

  • loadVector
  • internalForceVector
  • materialTangentMatrix
  • initialStressVector
source
LowLevelFEM.internalForceVector — Function
internalForceVector(problem::Problem; 
                    P::Union{Nothing,TensorField}=nothing, 
                    F::Union{Nothing,TensorField}=nothing, 
                    energy::Union{Nothing,Function}=nothing, 
                    params=nothing)

Assembles the internal force vector associated with a given first-order stress tensor field P, using a finite deformation formulation. Alternatively, P can be computed from a free-energy density energy (hyperelastic formulation) via Tensors.jl.

The function computes


f_int = ∫_Ω B_Pᵀ · P dΩ

where P is interpolated to Gauss points and contracted with the gradients of the shape functions. The routine is stress-measure agnostic: it treats P purely as a second-order tensor field and does not enforce any specific constitutive interpretation.


Arguments

  • problem::Problem Finite element problem definition. The routine currently supports only:

problem.dim  == 3
problem.pdim == 3
  • P::TensorField

Nodal stress tensor field. Each node stores a full dim×dim tensor, which is interpolated to Gauss points using Lagrange shape functions.

Typical choices for P include:

  • First Piola–Kirchhoff stress,
  • Second Piola–Kirchhoff stress (with compatible kinematics),
  • Cauchy stress (if used consistently).

The function does not distinguish between these cases; ensuring consistency with the rest of the formulation is the responsibility of the caller.

  • F::TensorField Nodal deformation gradient field. Required when using the energy-based path to compute P internally.

  • energy::Function Free-energy density ψ(C, params) of a hyperelastic material. If provided, the routine constructs C = FᵀF, computes S via Tensors.jl, and forms P = F * S at Gauss points.

  • params Optional parameter container passed through to energy.


Mathematical formulation

At each Gauss point, the stress tensor is obtained as


P_gp = Σ_a N_a P_a

The element internal force contribution is computed as


(f_e)*{ai} = ∫ (P_gp)*{iJ} (∇N_a)_J dΩ

where:

  • a denotes the node index,
  • i denotes the displacement component,
  • ∇N_a is the gradient of the shape function in the reference configuration.

The resulting element vector is assembled into the global internal force vector.


Notes

  • This function assembles only the internal force vector. The associated tangent contributions must be assembled separately via:

    • materialTangentMatrix (constitutive tangent),
    • initialStressMatrix (geometric tangent).
  • The stress field P is interpolated using standard Lagrange shape functions. No symmetry or push-forward/pull-back operations are applied internally.

  • If energy is supplied, P is computed at Gauss points from the free-energy function using Tensors.jl, enabling arbitrary hyperelastic laws without explicitly providing a stress field.

  • The formulation corresponds to a Total Lagrange–type internal force expression when P is interpreted as the first Piola–Kirchhoff stress.


Returns

  • VectorField Global internal force vector of size (ndof), returned as a VectorField with one time step.

Typical usage

f_int = internalForceVector(problem, Pfield)

R = f_int - f_ext

See also

  • materialTangentMatrix
  • initialStressMatrix
  • externalTangentFollower
  • TensorField
source

Visualization

LowLevelFEM.showDeformationResults — Function
showDeformationResults(r::VectorField, 
                       comp::Symbol; 
                       name=comp, 
                       visible=false)

Shows deformation result, where r contains the position vectors of nodes in the current configuration.

source

Legacy derivative helpers

LowLevelFEM.∇_old — Function
∇_old(r::Union{VectorField, ScalarField, TensorField}; nabla=:grad)

Computes derivatives of r.

  • If r is a ScalarField and nabla == :grad, returns the gradient (a VectorField).
  • If r is a VectorField and nabla == :grad, returns the gradient (a TensorField).
  • If r is a VectorField and nabla == :curl, returns the curl (a VectorField).
  • If r is a VectorField and nabla == :div, returns the divergence (a ScalarField).
  • If r is a TensorField and nabla == :div, returns the divergence (a VectorField).

Returns: ScalarField, VectorField, or TensorField

Types:

  • r: ScalarField, VectorField, or TensorField
  • nabla: Symbol

3D Examples (assumes problem is set as in the ∇ doc setup)

# One-time 3D setup (assumes examples/Fields/cube.geo exists with physical group "body")
using LowLevelFEM
gmsh.initialize()
gmsh.open("examples/Fields/cube.geo")
mat = material("body", E=210e3, ν=0.3, ρ=7.85e-9)
problem = Problem([mat], type=:Solid)

# 1) Gradient of a 3D scalar field: ∇f → VectorField
f(X,Y,Z) = X^2 + Y*Z
S = scalarField(problem, [field("body", f=f)])
G = ∇(S)  # VectorField with 3 components

# 2) Curl of a 3D vector field: ∇ × v → VectorField
vx(X,Y,Z) = 0
vy(X,Y,Z) = X
vz(X,Y,Z) = 0
V = vectorField(problem, [field("body", fx=vx, fy=vy, fz=vz)])
C = ∇(V, nabla=:curl)  # approx (0, 0, 1) everywhere

# 3) Divergence of a 3D vector field: ∇ ⋅ v → ScalarField
v1(X,Y,Z) = X
v2(X,Y,Z) = Y
v3(X,Y,Z) = Z
V2 = vectorField(problem, [field("body", fx=v1, fy=v2, fz=v3)])
D = ∇(V2, nabla=:div)  # ≈ 3

# 4) Divergence of a 3D tensor field: ∇ · T → VectorField (if T is TensorField)
# For example, a diagonal tensor T with only Tzz = g(Z): div(T) = (0, 0, ∂g/∂Z)
g(Z) = 10 - Z
T = tensorField(problem, [field("body", fz=g)])
DV = ∇(T, nabla=:div)  # VectorField

# Symmetric displacement gradient via operators
# A = (u ∘ ∇ + ∇ ∘ u) / 2
gmsh.finalize()
source
LowLevelFEM.grad_xy — Function
grad_xy(rr::ScalarField) -> VectorField

Legacy derivative helper for an xy-planar mesh. Return the two in-plane components (∂r/∂x, ∂r/∂y) in element-wise storage (type=:v2D). Element-wise input is first projected to nodal values, which can smooth jumps. For new field calculus use ∇ or ∂x and ∂y.

source