Boundary Conditions, MPC and Coordinates
For modern DSL models, assemble natural loads with ∫; pass essential conditions to solveField/solveEigen. In a mixed model, bind each condition to its unknown with field=P.
Conditions and DOF selection
LowLevelFEM.BoundaryCondition — TypeBoundaryCondition(phName::String; field=nothing, problem=field, kwargs...)General container type for prescribing boundary conditions in LowLevelFEM.
phNameis a Gmsh physical group name.problemoptionally binds the condition to a specific field (required for multi-field).fieldalias forproblemvaluesstores component-wise boundary condition data, such asux,uy,T,exx, etc., asNumber,Function, orScalarField.
BoundaryCondition unifies all Dirichlet- and Neumann-type boundary data (mechanical, thermal, elastic, convective, etc.) into a single, extensible structure. A boundary condition always refers to a physical group of the mesh (e.g. "left", "right", "wall") and may prescribe several components of its associated field.
The same BoundaryCondition type is used consistently across:
- static and transient solid mechanics
- modal and buckling analysis
- heat conduction and thermo-mechanical problems
Boundary conditions are typically passed as Vector{BoundaryCondition} to assembly, load, and solver routines.
Prescribed fields
Mechanical (solid mechanics)
Dirichlet-type (essential)
ux, uy, uz: prescribed displacement componentsp: prescribed pressure (if applicable)
Neumann-type (natural)
fx, fy, fz: prescribed surface forces / tractions
Elastic (Robin-type)
kx, ky, kz: elastic support (spring stiffness per displacement component)
Thermal
Dirichlet-type
T: prescribed temperature
Neumann-type
q: prescribed heat fluxqn: prescribed normal heat flux
Convection (Robin-type)
h: heat transfer coefficientT: ambient temperature (used together withh)
Poisson-type problems
Dirichlet-type
p: prescribed field
Neumann-type
q: prescribed force
For heat convection, the field T is interpreted as ambient temperature. This is intentional and handled consistently by the heat assembly routines.
Value types
Each field may be specified as:
- a scalar number (
Number) - a
ScalarField - a function
(x,y,z) -> value
depending on the context and the assembly routine using it.
Usage pattern
It is recommended to:
- use separate
BoundaryConditionobjects for conceptually different constraints (e.g. displacement support vs. load), - and collect them in a vector:
bc = [
displacementConstraint("left", ux=0.0, uy=0.0),
load("right", fx=1.0),
temperatureConstraint("wall", T=300.0)
]Notes
- Only the fields relevant to a given analysis are accessed; unused fields may safely remain
nothing. - The container stores keyword/value pairs; it does not validate every physical combination. The consuming solver or assembly routine determines which components are meaningful.
- For generic DSL fields, component keys follow
P.fieldandP.rhs_field. Usefield=Pin a mixed problem to identify the constrained unknown. - DSL natural loads are assembled as linear forms with
∫; storing a load in aBoundaryConditionalone does not assemble it. - With local solver coordinates, prescribed components are local. Use
Globalto mark a Cartesian right-hand side.
See also:
displacementConstraintloadelasticSupporttemperatureConstraintheatFluxheatConvection
LowLevelFEM.BoundaryConditionFields — FunctionBoundaryConditionFields(bc::BoundaryCondition)Return the defined field keys of a boundary condition.
Arguments
bc::BoundaryCondition: Boundary condition object with named values.
Returns
- An iterator over
Symbolkeys present inbc.values.
Example
keys = BoundaryConditionFields(bc)LowLevelFEM.constrainedDoFs — FunctionconstrainedDoFs(problem::Problem, supports::Vector{BoundaryCondition})Returns the serial numbers of constrained degrees of freedom. Support is a vector of boundary conditions given with the function displacementConstraint.
Return: DoFs
Types:
problem: Problemsupports: Vector{BoundaryCondition}DoFs: Vector{Int64}
constrainedDoFs(K::SystemMatrix,
support::Vector{BoundaryCondition})Return global constrained DOFs for single- or multi-field systems.
LowLevelFEM.freeDoFs — FunctionfreeDoFs(problem, supports)Returns the serial numbers of unconstrained degrees of freedom. Support is a vector of boundary conditions given with the function displacementConstraint.
Return: DoFs
Types:
problem: Problemsupports: Vector{BoundaryCondition}DoFs: Vector{Int64}
freeDoFs(K::SystemMatrix,
support::Vector{BoundaryCondition})Return global free DOFs for single- or multi-field systems.
LowLevelFEM.allDoFs — FunctionallDoFs(problem)Returns the serial numbers of degrees of freedom of the whole model.
Return: DoFs
Types:
problem: ProblemDoFs: Vector{Int64}
LowLevelFEM.ndofs — Functionndofs(problem::Problem)Return total number of dofs for a single-field problem.
Multi-point constraints
Detailed construction, rigid links, and periodic examples are in Multifield: Multi-point constraints.
LowLevelFEM.MultiPointConstraint — TypeMultiPointConstraint(; master::String, slave::String,
field=nothing, problem=field, kwargs...)
MPC(; master::String, slave::String,
field=nothing, problem=field, kwargs...)Define a multi-point constraint between master and slave physical groups.
MPC is a shorthand alias for MultiPointConstraint.
The constraint identifies corresponding degrees of freedom on the master and slave physical groups. The constrained components can be selected individually using Boolean keyword arguments.
If no component keyword is specified, all components of the associated field are constrained.
Arguments
master::String: Name of the Gmsh physical group containing the master node(s).slave::String: Name of the Gmsh physical group containing the slave node(s).
Keyword Arguments
field: Field (Problem) to which the constraint belongs. This is required when MPCs are used in multifield systems.problem: Backward-compatible alias forfield.kwargs...: Boolean component selectors. Component names follow the field name and its components, for exampleux,uy,uz,φ,φx,φy,φz.A value of
trueconstrains the corresponding component, whilefalseleaves it unconstrained.
Behavior
Two types of coupling are supported.
Single-master coupling
If the master physical group contains a single node, all selected slave degrees of freedom are tied to that master node. This can be used for remote-point-type constraints.
Periodic coupling
If the master and slave physical groups contain multiple nodes, the correspondence is obtained from the periodic node mapping stored in the Gmsh model.
Periodic pairing must therefore be defined in Gmsh before constructing the constraint.
Examples
Tie all displacement components of a boundary to a remote point:
mpc = MPC(
master="remote",
slave="right",
field=U
)Constrain only selected components:
mpc = MPC(
master="remote",
slave="right",
field=U,
ux=true,
uy=true,
uz=false
)Periodic displacement coupling:
periodic = MPC(
master="right",
slave="left",
field=U
)
u = solveField(
K,
f;
support=[bc],
mpc=[periodic]
)Notes
MPC relations may be chained. During solution, chained constraints are resolved so that each constrained degree of freedom points directly to its final master degree of freedom.
LowLevelFEM.MPC — TypeMPCAlias for MultiPointConstraint.
MPC can be used as a shorter name when defining multi-point constraints. Both names refer to exactly the same type.
MPC is an alias of MultiPointConstraint. The rigid-rotation and collapse helpers are documented with multifield assembly.
Local coordinates
LowLevelFEM.CoordinateSystem — TypeCoordinateSystem(e1::VectorField; handedness=:right)
CoordinateSystem(e1::VectorField, e2::VectorField; handedness=:right)Define a local orthonormal coordinate system from direction VectorFields.
The direction fields may contain constant or spatially varying components and their finite-element support determines where the local coordinate system is active. The same CoordinateSystem object can be used by solveField, rotateResult, and rotateNodes.
In 2D, only e1 is supplied. It defines the first local basis direction. The second direction is generated automatically. For handedness=:right,
\[\mathbf e_2 = (-e_{1y}, e_{1x}),\]
while handedness=:left reverses this direction.
In 3D, both e1 and e2 are required. e1 is normalized and e2 defines the local 1-2 plane. During construction of the transformation, e2 is orthogonalized against e1 and normalized. The third basis direction is
\[\mathbf e_3 = \mathbf e_1 \times \mathbf e_2\]
for handedness=:right, and the cross-product order is reversed for handedness=:left.
Arguments
e1::VectorField: first local basis direction.e2::VectorField: second reference direction; required in 3D and not allowed in 2D.handedness::Symbol::right(default) or:left.
Notes
The direction fields must contain exactly one time step and must belong to the same Problem. Multiple coordinate systems with disjoint support can be combined in solveField and rotateResult.
Examples
# 2D polar basis on a region called "body"
er = VectorField(U, "body", [(x, y, z) -> x, (x, y, z) -> y, 0.0])
cs = CoordinateSystem(er)
# 3D cylindrical basis
ex = VectorField(U, "body", [(x, y, z) -> x, (x, y, z) -> y, 0.0])
ez = VectorField(U, "body", [0.0, 0.0, 1.0])
cs = CoordinateSystem(ex, ez)
Q = rotateNodes(U, cs)LowLevelFEM.Transformation — TypeTransformation(T::SparseMatrixCSC{Float64}, non::Int64, dim::Int64)Structure containing the transformation matrix T at each node in the FE mesh, the number of nodes non, and the problem dimension dim.
Types:
T: SparseMatrixCSC{Float64}non: Int64dim: Int64
LowLevelFEM.rotateNodes — FunctionrotateNodes(problem::Problem, coordSys::CoordinateSystem)
rotateNodes(problem::Problem, phName::String, coordSys::CoordinateSystem)Build the nodal transformation matrix associated with coordSys.
The returned Transformation maps local vector components to global Cartesian components at the active nodes. The coordinate system is evaluated with the same backend used by solveField and rotateResult.
In the two-argument form, the active nodes are determined directly by the support of the direction fields stored in coordSys.
The three-argument form is retained for compatibility with existing rotateNodes workflows. In this form phName is checked against the support of the coordinate system; the physical group and the coordinate-system support must contain the same mesh nodes.
Arguments
problem::Problem: finite-element field whose nodal components are transformed.phName::String: optional Gmsh physical-group name used to verify the active node set.coordSys::CoordinateSystem: local coordinate-system definition.
Returns
A Transformation object Q such that
\[\mathbf v_\mathrm{global} = Q\,\mathbf v_\mathrm{local}.\]
Example
er = VectorField(U, "body", [(x, y, z) -> x, (x, y, z) -> y, 0.0])
cs = CoordinateSystem(er)
Q = rotateNodes(U, cs)LowLevelFEM.rotateResult — FunctionrotateResult(result; toCoordSys=CoordinateSystem[])Express a vector or second-order tensor result in one or more local coordinate systems.
The coordinate systems are defined with the same CoordinateSystem objects used by solveField. Multiple coordinate systems may be supplied in toCoordSys; their nodal supports must be disjoint. Outside their support the result remains expressed in the global Cartesian basis.
For a vector result, if Q maps local components to global components,
\[\mathbf v_\mathrm{local} = Q^T \mathbf v_\mathrm{global}.\]
For a second-order tensor,
\[\mathbf A_\mathrm{local} = Q^T \mathbf A_\mathrm{global} Q.\]
Both nodal and elementwise VectorField and TensorField representations are supported. The storage representation, element support, time grid and number of time steps are preserved.
In 2D, the in-plane coordinate transformation is embedded into three dimensions with the out-of-plane direction left unchanged when rotating a TensorField.
Arguments
result: aVectorFieldorTensorFieldcontaining global Cartesian components.toCoordSys: vector of local coordinate systems created withCoordinateSystem.
Returns
A new field of the same concrete type and storage representation as result, with components expressed in the requested local bases.
Example
For a circular shaft aligned with the global z axis, cylindrical result components can be obtained as
er = VectorField(U, "body", [
(x, y, z) -> x,
(x, y, z) -> y,
0.0
])
eφ = VectorField(U, "body", [
(x, y, z) -> -y,
(x, y, z) -> x,
0.0
])
cs = CoordinateSystem(er, eφ)
u_cyl = rotateResult(u; toCoordSys=[cs])
σ_cyl = rotateResult(σ; toCoordSys=[cs])
uφ = u_cyl[2]
τφz = σ_cyl[2, 3]The coordinate basis must be nondegenerate wherever it is active. For example, the cylindrical radial direction is undefined on the shaft axis.
With coordSys, ordinary RHS components and prescribed values are interpreted in the local solver basis; Global marks Cartesian loads. Solutions are reconstructed in global coordinates. See the coordinate guide for a complete example.
Engineering load and support declarations
These constructors store data for the retained engineering API. Current engineering assembly routines consume those declarations. They do not assemble a weak-form load or Robin matrix automatically.
LowLevelFEM.LoadCondition — TypeLoadCondition(phName; field=nothing, problem=field, kwargs...)Generic load specification for assembling right-hand side vectors.
phNameis a Gmsh physical group name.problemoptionally binds the load to a specific field (required for multi-field).fieldalias forproblemvaluesstores component-wise load data, such asfx,fy,q,σxx, etc., asNumber,Function, orScalarField.
The interpretation (surface traction vs body force vs flux, etc.) is decided by the assembly routine, not by this struct.
LowLevelFEM.displacementConstraint — FunctiondisplacementConstraint(name; ux=nothing, uy=nothing, uz=nothing)Specifies displacement constraints on the physical group name. At least one of ux, uy, or uz must be provided (depending on the problem dimension). ux, uy, or uz can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); displacementConstraint("support1", ux=fn))
Returns: BoundaryCondition
Examples
hc = heatConvection("outer", h=10.0, T∞=20.0)Examples
src = heatSource("body", h=1.0e6)Examples
q = heatFlux("out", qn=500.0)Examples
bcT = temperatureConstraint("hot_face", T=100.0)Examples
ld = load("load", fy=-1.0)Examples
bc = displacementConstraint("supp", ux=0, uy=0)Types:
name: Stringux: Float64 or Functionuy: Float64 or Functionuz: Float64 or Function
LowLevelFEM.load — Functionload(name; fx=nothing, fy=nothing, fz=nothing, p=nothing) -> BoundaryConditionCreate engineering distributed-load data on physical group name. Supply at least one Cartesian component or pressure p. Values may be numbers, spatial functions (x,y,z)->value, or scalar fields (converted to nodal storage). If p is supplied it takes precedence over Cartesian component keywords.
This declares load data consumed by the engineering assembly interface; it does not itself assemble a DSL RHS. The engineering API name is intended to remain when its backend migrates to DSL-backed wrappers. For direct weak forms use f = ∫(U ⋅ traction; Γ="right").
LowLevelFEM.elasticSupport — FunctionelasticSupport(name; kx=nothing, ky=nothing, kz=nothing)Specifies distributed stiffness for an elastic support on the physical group name. kx, ky, or kz can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); elasticSupport("supp1", kx=fn)) Default values are 1.
Returns: BoundaryCondition
Types:
name: Stringkx: Float64 or Functionky: Float64 or Functionkz: Float64 or Function
LowLevelFEM.temperatureConstraint — FunctiontemperatureConstraint(name; T=nothing)Specifies temperature constraints on the physical group name. T can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); temperatureConstraint("surf1", T=fn))
Returns: BoundaryCondition
Types:
name: StringT: Float64 or Function
LowLevelFEM.heatFlux — FunctionheatFlux(name; qn=nothing)Specifies the heat flux normal to the surface of the physical group name. qn can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); load("flux1", qn=fn))
Returns: BoundaryCondition
Types:
name: Stringqn: Float64 or Function
LowLevelFEM.heatSource — FunctionheatSource(name; h=nothing)Specifies the volumetric heat source in the physical group name. h can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); load("source1", h=fn))
Returns: BoundaryCondition
Types:
name: Stringh: Float64 or Function
LowLevelFEM.heatConvection — FunctionheatConvection(name; h=nothing, T∞=nothing)Specifies convective boundary conditions on the surface in the physical group name. h is the heat transfer coefficient of the surrounding medium; Tₐ is the ambient temperature. Tₐ can be either a constant or a function of x, y, and z.
Returns: BoundaryCondition
Types:
name: Stringh: Float64Tₐ: Float64 or Function
LowLevelFEM.BoundaryCondition_to_LoadCondition — FunctionBoundaryCondition_to_LoadCondition(bc::Vector{BoundaryCondition})Convert boundary-condition entries to load-condition entries.
Arguments
bc::Vector{BoundaryCondition}: Boundary condition definitions.
Returns
Vector{LoadCondition}: Load conditions with copiedphName,problem, andvalues.
Example
loads = BoundaryCondition_to_LoadCondition(bc)