Docstring brush-up

docs/make.jl

@@ -17,16 +17,16 @@ const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
 
 examples = [
-    "twodnavierstokes_decaying.jl",
-    "twodnavierstokes_stochasticforcing.jl",
-    "twodnavierstokes_stochasticforcing_budgets.jl",
-    "singlelayerqg_betadecay.jl",
-    "singlelayerqg_betaforced.jl",
-    "singlelayerqg_decaying_topography.jl",
-    "singlelayerqg_decaying_barotropic_equivalentbarotropic.jl",
-    "barotropicqgql_betaforced.jl",
-    "multilayerqg_2layer.jl",
-    "surfaceqg_decaying.jl",
+  "twodnavierstokes_decaying.jl",
+  "twodnavierstokes_stochasticforcing.jl",
+  "twodnavierstokes_stochasticforcing_budgets.jl",
+  "singlelayerqg_betadecay.jl",
+  "singlelayerqg_betaforced.jl",
+  "singlelayerqg_decaying_topography.jl",
+  "singlelayerqg_decaying_barotropic_equivalentbarotropic.jl",
+  "barotropicqgql_betaforced.jl",
+  "multilayerqg_2layer.jl",
+  "surfaceqg_decaying.jl",
 ]
 
 for example in examples
@@ -97,8 +97,8 @@ sitename = "GeophysicalFlows.jl",
             "Stochastic Forcing" => "stochastic_forcing.md",
             "Contributor's guide" => "contributing.md",
             "Library" => Any[
-            "lib/types.md",
-            "lib/functions.md"
+              "lib/types.md",
+              "lib/functions.md"
             ]
            ]
 )

docs/src/modules/barotropicqgql.md

