Points

Mantis.Points Module

module Points

Provides collections of coordinates in either canonical, parametric, or physical domains, in a standardised format.

This serves as an abstraction layer that is used to create evaluation points in several downstream modules, such as Geometry, FunctionSpaces, or Forms.

source

Overview

In Mantis, most object evaluations take place in the canonical domain , where is the manifold dimension. Physical coordinates are then defined from the canonical ones, according to the geometry being used, as described in Geometry. The Points module establishes an interface, common to every module, of how points are interpreted, regardless of whether they are canonical, parametric, or physical, ensuring consistency throughout the codebase.

The AbstractPoints Interface

All point sets in Mantis are subtypes of AbstractPoints:

Mantis.Points.AbstractPoints Type

AbstractPoints{manifold_dim, T}

Supertype for all evaluable points.

Type parameters

• manifold_dim: Dimension of the manifold where the points are evaluated.

• T: The eltype of the points; see Base.eltype.

source

The module requires every concrete subtype to implement get_num_points:

Mantis.Points.get_num_points Function

get_num_points(points::P) where {manifold_dim, P <: AbstractPoints{manifold_dim}}

Returns the number of evaluable points in the given point structure.

source

From this, other methods can be automatically derived, without needing manual implementation:

Mantis.Points.get_manifold_dim Function

get_manifold_dim(points::AbstractPoints{manifold_dim}) where {manifold_dim}

Returns the manifold dimension of the evaluable points.

source

Mantis.Points.get_input_points Function

get_input_points(points::P) where {P <: AbstractPoints}

Returns the points given as input when constructing points, up to a possible type promotion.

source

Mantis.Points.scale_and_shift_points Function

scale_and_shift_points(
    points::P, scalings::S, translations::T
) where {
    manifold_dim,
    P <: AbstractPoints{manifold_dim},
    S <: NTuple{manifold_dim, Real},
    T <: NTuple{manifold_dim, Real},
}

Applies an affine map defined by scalings and translations to each point in points.

Arguments

• points::P: The set of points.

• scalings::S: The scaling of the affine map.

• translations::T: The translation of the affine map.

Returns

• transformed_points::P: The set of transformed points of the same type as the original points.

source

Every concrete points object is also iterable and indexable. Indexing points at a linear index i returns an NTuple{manifold_dim, T} representing the coordinates of the i-th point. This uniform interface means that other modules can simply index points[i], or loop over all points with for p in points, regardless of whether the underlying layout is unstructured or tensor-product.

Concrete Subtypes

The module provides two concrete subtypes of AbstractPoints, each suited to a different structure of evaluation points.

PointSet

Mantis.Points.PointSet Type

PointSet{manifold_dim, T, P} <: AbstractPoints{manifold_dim, T}

Represents an unstructured set of points in manifold_dim dimensions.

Constructors

• PointSet( input_points::Vararg{AbstractVector{<:Number}, manifold_dim} ) where {manifold_dim}: General constructor. Performs validity checks on the given points.

• PointSet(input_points::Tuple): Convenience constructor that will splat the given tuple.

Fields

• input_points::P: A list of points per manifold dimension. The entry inputs[k][i] gives the k-th coordinate of point i.

• num_points::Int: The total number of points.

Examples

julia> using Mantis

julia> points = Points.PointSet([1, 2, 3], [3, 2, 1]);

julia> for point in points
           println(point)
       end
(1, 3)
(2, 2)
(3, 1)

julia> points = Points.PointSet(LinRange(0, 1, 3), [1, 2, 3]);

julia> for point in points
           println(point)
       end
(0.0, 1.0)
(0.5, 2.0)
(1.0, 3.0)

source

The dimension-wise layout, as opposed to a list of points, allows geometry and function-space evaluation routines to extract all coordinates along a given dimension with a single array access, avoiding unnecessary allocations when iterating over large point sets. As tensor-product structured geometries and function-spaces are very common, this ensures such implementations can remain efficient, even with unstructured points.

TensorProductPoints

Mantis.Points.TensorProductPoints Type

TensorProductPoints{manifold_dim, T, TP, CI} <: AbstractPoints{manifold_dim, T}

Represents a set of points tensored from manifold_dim lists of uni-dimensional points.

See also: TensorProducts.TensorProduct.

Constructors

• TensorProductPoints( input_points::Vararg{AbstractVector{<:Number}, manifold_dim}; iteration_order::NTuple{manifold_dim, Int}=ntuple(k -> k, manifold_dim), ) where {manifold_dim}: General constructor. Performs validity checks on the given points and iteration order.

• TensorProductPoints(input_points::Tuple; kwargs...): Convenience constructor that will splat the given tuple and keyword arguments.

Fields

• tensor_product::TP: The set of points per manifold dimension.

• iteration_order::NTuple{manifold_dim, Int}: Used to determine the iteration order over the tensored points. If the k-th entry has value i, then dimension k will be the i-th fastest changing index.

• permuted_cart_num_points::CI: A permuted version of tensored points, as given by iteration_order.

Examples

julia> using Mantis

julia> points = Points.TensorProductPoints([1,2], [1,2,3]; iteration_order=(1, 2));

julia> for point in points
           println(point)
       end
(1, 1)
(2, 1)
(1, 2)
(2, 2)
(1, 3)
(2, 3)

julia> points = Points.TensorProductPoints([1,2], [1,2,3]; iteration_order=(2, 1));

julia> for point in points
           println(point)
       end
(1, 1)
(1, 2)
(1, 3)
(2, 1)
(2, 2)
(2, 3)

source

Tensor-product points are the natural choice whenever the evaluation sites themselves have a tensor-product structure — for instance, the nodes of a Quadrature rule on a multidimensional element.

This concrete type has methods that help interface with TensorProducts:

Mantis.Points.get_factor_points Function

get_factor_points(points::TensorProductPoints)

Equivalent to get_input_points, but provides a consistent interface with TensorProducts.

source

Mantis.Points.get_cart_num_points Function

get_cart_num_points(points::TensorProductPoints)

Return the CartesianIndices used to convert from linear to cartesian indexing.

source

Mantis.Points.get_lin_num_points Function

get_lin_num_points(points::TensorProductPoints)

Returns the LinearIndices used to convert from cartesian to linear indexing.

source

Mantis.Points.get_factor_num_points Function

get_factor_num_points(points::TensorProductPoints)

Returns the number of input points per manifold dimension.

source

Mantis.Points.get_iteration_order Function

get_iteration_order(points::TensorProductPoints)

Returns the iteration_order order used to index points.

source

Mantis.Points.get_permuted_cart_num_points Function

get_permuted_cart_num_points(points::TensorProductPoints)

Returns the permuted tensored points used to index points, as given by iteration order.

source

Relationships to Other Modules

The Points module deliberately has minimal dependencies, only TensorProducts, and is used by every module that requires evaluation:

• Geometry: evaluates geometries by mapping points in the canonical domain to a set of points on a given element, in either parametric or physical coordinates.

• FunctionSpaces: evaluates basis functions and their derivatives at AbstractPoints in the canonical domain of each element.

• Forms: in the most general case, evaluates from a canonical set of points, using both parametric information from the underlying function spaces, and information from the physical geometry for pullbacks.

• Quadrature: quadrature rules store their nodes as AbstractPoints. The TensorProductPoints type is particularly useful here, as most multidimensional rules are formed from 1D factor rules.

• Plot: uses points to build visualisations written to VTK output.