Engineering Linear Mechanics API

Problem-oriented assembly and solution functions for the engineering workflow. Names such as stiffnessMatrix and solveDisplacement are intended to remain while their current dedicated kernels are migrated to DSL-backed wrappers. The current implementation is not yet uniformly DSL-based. For custom forms, use weak-form assembly and solveField directly. See API layers and legacy implementations.

Assembly

LowLevelFEM.stiffnessMatrix — Function
stiffnessMatrix(problem; elements=[], forceOneThread=true) -> SystemMatrix

Assemble elastic stiffness through the engineering API for a solid, plane, axisymmetric or truss problem. elements=[] uses the material-group elements; a nonempty list restricts the element tags assembled by the selected kernel.

forceOneThread=true keeps the solid path serial. With it disabled, multiple Julia threads and at least 50,000 mesh nodes are required for that legacy parallel dispatch. Axisymmetric and truss paths select their own kernels. The engineering entry point is intended to remain as its current dedicated kernels migrate to DSL-backed wrappers. For a direct weak-form formulation, use SymGrad, D and ∫.

source
LowLevelFEM.nonLinearStiffnessMatrix — Function
nonLinearStiffnessMatrix(q::VectorField)

Solves the nonlinear stiffness matrix of the problem. q is a displacement field.

Returns: stiffMat

Types:

  • problem: Problem
  • q: VectorField
  • stiffMat: SystemMatrix

Element selection

elements=[] assembles the material-group elements. A nonempty list restricts the element tags included by the legacy assembly kernel. For a new DSL model, select a physical group through Ω or Γ in ∫.

source
LowLevelFEM.massMatrix — Function
massMatrix(problem; lumped=true)

Solves the mass matrix of the problem. If lumped is true, computes the lumped mass matrix.

Returns: massMat

Types:

  • problem: Problem
  • lumped: Boolean
  • massMat: SystemMatrix

Examples

M = massMatrix(problem; lumped=true)
source
LowLevelFEM.dampingMatrix — Function
dampingMatrix(K::SystemMatrix, M::SystemMatrix, ωₘₐₓ::Float64; 
              α=0.0, ξ=0.01, β=[2ξ[i]/(ωₘₐₓ)^(2i-1) for i in 1:length(ξ)])

Generates the damping matrix for proportional damping. C = αM + βK, or C = αM + β₁K + β₂KM⁻¹K + β₃KM⁻¹KM⁻¹K + ⋯. The latter corresponds to a damping characteristic given by a power series in the natural frequencies with odd exponents. ξᵢ (ξ in the arguments) are the values of the individual terms of the series at ωₘₐₓ. βᵢ (β in the arguments) are the coefficients of the series. Either ξ or β must be specified; each may be a scalar or a vector. K is the stiffness matrix, M is the mass matrix, and ωₘₐₓ is the largest natural frequency.

Returns: dampingMatrix

Types:

  • K: SystemMatrix
  • M: SystemMatrix
  • ωₘₐₓ: Float64
  • α: Float64
  • ξ: Float64 or Vector{Float64}
  • β: Float64 or Vector{Float64}
  • dampingMatrix: SystemMatrix

Examples

K = stiffnessMatrix(problem)
M = massMatrix(problem; lumped=true)
ωmax = 2π * 1000
C = dampingMatrix(K, M, ωmax; α=0.0, ξ=[0.02, 0.02])
source
LowLevelFEM.elasticSupportMatrix — Function
elasticSupportMatrix(problem, elSupports)

Solves the elastic support matrix of the problem. elSupp is a vector of elastic supports defined in function elasticSupport. With the displacementent vector q in hand the reaction force vector fR arising from the elastic support can be solved. (fR = heatConvMat * q)

Return: elSuppMat

Types:

  • problem: Problem
  • elSupp: Vector{BoundaryCondition}
  • elSuppMat: SystemMatrix
source
LowLevelFEM.loadVector — Function
loadVector(problem, loads; F=nothing)

Assembles the right-hand-side vector associated with external mechanical loads in weak-form finite element problems.

Depending on the problem dimension and the dimension of the physical group, this function handles concentrated forces, line/surface/volume loads, tractions, pressures, and body forces in 1D, 2D, and 3D.

The interpretation of the physical group dimension is:

  • 1D problems:
    • Point → concentrated force
    • Line → distributed force
  • 2D problems:
    • Point → concentrated force
    • Line → surface force
    • Surface → body force
  • 3D problems:
    • Point → concentrated force
    • Line → edge force
    • Surface → surface force
    • Volume → body force

Load components may be specified as constants, spatial functions, or ScalarFields (nodal type). Axisymmetric and other weighted formulations can be handled by including the appropriate geometric factor (e.g. 2πr) in the load definition or coefficient.

