updated suggestions

Author: onzerem

docs/src/examples.md

@@ -1,85 +1,103 @@
 # Examples
 
-### Advection
+## 1D Column examples
 
-The 1D Column advection example in [`examples/column/advect.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/advect.jl).
+### Heat equation
 
-#### Equations and Discretizations
+The 1D Column heat example in [`examples/column/heat.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/heat.jl).
 
-Follows the advection equation
+#### Equations and discretizations
+
+Follows the heat equation
 
 ```math
 \begin{equation}
-  \frac{\partial \theta}{\partial t} = -\frac{\partial (v \theta)}{\partial z}
-\label{eq:1d-column-advection-continuity}
+  \frac{\partial T}{\partial t} = \alpha \cdot \nabla^2 T.
+\label{eq:1d-column-heat-continuity}
 \end{equation}
 ```
+
 This is discretized using the following
 
 ```math
 \begin{equation}
-  \frac{\partial \theta}{\partial t} \approx - D(v, \theta) 
-\label{eq:1d-column-advection-discrete}
+  \frac{\partial T}{\partial t} \approx \alpha \cdot D(G(T)).
+\label{eq:1d-column-heat-discrete}
 \end{equation}
 ```
 
 #### Prognostic Variables
 
-* ``\theta``: the scalar field
-* ``v``: the velocity field
-
-#### Tendencies 
+* ``\alpha``: thermal diffusivity measured in  $\frac{m^2}{s}$
+* ``T``: temperature
 
-The example code solves the equation for 4 different tendencies with the following discretizations:
+#### Differentiation Operators
 
-* Tendency 1: ``D = \partial(UB)``, where ``\partial`` is the [`face-to-center divergence`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) and $UB$ is the [`center-to-face upwind biased product`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.UpwindBiasedProductC2F) operator.
-* Tendency 2: Follows tendency 1, where ``D = \partial(UB)``. Similarly, ``\partial`` is the [`face-to-center divergence`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) and $UB$ is the [`center-to-face upwind biased product`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.UpwindBiasedProductC2F) operator. Tendency 2 also includes the [`center-to-center flux correction`](https://github.com/CliMA/ClimaCore.jl/blob/main/src/Operators/finitedifference.jl#L2617), `fcc`.
-* Tendency 3: $D = A$, where $A$ is the [`center-to-center vertical advection`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.AdvectionC2C) operator.
-* Tendency 4: Follows tendency 3, where $D = A$, the [`center-to-center vertical advection`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.AdvectionC2C). Tendency 4 also includes the [`center-to-center flux correction`](https://github.com/CliMA/ClimaCore.jl/blob/main/src/Operators/finitedifference.jl#L2617), `fcc`.
+ * ``D`` is the [face-to-center divergence](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) operator, called `divf2c` in the example code
+ * ``G`` is the [center-to-face gradient](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.GradientC2F) operator, called `gradc2f` in the example code
 
 #### Set Up
 
-This test case is set up in a 1D column domain ``z \in [0, 4\pi]``, discretized into a mesh of 128 elements. The velocity field is defined as a sinusoidal wave. The boundary conditions are operator dependent, so they depend on the tendency. 
-* For tendencies 1 and 2 where the upwind biased operator ``UB`` is used, the left boundary is defined as ``sin(a - t)``. The right boundary is ``sin(b - t)``. Here ``a`` and ``b`` are the left and right bounds of the domain. 
-* For tendencies 3 and 4, where the advection operator ``A`` is used, the left boundary is defined as ``sin(-t)``.  The right boundary is extrapolated, meaning its value is set to the closest interior point.
+This test case is set up in a 1D column domain ``z \in [0, 1]`` and discretized into a mesh of 10 elements. A homogeneous Dirichlet boundary condition is set at the bottom boundary, `bcs_bottom`, setting the temperature to 0. A Neumann boundary condition is applied to the top boundary, `bcs_top`, setting the temperature gradient to 1. 
 
-### Heat
+### Advection equation
 
-The 1D Column heat example in [`examples/column/heat.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/heat.jl).
+The 1D Column advection example in [`examples/column/advect.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/advect.jl).
 
-#### Equations and discretizations
+#### Equations and Discretizations
 
-Follows the heat equation
+Follows the advection equation
 
 ```math
 \begin{equation}
-  \frac{\partial T}{\partial t} = \alpha \cdot \nabla^2 T.
-\label{eq:1d-column-heat-continuity}
+  \frac{\partial \theta}{\partial t} = -\frac{\partial (v \theta)}{\partial z} .
+\label{eq:1d-column-advection-continuity}
 \end{equation}
 ```
-
 This is discretized using the following
 
 ```math
 \begin{equation}
-  \frac{\partial T}{\partial t} \approx \alpha \cdot D(G(T)).
-\label{eq:1d-column-heat-discrete}
+  \frac{\partial \theta}{\partial t} \approx - D(v, \theta)  .
+\label{eq:1d-column-advection-discrete}
 \end{equation}
 ```
 
 #### Prognostic Variables
 
-* ``\alpha``: thermal diffusivity measured in  $\frac{m^2}{s}$
-* ``T``: temperature
+* ``\theta``: the scalar field
+* ``v``: the velocity field
 
-#### Differentiation Operators
+#### Tendencies 
 
- * ``D`` is the [face-to-center divergence](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) operator, called `divf2c` in the example code
- * ``G`` is the [center-to-face gradient](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.GradientC2F) operator, called `gradc2f` in the example code
+The example code solves the equation for 4 different tendencies with the following discretizations:
+
+- Tendency 1:
+
+  $$D = \partial(UB),$$  
+
+  where ``\partial`` is the [`face-to-center divergence`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) and $UB$ is the [`center-to-face upwind biased product`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.UpwindBiasedProductC2F) operator.
+- Tendency 2:
+
+  $$D = \partial(UB) + \textrm{fcc}(v, \theta),$$  
+  
+  where $\textrm{fcc}(v, \theta)$ is the [`center-to-center flux correction`](https://github.com/CliMA/ClimaCore.jl/blob/main/src/Operators/finitedifference.jl#L2617) operator.
+- Tendency 3:
+
+  $$D = A,$$  
+   
+  where $A$ is the [`center-to-center vertical advection`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.AdvectionC2C) operator.
+- Tendency 4:
+
+  $$D = A + \textrm{fcc}(v, \theta),$$  
+  
+  where $\textrm{fcc}(v, \theta)$ is the [`center-to-center flux correction`](https://github.com/CliMA/ClimaCore.jl/blob/main/src/Operators/finitedifference.jl#L2617) operator.
 
 #### Set Up
 
-This test case is set up in a 1D column domain ``z \in [0, 1]`` and discretized into a mesh of 10 elements. A homogeneous Dirichlet boundary condition is set at the bottom boundary, `bcs_bottom`, setting the temperature to 0. A Neumann boundary condition is applied to the top boundary, `bcs_top`, setting the temperature gradient to 1. 
+This test case is set up in a 1D column domain ``z \in [0, 4\pi]``, discretized into a mesh of 128 elements. The velocity field is defined as a sinusoidal wave. The boundary conditions are operator dependent, so they depend on the tendency. 
+* For tendencies 1 and 2 where the upwind biased operator ``UB`` is used, the left boundary is defined as ``sin(a - t)``. The right boundary is ``sin(b - t)``. Here ``a`` and ``b`` are the left and right bounds of the domain. 
+* For tendencies 3 and 4, where the advection operator ``A`` is used, the left boundary is defined as ``sin(-t)``.  The right boundary is extrapolated, meaning its value is set to the closest interior point.
 
 ## 2D Cartesian examples