Vertical coordinate¶

The vertical coordinate used in most MPAS-Ocean test cases is determined by config options in the vertical_grid section of the config file:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = 100layerE3SMv1

# Number of vertical levels
vert_levels = 100

# Depth of the bottom of the ocean
bottom_depth = 2500.0

# The minimum layer thickness
min_layer_thickness = 3.0

# The maximum layer thickness
max_layer_thickness = 500.0

# The characteristic number of levels over which the index_tanh_dz
# transition between the min and max occurs
transition_levels = 28

# The type of vertical coordinate (e.g. z-level, z-star)
coord_type = z-star

# Whether to use "partial" or "full", or "None" to not alter the topography
partial_cell_type = full

# The minimum fraction of a layer for partial cells
min_pc_fraction = 0.1

The vertical coordinate is typically defined based on a 1D reference grid. Possible 1D grid types are: uniform, tanh_dz, index_tanh_dz, 60layerPHC, 80layerE3SMv1, and 100layerE3SMv1.

The meaning of the config options vert_levels, bottom_depth, min_layer_thickness, max_layer_thickness, and transition_levels depends grid type and is described below.

The options coord_type, partial_cell_type and min_pc_fraction relate to 3D vertical coordinates, described below.

1D Grid type¶

uniform¶

Uniform vertical grids have vertical layers all of the same thickness. The layer thickness is simply bottom_depth (the positive depth of the bottom interface of the deepest layer) divided by the number of layers (vert_levels). In this example, the vertical grid would have 10 vertical layers, each 100 m thick.

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = uniform

# Number of vertical levels
vert_levels = 10

# Depth of the bottom of the ocean
bottom_depth = 1000.0

tanh_dz¶

This vertical coordinate is a variant on Stewart et al. (2017). Layer thickness is defined by:

\[\Delta z\left(z\right) = (\Delta z_2 - \Delta z_1) \mathrm{tanh}\left(\frac{-\pi z}{\Delta}\right) + \Delta z_1,\]

where \(\Delta z_1\) is the value of the layer thickness \(\Delta z\) at \(z = 0\) and \(\Delta z_2\) is the same as \(z \rightarrow \infty\). Interface locations z_k are defined by:

\[\begin{split}z_0 = 0, \\ z_{k+1} = z_k - \Delta z\left(z_k\right).\end{split}\]

We use a root finder to solve for \(\Delta\), such that \(z_{n_z+1} = -H_\mathrm{bot}\), where \(n_z\) is nVertLevels, the number of vertical levels (one less than the number of layer interfaces) and \(H_\mathrm{bot}\) is bottom_depth, the depth of the seafloor.

The following config options are all required. This is an example of a 64-layer vertical grid that has been explored in E3SM v2:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = tanh_dz

# Number of vertical levels
vert_levels = 64

# Depth of the bottom of the ocean
bottom_depth = 6000.0

# The minimum layer thickness
min_layer_thickness = 2.0

# The maximum layer thickness
max_layer_thickness = 210.0

index_tanh_dz¶

This is similar to tanh_dz but the hyperbolic tangent function is defined in layer index space rather than physical depth. Layer thickness is defined by:

\[\Delta z\left(k\right) = (\Delta z_2 - \Delta z_1) \mathrm{tanh}\left[\frac{\pi \left(k - k_0\right)}{\Delta}\right]+ \Delta z_1,\]

where \(\Delta z_1\) (min_layer_thickness) is the value of the layer thickness \(\Delta z\) at \(z = 0\) and \(\Delta z_2\) (max_layer_thickness) is the same as \(z \rightarrow \infty\). The vertical layer index is k, Delta (transition_levels) is the number of vertical levels over which the tanh transitions from the finer to the coarser resolution, and \(k_0\) is the origin in vertical index space of the transition. Interface locations z_k are defined by:

\[\begin{split}z_0 = 0, \\ z_{k+1} = z_k - \Delta z\left(k\right).\end{split}\]