Returns a VectorField for vector-valued problems (pdim > 1) and a ScalarField for scalar problems (pdim == 1).

If F is the deformation gradient (a TensorField), then the function solves the follower load for large displacement problems (in 3D).

Return: loadVec

Types:

  • problem: Problem
  • loads: Vector{BoundaryCondition}
  • loadVec: VectorField
  • F: Union{Nothing,TensorField}
source
LowLevelFEM.sourceVector — Function
sourceVector(problem, sources)

Assembles the right-hand-side vector corresponding to a volumetric source term in Poisson-type and other scalar or vector-valued PDEs expressed in weak form.

Mathematically, this function assembles

f_a = ∫_Ω N_a f dΩ

where the source term f may be given as a constant, a spatial function, or a ScalarField.

This function is an alias of loadVector and shares the same implementation. The difference is purely interpretational: sourceVector emphasizes the role of the right-hand side as a PDE source term rather than a mechanical load.

Axisymmetric or spherically symmetric problems can be handled by including the appropriate geometric weighting (e.g. 2πr, 4πr²) as a coefficient field.

In LowLevelFEM, right-hand-side vectors are assembled independently of the governing equation. The same numerical machinery can therefore represent mechanical loads, heat sources, or generic PDE source terms.

Returns a ScalarField or VectorField, depending on the problem field dimension.

source
LowLevelFEM.applyBoundaryConditions — Function
applyBoundaryConditions(problem::Problem, 
                        supports::Vector{BoundaryCondition}; 
                        steps::Int=1)

Create a ScalarField, VectorField or TensorField and applies the boundary conditions supports on it. Mesh details are in problem. supports is BoundaryCondition.

Returns: ScalarField, VectorField or TensorField

Types:

  • problem: Problem
  • supports: Vector{BoundaryCondition}
source
LowLevelFEM.applyBoundaryConditions! — Function
applyBoundaryConditions!(field::Union{ScalarField,VectorField,TensorField}, 
                         supports::Vector{BoundaryCondition})

Applies boundary conditions supports on a ScalarField, VectorField or TensorField field. Mesh details are in problem. supports is BoundaryCondition.

Returns: nothing

Types:

  • problem: Problem
  • field: ScalarField, VectorField or TensorField
  • supports: Vector{BoundaryCondition}
source
LowLevelFEM.applyElasticSupport! — Function
applyElasticSupport!(stiffMat::SystemMatrix, elastSupp)

Applies elastic support boundary conditions elastSupp on a stiffness matrix stiffMat. Mesh details are in problem. elastSupp is a tuple of name of physical group and prescribed kx, ky and kz stiffnesses.

Returns: nothing

Types:

  • stiffMat: SystemMatrix
  • elastSupp: Vector{BoundaryCondition}}
source

Static and Stress/Strain Solvers

LowLevelFEM.solveDisplacement — Function
solveDisplacement(K::SystemMatrix, f::VectorField; 
                  support::Vector{BoundaryCondition}=BoundaryCondition[], 
                  iterative=false, 
                  reltol::Real = sqrt(eps()), 
                  maxiter::Int = K.model.non * K.model.dim, 
                  preconditioner = Identity(), 
                  ordering=true)

Solves the linear system

K * u = f

for the displacement vector u, where K is a stiffness matrix and f is the load vector. Essential (Dirichlet) boundary conditions are imposed via the support argument.

This is a low-level solver operating directly on a preassembled [SystemMatrix] and load [VectorField]. It assumes that the stiffness matrix already includes all material contributions (and optional elastic supports).

If iterative = true, the reduced system is solved using the conjugate gradient method. Otherwise, a direct solver is used.

Arguments

  • K::SystemMatrix: Assembled stiffness matrix associated with a [Problem].
  • f::VectorField: Load vector.
  • support::Vector{BoundaryCondition} (keyword, optional): Essential boundary conditions (Dirichlet-type constraints). Default is an empty vector (no supports).
  • iterative::Bool (keyword): If true, uses the conjugate gradient method.
  • reltol::Real (keyword): Relative tolerance for the iterative solver.
  • maxiter::Int (keyword): Maximum number of iterations for the iterative solver.
  • preconditioner (keyword): Preconditioner object for iterative solution (e.g. from ilu or ichol).
  • ordering::Bool (keyword): If false, disables column reordering in the direct solver (lu(A, q=nothing)).

Returns

  • u::VectorField: Displacement vector satisfying the prescribed boundary conditions.

Notes

  • Only the unconstrained degrees of freedom are solved for; constrained values are imposed explicitly.
  • This function is primarily intended for internal or advanced use. Most users should prefer the high-level solveDisplacement(problem; ...) interface.
