Merge pull request #58 from FourierFlows/UpdatesDocs

Updates docs

Author: navidcy

docs/make.jl

@@ -7,7 +7,9 @@ makedocs(modules=[FourierFlows],
           "Home" => "index.md",
           "Modules" => Any[
               "modules/twodturb.md",
-              "modules/barotropicqg.md"
+              "modules/barotropicqg.md",
+              "modules/kuramotosivashinsky.md",
+              "modules/traceradvdiff.md"
               ],
           "DocStrings" => Any[
               "man/docstrings.md"

docs/src/index.md

@@ -66,20 +66,17 @@ Here's an overview of the code structure:
         - `barotropicqg.jl`: Defines a `BarotropicQG` module that provides
                 several solvers for the barotropic QG model that permit beta,
                 topography, beta + topography, and forcing.
-        - `twomodeboussinesq.jl`: Defines a `TwoModeBoussinesq` module
-                that provides solvers for a two-mode truncation of the
-                rotating, stratified Boussinesq equation.
+        - `kuramotosivashinsky.jl`: Defines a `KuramotoSivashinsky` module that
+                solves the Kuramoto-Sivashinsky.
         - `traceradvdiff.jl`: Defines a `TracerAdvDiff` module that
                 provides a solver for a two-dimensional and periodic tracer
                 field in a given 2D flow (u, w), which can be an arbitrary
                 function of x, z, and t.
-        - `tracerpatcheqn.jl`: ...
-
 
 ## Writing fast solvers
 
 The performance-intensive part of the code involves just two functions: the
-timestepping scheme `stepforward!`, and the function `calcN!` that
+time-stepping scheme `stepforward!`, and the function `calcN!` that
 calculates the nonlinear part of the given equation's right-hand side.
 Optimization of these two functions for a given problem will produce the
 fastest possible code.
@@ -91,11 +88,11 @@ fastest possible code.
 
   > McWilliams, J. C. (1984). The emergence of isolated coherent vortices in turbulent flow. *J. Fluid Mech.*, **146**, 21-43
 
-- `examples/barotropicqg/decayingbetaturb.jl`: An example script that simulates decaying quasi-geostrophic flow on a beta-plane.
+- `examples/barotropicqg/decayingbetaturb.jl`: An example script that simulates decaying quasi-geostrophic flow on a beta-plane demonstrating zonation.
 
 - `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
+  > Constantinou, N. C. (2018). A barotropic model of eddy saturation. *J. Phys. Oceanogr.*, **48 (2)**, 397-411
 
 
 
@@ -105,6 +102,8 @@ fastest possible code.
 Pages = [
     "modules/twodturb.md",
     "modules/barotropicqg.md"
+    "modules/kuramotosivashinsky.md"
+    "modules/traceradvdiff.md"
         ]
 Depth = 1
 ```
@@ -141,7 +140,9 @@ Depth = 2
 ```@index
 Pages = [
     "modules/twodturb.md",
-    "modules/barotropicqg.md",
+    "modules/barotropicqg.md"
+    "modules/kuramotosivashinsky.md"
+    "modules/traceradvdiff.md"
     "man/docstrings.md",
     ]
 ```

docs/src/modules/barotropicqg.md

@@ -1,8 +1,8 @@
-# BarotropicQG Modules
+# BarotropicQG Module
 
 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,\upsilon) = (-\partial_y\psi, \partial_x\psi)$. All flow
+streamfunction $\psi$ as $(u, \upsilon) = (-\partial_y\psi, \partial_x\psi)$. All flow
 fields can be obtained from the quasi-geostrophic potential vorticity (QGPV).
 Here the QGPV is
 
@@ -11,7 +11,7 @@ $$\underbrace{f_0 + \beta y}_{\text{planetary PV}} + \underbrace{(\partial_x \up
 	\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$.
+the plane of motion, $\zeta\equiv \partial_x \upsilon- \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:
 

docs/src/modules/kuramotosivashinsky.md

@@ -0,0 +1,16 @@
+# Kuramoto-Sivashinsky Module
+
+This module solves the Kuramoto-Sivashinsky equation for $u(x,t)$:
+
+$$\partial_t u + \partial_x^4 u + \partial_x^2 u + u\partial_x u = 0\ .$$
+
+The equation is time-stepped forward in Fourier space:
+
+$$\partial_t \widehat{u} + k_x^4 \widehat{u} - k_x^2 \widehat{u} + \widehat{ u\partial_x u } = 0\ .$$
+
+Thus:
+
+$$\mathcal{L} = k_x^2 - k_x^4\ ,$$
+$$\mathcal{N}(\widehat{u}) = - \mathrm{FFT}(u \partial_x u)\ .$$
+
+The function `calcN!` implements dealiasing to avoid energy piling up at the grid-scale.

docs/src/modules/traceradvdiff.md

@@ -1,9 +1,8 @@
-# TracerAdvDiff
+# TracerAdvDiff Module
 
 This module solves the advection diffusion equation for a passive tracer
-concentration `c` in two-dimensions:
+concentration $c(x,y,t)$ in two-dimensions:
 
-$$c_t + \mathbf{u} \cdot \nabla c = \kappa \nabla^2 c$$ ,
+$$\partial_t c + \boldsymbol{u} \boldsymbol{\cdot} \boldsymbol{\nabla} c = \kappa \nabla^2 c\ ,$$
 
-where $\mathbf{u} = (u,v)$ is the two-dimensional advecting velocity and $\kappa$
-is the diffusivity.
+where $\boldsymbol{u} = (u,\upsilon)$ is the two-dimensional advecting velocity and $\kappa$ is the diffusivity.