Merge pull request #191 from FourierFlows/ncc/docs-patch

Enhances docstrings and Docs/modules
FourierFlows · Jan 28, 2021 · e0cc346 · e0cc346
2 parents 4fb7c56 + 62f6e10
commit e0cc346
Show file tree

Hide file tree

Showing 19 changed files with 769 additions and 389 deletions.
diff --git a/Project.toml b/Project.toml
@@ -6,6 +6,7 @@ version = "0.11.2"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 FourierFlows = "2aec4490-903f-5c70-9b11-9bed06a700e1"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
@@ -18,6 +19,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 CUDA = "^1, ^2"
+DocStringExtensions = "^0.8"
 FFTW = "^1"
 FourierFlows = "^0.6.10"
 JLD2 = "^0.1, ^0.2, ^0.3"

diff --git a/README.md b/README.md
@@ -29,6 +29,7 @@ Geophysical Fluid Dynamics on periodic domains using Fourier-based pseudospectra
 To install, do
 ```julia
 ] add GeophysicalFlows
+] instantiate
 ```
 
 ## Examples

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -18,10 +18,10 @@ Examples aim to demonstrate the main functionalities of each module. Have a look
     of ``u`` like, e.g.,
 
     ```math
-    u(x) = \sum_{k_x} \hat{u}(k_x) \, e^{i k_x x} \ .
+    u(x) = \sum_{k_x} \hat{u}(k_x) \, e^{i k_x x} .
     ```
 
-    The convention used inside modules is that the Fourier transform of a variable, e.g., `u` 
+    The convention used in the modules is that the Fourier transform of a variable, e.g., `u` 
     is denoted with `uh` (where the trailing `h` is there to imply "hat"). Note, however, 
     that `uh` is obtained via a FFT of `u` and due to different normalization factors that the 
     FFT algorithm uses, `uh` _is not_ exactly the same as ``\hat{u}`` above. Instead,

diff --git a/docs/src/man/functions.md b/docs/src/man/functions.md
@@ -1,19 +1,19 @@
 # Functions
 
 
-## Functions exported from `GeophysicalFlows`:
+## Functions exported from `TwoDNavierStokes`:
 
 ```@autodocs
-Modules = [GeophysicalFlows]
+Modules = [GeophysicalFlows.TwoDNavierStokes]
 Private = false
 Order = [:function]
 ```
 
-## Functions exported from `TwoDNavierStokes`:
+## Private functions from `TwoDNavierStokes`:
 
 ```@autodocs
 Modules = [GeophysicalFlows.TwoDNavierStokes]
-Private = false
+Public = false
 Order = [:function]
 ```
 

diff --git a/docs/src/man/types.md b/docs/src/man/types.md
@@ -1,49 +1,54 @@
 # Private types
 
-## Private types in module `GeophysicalFlows`:
-
-```@autodocs
-Modules = [GeophysicalFlows]
-Public = false
-Order = [:type]
-```
-
 ## Private types in module `TwoDNavierStokes`:
 
-```@autodocs
-Modules = [GeophysicalFlows.TwoDNavierStokes]
-Public = false
-Order = [:type]
+```@docs
+GeophysicalFlows.TwoDNavierStokes.Params
+GeophysicalFlows.TwoDNavierStokes.Vars
+GeophysicalFlows.TwoDNavierStokes.DecayingVars
+GeophysicalFlows.TwoDNavierStokes.ForcedVars
+GeophysicalFlows.TwoDNavierStokes.StochasticForcedVars
 ```
 
 ## Private types in module `SingleLayerQG`:
 
-```@autodocs
-Modules = [GeophysicalFlows.SingleLayerQG]
-Public = false
-Order = [:type]
+```@docs
+GeophysicalFlows.SingleLayerQG.Params
+GeophysicalFlows.SingleLayerQG.BarotropicQGParams
+GeophysicalFlows.SingleLayerQG.EquivalentBarotropicQGParams
+GeophysicalFlows.SingleLayerQG.Vars
+GeophysicalFlows.SingleLayerQG.DecayingVars
+GeophysicalFlows.SingleLayerQG.ForcedVars
+GeophysicalFlows.SingleLayerQG.StochasticForcedVars
 ```
 
 ## Private types in module `BarotropicQGQL`:
 