source
solveDisplacement(problem::Problem; 
                  load::Vector{LoadCondition}=LoadCondition[], 
                  support::Vector{BoundaryCondition}=BoundaryCondition[], 
                  elasticSupport::Vector{BoundaryCondition}=BoundaryCondition[], 
                  condensed=true, 
                  iterative=false, 
                  reltol::Real = sqrt(eps()), 
                  maxiter::Int = problem.non * problem.dim, 
                  preconditioner = Identity(), 
                  ordering=true)

Computes the displacement vector u for a given [Problem] subject to external loads, essential supports, and optional elastic supports.

The stiffness matrix is assembled internally. Depending on the value of condensed, either a reduced system (eliminating constrained degrees of freedom) or the full system with modified rows and columns is solved.

This is the high-level, user-facing displacement solver.

Arguments

  • problem::Problem: Finite element problem definition (geometry, materials, DOFs, etc.).
  • load::Vector{BoundaryCondition} (keyword, optional): Prescribed nodal loads.
  • support::Vector{BoundaryCondition} (keyword, optional): Essential (Dirichlet) boundary conditions.
  • elasticSupport::Vector{BoundaryCondition} (keyword, optional): Elastic (spring-type) supports contributing to the stiffness matrix.
  • condensed::Bool (keyword): If true, solves the reduced system using only free degrees of freedom. If false, modifies the full system matrix explicitly.
  • iterative::Bool (keyword): If true, uses the conjugate gradient method.
  • reltol::Real (keyword): Relative tolerance for the iterative solver.
  • maxiter::Int (keyword): Maximum number of iterations for the iterative solver.
  • preconditioner (keyword): Preconditioner object for iterative solution (e.g. from ilu or ichol).
  • ordering::Bool (keyword): If false, disables column reordering in the direct solver (lu(A, q=nothing)).

Returns

  • u::VectorField: Displacement vector defined on the problem degrees of freedom.

Notes

  • If problem.type == :dummy, the function returns nothing.
  • When condensed = true, constrained DOFs are eliminated algebraically.
  • When condensed = false, constrained rows and columns are modified explicitly.
  • This function internally calls the low-level solveDisplacement(K, f; ...) routine after assembling the stiffness matrix and load vector.
source
LowLevelFEM.solveStrain — Function
solveStrain(q; DoFResults=false)

Solves the strain field E from displacement vector q. Strain field is given per elements, so it usually contains jumps at the boundaries of elements. Details of mesh is available in problem. If DoFResults is true, E is a matrix with nodal results. In this case showDoFResults can be used to show the results (otherwise showStrainResults or showElementResults).

Return: E

Types:

  • q: VectorField
  • E: TensorField
source
LowLevelFEM.solveStress — Function
solveStress(q::VectorField; 
            T=ScalarField([],[;;],[0.0],[],0,:null,q.model), 
            T₀=ScalarField([],reshape(zeros(q.model.non),:,1),[0],[],1,:scalar,q.model), 
            DoFResults=false)

Solves the stress field S from displacement vector q. Stress field is given per elements, so it usually contains jumps at the boundary of elements. Details of mesh is available in problem. If DoFResults is true, S is a matrix with nodal results. In this case showDoFResults can be used to show the results (otherwise showStressResults or showElementResults). If the T temperature field (and T₀ initial temperature field if it differs from zero) is given, the function solves also the thermal stresses.

Return: S

Types:

  • q: VectorField
  • T: ScalarField
  • T₀: ScalarField
  • S: TensorField
source
LowLevelFEM.solveAxialForce — Function
solveAxialForce(u::VectorField)

Compute axial (bar/truss) forces from a displacement field.

The input displacement field u must be nodal (VectorField), typically containing the nodal displacements of a truss or bar structure. The output is a scalar field (ScalarField), where each value represents the axial force in a truss element.

Arguments

  • u::VectorField: nodal displacement field.

Returns

  • ScalarField: axial forces defined per element.

Examples

u = solveDisplacement(problem, load=[loads], support=[supports])  # VectorField of nodal displacements
N = solveAxialForce(u)                               # ScalarField of axial element forces
source

Engineering eigenvalue helpers

For the generic solver and eigenfields, use Solution. These helpers provide specialized mechanical interpretations and the existing Eigen result container for engineering workflows.

LowLevelFEM.solveEigenModes — Function
solveEigenModes(K, M; n=6, fₘᵢₙ=0.01, support=[], mpc=[],
                coordSys=[], solver=:auto, directSolver=false)

Compute natural frequencies and real mode shapes for a single mechanical field and return the existing Gmsh-compatible Eigen container.

Backend options

solver=:auto, solveroptions=(;), and directSolver=false select/configure the underlying solveEigen backend. directSolver=true overrides solver with :direct; otherwise an ARPACK selection requires using Arpack. normalize=:mass is forwarded to eigenvector reconstruction.

