Nonlinear API

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

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 Mandel/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 Mandel notation.

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 Mandel/Voigt notation.

  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) is constructed consistently with Mandel notation (shear components scaled by 2).

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

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

IIPiolaKirchhoff(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.

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

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

showDeformationResults(r::VectorField, 
                       comp::Symbol; 
                       name=comp, 
                       visible=false)

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