Spaces

Spaces

Function spaces on which fields are defined. A space combines a grid (domain, topology, coordinates, metric terms, and quadrature rules and weights) with a vertical staggering.

Notes

References: CEED and the ClimateMachine sphere helpers.

AbstractSpace

Abstract supertype of spaces. Subtypes define grid(space), staggering(space), and the constructor space(grid, staggering).

Δz_data(space::AbstractSpace)

Return a DataLayout containing the vertical extent Δz = ∂z/∂ξ³ of each cell of space [m].

AbstractFiniteDifferenceSpace <: AbstractSpace

Abstract supertype of one-dimensional, vertically staggered finite difference spaces. The concrete subtype is Spaces.FiniteDifferenceSpace.

FiniteDifferenceSpace(grid::Grids.FiniteDifferenceGrid, staggering::Staggering)
FiniteDifferenceSpace(topology::Topologies.IntervalTopology, staggering::Staggering)

One-dimensional finite-difference space, located at either

• cell centers, where staggering is Grids.CellCenter, or
• cell faces, where staggering is Grids.CellFace.

CenterFiniteDifferenceSpace{G}

Alias of Spaces.FiniteDifferenceSpace with Grids.CellCenter staggering: a one-dimensional space located at cell centers. G is the finite difference grid type.

FaceFiniteDifferenceSpace{G}

Alias of Spaces.FiniteDifferenceSpace with Grids.CellFace staggering: a one-dimensional space located at cell faces. G is the finite difference grid type.

AbstractSpectralElementSpace <: AbstractSpace

Abstract supertype of horizontal spectral element spaces, in which each element carries a polynomial representation on quadrature nodes. Subtypes are Spaces.SpectralElementSpace1D, Spaces.SpectralElementSpace2D, and SpectralElementSpaceSlab; they have no staggering (staggering(space) is nothing) and are their own horizontal space.

SpectralElementSpace1D(grid::Grids.SpectralElementGrid1D)
SpectralElementSpace1D(
    topology::Topologies.IntervalTopology,
    quadrature_style::Quadratures.QuadratureStyle;
    discretization = nothing,
    kwargs...
)

A one-dimensional spectral-element space. The second form builds the Grids.SpectralElementGrid1D and forwards kwargs to it; discretization = Grids.DG() makes the space discontinuous across element boundaries, and omitting it follows the quadrature. Read the choice back with Spaces.discretization.

SpectralElementSpace2D(grid::Grids.SpectralElementGrid2D)
SpectralElementSpace2D(
    topology::Topologies.Topology2D,
    quadrature_style::Quadratures.QuadratureStyle;
    discretization = nothing,
    kwargs...,
)

A two-dimensional spectral-element space. The second form builds the Grids.SpectralElementGrid2D and forwards kwargs to it (discretization, enable_bubble, enable_mask, autodiff_metric, VIJH); discretization = Grids.DG() makes the space discontinuous across element boundaries, so Spaces.weighted_dss! is a no-op and inter-element coupling goes through numerical fluxes. Omitting it follows the quadrature. Read the choice back with Spaces.discretization.

Examples

space = Spaces.SpectralElementSpace2D(topology, Quadratures.GLL{4}())
dg_space = Spaces.SpectralElementSpace2D(
    topology,
    Quadratures.GLL{4}();
    discretization = Grids.DG(),
)

RectilinearSpectralElementSpace2D

Alias of Spaces.SpectralElementSpace2D restricted to grids on a rectangular (plane) domain: a Grids.RectilinearSpectralElementGrid2D, or a level of a Grids.ExtrudedRectilinearSpectralElementGrid3D.

CubedSphereSpectralElementSpace2D

Alias of Spaces.SpectralElementSpace2D restricted to grids on a cubed-sphere domain: a Grids.CubedSphereSpectralElementGrid2D, or a level of a Grids.ExtrudedCubedSphereSpectralElementGrid3D.

SpectralElementSpaceSlab <: AbstractSpace

View into a spectral element space for a single slab (one element at one level).

Spaces.node_horizontal_length_scale(space::AbstractSpectralElementSpace)
Spaces.node_horizontal_length_scale(::Nothing)

Return the approximate distance between nodes: the length scale of the mesh (see Meshes.element_horizontal_length_scale) divided by the number of unique quadrature points along each dimension. The method for nothing returns 1.

ExtrudedFiniteDifferenceSpace(grid, staggering)

ExtrudedFiniteDifferenceSpace(
    horizontal_space::AbstractSpace,
    vertical_space::FiniteDifferenceSpace,
    hypsography::Grids.HypsographyAdaption = Grids.Flat();
    deep::Bool = false,
)

Extruded finite-difference space: a horizontal space extruded along a staggered vertical direction, with grid information at either

• cell centers, where staggering is Grids.CellCenter, or
• cell faces, where staggering is Grids.CellFace.

The second constructor takes the staggering from vertical_space; deep = true selects deep-atmosphere spherical geometry.

ExtrudedFiniteDifferenceSpace2D

