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 — FunctionstiffnessMatrix(problem; elements=[], forceOneThread=true) -> SystemMatrixAssemble 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 ∫.
LowLevelFEM.nonLinearStiffnessMatrix — FunctionnonLinearStiffnessMatrix(q::VectorField)Solves the nonlinear stiffness matrix of the problem. q is a displacement field.
Returns: stiffMat
Types:
problem: Problemq: VectorFieldstiffMat: 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 ∫.
LowLevelFEM.massMatrix — FunctionmassMatrix(problem; lumped=true)Solves the mass matrix of the problem. If lumped is true, computes the lumped mass matrix.
Returns: massMat
Types:
problem: Problemlumped: BooleanmassMat: SystemMatrix
Examples
M = massMatrix(problem; lumped=true)LowLevelFEM.dampingMatrix — FunctiondampingMatrix(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: SystemMatrixM: 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])LowLevelFEM.elasticSupportMatrix — FunctionelasticSupportMatrix(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: ProblemelSupp: Vector{BoundaryCondition}elSuppMat: SystemMatrix
LowLevelFEM.loadVector — FunctionloadVector(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: Problemloads: Vector{BoundaryCondition}loadVec: VectorFieldF: Union{Nothing,TensorField}
LowLevelFEM.sourceVector — FunctionsourceVector(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.
LowLevelFEM.applyBoundaryConditions — FunctionapplyBoundaryConditions(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: Problemsupports: Vector{BoundaryCondition}
LowLevelFEM.applyBoundaryConditions! — FunctionapplyBoundaryConditions!(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: Problemfield: ScalarField, VectorField or TensorFieldsupports: Vector{BoundaryCondition}
LowLevelFEM.applyElasticSupport! — FunctionapplyElasticSupport!(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: SystemMatrixelastSupp: Vector{BoundaryCondition}}
Static and Stress/Strain Solvers
LowLevelFEM.solveDisplacement — FunctionsolveDisplacement(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 = ffor 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): Iftrue, 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. fromiluorichol).ordering::Bool(keyword): Iffalse, 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.
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): Iftrue, solves the reduced system using only free degrees of freedom. Iffalse, modifies the full system matrix explicitly.iterative::Bool(keyword): Iftrue, 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. fromiluorichol).ordering::Bool(keyword): Iffalse, 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 returnsnothing. - 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.
LowLevelFEM.solveStrain — FunctionsolveStrain(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: VectorFieldE: TensorField
LowLevelFEM.solveStress — FunctionsolveStress(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: VectorFieldT: ScalarFieldT₀: ScalarFieldS: TensorField
LowLevelFEM.solveAxialForce — FunctionsolveAxialForce(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 forcesEngineering 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 — FunctionsolveEigenModes(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.
LowLevelFEM.solveEigenFields — FunctionsolveEigenFields(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.
LowLevelFEM.solveBucklingModes — FunctionsolveBucklingModes(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.
LowLevelFEM.solveModalAnalysis — FunctionsolveModalAnalysis(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.
LowLevelFEM.solveBuckling — FunctionsolveBuckling(problem; load=[], support=[], n=6)Compute critical load multipliers after calculating the geometric stiffness of the prestressed reference configuration. Contact is not included.
LowLevelFEM.largestPeriodTime — FunctionlargestPeriodTime(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.
LowLevelFEM.smallestPeriodTime — FunctionsmallestPeriodTime(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.
LowLevelFEM.largestEigenValue — FunctionlargestEigenValue(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.
LowLevelFEM.smallestEigenValue — FunctionsmallestEigenValue(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.
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 — FunctionCDM(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
| Argument | Meaning |
|---|---|
K, M, C | Primary-field, second-derivative and first-derivative operators. |
f | Constant or sampled RHS; Field, SystemVector, tuple or local/global sum. |
U0, V0 | Initial primary field and first derivative; one column each. |
n, Δt | Stored 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
| Keyword | Default | Meaning |
|---|---|---|
dampingScheme | :lagged | Backward damping velocity; :central uses centered damping. |
velocityScheme | :backward | Historical half-step free-velocity estimates; :central returns sample-time estimates. |
:laggeddamping usesC*(u[j]-u[j-1])/Δtand the free mass matrix.:centraldamping usesC*(u[j+1]-u[j-1])/(2Δt)and the effective matrixM + Δ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
| Keyword | Default | Meaning |
|---|---|---|
support | BoundaryCondition[] | Prescribed components and their complete time histories. |
mpc | MPC[] | Multi-point constraints, including multifield remote couplings. |
coordSys | CoordinateSystem[] | Local bases for loads, initial values, supports and MPC components. |
t0 | 0.0 | Time 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
| Keyword | Default | Updated quantity |
|---|---|---|
modifyA2 | nothing | A2=M: second-derivative operator. |
modifyA1 | nothing | A1=C: first-derivative operator. |
modifyA0 | nothing | A0=K: primary-field operator. |
modifyRHS | nothing | RHS at the known current state. |
copyOperators | true | Copy 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)HHT / Newmark
LowLevelFEM.HHT — FunctionHHT(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
| Argument | Meaning |
|---|---|
K, M, C | Field, second-derivative and first-derivative operators; single- or multifield SystemMatrixs. |
f | Constant or sampled RHS Field, SystemVector, field tuple or local/global sum. |
U0, V0 | Initial primary field and first derivative, one column each, on free DOFs. |
n | Number of stored samples, including the initial sample; n ≥ 2. |
Δt | Constant 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
| Keyword | Default | Meaning |
|---|---|---|
α | 0.0 | Algorithmic damping, in [-1/3,0]; distinct from physical C. |
δ | nothing | Optional override of the relation γ=0.5+δ. |
γ | 0.5-α | Velocity parameter when δ is omitted; explicit values override it. |
β | (0.5+γ)^2/4 | Displacement 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
| Keyword | Default | Meaning |
|---|---|---|
support | BoundaryCondition[] | Prescribed components and their complete time histories. |
mpc | MPC[] | Multi-point constraints, including multifield remote couplings. |
coordSys | CoordinateSystem[] | Local bases for loads, initial values, supports and MPC components. |
t0 | 0.0 | Time 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
| Keyword | Default | Meaning |
|---|---|---|
solver | :auto | Select 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. LoadIterativeSolvers;:ichadditionally needsPreconditioners, and:iluneedsIncompleteLU. - Wrap every contributing operator in
Symmetric(...)to declare the effective matrix symmetric. Then:autotries 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,Prandinitially_zeroare managed internally. Constructor options cannot accompany:noneor 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.
| Keyword | Default | Updated quantity |
|---|---|---|
modifyA2 | nothing | Second-derivative operator, e.g. mass. |
modifyA1 | nothing | First-derivative operator, e.g. damping. |
modifyA0 | nothing | Primary-field operator, e.g. stiffness or tangent. |
modifyRHS | nothing | RHS at the evaluation time. |
copyOperators | true | Copy 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 member | Default | Meaning |
|---|---|---|
maxiter | 30 | Maximum nonlinear updates; positive integer. |
reltol | 1e-9 | Relative residual tolerance; nonnegative. |
abstol | 1e-11 | Absolute residual tolerance, in equilibrium-equation units; nonnegative. |
relaxation | 1.0 | Fraction 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.
Modal accuracy analysis
LowLevelFEM.CDMaccuracyAnalysis — FunctionCDMaccuracyAnalysis(ω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 lengthn, for plotting without a GUI dependency.
type | y | x |
|---|---|---|
:SR | Spectral radius of the amplification matrix. | Natural log of ω*Δt/(2π). |
:PDR | Physical damping contribution from the β series. | ω*Δt/(2π). |
:ADR | Algorithmic damping indicator. | ω*Δt/(2π). |
:PE | Relative period-error indicator. | ω*Δt/(2π). |
Keyword arguments
| Keyword | Default | Meaning |
|---|---|---|
n | 100 | Number of frequency samples. |
dampingScheme | :lagged | Match the integrator: :lagged or :central. |
α | 0.0 | Legacy mass-proportional damping parameter; not HHT algorithmic α. |
ξ | 0.01 | Scalar/vector of β-series damping contributions at ωmax. |
β | Derived from ξ | Explicit Caughey-series coefficients; overrides the derived values. |
show_β | false | Print β coefficients. |
show_ξ | false | Print 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.
LowLevelFEM.HHTaccuracyAnalysis — FunctionHHTaccuracyAnalysis(ω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 fromK*ϕ=ω²*M*ϕ.Δt: finite positive candidate increment.type: analysis listed below.- Return
(x,y)vectors of lengthn.
type | y | x |
|---|---|---|
:SR | Amplification spectral radius. | Natural log of ω*Δt/(2π). |
:PDR | Total physical modal damping ratio. | ω*Δt/(2π). |
:ADR | Algorithmic damping indicator. | ω*Δt/(2π). |
:PE | Relative period-error indicator. | ω*Δt/(2π). |
Keyword arguments
| Keyword | Default | Meaning |
|---|---|---|
n | 100 | Number of samples; at least 2. |
α | 0.0 | HHT algorithmic damping in [-1/3,0]. |
δ | nothing | Optional γ=0.5+δ relation. |
γ | 0.5-α | Standard default, or 0.5+δ when δ is supplied. |
β | (0.5+γ)^2/4 | Displacement parameter; explicit values override the default. |
ξ | 0.0 | Physical modal ratio, a number or function ξ(ω). |
massDamping | 0.0 | Coefficient of M in Rayleigh damping. |
stiffnessDamping | 0.0 | Coefficient 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.
Initial fields
LowLevelFEM.initialDisplacement — FunctioninitialDisplacement(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: Problemname: Stringu0: VectorFieldux: Float64uy: Float64uz: Float64
LowLevelFEM.initialDisplacement! — FunctioninitialDisplacement!(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: Stringux: Float64uy: Float64uz: Float64u0: VectorField
LowLevelFEM.initialVelocity — FunctioninitialVelocity(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: Problemname: Stringvx: Float64vy: Float64vz: Float64v0: VectorField
LowLevelFEM.initialVelocity! — FunctioninitialVelocity!(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: Stringv0: VectorFieldvx: Float64vy: Float64vz: Float64
Utility
LowLevelFEM.printElasticConstantsTable — FunctionprintElasticConstantsTable(; 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.