Gridap.Fields

Exported names

AffineField, ArrayBlock, ArrayBlockView, BlockMap, ConstantField, DIV, DensifyInnerMostBlockLevelMap, Field, FieldGradient, FieldGradientArray, GenericField, IntegrationMap, MatrixBlock, MatrixBlockView, MockField, MockFieldArray, Point, VectorBlock, VectorBlockView, VoidBasis, VoidBasisMap, VoidField, VoidFieldMap, ZeroField, affine_map, codifferential, constant_field, curl, d_0form, d_1form, divergence, evaluate, evaluate!, exterior_derivative, grad2curl, gradient, gradient_type, integrate, inverse_map, laplacian, lie_derivative, linear_combination, pinvJt, push_∇, push_∇∇, return_cache, return_type, symmetric_gradient, test_field, test_field_array, Δ, ε, ∇, ∇∇, 𝑑, 𝓛,

struct AffineField{D1,D2,T,L} <: Field

A Field with the form:

y = x⋅G + y0

with G::TensorValue{D1,D2,T,L} and y0::Point{D2,T}.

struct AffineMap <: Map

Type that represents a broadcast operation over a set of AbstractArray{<:Field}. The result is a sub-type of AbstractArray{<:Field}

CodifferentialForm{K,D,F} <: Field

Lazy codifferential of DifferentialForm{K,D,...}. Stores only form::F; all helper data (Hodge star matrix, gradient caches) are derived in return_cache and reused across point evaluations.

struct ConstantField{T<:Number} <: Field

Constant field with value of type T.

struct DensifyInnerMostBlockLevelMap <: Map

DifferentialForm{K,D,L,Data} <: Field

Typed K-form in D dimensions. Data = typeof(data) captures the full tuple type of the L = binomial(D,K) component Fields so that downstream wrappers (ExteriorDerivativeForm, CodifferentialForm) can use map(∇, form.data) with full type inference — giving zero-allocation, type-stable evaluation.

ExteriorDerivativeForm{K,D,F} <: Field

Lazy exterior derivative of a DifferentialForm{K,D,...}. Stores only form::F; gradient fields are derived in return_cache via map(∇, form.data).

abstract type Field <: Map

Abstract type representing a physical (scalar, vector, or tensor valued) field. The domain is a Point and the range a scalar (sub-typing a Number), a VectorValue, or a TensorValue.

The Fields module implements evaluate Array of fields at Points and AbstractVector of points. These different cases are distinguished by the return value obtained when evaluating them. For example, a field returns a Vector of values when evaluated at a Vector of points, and a basis of nf fields returns a (np x nf) Matrix when evaluated at a Vector of np points.

The following functions (i.e., the Map API) need to be overloaded:

• evaluate!(cache,f,x)

and optionally

• return_cache(f,x)
• return_type(f,x)

A Field or Function f can also provide its gradient if the following method is implemented

• gradient(::typeof(f))

This also provide higher order derivatives of user defined f, and the other differential operators will use the derivatives provided by gradient rather than automatic differentiation.

The interface can be tested with

• test_field

For performance, the user can also consider a vectorised version of the Field API that evaluates the field in a vector of points (instead of only one point). E.g., the evaluate! function for a vector of points returns a vector of scalar, vector or tensor values.

struct FieldGradient{N,F} <: Field

Type that represents the gradient of a field of type F. N is how many times the gradient is applied. Requires implementing

evaluate!(cache,f::FieldGradient,x::Point) = @abstractmethod.

For F<:Function, FieldGradient is implemented for N=1, 2 by gradient and hessian.

struct FieldGradientArray{Ng,A,T,N} <: AbstractArray{T,N}

A wrapper that represents the broadcast of gradient over an array of fields. Ng is the number of times the gradient is applied, A the type of the field array to take derivatives of.

struct GenericField{T} <: Field

A wrapper for objects that can act as fields, e.g., functions which implement the Field API.

struct IntegrationMap <: Map

Map for low level integrate, that is computation of vectorized discrete quadratures.

KoszulForm{K,D,F} <: Field

Lazy Koszul contraction of a DifferentialForm{K,D,...}. Stores only form::F; evaluates ι_x(form(x)) at each point x.

struct MockField{T<:Number} <: Field

For tests.

struct MockFieldArray{N,A} <: AbstractArray{GenericField{Nothing},N}

For tests.

struct OperationField{O,F} <: Field

A Field that is obtained as a given operation op::O over a tuple of fields fields::F.

const Point{D,T} = VectorValue{D,T}

Type representing a point of D dimensions with coordinates of type T. Fields are evaluated at vectors of Point objects.

PullbackForm{K,Dm,Dn} <: Field

Lazy pullback φ*ω of a DifferentialForm{K,Dn} under a map field φ : ℝᴰᵐ → ℝᴰⁿ, see pullback(φ::Field, ω::DifferentialForm, ::Val).

Given a matrix np x nf1 x nf2 result of the evaluation of a field vector on a vector of points, it returns an array in which the field axes (second and third axes) are permuted. It is equivalent as Base.permutedims(A,(1,3,2)) but more performant, since it does not involve allocations.

struct VoidBasis{T,N,A} <: AbstractArray{T,N}

struct VoidBasisMap <: Map

struct VoidField{F} <: Field

struct VoidFieldMap <: Map

struct ZeroField{F} <: Field

It represents 0.0*f for a field f::F.

f∘g

It returns the composition of two fields, which is just Operation(f)(g)

evaluate!(c, f::AbstractArray{T}, x::Point) where T<:Field

Evaluation of an array of Field.

