ClimaLand Domains

AbstractDomain{FT <:AbstractFloat}

An abstract type for domains.

The domain structs typically hold information regarding the bounds of the domain, the boundary condition type (periodic or not), and the spatial discretization.

Additionally, the domain struct holds the relevant spaces for that domain. For example, a 3D domain holds the center space (in terms of finite difference - the space corresponding to the centers of each element), and the top face space where surface fluxes are computed.

struct SphericalShell{FT} <: AbstractDomain{FT}
    radius::FT
    depth::FT
    dz_tuple::Union{Tuple{FT, FT}, Nothing}
    nelements::Tuple{Int, Int}
    npolynomial::Int
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (non-radial directions) x a 1d finite difference space (radial direction), and the resulting coordinate field.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• radius: The radius of the shell

• depth: The radial extent of the shell

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• nelements: The number of elements to be used in the non-radial and radial directions

• npolynomial: The polynomial order to be used in the non-radial directions

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields and field data associated with the coordinates of the domain that are useful to store

struct SphericalSurface{FT} <: AbstractDomain{FT}
    radius::FT
    nelements::Tuple{Int, Int}
    npolynomial::Int
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (non-radial directions) and the resulting coordinate field.

space is a NamedTuple holding the surface space (in this case, the entire SphericalSurface space).

Fields

• radius: The radius of the surface

• nelements: The number of elements to be used in the non-radial directions

• npolynomial: The polynomial order to be used in the non-radial directions

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface (SphericalSurface) space

struct HybridBox{FT} <: AbstractDomain{FT}
    xlim::Tuple{FT, FT}
    ylim::Tuple{FT, FT}
    zlim::Tuple{FT, FT}
    longlat::Union{Nothing, Tuple{FT, FT}},
    dz_tuple::Union{Tuple{FT, FT}, Nothing}
    nelements::Tuple{Int, Int, Int}
    npolynomial::Int
    periodic::Tuple{Bool, Bool}
end

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space (horizontal) x a 1d finite difference space (vertical), and the resulting coordinate field. This domain is not periodic along the z-axis. Note that no-flow boundary conditions are supported in the horizontal.

When longlat is not nothing, assume that the box describes a region on the globe centered around the long and lat.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• xlim: Domain interval limits along x axis, in meters or degrees (if latlong != nothing)

• ylim: Domain interval limits along y axis, in meters or degrees (if latlong != nothing)

• zlim: Domain interval limits along z axis, in meters

• longlat: When not nothing, a Tuple that contains the center long and lat.

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• nelements: Number of elements to discretize interval, (nx, ny,nz)

• npolynomial: Polynomial order for the horizontal directions

• periodic: Flag indicating periodic boundaries in horizontal

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields and field data associated with the coordinates of the domain that are useful to store

Column{FT} <: AbstractDomain{FT}

A struct holding the necessary information to construct a domain, a mesh, a center and face space, etc. for use when a finite difference in 1D is suitable, as for a soil column model.

space is a NamedTuple holding the surface space (in this case, the top face space) and the center space for the subsurface. These are stored using the keys :surface and :subsurface.

Fields

• zlim: Domain interval limits, (zmin, zmax), in meters

• nelements: Number of elements used to discretize the interval

• dz_tuple: Tuple for mesh stretching specifying target (dzbottom, dztop) (m). If nothing, no stretching is applied.

• boundary_names: Boundary face identifiers

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface space and subsurface center space

• fields: Fields and field data associated with the coordinates of the domain that are useful to store

Plane{FT} <: AbstractDomain{FT}

A struct holding the necessary information to construct a domain, a mesh, a 2d spectral element space, and the resulting coordinate field.

When longlat is not nothing, the plane is assumed to be centered around these coordinates. In this case, the curvature of the Earth is not accounted for.

longlat are in degrees, with longitude going from -180 to 180.

:warning: Only independent columns are supported! (No lateral flow).

space is a NamedTuple holding the surface space (in this case, the entire Plane space).

Fields

• xlim: Domain interval limits along x axis, in meters or degrees (if latlong != nothing)

• ylim: Domain interval limits along y axis, in meters or degrees (if latlong != nothing)

• longlat: When not nothing, a Tuple that contains the center long and lat (in degrees, with long from -180 to 180).

• nelements: Number of elements to discretize interval, (nx, ny)

• periodic: Flags for periodic boundaries. Only periodic or no lateral flow is supported.

• npolynomial: Polynomial order for both x and y

• space: A NamedTuple of associated ClimaCore spaces: in this case, the surface(Plane) space

Point{FT} <: AbstractDomain{FT}

A domain for single column surface variables. For models such as ponds, snow, plant hydraulics, etc. Enables consistency in variable initialization across all domains.

space is a NamedTuple holding the surface space (in this case, the Point space).

Fields

• z_sfc: Surface elevation relative to a reference (m)

• space: A NamedTuple of associated ClimaCore spaces: in this case, the Point (surface) space

