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 — Function
heatConductionMatrix(problem::Problem)

Solves the heat conduction matrix of the problem.

Returns: heatCondMat

Types:

  • problem: Problem
  • heatCondMat: 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 ∫.

source
LowLevelFEM.heatCapacityMatrix — Function
heatCapacityMatrix(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: Problem
  • lumped: Boolean
  • massMat: SystemMatrix

Element selection

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

source
LowLevelFEM.latentHeatMatrix — Function
latentHeatMatrix(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: Problem
  • u: VectorField
  • v: VectorField
  • T0: ScalarField
  • latHeatMat: SystemMatrix
source
LowLevelFEM.heatConvectionMatrix — Function
heatConvectionMatrix(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: Problem
  • heatConvection: Vector{Tuple{String, Float64, Float64, Float64}}
  • heatConvMat: SystemMatrix
source
LowLevelFEM.heatConvectionVector — Function
heatConvectionVector(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: Problem
  • heatConvection: Vector{Tuple{String, Float64, Float64, Float64}}
  • heatConvVec: ScalarField
source
LowLevelFEM.heatFluxVector — Function
heatFluxVector(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: Problem
  • heatFlux: Vector{Tuple{String, Float64, Float64, Float64}}
  • heatFluxVec: VectorField
source
LowLevelFEM.heatSourceVector — Function
heatSourceVector(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: Problem
  • heatSource: Vector{Tuple{String, Float64, Float64, Float64}}
  • heatSourceVec: VectorField
source
LowLevelFEM.thermalLoadVector — Function
thermalLoadVector(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: Problem
  • T: ScalarField
  • T₀: ScalarField
  • thermLoadVec: VectorField
source
LowLevelFEM.applyHeatConvection! — Function
applyHeatConvection!(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: Problem
  • heatCondMat: SystemMatrix
  • heatFluxVec: VectorField
  • heatConv: Vector{Tuple{String, Float64, Float64, Float64}}
source

Heat Solvers and Initial Conditions

LowLevelFEM.solveTemperature — Function
solveTemperature(K::SystemMatrix, 
                 q::ScalarField; 
                 temperatureConstraint=Vector{BoundaryCondition}())

Solves the linear heat conduction problem

K * T = q

for 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.
source
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.
source
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: Problem
  • u: VectorField
  • T0: Float64
  • T: ScalarField
source
LowLevelFEM.solveHeatFlux — Function
solveHeatFlux(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: Problem
  • T: ScalarField
  • q: VectorField
source
LowLevelFEM.initialTemperature — Function
initialTemperature(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: Problem
  • name: String
  • T: Float64
  • T0: ScalarField
source
LowLevelFEM.initialTemperature! — Function
initialTemperature!(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: String
  • T0: ScalarField
  • T: Float64
source

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 — Function
FDM(K, C, q, X0, n, Δt; kwargs...)

Integrate a first-order system with the theta method:

\[C\dot{x} + Kx = q.\]

Arguments

ArgumentMeaning
K, CPrimary-field and first-derivative/capacity operators; single- or multifield matrices.
qConstant or sampled RHS Field, SystemVector, tuple or local/global sum.
X0Initial primary field, one column, on free coordinates.
n, ΔtSample 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

KeywordDefaultMeaning
ϑ0.5Endpoint weight in [0,1]; choices below.
ϑSchemeTime accuracy for smooth solutions
0.0Explicit EulerFirst order; conditionally stable.
0.5Crank–NicolsonSecond order.
1.0Backward EulerFirst order; strong decay of stiff modes.

Data, constraints and coordinates

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

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

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

Prescribed capacity coupling includes the complete increment -C_fc*(d[j+1]-d[j])/Δt; all histories are supplied through support.

Linear solver options

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

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

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

KeywordDefaultUpdated quantity
modifyA1nothingA1=C: first-derivative/capacity operator.
modifyA0nothingA0=K: primary-field operator or tangent.
modifyRHSnothingRHS at the trial endpoint.
modifyA2nothingReserved: any value other than nothing is rejected by FDM.
copyOperatorstrueCopy 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 memberDefaultMeaning
maxiter30Maximum nonlinear updates; positive integer.
reltol1e-9Relative residual tolerance; nonnegative.
abstol1e-11Absolute residual tolerance, in equilibrium-equation units; nonnegative.
relaxation1.0Fraction of each correction, in (0,1].

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

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 Δt still 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)
source