Geometry

AbstractPoint

Supertype for points in space, parameterized by the float type FT of their coordinates.

Concrete subtypes, grouped by the abstract dimension types Abstract1DPoint, Abstract2DPoint, and Abstract3DPoint:

• 1D: XPoint(x), YPoint(y), ZPoint(z), PPoint(p), LatPoint(lat), LongPoint(long), Cartesian1Point(x1), Cartesian2Point(x2), Cartesian3Point(x3).
• 2D: XYPoint(x, y), XZPoint(x, z), YZPoint(y, z), LatLongPoint(lat, long), Cartesian12Point(x1, x2), Cartesian13Point(x1, x3).
• 3D: XYZPoint(x, y, z), LatLongZPoint(lat, long, z), LatLongPPoint(lat, long, p), Cartesian123Point(x1, x2, x3).

Latitudes and longitudes are in degrees.

Abstract1DPoint{FT}

Supertype for points with a single coordinate of float type FT: XPoint, YPoint, ZPoint, PPoint, LatPoint, LongPoint, Cartesian1Point, Cartesian2Point, and Cartesian3Point. 1D points support tofloat, ordering with isless, and LinRanges.

Abstract2DPoint{FT}

Supertype for points with two coordinates of float type FT: XYPoint, XZPoint, YZPoint, LatLongPoint, Cartesian12Point, and Cartesian13Point.

Abstract3DPoint{FT}

Supertype for points with three coordinates of float type FT: XYZPoint, LatLongZPoint, LatLongPPoint, and Cartesian123Point.

float_type(T)

Return the floating point type backing T: T can either be an object or a type.

component(p::AbstractPoint, i)

Return the ith coordinate of the point p as a plain number, where i is either an integer index or the name of the coordinate as a Symbol: for p = XYPoint(1.0, 2.0), both component(p, 2) and component(p, :y) return 2.0. See also coordinate, which returns the coordinate as a 1D point.

coordinate(pt::AbstractPoint, i::Integer)

Return the ith coordinate of pt as a 1D point: coordinate(XYZPoint(1.0, 2.0, 3.0), 3) is ZPoint(3.0), and for a 1D point coordinate(pt, 1) is pt itself. Defined for all 1D points and for XYPoint, XZPoint, YZPoint, and XYZPoint; the type of the result is given by coordinate_type. See also component, which returns the plain number.

tofloat(p::Abstract1DPoint)

Return the single coordinate of the 1D point p as a plain number, e.g. tofloat(ZPoint(2.0)) == 2.0. Defined for every 1D point type.

euclidean_distance(pt1::T, pt2::T)

Compute the Euclidean distance between two points of the same Cartesian type T, one of XPoint, YPoint, ZPoint, XYPoint, XZPoint, or XYZPoint.

great_circle_distance(pt1::LatLongPoint, pt2::LatLongPoint, global_geom::AbstractSphericalGlobalGeometry)

Compute the great-circle (spherical geodesic) distance between pt1 and pt2 on the sphere of radius global_geom.radius [m].

great_circle_distance(pt1::LatLongZPoint, pt2::LatLongZPoint, global_geom::ShallowSphericalGlobalGeometry)
great_circle_distance(pt1::LatLongZPoint, pt2::LatLongZPoint, global_geom::DeepSphericalGlobalGeometry)

Compute the great-circle (spherical geodesic) distance between pt1 and pt2 [m], ignoring the difference in z. The shallow geometry measures the distance on the sphere of radius global_geom.radius; the deep geometry on the sphere of radius global_geom.radius + (pt1.z + pt2.z) / 2.

Tensor(components, bases::NTuple{N, Components})
Tensor(s::UniformScaling, bases::NTuple{2, Components})

N-dimensional tensor whose entries in components are interpreted with respect to the given bases. Each entry of bases is a Components, and the shape of components must match length.(bases) (otherwise the constructor throws a DimensionMismatch). The bases are stored as a type parameter so that operations can dispatch on the kind of basis (covariant, contravariant, orthonormal, or scalar) at compile time.

parent(x) returns the component array and axes(x) the bases. Scalar indexing x[i, j, ...] reads from the component array; indexing with colons yields a smaller Tensor over the colon axes.

Shapes that Tensor takes in practice

• Tensor{1} (a vector): components::SVector, bases::Tuple{Components}.
• Tensor{2} covector (a row vector): the first axis is ScalarComponents and components::Adjoint{T, SVector}. This is what v' produces for a Tensor{1} v.
• Tensor{2} square tensor: components::SMatrix.

