Merge pull request #2322 from onzerem/on/advect-heat-doc

Add 1D Heat and Advection Examples to Documentation

Author: Sbozzolo

docs/src/examples.md

@@ -2,6 +2,103 @@
 
 ## 1D Column examples
 
+### Heat equation
+
+The 1D Column heat example in [`examples/column/heat.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/heat.jl).
+
+#### Equations and discretizations
+
+Follows the heat equation
+
+```math
+\begin{equation}
+  \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 T}{\partial t} \approx \alpha \cdot D(G(T)).
+\label{eq:1d-column-heat-discrete}
+\end{equation}
+```
+
+#### Prognostic Variables
+
+* ``\alpha``: thermal diffusivity measured in  $\frac{m^2}{s}$
+* ``T``: temperature
+
+#### Differentiation Operators
+
+ * ``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, 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. 
+
+### Advection equation
+
+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
+
+Follows the advection equation
+
+```math
+\begin{equation}
+  \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 \theta}{\partial t} \approx - D(v, \theta)  .
+\label{eq:1d-column-advection-discrete}
+\end{equation}
+```
+
+#### Prognostic Variables
+
+* ``\theta``: the scalar field
+* ``v``: the velocity field
+
+#### Tendencies 
+
+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, 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
 
 ### Flux Limiters advection