Merge pull request #98 from LukasFuchs/main

Finalize Exercise 12 English Version

Author: LukasFuchs

docs/make.jl

@@ -3,7 +3,7 @@
 In two dimensions ($x$ and $y$), the advection equation for the temperature conservation equation, for example, is given as follows 
 
 $\begin{equation}
-\frac{\partial{T}}{\partial{t}} = -v_x \left(\frac{\partial{T}}{\partial{x}}\right) - -v_y \left(\frac{\partial{T}}{\partial{y}}\right),
+\frac{\partial{T}}{\partial{t}} = -v_x \left(\frac{\partial{T}}{\partial{x}}\right) - v_y \left(\frac{\partial{T}}{\partial{y}}\right),
 \end{equation}$
 
 where $T$ is the temperature [K], $t$ is the time [s], and $v_x$ and $v_y$ are the velocities in the $x$- and $y$-direction, respectively. 

docs/src/assets/12_ThermalConvectionTimeSeries_1.0e6_150_50_lineara_semilag_CNA_dc.png

@@ -40,7 +40,7 @@ where $x_i$ are the coordinates and $v_i$ the corresponding velocity components.
 
 ## Discretization Schemes
 
-Although simple in form, the advection equation is challenging to solve numerically. The choice of discretization and interpolation schemes—particularly when coupling grid-based fields with Lagrangian tracers—can introduce numerical artifacts such as diffusion, dispersion, or instability.
+Although simple in form, the advection equation is challenging to solve numerically. The choice of discretization and interpolation schemes can introduce numerical artifacts such as diffusion, dispersion, or instability.
 
 To promote clarity and modularity, `GeoModBox.jl` employs an **operator-splitting** strategy. This approach decouples the advective and diffusive terms of the temperature conservation equation and solves them sequentially. First, the advective (convective) term is solved, followed by the diffusive term. The latter is handled using the schemes described in the [Diffusion Equation documentation](./DiffMain.md). 
 
@@ -86,5 +86,5 @@ See the [examples documentation](./Examples.md) for further details.
 
 ## Exercises
 