The UniformScaling constructor converts s = λ * I (with λ = s.λ the scalar stored in LinearAlgebra.UniformScaling) into an SMatrix of the size given by bases, which must be square; e.g., Tensor(2I, (b, b)) builds a diagonal tensor with 2 on the diagonal.

Role in reshape

reshape(x::Tensor, bases::NTuple{N, Components}) changes the component names along each axis, dropping components absent from bases and zero-filling the missing ones. reshape alone cannot change the ComponentsType of a concrete Tensor; attempting it throws a DimensionMismatch:

julia> reshape(Covariant12Vector(1.0, 2.0), (Contravariant12Axis(),))
ERROR: DimensionMismatch: Metric is needed for change of basis: Covariant vs Contravariant

To change the basis type, use project or transform with a LocalGeometry, which apply the metric.

Examples

julia> v = Covariant12Vector(1.0, 2.0)
Tensor([1.0, 2.0], (Covariant12Components(),))

julia> parent(v)
2-element SVector{2, Float64} with indices SOneTo(2):
 1.0
 2.0

julia> axes(v)
(Covariant12Components(),)

julia> v[1], v.u₁                                # indexed and named access
(1.0, 1.0)

julia> reshape(v, (Covariant123Axis(),))         # names-only reshape
Tensor([1.0, 2.0, 0.0], (Covariant123Components(),))

Components{T <: ComponentsType, names}()
Components(components_type::ComponentsType, names::Tuple)

Type-level description of a single tensor axis. The parameter T selects the component convention (Covariant, Contravariant, Orthonormal, or OneScalar), and names is a tuple of identifiers for the components along the axis: dimension indices such as (1, 3) for the ξ¹/ξ³ directions, or (nothing,) for the scalar row of a covector (see ScalarComponents). The constructor throws a DuplicateComponentNamesError if names repeat.

A Components is a singleton: all information lives in the type parameters, so instances carry no runtime data and are available for multiple dispatch. Aliases such as Covariant13Axis, UWAxis, and ScalarComponents are defined for every supported dimension combination.

Role in reshape

Components objects, unlike bare ComponentsTypes, carry the component names, so reshape uses them to reorder, drop, or zero-fill components along an axis. reshape alone cannot change the ComponentsType of a concrete Tensor; that needs a metric from a LocalGeometry and is done by project and transform in conversions.jl.

Examples

julia> Covariant13Axis()
Covariant13Components()

julia> length(Covariant13Axis())
2

julia> dual(Covariant13Axis())
Contravariant13Components()

# reshape(tensor, (Components, ...)) reorders and zero-fills by `names`:

julia> v = Covariant12Vector(1.0, 2.0);

julia> reshape(v, (Covariant123Axis(),))         # zero-fill the missing u₃
Tensor([1.0, 2.0, 0.0], (Covariant123Components(),))

julia> reshape(v, (Covariant2Axis(),))           # drop u₁, keep u₂
Tensor([2.0], (Covariant2Components(),))

CovariantVector{T, I, S}
CovariantVector(u::AbstractTensor{1}, local_geometry::LocalGeometry)

Alias for a rank-1 Geometry.Tensor whose axis is Components{Covariant, I}: a vector represented by its covariant components (u₁, u₂, u₃) along the dimensions I, with element type T and storage S. The concrete aliases Covariant1Vector, ..., Covariant123Vector fix I. Called with a vector u and a Geometry.LocalGeometry, it converts u to covariant components with the metric of local_geometry (u is returned unchanged if it is already covariant).

ContravariantVector{T, I, S}
ContravariantVector(u::AbstractTensor{1}, local_geometry::LocalGeometry)

Alias for a rank-1 Geometry.Tensor whose axis is Components{Contravariant, I}: a vector represented by its contravariant components (u¹, u², u³) along the dimensions I, with element type T and storage S. The concrete aliases Contravariant1Vector, ..., Contravariant123Vector fix I. Called with a vector u and a Geometry.LocalGeometry, it converts u to contravariant components with the metric of local_geometry (u is returned unchanged if it is already contravariant).

LocalVector{T, I, S}
LocalVector(u::AbstractTensor{1}, local_geometry::LocalGeometry)
LocalVector(u::Cartesian123Vector, global_geometry::AbstractGlobalGeometry, coord)

