Skip to content

Commit b59e19b

Browse files
Snowdog85123Snowdog85123
committed
Reorder examples and remove root-level examples.md
1 parent fd3c717 commit b59e19b

File tree

2 files changed

+101
-282
lines changed

2 files changed

+101
-282
lines changed

‎docs/src/examples.md

Lines changed: 101 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,104 @@
11
# Examples
22

33
## 1D Column examples
4+
5+
### Heat equation
6+
7+
The 1D Column heat example in [`examples/column/heat.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/heat.jl).
8+
9+
#### Equations and discretizations
10+
11+
Follows the heat equation
12+
13+
```math
14+
\begin{equation}
15+
\frac{\partial T}{\partial t} = \alpha \cdot \nabla^2 T.
16+
\label{eq:1d-column-heat-continuity}
17+
\end{equation}
18+
```
19+
20+
This is discretized using the following
21+
22+
```math
23+
\begin{equation}
24+
\frac{\partial T}{\partial t} \approx \alpha \cdot D(G(T)).
25+
\label{eq:1d-column-heat-discrete}
26+
\end{equation}
27+
```
28+
29+
#### Prognostic Variables
30+
31+
* ``\alpha``: thermal diffusivity measured in $\frac{m^2}{s}$
32+
* ``T``: temperature
33+
34+
#### Differentiation Operators
35+
36+
* ``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
37+
* ``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
38+
39+
#### Set Up
40+
41+
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.
42+
43+
### Advection equation
44+
45+
The 1D Column advection example in [`examples/column/advect.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/advect.jl).
46+
47+
#### Equations and Discretizations
48+
49+
Follows the advection equation
50+
51+
```math
52+
\begin{equation}
53+
\frac{\partial \theta}{\partial t} = -\frac{\partial (v \theta)}{\partial z} .
54+
\label{eq:1d-column-advection-continuity}
55+
\end{equation}
56+
```
57+
This is discretized using the following
58+
59+
```math
60+
\begin{equation}
61+
\frac{\partial \theta}{\partial t} \approx - D(v, \theta) .
62+
\label{eq:1d-column-advection-discrete}
63+
\end{equation}
64+
```
65+
66+
#### Prognostic Variables
67+
68+
* ``\theta``: the scalar field
69+
* ``v``: the velocity field
70+
71+
#### Tendencies
72+
73+
The example code solves the equation for 4 different tendencies with the following discretizations:
74+
75+
- Tendency 1:
76+
77+
$$D = \partial(UB),$$
78+
79+
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.
80+
- Tendency 2:
81+
82+
$$D = \partial(UB) + \textrm{fcc}(v, \theta),$$
83+
84+
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.
85+
- Tendency 3:
86+
87+
$$D = A,$$
88+
89+
where $A$ is the [`center-to-center vertical advection`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.AdvectionC2C) operator.
90+
- Tendency 4:
91+
92+
$$D = A + \textrm{fcc}(v, \theta),$$
93+
94+
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.
95+
96+
#### Set Up
97+
98+
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.
99+
* 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.
100+
* 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.
101+
4102
### Ekman Layer
5103

