Solution API
Matrices and right-hand sides
SystemMatrix.A exposes the sparse matrix. SystemVector.a and nodal field .a expose RHS/solution matrices, with one column per independent RHS or mode. For block systems, preserve the same Problem order in matrices and vectors. Symmetric(K, :U) or Symmetric(K, :L) declares its authoritative triangle. Solvers expand that triangle before coordinate, approximation or MPC projection, so triangular storage is supported consistently across field, eigen and transient solutions. The opposite triangle is intentionally ignored, following Julia's Symmetric contract; projection roundoff follows the same convention.
LowLevelFEM.SystemMatrix — TypeSystemMatrix(A::SparseMatrixCSC{Float64}, trial::Problem, test::Problem=trial)
SystemMatrix(blocks::Matrix{SystemMatrix})
SystemMatrix(K::SystemMatrix, trial::Problem, test::Problem=trial)Sparse finite-element matrix with trial/test field metadata.
The sparse-array constructor wraps an existing matrix. Rebinding an existing SystemMatrix changes metadata while sharing its .A array; it does not copy entries. Matrix multiplication by a compatible field returns a nodal field. Symmetric(K) declares a symmetric system for solver dispatch; it does not verify the physical definiteness of the problem.
The block constructor builds a global matrix from SystemMatrix blocks. Literal zero blocks are accepted where the row/column Problems can be inferred from other blocks. .problems and .offsets record the block order.
This function assembles a global sparse matrix from a block structure where each block represents the discretization of a bilinear form between two fields (test and trial problems). The blocks are assumed to correspond to different fields in a multifield formulation.
The function performs the following steps:
Determine the ordering of trial problems from the columns of the block matrix.
Determine the ordering of test problems from the rows of the block matrix.
Verify that the block system is square in the field sense, i.e.
trial_problems[i] === test_problems[i]for all fields.
Compute global DOF offsets for each field.
Assemble the global sparse matrix by inserting the entries of each block at the appropriate offset position.
Each block blocks[i,j] must satisfy
blocks[i,j].test_model → test Problem (row space)
blocks[i,j].model → trial Problem (column space)
blocks[i,j].A → sparse block matrixThe resulting global matrix has the structure
[ A₁₁ A₁₂ ⋯ ]
[ A₂₁ A₂₂ ⋯ ]
[ ⋮ ⋮ ⋱ ]where Aᵢⱼ couples the j-th trial field with the i-th test field.
Arguments
blocks::Matrix{SystemMatrix}: Matrix of block matrices representing the bilinear operators between fields.
Returns
SystemMatrix: A global system matrix containing the assembled sparse matrix and metadata about the involvedProblems and their DOF offsets.
Errors
An error is thrown if:
- no trial or test problems are found in the block matrix,
- the block system is not square in the field sense,
- a block contains inconsistent matrix dimensions.
Example
Auu = ∫(ε(Pu) ⋅ C ⋅ ε(Pu))
Aup = ∫(Div(Pu) ⋅ Id(Pp))
Apu = ∫(Div(Pu) ⋅ Id(Pp))'
App = ∫(Grad(Pp) ⋅ Grad(Pp) * δ)
K = SystemMatrix([
Auu Aup
Apu App
])This assembles the global block system
[ Kuu Kup ]
[ Kpu Kpp ]For replacing field and test_field, use:
M = SystemMatrix(M, new_field)or
M = SystemMatrix(M, new_field, new_test_field)corresponding to a two-field problem.
LowLevelFEM.SystemVector — TypeSystemVectorGlobal right-hand-side container. .a::AbstractMatrix{Float64} has one row per DOF and one column per right-hand side or stored step.
A single-field vector has .model set and .problems === nothing. A multifield vector has .model === nothing, an ordered .problems vector, and zero-based starting .offsets into the concatenated rows. Its field order must match the corresponding SystemMatrix.
Construct through SystemVector(field) or SystemVector([f1, f2, ...]).
LowLevelFEM.subSystemMatrix — FunctionsubSystemMatrix(K::SystemMatrix, nodeTags::AbstractVector{<:Integer})Restrict a field-level system matrix to the supplied mesh nodes.
Rows are selected from the test field and columns from the trial field. The order of nodeTags is preserved, therefore the function can also be used as a permutation of the original nodal system.
The returned matrix acts on an anonymous reduced algebraic space and therefore has model === nothing and test_model === nothing.
This operation is intended for field-level SystemMatrix objects and is not defined for already assembled multifield systems.
subSystemMatrix(K::SystemMatrix, physicalName::String)Restrict a field-level system matrix to the nodes of a Gmsh physical group.
Nodes are ordered by ascending Gmsh node tag. This is the same ordering used by the contact formulation, so the returned matrix is directly compatible with contact-space operators constructed on the same physical group.
subSystemMatrix(K::SystemMatrix; onPhysicalGroup::String)Keyword form of subSystemMatrix.
Linear field solution
LowLevelFEM.solveField — FunctionsolveField(
K, rhs;
support=BoundaryCondition[],
mpc=MPC[],
coordSys=CoordinateSystem[],
solver=:auto,
preconditioner=:auto,
solveroptions=(;),
preconditioneroptions=(;)
)Solve a linear single-field finite-element system.
The solution pipeline is
prepare -> solve_linear_system -> reconstructand uses the transformation
\[u_\mathrm{global} = Q T u_\mathrm{reduced},\]
where Q is the nodal coordinate-basis transformation and T contains kinematic transformations such as reduced-order interpolation and MPCs.
Right-hand side
rhs may be a ScalarField, VectorField, TensorField, Global(...) wrapper, or a symbolic sum of local and global load terms. Multiple right-hand sides are supported columnwise. Return a nodal field of the RHS container type in global coordinates, with one solution per input column. support, mpc, and coordSys must refer to the matrix's field. Matrices and input RHS values are not overwritten by boundary-condition elimination.
With coordSys present, ordinary loads and prescribed component values are interpreted in the local solver basis. Global(...) marks right-hand-side data that are supplied in global Cartesian components.
Coordinate systems and MPCs
MPCs identify local solver components. Therefore master and slave nodes may deliberately use different local bases. In global coordinates the relation is
\[u_{g,s} = Q_s Q_m^T u_{g,m},\]
which can represent rotated periodic or sector-symmetry constraints.
With reducedOrder=true, order reduction acts on the local components. A spatially varying coordinate system can change the polynomial variation of the reconstructed Cartesian components.
Linear solvers
solver may be :auto, :backslash, :lu, :lu_no_ordering, :cholesky, :qr, :cg, :ldlt, or :gmres.
For an ordinary SystemMatrix, solver=:auto uses Julia's sparse backslash solver. For Symmetric(K), :auto attempts a Cholesky factorization first. If the constrained system is not positive definite, a warning is emitted and the solve falls back to sparse LU. Explicit solver=:cholesky never falls back.
The iterative solvers are optional extensions:
solver=:cgis intended for symmetric positive-definite systems. Withpreconditioner=:auto, a symmetric system uses incomplete Cholesky (:ich).solver=:gmresis suitable for general nonsymmetric systems. Withpreconditioner=:auto, incomplete LU (:ilu) is used.
IterativeSolvers.jl must be loaded for :cg and :gmres. The automatic :ich and :ilu preconditioners additionally require Preconditioners.jl and IncompleteLU.jl, respectively.
Use preconditioner=:none to disable preconditioning. Alternatively, a preconstructed preconditioner object may be supplied directly.
solveroptions is a NamedTuple containing native options of the selected iterative solver, for example
solveroptions=(reltol=1e-8, maxiter=5000)An iterative solver that does not converge raises LinearSolveConvergenceError, including when called from a transient solver. To accept its last iterate with a warning, explicitly pass solveroptions=(reltol=1e-8, maxiter=5000, on_failure=:warn).
The options log, Pl, Pr, and initially_zero are managed internally by LowLevelFEM. preconditioneroptions similarly contains options used when constructing the selected symbolic preconditioner. These option containers are only accepted for iterative solvers, so misspelled or irrelevant solver configuration is not ignored silently.
A practical starting point is:
| Problem / matrix type | Suggested solver | Suggested preconditioner |
|---|---|---|
| General small or medium sparse system | :backslash | none |
| Symmetric positive-definite system | :cholesky or :cg | :ich for CG |
| Large linear-elasticity system | :cg | :ich |
| General nonsymmetric system | :gmres | :ilu |
| Symmetric indefinite / saddle-point system | direct solver | none |
These are starting recommendations rather than automatic classifications. LowLevelFEM does not inspect the assembled matrix to choose an iterative method for the user.
The legacy keywords iterative and ordering are still accepted for backward compatibility. iterative=true selects conjugate gradient; ordering=false selects LU without column reordering. New code should prefer solver.
solveField(K, rhs::SystemVector; kwargs...)Solve a linear multifield finite-element system.
Full-order and reduced-order fields may be mixed in the same block system. Each field may have its own MPCs and local coordinate systems. A field using reducedOrder=true interpolates its local components before reconstructing the Cartesian result.
For a multifield system,
\[x_\mathrm{global} = Q T x_\mathrm{reduced},\]
with block-diagonal field-wise coordinate transformation Q. MPC relations are imposed on local solver components, so deliberately different master and slave bases naturally produce rotated periodic relations.
rhs may be a SystemVector, Global(rhs), or a symbolic sum containing local and global SystemVector contributions. Multiple right-hand sides are supported. Return a tuple of nodal solution fields in the K.problems block order. A one-block multifield system returns its field directly. Boundary conditions in a mixed system must identify their Problem with field=P or problem=P.
The solver interface is the same as for the single-field method. In particular, solveroptions contains native options of the selected iterative solver and preconditioneroptions contains options for a symbolic preconditioner constructed by LowLevelFEM.
Mixed and Lagrange-multiplier formulations may produce symmetric indefinite saddle-point systems. Such systems are not suitable for Cholesky or CG merely because the assembled matrix is symmetric; a direct solver is currently the recommended default unless an appropriate specialized iterative method and preconditioner are selected explicitly.
LowLevelFEM.Global — FunctionGlobal(f)Mark right-hand-side data as expressed in the global Cartesian coordinate system.
When coordSys is supplied to solveField, ordinary unwrapped loads are interpreted directly in the local solver components. Global(f) is the explicit exception: its Cartesian components are transformed to the local solver basis before the linear system is solved.
Global accepts scalar, vector and tensor fields as well as multifield SystemVectors. It can also be combined with local load terms, for example
Example
f = f_local + Global(f_gravity)e1 = VectorField(U, "right", [0.0, 1.0, 0.0])
cs = CoordinateSystem(e1)
u = solveField(
K,
Global(f);
support=support,
coordSys=[cs]
)The tutorial matrix-level workflow includes single-field, coupled-field and eigen examples. Direct solvers are available in the base package; iterative solvers and preconditioners require explicitly loaded optional packages described by solveField.
Eigenproblems
solveEigen(A,B) solves A*ϕ = λ*B*ϕ; the physical interpretation of λ depends on the chosen pencil. Dense solver=:direct has quadratic storage cost; dense_limit=1024^3 bytes guards an estimate of six full work arrays before densification. Set a larger limit explicitly, or nothing to disable the guard. This estimate is not a strict bound on backend peak memory. For vibration, convert positive λ=ω² to Hz as sqrt(λ)/(2π). A buckling multiplier is not a frequency.
LowLevelFEM.solveEigen — FunctionsolveEigen(A, B; n=6, nev=nothing, shift=nothing, sigma=nothing,
which=nothing, support=[], mpc=[], coordSys=[],
solver=:auto, solveroptions=(;), dense_limit=1024^3, normalize=:unit,
output=:field, part=:real, kwargs...)Solve A*ϕ = λ*B*ϕ for single-field or multifield problems.
By default return one standard nodal Field per Problem (as solveField does), with columns representing mode shapes and field.t holding the real or imaginary parts of the eigenvalues. part=:real, :imag, or :both selects components; :both returns the two Fields consecutively for each Problem.
With output=:raw, return (λ, ϕ) with the complete real/complex generalized eigenpairs. part is ignored in this mode. Eigenpairs are ordered by increasing real part of λ (then imaginary part).
Selection modes
shift=lo: Return the firstneigenpairs withreal(λ) > lo. For ARPACK, this one-sided selection is currently implemented only for real symmetric pencils with positive-definite B. Usesolver=:directfor other pencils.sigma=s, which=:LM: Native ARPACK shift-invert selection; modes on both sides ofsmay be included.whichandsigmaretain ARPACK semantics.- Neither
shiftnorsigma:which=:SRby default (smallest real part). For large positive elastic systems,shift=0.0is usually faster.
Use n or its alias nev for the number of eigenpairs. The original ARPACK keywords ncv, tol, maxiter, v0, check, explicittransform, which and sigma can be passed directly, or in solveroptions=(; ...). ritzvec=false is unsupported because eigenvectors are always returned.
Solvers and normalization
solver=:direct uses a dense generalized eigensolve of the reduced matrices. :arpack requires using Arpack; :auto selects direct solution for reduced size at most 32 or near-full mode requests, and ARPACK otherwise. No optional package is loaded automatically. Dense solution estimates six full matrix work arrays and rejects estimates above dense_limit=1024^3 bytes before densifying. Increase the limit explicitly or use dense_limit=nothing to disable the guard. Unshifted :SR also supports indefinite/nonsymmetric pencils; use shift=0.0 explicitly for faster positive-spectrum searches when its assumptions hold. The strict shift bound is not a physical rigid-mode tolerance: supply a positive cutoff when roundoff near zero must be excluded.
normalize=:none retains reconstructed eigenvectors; :unit gives unit Euclidean norm; :mass and its alias :B normalize using the full B matrix. The latter requires an appropriate positive modal B-norm. Normalized modes have their largest-magnitude component real and positive. Repeated eigenspaces may still have different bases; normalize=:none preserves the backend phase.
Single-field output=:field returns one field (or a real/imaginary pair for part=:both). Multifield output is a tuple in block order. Raw eigenvectors are columns in the original global DOF order after constraint reconstruction. A one-block system also returns its sole field directly. An eigenvalue is a frequency squared, buckling multiplier, or another physical quantity only according to the chosen matrix pencil; no conversion to Hz is performed automatically.
Coordinates, boundary conditions and MPCs share the solveField reduction. Essential constraints for eigenmodes must be homogeneous. Consult the shared solver/basis restrictions when combining spectral interpolation and MPCs.
LowLevelFEM.solveEigenProblem — FunctionsolveEigenProblem(A, B; shift=0.0, directSolver=false, kwargs...)Backward-compatible alias. The historical shift means the ARPACK numerical shift (sigma), not the solveEigen lower spectral bound. Additional keywords, including native ARPACK which, are forwarded to solveEigen. Prefer that interface for new code.
LowLevelFEM.eigenValue — FunctioneigenValue(u::Union{ScalarField,VectorField,TensorField}; n=1)Return the stored real or imaginary part of the n-th eigenvalue, as Float64. Only Fields marked :eigen_real or :eigen_imag are accepted. For complex eigenvalues, use part=:both to retain both parts separately.
LowLevelFEM.eigenVector — FunctioneigenVector(u::Union{ScalarField,VectorField,TensorField}; n=1)Extract one mode as a single-step Field of the same type and representation. The selected eigenvalue component remains in t[1], and kind is preserved.
LowLevelFEM.showEigenResults — FunctionshowEigenResults(u; name=:eigen, visible=false, ff=2, factor=0)Display the modes of an eigenmode Field in a Gmsh view. Each stored column is a mode; its (real-valued) eigenvalue component is shown via the Field's t data. ff=1 and ff=2 display mode shapes as displacements with eigenvalue labels; ff=0 selects an ordinary vector/field view with time labels. The default ff=2 uses eigenvalue labeling and displacement visualization. Returns the Gmsh view tag.
showEigenResults(fields::Tuple; name=:eigen, visible=false, ff=2, factor=0)Create one Gmsh view for each Field in a multifield eigenresult tuple. Returns a tuple of view tags in the same order as the input Fields.
LowLevelFEM.getEigenValues — FunctiongetEigenValues(u::VectorField)Return the eigenvalues stored in a VectorField.
Supports real and imaginary eigenvalue fields.
LowLevelFEM.mapEigenValues — FunctionmapEigenValues(f, u::VectorField)Apply the f function to the eigenvalues stored in a vector field.
Return a new field with transformed eigenvalues, preserving the eigenvectors, their order, and the field metadata. The original field remains unchanged.
mapEigenValues currently accepts VectorField eigenresults; it does not have scalar/tensor overloads. For other field types, extract values with eigenValue or request output=:raw.
Normalized eigenvectors have their largest-magnitude component real and positive; normalize=:none keeps the backend phase. Repeated eigenspaces can still have different bases. The unshifted default which=:SR applies to general pencils. For a symmetric positive spectrum, explicit shift=0.0 usually converges faster. shift is a strict numerical lower bound, not a physical rigid-mode filter: choose a positive cutoff to exclude zero-mode roundoff. Shift-invert regularization is placed below the requested bound and requests additional candidates when necessary, retaining modes just above it.
See Linear Buckling and Prestressed Natural Frequencies for a complete mechanical application. Engineering mechanical eigen helpers and their existing result containers are documented under Linear API.
Interpolation-space transformations
Field storage remains in Gmsh/Lagrange coordinates even when the solver uses a reduced or spectral basis. These are advanced transformation APIs; the ordinary solver constructs and applies its required transformations automatically.
LowLevelFEM.reductionMatrices — FunctionreductionMatrices(P::Problem) -> T, RConstruct sparse transformation matrices for reducing the polynomial order of a C0 Lagrange finite element field from order p to p - 1.
The returned matrices satisfy
u_full = T * u_reduced
u_reduced = R * u_full
K_reduced = T' * K * Tfor fields representable in the reduced space.
The transformation is constructed from the Gmsh Lagrange basis functions. All element types belonging to the problem must have the same polynomial order. An error is thrown for first-order meshes.
The matrices are expanded automatically according to P.pdim.
Example
T, R = reductionMatrices(problem)
LowLevelFEM.reduced_bc_data — Functionreduced_bc_data(R, fixed, uD)Convert full-space Dirichlet data to the reduced finite element space.
A reduced DOF is considered constrained if its restriction row depends exclusively on constrained full-space DOFs.
Returns
free_r, fixed_r, uD_rwhere uD_r contains the prescribed values at the reduced DOFs.
LowLevelFEM.spectralTransformation — FunctionspectralTransformation(P::Problem; details=false, check=false)Return a Legendre-Gauss-Lobatto spectral basis transformation for P.
For basis=:spectral, the transformation and spectral mesh metadata are built when the Problem is initialized and reused here. The ordinary LowLevelFEM/Gmsh Lagrange representation remains the global storage space:
u_global = T * u_spectral
u_spectral = R * u_globaland an assembled system is projected as
K_spectral = T' * K * T
f_spectral = T' * fThe transformation matrices are assembled directly in CSC format; no global Dict{Tuple{Int,Int},...} or I/J/V sparse construction is used.
Current limitations
- 1D
Lineand complete tensor-product 2DQuadrangleelements are supported, - triangular spectral elements are not yet implemented,
- all domain elements must have the same polynomial order,
basis=:spectral, reducedOrder=trueis reserved by the API but not yet implemented,- spectral basis combined with MPCs is not yet implemented by the solver.
Keyword arguments
details=false: return only(T, R).details=true: return a named tuple with cached transformation and spectral mesh information.check=false: iftrue, verifyR*T ≈ I.
Calling spectralTransformation on a non-spectral Problem remains supported as an explicit diagnostic utility; in that case the result is built on demand and is not cached in the Problem.
Reduced quadrature (reduced(expr)) is distinct from reduced interpolation (reducedOrder=true). Spectral support currently covers lines and complete quadrangles; consult spectralTransformation for unsupported combinations.
Transient integration
The Time Integration guide contains the full HHT/CDM/FDM workflow, keyword tables, support histories, solver choices and time-step selection. The function references are HHT, CDM and FDM.
| Method | System | Main choice |
|---|---|---|
| HHT | Second order | Implicit dynamics and algorithmic damping. |
| CDM | Second order | Explicit displacement updates and a stability-limited step. |
| FDM | First order | Theta integration for diffusion/heat and other first-order systems. |
All three share coordinate, approximation and MPC preparation. Initial fields have one column; support supplies each prescribed history once. Results are global nodal fields at t0+(j-1)*Δt, including the initial sample.
Operator modifications and nonlinear iteration
See Operator updates and nonlinear iteration for modifyA2, modifyA1, modifyA0, modifyRHS, callback state members and nonlinear tolerances. Each callback defaults to nothing. HHT/FDM iterate within a step; CDM keeps explicit displacement updates.
First-order accuracy analysis
LowLevelFEM.FDMaccuracyAnalysis — FunctionFDMaccuracyAnalysis(λmin, λmax, Δt; type=:SR, n=100, ϑ=0.5)Evaluate the theta-method amplification factor for FDM.
Arguments
| Argument | Meaning |
|---|---|
λmin, λmax | Nonnegative real interval from K*ϕ=λ*C*ϕ. |
Δt | Finite positive candidate time increment. |
Keyword arguments
| Keyword | Default | Meaning |
|---|---|---|
type | :SR | Spectral-radius analysis; the only supported choice. |
n | 100 | Number of eigenvalue samples; at least 2. |
ϑ | 0.5 | Theta weight in [0,1], matching the integration run. |
Returns and interpretation
Return (x,radius) vectors, with x=λ*Δt and radius=abs((1-(1-ϑ)*x)/(1+ϑ*x)). Values above one indicate modal growth. For ϑ<0.5, the nonnegative-real stability boundary is λmax*Δt < 2/(1-2ϑ). Complex spectra require a full stability-region check.
x, radius = FDMaccuracyAnalysis(0.0, λmax, Δt; ϑ=0.5)Transient preparation helpers
These lower-level helpers implement the shared preparation/reconstruction; ordinary applications call HHT, CDM or FDM directly.
LowLevelFEM.prepare_transient_system — Functionprepare_transient_system(K, M, C, rhs, U0, V0, n, Δt; ...)Common coordinate/approximation/MPC preparation for all transient methods. M and V0 may be nothing for a first-order system. Matrices and input fields are never modified. Dirichlet values are transferred through the same MPC and approximation helpers as solveField and solveEigen. U0 and V0 contain one initial column. All prescribed primary-variable histories come from support; the integrator determines their derivatives.
LowLevelFEM.reconstruct_transient_solution — Functionreconstruct_transient_solution(U, D, prepared)Insert free values U and constrained values D, prolong through T, rotate through Q, and return ordinary nodal Fields with physical time labels. Multifield output follows the matrix block order.
Iterative convergence
An unconverged CG or GMRES solve raises LinearSolveConvergenceError by default. The exception exposes solver, iterations, and the true residual_norm. This also stops HHT and FDM when an inner linear solve fails.
Use solveroptions=(reltol=1e-8, maxiter=5000, on_failure=:warn) only when you explicitly want a warning and the last iterate instead.
LowLevelFEM.LinearSolveConvergenceError — TypeLinearSolveConvergenceErrorAn iterative linear solver stopped before convergence. The fields solver, iterations, and residual_norm record the backend, completed iteration count, and final true residual norm norm(A*x-b).
By default solveField, HHT and FDM propagate this error rather than accepting an unconverged linear solution. Set solveroptions=(on_failure=:warn, ...) explicitly to warn and return the last iterate instead.