Alias for a rank-1 Geometry.Tensor whose axis is Components{Orthonormal, I}: a vector represented by its components (u, v, w) in the local orthonormal frame along the dimensions I, with element type T and storage S. The concrete aliases UVector, UVVector, UVWVector, ... (and their Cartesian*Vector synonyms) fix I. Called with a vector u and a Geometry.LocalGeometry, it converts u to the local orthonormal frame with the metric of local_geometry. The three-argument form rotates a vector from the global Cartesian frame into the local frame at the position coord; it is the inverse of CartesianVector.

outer(x, y)
x ⊗ y

Compute the outer product x * y' of x and y.

outer(x, y)
x ⊗ y

Compute the outer product x * y' of x and y.

project(basis, v)
project(basis, v, basis2)
project(v, basis)

Change the component names along the first axis of the vector or 2-tensor v to basis, dropping components absent from basis and zero-filling components absent from v. For a 2-tensor, project(basis, v, basis2) also changes the second axis to basis2, and project(v, basis) changes only the second axis.

The ComponentsType of each axis must match. Changing it (e.g., Covariant to Contravariant) needs a metric; see the project(basis, v, local_geometry) methods in conversions.jl.

project(basis, v, local_geometry)

Project the first axis of the vector or tensor v onto basis, changing the basis type via the metric of local_geometry if necessary. Missing components are zero-filled; extra components are dropped without error even when they are nonzero.

local_geometry is a LocalGeometry, or the single metric tensor extracted from one, or nothing when the conversion needs no metric. Dimensions orthogonal to the geometry (e.g. dimension 3 in a horizontal (1, 2) LocalGeometry) pass through the identity-padded metric in _to_components_type, which preserves every source component name; the final reshape then zero-fills the destination names that are not in the source.

transform(basis, v)

Change the component names along the first axis of the vector or 2-tensor v to basis, like project, but throw an InexactError if any dropped component of v is nonzero (for a 2-tensor, if any entry of a dropped row is nonzero).

transform(basis, v, local_geometry)

Like project(basis, v, local_geometry), but throw an InexactError if any dropped component is nonzero.

norm(u::AbstractTensor, lg::LocalGeometry)

Metric-aware norm of the vector u at a node with local geometry lg: u is converted to the local orthonormal frame first, so the result does not depend on which basis u is stored in. Equal to sqrt(norm_sqr(u, lg)).

norm_sqr(u, lg::LocalGeometry)

Metric-aware squared norm of the vector u at a node with local geometry lg: u is converted to the local orthonormal frame first, so the result does not depend on which basis u is stored in. Numbers and arrays are passed through to the one-argument norm_sqr; other containers are summed over recursively.

CartesianPoint(pt::AbstractPoint, global_geometry::AbstractGlobalGeometry)

Convert the point pt from the coordinates of the domain to the single global Cartesian frame, returning a Cartesian*Point.

With a Geometry.CartesianGlobalGeometry, XPoint, ZPoint, XYPoint, XZPoint, and XYZPoint map to Cartesian1Point, Cartesian3Point, Cartesian12Point, Cartesian13Point, and Cartesian123Point with the same coordinate values. With an AbstractSphericalGlobalGeometry of radius r, LatLongPoint and LatLongZPoint map to a Cartesian123Point at distance r (respectively r + z) from the centre of the sphere, with the x1 axis through zero latitude and longitude and the x3 axis through the north pole. The inverses on the sphere are LatLongPoint(pt::Cartesian123Point, global_geometry) and LatLongZPoint(pt::Cartesian123Point, global_geometry). Use Cartesian123Point(pt, global_geometry) to always obtain a 3D point.

CartesianVector(u::UVWVector, global_geometry::AbstractGlobalGeometry, coord::AbstractPoint)

Rotate the vector u, given by its components u (east), v (north), w (up) in the local orthonormal frame at the position coord, into the single global Cartesian frame, returning a Cartesian123Vector. For an AbstractSphericalGlobalGeometry, coord is the LatLongPoint or LatLongZPoint at which u is defined. For a Geometry.CartesianGlobalGeometry the local and global frames coincide, so u is returned unchanged and coord is ignored. The inverse is LocalVector(u::Cartesian123Vector, global_geometry, coord).

CartesianTensor(T::AbstractTensor{2}, global_geometry::AbstractGlobalGeometry, coord::AbstractPoint)

Similar to CartesianVector, but for rank-2 tensors whose second axis uses the local orthonormal basis, given by the components u (east), v (north), and w (up). The inverse is LocalTensor(T, global_geometry, coord).