Alias of Spaces.ExtrudedFiniteDifferenceSpace with either staggering whose horizontal grid is a one-dimensional spectral element grid (Grids.SpectralElementGrid1D), so the space is two-dimensional.

ExtrudedFiniteDifferenceSpace3D

Alias of Spaces.ExtrudedFiniteDifferenceSpace with either staggering whose horizontal grid is a two-dimensional spectral element grid (Grids.SpectralElementGrid2D), so the space is three-dimensional.

CenterExtrudedFiniteDifferenceSpace{G}

Alias of Spaces.ExtrudedFiniteDifferenceSpace with Grids.CellCenter staggering: an extruded space located at cell centers. G is the extruded grid type.

FaceExtrudedFiniteDifferenceSpace{G}

Alias of Spaces.ExtrudedFiniteDifferenceSpace with Grids.CellFace staggering: an extruded space located at cell faces. G is the extruded grid type.

CenterExtrudedFiniteDifferenceSpace2D

Alias of CenterExtrudedFiniteDifferenceSpace (an Spaces.ExtrudedFiniteDifferenceSpace at cell centers) whose horizontal grid is a one-dimensional spectral element grid.

FaceExtrudedFiniteDifferenceSpace2D

Alias of FaceExtrudedFiniteDifferenceSpace (an Spaces.ExtrudedFiniteDifferenceSpace at cell faces) whose horizontal grid is a one-dimensional spectral element grid.

CenterExtrudedFiniteDifferenceSpace3D

Alias of CenterExtrudedFiniteDifferenceSpace (an Spaces.ExtrudedFiniteDifferenceSpace at cell centers) whose horizontal grid is a two-dimensional spectral element grid.

FaceExtrudedFiniteDifferenceSpace3D

Alias of FaceExtrudedFiniteDifferenceSpace (an Spaces.ExtrudedFiniteDifferenceSpace at cell faces) whose horizontal grid is a two-dimensional spectral element grid.

ExtrudedSpectralElementSpace2D

Alias of Spaces.ExtrudedFiniteDifferenceSpace on a Grids.ExtrudedSpectralElementGrid2D, i.e. an extruded one-dimensional spectral element grid. It denotes the same set of spaces as ExtrudedFiniteDifferenceSpace2D.

ExtrudedSpectralElementSpace3D

Alias of Spaces.ExtrudedFiniteDifferenceSpace on a Grids.ExtrudedSpectralElementGrid3D, i.e. an extruded two-dimensional spectral element grid. It denotes the same set of spaces as ExtrudedFiniteDifferenceSpace3D.

ExtrudedRectilinearSpectralElementSpace3D

Alias of Spaces.ExtrudedFiniteDifferenceSpace with either staggering whose horizontal grid is a two-dimensional spectral element grid on a rectangular (plane) domain (Grids.ExtrudedRectilinearSpectralElementGrid3D).

ExtrudedCubedSphereSpectralElementSpace3D

Alias of Spaces.ExtrudedFiniteDifferenceSpace with either staggering whose horizontal grid is a two-dimensional spectral element grid on a cubed-sphere domain (Grids.ExtrudedCubedSphereSpectralElementGrid3D).

AbstractPointSpace <: AbstractSpace

Abstract supertype of zero-dimensional spaces, whose local geometry is a single point. The concrete subtype is Spaces.PointSpace.

PointSpace <: AbstractSpace

A zero-dimensional space: a single point, the horizontal space of one column (Spaces.level of a FiniteDifferenceSpace). For N disconnected horizontal points see MultiPointSpace, and for N independent columns see MultiColumnFiniteDifferenceSpace.

Constructor

PointSpace(context::ClimaComms.AbstractCommsContext, local_geometry::Geometry.LocalGeometry)
PointSpace(context::ClimaComms.AbstractCommsContext, coord::Geometry.Abstract1DPoint)
PointSpace(device::ClimaComms.AbstractDevice, x)
PointSpace(x)

Construct a PointSpace from a LocalGeometry, or from a 1D coordinate with unit metric terms. Without a context, the default ClimaComms.context() is used.

MultiPointSpace(grid)

Horizontal space of N independent (lat, lon) points. This is the N-column analog of PointSpace, which is the single-column level space.

Like SpectralElementSpace2D, the wrapped grid is either

• a Grids.MultiPointGrid, the level-agnostic horizontal grid of a MultiColumnFiniteDifferenceSpace (returned by Spaces.horizontal_space), or
• a Grids.LevelGrid of the extruded multi-column grid at a single vertical level (returned by Spaces.level), carrying full 3D local geometry.

MultiColumnFiniteDifferenceSpace(grid, staggering)

Space of N independent vertical columns at arbitrary horizontal (lat, lon) locations on a sphere. This is the N-column generalization of Spaces.FiniteDifferenceSpace, the single-column space:

• The data layout is VIJFH{LG, Nv, 1, 1, N}: the same vertical structure for every column, with full 3D local geometry including lat, lon, and z coordinates.
• Spaces.level returns a MultiPointSpace (N points at that level) rather than a spectral element horizontal space.
• Spaces.column returns a single-column Spaces.FiniteDifferenceSpace.
• Fields.bycolumn iterates over each column independently.

