up

docs/src/man/equations.md

@@ -1,36 +1,62 @@
-# Pseudo-transient iterative method
 The pseudo-transient method consists in augmenting the right-hand-side of the target PDE with a pseudo-time derivative (where $\psi$ is the pseudo-time) of the primary variables. We then solve the resulting system of equations with an iterative method. The pseudo-time derivative is then gradually reduced, until the original PDE is solved and the changes in the primary variables are below a preset tolerance.
 
 ## Heat diffusion
 The pseudo-transient heat-diffusion equation is:
 
-$\widetilde{\rho}\frac{\partial T}{\partial \psi} + \rho C_p \frac{\partial T}{\partial t} = \nabla \cdot (\kappa\nabla T) = -\nabla q$
+$$
+\begin{align}
+\widetilde{\rho}\frac{\partial T}{\partial \psi} + \rho C_p \frac{\partial T}{\partial t} = \nabla \cdot (\kappa\nabla T) = -\nabla q
+\end{align}
+$$
 
 We use a second order pseudo-transient scheme were continuation is also done on the flux, so that:
 
-$\widetilde{\theta}\frac{\partial q}{\partial \psi} + q  = -\kappa\nabla T$
+$$
+\begin{align}
+\widetilde{\theta}\frac{\partial q}{\partial \psi} + q  = -\kappa\nabla T
+\end{align}
+$$
 
 ## Stokes equations
 
- For example, the pseudo-transient formulation of the Stokes equations yields:
+For example, the pseudo-transient formulation of the Stokes equations yields:
 
-$\widetilde{\rho}\frac{\partial \boldsymbol{u}}{\partial \psi} + \nabla\cdot\boldsymbol{\tau} - \nabla p = \boldsymbol{f}$
-
-$\frac{1}{\widetilde{K}}\frac{\partial p}{\partial \psi} + \nabla\cdot\boldsymbol{v} = \beta \frac{\partial p}{\partial t} + \alpha \frac{\partial T}{\partial t}$
+$$
+\begin{align}
+\widetilde{\rho}\frac{\partial \boldsymbol{u}}{\partial \psi} + \nabla\cdot\boldsymbol{\tau} - \nabla p = \boldsymbol{f}
+\end{align}
+$$
 
+$$
+\begin{align}
+\frac{1}{\widetilde{K}}\frac{\partial p}{\partial \psi} + \nabla\cdot\boldsymbol{v} = \beta \frac{\partial p}{\partial t} + \alpha \frac{\partial T}{\partial t}
+\end{align}
+$$
 
 ## Constitutive equations
 A pseudo-transient continuation is also done on the constitutive law:
 