Before supplying a tensor to this function, promote its second axis to the full UVWAxis. For example, when working on a 2D horizontal plane, express the flux ρu ⊗ u as ρu ⊗ Geometry.project(UVWAxis(), u).

LocalTensor(T::AbstractTensor{2}, global_geometry::AbstractGlobalGeometry, coord::AbstractPoint)

Similar to LocalVector, but for rank-2 tensors. Rotates a tensor from the global Cartesian frame into the local frame at the position coord. This is the inverse of CartesianTensor.

LocalGeometry{I, C, FT, M, G}
LocalGeometry(coordinates, J, WJ, ∂x∂ξ::Tensor{2})

Local metric information defined at each node.

I is the tuple of component names of the reference-space axes that the node's grid spans, C the coordinate type, FT the float type, and M and G the padded tensor types of ∂x∂ξ and gⁱʲ. The constructor accepts a ∂x∂ξ Tensor{2} with orthonormal and covariant bases of any size and pads it to the full 3×3 shape.

Fields

• coordinates: coordinates of the node.
• J: Jacobian determinant of the transformation from reference space ξ to physical space x.
• WJ: J multiplied by the quadrature weight.
• ∂x∂ξ: canonical metric ∂x/∂ξ, identity-padded to the full (UVWAxis, Covariant123Axis) shape so that a single matrix-vector product covers every conversion regardless of I.
• gⁱʲ: contravariant metric tensor, identity-padded to the full (Contravariant123Axis, Contravariant123Axis) shape.

The derived properties invJ, ∂ξ∂x, and gᵢⱼ are computed on access as the inverses of J, ∂x∂ξ, and gⁱʲ.

SurfaceGeometry{FT, N}

Local metric information defined at each node on each element surface.

Fields

• sWJ: surface Jacobian determinant multiplied by the surface quadrature weight.
• normal: outward-pointing surface normal vector.

undertype(::Type{G})

Return the floating point type underlying the geometry type G, one of LocalGeometry, SurfaceGeometry, or CoordinateOnlyGeometry: the type of the metric terms, or of the coordinates for a CoordinateOnlyGeometry.

AbstractGlobalGeometry

Supertype for global geometries, which determine the conversion from local coordinates and vector bases to a Cartesian basis.

Subtypes:

• CartesianGlobalGeometry: local coordinates align with Cartesian coordinates.
• SphericalGlobalGeometry: local coordinates refer to a sphere of given radius.
• ShallowSphericalGlobalGeometry, DeepSphericalGlobalGeometry: spherical geometries for extruded spheres with the shallow- and deep-atmosphere assumptions.

CartesianGlobalGeometry()

Global geometry in which the local coordinates align with the Cartesian coordinates, e.g. XYZPoint aligns with Cartesian123Point, and UVWVector aligns with the Cartesian vector basis.

AbstractSphericalGlobalGeometry

Supertype for global geometries in which the local coordinates refer to a sphere: Geometry.SphericalGlobalGeometry, ShallowSphericalGlobalGeometry, and DeepSphericalGlobalGeometry. Every subtype stores the radius of the sphere [m], returned by radius. Positions are LatLongPoints or LatLongZPoints, and CartesianPoint, CartesianVector, and great_circle_distance convert to the global Cartesian frame and measure distances on the sphere.

SphericalGlobalGeometry(radius)

Global geometry in which the local coordinates refer to a sphere of radius radius [m]. The x1 axis is aligned with the zero longitude line.

The local vector basis has u in the zonal direction (east positive), v in the meridional direction (north positive), and w in the radial direction (outward positive). At a pole, the basis is the limit along the zero longitude line:

• at the north pole, this corresponds to u being aligned with the x2 direction, v being aligned with the negative x1 direction, and w being aligned with the x3 direction.
• at the south pole, this corresponds to u being aligned with the x2 direction, v being aligned with the x1 direction, and w being aligned with the negative x3 direction.

ShallowSphericalGlobalGeometry(radius)

Like SphericalGlobalGeometry, but for extruded spheres, with the shallow-atmosphere assumption that the circumference is the same at all z.

DeepSphericalGlobalGeometry(radius)

Like SphericalGlobalGeometry, but for extruded spheres, with the deep-atmosphere assumption that the circumference increases with z.

radius(global_geometry::AbstractSphericalGlobalGeometry)

Return the radius [m] of the sphere that global_geometry refers to.