Time Integration

Use this page to choose a method, prepare data, find keyword defaults and select a time increment. The complete function references remain at HHT, CDM and FDM.

Choose a method

EquationMethodTypical use
A2*ü + A1*u̇ + A0*u = rhsHHTImplicit second-order dynamics; adjustable algorithmic damping.
A2*ü + A1*u̇ + A0*u = rhsCDMExplicit displacement updates; a stability-limited increment.
A1*ẋ + A0*x = rhsFDMFirst-order systems, including diffusion and heat conduction.

The names K, M and C are positional aliases, not restrictions to elasticity:

Generic operatorHHT / CDM argumentFDM argument
A2: second derivativeMNot present.
A1: first derivativeC, optional dampingC, required capacity.
A0: primary fieldKK
RHSfq
u, v = HHT(K, M, C, f, u0, v0, n, Δt; support=bc, α=-0.1)
u, v = CDM(K, M, C, f, u0, v0, n, Δt;
           support=bc, dampingScheme=:central, velocityScheme=:central)
x = FDM(K, C, q, x0, n, Δt; support=bc, ϑ=0.5)

Omit positional C in HHT/CDM for zero physical damping, or provide it as damping=C in that shorter calling form. The old positional BC-list forms remain available; the keyword support=bc makes new calls easier to read.

Inputs, time grid and results

InputRequired layout
OperatorsCompatible SystemMatrixs, optionally wrapped in Symmetric.
LoadsOne constant column or exactly n columns in time order.
U0, X0, V0Exactly one initial column; values initialize free coordinates.
nNumber of stored samples, including the initial one; at least 2.
Δt, t0Constant positive increment and initial time (default 0.0).

The final time is t0 + (n-1)*Δt. Input Field time labels are not interpolated; columns must already match this grid. After changing Δt, rebuild sampled loads/supports and n to preserve the desired duration.

Loads and initial values accept nodal/element Fields, block SystemVectors or field tuples in matrix order. Ordinary data use local solver components; Global(field) or Global(SystemVector(...)) marks Cartesian input. A local load and Global(...) load can be added. Output consists of global nodal Fields with one column per sample.

MethodSingle-field outputMultifield output
HHT / CDM(u,v)(u1,u2), (v1,v2) in block order.
FDMx(x1,x2) in block order.

Prescribed histories and constraints

Supply each boundary condition once

support selects both the prescribed component and its history. Do not also write that history into U0 or call applyBoundaryConditions!(U0,bc).

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)

Accepted component values are:

ValueInterpretation
NumberConstant in space and time.
(x,y,z)->valueSpatial function, constant in time.
(x,y,z,t)->valueEvaluated at each physical time sample.
ScalarField with 1 columnConstant component sampled over the mesh.
ScalarField with n columnsComplete sampled component history.

If a function accepts both three and four arguments (optional arguments or varargs), the spatial interpretation takes precedence. Use an explicit four-argument closure for time dependence.

ux_history = ScalarField(U, "base", (x,y,z,t)->0.001*sin(20t);
                         steps=n, tmin=t0, tmax=t0+(n-1)*Δt)
bc = [BoundaryCondition("base"; field=U, ux=ux_history, uy=0.0)]

Initial values and prescribed derivatives

  • Boundary values override U0/X0 on constrained components.
  • V0 initializes free first derivatives only. Prescribed velocities and accelerations follow the primary-variable history by finite differences.
  • Interior stencils are centered; endpoint stencils are one-sided. Two samples define linear motion with zero acceleration; three use one common second difference; four or more permit second-order acceleration at the endpoints.
  • To prescribe velocity data, integrate its scalar components with integrate(v_history) / ∫(v_history) and use the results in a BC.

HHT integrates only the free coordinates with Newmark kinematics. Prescribed inertia, damping and stiffness are first transferred to the effective load, then receive the HHT endpoint weights. FDM includes the full capacity increment -C_fc*(d[j+1]-d[j])/Δt.

Coordinates, MPCs and approximation spaces

KeywordDefaultRole
supportBoundaryCondition[]Prescribed component values/histories.
mpcMPC[]Kinematic ties between field DOFs.
coordSysCoordinateSystem[]Local nodal component bases.
t00.0Initial physical time.