If the field vector has length nf and it is evaluated in one point, it returns an nf vector with the result. If the same array is applied to a vector of np points, it returns a matrix np x nf.

DIV(f)

Reference space divergence.

affine_map(gradient, origin) = AffineField(gradient, origin)

See AffineField.

codifferential(ω)

Codifferential of a differential K-form ω, is a (K-1)-form. In flat Euclidean space, δω = (-1)^{D(K-1)+1} ⋆ d ⋆ ω.

constant_field(value) = ConstantField(value)

See ConstantField.

curl(f)

Abstract curl operator, formally equivalent to

• f -> ∂₁f₂ - ∂₂f₁ for 2D vector functions, or
• f -> ∇×f for 3D vector functions.

d_0form(f) = to_1form(∇(f))

Discrete exterior derivative of a scalar (0-form) cell field. Returns a ExteriorFormValue{1,D}-valued OperationCellField.

d_1form(f) = Operation(grad_to_2form)(∇(f))

Discrete exterior derivative of a VectorValue'd (1-form) CellField (e.g., from a Nédélec FESpace). Returns a ExteriorFormValue{2,D}-valued OperationCellField.

divergence(f)

Abstract divergence operator, formally equivalent to f -> ∇⋅f.

exterior_derivative(ω)
𝑑(ω)

Exterior derivative of a differential K-form dω, is a (K+1)-form.

grad2curl(∇f)

Return

• ∇f[1,2] - ∇f[2,1] for 2×2 input tensor, or
• VectorValue(∇f[2,3] - ∇f[3,2], ∇f[3,1] - ∇f[1,3], ∇f[1,2] - ∇f[2,1]) for 3×3 input tensor.

function gradient end

Abstract gradient operator, see Field.

gradient_type(::Type{T}, x::Point) where T

Tensor type of the gradient of a T valued function.

hodge_star_form(ω::DifferentialForm{K,D})

Flat (Euclidean) Hodge star: a DifferentialForm{D-K,D} whose component fields are ±1 linear combinations of the components of ω.

It is differentiable, unlike the pointwise Operation(hodge_star).

integrate(a::AbstractArray{<:Field},q::AbstractVector{<:Point},w::AbstractVector{<:Real},j::Field)

Integration of a given array of fields in the "reference" space

integrate(a::AbstractArray{<:Field},x::AbstractVector{<:Point},w::AbstractVector{<:Real})

Integration of a given array of fields in the "physical" space

integrate(a::Field,q::AbstractVector{<:Point},w::AbstractVector{<:Real},j::Field)

Numerical integration of a given field in the "reference" space. j is the Jacobian field of the geometrical mapping .

integrate(a::Field,x::AbstractVector{<:Point},w::AbstractVector{<:Real})

Numerical integration of a given field in the "physical" space. a is the field, x the quadrature points and w the quadrature weights.

laplacian(f)
Δ(f)

Abstract laplacian operator, equivalent to tr(∇∇(f)).

lie_derivative(v, ω)
𝓛(v,ω)

Lie derivative 𝓛v ω = d(ιv ω) + ι_v(dω) (Cartan's magic formula).

Requires symbolic (Symbolics.Num) coefficients: methods are provided by the GridapSymbolicsExt package extension when Symbolics is loaded.

linear_combination(v::AbstractVector{<:Number}, f::AbstractVector{<:Field})
linear_combination(m::AbstractMatrix{<:Number}, f::AbstractVector{<:Field})

Lazy linear combination lc = vf = Σ vᵢfᵢ , or lcⱼ = (transpose(m)f)ⱼ = Σᵢ mᵢⱼfᵢ.

function pinvJt(Jt::MultiValue{Tuple{D,D}}) = inv(Jt)
function pinvJt(Jt::MultiValue{Tuple{D1,D2}}) = transpose(inv(Jt⋅transpose(J))⋅Jt)

(Psedo-)inverse of Jt.

push_∇(∇a::Field, ϕ::Field) = pinvJt(∇(ϕ))⋅∇a

Pushforward of ∇a by the mapping ϕ, or covariant Piola transform.

push_∇∇(∇∇a::Field, ϕ::Field) = @notimplemented

skew_symmetric_gradient(f)

Abstract skew symmetric gradient operator, formally equivalent to f -> ½(∇f - (∇f)ᵀ).

symmetric_gradient(f)
ε(f)

Abstract symmetric gradient operator, formally equivalent to f -> ½(∇f + (∇f)ᵀ).

test_field(
  f::Union{Field,AbstractArray{<:Field}},
  x,
  v,
  cmp=(==);
  grad=nothing,
  gradgrad=nothing)

Function used to test the field interface. v is an array containing the expected result of evaluating the field f at the point or vector of points x. The comparison is performed using the cmp function. For fields objects that support the gradient function, the keyword argument grad can be used. It should contain the result of evaluating gradient(f) at x. Idem for gradgrad. The checks are performed with the @test macro.

test_field_array(f::AbstractArray{<:Field}, x, v, cmp=(==); grad=nothing, gradgrad=nothing)

For tests.

∇∇(f) = gradient(gradient(f))

Abstract hessian operator.

koszul(ω::DifferentialForm)

Koszul differential of ω, giving a (K-1)-form valued KoszulForm.

outer(f,∇)
f⊗∇

Equivalent to transpose(gradient(f)).

outer(∇,f)
∇⊗f

Equivalent to gradient(f).

cross(∇,f)
∇×f

Equivalent to curl(f).

dot(∇,f)
∇⋅f

Equivalent to divergence(f).