# 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:

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:

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:

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:

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.