abstract type Field <: Map

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

These different cases are distinguished by the return value obtained when evaluating them. E.g., a physical field returns a vector of values when evaluated at a vector of points, and a basis of nf fields returns a 2d matrix (np x nf) when evaluated at a vector of np points.

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

and optionally

A Field can also provide its gradient if the following function is implemented

Higher derivatives can be obtained if the resulting object also implements this method.

The next paragraph is out-of-date:

Moreover, if the gradient(f) is not provided, a default implementation that uses the following functions will be used.

Higher order derivatives require the implementation of

These four methods are only designed to be called by the default implementation of field_gradient(f) and thus cannot be assumed that they are available for an arbitrary field. For this reason, these functions are not exported. The general way of evaluating a gradient of a field is to build the gradient with gradient(f) and evaluating the resulting object. For evaluating the hessian, use two times gradient.

The interface can be tested with

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.


Type that represents the gradient of a field. The wrapped field must implement evaluate_gradient! and return_gradient_cache for this gradient to work.

N is how many times the gradient is applied

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.


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.


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


Implementation of return_cache for a 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.


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.