-```@autodocs
-Modules = [GeophysicalFlows.BarotropicQGQL]
-Public = false
-Order = [:type]
+```@docs
+GeophysicalFlows.BarotropicQGQL.Params
+GeophysicalFlows.BarotropicQGQL.Vars
+GeophysicalFlows.BarotropicQGQL.DecayingVars
+GeophysicalFlows.BarotropicQGQL.ForcedVars
+GeophysicalFlows.BarotropicQGQL.StochasticForcedVars
 ```
 
 ## Private types in module `MultiLayerQG`:
 
-```@autodocs
-Modules = [GeophysicalFlows.MultiLayerQG]
-Public = false
-Order = [:type]
+```@docs
+GeophysicalFlows.MultiLayerQG.Params
+GeophysicalFlows.MultiLayerQG.SingleLayerParams
+GeophysicalFlows.MultiLayerQG.Vars
+GeophysicalFlows.MultiLayerQG.DecayingVars
+GeophysicalFlows.MultiLayerQG.ForcedVars
+GeophysicalFlows.MultiLayerQG.StochasticForcedVars
 ```
 
 ## Private types in module `SurfaceQG`:
 
-```@autodocs
-Modules = [GeophysicalFlows.SurfaceQG]
-Public = false
-Order = [:type]
+```@docs
+GeophysicalFlows.SurfaceQG.Params
+GeophysicalFlows.SurfaceQG.Vars
+GeophysicalFlows.SurfaceQG.DecayingVars
+GeophysicalFlows.SurfaceQG.ForcedVars
+GeophysicalFlows.SurfaceQG.StochasticForcedVars
 ```
diff --git a/docs/src/modules/barotropicqgql.md b/docs/src/modules/barotropicqgql.md
@@ -27,13 +27,13 @@ can be obtained from the quasi-geostrophic potential vorticity (QGPV). Here, the
 
 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``. After we apply the eddy-mean flow decomposition 
+topographic PV with ``\eta \equiv f_0 h / H``. After we apply the eddy-mean flow decomposition 
 above, the QGPV dynamics are:
 
 ```math
 \begin{aligned}
 \partial_t \overline{\zeta} & + \mathsf{J}(\overline{\psi}, \underbrace{\overline{\zeta} + \overline{\eta}}_{\equiv \overline{q}}) + \overline{\mathsf{J}(\psi', \underbrace{\zeta' + \eta'}_{\equiv q'})} = \underbrace{- \left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu}
-\right] \overline{\zeta} }_{\textrm{dissipation}} ,\\
+\right] \overline{\zeta} }_{\textrm{dissipation}} , \\
 \partial_t \zeta' &+ \mathsf{J}(\psi', \overline{q}) + \mathsf{J}(\overline{\psi}, q') + \underbrace{\mathsf{J}(\psi', q') - \overline{\mathsf{J}(\psi', q')}}_{\textrm{EENL}} + 
 \beta \partial_x \psi' = \underbrace{-\left[\mu + \nu(-1)^{n_\nu} \nabla^{2n_\nu}
 \right] \zeta'}_{\textrm{dissipation}} + F .
@@ -56,18 +56,42 @@ The equation is time-stepped forward in Fourier space:
 \partial_t \widehat{\zeta} = - \widehat{\mathsf{J}(\psi, q)}^{\textrm{QL}} + \beta \frac{i k_x}{|𝐤|^2} \widehat{\zeta} - \left ( \mu + \nu |𝐤|^{2n_\nu} \right ) \widehat{\zeta} + \widehat{F} .
 ```
 
-In doing so the Jacobian is computed in the conservative form: ``\mathsf{J}(f,g) =
-\partial_y [ (\partial_x f) g] -\partial_x[ (\partial_y f) g]``. The superscript QL on the 
-Jacobian term above denotes that triad interactions that correspond to the EENL term are 
-removed.
+The state variable `sol` is the Fourier transform of vorticity, [`ζh`](@ref GeophysicalFlows.BarotropicQGQL.Vars).
 
-Thus:
+The Jacobian is computed in the conservative form: ``\mathsf{J}(f, g) = \partial_y [ (\partial_x f) g] 
+- \partial_x [ (\partial_y f) g]``. The superscript QL on the Jacobian term above denotes that 
+triad interactions that correspond to the EENL term are removed.
 
-```math
-\begin{aligned}
-L & = \beta \frac{i k_x}{|𝐤|^2} - \mu - \nu |𝐤|^{2n_\nu} ,\\
-N(\widehat{\zeta}) & = - i k_x \mathrm{FFT}(u q)^{\textrm{QL}} - i k_y \mathrm{FFT}(v q)^{\textrm{QL}} + \widehat{F}.
-\end{aligned}
+The linear operator is constructed in `Equation`
+
+```@docs
+GeophysicalFlows.BarotropicQGQL.Equation
+```
+
+and the nonlinear terms are computed via
+
+```@docs
+GeophysicalFlows.BarotropicQGQL.calcN!
+```
+
+which in turn calls [`calcN_advection!`](@ref GeophysicalFlows.BarotropicQGQL.calcN_advection!) 
+and [`addforcing!`](@ref GeophysicalFlows.BarotropicQGQL.addforcing!).
+
+
+### Parameters and Variables
+
+All required parameters are included inside [`Params`](@ref GeophysicalFlows.BarotropicQGQL.Params)
+and all module variables are included inside [`Vars`](@ref GeophysicalFlows.BarotropicQGQL.Vars).
+
+For decaying case (no forcing, ``F = 0``), `vars` can be constructed with [`DecayingVars`](@ref GeophysicalFlows.BarotropicQGQL.DecayingVars). 
+For the forced case (``F \ne 0``) the `vars` struct is with [`ForcedVars`](@ref GeophysicalFlows.BarotropicQGQL.ForcedVars) or [`StochasticForcedVars`](@ref GeophysicalFlows.BarotropicQGQL.StochasticForcedVars).
+
+
+### Helper functions
+
+```@docs
+GeophysicalFlows.BarotropicQGQL.updatevars!
+GeophysicalFlows.BarotropicQGQL.set_zeta!
 ```
 
 

