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 — Type
BoundaryCondition(phName::String; field=nothing, problem=field, kwargs...)

General container type for prescribing boundary conditions in LowLevelFEM.

  • phName is a Gmsh physical group name.
  • problem optionally binds the condition to a specific field (required for multi-field).
  • field alias for problem
  • values stores component-wise boundary condition data, such as ux, uy, T, exx, etc., as Number, Function, or ScalarField.

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 components
  • p : 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 flux
  • qn : prescribed normal heat flux

Convection (Robin-type)

  • h : heat transfer coefficient
  • T : ambient temperature (used together with h)

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 BoundaryCondition objects 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.field and P.rhs_field. Use field=P in a mixed problem to identify the constrained unknown.
  • DSL natural loads are assembled as linear forms with ∫; storing a load in a BoundaryCondition alone does not assemble it.
  • With local solver coordinates, prescribed components are local. Use Global to mark a Cartesian right-hand side.

See also:

  • displacementConstraint
  • load
  • elasticSupport
  • temperatureConstraint
  • heatFlux
  • heatConvection
source
LowLevelFEM.BoundaryConditionFields — Function
BoundaryConditionFields(bc::BoundaryCondition)

Return the defined field keys of a boundary condition.

Arguments

  • bc::BoundaryCondition: Boundary condition object with named values.

Returns

  • An iterator over Symbol keys present in bc.values.

Example

keys = BoundaryConditionFields(bc)
source
LowLevelFEM.constrainedDoFs — Function
constrainedDoFs(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: Problem
  • supports: Vector{BoundaryCondition}
  • DoFs: Vector{Int64}
source
constrainedDoFs(K::SystemMatrix, 
                support::Vector{BoundaryCondition})

Return global constrained DOFs for single- or multi-field systems.

source
LowLevelFEM.freeDoFs — Function
freeDoFs(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: Problem
  • supports: Vector{BoundaryCondition}
  • DoFs: Vector{Int64}
source
freeDoFs(K::SystemMatrix, 
          support::Vector{BoundaryCondition})

Return global free DOFs for single- or multi-field systems.

source
LowLevelFEM.allDoFs — Function
allDoFs(problem)

Returns the serial numbers of degrees of freedom of the whole model.

Return: DoFs

Types:

  • problem: Problem
  • DoFs: Vector{Int64}
source

Multi-point constraints

Detailed construction, rigid links, and periodic examples are in Multifield: Multi-point constraints.

LowLevelFEM.MultiPointConstraint — Type
MultiPointConstraint(; 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 for field.

  • kwargs...: Boolean component selectors. Component names follow the field name and its components, for example ux, uy, uz, φ, φx, φy, φz.

    A value of true constrains the corresponding component, while false leaves 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.

source

MPC is an alias of MultiPointConstraint. The rigid-rotation and collapse helpers are documented with multifield assembly.

Local coordinates

LowLevelFEM.CoordinateSystem — Type
CoordinateSystem(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)
source
LowLevelFEM.Transformation — Type
Transformation(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: Int64
  • dim: Int64
source
LowLevelFEM.rotateNodes — Function
rotateNodes(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)
source
LowLevelFEM.rotateResult — Function
rotateResult(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: a VectorField or TensorField containing global Cartesian components.
  • toCoordSys: vector of local coordinate systems created with CoordinateSystem.

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.

source

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 — Type
LoadCondition(phName; field=nothing, problem=field, kwargs...)

Generic load specification for assembling right-hand side vectors.

  • phName is a Gmsh physical group name.
  • problem optionally binds the load to a specific field (required for multi-field).
  • field alias for problem
  • values stores component-wise load data, such as fx, fy, q, σxx, etc., as Number, Function, or ScalarField.

The interpretation (surface traction vs body force vs flux, etc.) is decided by the assembly routine, not by this struct.

source
LowLevelFEM.displacementConstraint — Function
displacementConstraint(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: String
  • ux: Float64 or Function
  • uy: Float64 or Function
  • uz: Float64 or Function
source
LowLevelFEM.load — Function
load(name; fx=nothing, fy=nothing, fz=nothing, p=nothing) -> BoundaryCondition

Create 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").

source
LowLevelFEM.elasticSupport — Function
elasticSupport(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: String
  • kx: Float64 or Function
  • ky: Float64 or Function
  • kz: Float64 or Function
source
LowLevelFEM.temperatureConstraint — Function
temperatureConstraint(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: String
  • T: Float64 or Function
source
LowLevelFEM.heatFlux — Function
heatFlux(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: String
  • qn: Float64 or Function
source
LowLevelFEM.heatSource — Function
heatSource(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: String
  • h: Float64 or Function
source
LowLevelFEM.heatConvection — Function
heatConvection(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: String
  • h: Float64
  • Tₐ: Float64 or Function
source
LowLevelFEM.BoundaryCondition_to_LoadCondition — Function
BoundaryCondition_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 copied phName, problem, and values.

Example

loads = BoundaryCondition_to_LoadCondition(bc)
source