Merge pull request #901 from navidcy/UpdatesDocEquations

Updates doc equations

docs/README.md

@@ -38,11 +38,11 @@ If you are building the full generated sphinx documentation you will need the fo
 
 (.e.g `apt-get install libxml2-dev libxslt-dev`)
 
-Before running sphinc (`make html`) you will need to issue:
+Before running sphinx (`make html`) you will need to issue:
 ```bash
 pip install -r requirements.txt
 ```
 
 ## Credits
 
-The sphinx documentation of MOM6 is made possible by modifications by Angus Gibson to two packages, [sphinx-fortran](https://github.com/angus-g/sphinx-fortran) and [autodoc_doxygen](https://github.com/angus-g/sphinxcontrib-autodoc_doxygen).
+The sphinx documentation of MOM6 is made possible by modifications by [Angus Gibson](https://github.com/angus-g) to two packages, [sphinx-fortran](https://github.com/angus-g/sphinx-fortran) and [autodoc_doxygen](https://github.com/angus-g/sphinxcontrib-autodoc_doxygen).

docs/equations/ALE-algorithm.rst

@@ -5,24 +5,24 @@ The semi-discrete, vertically integrated, Boussinesq hydrostatic equations of
 motion in general-coordinate :math:`r` are
 
 .. math::
-  D_t \vec{u} + f \hat{k} \wedge \vec{u} + \nabla_z \Phi + \frac{1}{\rho_o} \nabla_z p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \rho \delta_k \Phi + \delta_k p &= 0 \\
-  \partial_t h + \nabla_r \cdot ( h \vec{u} ) + \delta_k ( z_r \dot{r} ) &= 0 \\
-  \partial_t h \theta + \nabla_r \cdot ( h \vec{u} \theta ) + \delta_k ( z_r \dot{r} \theta ) &= \nabla \cdot \vec{Q}_\theta \\
-  \partial_t h S + \nabla_r \cdot ( h \vec{u} S ) + \delta_k ( z_r \dot{r} S ) &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
+  D_t \boldsymbol{u} + f \widehat{\boldsymbol{k}} \wedge \boldsymbol{u} + \frac{\rho}{\rho_o}\boldsymbol{\nabla}_z \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla}_z p &= \boldsymbol{\nabla} \cdot \boldsymbol{\underline{\tau}} ,\\
+  \rho \delta_k \Phi + \delta_k p &= 0 ,\\
+  \partial_t h + \nabla_r \cdot ( h \boldsymbol{u} ) + \delta_k ( z_r \dot{r} ) &= 0 ,\\
+  \partial_t (h \theta) + \nabla_r \cdot ( h \boldsymbol{u} \theta ) + \delta_k ( z_r \dot{r} \theta ) &= \boldsymbol{\nabla} \cdot \boldsymbol{Q}_\theta ,\\
+  \partial_t (h S) + \nabla_r \cdot ( h \boldsymbol{u} S ) + \delta_k ( z_r \dot{r} S ) &= \boldsymbol{\nabla} \cdot \boldsymbol{Q}_S ,\\
+  \rho &= \rho(S, \theta, z) .
 
 The Arbitrary-Lagrangian-Eulerian algorithm we use is quasi-Lagrangian in
 that in the first (Lagrangian) phase, regardless of the current mesh (or coordinate
 :math:`r`) we integrate the equations forward with :math:`\dot{r}=0`, i.e.:
 
 .. math::
-  D_t \vec{u} + f \hat{k} \wedge \vec{u} + \nabla_z \Phi + \frac{1}{\rho_o} \nabla_z p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \rho \delta_k \Phi + \delta_k p &= 0 \\
-  \partial_t h + \nabla_r \cdot ( h \vec{u} ) &= 0 \\
-  \partial_t h \theta + \nabla_r \cdot ( h \vec{u} \theta ) &= \nabla \cdot \vec{Q}_\theta \\
-  \partial_t h S + \nabla_r \cdot ( h \vec{u} S ) &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
+  D_t \boldsymbol{u} + f \widehat{\boldsymbol{k}} \wedge \boldsymbol{u} + \frac{\rho}{\rho_o}\boldsymbol{\nabla}_z \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla}_z p &= \boldsymbol{\nabla} \cdot \boldsymbol{\underline{\tau}} ,\\
+  \rho \delta_k \Phi + \delta_k p &= 0 ,\\
+  \partial_t h + \nabla_r \cdot ( h \boldsymbol{u} ) &= 0 ,\\
+  \partial_t (h \theta) + \nabla_r \cdot ( h \boldsymbol{u} \theta ) &= \boldsymbol{\nabla} \cdot \boldsymbol{Q}_\theta ,\\
+  \partial_t (h S) + \nabla_r \cdot ( h \boldsymbol{u} S ) &= \boldsymbol{\nabla} \cdot \boldsymbol{Q}_S ,\\
+  \rho &= \rho(S, \theta, z) .
 
 Notice that by setting :math:`\dot{r}=0` all the terms with the metric
 :math:`z_r` disappeared.
