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
LowLevelFEM.∂x — Function∂x(r::ScalarField) -> ScalarFieldDifferentiate 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 functionsLowLevelFEM.∂y — Function∂y(r::ScalarField) -> ScalarFieldDifferentiate 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 ∇.
LowLevelFEM.∂z — Function∂z(r::ScalarField) -> ScalarFieldDifferentiate 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 ∇.
LowLevelFEM.grad — Functiongrad(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 ∘ ∇LowLevelFEM.curl — Functioncurl(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 = ∇ × vLowLevelFEM.rot — Functionrot(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
Base.div — Methoddiv(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 ⋅ ∇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.
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.