-$\frac{1}{2\widetilde{G}} \frac{\partial\boldsymbol{\tau}}{\partial\psi}+ \frac{1}{2G}\frac{D\boldsymbol{\tau}}{Dt} + \frac{\boldsymbol{\tau}}{2\eta} = \dot{\boldsymbol{\varepsilon}}$
+$$
+\begin{align}
+\frac{1}{2\widetilde{G}} \frac{\partial\boldsymbol{\tau}}{\partial\psi}+ \frac{1}{2G}\frac{D\boldsymbol{\tau}}{Dt} + \frac{\boldsymbol{\tau}}{2\eta} = \dot{\boldsymbol{\varepsilon}}
+\end{align}
+$$
 
 where the wide tile denotes the effective damping coefficients and $\psi$ is the pseudo-time step. These are defined as in [Räss et al. (2022)](https://gmd.copernicus.org/articles/15/5757/2022/):
 
-$\widetilde{\rho} = Re\frac{\eta}{\widetilde{V}L}, \qquad \widetilde{G} = \frac{\widetilde{\rho} \widetilde{V}^2}{r+2}, \qquad \widetilde{K} = r \widetilde{G}$
+$$
+\begin{align}
+\widetilde{\rho} = Re\frac{\eta}{\widetilde{V}L}, \qquad \widetilde{G} = \frac{\widetilde{\rho} \widetilde{V}^2}{r+2}, \qquad \widetilde{K} = r \widetilde{G}
+\end{align}
+$$
 
 and
 
-$\widetilde{V} = \sqrt{ \frac{\widetilde{K} +2\widetilde{G}}{\widetilde{\rho}}}, \qquad r = \frac{\widetilde{K}}{\widetilde{G}}, \qquad Re = \frac{\widetilde{\rho}\widetilde{V}L}{\eta}$
+$$
+\begin{align}
+\widetilde{V} = \sqrt{ \frac{\widetilde{K} +2\widetilde{G}}{\widetilde{\rho}}}, \qquad r = \frac{\widetilde{K}}{\widetilde{G}}, \qquad Re = \frac{\widetilde{\rho}\widetilde{V}L}{\eta}
+\end{align}
+$$
 
 where the P-wave $\widetilde{V}=V_p$ is the characteristic velocity scale for Stokes, and $Re$ is the Reynolds number.
 

docs/src/man/equations_APT.md

@@ -0,0 +1,92 @@
+The pseudo-transient method consists in augmenting the right-hand-side of the target PDE with a pseudo-time derivative (where $\psi$ is the pseudo-time) of the primary variables. We then solve the resulting system of equations with an iterative method. The pseudo-time derivative is then gradually reduced, until the original PDE is solved and the changes in the primary variables are below a preset tolerance.
+
+## Heat diffusion
+The pseudo-transient heat-diffusion equation is:
+
+$$
+\begin{align}
+\widetilde{\rho}\frac{\partial T}{\partial \psi} + \rho C_p \frac{\partial T}{\partial t} = \nabla \cdot (\kappa\nabla T) = -\nabla q
+\end{align}
+$$
+
+We use a second order pseudo-transient scheme were continuation is also done on the flux, so that:
+
+$$
+\begin{align}
+\widetilde{\theta}\frac{\partial q}{\partial \psi} + q  = -\kappa\nabla T
+\end{align}
+$$
+
+## Stokes equations
+
+For example, the pseudo-transient formulation of the Stokes equations yields:
+
+$$
+\begin{align}
+\widetilde{\rho}\frac{\partial \boldsymbol{u}}{\partial \psi} + \nabla\cdot\boldsymbol{\tau} - \nabla p = \boldsymbol{f}
+\end{align}
+$$
+
+$$
+\begin{align}
+\frac{1}{\widetilde{K}}\frac{\partial p}{\partial \psi} + \nabla\cdot\boldsymbol{v} = \beta \frac{\partial p}{\partial t} + \alpha \frac{\partial T}{\partial t}
+\end{align}
+$$
+
+## Constitutive equations
+A pseudo-transient continuation is also done on the constitutive law:
+
+$$
+\begin{align}
+\frac{1}{2\widetilde{G}} \frac{\partial\boldsymbol{\tau}}{\partial\psi}+ \frac{1}{2G}\frac{D\boldsymbol{\tau}}{Dt} + \frac{\boldsymbol{\tau}}{2\eta} = \dot{\boldsymbol{\varepsilon}}
+\end{align}
+$$
+
+where the wide tile denotes the effective damping coefficients and $\psi$ is the pseudo-time step. These are defined as in [Räss et al. (2022)](https://gmd.copernicus.org/articles/15/5757/2022/):
+
+$$
+\begin{align}
+\widetilde{\rho} = Re\frac{\eta}{\widetilde{V}L}, \qquad \widetilde{G} = \frac{\widetilde{\rho} \widetilde{V}^2}{r+2}, \qquad \widetilde{K} = r \widetilde{G}
+\end{align}
+$$
+
+and
+
+$$
+\begin{align}
+\widetilde{V} = \sqrt{ \frac{\widetilde{K} +2\widetilde{G}}{\widetilde{\rho}}}, \qquad r = \frac{\widetilde{K}}{\widetilde{G}}, \qquad Re = \frac{\widetilde{\rho}\widetilde{V}L}{\eta}
+\end{align}
+$$
+
+where the P-wave $\widetilde{V}=V_p$ is the characteristic velocity scale for Stokes, and $Re$ is the Reynolds number.
+
+### Physical parameters
+
+| Symbol                           | Parameter              |
+| :------------------------------- | :--------------------: |
+| $T$                              | Temperature            |
+| $q$                              | Flux                   |
+| $\boldsymbol{\tau}$              | Deviatoric stress      |
+| $\dot{\boldsymbol{\varepsilon}}$ | Deviatoric strain rate |
+| $\boldsymbol{u}$                 | Velocity               |
+| $\boldsymbol{f}$                 | External forces        |
+| $P$                              | Pressure               |
+| $\eta$                           | Viscosity              |
+| $\rho$                           | Density                |
+| $\beta$                          | Compressibility        |
+| $G$                              | Shear modulus          |
+| $\alpha$                         | Thermal expansivity    |
+| $C_p$                            | Heat capacity          |
+| $\kappa$                         | Heat conductivity      |
+
+### Pseudo-transient parameters
+
+| Symbol               | Parameter                     |
+| :------------------- | :---------------------------: |
+| $\psi$                | Pseudo time step              |
+| $\widetilde{K}$      | Pseudo bulk modulus           |
+| $\widetilde{G}$      | Pseudo shear modulus          |
+| $\widetilde{V}$      | Characteristic velocity scale |
+| $\widetilde{\rho}$   | Pseudo density                |
+| $\widetilde{\theta}$ | Relaxation time               |
+| $Re$                 | Reynolds number               |

docs/src/man/equations_basic.md

@@ -0,0 +1,44 @@
+## Stokes equations
+
+Deformation of compressible viscous flow is desribed by the equations of conservation of momentum and mass:
+
+$$
+\begin{align}
+\nabla\cdot\boldsymbol{\tau} - \nabla p = \boldsymbol{f}
+\end{align}
+$$
+
+$$
+\begin{align}
+\nabla\cdot\boldsymbol{v} = \beta \frac{\partial p}{\partial t} + \alpha \frac{\partial T}{\partial t}
+\end{align}
+$$
+
+where $\boldsymbol{\tau}$ is the deviatoric stress tensor, $p$ is pressure, $f$ is the external forces vector, $\boldsymbol{v}$ is the velocity vector, $\beta$ is the compressibility coefficient, $\alpha$ is the thermal expansivity coefficient and $T$ is temperature.
+
+To close the previous systems of equations, we further need the constitutive relationship between stress and deformationl. In its simplest linear form this is:
+
+$$
+\begin{align}
+\boldsymbol{\tau} = 2 \eta \boldsymbol{\dot\varepsilon}
+\end{align}
+$$
+
+where $\eta$ is the shear viscosity and  $\boldsymbol{\dot\varepsilon}$ is the deviatoric strain tensor.
+
+## Heat diffusion
+The pseudo-transient heat-diffusion equation is:
+
+$$
+\begin{align}
+\rho C_p \frac{\partial T}{\partial t} = \nabla \cdot (\kappa\nabla T) + \boldsymbol{\tau}:\boldsymbol{\dot\varepsilon} + \alpha T(\boldsymbol{v} \cdot \nabla P) + H
+\end{align}
+$$
+
+where $\rho$ is density, $C_p$ is specific heat capacity, $\kappa$ is thermal conductivity, $T$ is temperature $\boldsymbol{\tau}:\boldsymbol{\dot\varepsilon}$ is the energy dissipated by viscous deformation (shear heating), $\alpha T(\boldsymbol{v} \cdot \nabla P)$ is adiabatic heating, and $H$ is the sum any other source term, such as radiogenic heat production.
+
+# Discretization of the governing equations
+
+We discretize both the Stokes and heat diffussion equations using a Finite Differences approach on a staggered grid (ref Taras book here), as sketched below:
+
+![Staggered Velocity Grid](../assets/StaggeredVelocity.png)

docs/src/man/equations_discretization.md

@@ -0,0 +1,64 @@
+# Discretization of the APT equations
+
+We discretize both the Stokes and heat diffussion equations using a Finite Differences approach on a staggered grid (ref Taras book here), as sketched below:
+
+![Staggered Velocity Grid](../assets/StaggeredVelocity.png)
+
+## Heat diffusion
+
+For simplicity we do not consider shear heating, adiabatic heating and source terms, and further consider the thermal conductivity as constant throughout the whole domain. The discretized 2D APT diffusion equation then yields:
+
+$$
+\begin{align}
+\widetilde{\theta}\frac{q^{n+1}_{x_{ij}} - q^{n}_{x_{ij}}}{\Delta \psi} + q^{n+1}_{x_{ij}} = -\kappa\frac{T^n_{i+1j} + T^n_{ij}}{\Delta x} \\
+
+\widetilde{\theta}\frac{q^{n+1}_{y_{ij}} - q^{n}_{y_{ij}}}{\Delta \psi} + q^{n+1}_{y_{ij}} = -\kappa\frac{T^n_{ij+1} + T^n_{ij}}{\Delta x} \\
+
+\widetilde{\rho}\frac{T^{n+1}_{ij} + T^n_{ij}}{\Delta \psi} + \rho C_p \frac{ T^{n+1}_{ij} + T^t_{ij}}{\Delta t} = -\left(\frac{q_{x_{i+1j}} + q_{x_{ij}}}{\Delta x} + \frac{q_{y_{i+1j}} + q_{y_{ij}}}{\Delta y}\right) \\
+
+\end{align} 
+$$
+
+Upon convergence we recover
+
+$$
+\begin{align}
+T^{t+\Delta t}_{ij}     = T^{n+1}_{ij}      \\ 
+q^{t+\Delta t}_{x_{ij}} = q^{n+1}_{y_{ij}}  \\
+q^{t+\Delta t}_{x_{ij}} = q^{n+1}_{y_{ij}}  \\
+\end{align}
+$$
+
+## Stokes equations
+
+For example, the pseudo-transient formulation of the Stokes equations yields:
+
+<!-- $$
+\begin{align}
+\widetilde{\rho}\frac{\boldsymbol{u}}{\Delta\psi} + \nabla\cdot\boldsymbol{\tau} - 
+(\frac{p^{n+1} - p^{n+1}}{\Delta x} + \frac{p^{n+1} - p^{n+1}}{\Delta y}) = 
+\boldsymbol{f} \\
+\end{align}
+$$ -->
+
+$$
+\begin{align}
+\widetilde{\rho}\frac{u^{n+1}_x - u^n_x}{\Delta\psi} + \nabla\cdot\boldsymbol{\tau} - 
+\frac{p^{n+1} - p^{n+1}}{\Delta x} = 
+0 \\
+\end{align}
+$$
+
+$$
+\begin{align}
+\widetilde{\rho}\frac{u^{n+1}_y - u^n_y}{\Delta\psi} + \nabla\cdot\boldsymbol{\tau} - 
+\frac{p^{n+1} - p^{n+1}}{\Delta y} = 
+\rho g_y \\
+\end{align}
+$$
+
+$$
+\begin{align}
+\frac{1}{\widetilde{K}}\frac{p^{n+1} - p^{n}}{\Delta\psi} + \nabla\cdot\boldsymbol{v} = \frac{1}{\Delta t} \left( \beta (p^{t+\Delta t} - p^{t}) + \alpha (T^{t+\Delta t} - T^{t}) \right)
+\end{align}
+$$