diff --git a/docs/src/modules/multilayerqg.md b/docs/src/modules/multilayerqg.md
@@ -10,16 +10,16 @@ is the number of fluid layers.
 The QGPV in each layer is
 
 ```math
-\mathrm{QGPV}_j = q_j + \underbrace{f_0 + \beta y}_{\textrm{planetary PV}} + \delta_{j, n} \underbrace{\frac{f_0 h}{H_n}}_{\textrm{topographic PV}}, \quad j = 1, \dots, n \ .
+\mathrm{QGPV}_j = q_j + \underbrace{f_0 + \beta y}_{\textrm{planetary PV}} + \delta_{j, n} \underbrace{\frac{f_0 h}{H_n}}_{\textrm{topographic PV}}, \quad j = 1, \dots, n .
 ```
 
 where ``q_j`` incorporates the relative vorticity in each layer ``\nabla^2 \psi_j`` and the 
 vortex stretching terms:
 
 ```math
-q_1 = \nabla^2 \psi_1 + F_{3/2, 1} (\psi_2 - \psi_1) \ ,\\
-q_j = \nabla^2 \psi_j + F_{j-1/2, j} (\psi_{j-1} - \psi_j) + F_{j+1/2, j} (\psi_{j+1} - \psi_j) \ , \quad j = 2, \dots, n-1 \ ,\\
-q_n = \nabla^2 \psi_n + F_{n-1/2, n} (\psi_{n-1} - \psi_n) \ .
+q_1 = \nabla^2 \psi_1 + F_{3/2, 1} (\psi_2 - \psi_1) ,\\
+q_j = \nabla^2 \psi_j + F_{j-1/2, j} (\psi_{j-1} - \psi_j) + F_{j+1/2, j} (\psi_{j+1} - \psi_j) , \quad j = 2, \dots, n-1 ,\\
+q_n = \nabla^2 \psi_n + F_{n-1/2, n} (\psi_{n-1} - \psi_n) .
 ```
 
 with
@@ -47,7 +47,7 @@ where
  0           &                  \ddots  &   \ddots   & \ddots & \\
  \vdots      &                          &            &        &  0 \\
  0           &       \cdots             &   0   & F_{n-1/2, n} & -F_{n-1/2, n}
-\end{pmatrix}\ .
+\end{pmatrix} .
 ```
 
 Including an imposed zonal flow ``U_j(y)`` in each layer, the equations of motion are:
@@ -59,33 +59,10 @@ Including an imposed zonal flow ``U_j(y)`` in each layer, the equations of motio
 with
 
 ```math
