MOM documentation update

docs/equations.rst

@@ -6,8 +6,9 @@ hydrostatic primitive equations (either Boussinesq or non-Boussinesq).
 
 We present the equations starting from the hydrostatic Boussinesq equation in
 height coordinates and progress through vector-invariant and
-general-coordinate equations to the final equations used in the A.L.E.
-algorithm, taken from :cite:`Adcroft2019`.
+general-coordinate equations to the final equations used in the
+vertical Lagrangian algorithm, taken from
+:cite:`Adcroft2019` and :cite:`Griffies_Adcroft_Hallberg2020`.
 
 .. toctree::
     :maxdepth: 2

src/ALE/_ALE.dox

@@ -127,14 +127,14 @@ tracer equation (\f$C\f$ is an arbitrary tracer) can be summarized as
 \\
  \delta_{r} w^{\scriptstyle{\mathrm{grid}}}
  &= -\nabla_{r} \cdot [h \, \mathbf{u}]^{(n)}
- &\mbox{layer motion via convergence of horz advection}
+ &\mbox{layer motion via horz conv}
 \\
  h^{\dagger} &= h^{(n)} + \Delta t \, \delta_{r} w^{\scriptstyle{\mathrm{grid}}}
 = h^{(n)} - \Delta t \, \nabla_{r} \cdot [h \, \mathbf{u}]^{(n)}
- &\mbox{horz advection thickness update}
+ &\mbox{update thickness via horz advect}
 \\
  [h \, C]^{\dagger} &= [h \, C]^{(n)} -\Delta t \, \nabla_{r} \cdot [ h \, C \, \mathbf{u} ]^{(n)}
- &\mbox{horz advection tracer update}
+ &\mbox{update tracer via horz advect}
 \\
  h^{(n+1)} &=  h^{\scriptstyle{\mathrm{target}}}
  &\mbox{regrid to the target grid}
@@ -143,11 +143,11 @@ tracer equation (\f$C\f$ is an arbitrary tracer) can be summarized as
  &\mbox{diagnose dia-surface transport}
 \\
  [h \, C]^{(n+1)} &= [h \, C]^{\dagger}  - \Delta t  \, \delta_{r} ( w^{(\dot{r})} \, C^{\dagger})
- &\mbox{remap tracer using dia-surface transport}
+ &\mbox{remap tracer via dia-surface transport}
 \f}
 The first three equations constitute the Lagrangian portion of the
 algorithm.  In particular, the second equation provides an
-intermediate or ``predictor'' value for the updated thickness,
+intermediate or predictor value for the updated thickness,
 \f$h^{\dagger}\f$, resulting from the vertical Lagrangian update.
 Similarly, the third equation performs a Lagrangian update of the
 thickness-weighted tracer to intermediate values, again operationally
@@ -166,8 +166,8 @@ dia-surface velocity according to
 \f}
 This step, and the remaining step for tracers, constitute the
 remapping portion of the algorithm.  For example, if the prescribed
-coordinate surfaces are geopotentials, then \f$w^{(\dot{r})} = w\f$
-and \f$h^{\scriptstyle{\mathrm{target}}} = h^{(n)}\f$, in which case the
+coordinate surfaces are geopotentials, then \f$w^{(\dot{r})}\f$ and
+\f$h^{\scriptstyle{\mathrm{target}}} = h^{(n)}\f$, in which case the
 remap step reduces to Cartesian vertical advection.
 
 Within the above framework for evolving the ocean state, we make use

src/ALE/_ALE_timestep.dox

@@ -49,15 +49,14 @@ deformed coordinate grid has been deleted:
 The new layer thicknesses, \f$h_k\f$, are computed and then the layers
 are populated with the new velocities and tracers
 \f{align}
-  % h_k^{\mbox{new}} %= \nabla_k z_{\mbox{coord}} \\
-  \sum h_k^{\mbox{new}} &= \sum h_k^{\mbox{old}}
+  \sum h_k^{\scriptstyle{\mathrm{new}}} &= \sum h_k^{\scriptstyle{\mathrm{old}}}
 \\
-  \mathbf{u}_k^{\mbox{new}}
+  \mathbf{u}_k^{\scriptstyle{\mathrm{new}}}
   &= \frac{1}{h_k}