There is no horizontal connectivity between columns; DSS is not supported, and horizontal spectral-element derivative operators evaluate to zero, as on a single column.

CenterMultiColumnFiniteDifferenceSpace{G}

Alias of Spaces.MultiColumnFiniteDifferenceSpace with Grids.CellCenter staggering: N independent columns located at cell centers. G is the extruded multi-point grid type.

FaceMultiColumnFiniteDifferenceSpace{G}

Alias of Spaces.MultiColumnFiniteDifferenceSpace with Grids.CellFace staggering: N independent columns located at cell faces. G is the extruded multi-point grid type.

Spaces.grid(space::AbstractSpace)

Return the Grids.AbstractGrid underlying space: the domain, topology, coordinates, metric terms, and quadrature, without the vertical staggering.

Spaces.staggering(space::AbstractSpace)

Return the vertical staggering of space: Grids.CellCenter or Grids.CellFace for spaces with a vertical direction, and nothing for purely horizontal spaces.

Spaces.horizontal_space(space::AbstractSpace)

Return the horizontal space of space: space itself for a spectral element space, the wrapped horizontal space of an Spaces.ExtrudedFiniteDifferenceSpace or Spaces.MultiColumnFiniteDifferenceSpace, and the first level of a Spaces.FiniteDifferenceSpace (a Spaces.PointSpace).

Spaces.horizontal_grid(grid::Grids.AbstractGrid)

Return the horizontal grid underlying grid: a spectral element grid is its own horizontal grid, and a Grids.LevelGrid returns the horizontal grid of the extruded grid it is a level of. Used to decide whether two horizontal spaces share a grid (see Spaces.issubspace).

Spaces.vertical_grid(grid::Grids.AbstractGrid)

Return the vertical (finite difference) grid underlying grid: a finite difference grid is its own vertical grid, an extruded grid returns its vertical_grid, and a Grids.ColumnGrid returns the vertical grid of the extruded grid it is a column of. Used to decide whether two vertical spaces share a grid (see Spaces.issubspace).

center_space(space::FiniteDifferenceSpace)

Return the cell-centered space corresponding to space. If space is already cell-centered, return an equal space.

center_space(space::ExtrudedFiniteDifferenceSpace)

Return the cell-centered space corresponding to space. If space is already cell-centered, return an equal space.

face_space(space::FiniteDifferenceSpace)

Return the face-centered space corresponding to space. If space is already face-centered, return an equal space.

face_space(space::ExtrudedFiniteDifferenceSpace)

Return the face-centered space corresponding to space. If space is already face-centered, return an equal space.

has_horizontal(::AbstractSpace)

Return true if the space has a horizontal grid.

has_vertical(::AbstractSpace)

Return true if the space has a vertical grid.

nlevels(space::AbstractSpace)

Return the number of vertical levels of space at its staggering: the number of cell centers or cell faces for a staggered space, and 1 for a horizontal space.

ncolumns(space::AbstractSpace)

Return the number of columns of space on the local process.

ncolumns(::Field)

Return the number of columns of the space of field.

Spaces.undertype(space::AbstractSpace)

Return the underlying floating-point type of space, i.e. the number type of the coordinates and metric terms of its local geometry.

Spaces.coordinates_data(space::AbstractSpace)
Spaces.coordinates_data(grid::Grids.AbstractGrid)
Spaces.coordinates_data(staggering, grid::Grids.AbstractGrid)

Return the DataLayout of coordinates of space (or of grid at the given staggering): the coordinates of its local geometry.

Spaces.radius(space::AbstractSpace)

Return the radius [m] of the sphere on which space is defined, read from the radius of its global geometry (Spaces.global_geometry(space)). Throws an ArgumentError if the global geometry is not spherical, e.g. for spaces on planar or interval domains.

Spaces.issubspace(subspace::AbstractSpace, space::AbstractSpace)

Return true if fields on subspace can be broadcast against fields on space: subspace is space itself, the horizontal space or a level of an extruded space, or the vertical space or a column of it. Two spaces built on the same grid with different staggering are not subspaces of each other.

Spaces.eachslabindex(space::AbstractSpace)

Return an iterator over the indices of the slabs (single elements at a single level) of space: element indices h for a spectral element space, and (v, h) tuples of level and element indices for an Spaces.ExtrudedFiniteDifferenceSpace. Each index can be passed to slab(space, index...).

Spaces.area(space::Spaces.AbstractSpace)

Return the length, area, or volume of space, computed as the sum of the quadrature weights $W_i$ multiplied by the Jacobian determinants $J_i$:

\[\sum_i W_i J_i \approx \int_\Omega \, d \Omega\]

If space is distributed, this uses a ClimaComms.allreduce operation.

Spaces.local_area(space::Spaces.AbstractSpace)

Return the length, area, or volume of the part of space local to the current process. See Spaces.area.