The common transformation is u_global=Q*T*u_reduced: Q supplies coordinate bases and T contains approximation/MPC mappings. MPCs identify local components; prescribed slave values transfer to their masters at every sample. Each block BC and MPC must identify field=Problem.

  • Reduced-order and SEM interpolation use the existing cached transformations.
  • Reduced-order interpolation acts on the local components when a coordinate system is present. Coordinates plus SEM on the same field are unsupported.
  • SEM plus MPC on the same field is currently unsupported.
  • Separate block fields may use these features independently.
  • HHT/CDM need nonsingular mass on the remaining free coordinates; arbitrary mass-singular differential-algebraic systems are outside this interface.

Physical groups and components are resolved once per BC. Boundary-history storage scales with prescribed rows times n, including transfer/restriction; returned full solution histories still need nodal storage times n.

HHT parameters

KeywordDefaultEffect
α0.0Algorithmic damping in [-1/3,0]; physical damping is in C.
δnothingOptional override selecting γ=0.5+δ.
γ0.5-αVelocity parameter; a supplied value overrides the relation.
β(0.5+γ)^2/4Displacement parameter; can also be supplied explicitly.
dampingnothingC by keyword, only when positional C is omitted.

The standard family has γ=0.5-α, β=(1-α)^2/4. With α=0 this is average-acceleration Newmark. Explicit δ=0 selects the historical independent family. The implementation accepts custom finite γ ≥ 0, β > 0; those choices require their own stability assessment.

CDM scheme options

KeywordDefaultChoices
dampingScheme:lagged:lagged or :central.
velocityScheme:backward:backward or :central.
dampingnothingC by keyword, only when positional C is omitted.
ChoiceMeaning
Lagged dampingC*(u[j]-u[j-1])/Δt; first-order damping term, factor M.
Centered dampingC*(u[j+1]-u[j-1])/(2Δt); second-order damping term, factor M+Δt*C/2.
Backward free velocityHistorical half-step estimate stored under the sample's time label.
Central free velocityCentered sample-time derivative; one-sided final stencil; initial V0 retained.

Constrained derivatives always follow the prescribed history, regardless of velocityScheme. A diagonal mass uses division; otherwise CDM caches a factorization, without automatic mass lumping. CDM has no linear-solver or preconditioner keywords.

FDM theta parameter

KeywordDefaultChoices
ϑ0.5Any finite value in [0,1].
ValueMethodAccuracy and decay
0.0Explicit EulerFirst order; stability-limited step.
0.5Crank–NicolsonSecond order; weak damping of very stiff modes.
1.0Backward EulerFirst order; strong stiff-mode decay.

For constant coefficients, FDM prepares C_ff+ϑ*Δt*K_ff once. With callbacks, capacity is interpolated as (1-ϑ)*A1_old+ϑ*A1_new; each endpoint uses its own A0*x-rhs contribution.

Choosing Δt: stability and accuracy

CDM: respect the highest retained frequency

For a linear undamped positive-mass system, obtain the largest eigenvalue of the same constrained/reduced pencil K*ϕ=ω²*M*ϕ. Then

\[\Delta t < \frac{2}{\omega_{\max}} = \frac{T_{\min}}{\pi}, \qquad T_{\min}=\frac{2\pi}{\omega_{\max}}.\]

Lagged damping further limits the step. With classical modal damping and ξmax bounding modal ratios over the retained spectrum, a conservative bound is

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

Centered damping retains the undamped modal limit for nonnegative classical damping. Use a safety factor below the relevant bound (for example 0.8) and also check accuracy. These formulas are not a general stability certificate for arbitrary nonsymmetric/nonproportionally damped operators.

# Undamped or centered classically damped CDM; use the run's own constraints.
λmax = largestEigenValue(K, M; support=bc, mpc=ties, coordSys=cs)
ωmax = sqrt(λmax)
Δt_limit = 2/ωmax
Δt = min(0.8*Δt_limit, T_interest/40)

Here T_interest is the shortest physical period that must be resolved, including any faster imposed load or support motion. largestEigenValue uses its optional ARPACK backend unless a direct solver is requested; load Arpack first when needed. For lagged damping include its damping-dependent factor in Δt_limit.

HHT: unconditional linear stability still needs resolution

The standard HHT family is unconditionally stable for the usual linear system with positive-definite mass, nonnegative stiffness and nonnegative physical damping. This does not ensure accurate periods, peaks or wave propagation.

  1. Start with roughly 20–50 samples per shortest period of interest.
  2. Resolve rapid load changes, support motion and expected contact events.
  3. Inspect :PE, :ADR and :SR using HHTaccuracyAnalysis.
  4. Halve Δt, resample histories and compare the actual output quantities.

