Engineering Heat API
Problem-oriented heat matrices, loads and solvers form the engineering API. Their names are intended to remain while dedicated kernels are migrated to DSL-backed wrappers. Current implementations still use dedicated heat assembly. For custom diffusion/heat forms, Grad and weak-form assembly and solveField are available directly. Existing transient routines remain documented below; see API layers.
Heat Assembly
LowLevelFEM.heatConductionMatrix — FunctionheatConductionMatrix(problem::Problem)Solves the heat conduction matrix of the problem.
Returns: heatCondMat
Types:
problem: ProblemheatCondMat: SystemMatrix
Examples
Kth = heatConductionMatrix(problem)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.heatCapacityMatrix — FunctionheatCapacityMatrix(problem::Problem; lumped=false)Solves the heat capacity matrix of the problem. If lumped is true, solves lumped heat capacity matrix.
Return: heatCapMat
Types:
problem: Problemlumped: BooleanmassMat: 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.latentHeatMatrix — FunctionlatentHeatMatrix(u::VectorField,
v::VectorField,
T0::ScalarField)Solves the latent heat matrix of the problem. With this matrix the generated heat due to deformations (given with displacement field u and velocity field v) can be solved. T0 is the current temperature field which is given in absolute temperature scale (Kelvin).
Return: latHeatMat
Types:
problem: Problemu: VectorFieldv: VectorFieldT0: ScalarFieldlatHeatMat: SystemMatrix
LowLevelFEM.heatConvectionMatrix — FunctionheatConvectionMatrix(problem, heatConvection)Solves the heat convection matrix of the problem. heatConvection is a vector of heat convection boundary condicions defined in function heatConduction. With the heat convection vector (see the heatConvectionVector function) heatConvVec, temperature field vector T in hand the heat flux vector qCV arising from the heat convection boundary condition can be solved. qCV = heatConvMat * T - heatConvVec
Return: heatConvMat
Types:
problem: ProblemheatConvection: Vector{Tuple{String, Float64, Float64, Float64}}heatConvMat: SystemMatrix
LowLevelFEM.heatConvectionVector — FunctionheatConvectionVector(problem, heatConvection)Solves a heat convection vector of problem. heatConvection is a vector of heat convection boundary condicions defined in function heatConduction. With the heat convection matrix (see the heatConvectionMatrix function) heatConvMat, temperature field vector T in hand the heat flux vector qCV arising from the heat convection boundary condition can be solved. qCV = heatConvMat * T - heatConvVec
Return: heatConvVec
Types:
problem: ProblemheatConvection: Vector{Tuple{String, Float64, Float64, Float64}}heatConvVec: ScalarField
LowLevelFEM.heatFluxVector — FunctionheatFluxVector(problem::Problem, heatFlux::Vector{LoadCondition})Solves a heat flux or heat source vector of problem. heatFlux is a tuple of name of physical group name, heat flux qn normal to the surface of the body. The outward direction is positive. It can solve heat flux (or heat source) depending on the problem.
- In case of 2D problems and Point physical group means concentrated heat flux.
- In case of 2D problems and Line physical group means surface heat flux.
- In case of 2D problems and Surface physical group means body heat source.
- In case of 3D problems and Point physical group means concentrated heat flux.
- In case of 3D problems and Line physical group means edge heat source.
- In case of 3D problems and Surface physical group means surface heat flux.
- In case of 3D problems and Volume physical group means body heat source.
Return: heatFluxVec
Types:
problem: ProblemheatFlux: Vector{Tuple{String, Float64, Float64, Float64}}heatFluxVec: VectorField
LowLevelFEM.heatSourceVector — FunctionheatSourceVector(problem::Problem, heatSource::Vector{LoadCondition})Solves a heat flux or heat source vector of problem. heatSource is a tuple of name of physical group name, heat flux qn normal to the surface of the body. The outward direction is positive. It can solve heat flux (or heat source) depending on the problem.
- In case of 2D problems and Point physical group means concentrated heat flux.
- In case of 2D problems and Line physical group means surface heat flux.
- In case of 2D problems and Surface physical group means body heat source.
- In case of 3D problems and Point physical group means concentrated heat flux.
- In case of 3D problems and Line physical group means edge heat source.
- In case of 3D problems and Surface physical group means surface heat flux.
- In case of 3D problems and Volume physical group means body heat source.
Same as the heatFluxVector function.
Return: heatSourceVec
Types:
problem: ProblemheatSource: Vector{Tuple{String, Float64, Float64, Float64}}heatSourceVec: VectorField
LowLevelFEM.thermalLoadVector — FunctionthermalLoadVector(problem::Problem,
T::ScalarField;
T₀=ScalarField([], zeros(problem.non, 1), [0], [], 1, :scalar, problem))Solves the thermal load vector from a temperature field T for problem problem. T₀ is the initial temperature field. problem is an elastic problem.
Return: thermLoadVec
Types:
problem: ProblemT: ScalarFieldT₀: ScalarFieldthermLoadVec: VectorField
LowLevelFEM.applyHeatConvection! — FunctionapplyHeatConvection!(heatCondMat, heatFluxVec, heatConv)Applies heat convectiom boundary conditions heatConv on a heat conduction matrix heatCondMat and heat flux vector heatFluxVec. Mesh details are in problem. heatConv is a tuple of name of physical group and prescribed heat transfer coefficient h and ambient temperature Tₐ. The ambient temperature can be either a constant or a function of x, y and z coordinates.
Returns: nothing
Types:
problem: ProblemheatCondMat: SystemMatrixheatFluxVec: VectorFieldheatConv: Vector{Tuple{String, Float64, Float64, Float64}}
Heat Solvers and Initial Conditions
LowLevelFEM.solveTemperature — FunctionsolveTemperature(K::SystemMatrix,
q::ScalarField;
temperatureConstraint=Vector{BoundaryCondition}())Solves the linear heat conduction problem
K * T = qfor the temperature field T, where K is the assembled heat conduction matrix and q is the heat flux (load) vector. Essential temperature constraints (Dirichlet-type boundary conditions) are imposed via temperatureConstraint.
This is a low-level temperature solver operating directly on a preassembled [SystemMatrix] and a heat flux [ScalarField]. It assumes that the system matrix already contains all material contributions.
Arguments
K::SystemMatrix: Assembled heat conduction matrix associated with a [Problem].q::ScalarField: Heat flux vector (right-hand side of the heat equation).temperatureConstraint::Vector{BoundaryCondition}(keyword, optional): Prescribed temperature constraints (Dirichlet boundary conditions). Default is an empty vector (no temperature constraints).
Returns
T::ScalarField: Temperature field satisfying the prescribed constraints.
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
solveTemperature(problem; ...)interface.
solveTemperature(problem::Problem;
heatFlux::Vector{LoadCondition}=LoadCondition[],
temperatureConstraint::Vector{BoundaryCondition}=BoundaryCondition[],
heatConvection::Vector{BoundaryCondition}=BoundaryCondition[])Computes the temperature field T for a given [Problem] subject to prescribed heat fluxes, temperature constraints, and optional heat convection boundary conditions.
The heat conduction matrix and load vector are assembled internally. Heat convection terms, if present, are incorporated into the system before solving.
This is the high-level, user-facing temperature solver.
Arguments
problem::Problem: Finite element heat transfer problem definition.heatFlux::Vector{BoundaryCondition}(keyword, optional): Prescribed heat flux boundary conditions.temperatureConstraint::Vector{BoundaryCondition}(keyword, optional): Prescribed temperature constraints (Dirichlet boundary conditions).heatConvection::Vector{BoundaryCondition}(keyword, optional): Heat convection boundary conditions contributing to both the system matrix and the load vector.
Returns
T::ScalarField: Temperature field defined on the problem degrees of freedom.
Notes
- Temperature constraints are enforced by eliminating constrained degrees of freedom from the linear system.
- Heat convection terms are added to the conduction matrix and load vector via
applyHeatConvection!. - This function internally assembles the heat conduction matrix and heat flux vector, then solves the reduced linear system.
solveTemperature(problem::Problem, u::VectorField; T0=273.0)Solves the raise of temperature T during reversible (no dissipation) elastic deformations, where u is the displacement field, and problem is a heat cunduction problem.
Return: T
Types:
problem: Problemu: VectorFieldT0: Float64T: ScalarField
LowLevelFEM.solveHeatFlux — FunctionsolveHeatFlux(T; DoFResults=false)Solves the heat flux field q from temperature vector T. heat flux 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, q is a matrix with nodal results. In this case showDoFResults can be used to show the results (otherwise showHeatFluxResults or showElementResults).
Return: q
Types:
problem: ProblemT: ScalarFieldq: VectorField
LowLevelFEM.initialTemperature — FunctioninitialTemperature(problem::Problem, name::String; T=nothing)Sets the temperature value T at nodes belonging to physical group name. Returns the T0 initial nodal temperature vector.
Return: T0
Types:
problem: Problemname: StringT: Float64T0: ScalarField
LowLevelFEM.initialTemperature! — FunctioninitialTemperature!(T0::ScalarField,
name::String;
T=nothing)Changes the tempetature value to T at nodes belonging to physical group name. Original values are in temperature vector T0.
Returns: nothing
Types:
name: StringT0: ScalarFieldT: Float64
Time Integration
The Time Integration guide explains FDM inputs, theta choices, all keyword defaults and choosing Δt. The same method also accepts general first-order scalar/vector/tensor or multifield systems. Here C denotes heat capacity (A1), while K denotes conduction (A0).
LowLevelFEM.FDM — FunctionFDM(K, C, q, X0, n, Δt; kwargs...)Integrate a first-order system with the theta method:
\[C\dot{x} + Kx = q.\]
Arguments
| Argument | Meaning |
|---|---|
K, C | Primary-field and first-derivative/capacity operators; single- or multifield matrices. |
q | Constant or sampled RHS Field, SystemVector, tuple or local/global sum. |
X0 | Initial primary field, one column, on free coordinates. |
n, Δt | Sample count (n ≥ 2, including the initial sample) and positive constant increment. |
The positional-support alias FDM(K,C,q,bc,X0,n,Δt) is retained. Here C is capacity/first-derivative data, whereas it denotes damping in HHT/CDM.
Theta parameter
| Keyword | Default | Meaning |
|---|---|---|
ϑ | 0.5 | Endpoint weight in [0,1]; choices below. |
ϑ | Scheme | Time accuracy for smooth solutions |
|---|---|---|
0.0 | Explicit Euler | First order; conditionally stable. |
0.5 | Crank–Nicolson | Second order. |
1.0 | Backward Euler | First order; strong decay of stiff modes. |
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 capacity coupling includes the complete increment -C_fc*(d[j+1]-d[j])/Δt; all histories are supplied through support.
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.
For constant operators the effective free matrix is C_ff + ϑ*Δt*K_ff. Wrap both operators in Symmetric(...) for the symmetric automatic path.
Operator updates and nonlinear iteration
| Keyword | Default | Updated quantity |
|---|---|---|
modifyA1 | nothing | A1=C: first-derivative/capacity operator. |
modifyA0 | nothing | A0=K: primary-field operator or tangent. |
modifyRHS | nothing | RHS at the trial endpoint. |
modifyA2 | nothing | Reserved: any value other than nothing is rejected by FDM. |
copyOperators | true | Copy matrix callback inputs; false borrows them read-only. |
nonlinearoptions | (;) | Nonlinear iteration controls listed below. |
FDM reevaluates callbacks within each step. It interpolates capacity as A1θ=(1-ϑ)*A1_old+ϑ*A1_new and uses each endpoint's own A0*x-rhs. There is no second-derivative operator.
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.
At FDM initialization both derivative entries in state are nothing; a first derivative is available during step iterations. The same coordinate, reduced-order and SEM restrictions as in HHT apply.
Returns
Return a global nodal Field x with n columns at t0 + (j-1)*Δt. A multifield result is a tuple in matrix block order: x1,x2 = FDM(...).
Choosing the time step
For a linear diffusion-type pencil K*ϕ=λ*C*ϕ with real nonnegative eigenvalues:
ϑ ≥ 0.5: unconditionally stable, butΔtstill controls accuracy.ϑ < 0.5: requireΔt < 2/((1-2ϑ)*λmax)with a safety margin.
For complex/nonsymmetric spectra, assess the full stability region instead. Crank–Nicolson may alternate stiff modes when λ*Δt is large; backward Euler damps them more strongly. Resolve the fastest decay/forcing of interest and halve Δt to check accuracy. See FDMaccuracyAnalysis.
Example
x = FDM(K, C, q, x0, n, Δt; support=bc, ϑ=0.5)
x = FDM(Symmetric(K), Symmetric(C), q, x0, n, Δt;
support=bc, ϑ=1.0, solver=:cholesky)