source
LowLevelFEM.solveEigenFields — Function
solveEigenFields(K, M; n=6, fmin=0.0, support=[], mpc=[], coordSys=[])

Return a tuple of Eigen containers, one per physical field, for real multifield vibration modes. Use solveEigen directly for complex problems.

Backend options

solver=:auto, solveroptions=(;), and directSolver=false select/configure the underlying solveEigen backend. directSolver=true overrides solver with :direct; otherwise an ARPACK selection requires using Arpack. normalize=:mass is forwarded to eigenvector reconstruction.

source
LowLevelFEM.solveBucklingModes — Function
solveBucklingModes(K, Kg; n=6, support=[], mpc=[], coordSys=[])

Compute critical load multipliers from K*phi = -λ*Kg*phi and return a Gmsh-compatible Eigen container for a real, single-field problem.

Backend options

solver=:auto, solveroptions=(;), and directSolver=false select/configure the underlying solveEigen backend. directSolver=true overrides solver with :direct; otherwise an ARPACK selection requires using Arpack. Buckling modes use unit Euclidean eigenvector normalization.

source
LowLevelFEM.solveModalAnalysis — Function
solveModalAnalysis(problem; support=[], load=[], n=6,
                   fₘᵢₙ=1e-5, directSolver=false)

Compute real undamped modes of a structure, optionally around the current iteratively updated prestressed equilibrium. The eigensolver itself receives the full matrices and applies the support constraints exactly once.

source
LowLevelFEM.solveBuckling — Function
solveBuckling(problem; load=[], support=[], n=6)

Compute critical load multipliers after calculating the geometric stiffness of the prestressed reference configuration. Contact is not included.

source
LowLevelFEM.largestPeriodTime — Function
largestPeriodTime(K, M; kwargs...)

Return the longest vibration period 2π/sqrt(λmin) in a real mechanical system. Supports the same boundary-condition, MPC and solver keywords as smallestEigenValue. A zero eigenvalue yields Inf, as in the legacy formula.

source
LowLevelFEM.smallestPeriodTime — Function
smallestPeriodTime(K, M; kwargs...)

Return the shortest vibration period 2π/sqrt(λmax) in a real mechanical system. Supports the same boundary-condition, MPC and solver keywords as largestEigenValue.

source
LowLevelFEM.largestEigenValue — Function
largestEigenValue(K, C; support=BoundaryCondition[], mpc=MPC[],
                  coordSys=[], solver=:auto, which=:LM,
                  solveroptions=(;), kwargs...)

Return the generalized eigenvalue of largest magnitude for K*ϕ = λ*C*ϕ.

The default selection is the original unshifted ARPACK which=:LM. Return abs(real(λ))::Float64, preserving the legacy API. This is intended for real positive spectra such as undamped mechanical vibration problems; use the raw solveEigen result for instability or complex spectral analysis.

source
LowLevelFEM.smallestEigenValue — Function
smallestEigenValue(K, C; support=BoundaryCondition[], mpc=MPC[],
                   coordSys=[], solver=:auto, sigma=1e-8, which=:LR,
                   solveroptions=(;), kwargs...)

Return the smallest generalized eigenvalue near zero for K*ϕ = λ*C*ϕ.

For compatibility with the original implementation, the result is a Float64 containing abs(real(λ)). By default ARPACK uses a small numerical shift (sigma=1e-8, which=:LR); if that solve fails numerically, it retries with which=:SM and no numerical shift. Boundary conditions and MPCs use the same reduction as solveEigen, for single- and multifield systems.

This legacy wrapper discards the sign and imaginary part of an eigenvalue. Use solveEigen(K, C; output=:raw) to retain the original eigenvalue.

source

Time Integration

Start with the Time Integration guide for method comparison, all keyword defaults, prescribed histories and choosing Δt. The methods accept general scalar/vector/tensor and multifield operators.

Central differences (CDM)

LowLevelFEM.CDM — Function
CDM(K, M, C, f, U0, V0, n, Δt; kwargs...)
CDM(K, M, f, U0, V0, n, Δt; damping=nothing, kwargs...)

Integrate a second-order system by central differences:

\[M\ddot{u} + C\dot{u} + Ku = f.\]

Arguments

ArgumentMeaning
K, M, CPrimary-field, second-derivative and first-derivative operators.
fConstant or sampled RHS; Field, SystemVector, tuple or local/global sum.
U0, V0Initial primary field and first derivative; one column each.
n, ΔtStored sample count (n ≥ 2, including the initial sample) and positive constant increment.

Single-field and multifield SystemMatrixs are accepted. Omit C for zero damping; only that calling form accepts damping=C (default nothing). The positional-support alias CDM(K,M,[C,]f,bc,U0,V0,n,Δt) is retained.