Algorithmic damping can suppress unwanted high-frequency modes; it cannot recover a physical response that was not resolved. Nonlinear iteration also has no unconditional convergence guarantee from the linear stability result.

FDM: distinguish diffusion stability from decay accuracy

For K*ϕ=λ*C*ϕ with real nonnegative spectrum:

Theta weightLinear stability condition
ϑ < 0.5Δt < 2/((1-2ϑ)*λmax); leave a safety margin.
ϑ ≥ 0.5No linear stability restriction on Δt for this spectral class.

For complex spectra, examine the full theta stability region instead. Even with Crank–Nicolson or backward Euler, resolve the shortest decay time 1/λ that matters and any faster forcing. Large λ*Δt can produce alternating stiff modes with Crank–Nicolson. Use FDMaccuracyAnalysis and refine Δt to check decay rates and peaks.

When operators change

Reassess the CDM/explicit-FDM bound when callbacks change coefficients: contact can increase the highest frequency abruptly. These APIs use fixed Δt, not an automatic adaptive-step controller. A step that converges nonlinearly can still be temporally inaccurate.

Linear solver and preconditioner options

These four keywords apply to HHT and FDM, not CDM.

KeywordDefaultMeaning
solver:autoBackend in the table below.
preconditioner:auto:auto, :none, :ich, :ilu, or a preconstructed object.
solveroptions(;)Native iterative keywords, e.g. (reltol=1e-9,maxiter=1000).
preconditioneroptions(;)Options used to construct :ich or :ilu.
SolverUse
:autoGeneral sparse factorization; with symmetric declarations, Cholesky with LU fallback.
:backslashJulia's generic factorization; diagonal systems use division.
:luLU factorization.
:lu_no_orderingLU without the default column reordering.
:choleskyPositive-definite symmetric system; no fallback.
:ldltSymmetric system; must be declared symmetric.
:qrQR factorization.
:cgIterative conjugate gradients for a positive-definite symmetric system.
:gmresIterative GMRES for a general system.

Wrap all contributing matrices in Symmetric(...) for a symmetric effective system: K/M and supplied C in HHT, K/C in FDM. Upper- or lower-triangle storage is supported. A symmetric declaration does not prove positive definiteness.

PreconditionerDependency / behavior
:autoCG selects :ich; GMRES selects :ilu.
:noneNo preconditioner.
:ichPreconditioners; constructor memory defaults to 2.
:iluIncompleteLU; forwards constructor options such as τ.
Supplied objectReused directly; constructor options must be empty.

Both iterative solvers need using IterativeSolvers. Load the selected preconditioner package explicitly. Automatic CG preconditioning requires the symmetric declaration. Nonempty option tuples and actual preconditioners are rejected with direct solvers. preconditioneroptions also cannot accompany :none or a preconstructed object. Native log, Pl, Pr, initially_zero are managed internally; other supported native options depend on the backend.

using IterativeSolvers, Preconditioners
u, v = HHT(Symmetric(K), Symmetric(M), Symmetric(C),
           f, u0, v0, n, Δt;
           solver=:cg, solveroptions=(reltol=1e-10, maxiter=2000),
           preconditioner=:ich, preconditioneroptions=(memory=2,))

Fixed operators reuse factors/preconditioners. HHT also prepares a separate initial mass solve with the same settings unless the mass is diagonal. See solveField for the shared backend contract.

Operator updates and nonlinear iteration

Callback options

All callbacks default to nothing and use callback(operator,state). Extra constants, contact objects and model parameters can be captured by a closure or callable object; no Function type restriction is imposed.

KeywordHHT / CDMFDM
modifyA2Update M, the second-derivative operator.Only nothing is accepted.
modifyA1Update C, the first-derivative operator.Update C, the capacity operator.
modifyA0Update K, the primary-field operator/tangent.Update K, the primary-field operator/tangent.
modifyRHSUpdate f at the evaluated state.Update q at the trial endpoint.
copyOperatorsCopy matrix callback inputs (default true); false borrows them read-only.Same behavior.
nonlinearoptionsResidual iteration settings, default (;).Same settings.

With no callbacks, keep nonlinearoptions=(;) for the fast linear path. HHT/FDM iterate within the time step. CDM retains explicit displacement updates and only iterates acceleration/centered-velocity consistency when needed. Changing coefficients does not remove explicit stability limits.