6104
The 1D vertical Ekman layer simulation in [`examples/column/ekman.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/ekman.jl) demonstrates the simulation of atmospheric boundary layer dynamics, specifically the Ekman spiral phenomenon resulting from the balance between Coriolis force and vertical diffusion.
@@ -145,13 +243,13 @@ This is discretized using the following:
145243

146244
Where $B$ applies boundary conditions to enforce $\boldsymbol{w} = 0$ at the domain boundaries.
147245

148-
### Prognostic variables
246+
#### Prognostic variables
149247

150248
* $\rho$: _density_ measured in kg/m³, discretized at cell centers.
151249
* $\rho\theta$: _potential temperature density_ measured in K·kg/m³, discretized at cell centers.
152250
* $\boldsymbol{w}$: _vertical velocity_ measured in m/s, discretized at cell faces.
153251

154-
### Operators
252+
#### Operators
155253

156254
#### Reconstructions
157255

@@ -166,7 +264,7 @@ Where $B$ applies boundary conditions to enforce $\boldsymbol{w} = 0$ at the dom
166264
* $B$ is the [boundary operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.SetBoundaryOperator), called `B` in the example code.
167265
- This enforces zero vertical velocity at domain boundaries.
168266

169-
### Problem flow and set-up
267+
#### Problem flow and set-up
170268

171269
This test case is set up in a vertical column domain from $z=0$ m to $z=30$ km with 30 vertical elements. The column is initialized with a decaying temperature profile, where:
172270

@@ -180,102 +278,6 @@ The initial vertical velocity is set to zero everywhere. To maintain hydrostatic
180278

181279
The simulation is run for 10 days to verify that the hydrostatic balance is maintained over time. Results are plotted showing density ($\rho$), vertical velocity ($\boldsymbol{w}$), and potential temperature density ($\rho\theta$) profiles.
182280

183-
### Heat equation
184-
185-
The 1D Column heat example in [`examples/column/heat.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/heat.jl).
186-
187-
#### Equations and discretizations
188-
189-
Follows the heat equation
190-
191-
```math
192-
\begin{equation}
193-
\frac{\partial T}{\partial t} = \alpha \cdot \nabla^2 T.
194-
\label{eq:1d-column-heat-continuity}
195-
\end{equation}
196-
```
197-
198-
This is discretized using the following
199-
200-
```math
201-
\begin{equation}
202-
\frac{\partial T}{\partial t} \approx \alpha \cdot D(G(T)).
203-
\label{eq:1d-column-heat-discrete}
204-
\end{equation}
205-
```
206-
207-
#### Prognostic Variables
208-
209-
* ``\alpha``: thermal diffusivity measured in $\frac{m^2}{s}$
210-
* ``T``: temperature
211-
212-
#### Differentiation Operators
213-
214-
* ``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
215-
* ``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
216-
217-
#### Set Up
218-
219-
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.
220-
221-
### Advection equation
222-
223-
The 1D Column advection example in [`examples/column/advect.jl`](https://github.com/CliMA/ClimaCore.jl/blob/main/examples/column/advect.jl).
224-
225-
#### Equations and Discretizations
226-
227-
Follows the advection equation
228-
229-
```math
230-
\begin{equation}
231-
\frac{\partial \theta}{\partial t} = -\frac{\partial (v \theta)}{\partial z} .
232-
\label{eq:1d-column-advection-continuity}
233-
\end{equation}
234-
```
235-
This is discretized using the following
236-
237-
```math
238-
\begin{equation}
239-
\frac{\partial \theta}{\partial t} \approx - D(v, \theta) .
240-
\label{eq:1d-column-advection-discrete}
241-
\end{equation}
242-
```
243-
244-
#### Prognostic Variables
245-
246-
* ``\theta``: the scalar field
247-
* ``v``: the velocity field
248-
249-
#### Tendencies
250-
251-
The example code solves the equation for 4 different tendencies with the following discretizations:
252-
253-
- Tendency 1:
254-
255-
$$D = \partial(UB),$$
256-
257-
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.
258-
- Tendency 2:
259-
260-
$$D = \partial(UB) + \textrm{fcc}(v, \theta),$$
261-
262-
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.
263-
- Tendency 3:
264-
265-
$$D = A,$$
266-
267-
where $A$ is the [`center-to-center vertical advection`](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.AdvectionC2C) operator.
268-
- Tendency 4:
269-
270-
$$D = A + \textrm{fcc}(v, \theta),$$
271-
272-
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.
273-
274-
#### Set Up
275-
276-
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.
277-
* 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.
278-
* 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.
279281

280282
## 2D Cartesian examples
281283

0 commit comments

Comments
 (0)