Merge pull request #43 from FourierFlows/UpdateDocs

Update docs

Author: navidcy

README.md

@@ -82,15 +82,15 @@ fastest possible code.
 
 ## Future work
 
-The code is in the chaos stage of development. A main goal for the future
+The code is in the chaotic stage of development. A main goal for the future
 is to permit the use of shared memory parallelism in the compute-intensive
 routines (shared-memory parallelism provided already by FFTW/MKLFFT, but
 is not yet native to Julia for things like element-wise matrix multiplication,
 addition, and assignment). This feature may possibly be enabled by
 Intel Lab's [ParallelAccelerator][] package.
 
 
-# Authors
+# Developers
 
 FourierFlows is currently being developed by [Gregory L. Wagner][] (@glwagner)
 and [Navid C. Constantinou][] (@navidcy).

docs/make.jl

@@ -5,6 +5,10 @@ makedocs(modules=[FourierFlows],
          sitename = "FourierFlows.jl",
          pages = Any[
           "Home" => "index.md",
+          "Modules" => Any[
+              "modules/twodturb.md",
+              "modules/barotropicqg.md"
+              ],
           "DocStrings" => Any[
               "man/docstrings.md"
               ]

docs/src/index.md

@@ -28,11 +28,12 @@ The code solves partial differential equations of the general form:
 
 $\partial_t u = \mathcal{L}u + \mathcal{N}(u)\ .$
 
-The $\mathcal{L}u$ part is time-stepped forward using an implicit scheme; the
-$\mathcal{N}(u)$ part is time-stepped forward using an explicit scheme.
+We decompose the right hand side of the above in a linear part ($\mathcal{L}u$)
+and a nonlinear part ($\mathcal{N}(u)$). The time steppers treat the linear and
+nonlinear parts differently.
 
 The coefficients for the linear operator $\mathcal{L}$ are stored in array `LC`.
-The term $\mathcal{N}(u)$ is computed for by calling the function `calcN`.
+The term $\mathcal{N}(u)$ is computed for by calling the function `calcN!`.
 
 
 ## Source code organization
@@ -56,7 +57,7 @@ Here's an overview of the code structure:
         various time-steppers. Current implemented time-steppers are:
         - Forward Euler (+ Filtered Forward Euler)
         - 3rd-order Adams-Bashforth (AB3)
-        - 4th-order Runge-Kutta (RK4)
+        - 4th-order Runge-Kutta (RK4) (+ Filtered ETDRK4)
         - 4th-order Runge-Kutta Exponential Time Differencing (ETDRK4)
         (+ Filtered ETDRK4)
     - `physics/`
@@ -86,18 +87,32 @@ fastest possible code.
 
 ## Examples
 
-An example script that simulates decaying two-dimensional turbulence reproducing
-the results of the paper by
+- `examples/twodturb/McWilliams.jl`: A script that simulates decaying two-dimensional turbulence reproducing the results of the paper by
 
-  > McWilliams, J. C. (1984). The emergence of isolated coherent vortices in turbulent flow. *J. Fluid Mech.*, **146**, 21-43.
+  > McWilliams, J. C. (1984). The emergence of isolated coherent vortices in turbulent flow. *J. Fluid Mech.*, **146**, 21-43
 
-is found in `examples/twodturb/McWilliams.jl`.
+- `examples/barotropicqg/decayingbetaturb.jl`: An example script that simulates decaying quasi-geostrophic flow on a beta-plane.
 
+- `examples/barotropicqg/ACConelayer.jl`: A script that simulates barotropic quasi-geostrophic flow above topography reproducing the results of the paper by
+
+  > Constantinou, N. C. (2018). A barotropic model of eddy saturation. *J. Phys. Oceanogr.*, in press, doi:10.1175/JPO-D-17-0182.1
+
+
+
+## Tutorials
+
+```@contents
+Pages = [
+    "modules/twodturb.md",
+    "modules/barotropicqg.md"
+        ]
+Depth = 1
+```
 
 
 ## Future work
 
-The code is in the chaos stage of development. A main goal for the future
+The code is in the chaotic stage of development. A main goal for the future
 is to permit the use of shared memory parallelism in the compute-intensive
 routines (shared-memory parallelism provided already by FFTW/MKLFFT, but
 is not yet native to Julia for things like element-wise matrix multiplication,
@@ -106,14 +121,16 @@ Intel Lab's
 [ParallelAccelerator](https://github.com/IntelLabs/ParallelAccelerator.jl)
 package.
 
-## Authors
+## Developers
 
 FourierFlows is currently being developed by [Gregory L. Wagner](https://glwagner.github.io) and [Navid C. Constantinou](http://www.navidconstantinou.com).
 
 ## DocStrings
 
 ```@contents
 Pages = [
+    "modules/twodturb.md",
+    "modules/barotropicqg.md",
     "man/docstrings.md",
     ]
 Depth = 2
@@ -123,6 +140,8 @@ Depth = 2
 
 ```@index
 Pages = [
+    "modules/twodturb.md",
+    "modules/barotropicqg.md",
     "man/docstrings.md",
     ]
 ```

docs/src/modules/barotropicqg.md

@@ -0,0 +1,40 @@
+# BarotropicQG Modules
+
+This module solves the quasi-geostrophic barotropic vorticity equation on a
+beta-plane of variable fluid depth $H-h(x,y)$. The flow is obtained through a
+streamfunction $\psi$ as $(u,v) = (-\partial_y\psi, \partial_x\psi)$. All flow
+fields can be obtained from the quasi-geostrophic potential vorticity (QGPV).
+Here the QGPV is
+
+$$\underbrace{f_0 + \beta y}_{\text{planetary PV}} + \underbrace{(\partial_x v
+	- \partial_y u)}_{\text{relative vorticity}} +
+	\underbrace{\frac{f_0 h}{H}}_{\text{topographic PV}}.$$
+
+The dynamical variable is the component of the vorticity of the flow normal to
+the plane of motion, $\zeta\equiv \partial_x v- \partial_y u = \nabla^2\psi$.
+Also, we denote the topographic PV with $\eta\equiv f_0 h/H$. Thus, the
+equation solved by the module is:
+
+$$\partial_t \zeta + J(\psi, \underbrace{\zeta + \eta}_{\equiv q}) +
+\beta\partial_x\psi = \underbrace{-\left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu}
+\right] \zeta }_{\textrm{dissipation}} + f\ .$$
+
+where $J(f,g) = (\partial_xf)(\partial_y g)-(\partial_x g)(\partial_y f)$. On
+the right hand side, $f(x,y,t)$ is forcing, $\mu$ is linear drag, and $\nu$ is
+hyperviscosity. Plain old viscosity corresponds to $n_{\nu}=1$. The sum of
+relative vorticity and topographic PV is denoted with $q\equiv\zeta+\eta$.
+
+
+The equation is time-stepped forward in Fourier space:
+
+$$\partial_t \widehat{\zeta} = - \widehat{J(\psi, q)} +\beta\frac{\mathrm{i}k_x}{k^2}\widehat{\zeta} -\left(\mu
++\nu k^{2n_\nu}\right) \widehat{\zeta}  + \widehat{f}\ .$$
+
+In doing so the Jacobian is computed in the conservative form: $J(f,g) =
+\partial_y [ (\partial_x f) g] -\partial_x[ (\partial_y f) g]$.
+
+Thus:
+
+$$\mathcal{L} = \beta\frac{\mathrm{i}k_x}{k^2} - \mu - \nu k^{2n_\nu}\ ,$$
+$$\mathcal{N}(\widehat{\zeta}) = - \mathrm{i}k_x \mathrm{FFT}(u q)-
+	\mathrm{i}k_y \mathrm{FFT}(v q)\ .$$

docs/src/modules/twodturb.md

@@ -0,0 +1,29 @@
+# TwoDTurb Module
+
+This module solves two-dimensional incompressible turbulence. The flow is given
+through a streamfunction $\psi$ as $(u,v) = (-\partial_y\psi, \partial_x\psi)$.
+The dynamical variable used here is the component of the vorticity of the flow
+normal to the plane of motion, $q=\partial_x v- \partial_y u = \nabla^2\psi$.
+The equation solved by the module is:
+
+$$\partial_t q + J(\psi, q) = \underbrace{-\left[\mu(-1)^{n_\mu} \nabla^{2n_\mu}
++\nu(-1)^{n_\nu} \nabla^{2n_\nu}\right] q}_{\textrm{dissipation}} + f\ .$$
+
+where $J(f,g) = (\partial_xf)(\partial_y g)-(\partial_x g)(\partial_y f)$. On
+the right hand side, $f(x,y,t)$ is forcing, $\mu$ is hypoviscosity, and $\nu$ is
+hyperviscosity. Plain old linear drag corresponds to $n_{\mu}=0$, while normal
+viscosity corresponds to $n_{\nu}=1$.
+
+The equation is time-stepped forward in Fourier space:
+
+$$\partial_t \widehat{q} = - \widehat{J(\psi, q)} -\left[\mu k^{2n_\mu}
++\nu k^{2n_\nu}\right] \widehat{q}  + \widehat{f}\ .$$
+
+In doing so the Jacobian is computed in the conservative form: $J(f,g) =
+\partial_y [ (\partial_x f) g] -\partial_x[ (\partial_y f) g]$.
+
+Thus:
+
+$$\mathcal{L} = -\mu k^{-2n_\mu} - \nu k^{2n_\nu}\ ,$$
+$$\mathcal{N}(\widehat{q}) = - \mathrm{i}k_x \mathrm{FFT}(u q)-
+	\mathrm{i}k_y \mathrm{FFT}(v q)\ .$$