-- [1-D Gaussian or block anomaly advection](https://github.com/GeoSci-FFM/GeoModBox.jl/blob/main/exercises/06_1D_Advection.ipynb)  
-- [2-D coupled advection-diffusion](https://github.com/GeoSci-FFM/GeoModBox.jl/blob/main/exercises/07_2D_Energy_Equation.ipynb)
+- [1-D Gaussian or block anomaly advection](../man/exercises/06_1D_Advection.md)  
+- [2-D coupled advection-diffusion](../man/exercises/07_2D_Energy_Equation.md)

docs/src/assets/12_ThermalConvection_1.0e6_150_50_lineara_semilag_CNA_dc.gif

@@ -35,12 +35,19 @@ This equation captures temperature changes due to **diffusion** (right-hand side
 
 # Heat Diffusion Equation
 
+Neglecting the advection part of the temperature equation, the heat diffusion equation is defined as: 
+
+$\begin{equation}
+\rho c_p \frac{\partial T}{\partial t} = -\frac{\partial q_i}{\partial x_i} + \rho H.
+\end{equation}$
+
 ```GeoModBox.jl``` provides several finite difference (FD) schemes to solve the diffusive component of the time-dependent or steady-state temperature equation—including optional radioactive heating—in both [1-D](https://github.com/GeoSci-FFM/GeoModBox.jl/blob/main/src/HeatEquation/1Dsolvers.jl) and [2-D](https://github.com/GeoSci-FFM/GeoModBox.jl/blob/main/src/HeatEquation/2Dsolvers.jl). Available methods include:
 
 - Forward Euler  
 - Backward Euler  
 - Crank–Nicolson  
 - Alternating Direction Implicit (ADI)
+- Defection Correction
 
 See the documentation for the [1-D](./DiffOneD.md) and [2-D](./DiffTwoD.md) solvers for detailed descriptions of each method.
 

docs/src/assets/12_ThermalConvection_iterations_1.0e6_150_50_lineara_semilag_CNA_dc.png

@@ -369,7 +369,7 @@ $k$ is the thermal conductivity [W/m/K],
 $H$ is the internal heat generation rate per unit mass [W/kg], and
 $y$ is the vertical coordinate (depth) [m]
 
-## Discretization
+### Discretization
 
 In a conservative scheme, the vertical conductive heat flux $q_y$ is defined on vertices, as:
 
@@ -379,7 +379,7 @@ $\begin{equation}
 
 where $n_v$ is the number of *vertices*.
 
-## Explicit Finite Difference Formulation
+### Explicit Finite Difference Formulation
 
 Using the above discretization, the time evolution of temperature at each centroid is computed from:
 

docs/src/man/AdvTwoD.md

@@ -265,7 +265,7 @@ $\begin{equation}
 Discretizing the equation in space and time using implicit finite differences yields:
 
 $\begin{equation}
-\frac{T_i^{n+1}-T_i^{n}}{\Delta{t}} - \kappa 
+\frac{T_{i,j}^{n+1}-T_{i,j}^{n}}{\Delta{t}} - \kappa 
 \left( \frac{T_{i-1,j}^{n+1} - 2 T_{i,j}^{n+1} + T_{i+1,j}^{n+1}}{\Delta{x}^2} + \frac{T_{i,j-1}^{n+1} - 2 T_{i,j}^{n+1} + T_{i,j+1}^{n+1}}{\Delta{y}^2}  
 \right) - \frac{Q_{i,j}^n}{\rho c_p} = R.
 \end{equation}$
@@ -298,13 +298,13 @@ In 2-D, the diffusive part of the heat equation (Equation 3) using the Crank–N
 $\begin{equation}\begin{gather*}
 & \frac{T_{i,j}^{n+1} - T_{i,j}^{n}}{\Delta t} = \\ &
 \frac{\kappa}{2}\frac{(T_{i-1,j}^{n+1}-2T_{i,j}^{n+1}+T_{i+1,j}^{n+1})+(T_{i-1,j}^{n}-2T_{i,j}^{n}+T_{i+1,j}^{n})}{\Delta x^2} + \\ &
-\frac{\kappa}{2}\frac{(T_{i,j-1}^{n+1}-2T_{i,j}^{n+1}+T_{i,j+1}^{n+1})+(T_{i,j-1}^{n}-2T_{i,j}^{n}+T_{i,j+1}^{n})}{\Delta y^2}
+\frac{\kappa}{2}\frac{(T_{i,j-1}^{n+1}-2T_{i,j}^{n+1}+T_{i,j+1}^{n+1})+(T_{i,j-1}^{n}-2T_{i,j}^{n}+T_{i,j+1}^{n})}{\Delta y^2} + \frac{Q_{i,j}^n}{\rho c_p}
 \end{gather*}\end{equation}$
 
 Rearranging into a form that separates known and unknown variables gives the linear system:
 
 $\begin{equation}\begin{gather*}
-& -b T_{i,j-1}^{n+1} -aT_{i-1,j}^{n+1}+\left(2a + 2b + c\right)T_{i,j}^{n+1} -aT_{i+1,j}^{n+1} -b T_{i,j+1}^{n+1} = \\ &b T_{i,j-1}^{n} +aT_{i-1,j}^{n}-\left(2a + 2b - c\right)T_{i,j}^{n} +aT_{i+1,j}^{n} +b T_{i,j+1}^{n}
+& -b T_{i,j-1}^{n+1} -aT_{i-1,j}^{n+1}+\left(2a + 2b + c\right)T_{i,j}^{n+1} -aT_{i+1,j}^{n+1} -b T_{i,j+1}^{n+1} = \\ &b T_{i,j-1}^{n} +aT_{i-1,j}^{n}-\left(2a + 2b - c\right)T_{i,j}^{n} +aT_{i+1,j}^{n} +b T_{i,j+1}^{n} + \frac{Q_{i,j}^n}{\rho c_p}
 \end{gather*}\end{equation}$
 
 where the coefficients are defined as:
@@ -325,7 +325,7 @@ $\begin{equation}\begin{gather*}
 & -b T_{1,j-1}^{n+1} +
 \left(3a + 2b + c \right) T_{1,j}^{n+1} 
 -a T_{2,j}^{n+1} - b T_{1,j+1}^{n+1} = \\ &
-b T_{1,j-1}^{n} - \left( 3a + 2b - c \right) T_{1,j}^{n} + a T_{2,j}^{n} + b T_{1,j+1}^{n} + 4 a T_{BC,W},
+b T_{1,j-1}^{n} - \left( 3a + 2b - c \right) T_{1,j}^{n} + a T_{2,j}^{n} + b T_{1,j+1}^{n} + 4 a T_{BC,W} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **East boundary**
@@ -335,22 +335,22 @@ $\begin{equation}\begin{gather*}
 \left(3a + 2b + c \right) T_{ncx,j}^{n+1} 
 -b T_{ncx,j+1}^{n+1} = \\ & 
 b T_{ncx,j-1}^{n} + a T_{ncx-1,j}^{n} -
-\left( 3a + 2b - c \right) T_{ncx,j}^{n} + b T_{ncx,j+1}^{n} + 4 a T_{BC,E},
+\left( 3a + 2b - c \right) T_{ncx,j}^{n} + b T_{ncx,j+1}^{n} + 4 a T_{BC,E} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **South boundary**
 
 $\begin{equation}\begin{gather*}
 & -a T_{i-1,1}^{n+1} +
 \left(2a + 3b + c \right) T_{i,1}^{n+1} - a T_{i+1,1}^{n+1} - b T_{i,2}^{n+1} = \\ & 
-a T_{i-1,1}^{n} - \left( 2a + 3b - c \right) T_{i,1}^{n} + a T_{i+1,1}^{n} + b T_{i,2}^{n} + 4 b T_{BC,S},
+a T_{i-1,1}^{n} - \left( 2a + 3b - c \right) T_{i,1}^{n} + a T_{i+1,1}^{n} + b T_{i,2}^{n} + 4 b T_{BC,S} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **North boundary**
 
 $\begin{equation}\begin{gather*}
 & -b T_{i,ncy-1}^{n+1} + a T_{i-1,ncy}^{n+1} + \left(2a + 3b + c \right) T_{i,ncy}^{n+1} - a T_{i+1,ncy}^{n+1} = \\ &
-b T_{i,ncy-1}^{n} + a T_{i-1,ncy}^{n} - \left( 2a + 3b - c \right) T_{i,ncy}^{n} + a T_{i+1,ncy}^{n} + 4 b T_{BC,N}.
+b T_{i,ncy-1}^{n} + a T_{i-1,ncy}^{n} - \left( 2a + 3b - c \right) T_{i,ncy}^{n} + a T_{i+1,ncy}^{n} + 4 b T_{BC,N} + \frac{Q_{i,j}^n}{\rho c_p}.
 \end{gather*}\end{equation}$
 
 **Neumann Boundary Conditions**
@@ -359,28 +359,28 @@ b T_{i,ncy-1}^{n} + a T_{i-1,ncy}^{n} - \left( 2a + 3b - c \right) T_{i,ncy}^{n}
 
 $\begin{equation}\begin{gather*}
 & -b T_{1,j-1}^{n+1} + \left(a + 2b + c \right) T_{1,j}^{n+1} - a T_{2,j}^{n+1} - b T_{1,j+1}^{n+1} = \\ &
-b T_{1,j-1}^{n} - \left( a + 2b - c \right) T_{1,j}^{n} + a T_{2,j}^{n} + b T_{1,j+1}^{n} - 2 a c_W \Delta{x},
+b T_{1,j-1}^{n} - \left( a + 2b - c \right) T_{1,j}^{n} + a T_{2,j}^{n} + b T_{1,j+1}^{n} - 2 a c_W \Delta{x} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **East boundary**
 
 $\begin{equation}\begin{gather*}
 & -b T_{ncx,j-1}^{n+1} - a T_{ncx-1,j}^{n+1} + \left(a + 2b + c \right) T_{ncx,j}^{n+1} - b T_{ncx,j+1}^{n+1} = \\ &
-b T_{ncx,j-1}^{n} + a T_{ncx-1,j}^{n} - \left( a + 2b - c \right) T_{ncx,j}^{n} + b T_{ncx,j+1}^{n} + 2 a c_E \Delta{x},
+b T_{ncx,j-1}^{n} + a T_{ncx-1,j}^{n} - \left( a + 2b - c \right) T_{ncx,j}^{n} + b T_{ncx,j+1}^{n} + 2 a c_E \Delta{x} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **South boundary**
 
 $\begin{equation}\begin{gather*}
 & -a T_{i-1,1}^{n+1} + \left(2a + b + c \right) T_{i,1}^{n+1} - a T_{i+1,1}^{n+1} - b T_{i,2}^{n+1} = \\ &
-a T_{i-1,1}^{n} - \left( 2a + b - c \right) T_{i,1}^{n} + a T_{i+1,1}^{n} + b T_{i,2}^{n} - 2 b c_S \Delta{y}
+a T_{i-1,1}^{n} - \left( 2a + b - c \right) T_{i,1}^{n} + a T_{i+1,1}^{n} + b T_{i,2}^{n} - 2 b c_S \Delta{y} + \frac{Q_{i,j}^n}{\rho c_p},
 \end{gather*}\end{equation}$
 
 **North boundary**
 
 $\begin{equation}\begin{gather*}
 & -b T_{i,ncy-1}^{n+1} + a T_{i-1,ncy}^{n+1} + \left(2a + b + c \right) T_{i,ncy}^{n+1} - a T_{i+1,ncy}^{n+1} = \\ &
-b T_{i,ncy-1}^{n} + a T_{i-1,ncy}^{n} - \left( 2a + b - c \right) T_{i,ncy}^{n} + a T_{i+1,ncy}^{n} + 2 b c_N \Delta{y}
+b T_{i,ncy-1}^{n} + a T_{i-1,ncy}^{n} - \left( 2a + b - c \right) T_{i,ncy}^{n} + a T_{i+1,ncy}^{n} + 2 b c_N \Delta{y} + \frac{Q_{i,j}^n}{\rho c_p}.
 \end{gather*}\end{equation}$
 
 For implementation details, refer to the [source code](https://github.com/GeoSci-FFM/GeoModBox.jl/blob/main/src/HeatEquation/2Dsolvers.jl).
@@ -396,7 +396,7 @@ $\begin{equation}
     \left( 
     \frac{T_{i-1,j}^n-2T_{i,j}^n+T_{i+1,j}^n}{\Delta x^2} +
     \frac{T_{i,j-1}^{n+1/2}-2T_{i,j}^{n+1/2}+T_{i,j+1}^{n+1/2}}{\Delta y^2}
-    \right)
+    \right) + \frac{Q_{i,j}^n}{\rho c_p}
 \end{equation}$
 
 ### Second half-step (implicit in $x$, explicit in $y$):
@@ -407,7 +407,7 @@ $\begin{equation}
     \left( 
     \frac{T_{i-1,j}^{n+1}-2T_{i,j}^{n+1}+T_{i+1,j}^{n+1}}{\Delta x^2} + 
     \frac{T_{i,j-1}^{n+1/2}-2T_{i,j}^{n+1/2}+T_{i,j+1}^{n+1/2}}{\Delta y^2}
-    \right)
+    \right) + \frac{Q_{i,j}^n}{\rho c_p}
 \end{equation}$
 
 Each fractional step results in a tridiagonal linear system, alternating between the $x$- and $y$-directions. This decomposition improves computational efficiency while retaining the stability benefits of implicit schemes.
@@ -443,7 +443,7 @@ $\begin{equation}
 \rho_{i,j} c_{p,(i,j)}\left(\frac{T_{i,j}^{n+1} - T_{i,j}^{n}}{\Delta{t}}\right) 
 +\frac{q_{x,(i+1,j)} - q_{x,(i,j)}}{\Delta{x}} 
 +\frac{q_{y,(i,j+1)} - q_{y,(i,j)}}{\Delta{y}} 
--\rho_{i,j} H_{i,j} = R, 
+-\rho_{i,j} H_{i,j} = R_{i,j}, 
 \end{equation}$
 
 where $\Delta{x}$ and $\Delta{y}$ are the horizontal and vertical grid resolution, respectively, $\Delta{t}$ is the time step length and $i$ and $j$ the horizontal and vertical indices, respectively. 
@@ -462,7 +462,7 @@ $\begin{equation}
 +k_{y,(i,j)}\frac{T_{i,j}^{n+1}-T_{i,j-1}^{n+1}}{\Delta{y}}}
 {\Delta{y}}
 \right)
--\rho_{i,j} H_{i,j} = R.
+-\rho_{i,j} H_{i,j} = R_{i,j}.
 \end{equation}$
 
 Rewriting this in a matrix-compatible form leads to: 
@@ -474,7 +474,7 @@ aT_{i,j-1}^{n+1}
 +dT_{i+1,j}^{n+1} 
 +eT_{i,j+1}^{n+1} 
 +fT_{i,j}^{n} 
--\rho_{i,j} H_{i,j} = R,
+-\rho_{i,j} H_{i,j} = R_{i,j},
 \end{equation}$
 
 where

docs/src/man/AdvectMain.md

@@ -39,7 +39,7 @@ All exercises were performed on a single CPU: *AMD Ryzen 7 7735U with Radeon Gra
 | 9               | 2-D Falling Block (steady state)    | 20.764 (0.891) | 
 | 10              | 2-D Falling Block (time-dep.)       | 1) Upwind: 33.295 (3.68) <br/> 2) SLF: 32.333 (3.629) <br/> 3) SL: 37.537 (3.755) <br/> 4) Tracers: 36.291 (6.12) |
 | 11<sup>1</sup> | Thermal Convection (dim)            | **Ra = 1e4** (Diff+Adv+Momentum) <br/> 1) Explicit+upwind+direct: 262.912 (1703) <br/> 2) Implicit+upwind+direct: 283.031 (1709) <br/> 3) CNA+upwind+direct: 284.944 (1708) <br/> 4) ADI+upwind+direct: 645.181 (1708) <br/> 5) DC+upwind+direct: 294.1 (1710) <br/> 6) Explicit+SLF+direct: 354.35 (2341) <br/> 7) Implicit+SLF+direct: 382.307 (2345) <br/> 8) CNA+SLF+direct: 386.764 (2344) <br/> 9) ADI+SLF+direct: 892.411 (2344) <br/> 10) DC+SLF+direct: 492.168 (2346) <br/> 11) Explicit+semilag+direct: 334.941 (1743) <br/> 12) Implicit+semilag+direct: 367.501 (1746) <br/> 13) CNA+semilag+direct: 371.289 (1744) <br/> 14) ADI+semilag+direct: 704.852 (1744) <br/> 15) DC+semilag+direct: 390.767 (1749) <br/> 16) Explicit+upwind+DC: 371.091 (1703) <br/> 17) Implicit+upwind+DC: 358.323 (1709) <br/> 18) CNA+upwind+DC: 338.862 (1708) <br/> 19) ADI+upwind+DC: 654.069 (1708) <br/> 20) DC+upwind+DC: 316.456 (1710) <br/> 21) Explicit+SLF+DC: 394.471 (2341) <br/> 22) Implicit+SLF+DC: 417.712 (2345) <br/> 23) CNA+SLF+DC: 412.717 (2344) <br/> 24) ADI+slf+DC: 890.714 (2344) <br/> 25) DC+SLF+DC: 403.217 (2346) <br/> 26) Explicit+semilag+DC: 286.046 (1743) <br/> 27) Implicit+semilag+DC: 295.961 (1746) <br/> 28) CNA+semilag+DC: 288.067 (1744) <br/> 29) ADI+semilag+DC: 671.159 (1744) <br/> 30) DC+semilag+DC: 357.894 (1749) <br/> <br/> **Ra = 1e5** (Diff+Adv+Momentum) <br/> 1) Explicit+semilag+dc: 489.869 (2433) <br/> 2) CNA+semilag+dc: 515.539 (2448) <br/> 3) CNA+upwind+dc: 1327.856 (8000) <br/><br/> **Ra = 1e6** (Diff+Adv+Momentum) <br/> 4) Explicit+semilag+dc: 1280.077 (8000) <br/> 5) CNA+semilag+dc: 1324.29 (8000) <br/> 6) CNA+upwind+dc: 1272.997 (8000)  |