global_domain(
FT;
apply_mask = true,
mask_threshold = 0.5,
nelements = (101, 15),
dz_tuple = (10.0, 0.05),
depth = 50.0,
npolynomial = 0,
context = ClimaComms.context(),
filepath = landseamask_file_path(;context),
regridder_type = :InterpolationsRegridder,
extrapolation_bc = (
    Interpolations.Periodic(),
    Interpolations.Flat(),
    Interpolations.Flat(),
),
interpolation_method = Interpolations.Constant()

)

Helper function to create a SphericalShell domain with (101,15) elements, a depth of 50m, vertical layering ranging from 0.05m in depth at the surface to 10m at the bottom of the domain, with npolynomial = 0 and GL quadrature.

npolynomial determines the order of polynomial base to use for the spatial discretization, which is correlated to the spatial resolution of the domain.

When npolynomial is zero, the element is equivalent to a single point. In this case, the resolution of the model is sqrt((360180)/(1011016)). The factor of 6 arises because there are 101x101 elements per side of the cubed sphere, meaning 6101*101 for the entire globe.

When npolynomial is greater than 1, a Gauss-Legendre-Lobotto quadrature is used, with npolynomial + 1 points along the element. In this case, there are always points two points on the boundaries for each direction with the other points in the interior. These points are not equally spaced.

In practice, there is no reason to use npolynomial greater than 1 in the current version of ClimaLand. To increase resolution, we recommend increasing the number of elements rather than increasing the polynomial order.

coordinates(domain::AbstractDomain)

Returns the coordinate fields for the domain as a NamedTuple.

The returned coordinates are stored with keys :surface, :subsurface, e.g. as relevant for the domain.

Domains.coordinates(model::AbstractLandModel)

Returns a NamedTuple of the unique set of coordinates for the LSM model, where the unique set is taken over the coordinates of all of the subcomponents.

For example, an LSM with a single layer snow model, multi-layer soil model, and canopy model would have a coordinate set corresponding to the coordinates of the surface (snow), the subsurface coordinates (soil) and the coordinates of the surface (canopy). This would return the coordinates of the surface and subsurface. These are distinct because the subsurface coordinates correspond to the centers of the layers, while the surface corresponds to the top face of the domain.

obtain_surface_space(cs::ClimaCore.Spaces.AbstractSpace)

Returns the surface space, if applicable, for the center space cs.

obtain_surface_space(cs::ClimaCore.Spaces.CenterExtrudedFiniteDifferenceSpace)

Returns the horizontal space for the CenterExtrudedFiniteDifferenceSpace cs.

obtain_surface_space(cs::ClimaCore.Spaces.FiniteDifferenceSpace)

Returns the top level of the face space corresponding to the input space cs.

obtain_surface_domain(d::AbstractDomain) where {FT}

Default method throwing an error; any domain with a corresponding domain should define a new method of this function.

obtain_surface_domain(c::Column{FT}) where {FT}

Returns the Point domain corresponding to the top face (surface) of the Column domain c.

obtain_surface_domain(b::HybridBox{FT}) where {FT}

Returns the Plane domain corresponding to the top face (surface) of the HybridBox domain b.

obtain_surface_domain(s::SphericalShell{FT}) where {FT}

Returns the SphericalSurface domain corresponding to the top face (surface) of the SphericalShell domain s.

top_face_to_surface(face_field::ClimaCore.Fields.Field, surface_space)

Creates and returns a ClimaCore.Fields.Field defined on the space corresponding to the surface of the space on which face_field is defined, with values equal to the those at the level of the top face.

Given a face_field defined on a 3D extruded face finite difference space, this would return a 2D field corresponding to the surface, with values equal to the topmost level.

linear_interpolation_to_surface!(sfc_field, center_field, z, Δz_top)

Linearly interpolate the center field center_field to the surface defined by the top face coordinate of z with a center to face distance Δz_top in the first layer; updates the sfc_field on the surface (face) space in place.

get_Δz(z::ClimaCore.Fields.Field)

A function to return a tuple containing the distance between the top boundary and its closest center, and the bottom boundary and its closest center, both as Fields. It also returns the widths of each layer as a field.

horizontal_resolution_degrees(domain::AbstractDomain)

Return a tuple with the approximate resolution on the domain in degrees along the two directions.

For boxes and planes, the order is (latitude, longitude).

Examples

julia> using ClimaLand

julia> domain = ClimaLand.Domains.SphericalShell(;
        radius = 6300e3,
        depth = 15.,
        nelements = (10, 3),
        dz_tuple = ((1.0, 0.05)));

julia> ClimaLand.Domains.average_horizontal_resolution_degrees(domain)
(9.0, 9.0)

julia> domain = ClimaLand.Domains.Plane(;
        xlim = (50000.0, 80000.),
        ylim = (30000.0, 40000.),
        longlat = (-118.14452, 34.14778),
        nelements = (20, 3));

julia> round.(ClimaLand.Domains.average_horizontal_resolution_degrees(domain), digits = 3)
(0.031, 0.389)