-  \int_{z_{k + \frac{1}{2}}}^{z_{k + \frac{1}{2}} + h_k} \mathbf{u}^{\mbox{old}}(z') \, \mathrm{d}z'
+  \int_{z_{k + 1/2}}^{z_{k + 1/2} + h_k} \mathbf{u}^{\scriptstyle{\mathrm{old}}}(z') \, \mathrm{d}z'
 \\
-  \theta^{\mbox{new}} &= \frac{1}{h_k}
-  \int_{z_{k + \frac{1}{2}}}^{z_{k + \frac{1}{2}} + h_k} \theta^{\mbox{old}}(z') \, \mathrm{d}z'
+  \theta_k^{\scriptstyle{\mathrm{new}}}  &= \frac{1}{h_k}
+  \int_{z_{k + 1/2}}^{z_{k + 1/2} + h_k} \theta^{\scriptstyle{\mathrm{old}}}(z') \, \mathrm{d}z'
 \f}
 
 */

src/core/_General_coordinate.dox

@@ -138,7 +138,7 @@ continuous-in-the-vertical form for brevity; the exact discretization
 is detailed in \cite adcroft2008 and
 \cite Griffies_Adcroft_Hallberg2020.  The \f$1/h\f$ and \f$h\f$ appearing in
 the horizontal momentum equation are carefully handled in the code to
-ensure proper cancellation even when the layer thickness goes to zero;
+ensure proper cancellation even when the layer thickness goes to zero
 i.e., l'Hospital's rule is respected.
 
 The MOM6 time-stepping algorithm integrates the above layer-averaged

src/core/_Governing.dox

@@ -154,7 +154,7 @@ geopotential coordinates
    + (f + \zeta) \hat{\mathbf{z}} \times \mathbf{u}
    \right]
   &= -\nabla_{z} (p + K) - \rho \, \nabla_{z} \Phi +  \rho_{o} \, \mathbf{\mathcal{F}}
- &\mbox{vector-invariant horz velocity}
+ &\mbox{vector-inv horz velocity}
 \\
   \rho \, \partial_{z} \Phi + \partial_{z} p &= 0 &\mbox{hydrostatic}
 \\
@@ -164,7 +164,7 @@ geopotential coordinates
   \\
   \partial_t \theta + \nabla_z \cdotp ( \mathbf{u} \, \theta ) + \partial_z ( w \, \theta )
    &= \mathbf{\mathcal{N}}_\theta^\gamma - \partial_{z} J_\theta^{(z)}
-   &\mbox{potential/Conservative temp}
+   &\mbox{potential/Cons temp}
   \\
   \partial_t S + \nabla_z \cdotp ( \mathbf{u} \, S ) + \partial_z (w \, S)
    &= \mathbf{\mathcal{N}}_S^\gamma - \partial_{z} J_S^{(z)}

src/core/_Notation.dox

@@ -41,21 +41,23 @@ used in the Boussinesq equation of state.
 
 \section vector_notation Vector notation
 
-The three-dimensional velocity vector is denoted \f$\boldsymbol{v}\f$
+The three-dimensional velocity vector is denoted \f$\mathbf{v}\f$
 and it is decomposed into its horizontal and vertical components according to
-  \f[\boldsymbol{v}
-  = \boldsymbol{u} + \hat{\boldsymbol{z}} w
-  = \hat{\boldsymbol{x}} u + \hat{\boldsymbol{y}} v + \hat{\boldsymbol{z}} w,
- \f]
-where \f$\hat{\boldsymbol{z}}\f$ is the unit vector pointed in the
-upward vertical direction and \f$\boldsymbol{u} = (u, v, 0)\f$ is the
+\f{align}
+\mathbf{v}
+  = \mathbf{u} + \hat{\mathbf{z}} \, w
+  = \hat{\mathbf{x}} \, u + \hat{\mathbf{y}} \, v + \hat{\mathbf{z}} \, w,
+ \f}
+where \f$\hat{\mathbf{z}}\f$ is the unit vector pointed in the
+upward vertical direction and \f$\mathbf{u} = (u, v, 0)\f$ is the
 horizontal component of velocity normal to the vertical.
 
 The three-dimensional gradient operator is denoted \f$\nabla\f$, and it is decomposed into
 its horizontal and vertical components according to
-  \f[\nabla
-   = \nabla_z + \hat{\boldsymbol{z}} \partial_z
-   = \hat{\boldsymbol{x}} \partial_x + \hat{\boldsymbol{y}} \partial_y + \hat{\boldsymbol{z}} \partial_z.
-  \f]
+\f{align}
+\nabla
+   = \nabla_z + \hat{\mathbf{z}} \, \partial_z
+   = \hat{\mathbf{x}} \, \partial_x + \hat{\mathbf{y}} \, \partial_y + \hat{\mathbf{z}} \, \partial_z.
+  \f}
 
 */