-\partial_y Q_j \equiv \beta - \partial_y^2 U_j - (1-\delta_{j,1}) F_{j-1/2, j} (U_{j-1} - U_j) - (1 - \delta_{j,n}) F_{j+1/2, j} (U_{j+1} - U_j) + \delta_{j,n} \partial_y \eta \ , \\
-\partial_x Q_j \equiv \delta_{j, n} \partial_x \eta \ .
+\partial_y Q_j \equiv \beta - \partial_y^2 U_j - (1-\delta_{j,1}) F_{j-1/2, j} (U_{j-1} - U_j) - (1 - \delta_{j,n}) F_{j+1/2, j} (U_{j+1} - U_j) + \delta_{j,n} \partial_y \eta , \\
+\partial_x Q_j \equiv \delta_{j, n} \partial_x \eta .
 ```
 
-### Helper functions
-
-```@docs
-GeophysicalFlows.MultiLayerQG.set_q!
-GeophysicalFlows.MultiLayerQG.set_ψ!
-GeophysicalFlows.MultiLayerQG.updatevars!
-```
-
-### Diagnostics
-
-The eddy kinetic energy in each layer and the eddy potential energy that corresponds to each 
-fluid interface is computed via `energies()`:
-
-```@docs
-GeophysicalFlows.MultiLayerQG.energies
-```
-
-The lateral eddy fluxes in each layer and the vertical fluxes across fluid interfaces are
-computed via `fluxes()`:
-
-```@docs
-GeophysicalFlows.MultiLayerQG.fluxes
-```
 
 ### Implementation
 
@@ -101,13 +78,14 @@ The equations of motion are time-stepped forward in Fourier space:
 
 ```math
 \partial_t \widehat{q}_j = - \widehat{\mathsf{J}(\psi_j, q_j)}  - \widehat{U_j \partial_x Q_j} - \widehat{U_j \partial_x q_j}
-+ \widehat{(\partial_y \psi_j) \partial_x Q_j}  - \widehat{(\partial_x \psi_j)(\partial_y Q_j)} + \delta_{j, n} \mu |𝐤|^{2} \widehat{\psi}_n - \nu |𝐤|^{2n_\nu} \widehat{q}_j \ .
++ \widehat{(\partial_y \psi_j) \partial_x Q_j}  - \widehat{(\partial_x \psi_j)(\partial_y Q_j)} + \delta_{j, n} \mu |𝐤|^{2} \widehat{\psi}_n - \nu |𝐤|^{2n_\nu} \widehat{q}_j .
 ```
 
 In doing so the Jacobian is computed in the conservative form: ``\mathsf{J}(f,g) =
 \partial_y [ (\partial_x f) g] - \partial_x[ (\partial_y f) g]``.
 
-Equations are formulated using $q_j$ as the state variables, i.e., `sol = qh`.
+The state variable `sol` consists of the Fourier transforms of ``q_j`` at each layer, i.e., 
+[`qh`](@ref GeophysicalFlows.MultiLayerQG.Vars).
 
 The linear operator is constructed in `Equation`
 
@@ -116,23 +94,50 @@ GeophysicalFlows.MultiLayerQG.Equation
 GeophysicalFlows.MultiLayerQG.hyperviscosity
 ```
 
-The nonlinear terms is computed via
+The nonlinear terms are computed via
 
 ```@docs
 GeophysicalFlows.MultiLayerQG.calcN!
 ```
-which, in turn, calls 
+
+which in turn calls [`calcN_advection!`](@ref GeophysicalFlows.MultiLayerQG.calcN_advection!) 
+and [`addforcing!`](@ref GeophysicalFlows.MultiLayerQG.addforcing!).
+
+
+### Parameters and Variables
+
+All required parameters are included inside [`Params`](@ref GeophysicalFlows.MultiLayerQG.Params)
+and all module variables are included inside [`Vars`](@ref GeophysicalFlows.MultiLayerQG.Vars).
+
+For decaying case (no forcing, ``F=0``), `vars` can be constructed with [`DecayingVars`](@ref GeophysicalFlows.MultiLayerQG.DecayingVars). 
+For the forced case (``F \ne 0``) the `vars` struct is with [`ForcedVars`](@ref GeophysicalFlows.MultiLayerQG.ForcedVars) or [`StochasticForcedVars`](@ref GeophysicalFlows.MultiLayerQG.StochasticForcedVars).
+
+
+### Helper functions
+
+```@docs
+GeophysicalFlows.MultiLayerQG.set_q!
+GeophysicalFlows.MultiLayerQG.set_ψ!
+GeophysicalFlows.MultiLayerQG.updatevars!
+```
+
+### Diagnostics
+
+The eddy kinetic energy in each layer and the eddy potential energy that corresponds to each 
+fluid interface is computed via `energies()`:
 
 ```@docs
-GeophysicalFlows.MultiLayerQG.calcN_advection!
+GeophysicalFlows.MultiLayerQG.energies
 ```
-and
+
+The lateral eddy fluxes in each layer and the vertical fluxes across fluid interfaces are
+computed via `fluxes()`:
 
 ```@docs
-GeophysicalFlows.MultiLayerQG.addforcing!
+GeophysicalFlows.MultiLayerQG.fluxes
 ```
- 
- 
- ## Examples
+
+
+## Examples
 
  - `examples/multilayerqg_2layer.jl`: A script that simulates the growth and equilibration of baroclinic eddy turbulence in the Phillips 2-layer model.