CDM scheme options

KeywordDefaultMeaning
dampingScheme:laggedBackward damping velocity; :central uses centered damping.
velocityScheme:backwardHistorical half-step free-velocity estimates; :central returns sample-time estimates.
  • :lagged damping uses C*(u[j]-u[j-1])/Δt and the free mass matrix.
  • :central damping uses C*(u[j+1]-u[j-1])/(2Δt) and the effective matrix M + Δt*C/2; it is second-order in the damping term.
  • Central output velocities use centered interior and one-sided final differences; the initial free value remains V0.

Diagonal systems use componentwise division; otherwise a factorization is cached. A consistent or projected mass is supported and is not automatically lumped. CDM has no solver or preconditioner keywords.

Data, constraints and coordinates

KeywordDefaultMeaning
supportBoundaryCondition[]Prescribed components and their complete time histories.
mpcMPC[]Multi-point constraints, including multifield remote couplings.
coordSysCoordinateSystem[]Local bases for loads, initial values, supports and MPC components.
t00.0Time of the initial sample.

Loads have one constant column or exactly n sampled columns. Initial fields have one column. Input time labels are not resampled. support is the only source of prescribed histories: use numbers, spatial (x,y,z) functions, time-dependent (x,y,z,t) functions or sampled ScalarField components. Supported values override initial data on constrained DOFs; no external applyBoundaryConditions! call is needed.

Ordinary loads and initial fields use local solver components. Use Global(...) for Cartesian input or combine local/global loads. Output is always global. For multiple fields, use a SystemVector or tuple in matrix block order and identify field=Problem in every BC/MPC. Reduced-order and SEM spaces follow the shared solver transformations.

Constrained derivatives always follow the prescribed history by finite differences, independently of velocityScheme. Two samples define linear motion with zero acceleration; four samples permit second-order acceleration at both endpoints. The unsupported coordinate/reduced/SEM combinations are the same as for HHT; mass must be nonsingular on free coordinates.

Operator updates

KeywordDefaultUpdated quantity
modifyA2nothingA2=M: second-derivative operator.
modifyA1nothingA1=C: first-derivative operator.
modifyA0nothingA0=K: primary-field operator.
modifyRHSnothingRHS at the known current state.
copyOperatorstrueCopy matrix callback inputs; false borrows them read-only.
nonlinearoptions(;)maxiter=30, reltol=1e-9, abstol=1e-11, relaxation=1.0.

Callbacks use callback(operator,state) in full global coordinates, with the same state, return types and copying contracts as HHT. With copyOperators=false, matrix inputs and all earlier returned matrices must remain read-only; return a new independent matrix for any change. RHS inputs remain private, and internal cache copies are retained. Returning nothing preserves the accepted operator or prescribed RHS sample. Displacement updates remain explicit. A consistency iteration handles callback dependence on acceleration or on the centered damping velocity; it does not introduce an implicit displacement Newton solve. Nonlinear options control that residual iteration and require at least one callback. maxiter is positive, tolerances are nonnegative, and relaxation lies in (0,1].

Returns

Return (u,v) as global nodal Fields at t0 + (j-1)*Δt, j=1:n. Multifield outputs are tuples in block order, for example (u1,u2), (v1,v2) = CDM(...). Backward free velocities are half-step estimates stored under these same time labels; choose velocityScheme=:central for sample-time derivatives.

Choosing the time step

For an undamped linear system, let ωmax be the largest free-coordinate frequency from K*ϕ = ω²*M*ϕ. Require Δt < 2/ωmax and leave a safety margin. For classical modal damping with dampingScheme=:lagged, a conservative limit is

\[\Delta t_{\mathrm{crit}} = \frac{2}{\omega_{\max}} \left(\sqrt{1+\xi_{\max}^2}-\xi_{\max}\right),\]

where ξmax bounds modal damping ratios over the retained spectrum. Centered damping keeps the undamped modal limit 2/ωmax for nonnegative classical damping. These formulas do not establish stability for arbitrary nonsymmetric or nonproportionally damped systems. Resolve forcing/support motion as well, perform step refinement, and reassess the limit when callbacks change operators. Use CDMaccuracyAnalysis with the same dampingScheme; the time-step guide gives an eigenvalue-based example.

Example

u, v = CDM(K, M, C, f, u0, v0, n, Δt;
           support=bc, dampingScheme=:central, velocityScheme=:central)
source

HHT / Newmark

LowLevelFEM.HHT — Function
HHT(K, M, C, f, U0, V0, n, Δt; kwargs...)
HHT(K, M, f, U0, V0, n, Δt; damping=nothing, kwargs...)