-| 12            | 
+| 12            | Thermal Convection (scaled)       | **Ra = 1e4** (Diff+Adv+Momentum) <br/> 1) Explicit+upwind+direct: 310.208 (1950) <br/> 2) Implicit+upwind+direct: 333.82 (1957) <br/> 3) CNA+upwind+direct: 331.791 (1955) <br/> 4) ADI+upwind+direct: 739.821 (1955) <br/> 5) DC+upwind+direct: 352.163 (1953) <br/> 6) Explicit+SLF+direct: 437.435 (2704) <br/> 7) Implicit+SLF+direct: 468.642 (2708) <br/> 8) CNA+SLF+direct: 464.97 (2707) <br/> 9) ADI+SLF+direct: 1013.196 (2707) <br/> 10) DC+SLF+direct: 476.063 (2706) <br/> 11) Explicit+semilag+direct: 358.84 (1999) <br/> 12) Implicit+semilag+direct: 341.811 (2002) <br/> 13) CNA+semilag+direct: 384.29 (2000) <br/> 14) ADI+semilag+direct: 754.453 (2000) <br/> 15) DC+semilag+direct: 359.703 (2001) <br/> 16) Explicit+upwind+DC: 683.465 (1950) <br/> 17) Implicit+upwind+DC: 614.899 (1957) <br/> 18) CNA+upwind+DC:  649.386 (1955) <br/> 19) ADI+upwind+DC: 1048.092 (1955) <br/> 20) DC+upwind+DC:  640.199 (1953) <br/> 21) Explicit+SLF+DC:  835.568 (2704) <br/> 22) Implicit+SLF+DC:  862.991 (2708) <br/> 23) CNA+SLF+DC:  868.07 (2707) <br/> 24) ADI+slf+DC:  1402.997 (2707) <br/> 25) DC+SLF+DC: 876.505 (2706) <br/> 26) Explicit+semilag+DC: 613.413 (1999) <br/> 27) Implicit+semilag+DC: 652.126 (2002) <br/> 28) CNA+semilag+DC: 638.264 (2000) <br/> 29) ADI+semilag+DC:  1027.153 (2000) <br/> 30) DC+semilag+DC: 620. 945 (2001) <br/> <br/> **Ra = 1e5** (Diff+Adv+Momentum) <br/> 31) Explicit+semilag+dc:  3502.72 (8000) <br/>  32) CNA+semilag+dc: 3175.01 (8000) <br/> 33) CNA+upwind+dc: 3330.177 (8000) <br/><br/> **Ra = 1e6** (Diff+Adv+Momentum) <br/> 34) Explicit+semilag+dc: 3327.062 (8000) <br/> 35) CNA+semilag+dc: 3387.836 (8000) <br/> 36) CNA+upwind+dc: 3277.684 (8000) <br/> | 
 
 ---