@@ -31,4 +31,3 @@ After a finite amount of time, the mesh (:math:`h`) may become very distorted
 or unrelated to the intended mesh. At any point in time, we can simply define
 a new mesh and remap from the current mesh to the new mesh without an
 explicit change in the physical state.
-

docs/equations/general_coordinate.rst

@@ -9,9 +9,9 @@ The Boussinesq hydrostatic equations of motion in general-coordinate
 :math:`r` are
 
 .. math::
-  D_t \vec{u} + f \hat{k} \wedge \vec{u} + \nabla_z \Phi + \frac{1}{\rho_o} \nabla_z p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \rho \partial_z \Phi + \partial_z p &= 0 \\
-  \partial_t z_r + \nabla_r \cdot ( z_r \vec{u} ) + \partial_r ( z_r \dot{r} ) &= 0 \\
-  \partial_t z_r \theta + \nabla_r \cdot ( z_r \vec{u} \theta ) + \partial_r ( z_r \dot{r} \theta ) &= \nabla \cdot \vec{Q}_\theta \\
-  \partial_t z_r S + \nabla_r \cdot ( z_r \vec{u} S ) + \partial_r ( z_r \dot{r} S ) &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
+  D_t \boldsymbol{u} + f \widehat{\boldsymbol{k}} \wedge \boldsymbol{u} + \frac{\rho}{\rho_o}\boldsymbol{\nabla}_z \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla}_z p &= \boldsymbol{\nabla} \cdotp \boldsymbol{\underline{\tau}} ,\\
+  \rho \partial_z \Phi + \partial_z p &= 0 ,\\
+  \partial_t z_r + \boldsymbol{\nabla}_r \cdotp ( z_r \boldsymbol{u} ) + \partial_r ( z_r \dot{r} ) &= 0 ,\\
+  \partial_t (z_r \theta) + \boldsymbol{\nabla}_r \cdotp ( z_r \boldsymbol{u} \theta ) + \partial_r ( z_r \dot{r} \theta ) &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_\theta ,\\
+  \partial_t (z_r S) + \boldsymbol{\nabla}_r \cdotp ( z_r \boldsymbol{u} S ) + \partial_r ( z_r \dot{r} S ) &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_S ,\\
+  \rho &= \rho(S, \theta, z) .

docs/equations/governing.rst

@@ -6,39 +6,39 @@ Governing equations
 The Boussinesq hydrostatic equations of motion in height coordinates are
 
 .. math::
-  D_t \vec{u} + f \hat{k} \wedge \vec{u} + \nabla_z \Phi + \frac{1}{\rho_o} \nabla_z p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \rho \partial_z \Phi + \partial_z p &= 0 \\
-  \nabla_z \cdot \vec{u} + \partial_z w &= 0 \\
-  D_t \theta &= \nabla \cdot \vec{Q}_\theta \\
-  D_t S &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
- 
-where notation is described in :ref:`equations-notation`. :math:`\vec{\underline{\tau}}` is the stress tensori and
-:math:`\vec{Q}_\theta` and :math:`\vec{Q}_S` are fluxes of heat and salt respectively.
+  D_t \boldsymbol{u} + f \widehat{\boldsymbol{k}} \wedge \boldsymbol{u} + \frac{\rho}{\rho_o} \boldsymbol{\nabla}_z \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla}_z p &= \boldsymbol{\nabla} \cdotp \boldsymbol{\underline{\tau}} , \\
+  \rho \partial_z \Phi + \partial_z p &= 0 , \\
+  \boldsymbol{\nabla}_z \cdotp \boldsymbol{u} + \partial_z w &= 0 , \\
+  D_t \theta &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_\theta , \\
+  D_t S &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_S , \\
+  \rho &= \rho(S, \theta, z) ,
+
+where notation is described in :ref:`equations-notation`. :math:`\boldsymbol{\underline{\tau}}` is the stress tensori and
+:math:`\boldsymbol{Q}_\theta` and :math:`\boldsymbol{Q}_S` are fluxes of heat and salt respectively.
 
 
 .. :ref:`vector_invariant`
 The total derivative is
 
 .. math::