@@ -115,4 +115,4 @@ Other diagnostic include: [`dissipation`](@ref GeophysicalFlows.BarotropicQGQL.d
 
 ## Examples
 
-- [`examples/barotropicqgql_betaforced.jl`](../literated/barotropicqgql_betaforced/): A script that simulates forced-dissipative quasi-linear quasi-geostrophic flow on a beta plane demonstrating zonation. The forcing is temporally delta-correlated and its spatial structure is isotropic with power in a narrow annulus of total radius ``k_f`` in wavenumber space. This example demonstrates that the anisotropic inverse energy cascade is not required for zonation.
+- [`examples/barotropicqgql_betaforced.jl`](../../literated/barotropicqgql_betaforced/): A script that simulates forced-dissipative quasi-linear quasi-geostrophic flow on a beta plane demonstrating zonation. The forcing is temporally delta-correlated and its spatial structure is isotropic with power in a narrow annulus of total radius ``k_f`` in wavenumber space. This example demonstrates that the anisotropic inverse energy cascade is not required for zonation.

docs/src/modules/multilayerqg.md

@@ -146,4 +146,4 @@ GeophysicalFlows.MultiLayerQG.fluxes
 
 ## Examples
 
- - [`examples/multilayerqg_2layer.jl`](../literated/multilayerqg_2layer/): A script that simulates the growth and equilibration of baroclinic eddy turbulence in the Phillips 2-layer model.
+ - [`examples/multilayerqg_2layer.jl`](../../literated/multilayerqg_2layer/): A script that simulates the growth and equilibration of baroclinic eddy turbulence in the Phillips 2-layer model.

docs/src/modules/singlelayerqg.md

@@ -110,10 +110,10 @@ Other diagnostic include: [`energy_dissipation`](@ref GeophysicalFlows.SingleLay
 
 ## Examples
 
-- [`examples/singlelayerqg_betadecay.jl`](../literated/singlelayerqg_betadecay/): A script that simulates decaying quasi-geostrophic flow on a beta plane demonstrating zonation.
+- [`examples/singlelayerqg_betadecay.jl`](../../literated/singlelayerqg_betadecay/): A script that simulates decaying quasi-geostrophic flow on a beta plane demonstrating zonation.
 
-- [`examples/singlelayerqg_betaforced.jl`](../literated/singlelayerqg_betaforced/): A script that simulates forced-dissipative quasi-geostrophic flow on a beta plane demonstrating zonation. The forcing is temporally delta-correlated with isotropic spatial structure with power in a narrow annulus in wavenumber space with total wavenumber ``k_f``.
+- [`examples/singlelayerqg_betaforced.jl`](../../literated/singlelayerqg_betaforced/): A script that simulates forced-dissipative quasi-geostrophic flow on a beta plane demonstrating zonation. The forcing is temporally delta-correlated with isotropic spatial structure with power in a narrow annulus in wavenumber space with total wavenumber ``k_f``.
 
-- [`examples/singlelayerqg_decay_topography.jl`](../literated/singlelayerqg_decay_topography/): A script that simulates two dimensional turbulence (barotropic quasi-geostrophic flow with ``\beta=0``) above topography.
+- [`examples/singlelayerqg_decay_topography.jl`](../../literated/singlelayerqg_decay_topography/): A script that simulates two dimensional turbulence (barotropic quasi-geostrophic flow with ``\beta=0``) above topography.
 
-- [`examples/singlelayerqg_decaying_barotropic_equivalentbarotropic.jl`](../literated singlelayerqg_decaying_barotropic_equivalentbarotropic/): A script that simulates two dimensional turbulence (``\beta=0``) with both infinite and finite Rossby radius of deformation and compares the evolution of the two.
+- [`examples/singlelayerqg_decaying_barotropic_equivalentbarotropic.jl`](../../literated singlelayerqg_decaying_barotropic_equivalentbarotropic/): A script that simulates two dimensional turbulence (``\beta=0``) with both infinite and finite Rossby radius of deformation and compares the evolution of the two.

docs/src/modules/surfaceqg.md

@@ -96,6 +96,6 @@ Other diagnostic include: [`buoyancy_dissipation`](@ref GeophysicalFlows.Surface
 
 ## Examples
 
-- [`examples/surfaceqg_decaying.jl`](../literated/surfaceqg_decaying/): A script that simulates decaying surface quasi-geostrophic flow with a prescribed initial buoyancy field, producing an animation of the evolution of the surface buoyancy.
+- [`examples/surfaceqg_decaying.jl`](../../literated/surfaceqg_decaying/): A script that simulates decaying surface quasi-geostrophic flow with a prescribed initial buoyancy field, producing an animation of the evolution of the surface buoyancy.
 
   > Capet, X. et al., (2008). Surface kinetic energy transfer in surface quasi-geostrophic flows. *J. Fluid Mech.*, **604**, 165-174.

docs/src/modules/twodnavierstokes.md

@@ -90,10 +90,10 @@ Other diagnostic include: [`energy_dissipation`](@ref GeophysicalFlows.TwoDNavie
 
 ## Examples
 
-- [`examples/twodnavierstokes_decaying.jl`](../literated/twodnavierstokes_decaying/): A script that simulates decaying two-dimensional turbulence reproducing the results by
+- [`examples/twodnavierstokes_decaying.jl`](../../literated/twodnavierstokes_decaying/): A script that simulates decaying two-dimensional turbulence reproducing the results by
 
   > McWilliams, J. C. (1984). The emergence of isolated coherent vortices in turbulent flow. *J. Fluid Mech.*, **146**, 21-43.
 
-- [`examples/twodnavierstokes_stochasticforcing.jl`](../literated/twodnavierstokes_stochasticforcing/): A script that simulates forced-dissipative two-dimensional turbulence with isotropic temporally delta-correlated stochastic forcing.
+- [`examples/twodnavierstokes_stochasticforcing.jl`](../../literated/twodnavierstokes_stochasticforcing/): A script that simulates forced-dissipative two-dimensional turbulence with isotropic temporally delta-correlated stochastic forcing.
 
-- [`examples/twodnavierstokes_stochasticforcing_budgets.jl`](../literated/twodnavierstokes_stochasticforcing_budgets/): A script that simulates forced-dissipative two-dimensional turbulence demonstrating how we can compute the energy and enstrophy budgets.
+- [`examples/twodnavierstokes_stochasticforcing_budgets.jl`](../../literated/twodnavierstokes_stochasticforcing_budgets/): A script that simulates forced-dissipative two-dimensional turbulence demonstrating how we can compute the energy and enstrophy budgets.

examples/twodnavierstokes_stochasticforcing.jl

@@ -1,6 +1,6 @@
 # # 2D forced-dissipative turbulence
 #
-#md # This example can be viewed as a Jupyter notebook via [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/twodnavierstokes_stochasticforcing.ipynb).
+#md # This example can be viewed as a Jupyter notebook via [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/literated/twodnavierstokes_stochasticforcing.ipynb).
 #
 # A simulation of forced-dissipative two-dimensional turbulence. We solve the
 # two-dimensional vorticity equation with stochastic excitation and dissipation in

src/barotropicqgql.jl

@@ -50,22 +50,22 @@ Construct a quasi-linear barotropic quasi-geostrophic `problem` on device `dev`.
 
 Keyword arguments
 =================
-    - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
-    - `nx`: Number of grid points in ``x``-domain.
-    - `ny`: Number of grid points in ``y``-domain.
-    - `Lx`: Extent of the ``x``-domain.
-    - `Ly`: Extent of the ``y``-domain.
-    - `β`: Planetary vorticity ``y``-gradient.
-    - `eta`: Topographic potential vorticity.
-    - `ν`: Small-scale (hyper)-viscosity coefficient.
-    - `nν`: (Hyper)-viscosity order, `nν```≥ 1``".
-    - `μ`: Linear drag coefficient.
-    - `dt`: Time-step.
-    - `stepper`: The extent of the ``y``-domain.
-    - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
-    - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
-    - `aliased_fraction`: the fraction of high-wavenubers that are zero-ed out by `dealias!()`.
-    - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
+  - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
+  - `nx`: Number of grid points in ``x``-domain.
+  - `ny`: Number of grid points in ``y``-domain.
+  - `Lx`: Extent of the ``x``-domain.
+  - `Ly`: Extent of the ``y``-domain.
+  - `β`: Planetary vorticity ``y``-gradient.
+  - `eta`: Topographic potential vorticity.
+  - `ν`: Small-scale (hyper)-viscosity coefficient.
+  - `nν`: (Hyper)-viscosity order, `nν```≥ 1``.
+  - `μ`: Linear drag coefficient.
+  - `dt`: Time-step.
+  - `stepper`: Time-stepping method.
+  - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
+  - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
+  - `aliased_fraction`: the fraction of high-wavenumbers that are zero-ed out by `dealias!()`.
+  - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
 """
 function Problem(dev::Device=CPU();
   # Numerical parameters
@@ -120,7 +120,7 @@ A struct containing the parameters for a barotropic QL QG problem. Included are:
 $(TYPEDFIELDS)
 """
 struct Params{T, Aphys, Atrans} <: AbstractParams
-    "planetary vorticity y-gradient"
+    "planetary vorticity ``y``-gradient"
        β :: T
     "topographic potential vorticity"
      eta :: Aphys

src/multilayerqg.jl

@@ -55,28 +55,28 @@ Construct a multi-layer quasi-geostrophic `problem` with `nlayers` fluid layers
 
 Keyword arguments
 =================
-    - `nlayers`: (required) Number of fluid layers.
-    - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
-    - `nx`: Number of grid points in ``x``-domain.
-    - `ny`: Number of grid points in ``y``-domain.
-    - `Lx`: Extent of the ``x``-domain.
-    - `Ly`: Extent of the ``y``-domain.
-    - `f₀`: Constant planetary vorticity.
-    - `β`: Planetary vorticity ``y``-gradient.
-    - `g`: Gravitational accelaration constant.
-    - `U`: T imposed constant zonal flow U(y) in each fluid layer.
-    - `H`: Rest height of each fluid layer.
-    - `ρ`: Densities of each fluid layer.
-    - `eta`: Topographic potential vorticity.
-    - `μ`: Linear bottom drag coefficient.
-    - `ν`: Small-scale (hyper)-viscosity coefficient.
-    - `nν`: (Hyper)-viscosity order, `nν```≥ 1``".
-    - `dt`: Time-step.
-    - `stepper`: The extent of the ``y``-domain.
-    - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
-    - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
-    - `aliased_fraction`: the fraction of high-wavenubers that are zero-ed out by `dealias!()`.
-    - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
+  - `nlayers`: (required) Number of fluid layers.
+  - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
+  - `nx`: Number of grid points in ``x``-domain.
+  - `ny`: Number of grid points in ``y``-domain.
+  - `Lx`: Extent of the ``x``-domain.
+  - `Ly`: Extent of the ``y``-domain.
+  - `f₀`: Constant planetary vorticity.
+  - `β`: Planetary vorticity ``y``-gradient.
+  - `g`: Gravitational acceleration constant.
+  - `U`: The imposed constant zonal flow ``U(y)`` in each fluid layer.
+  - `H`: Rest height of each fluid layer.
+  - `ρ`: Density of each fluid layer.
+  - `eta`: Topographic potential vorticity.
+  - `μ`: Linear bottom drag coefficient.
+  - `ν`: Small-scale (hyper)-viscosity coefficient.
+  - `nν`: (Hyper)-viscosity order, `nν```≥ 1``.
+  - `dt`: Time-step.
+  - `stepper`: Time-stepping method.
+  - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
+  - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
+  - `aliased_fraction`: the fraction of high-wavenumbers that are zero-ed out by `dealias!()`.
+  - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
 """
 function Problem(nlayers::Int,                        # number of fluid layers
                      dev = CPU();
@@ -147,16 +147,16 @@ struct Params{T, Aphys3D, Aphys2D, Aphys1D, Atrans4D, Trfft} <: AbstractParams
          g :: T
     "constant planetary vorticity"
         f₀ :: T
-    "planetary vorticity y-gradient"
-         β :: T
+    "planetary vorticity ``y``-gradient"
+         β :: T       
     "array with density of each fluid layer"
          ρ :: Aphys3D
     "array with rest height of each fluid layer"
-         H :: Aphys3D
-    "array with imposed constant zonal flow U(y) in each fluid layer"
-         U :: Aphys3D
-    "array containing topographic PV"
-       eta :: Aphys2D
+         H :: Aphys3D 
+    "array with imposed constant zonal flow ``U(y)`` in each fluid layer"
+         U :: Aphys3D 
+    "array containing the topographic PV"
+       eta :: Aphys2D 
     "linear bottom drag coefficient"
          μ :: T
     "small-scale (hyper)-viscosity coefficient"
@@ -169,9 +169,9 @@ struct Params{T, Aphys3D, Aphys2D, Aphys1D, Atrans4D, Trfft} <: AbstractParams
   # derived params
     "array with the reduced gravity constants for each fluid interface"
         g′ :: Aphys1D
-    "array containing x-gradient of PV due to eta in each fluid layer"
+    "array containing ``x``-gradient of PV due to eta in each fluid layer"
         Qx :: Aphys3D
-    "array containing y-gradient of PV due to β, U, and eta in each fluid layer"
+    "array containing ``y``-gradient of PV due to ``β``, ``U``, and topographic PV in each fluid layer"
         Qy :: Aphys3D
     "array containing coeffients for getting PV from streamfunction"
          S :: Atrans4D

src/singlelayerqg.jl

@@ -51,23 +51,23 @@ Construct a single-layer quasi-geostrophic `problem` on device `dev`.
 
 Keyword arguments
 =================
-    - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
-    - `nx`: Number of grid points in ``x``-domain.
-    - `ny`: Number of grid points in ``y``-domain.
-    - `Lx`: Extent of the ``x``-domain.
-    - `Ly`: Extent of the ``y``-domain.
-    - `β`: Planetary vorticity ``y``-gradient.
-    - `deformation_radius`: Rossby radius of deformation; set `Inf` for purely barotropic.
-    - `eta`: Topographic potential vorticity.
-    - `ν`: Small-scale (hyper)-viscosity coefficient.
-    - `nν`: (Hyper)-viscosity order, `nν```≥ 1``".
-    - `μ`: Linear drag coefficient.
-    - `dt`: Time-step.
-    - `stepper`: The extent of the ``y``-domain.
-    - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
-    - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
-    - `aliased_fraction`: the fraction of high-wavenubers that are zero-ed out by `dealias!()`.
-    - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
+  - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
+  - `nx`: Number of grid points in ``x``-domain.
+  - `ny`: Number of grid points in ``y``-domain.
+  - `Lx`: Extent of the ``x``-domain.
+  - `Ly`: Extent of the ``y``-domain.
+  - `β`: Planetary vorticity ``y``-gradient.
+  - `deformation_radius`: Rossby radius of deformation; set `Inf` for purely barotropic.
+  - `eta`: Topographic potential vorticity.
+  - `ν`: Small-scale (hyper)-viscosity coefficient.
+  - `nν`: (Hyper)-viscosity order, `nν```≥ 1``.
+  - `μ`: Linear drag coefficient.
+  - `dt`: Time-step.
+  - `stepper`: Time-stepping method.
+  - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
+  - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
+  - `aliased_fraction`: the fraction of high-wavenumbers that are zero-ed out by `dealias!()`.
+  - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
 """
 function Problem(dev::Device=CPU();
   # Numerical parameters
@@ -123,7 +123,7 @@ A struct containing the parameters for the SingleLayerQG problem. Included are:
 $(TYPEDFIELDS)
 """
 struct Params{T, Aphys, Atrans, ℓ} <: SingleLayerQGParams
-    "planetary vorticity y-gradient"
+    "planetary vorticity ``y``-gradient"
                    β :: T
     "Rossby radius of deformation"
   deformation_radius :: ℓ

src/surfaceqg.jl

@@ -43,19 +43,19 @@ Construct a surface quasi-geostrophic `problem` on device `dev`.
 
 Keyword arguments
 =================
-    - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
-    - `nx`: Number of grid points in ``x``-domain.
-    - `ny`: Number of grid points in ``y``-domain.
-    - `Lx`: Extent of the ``x``-domain.
-    - `Ly`: Extent of the ``y``-domain.
-    - `ν`: Small-scale (hyper)-viscosity coefficient.
-    - `nν`: (Hyper)-viscosity order, `nν```≥ 1``".
-    - `dt`: Time-step.
-    - `stepper`: The extent of the ``y``-domain.
-    - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
-    - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
-    - `aliased_fraction`: the fraction of high-wavenubers that are zero-ed out by `dealias!()`.
-    - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
+  - `dev`: (required) `CPU()` or `GPU()`; computer architecture used to time-step `problem`.
+  - `nx`: Number of grid points in ``x``-domain.
+  - `ny`: Number of grid points in ``y``-domain.
+  - `Lx`: Extent of the ``x``-domain.
+  - `Ly`: Extent of the ``y``-domain.
+  - `ν`: Small-scale (hyper)-viscosity coefficient.
+  - `nν`: (Hyper)-viscosity order, `nν```≥ 1``.
+  - `dt`: Time-step.
+  - `stepper`: Time-stepping method.
+  - `calcF`: Function that calculates the Fourier transform of the forcing, ``F̂``.
+  - `stochastic`: `true` or `false`; boolean denoting whether `calcF` is temporally stochastic.
+  - `aliased_fraction`: the fraction of high-wavenumbers that are zero-ed out by `dealias!()`.
+  - `T`: `Float32` or `Float64`; floating point type used for `problem` data.
 """
 function Problem(dev::Device=CPU();
   # Numerical parameters