Merge pull request #73 from FourierFlows/UpdateDocs

Adds details in twodturb module in docs

Author: navidcy

docs/src/modules/barotropicqg.md

@@ -45,4 +45,4 @@ $$\mathcal{N}(\widehat{\zeta}) = - \mathrm{i}k_x \mathrm{FFT}(u q)-
 
 - `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.*, **48 (2)**, 397-411
+  > Constantinou, N. C. (2018). A barotropic model of eddy saturation. *J. Phys. Oceanogr.*, **48 (2)**, 397-411.

docs/src/modules/twodturb.md

@@ -24,23 +24,99 @@ 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}\ .$$
+$$\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]$.
+In doing so the Jacobian is computed in the conservative form: $\J(a,b) =
+\partial_y [ (\partial_x a) b] -\partial_x[ (\partial_y a) b]$.
 
 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}(\upsilon q)\ .$$
+	\mathrm{i}k_y \mathrm{FFT}(\upsilon q) + \widehat{f}\ .$$
+
+
+### AbstractTypes and Functions
+
+**Params**
+
+For the unforced case ($f=0$) parameters AbstractType is build with `Params` and it includes:
+- `nu`:   Float; viscosity or hyperviscosity coefficient.
+- `nnu`: Integer$>0$; the order of viscosity $n_\nu$. Case $n_\nu=1$ give normal viscosity.
+- `mu`: Float; bottom drag or hypoviscosity coefficient.
+- `nmu`: Integer$\ge 0$; the order of hypodrag $n_\mu$. Case $n_\mu=0$ give plain linear drag $\mu$.
+
+For the forced case ($f\ne 0$) parameters AbstractType is build with `ForcedParams`. It includes all parameters in `Params` and additionally:
+- `calcF!`: Function that calculates the forcing $\widehat{f}$
+
+
+**Vars**
+
+For the unforced case ($f=0$) variables AbstractType is build with `Vars` and it includes:
+- `q`: Array of Floats; relative vorticity.
+- `U`: Array of Floats; $x$-velocity, $u$.
+- `V`: Array of Floats; $y$-velocity, $v$.
+- `sol`: Array of Complex; the solution, $\widehat{q}$.
+- `qh`: Array of Complex; the Fourier transform $\widehat{q}$.
+- `Uh`: Array of Complex; the Fourier transform $\widehat{u}$.
+- `Vh`: Array of Complex; the Fourier transform $\widehat{v}$.
+
+For the forced case ($f\ne 0$) variables AbstractType is build with `ForcedVars`. It includes all variables in `Vars` and additionally:
+- `Fh`: Array of Complex; the Fourier transform $\widehat{f}$.
+- `prevsol`: Array of Complex; the values of the solution `sol` at the previous time-step (useful for calculating the work done by the forcing).
+
+
+
+**`calcN!` function**
+
+The nonlinear term $\mathcal{N}(\widehat{q})$ is computed via functions:
+
+- `calcN_advection!`: computes $- \widehat{J(\psi, q)}$ and stores it in array `N`.
+
+```julia
+function calcN_advection!(N, sol, t, s, v, p, g)
+  @. v.Uh =  im * g.l  * g.invKKrsq * sol
+  @. v.Vh = -im * g.kr * g.invKKrsq * sol
+  @. v.qh = sol
+
+  A_mul_B!(v.U, g.irfftplan, v.Uh)
+  A_mul_B!s(v.V, g.irfftplan, v.Vh)
+  A_mul_B!(v.q, g.irfftplan, v.qh)
+
+  @. v.U *= v.q # U*q
+  @. v.V *= v.q # V*q
+
+  A_mul_B!(v.Uh, g.rfftplan, v.U) # \hat{U*q}
+  A_mul_B!(v.Vh, g.rfftplan, v.V) # \hat{U*q}
+
+  @. N = -im*g.kr*v.Uh - im*g.l*v.Vh
+  nothing
+end
+```
+
+- `calcN_forced!`: computes $- \widehat{J(\psi, q)}$ via `calcN_advection!` and then adds to it the forcing $\widehat{f}$ computed via `calcF!` function. Also saves the solution $\widehat{q}$ of the previous time-step in array `prevsol`.
+
+```julia
+function calcN_forced!(N, sol, t, s, v, p, g)
+  calcN_advection!(N, sol, t, s, v, p, g)
+  if t == s.t # not a substep
+    v.prevsol .= s.sol # used to compute budgets when forcing is stochastic
+    p.calcF!(v.Fh, sol, t, s, v, p, g)
+  end
+  @. N += v.Fh
+  nothing
+end
+```
+- `updatevars!`: uses `sol` to compute $q$, $u$, $v$, $\widehat{u}$, and $\widehat{v}$ and stores them into corresponding arrays of `Vars`/`ForcedVars`.
+
+- `updatevars!`: uses `sol` to compute $q$, $u$, $v$, $\widehat{u}$, and $\widehat{v}$ and stores them into corresponding arrays of `Vars`/`ForcedVars`.
 
 
 ## Examples
 
 - `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.
 
-- `examples/twodturb/IsotropicRingForcing.jl`: A script that simulates stochastically forced two-dimensional turbulence. The forcing is temporally delta-corraleted and its spatial structure is isotropic with power in a narrow annulus of total radius `kf` in wavenumber space.
+- `examples/twodturb/IsotropicRingForcing.jl`: A script that simulates stochastically forced two-dimensional turbulence. The forcing is temporally delta-corraleted and its spatial structure is isotropic with power in a narrow annulus of total radius $k_f$ in wavenumber space.