We use a root finder to solve for \(k_0\), such that \(z_{n_z+1} = -H_\mathrm{bot}\), where \(n_z\) is vert_levels, the number of vertical levels (one less than the number of layer interfaces) and \(H_\mathrm{bot}\) is bottom_depth, the depth of the seafloor.

The following config options are all required. This is an example of a 64-layer vertical grid that has been explored in E3SM v2:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = index_tanh_dz

# Number of vertical levels
vert_levels = 64

# Depth of the bottom of the ocean
bottom_depth = 5500.0

# The minimum layer thickness
min_layer_thickness = 10.0

# The maximum layer thickness
max_layer_thickness = 250.0

# The characteristic number of levels over which the index_tanh_dz
# transition between the min and max occurs
transition_levels = 28

60layerPHC¶

This is the vertical grid used by the Polar science center Hydrographic Climatology (PHC). Layer thicknesses vary over 60 layers from 10 m at the surface to 250 m at the seafloor, which is at 5500 m depth. To get the default grid, use:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = 60layerPHC

If the bottom_depth option is also defined, the depths will be renormalized so that bottom of the deepest layer is at z = -bottom_depth

80layerE3SMv1¶

This is the vertical grid was used in some E3SM v1 and v2 meshes, such as the ARRM10to60 mesh. Layer thicknesses vary over 80 layers from 2 m at the surface to 146 m at the seafloor, which is at 5550 m depth. To get the default grid, use:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = 80layerE3SMv1

If the bottom_depth option is also defined, the depths will be renormalized so that bottom of the deepest layer is at z = -bottom_depth.

100layerE3SMv1¶

This is the vertical grid was used in some E3SM v1 experiments. Layer thicknesses vary over 100 layers from 1.51 m at the surface to 221 m at the seafloor, which is at 6000 m depth. To get the default grid, use:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = 100layerE3SMv1

If the bottom_depth option is also defined, the depths will be renormalized so that bottom of the deepest layer is at z = -bottom_depth. This is the default approach in the ziso test group:

# Options related to the vertical grid
[vertical_grid]

# the type of vertical grid
grid_type = 100layerE3SMv1

# Depth of the bottom of the ocean
bottom_depth = 2500.0

In this case, the thickness of the 100 layers vary between ~0.63 m and 92.1 m, with the sea floor at 2500 m.

3D vertical coordinates¶

Currently, z-star and z-level vertical coordinates are supported (coord_type). Each supports 3 options for partial_cell_type: full meaning the topography (bottom depth and sea-surface height) are expanded so that all layers have their full thickness; partial meaning that cells adjacent to the topography are allowed to be a small fraction of a full layer thickness; or None to indicate that no alteration is needed for full or partial cells (typically only in cases where the topography is already flat).

If partial_cell_type = partial, the option min_pc_fraction indicates the smallest fraction of a layer that a partial cell is allowed to have before it must either be expanded to the minimum or collapsed to the next adjacent valid layer (whichever would cause the smallest change).

z-star¶

Most MPAS-Ocean test cases currently use the z* vertical coordinate (Adcroft and Campin, 2004) by default. Typically (in the absence of ice-shelf cavities), the initial “resting” grid uses a z-level coordinate. As the sea-surface height evolves, the coordinate stretches and squashes in proportion to changes in the local watercolumn thickness.

In configurations with Ice shelf-cavities, the ice draft (elevation of the ice shelf-ocean interface) also acts the sea-surface height for a z-star coordinate. This means that the initial layers are squashed significantly from their “resting” thickness under ice shelves as if they were being pressed down by the weight of the ice.

z-level¶

In the absence of Ice shelf-cavities, the z-level coordinate in MPAS-Ocean is the same as the z-star coordinate.

When ice-shelf cavities are included, rather than depressing the vertical grid under the weight of the ice, the z-level coordinate used top cells to mask out parts of the mesh as “land” in the same way that cells below the batymetry are masked as land. The topography at the top of the ocean is represented by “stair steps”, using either “full” or “partial” cells to represent these steps in exactly the same way as at the seafloor.