Integrate a second-order system with the HHT-α / Newmark method:

\[M\ddot{u} + C\dot{u} + Ku = f.\]

Arguments

ArgumentMeaning
K, M, CField, second-derivative and first-derivative operators; single- or multifield SystemMatrixs.
fConstant or sampled RHS Field, SystemVector, field tuple or local/global sum.
U0, V0Initial primary field and first derivative, one column each, on free DOFs.
nNumber of stored samples, including the initial sample; n ≥ 2.
ΔtConstant finite positive time increment.

Omit positional C for zero physical damping. Only in that calling form, damping=C supplies the same operator by keyword (default nothing). The positional-support alias HHT(K,M,[C,]f,bc,U0,V0,n,Δt) is retained.

HHT parameters

KeywordDefaultMeaning
α0.0Algorithmic damping, in [-1/3,0]; distinct from physical C.
δnothingOptional override of the relation γ=0.5+δ.
γ0.5-αVelocity parameter when δ is omitted; explicit values override it.
β(0.5+γ)^2/4Displacement parameter; positive, and explicitly overridable.

The standard choice is γ=0.5-α, β=(1-α)^2/4; α=0 gives average-acceleration Newmark. Explicit δ=0 recovers the historical independent parameter family. Custom γ ≥ 0, β > 0 are accepted but need their own stability assessment.

Data, constraints and coordinates

KeywordDefaultMeaning
supportBoundaryCondition[]Prescribed components and their complete time histories.
mpcMPC[]Multi-point constraints, including multifield remote couplings.
coordSysCoordinateSystem[]Local bases for loads, initial values, supports and MPC components.
t00.0Time of the initial sample.

Loads have one constant column or exactly n sampled columns. Initial fields have one column. Input time labels are not resampled. support is the only source of prescribed histories: use numbers, spatial (x,y,z) functions, time-dependent (x,y,z,t) functions or sampled ScalarField components. Supported values override initial data on constrained DOFs; no external applyBoundaryConditions! call is needed.

Ordinary loads and initial fields use local solver components. Use Global(...) for Cartesian input or combine local/global loads. Output is always global. For multiple fields, use a SystemVector or tuple in matrix block order and identify field=Problem in every BC/MPC. Reduced-order and SEM spaces follow the shared solver transformations.

Prescribed derivatives come from the support history, using centered interior and one-sided endpoint differences. With two samples acceleration is zero; with three it is the same second difference at all samples; endpoint acceleration is second-order for at least four samples. Only free unknowns use Newmark recurrence. Prescribed inertia, damping and stiffness enter the effective load with the same HHT endpoint weighting as applied loads.

Linear solver options

KeywordDefaultMeaning
solver:autoSelect a direct or iterative solve; choices below.
preconditioner:auto:ich for CG, :ilu for GMRES; also :none or a supplied object.
solveroptions(;)Native iterative options, e.g. (reltol=1e-9, maxiter=1000).
preconditioneroptions(;)Options for a symbolic preconditioner, e.g. (memory=2,) for :ich.
  • Direct choices: :auto, :backslash, :lu, :lu_no_ordering, :cholesky, :ldlt, :qr.
  • Iterative choices: :cg (positive-definite symmetric systems) and :gmres. Load IterativeSolvers; :ich additionally needs Preconditioners, and :ilu needs IncompleteLU.
  • Wrap every contributing operator in Symmetric(...) to declare the effective matrix symmetric. Then :auto tries Cholesky with LU fallback; otherwise it uses the general sparse factorization. Symmetry alone does not imply positive definiteness.
  • Nonempty option tuples and actual preconditioners are for iterative solves. log, Pl, Pr and initially_zero are managed internally. Constructor options cannot accompany :none or a preconstructed preconditioner.

For unchanged coefficients, the effective factorization/preconditioner is reused. See solveField for the shared backend contract.

The initial acceleration uses a separate mass solve with the same solver settings; diagonal mass uses direct division.

Operator updates and nonlinear iteration

The generic names are A2=M, A1=C, A0=K.

KeywordDefaultUpdated quantity
modifyA2nothingSecond-derivative operator, e.g. mass.
modifyA1nothingFirst-derivative operator, e.g. damping.
modifyA0nothingPrimary-field operator, e.g. stiffness or tangent.
modifyRHSnothingRHS at the evaluation time.
copyOperatorstrueCopy matrix callback inputs; false borrows them read-only.
nonlinearoptions(;)Nonlinear iteration controls listed below.

HHT reevaluates callbacks within each step until discrete equilibrium converges.

The callback signature is callback(operator, state). Matrices are full/global SystemMatrixs (optionally Symmetric); RHS results are one-column global Fields, field tuples or SystemVectors. state includes trial fields and derivatives, Problems/material data, time, step, iteration, previous accepted snapshot and current operators. Callback order is A2, A0, A1, RHS. See the complete callback guide.