What is in state?

MemberMeaning
fieldsTuple of trial global nodal Fields, even for one field.
velocityTuple of global first derivatives; nothing at FDM initialization.
accelerationTuple of global second derivatives for HHT/CDM; nothing for FDM.
problemsTuple of corresponding Problem objects, including materials.
tCurrent physical evaluation time.
dtConstant time increment.
stepZero-based sample index; the initial sample is 0.
iteration0 for the predictor, then the completed correction count.
phase:initial, :step for HHT/FDM, or :explicit for CDM.
previousPrevious accepted field snapshot; nothing at initialization.
operatorsCurrent full/global A2, A0, A1; exposed as updates proceed.

Callbacks run in order A2, A0, A1, RHS. For example, the A1 callback can use updated A2/A0 to build Rayleigh damping.

Inputs, returns and accepted state

CallbackInputReturn
Matrix callbackLast accepted full operator: private copy by default, read-only original with copyOperators=false.SystemMatrix, optionally Symmetric, or nothing.
RHS callbackPrivate one-column original prescribed RHS sample at state.t.Global one-column Field, tuple, SystemVector, or nothing.

With the default copyOperators=true, return the private matrix argument to retain in-place edits. Returning nothing keeps the accepted matrix or the original prescribed RHS sample. Every trial starts from the accepted base; changes do not accumulate across rejected/unequilibrated trials.

Avoiding matrix input copies

For callbacks that construct a new matrix, such as a weak-form assembly, copyOperators=false skips the otherwise unused input copy:

u, v = HHT(K, M, f, u0, v0, n, Δt;
           support=bc, modifyA0=assembleA0, copyOperators=false)

This Boolean option applies to matrix inputs of modifyA2, modifyA1 and modifyA0 in HHT/CDM/FDM. Without matrix callbacks it has no effect.

  • The borrowed matrix is read-only, including its underlying sparse arrays. Return a new, independently stored matrix for any change.
  • Returning the unchanged argument or nothing retains the accepted operator.
  • Do not overwrite a previously returned matrix, reuse its mutable storage for a new result, or mutate operators through state.operators. Such changes can corrupt accepted states and bypass projection/factorization invalidation.
  • Keep the default copyOperators=true for in-place matrix callbacks and return their modified private argument. RHS callback inputs remain private in either mode; copies needed for internal cache validity are retained.

The saving is one full input-matrix copy per matrix callback evaluation. It does not remove weak-form assembly, projection, factorization or state construction; its effect on total runtime should be measured for the actual model.

Callback data use global Cartesian components, including RHS values. Do not preapply coordinates, MPCs, Dirichlet elimination or basis reduction. Treat state Fields, Problems and state.operators as read-only. Callbacks may run repeatedly at the same time; do not commit irreversible material-history updates on the assumption that each call is an accepted step.

Numerical values and sparse connectivity may change. Problem identities, field order, dimensions, mesh connectivity, supports, MPCs, coordinates and approximation spaces stay fixed. Previously removed auxiliary MPC DOFs cannot be activated. Equal operators reuse their cached projection/factorization; RHS-only updates do not invalidate a matrix factorization.

Reusing CSC storage in a matrix callback

On a fixed mesh/domain, a matrix callback can assemble into its private input instead of building a new CSC pattern on every evaluation. Keep copyOperators=true and initialize the operator with a complete pattern:

K = ∫(Grad(P)⋅Grad(P); csc_matrix=build_csc_pattern(P, P))

function updateA0(A, state)
    fill!(A.A.nzval, 0.0)
    ∫(Grad(P)⋅(1 + state.t)⋅Grad(P); csc_matrix=A.A)
end

u, v = HHT(K, M, f, u0, v0, n, Δt;
           support=bc, modifyA0=updateA0, copyOperators=true)

Here A.A belongs to the private callback argument, so overwriting it preserves the accepted operator and the previous trial used for cache comparisons. HHT needs the old endpoint force, and FDM also blends the old and new capacity matrices. These histories must not be overwritten through borrowed inputs or reused external result storage.

A normal integral may have removed numerical zeros. Therefore, do not assume that an arbitrary existing K.A contains every coupling needed by a later nonlinear assembly. Supplying build_csc_pattern(...) to the initial integral preserves those entries; subsequent private copies retain them. Assembly adds to existing values: clear nzval before each independent assembly and never call dropzeros! on a pattern that will be reused. Put scalar factors inside the expression or use weight=.... Multiplying the assembled sparse matrix afterwards can remove structural zeros and make its pattern unsuitable for reuse. For example, replace b*∫(...; weight=b, csc_matrix=...) with ∫(...; weight=b, csc_matrix=...): the former also applies b twice. Incomplete vector component-block patterns are rejected before CSC scatter.

