Fields and Storage API
Lowercase constructors create nodal values; uppercase constructors normally create element-wise values. Both are finite-element fields associated with a Problem. Inspect the representation rather than inferring it from a variable name. See Nodal vs Element Fields.
Containers and construction
LowLevelFEM.ScalarField — TypeScalarField(A, a, t, numElem, nsteps, type, model)
ScalarField(problem::Problem, dataField::Vector; steps=1, tmin=0.0, tmax=tmin+(steps-1))
ScalarField(problem::Problem, phName::String, data::Union{Number,Function};
steps=1, tmin=0.0, tmax=tmin+(steps-1))
ScalarField(s::ScalarField; steps=1, tmin=0.0, tmax=tmin+(steps-1), step=1)Container for a time-dependent scalar field defined on a finite element mesh (e.g. temperature, pressure, potential).
A ScalarField can store the field either
- element-wise (values at the element nodes, stored in
A), or - nodally (values at global mesh nodes, stored in
a).
Time dependence is handled by storing multiple time steps for each spatial degree of freedom.
Stored data
kind=:field (default) marks ordinary field data. For :eigen_real and :eigen_imag, columns are eigenmodes and t contains the corresponding real or imaginary eigenvalue components rather than physical time instants.
A: Vector of matrices holding element-wise values (A[e][k,i]= value at local nodekof elementeat time stepi)a: Matrix of nodal values (a[n,i]= value at nodenat time stepi)t: Vector of time instants corresponding to the stored time stepsnumElem: Vector of element tags associated withAnsteps: Number of stored time stepstype: Symbol identifying the physical meaning of the fieldmodel: AssociatedProblem
At a given time, either A or a is typically populated, depending on whether the field is element-wise or nodal.
Constructors
Low-level constructor
ScalarField(A, a, t, numElem, nsteps, type, model)Directly constructs a ScalarField from preallocated data arrays.
From spatial field definitions
ScalarField(problem, dataField; steps, tmin, tmax)Constructs an element-wise scalar field from a vector of field definitions (e.g. as returned by field(...)). The scalar value may be:
- a constant,
- a spatial function
f(x,y,z), - or a space–time function
f(x,y,z,t).
Values are evaluated at the element nodes for each requested time step.
From a physical group
ScalarField(problem, phName, data; steps, tmin, tmax)Convenience constructor for defining a scalar field on a single physical group. Equivalent to calling field(phName, f=data) internally.
From an existing ScalarField
ScalarField(s; steps, tmin, tmax, step)Creates a new ScalarField by replicating a selected time step of an existing field. This is useful for initializing a time-dependent field from a static solution.
stepselects the time index ofsto be replicated.- The new field contains
stepsidentical time slices.
Notes
- Time steps do not need to be uniformly spaced.
- No assumptions are made about governing equations; this is a pure data container.
- Spatial interpolation and projections (e.g. nodal ↔ element-wise) are handled by separate utility functions.
Example
s(x,y,z) = 2x + 3y
fs = field("body", f=s)
S1 = ScalarField(problem, [fs])
S2 = ScalarField(problem, "body", s)Here S1 and S2 define equivalent element-wise scalar fields.
LowLevelFEM.VectorField — TypeVectorField(A, a, t, numElem, nsteps, type, model)
VectorField(problem::Problem, dataField::Vector)
VectorField(problem::Problem, phName::String, data::Vector)
VectorField(problem::Problem, phName::String, func::Function)
VectorField(comps::Vector)Container for a (possibly time-dependent) vector field defined on a finite element mesh (e.g. displacement, velocity, heat flux).
A VectorField stores a 3D vector field either
- element-wise, with values given at element nodes (
A), or - nodally, with values given at global mesh nodes (
a).
Time dependence is handled by storing multiple time steps for each spatial degree of freedom, analogously to ScalarField.
Stored data
kind=:field (default) marks ordinary field data. For :eigen_real and :eigen_imag, columns are eigenmodes and t contains the corresponding real or imaginary eigenvalue components rather than physical time instants.
A: Vector of matrices holding element-wise vector values (A[e][3k-2:3k, i]= vector value at local nodekof elementeat time stepi)a: Matrix of nodal vector values (layout follows the same interleaved component ordering)t: Vector of time instants corresponding to the stored time stepsnumElem: Vector of element tags associated withAnsteps: Number of stored time stepstype: Symbol identifying the physical meaning of the vector field (e.g.:v3D)model: AssociatedProblem
Vector components are stored in interleaved form (x₁,y₁,z₁,x₂,y₂,z₂,…) for element-wise :v3D data. A nodal solution or assembled load instead has model.pdim components per node; for a 2D vector unknown this means (x₁,y₁,x₂,y₂,…).
Constructors
Low-level constructor
VectorField(A, a, t, numElem, nsteps, type, model)Directly constructs a VectorField from preallocated data arrays.
From element-wise field definitions
VectorField(problem, dataField::Vector)Constructs an element-wise vector field from a vector of field definitions (e.g. as returned by field(...)). Each component may be specified as:
- a constant,
- a spatial function
f(x,y,z).
Values are evaluated at the element nodes.
From a physical group and component data
VectorField(problem, phName, data::Vector)Convenience constructor for defining a vector field on a single physical group, where data = [fx, fy, fz] specifies the three components (constants or functions).
From a vector-valued function
VectorField(problem, phName, func::Function)Constructs an element-wise vector field by evaluating a function func(x,y,z) -> (vx,vy,vz) at the element nodes.
From scalar components
VectorField(comps::Vector{ScalarField})Assembles a 3D vector field from exactly three components. At least one component must be a ScalarField; the others may be compatible scalar fields or numbers. Numbers are expanded over the reference field's element support and columns. Nodal scalar components are converted to element-wise storage.
Requirements:
- exactly three components, at least one a scalar field,
- all field components share the same
Problem, - identical element numbering,
- identical time discretization.
Each scalar field provides one vector component.
From an existing VectorField
VectorField(s; steps, tmin, tmax, step)Creates a new VectorField by replicating a selected time step of an existing field. This is useful for initializing a time-dependent field from a static solution.
stepselects the time index ofsto be replicated.- The new field contains
stepsidentical time slices.
Notes
- Time steps do not need to be uniformly spaced.
- No governing equations are implied; this is a pure data container.
- Spatial operations (gradient, divergence, projections, etc.) are handled by separate utility functions.
- Element-wise storage is the primary representation; nodal storage may be empty depending on construction.
Example
vx(x,y,z) = x + y
vy(x,y,z) = z
fv = field("body", fx=vx, fy=vy, fz=3)
V1 = VectorField(problem, [fv])
V2 = VectorField(problem, "body", [vx, vy, 3])Here V1 and V2 define equivalent element-wise vector fields.
LowLevelFEM.TensorField — TypeTensorField(A, a, t, numElem, nsteps, type, model)
TensorField(problem::Problem, dataField::Vector)
TensorField(problem::Problem, phName::String, data::Matrix)
TensorField(comps::Matrix{ScalarField})Container for a (possibly time-dependent) second-order tensor field defined on a finite element mesh (e.g. stress, strain, conductivity tensor).
A TensorField stores a full 3×3 tensor at each spatial location, either
- element-wise, with values given at element nodes (
A), or - nodally, with values given at global mesh nodes (
a).
Time dependence is handled by storing multiple time steps for each tensor component.
Stored data
kind=:field (default) marks ordinary field data. For :eigen_real and :eigen_imag, columns are eigenmodes and t contains the corresponding real or imaginary eigenvalue components rather than physical time instants.
A: Vector of matrices holding element-wise tensor values (A[e][9k-8:9k, i]= tensor components at local nodekof elementeat time stepi)a: Matrix of nodal tensor values (same component ordering as element-wise storage)t: Vector of time instants corresponding to the stored time stepsnumElem: Vector of element tags associated withAnsteps: Number of stored time stepstype: Symbol identifying the physical meaning of the tensor field (e.g.:e,:stress,:tensor)model: AssociatedProblem
Tensor components are stored in column-major, interleaved form for each node:
(xx, yx, zx,
xy, yy, zy,
xz, yz, zz)
repeated for all nodes and time steps.
Constructors
Low-level constructor
TensorField(A, a, t, numElem, nsteps, type, model)Directly constructs a TensorField from preallocated data arrays.
From element-wise field definitions
TensorField(problem, dataField::Vector)Constructs an element-wise tensor field from a vector of field definitions (e.g. as returned by field(...)).
Each tensor component may be specified as:
- a constant,
- a spatial function
f(x,y,z).
Values are evaluated at the element nodes.
From a constant or functional tensor
TensorField(problem, phName, data::Matrix)Convenience constructor for defining a tensor field on a single physical group, where data is a 3×3 matrix whose entries are constants or functions f(x,y,z).
From scalar components
TensorField(comps::Matrix{ScalarField})Assembles a 3×3 tensor field from a 3×3 matrix of compatible ScalarFields.
Requirements:
- exactly a 3×3 matrix of scalar fields,
- identical
Problem, - identical element numbering,
- identical time discretization.
Each scalar field provides one tensor component.
Notes
- Time steps do not need to be uniformly spaced.
- No symmetry is assumed; all 9 tensor components are stored explicitly.
- This is a pure data container; no constitutive or kinematic assumptions are implied.
- Spatial operations (e.g. divergence, invariants, projections) are handled by separate utility functions.
- Element-wise storage is the primary representation; nodal storage may be empty depending on construction.
Example
tx(x,y,z) = x + y
txy(x,y,z) = z
ft = field("body", fx=tx, fxy=txy, fz=3)
T1 = TensorField(problem, [ft])
T2 = TensorField(problem, "body", [1 0 0;
0 2 0;
0 0 3])Both examples construct element-wise tensor fields; their values differ. Matrix-based construction also accepts ScalarField entries belonging to the same Problem, and mixed scalar components can be used with TensorField(comps::Matrix). Nodal components are converted to element-wise storage; component fields must have compatible support and column counts.
LowLevelFEM.field — Functionfield(name; f=nothing, fx=nothing, fy=nothing, fz=nothing,
fxy=nothing, fyx=nothing, fyz=nothing,
fzy=nothing, fzx=nothing, fxz=nothing)Specifies the value of a scalar, vector, or tensor field on the physical group name. At least one of fx, fy, or fz etc. must be provided (depending on the problem dimension). Each component can be a constant or a function of x, y, and z. (e.g., fn(x,y,z) = 5*(5-x); field("surf1", fx=fn))
Returns: BoundaryCondition
Types:
name: Stringf: Float64 or Functionfx: Float64 or Functionfy: Float64 or Functionfz: Float64 or Functionfxy: Float64 or Functionfyz: Float64 or Functionfzx: Float64 or Function
Examples
f1(x, y, z) = y
f2 = field("face1", f=f1)
qq = scalarField(problem, [f2])
qqq = showDoFResults(qq, :scalar)LowLevelFEM.scalarField — FunctionscalarField(problem, dataField)Defines a scalar field from dataField, which is a tuple of name of physical group and prescribed values or functions. Mesh details are in problem.
Return: Vector{Float64}
Types:
problem: ProblemdataField: Vector{BoundaryCondition}
Examples
f2 = field("face1", f=1)
qq = scalarField(problem, [f2])
qqq = showDoFResults(qq)
qq2 = scalarField(problem, "body", 2.0)Here ScalarField is defined in nodes.
LowLevelFEM.vectorField — FunctionvectorField(problem::Problem, dataField::Vector{BoundaryCondition})Defines a vector field from dataField, which is a tuple of name of physical group and prescribed values or functions. Mesh details are in problem. type can be an arbitrary Symbol, e.g., :u or :f.
Return: VectorField
Types:
problem: ProblemdataField: Vector{BoundaryCondition}
Examples
f1(x, y, z) = sin(x)
f2(x, y, z) = 5y
ff1 = field("face1", fx=f1, fy=f2, fz=0)
ff2 = field("face2", fx=f2, fy=f1, fz=1)
qq = vectorField(problem, [ff1, ff2])
qq0 = showDoFResults(qq)
qq2 = vectorField(problem, "body", [1, 2, ff2])Here VectorField is defined in nodes.
LowLevelFEM.tensorField — FunctiontensorField(problem::Problem, dataField::Vector{BoundaryCondition}; type=:e)Defines a vector field from dataField, which is a tuple of name of physical group and prescribed values or functions. Mesh details are in problem. type can be an arbitrary Symbol, e.g., :u or :f.
Return: TensorField
Types:
problem: ProblemdataField: Vector{BoundaryCondition}
Examples
f1(x, y, z) = sin(x)
f2(x, y, z) = 5y
ff1 = field("face1", fx=f1, fy=f2, fz=0, fxy=1, fyz=1, fzx=f2)
ff2 = field("face2", fx=f2, fy=f1, fz=1, fxy=1, fyz=f1, fzx=1)
qq = tensorField(problem, [ff1, ff2])
qq0 = showDoFResults(qq)
qq2 = tensorField(problem, "body", [1 0 0; 0 2 0; 0 0 f1])Here TensorField is defined in nodes.
Access, conversion and restriction
f[i] selects a vector component; T[i,j] selects a tensor component. These are scalar fields. For column/mode selection use the documented constructor or eigenVector, not the component indexing syntax.
LowLevelFEM.DoFs — FunctionDoFs(f::AbstractField)Return the vector of degrees of freedom (DOFs) associated with a field.
This corresponds to the nodal representation used in linear algebra operations (assembly, solving, post-processing).
LowLevelFEM.isNodal — FunctionisNodal(field::Union{ScalarField,VectorField,TensorField})Check if a given field is defined at nodes (nodal quantity).
Nodal quantities are associated with mesh nodes, for example displacements, nodal forces, or nodal temperatures.
Examples
isNodal(displacement_field) # returns true
isNodal(strain_field) # returns falseLowLevelFEM.isElementwise — FunctionisElementwise(field::Union{ScalarField,VectorField,TensorField})Check if a given field is defined per element (elementwise quantity).
Elementwise quantities are associated with finite elements as a whole, for example stresses, strains, or energy densities evaluated inside elements.
Examples
isElementwise(displacement_field) # returns false
isElementwise(strain_field) # returns trueLowLevelFEM.elementsToNodes — FunctionelementsToNodes(S::Union{ScalarField,VectorField,TensorField})Convert an elementwise field to a nodal field by averaging the values of all elements connected to each node.
Only elements contained in S.numElem contribute to the nodal average. For discontinuous elementwise fields, this operation smooths jumps across element boundaries by arithmetic averaging.
LowLevelFEM.nodesToElements — FunctionnodesToElements(T::Union{ScalarField,VectorField,TensorField};
onPhysicalGroup="")Solves the element results F from the nodal results T. T can be ScalarField, VectorField or TensorField. If onPhysicalGroup is an existing physical group in gmsh, field T will be solve only on elements belonging to that physical group. Dimension of physical group can be different than the dimension of the problem. (eg. mapping from 3D volume to a 2D surface)
Return: F
Types:
T: ScalarField, VectorField or TensorFieldF: ScalarField, VectorField or TensorFieldonPhysicalGroup: String
LowLevelFEM.elementsToElements — FunctionelementsToElements(
S::Union{ScalarField,VectorField,TensorField};
onPhysicalGroup::String,
fromPhysicalGroup::String=""
)Transfer or restrict an elementwise field to the elements of another physical group while preserving elementwise discontinuities.
Two operations are supported:
- same-dimensional restriction,
- transfer to codimension-one boundary or interface elements.
No nodal averaging is performed.
Arguments
S: ElementwiseScalarField,VectorFieldorTensorField.
Keyword Arguments
onPhysicalGroup::String: Target Gmsh physical group.fromPhysicalGroup::String="": Optional source physical group used to disambiguate codimension-one transfers on internal interfaces.
Same-dimensional restriction
If the target physical group has the same dimension as the source elements, only source elements belonging to the target group are retained.
Supported cases are
1D -> 1D
2D -> 2D
3D -> 3DThe element values are copied directly and their elementwise representation is preserved.
This is useful, for example, when an elementwise result is defined on an entire beam structure but only one beam segment should be extracted.
Codimension-one transfer
If the target physical group has dimension one less than the source elements, each target element is matched to a side of a source element through common primary Gmsh node tags.
Supported cases are
1D -> 0D
2D -> 1D
3D -> 2DValues are copied from the matched source element without nodal averaging. Target nodes that are not present in the matched source element are assigned zero.
If a target element is adjacent to more than one eligible source element, the transfer is ambiguous and an error is thrown. Use fromPhysicalGroup to select the required source side of an internal interface.
Returns
A field of the same type as S containing values on the target elements.
Examples
Restrict an elementwise beam result to one beam segment:
M_ABC = elementsToElements(
M;
onPhysicalGroup="ABC"
)Transfer a volume field to a boundary surface:
surface_field = elementsToElements(
volume_field;
onPhysicalGroup="surface"
)Select one side of an internal interface:
interface_field = elementsToElements(
volume_field;
onPhysicalGroup="interface",
fromPhysicalGroup="body_1"
)Notes
The source field must be elementwise.
For codimension-one transfer, the source and target meshes must be conforming.
To obtain nodally averaged values instead of preserving elementwise discontinuities, use
nodesToElements(
elementsToNodes(S);
onPhysicalGroup="..."
)LowLevelFEM.mergeFields — FunctionmergeFields(uu::Vector{<:AbstractField})Concatenates multiple Fields along a common pseudo-time axis.
Interpretation of nsteps:
- If
nsteps == 1, the Field is treated as an iteration state (pseudo-time index: 1, 2, 3, ...). - If
nsteps > 1, the Field is treated as a time history, and its internal time vectortis preserved.
When concatenating multiple time histories, continuity of time is enforced by shifting each subsequent segment such that it starts after the previous one. The time increment between segments is estimated from the last two time points of the previous Field. If this information is unavailable (nsteps == 1), a unit increment (Δt = 1) is assumed.
This function is intended for post-processing and visualization (e.g. merging iteration histories or successive load/time segments), not for time-accurate integration.
All input Fields must:
- have
kind=:field; eigenmode fields cannot be merged on a time axis, - have the same number of degrees of freedom,
- belong to the same model,
- share the same Field type (ScalarField, VectorField, or TensorField).
Returns a Field of the same concrete type as the first element of uu.
Exaples
u1 = solveDisplacement(problem, load=[load1]) # nsteps = 1 u2 = solveDisplacement(problem, load=[load2]) # nsteps = 1 u3 = solveDisplacement(problem, load=[load3]) # nsteps = 1
u_steps = mergeFields([u1, u2, u3])
Warning
The time increment between concatenated segments is estimated heuristically.
When a Field has nsteps == 1, it is interpreted as an iteration state and a unit pseudo-time increment (Δt = 1) is assumed when concatenating with subsequent segments.
This heuristic ensures continuity of the time axis but does NOT represent physical time. The resulting time vector should therefore be used only for post-processing and visualization, not for time-accurate analysis.
LowLevelFEM.projectTo2D — FunctionprojectTo2D(V3D::VectorField)Project a 3D vector field onto the xy-plane by discarding the z-component.
return: VectorField
Examples
V2D = projectTo2D(V3D)LowLevelFEM.expandTo3D — FunctionexpandTo3D(V2D::VectorField)Expand a 2D vector field into 3D by adding a zero z-component.
return: VectorField
Examples
V3D = expandTo3D(V2D)Persistence
LowLevelFEM.saveField — FunctionsaveField(fileName::String, variable::Union{ScalarField,VectorField,TensorField,Number})Saves variable of type ScalarField, VectorField, or TensorField to a file named fileName. The name of the file will be complemented with the string "-LLF-Data.jld2". The field kind is preserved when saving and loading.
Returns: nothing
Types:
fileName: Stringvariable: ScalarField, VectorField or TensorField
LowLevelFEM.loadField — FunctionloadField(fileName::String)Loads a ScalarField, VectorField, or TensorField from a file named fileName (without "-LLF-Data.jld2").
Returns: variable
Types:
fileName: Stringvariable: ScalarField, VectorField or TensorField
LowLevelFEM.isSaved — FunctionisSaved(fileName::String)Checks whether a variable has been saved or not.
Returns: Boolean
Types:
fileName: String
Related topics
- Field algebra: arithmetic, contractions, invariants and tensor functions.
- Field calculus: derivatives of computed fields.
- Solution:
SystemMatrix,SystemVector,solveFieldandsolveEigen.