With copyOperators=true, the matrix argument is a private copy; return it to keep in-place edits. With copyOperators=false, it is the accepted operator and must remain read-only. Return a new independent matrix to change it, or return the unchanged argument/nothing to retain it. Never overwrite an earlier returned matrix or its shared storage. The option affects only matrix callback inputs: RHS arguments remain private, and internal cache copies stay. Returning nothing from an RHS callback retains the prescribed RHS sample. State data are read-only. Mesh, field ordering, supports, MPCs and bases stay fixed; inactive MPC DOFs cannot be activated.

nonlinearoptions memberDefaultMeaning
maxiter30Maximum nonlinear updates; positive integer.
reltol1e-9Relative residual tolerance; nonnegative.
abstol1e-11Absolute residual tolerance, in equilibrium-equation units; nonnegative.
relaxation1.0Fraction of each correction, in (0,1].

For Newton iteration, return the tangent J(u) as A0 and external - internal(u) + J(u)*u as RHS. State-dependent A2/A1 also require consistent linearization for Newton convergence. Picard updates are permitted. Nonconvergence throws a step/time/residual error. Without callbacks, leave nonlinearoptions=(;) to use the linear path.

Returns

Return (u,v) as global nodal Fields, with n columns at t[j] = t0 + (j-1)*Δt. For multiple fields, return tuples in block order: (u1,u2), (v1,v2) = HHT(...).

Choosing the time step

For linear positive-definite mass, nonnegative stiffness and physical damping, the standard HHT parameter family is unconditionally stable. This is a stability property, not a time-resolution guarantee. Start with about 20–50 samples per shortest period of interest, resolve rapid loads/support motion, then halve Δt and compare the quantities of interest. Use HHTaccuracyAnalysis to inspect damping and phase effects; see the time-step guide for a practical workflow.

Example

bc = [BoundaryCondition("base"; field=U,
                        ux=(x,y,z,t)->0.001*sin(20t), uy=0.0)]
u, v = HHT(K, M, C, f, u0, v0, n, Δt; support=bc, α=-0.1)

Limitations

Mass must be nonsingular on free reduced coordinates; arbitrary mass-singular DAEs are not supported. Combining SEM with local coordinates or MPCs on the same field is unsupported. See also CDM, FDM.

source
LowLevelFEM.CDMaccuracyAnalysis — Function
CDMaccuracyAnalysis(ωmin, ωmax, Δt, type; kwargs...)

Evaluate a scalar modal amplification model of CDM. Frequencies are angular frequencies from K*ϕ=ω²*M*ϕ.

Arguments and output

  • ωmin, ωmax: positive frequency interval in radians/time.
  • Δt: positive candidate time increment.
  • type: analysis listed below.
  • Return (x,y) vectors of length n, for plotting without a GUI dependency.
typeyx
:SRSpectral radius of the amplification matrix.Natural log of ω*Δt/(2π).
:PDRPhysical damping contribution from the β series.ω*Δt/(2π).
:ADRAlgorithmic damping indicator.ω*Δt/(2π).
:PERelative period-error indicator.ω*Δt/(2π).

Keyword arguments

KeywordDefaultMeaning
n100Number of frequency samples.
dampingScheme:laggedMatch the integrator: :lagged or :central.
α0.0Legacy mass-proportional damping parameter; not HHT algorithmic α.
ξ0.01Scalar/vector of β-series damping contributions at ωmax.
βDerived from ξExplicit Caughey-series coefficients; overrides the derived values.
show_βfalsePrint β coefficients.
show_ξfalsePrint the corresponding β-series contributions at ωmax.

The derived coefficients are β[i]=2ξ[i]/ωmax^(2i-1). The amplification matrix uses the existing convention ξeff(ω)=α/ω + sum(β[i]*ω^(2i-1)/2). Thus, for a physical mass term a*M, use α=a/2. The :PDR curve and show_ξ report only the β-series contribution; they do not include the mass term. Explicit β permits stiffness-proportional or higher-order Caughey damping models.

Use and limitations

Use :SR to inspect a candidate stable step; use :PE and :ADR to judge numerical distortion. Select the same damping scheme as the integration run. This is a modal/proportional model, not a stability proof for an arbitrary coupled or nonproportionally damped matrix system.

x, radius = CDMaccuracyAnalysis(ωmin, ωmax, Δt, :SR;
                              ξ=0.02, dampingScheme=:central)

See Serfőző and Pere, An effective reduction method with Caughey damping for spurious oscillations in dynamic problems, Meccanica (2025), https://doi.org/10.1007/s11012-025-02036-9.

