Field Calculus API

Differentiate computed field values. These functions return fields; the capitalized Grad, Div, Curl, and SymGrad constructors instead describe operators inside an assembly expression.

Spatial derivatives

LowLevelFEM.∇ — Function
∇(r::Union{ScalarField,VectorField,TensorField}; nabla=:grad)

Compute spatial derivatives at the element nodes and return an element-wise field. This experimental implementation retrieves the Jacobians of all elements of a given type and entity in one Gmsh call and evaluates the field derivatives directly, without assembling element derivative matrices.

Nodal input is converted to element-wise storage with nodesToElements, which preserves its values at the element nodes. Element-wise input is used directly, so discontinuities between adjacent elements are preserved. The result is always element-wise because derivatives can also be discontinuous between adjacent elements. For element-wise input, r.numElem defines the domain of the operation; consequently, fields restricted to a surface, curve, or another physical group remain restricted to that group.

Supported operations:

  • ScalarField, nabla=:grad -> VectorField
  • three-component VectorField, nabla=:grad -> TensorField
  • three-component VectorField, nabla=:div -> ScalarField
  • three-component VectorField, nabla=:curl -> VectorField
  • TensorField, nabla=:div -> VectorField
  • axisymmetric two-component VectorField, nabla=:grad -> TensorField
source
LowLevelFEM.∂x — Function
∂x(r::ScalarField) -> ScalarField

Differentiate a scalar field with respect to global Cartesian x. Equivalent to ∇(r)[1]; see ∇ for supported geometries.

Nodal input is evaluated through element interpolation. Element-wise input preserves its support and discontinuities. The output is element-wise and contains all input columns. The derivative is that of the finite-element interpolant, so an analytic function must be representable by the element space before its exact derivative can be expected.

s = ScalarField(P, "body", (x,y,z) -> 2x + 3y)
dx = ∂x(s)  # constant 2 on a mesh reproducing linear functions
source
LowLevelFEM.∂y — Function
∂y(r::ScalarField) -> ScalarField

Differentiate with respect to global Cartesian y. Equivalent to ∇(r)[2]; input support, columns, and discontinuities are handled as for ∂x. The result is element-wise.

On an xy-planar mesh, ∂z returns zero. On embedded curves or surfaces, Cartesian components follow the tangential physical gradient from ∇.

source
LowLevelFEM.∂z — Function
∂z(r::ScalarField) -> ScalarField

Differentiate with respect to global Cartesian z. Equivalent to ∇(r)[3]; input support, columns, and discontinuities are handled as for ∂x. The result is element-wise.

On an xy-planar mesh, ∂z returns zero. On embedded curves or surfaces, Cartesian components follow the tangential physical gradient from ∇.

source
LowLevelFEM.grad — Function
grad(r::Union{ScalarField,VectorField})

Solves the gradient of the scalar field or vector field r. An alternative way to solve grad is to use ∇ as a differencial operator.

Return: VectorField or TensorField

Types:

  • r: ScalarField or VectorField

3D Examples

# Assumes a 3D mesh with physical group "body".

# 1) Gradient of a 3D scalar field → VectorField
f(X,Y,Z) = X^2 + Y*Z
S = scalarField(problem, [field("body", f=f)])
G1 = grad(S)
G2 = ∇(S)

# 2) Gradient of a 3D vector field → TensorField
vx(X,Y,Z) = X
vy(X,Y,Z) = Y
vz(X,Y,Z) = Z
V = vectorField(problem, [field("body", fx=vx, fy=vy, fz=vz)])
T1 = grad(V)
T2 = V ∘ ∇
source
LowLevelFEM.curl — Function
curl(r::VectorField)

Solves the rotation of the vector field r. An alternative way to solve curl is to use ∇ as a differencial operator.

Return: VectorField

Types:

  • r: VectorField

3D Example (assumes problem is set as in the ∇ doc setup)

# Assumes a 3D mesh with physical group "body".
vx(X, Y, Z) = 0
vy(X, Y, Z) = X
vz(X, Y, Z) = 0
v = vectorField(problem, [field("body", fx=vx, fy=vy, fz=vz)])
D1 = curl(v)
D2 = ∇ × v
source
LowLevelFEM.rot — Function
rot(r::VectorField)

Solves the rotation of the vector field r. In some countries "rot" denotes the English "curl". (See the curl function.)

Return: VectorField

Types:

  • r: VectorField
source
Base.div — Method
div(r::Union{VectorField,TensorField})

Solves the divergence of the vector field or tensor field r. An alternative way to solve div is to use ∇ as a differencial operator.

Return: ScalarField or VectorField

Types:

  • r: VectorField or TensorField

3D Examples (assumes problem is set as in the ∇ doc setup)

# Assumes a 3D mesh with physical group "body".

# 1) Divergence of a 3D vector field → ScalarField
v1(X,Y,Z) = X
v2(X,Y,Z) = Y
v3(X,Y,Z) = Z
v = vectorField(problem, [field("body", fx=v1, fy=v2, fz=v3)])
D1 = div(v)
D2 = ∇ ⋅ v

# 2) Divergence of a 3D tensor field → VectorField
fsz(X, Y, Z) = 10 - Z
S = tensorField(problem, [field("body", fz=fsz)])
b1 = -div(S)
b2 = -S ⋅ ∇
source

The symbolic notation u ∘ ∇, ∇ ∘ u, ∇ ⋅ u, and ∇ × u is implemented for supported field layouts. The order of a dyadic gradient determines whether the tensor gradient is transposed; see the calculus guide. Derivatives belong to elements and can jump across shared nodes.

Derivatives along stored time columns

LowLevelFEM.∂t — Function
∂t(s::Union{ScalarField,VectorField,TensorField})

Compute the time derivative of a time-dependent field using second-order finite differences in time.

The field values are assumed to be stored at discrete time instants s.t and are differentiated independently at each spatial degree of freedom. The result has the same type and layout (nodal or elementwise) as the input field.

Time discretization

  • For interior time steps, a second-order central difference is used:

∂s/∂t(tᵢ) ≈ (s(tᵢ₊₁) − s(tᵢ₋₁)) / (tᵢ₊₁ − tᵢ₋₁)
  • At the first and last time steps, the derivative is obtained by

second-order extrapolation to preserve overall accuracy.

  • If only two time steps are present, a first-order difference is used

and assigned to both time levels.

  • If s.nsteps == 1, a zero field is returned.

The time grid s.t is not required to be uniform.

Notes

  • The operation is purely algebraic in time and does not involve any

spatial operators or time-integration schemes.

  • The derivative is computed in-place on newly allocated storage and

does not modify the original field.

  • For elementwise fields, the time derivative is computed independently

for each element.

Returns

A new field of the same concrete type as s (ScalarField, VectorField, or TensorField) containing the time derivative.

source

For eigenfields, columns represent modes and t stores eigenvalues. Treating these columns as a physical time history is invalid.

Integrals

Use integrate for scalar spatial integration over a group. integrate(field) and ∫(field) are time-history integrals; ∫(weak_form) assembles matrices or loads. These overloads have different meanings.

Compatibility helpers

The old ∇_old and grad_xy routines remain in the legacy nonlinear reference. New postprocessing should use ∇ and the directional wrappers above.