Field Algebra API
These operations evaluate existing field values. To construct an element matrix from unknown fields, use the weak-form DSL.
Arithmetic and contractions
| Expression | Meaning |
|---|---|
s1 + s2, s1*s2, s1/s2, s^p | Scalar-field arithmetic |
s + a, v*a, T/a | Arithmetic with scalar numbers |
v1 + v2, v*s, v/s | Vector addition and scalar scaling |
dot(v,w) or v ⋅ w | Vector inner product, returning a scalar field |
v × w | Three-component cross product |
v ∘ w | Dyadic product, returning a tensor field |
T*U | Matrix product at field sample points |
T ⋅ U | Tensor double contraction, returning a scalar field |
T*v, v*T | Tensor-vector products |
transpose(T), T' | Tensor transpose |
norm(v) | Pointwise vector norm |
det(T), trace(T), inv(T) | Tensor determinant, trace and inverse |
sqrt(T), cbrt(T), log(T) | Small-matrix functions at field sample points |
eigen(T) | Principal values (VectorField) and vectors (TensorField) |
Most field algebra evaluates element-wise data, converting nodal inputs when necessary. Operands must have compatible mesh support, element ordering and columns. Ordinary array broadcasting is not a substitute for field operations. Matrix functions retain their usual domain restrictions; for example a real matrix logarithm is not defined for every tensor.
eigen(T) computes local tensor eigensystems. The global FEM eigenproblem is solveEigen.
Vector and tensor operations
LinearAlgebra.dot — Methoddot(A::VectorField, B::VectorField) -> ScalarFieldCompute the pointwise inner product of three-component (:v3D) vector fields on their intersecting element support. Nodal inputs are converted to element values; column counts must agree. Use expandTo3D for two-component nodal vector layouts before applying this operation.
Base.:∘ — Method∘(A::VectorField, B::VectorField) -> TensorFieldCompute the pointwise dyadic tensor Aᵢ*Bⱼ on the intersecting element support of three-component vectors. Inputs are converted to element-wise storage and must have matching column counts. Tensor entries are stored column-major.
Base.:* — Method*(A::TensorField, b::VectorField) -> VectorFieldEvaluate the matrix-vector product A*b at element nodes. The vector must use three Cartesian components; columns must agree. Nodal data are converted to element-wise values and the intersecting element support is used.
Base.:* — Method*(b::VectorField, A::TensorField) -> VectorFieldEvaluate the row-vector/tensor product bᵀ*A, storing its three components as a vector field. The same three-component, column and intersecting-support requirements apply as for A*b.
Tensor matrix functions
LinearAlgebra.eigen — Methodeigen(A::TensorField) -> values::VectorField, vectors::TensorFieldCompute a local 3×3 eigensystem at every element node and stored column. Nodal input is converted to element-wise data. Eigenvalues are sorted in descending order and eigenvectors are normalized and stored as tensor columns. The real-valued result containers require real eigenvalues/eigenvectors; complex local eigensystems are unsupported. Symmetry is not imposed.
This is a tensor/principal-value operation. Use solveEigen for a global finite-element generalized eigenproblem.
Base.sqrt — Methodsqrt(A::TensorField) -> TensorFieldApply Julia's matrix square root to each 3×3 tensor at element nodes, converting nodal input first. This is a matrix function, not entry-wise square root. Results must be representable in the real-valued field storage; matrices whose square root is complex are unsupported.
Base.Math.cbrt — Methodcbrt(A::TensorField) -> TensorFieldApply Julia's real matrix cube root to each local 3×3 tensor after converting nodal input to element-wise storage. This is a matrix function, not entry-wise cube root. The resulting local matrices must fit real-valued field storage; Julia's matrix-function restrictions apply.
Base.log — Methodlog(A::TensorField) -> TensorFieldApply the matrix logarithm to each local 3×3 tensor, converting nodal data to element-wise storage first. This is not entry-wise logarithm. A complex result cannot be stored in the real-valued field container.
Three-component vector contractions require :v3D data; expand a two-component nodal field explicitly before dot, dyadic or tensor-vector products. Tensor sqrt, cbrt and log are matrix functions; scalar-field versions operate on individual scalar values.
Scalar and tensor helpers
LinearAlgebra.:⋅ — Function⋅(A::TensorField, B::TensorField)Element-wise (Hadamard) product followed by summation of all components, yielding a scalar per tensor (i.e., Frobenius inner product).
Returns: ScalarField
⋅(A::Union{VectorField,TensorField}, D::Function)Right contraction with the differential operator. With D == ∇:
- If
AisVectorField: returnsdiv(A)(scalar field). - If
AisTensorField: returnsdiv(A)(vector field).
Returns: ScalarField or VectorField
Examples
# 3D (assumes `problem` and a "body" physical group are defined)
V = vectorField(problem, [field("body", fx=x->x, fy=y->y, fz=z->z)])
divV = V ⋅ ∇ # ScalarField⋅(D::Function, A::Union{VectorField,TensorField})Left contraction with the differential operator. With D == ∇:
- If
AisVectorField: returnsdiv(A). - If
AisTensorField: returnsdiv(A').
Returns: ScalarField or VectorField
Examples
# 3D (assumes `problem` and a "body" physical group are defined)
T = tensorField(problem, [field("body", fz=z->z)])
DV = ∇ ⋅ T # VectorField (divergence of tensor)LowLevelFEM.unitTensor — FunctionunitTensor(A::TensorField)Creates an identity tensor field (I) with the same element structure and time steps as A.
Returns: TensorField
LowLevelFEM.trace — Functiontrace(A::TensorField)Computes the trace of each 3×3 tensor block.
Returns: ScalarField
LinearAlgebra.det — Methoddet(A::TensorField)Computes the determinant of each 3×3 tensor block.
Returns: ScalarField
LowLevelFEM.mapScalarField — FunctionmapScalarField(f, A::ScalarField)Apply a function elementwise to a scalar field.
The function f is applied to each element-wise matrix of the scalar field. If the field is nodal, it is first converted to elementwise form.
This is a low-level helper used to implement elementwise scalar-field operations such as abs, +, -, log, sqrt, etc.
Returns
- A new
ScalarFieldcontaining the transformed values.
The ε name is an alias of the DSL SymGrad constructor. It is not a stored strain field and does not replace tensor shear conventions.
Tensor component conversion
tensorToMatrix and tensorToVector expose scalar components for coefficient construction; conversion to Voigt form does not double shear entries. See component conventions.