source
LowLevelFEM.HHTaccuracyAnalysis — Function
HHTaccuracyAnalysis(ωmin, ωmax, Δt, type; kwargs...)

Evaluate the HHT modal amplification matrix, including physical damping. Use it to compare candidate time increments and HHT parameter choices.

Arguments and output

  • ωmin, ωmax: positive angular-frequency interval from K*ϕ=ω²*M*ϕ.
  • Δt: finite positive candidate increment.
  • type: analysis listed below.
  • Return (x,y) vectors of length n.
typeyx
:SRAmplification spectral radius.Natural log of ω*Δt/(2π).
:PDRTotal physical modal damping ratio.ω*Δt/(2π).
:ADRAlgorithmic damping indicator.ω*Δt/(2π).
:PERelative period-error indicator.ω*Δt/(2π).

Keyword arguments

KeywordDefaultMeaning
n100Number of samples; at least 2.
α0.0HHT algorithmic damping in [-1/3,0].
δnothingOptional γ=0.5+δ relation.
γ0.5-αStandard default, or 0.5+δ when δ is supplied.
β(0.5+γ)^2/4Displacement parameter; explicit values override the default.
ξ0.0Physical modal ratio, a number or function ξ(ω).
massDamping0.0Coefficient of M in Rayleigh damping.
stiffnessDamping0.0Coefficient of K in Rayleigh damping.

The physical modal ratio is ξ(ω) + massDamping/(2ω) + stiffnessDamping*ω/2. These terms affect the amplification matrix; :PDR reports their sum. HHT defaults and explicit parameter overrides follow HHT.

Example and limitations

x, radius = HHTaccuracyAnalysis(ωmin, ωmax, Δt, :SR;
                               α=-0.1, ξ=0.02, stiffnessDamping=1e-4)

Use the same coefficients as the transient calculation. This scalar analysis assumes modal/proportional damping; an arbitrary nonproportional matrix cannot be reconstructed from the undamped frequency interval alone. Stability of the standard linear scheme does not replace a time-step refinement check.

See Belytschko and Hughes, Computational Methods for Transient Analysis (North-Holland, 1983), and Serfőző and Pere, A method to accurately define arbitrary algorithmic damping character as viscous damping, Arch. Appl. Mech. 93 (2023), https://doi.org/10.1007/s00419-023-02454-9.

source

Initial fields

LowLevelFEM.initialDisplacement — Function
initialDisplacement(problem::Problem, 
                    name::String; 
                    ux=nothing, 
                    uy=nothing, 
                    uz=nothing)

Sets the displacement values ux, uy and uz (depending on the dimension of the problem) at nodes belonging to physical group name. Returns the initial displacement vector u0.

Return: u0

Types:

  • problem: Problem
  • name: String
  • u0: VectorField
  • ux: Float64
  • uy: Float64
  • uz: Float64
source
LowLevelFEM.initialDisplacement! — Function
initialDisplacement!(u0::VectorField, 
                     name::String; 
                     ux=nothing, 
                     uy=nothing, 
                     uz=nothing)

Changes the displacement values to ux, uy and uz (depending on the dimension of the problem) at nodes belonging to physical group name. Original values are in displacement vector u0.

Return: nothing

Types:

  • name: String
  • ux: Float64
  • uy: Float64
  • uz: Float64
  • u0: VectorField
source
LowLevelFEM.initialVelocity — Function
initialVelocity(problem::Problem, 
                name::String; 
                vx=nothing, 
                vy=nothing, 
                vz=nothing)

Sets the velocity values vx, vy and vz (depending on the dimension of the problem) at nodes belonging to physical group name. Returns the initial velocity vector v0.

Return: v0

Types:

  • problem: Problem
  • name: String
  • vx: Float64
  • vy: Float64
  • vz: Float64
  • v0: VectorField
source
LowLevelFEM.initialVelocity! — Function
initialVelocity!(u0::VectorField, 
                 name::String; 
                 vx=nothing, 
                 vy=nothing, 
                 vz=nothing)

Changes the velocity values vx, vy and vz (depending on the dimension of the problem) at nodes belonging to physical group name. Original values are in velocity vector v0.

Returns: nothing

Types:

  • name: String
  • v0: VectorField
  • vx: Float64
  • vy: Float64
  • vz: Float64
source

Utility

LowLevelFEM.printElasticConstantsTable — Function
printElasticConstantsTable(; io::IO=stdout)

Prints a compact reference table of the most common relations between isotropic linear-elastic material constants:

  • Young's modulus E
  • Poisson's ratio ν
  • Shear modulus G (also denoted as μ)
  • Bulk modulus K
  • Lamé's first parameter λ
  • Lamé's second parameter μ (= G)

The table is meant as a quick cheat-sheet for documentation / teaching.

source