-  D_t &\equiv \partial_t + \vec{v} \cdot \nabla \\
-      &= \partial_t + \vec{u} \cdot \nabla_z + w \partial_z
+  D_t & \equiv \partial_t + \boldsymbol{v} \cdotp \boldsymbol{\nabla} \\
+      &= \partial_t + \boldsymbol{u} \cdotp \boldsymbol{\nabla}_z + w \partial_z .
 
 The non-divergence of flow allows a total derivative to be re-written in flux form:
 
 .. math::
-  D_t \theta &= \partial_t + \nabla \cdot ( \vec{v} \theta ) \\
-             &= \partial_t + \nabla_z \cdot ( \vec{u} \theta ) + \partial_z ( w \theta )
+  D_t \theta &= \partial_t + \boldsymbol{\nabla} \cdotp ( \boldsymbol{v} \theta ) \\
+             &= \partial_t + \boldsymbol{\nabla}_z \cdotp ( \boldsymbol{u} \theta ) + \partial_z ( w \theta ) .
 
 The above equations of motion can thus be written as:
 
 .. math::
-  D_t \vec{u} + f \hat{k} \wedge \vec{u} + \nabla_z \Phi + \frac{1}{\rho_o} \nabla_z p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \rho \partial_z \Phi + \partial_z p &= 0 \\
-  \nabla_z \cdot \vec{u} + \partial_z w &= 0 \\
-  \partial_t \theta + \nabla_z \cdot ( \vec{u} \theta ) + \partial_z ( w \theta ) &= \nabla \cdot \vec{Q}_\theta \\
-  \partial_t S + \nabla_z \cdot ( \vec{u} S ) + \partial_z ( w S ) &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
+  D_t \boldsymbol{u} + f \widehat{\boldsymbol{k}} \wedge \boldsymbol{u} + \frac{\rho}{\rho_o}\boldsymbol{\nabla}_z \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla}_z p &= \boldsymbol{\nabla} \cdotp \boldsymbol{\underline{\tau}} ,\\
+  \rho \partial_z \Phi + \partial_z p &= 0 ,\\
+  \boldsymbol{\nabla}_z \cdotp \boldsymbol{u} + \partial_z w &= 0 ,\\
+  \partial_t \theta + \boldsymbol{\nabla}_z \cdotp ( \boldsymbol{u} \theta ) + \partial_z ( w \theta ) &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_\theta ,\\
+  \partial_t S + \boldsymbol{\nabla}_z \cdotp ( \boldsymbol{u} S ) + \partial_z ( w S ) &= \nabla \cdotp \boldsymbol{Q}_S ,\\
+  \rho &= \rho(S, \theta, z) .
 
 .. toctree::
   vector_invariant_eqns

docs/equations/notation.rst

@@ -16,28 +16,28 @@ Horizontal components of velocity are indicated by :math:`u` and :math:`v` and v
 
 :math:`p` is pressure and :math:`\Phi` is geo-potential:
 
-.. math:
-  \Phi = g z
+.. math::
+  \Phi = g z .
 
 The thermodynamic state variables are usually salinity, :math:`S`, and potential temperature, :math:`\theta` or the absolute salinity and conservative temperature, depending on the equation of state. :math:`\rho` is in-situ density.
 
 Vector notation
 ---------------
 
-The three-dimensional velocity vector is denoted :math:`\vec{v}`
+The three-dimensional velocity vector is denoted :math:`\boldsymbol{v}`
 
 .. math::
-  \vec{v} = \vec{u} + \vec{k} w
+  \boldsymbol{v} = \boldsymbol{u} + \widehat{\boldsymbol{k}} w ,
 
-where :math:`\vec{k}` is the unit vector pointed in the upward vertical direction and :math:`\vec{u} = (u,v,0)` is the horizontal
+where :math:`\widehat{\boldsymbol{k}}` is the unit vector pointed in the upward vertical direction and :math:`\boldsymbol{u} = (u, v, 0)` is the horizontal
 component of velocity normal to the vertical.
 
 The gradient operator without a suffix is three dimensional:
 
 .. math::
