Update user's guide

docs/users_guide/ocean/framework/vertical.md

@@ -24,6 +24,10 @@ 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
 
@@ -35,12 +39,12 @@ 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`, `60layerPHC`, and
-`100layerE3SMv1`.
+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` and `max_layer_thickness` depends grid type and is
-described below.
+`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 {ref}`ocean-vert-3d`, described below.
@@ -117,6 +121,61 @@ min_layer_thickness = 2.0
 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:
+
+$$
+z_0 = 0, \\
+z_{k+1} = z_k - \Delta z\left(k\right).
+$$
+
+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 v3:
+
+```cfg
+# 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
@@ -135,6 +194,22 @@ 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:
+```cfg
+# 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
@@ -171,13 +246,14 @@ 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).
+Currently, `z-star`, `z-level` and `sigma` vertical coordinates are supported
+(`coord_type`).  The `z-star` and `z-level` types support 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
@@ -193,7 +269,7 @@ Most ocean tasks currently use the z\* vertical coordinate
 by default.  Typically (in the absence of ice-shelf cavities), the initial
 "resting" grid uses a {ref}`ocean-z-level` coordinate.  As the sea-surface
 height evolves, the coordinate stretches and squashes in proportion to changes
-in the local watercolumn thickness.
+in the local water-column thickness.
 
 In configurations with {ref}`ocean-ice-shelf-cavities`, the ice draft
 (elevation of the ice shelf-ocean interface) also acts the sea-surface height
@@ -214,3 +290,10 @@ 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.
+
+(ocean-sigma)=
+
+### sigma
+
+The `sigma` coordinate is a terrain-following coordinate that stretches a 1D
+reference coordinate between `z = -bottomDepth` and `z = ssh`.