This avoids rebuilding the pattern and allocating another output CSC matrix. The private input copy is still allocated at each callback evaluation; quadrature, worker buffers, coefficient fields and solver storage can also allocate. copyOperators=false is for callbacks returning independent new matrices and cannot be combined with overwriting A.A in this example. A single external CSC matrix repeatedly returned and overwritten is also unsafe: object identity can otherwise hide changed values from projection/cache reuse.

Nonlinear controls

nonlinearoptions memberDefaultMeaning
maxiter30Maximum corrections; positive integer.
reltol1e-9Nonnegative relative residual tolerance.
abstol1e-11Nonnegative absolute tolerance in equilibrium-equation units.
relaxation1.0Correction fraction in (0,1].

The acceptance condition is norm(residual) ≤ abstol + reltol*scale, using assembled equilibrium terms for the scale. A small correction alone does not establish equilibrium. A failure throws the method, step, time and residual; the solution is not advanced on an unconverged trial.

Newton/Picard example

See Nonlinear Cantilever Dynamics: Secant vs Newton-Type HHT for a complete notebook comparing secant and tangent updates for a finite-rotation continuum model with the same internal-force residual.

For internal force g(u), return its tangent J(u) as A0 and f_external-g(u)+J(u)*u as RHS. Picard coefficient updates are also possible. State-dependent A2/A1 require their own consistent linearization for Newton convergence; the residual loop does not construct those derivatives.

# Scalar cubic internal force: k*u + λ*u^3; k, λ and P are captured.
updateA0 = (A, state) -> begin
    u = vec(state.fields[1].a)
    SystemMatrix(spdiagm(0 => k .+ 3λ .* u.^2), P)
end
updateRHS = (rhs, state) -> begin
    out = copy(rhs)
    out.a .+= 2λ .* state.fields[1].a.^3
    out
end
u, v = HHT(K, M, C, f, u0, v0, n, Δt;
           support=bc, modifyA0=updateA0, modifyRHS=updateRHS,
           nonlinearoptions=(reltol=1e-10, maxiter=30))

Multifield remote translation and rotation

Loads and initial data follow block order, for example (u1,u2), (v1,v2) = HHT(Kblock,Mblock,Cblock,F,U0,V0,n,Δt; ...). FDM returns (x1,x2) and uses the same preparation.

For physical displacement u_phys=u+R*φ, apply the same rigid map to every operator and load:

R = rigidRotationMap(mpc_u, mpc_φ)
block(A) = SystemMatrix([A A*R; R'*A R'*A*R])
Kblock, Mblock, Cblock = block(Ku), block(Mu), block(Cu)
F = SystemVector([fu, R'*fu])

(u,φ), (v,ω) = HHT(Kblock, Mblock, Cblock, F, U0, V0, n, Δt;
                   support=bc, mpc=[mpc_u,mpc_φ])
u_phys = u + R*φ
v_phys = v + R*ω

Transforming stiffness alone omits rotational inertia/coupling. No artificial independent mass is needed on the auxiliary rotation field: its inertia comes from R'*Mu*R. Inactive auxiliary DOFs are removed before time integration.

Accuracy-analysis helpers

FunctionSpectrumAvailable analysis
CDMaccuracyAnalysisK*ϕ=ω²*M*ϕ:SR, :PDR, :ADR, :PE; match dampingScheme.
HHTaccuracyAnalysisK*ϕ=ω²*M*ϕSame indicators; includes modal and Rayleigh damping.
FDMaccuracyAnalysisK*ϕ=λ*C*ϕtype=:SR for the theta method.

Each returns plotting vectors (x,y) and accepts n=100 sample points. For HHT/CDM :SR, x is the natural logarithm of ω*Δt/(2π); other HHT/CDM curves use ω*Δt/(2π). FDM uses λ*Δt.

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

Use the same damping parameters as the integrator. These scalar analyses assume modal/proportional damping; a general nonproportional matrix cannot be inferred from the undamped frequency interval alone. The helper docstrings list every parameter and the CDM helper's legacy mass-damping convention.

See also the 2D transient elasticity tutorial and the shared Solution API.