-  \nabla = ( \nabla_z, \partial_z  ) .
+  \boldsymbol{\nabla} = ( \boldsymbol{\nabla}_z, \partial_z  ) .
 
 but a suffix indicates a lateral gradient along a surface of constant property indicated by the suffix:
 
 .. math::
-  \nabla_z = \left( \left. \partial_x \right|_z, \left. \partial_y \right|_z, 0 \right) .
+  \boldsymbol{\nabla}_z = \left( \left. \partial_x \right|_z, \left. \partial_y \right|_z, 0 \right) .

docs/equations/overview.rst

@@ -4,7 +4,7 @@ Equations
 The model equations are the layer-integrated vector-invariant form of the
 hydrostatic primitive equations (either Boussinesq or non-Boussinesq).
 
-We present the equations starting from the hydrostatic Boussinesq equation is
+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.

docs/equations/vector_invariant_eqns.rst

@@ -3,23 +3,23 @@
 Vector Invariant Equations
 ==========================
 
-MOM6 solve the momentum equations written in vector-invariant form.
+MOM6 solves the momentum equations written in vector-invariant form.
 
-An identity allows the total derivative of velocity to be written in the vector-invariant form:
+A vector identity allows the total derivative of velocity to be written in the vector-invariant form:
 
 .. math::
-  D_t \vec{u} &= \partial_t \vec{u} + \vec{v} \cdot \nabla \vec{u} \\
-              &= \partial_t \vec{u} + \vec{u} \cdot \nabla_z \vec{u} + w \partial_z \vec{u} \\
-              &= \partial_t \vec{u} + \left( \nabla \wedge \vec{u} \right) \wedge \vec{v} + \nabla \frac{1}{2} \left|\vec{u}\right|^2
+  D_t \boldsymbol{u} &= \partial_t \boldsymbol{u} + \boldsymbol{v} \cdotp \boldsymbol{\nabla} \boldsymbol{u} \\
+              &= \partial_t \boldsymbol{u} + \boldsymbol{u} \cdotp \boldsymbol{\nabla}_z \boldsymbol{u} + w \partial_z \boldsymbol{u} \\
+              &= \partial_t \boldsymbol{u} + \left( \boldsymbol{\nabla} \wedge \boldsymbol{u} \right) \wedge \boldsymbol{v} + \boldsymbol{\nabla} \underbrace{\frac{1}{2} \left|\boldsymbol{u}\right|^2}_{\equiv K} .
 
 The flux-form equations of motion in height coordinates can thus be written succinctly as:
 
 .. math::
-  \partial_t \vec{u} + \left( f \hat{k} + \nabla \wedge \vec{u} \right) \wedge \vec{v} + \nabla K
-  + \frac{\rho}{\rho_o} \nabla \Phi + \frac{1}{\rho_o} \nabla p &= \nabla \cdot \vec{\underline{\tau}} \\
-  \nabla_z \cdot \vec{u} + \partial_z w &= 0 \\
-  \partial_t \theta + \nabla_z \cdot ( \vec{u} \theta ) + \partial_z ( w \theta ) &= \nabla \cdot \vec{Q}_\theta \\
-  \partial_t S + \nabla_z \cdot ( \vec{u} S ) + \partial_z ( w S ) &= \nabla \cdot \vec{Q}_S \\
-  \rho &= \rho(S, \theta, z)
+  \partial_t \boldsymbol{u} + \left( f \widehat{\boldsymbol{k}} + \boldsymbol{\nabla} \wedge \boldsymbol{u} \right) \wedge \boldsymbol{v} + \boldsymbol{\nabla} K
+  + \frac{\rho}{\rho_o} \boldsymbol{\nabla} \Phi + \frac{1}{\rho_o} \boldsymbol{\nabla} p &= \boldsymbol{\nabla} \cdotp \boldsymbol{\underline{\tau}} ,\\
+  \boldsymbol{\nabla}_z \cdotp \boldsymbol{u} + \partial_z w &= 0 ,\\
+  \partial_t \theta + \boldsymbol{\nabla}_z \cdotp ( \boldsymbol{u} \theta ) + \partial_z ( w \theta ) &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_\theta ,\\
+  \partial_t S + \boldsymbol{\nabla}_z \cdotp ( \boldsymbol{u} S ) + \partial_z ( w S ) &= \boldsymbol{\nabla} \cdotp \boldsymbol{Q}_S ,\\
+  \rho &= \rho(S, \theta, z) ,
 
 where the horizontal momentum equations and vertical hydrostatic balance equation have been written as a single three-dimensional equation.