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 — Type
ScalarField(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 node k of element e at time step i)
  • a : Matrix of nodal values (a[n,i] = value at node n at time step i)
  • t : Vector of time instants corresponding to the stored time steps
  • numElem : Vector of element tags associated with A
  • nsteps : Number of stored time steps
  • type : Symbol identifying the physical meaning of the field
  • model : Associated Problem

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.

  • step selects the time index of s to be replicated.
  • The new field contains steps identical 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.

source
LowLevelFEM.VectorField — Type
VectorField(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 node k of element e at time step i)
  • a : Matrix of nodal vector values (layout follows the same interleaved component ordering)
  • t : Vector of time instants corresponding to the stored time steps
  • numElem : Vector of element tags associated with A
  • nsteps : Number of stored time steps
  • type : Symbol identifying the physical meaning of the vector field (e.g. :v3D)
  • model : Associated Problem

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.

  • step selects the time index of s to be replicated.
  • The new field contains steps identical 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.

source
LowLevelFEM.TensorField — Type
TensorField(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 node k of element e at time step i)
  • a : Matrix of nodal tensor values (same component ordering as element-wise storage)
  • t : Vector of time instants corresponding to the stored time steps
  • numElem : Vector of element tags associated with A
  • nsteps : Number of stored time steps
  • type : Symbol identifying the physical meaning of the tensor field (e.g. :e, :stress, :tensor)
  • model : Associated Problem

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.

source
LowLevelFEM.field — Function
field(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: String
  • f: Float64 or Function
  • fx: Float64 or Function
  • fy: Float64 or Function
  • fz: Float64 or Function
  • fxy: Float64 or Function
  • fyz: Float64 or Function
  • fzx: Float64 or Function

Examples

f1(x, y, z) = y
f2 = field("face1", f=f1)
qq = scalarField(problem, [f2])
qqq = showDoFResults(qq, :scalar)
source
LowLevelFEM.scalarField — Function
scalarField(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: Problem
  • dataField: 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.

source
LowLevelFEM.vectorField — Function
vectorField(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: Problem
  • dataField: 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.

source
LowLevelFEM.tensorField — Function
tensorField(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: Problem
  • dataField: 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.

source

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 — Function
DoFs(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).

source
LowLevelFEM.isNodal — Function
isNodal(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 false
source
LowLevelFEM.isElementwise — Function
isElementwise(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 true
source
LowLevelFEM.elementsToNodes — Function
elementsToNodes(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.

source
LowLevelFEM.nodesToElements — Function
nodesToElements(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 TensorField
  • F: ScalarField, VectorField or TensorField
  • onPhysicalGroup: String
source
LowLevelFEM.elementsToElements — Function
elementsToElements(
    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:

  1. same-dimensional restriction,
  2. transfer to codimension-one boundary or interface elements.

No nodal averaging is performed.

Arguments

  • S: Elementwise ScalarField, VectorField or TensorField.

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 -> 3D

The 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 -> 2D

Values 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="..."
)
source
LowLevelFEM.mergeFields — Function
mergeFields(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 vector t is 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.

source
LowLevelFEM.projectTo2D — Function
projectTo2D(V3D::VectorField)

Project a 3D vector field onto the xy-plane by discarding the z-component.

return: VectorField

Examples

V2D = projectTo2D(V3D)
source
LowLevelFEM.expandTo3D — Function
expandTo3D(V2D::VectorField)

Expand a 2D vector field into 3D by adding a zero z-component.

return: VectorField

Examples

V3D = expandTo3D(V2D)
source

Persistence

LowLevelFEM.saveField — Function
saveField(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: String
  • variable: ScalarField, VectorField or TensorField
source
LowLevelFEM.loadField — Function
loadField(fileName::String)

Loads a ScalarField, VectorField, or TensorField from a file named fileName (without "-LLF-Data.jld2").

Returns: variable

Types:

  • fileName: String
  • variable: ScalarField, VectorField or TensorField
source
LowLevelFEM.isSaved — Function
isSaved(fileName::String)

Checks whether a variable has been saved or not.

Returns: Boolean

Types:

  • fileName: String
source
  • Field algebra: arithmetic, contractions, invariants and tensor functions.
  • Field calculus: derivatives of computed fields.
  • Solution: SystemMatrix, SystemVector, solveField and solveEigen.