Merge pull request #47 from agdestein/rewrite-docs

Update docs

docs/make.jl

@@ -55,6 +55,7 @@ makedocs(;
         canonical = "https://agdestein.github.io/IncompressibleNavierStokes.jl",
         assets = String[],
     ),
+    pagesonly = true,
     pages = [
         "Home" => "index.md",
         "Getting Started" => "getting_started.md",

docs/references.bib

@@ -153,3 +153,33 @@ @article{Sanderse2020
   volume   = {421},
   year     = {2020}
 }
+@article{Verstappen1997,
+  doi = {10.1023/a:1004255329158},
+  url = {https://doi.org/10.1023%2Fa%3A1004255329158},
+  year = 1997,
+  publisher = {Springer Science and Business Media {LLC}},
+  volume = {32},
+  number = {2/3},
+  pages = {143--159},
+  author = {R.W.C.P. Verstappen and A.E.P. Veldman},
+  journal = {Journal of Engineering Mathematics},
+  title = {Direct Numerical Simulation of Turbulence at Lower Costs}
+}
+@article{Verstappen2003,
+  author = {Verstappen, R. W. C. P. and Veldman, A. E. P.},
+  title = {Symmetry-Preserving Discretization of Turbulent Flow},
+  year = {2003},
+  issue_date = {May 2003},
+  publisher = {Academic Press Professional, Inc.},
+  address = {USA},
+  volume = {187},
+  number = {1},
+  issn = {0021-9991},
+  url = {https://doi.org/10.1016/S0021-9991(03)00126-8},
+  doi = {10.1016/S0021-9991(03)00126-8},
+  journal = {J. Comput. Phys.},
+  month = {may},
+  pages = {343–368},
+  numpages = {26},
+  keywords = {stability, nonuniform grid, conservation, higher-order discretization, turbulent channel flow, direct numerical simulation}
+}

docs/src/equations/ns.md

@@ -1,57 +1,31 @@
 # Incompressible Navier-Stokes equations
 
-The incompressible Navier-Stokes equations are comprised of a mass equation and
-two or three momentum equations. In conservative form, they are given by
+Let ``d \in \{2, 3\}`` denote the spatial dimension, and ``\Omega \subset
+\mathbb{R}^d`` some spatial domain. The incompressible Navier-Stokes equations
+on ``\Omega`` are comprised of a mass equation and ``d`` momentum equations. In
+conservative form, they are given by
 
 ```math
 \begin{align*}
-\nabla \cdot V & = 0, \\
-\frac{\mathrm{d} V}{\mathrm{d} t} + \nabla \cdot (V V^\mathsf{T}) & = -\nabla p +
-\nu \nabla^2 V + f.
+\nabla \cdot u & = 0, \\
+\frac{\partial u}{\partial t} + \nabla \cdot (u u^\mathsf{T}) & = -\nabla p +
+\nu \nabla^2 u + f.
 \end{align*}
 ```
 
-where ``V = (u, v)`` or ``V = (u, v, w)`` is the velocity field, ``p`` is the
-pressure, ``\nu`` is the kinematic viscosity, and ``f = (f_u, f_v)`` or ``f =
-(f_u, f_v, f_w)`` is the body force per unit of volume. In 2D, the equations
-become
+where ``u = (u^1, \dots, u^d)`` is the velocity field, ``p`` is the
+pressure, ``\nu`` is the kinematic viscosity, and ``f = (f^1, \dots, f^d)`` is
+the body force per unit of volume. In scalar notation, the equations can be
+written as
 
 ```math
-\begin{split}
-    \frac{\partial u}{\partial x} + \frac{\partial v}{\partial y} & = 0, \\
-    \frac{\partial u}{\partial t} + \frac{\partial (u u)}{\partial x} +
-    \frac{\partial (v u)}{\partial y} & = - \frac{\partial p}{\partial x} +
-    \nu \left( \frac{\partial^2 u}{\partial x^2} + \frac{\partial^2
-    u}{\partial y^2} \right) + f_u, \\
-    \frac{\partial v}{\partial t} + \frac{\partial (u v)}{\partial x} +
-    \frac{\partial (v v)}{\partial y} & = - \frac{\partial p}{\partial y} +
-    \nu \left( \frac{\partial^2 v}{\partial x^2} + \frac{\partial^2
-    v}{\partial y^2} \right) + f_v.
-\end{split}
-```
-
-In 3D, the equations become
-
-```math
-\begin{split}
-    \frac{\partial u}{\partial x} + \frac{\partial v}{\partial y} +
-    \frac{\partial w}{\partial z} & = 0, \\
-    \frac{\partial u}{\partial t} + \frac{\partial (u u)}{\partial x} +
-    \frac{\partial (v u)}{\partial y} + \frac{\partial (w u)}{\partial z} & = -
-    \frac{\partial p}{\partial x} + \nu \left( \frac{\partial^2 u}{\partial
-    x^2} + \frac{\partial^2 u}{\partial y^2} + \frac{\partial^2 u}{\partial
-    z^2} \right) + f_u, \\
-    \frac{\partial v}{\partial t} + \frac{\partial (u v)}{\partial x} +
-    \frac{\partial (v v)}{\partial y} + \frac{\partial (w v)}{\partial z} & = -
-    \frac{\partial p}{\partial y} + \nu \left( \frac{\partial^2 v}{\partial
-    x^2} + \frac{\partial^2 v}{\partial y^2} + \frac{\partial^2 v}{\partial
-    z^2}  \right) + f_v, \\
-    \frac{\partial w}{\partial t} + \frac{\partial (u w)}{\partial x} +
-    \frac{\partial (v w)}{\partial y} + \frac{\partial (w w)}{\partial z} & = -
-    \frac{\partial p}{\partial z} + \nu \left( \frac{\partial^2 w}{\partial
-    x^2} + \frac{\partial^2 w}{\partial y^2} + \frac{\partial^2 w}{\partial
-    z^2}  \right) + f_w. \\
-\end{split}
+\begin{align*}
+\sum_{\beta = 1}^d \frac{\partial u^\beta}{\partial x^\beta} & = 0, \\
+\frac{\partial u^\alpha}{\partial t} + \sum_{\beta = 1}^d
+\frac{\partial}{\partial x^\beta} (u^\alpha u^\beta) & = -\frac{\partial
+p}{\partial x^\alpha} + \nu \sum_{\beta = 1}^d \frac{\partial^2 u^\alpha}{\partial
+x^\beta \partial x^\beta} + f^\alpha.
+\end{align*}
 ```
 
 
@@ -65,84 +39,72 @@ be denoted ``\partial \mathcal{O}``, with normal ``n`` and surface element
 The mass equation in integral form is given by
 
 ```math
-\int_{\partial \mathcal{O}} V \cdot n \, \mathrm{d} \Gamma = 0.
+\int_{\partial \mathcal{O}} u \cdot n \, \mathrm{d} \Gamma = 0,
 ```
 
 where we have used the divergence theorem to convert the volume integral to a
 surface integral. Similarly, the momentum equations take the form
 
 ```math
-\frac{\partial }{\partial t} \int_\mathcal{O} V \, \mathrm{d} \Omega
-= \int_{\partial \mathcal{O}} \left( - V V^\mathsf{T} - P + \nu S \right) \cdot n \,
+\frac{\partial }{\partial t} \int_\mathcal{O} u \, \mathrm{d} \Omega
+= \int_{\partial \mathcal{O}} \left( - u u^\mathsf{T} - P + \nu S \right) \cdot n \,
 \mathrm{d} \Gamma + \int_\mathcal{O} f \mathrm{d} \Omega
 ```
 
-where ``P = p \mathrm{I} = \operatorname{diag}(p, p)`` is the hydrostatic stress tensor
-and ``S = \nabla V + (\nabla V)^\mathsf{T}`` is the strain-rate tensor. Here we
+where ``P = p \mathrm{I}`` is the hydrostatic stress tensor
+and ``S = \nabla u + (\nabla u)^\mathsf{T}`` is the strain-rate tensor. Here we
 have once again used the divergence theorem.
 
 !!! note "Strain-rate tensor"
     The second term in the strain rate tensor is optional, as
 
     ```math
-    \int_{\partial \mathcal{O}} (\nabla V)^\mathsf{T} \cdot n \, \mathrm{d} \Gamma = 0
+    \int_{\partial \mathcal{O}} (\nabla u)^\mathsf{T} \cdot n \, \mathrm{d} \Gamma = 0
     ```
 
-    due to the divergence freeness of ``V`` (mass equation).
+    due to the divergence freeness of ``u`` (mass equation).
 
 
 ## Boundary conditions
 
-Because we will use a Cartesian grid for discretization, the fields ``V``,
-``p``, and ``f`` are defined over the rectangular or prismatic domain ``\Omega
-= [x_1, x_2] \times [y_1, y_2]`` or ``\Omega = [x_1, x_2] \times [y_1, y_2]
-\times [z_1, z_2]``. Along each of the two or three dimensions, we allow for
-the following boundary conditions (here illustrated on the first boundary of
-the first dimension)
-
-- Periodic: ``V(x = x_1) = V(x = x_2)`` and ``p(x = x_1) = p(x = x_2)``
-- Dirichlet: ``V(x = x_1) = V_1``
-- Pressure: ``p(x = x_1) = p_1``
-- Symmetric (no movement through boundary ``x = x_1``, but free movement along
-  it): ``u(x = x_1) = 0``
+Consider a part ``\Gamma`` of the total boundary ``\partial \Omega``, with
+normal ``n``. We allow for the following types of boundary conditions on
+``\Gamma``:
+
+- Periodic boundary conditions: ``u(x) = u(x + \tau)`` and ``p(x) = p(x + \tau)`` for ``x \in
+  \Gamma``, where ``\tau`` is a constant translation to another part of the
+  boundary ``\partial \Omega``. This usually requires ``\Gamma`` and its
+  periodic counterpart ``\Gamma + \tau`` to be flat and rectangular (including
+  in this software suite).
+- Dirichlet boundary conditions: ``u = u_\text{BC}`` on ``\Gamma``. A common
+  situation here is that of a sticky wall, with "no slip boundary conditions.
+  Then ``u_\text{BC} = 0``.
+- Symmetric boundary conditions: Same velocity field at each side. This implies
+  zero Dirichlet conditions for the normal component (``n \cdot u = 0``), and
+  zero Neumann conditions for the parallel component: ``n \cdot \nabla (u - (n
+  \cdot u) n) = 0``.
+- Pressure boundary conditions: The pressure is prescribed (``p =
+  p_\text{BC}``), while the velocity has zero Neumann conditions:
+  ``n \cdot \nabla u = 0``.
 
 
 ## Pressure equation
 
-Taking the divergence of the two or tree momemtum equations yields a Poisson
+Taking the divergence of the momemtum equations yields a Poisson
 equation for the pressure:
 
 ```math
-- \nabla^2 p = \nabla \cdot \left( \nabla \cdot (V V^\mathsf{T}) \right) -
+- \nabla^2 p = \nabla \cdot \left( \nabla \cdot (u u^\mathsf{T}) \right) -
 \nabla \cdot f
 ```
 
-In 2D, this equation becomes
-
-```math
-- \left(\frac{\partial^2}{\partial x^2} + \frac{\partial^2}{\partial
-y^2}\right) p = \frac{\partial^2 (u u)}{\partial x^2} + 2 \frac{\partial^2 (u
-v)}{\partial x \partial y} + \frac{\partial^2 (v v)}{\partial y^2} - \left( \frac{\partial f_u}{\partial x} + \frac{\partial f_v}{\partial y} \right).
-```
-
-In 3D, this equation becomes
+In scalar notation, this becomes
 
 ```math
-\begin{split}
-    - \left( \frac{\partial^2}{\partial x^2} + \frac{\partial^2}{\partial
-    y^2} + \frac{\partial^2 }{\partial z^2} \right) p
-    & = \frac{\partial^2 (u u)}{\partial x^2}
-    + 2 \frac{\partial^2 (u v)}{\partial x \partial y}
-    + 2 \frac{\partial^2 (u w)}{\partial x \partial z} \\
-    & + 2 \frac{\partial^2 (v u)}{\partial y \partial x}
-    +   \frac{\partial^2 (v v)}{\partial y^2}
-    + 2 \frac{\partial^2 (v w)}{\partial y \partial z} \\
-    & + 2 \frac{\partial^2 (v u)}{\partial z \partial x}
-    + 2 \frac{\partial^2 (w v)}{\partial z \partial y}
-    +   \frac{\partial^2 (w w)}{\partial z^2} \\
-    & - \left( \frac{\partial f_u}{\partial x} + \frac{\partial f_v}{\partial
-    y} + \frac{\partial f_w}{\partial z} \right).
-\end{split}
+- \sum_{\alpha = 1}^d \frac{\partial^2}{\partial x^\alpha \partial x^\alpha} p = \sum_{\alpha
+= 1}^d \sum_{\beta = 1}^d \frac{\partial^2 }{\partial x^\alpha \partial
+x^\beta} (u^\alpha u^\beta) - \sum_{\alpha = 1}^d \frac{\partial
+f^\alpha}{\partial x^\alpha}.
 ```
 
 Note the absence of time derivatives in the pressure equation. While the
@@ -155,54 +117,65 @@ a constant. We set this constant to ``1``.
 
 ## Other quantities of interest
 
+### Reynolds number
+
+The Reynolds number is the inverse of the viscosity: ``Re = \frac{1}{\nu}``. It
+is the only flow parameter governing the incompressible Navier-Stokes
+equations.
+
+### Kinetic energy
+
+The local and total kinetic energy are defined by ``k = \frac{1}{2} \| u
+\|_2^2`` and ``K = \frac{1}{2} \| u \|_{L^2(\Omega)}^2 = \int_\Omega k \,
+\mathrm{d} \Omega``.
+
 ### Vorticity
 
-The vorticity is defined as ``\omega = \nabla \times V``.
+The vorticity is defined as ``\omega = \nabla \times u``.
 
 In 2D, it is a scalar field given by
 
 ```math
-\omega = -\frac{\partial u}{\partial y} + \frac{\partial v}{\partial x}.
+\omega = -\frac{\partial u^1}{\partial x^2} + \frac{\partial u^2}{\partial
+x^1}.
 ```
 
 In 3D, it is a vector field given by
 
 ```math
 \omega = \begin{pmatrix}
-    - \frac{\partial v}{\partial z} + \frac{\partial w}{\partial y} \\
-    \phantom{+} \frac{\partial u}{\partial z} - \frac{\partial w}{\partial x} \\
-    - \frac{\partial u}{\partial z} + \frac{\partial w}{\partial x}
+    - \frac{\partial u^2}{\partial x^3} + \frac{\partial u^3}{\partial x^2} \\
+    - \frac{\partial u^3}{\partial x^1} + \frac{\partial u^1}{\partial x^3}  \\
+    - \frac{\partial u^1}{\partial x^2} + \frac{\partial u^2}{\partial x^1}
 \end{pmatrix}.
 ```
 
 Note that the 2D vorticity is equal
-to the ``z``-component of the 3D vorticity.
+to the ``x^3``-component of the 3D vorticity.
 
 ### Stream function
 
-In 2D, the stream function ``\psi`` is a scalar field defined such that
+In 2D, the stream function ``\psi`` is a scalar field such that
 
 ```math
-u = \frac{\partial \psi}{\partial y}, \quad v = \frac{\partial \psi}{\partial x}.
+u^1 = \frac{\partial \psi}{\partial x^2}, \quad
+u^2 = -\frac{\partial \psi}{\partial x^1}.
 ```
 
-In 3D, the stream function ``\psi`` is a vector field defined such that
+It can be found by solving
 
 ```math
-V = \nabla \times \psi
+\nabla^2 \psi = - \omega.
 ```
 
-It is related to the 3D vorticity as
+In 3D, the stream function is a vector field such that
 
 ```math
-\nabla^2 \psi = \nabla \times \omega
+u = \nabla \times \psi.
 ```
 
-### Kinetic energy
+It can be found by solving
 
-The kinetic energy is defined by ``e = \frac{1}{2} \| V \|^2``.
-
-### Reynolds number
-
-The Reynolds number is the inverse of the viscosity: ``Re =
-\frac{1}{\nu}``.
+```math
+\nabla^2 \psi = \nabla \times \omega.
+```