From 9dde3d52853e89b5f99a62dc804844792c96a8ed Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 10:40:22 -0600 Subject: [PATCH 1/7] use DocumenterCitations for refs --- docs/Project.toml | 3 ++ docs/make.jl | 17 +++++--- docs/src/modules/barotropicqgql.md | 6 +-- docs/src/modules/surfaceqg.md | 4 +- docs/src/modules/twodnavierstokes.md | 2 - docs/src/references.bib | 61 +++++++++++++++++++++++++++ docs/src/references.md | 4 ++ examples/surfaceqg_decaying.jl | 2 +- examples/twodnavierstokes_decaying.jl | 5 ++- 9 files changed, 86 insertions(+), 18 deletions(-) create mode 100644 docs/src/references.bib create mode 100644 docs/src/references.md diff --git a/docs/Project.toml b/docs/Project.toml index 0ce61883..1c92af57 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -2,6 +2,8 @@ CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba" CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" +GeophysicalFlows = "44ee3b1c-bc02-53fa-8355-8e347616e15e" JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" @@ -10,4 +12,5 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" CUDA = "1, 2.4.2, 3.0.0 - 3.6.4, 3.7.1, 4" CairoMakie = "< 0.10.5" Documenter = "1" +DocumenterCitations = "1.2" Literate = "≥2.9.0" diff --git a/docs/make.jl b/docs/make.jl index 41428bc8..6f3a8445 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,4 +1,4 @@ -using Documenter, Literate +using Documenter, DocumenterCitations, Literate using CairoMakie # CairoMakie.activate!(type = "svg") @@ -31,7 +31,7 @@ for example in examples example_filepath = joinpath(EXAMPLES_DIR, example) withenv("JULIA_DEBUG" => "Literate") do Literate.markdown(example_filepath, OUTPUT_DIR; - flavor = Literate.DocumenterFlavor(), execute = true) + flavor = Literate.DocumenterFlavor(), execute = false) end end end @@ -47,14 +47,20 @@ format = Documenter.HTML( canonical = "https://fourierflows.github.io/GeophysicalFlowsDocumentation/stable/" ) +bib_filepath = joinpath(dirname(@__FILE__), "src/references.bib") +bib = CitationBibliography(bib_filepath, style=:authoryear) + makedocs( + authors = "Navid C. Constantinou, Gregory L. Wagner, and contributors", + sitename = "GeophysicalFlows.jl", modules = [GeophysicalFlows], + plugins = [bib], + format = format, + draft = true, doctest = true, clean = true, checkdocs = :all, - format = format, - authors = "Navid C. Constantinou, Gregory L. Wagner, and contributors", - sitename = "GeophysicalFlows.jl", + warnonly = [:footnote, :cross_references], pages = Any[ "Home" => "index.md", "Installation instructions" => "installation_instructions.md", @@ -92,6 +98,7 @@ checkdocs = :all, ], "Stochastic forcing" => "stochastic_forcing.md", "Contributor's guide" => "contributing.md", + "References" => "references.md", "Library" => Any[ "lib/types.md", "lib/functions.md" diff --git a/docs/src/modules/barotropicqgql.md b/docs/src/modules/barotropicqgql.md index 084afc14..f945a8d8 100644 --- a/docs/src/modules/barotropicqgql.md +++ b/docs/src/modules/barotropicqgql.md @@ -11,11 +11,7 @@ e.g., \phi(x, y, t) = \overline{\phi}(y, t) + \phi'(x, y, t) , ``` -where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., - -- Farrell, B. F. and Ioannou, P. J. (2003). [Structural stability of turbulent jets.](http://doi.org/10.1175/1520-0469(2003)060<2101:SSOTJ>2.0.CO;2) *J. Atmos. Sci.*, **60**, 2101-2118. -- Srinivasan, K. and Young, W. R. (2012). [Zonostrophic instability.](http://doi.org/10.1175/JAS-D-11-0200.1) *J. Atmos. Sci.*, **69 (5)**, 1633-1656. -- Constantinou, N. C., Farrell, B. F., and Ioannou, P. J. (2014). [Emergence and equilibration of jets in beta-plane turbulence: applications of Stochastic Structural Stability Theory.](http://doi.org/10.1175/JAS-D-13-076.1) *J. Atmos. Sci.*, **71 (5)**, 1818-1842. +where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., [Farrell-Ioannou-2003](@citet), [Srinivasan-Young-2012](@citet), [Constantinou-etal-2014](@citet). As in the [SingleLayerQG module](singlelayerqg.md), the flow is obtained through a streamfunction ``\psi`` as ``(u, v) = (-\partial_y \psi, \partial_x \psi)``. All flow fields diff --git a/docs/src/modules/surfaceqg.md b/docs/src/modules/surfaceqg.md index 0bdfeaad..e454529b 100644 --- a/docs/src/modules/surfaceqg.md +++ b/docs/src/modules/surfaceqg.md @@ -3,7 +3,7 @@ ### Basic Equations This module solves the non-dimensional surface quasi-geostrophic (SQG) equation for surface -buoyancy ``b_s = b(x, y, z=0)``, as described in Capet et al., 2008. The buoyancy and the fluid +buoyancy ``b_s = b(x, y, z=0)``, as described by [Capet-etal-2008](@citet). The buoyancy and the fluid velocity at the surface are related through a streamfunction ``\psi`` via: ```math @@ -101,5 +101,3 @@ Other diagnostic include: [`buoyancy_dissipation`](@ref GeophysicalFlows.Surface - [`examples/surfaceqg_decaying.jl`](@ref surfaceqg_decaying_example): Simulate decaying surface quasi-geostrophic flow with a prescribed initial buoyancy field. - - > Capet, X. et al., (2008). Surface kinetic energy transfer in surface quasi-geostrophic flows. *J. Fluid Mech.*, **604**, 165-174. diff --git a/docs/src/modules/twodnavierstokes.md b/docs/src/modules/twodnavierstokes.md index bce3b31c..e541a48d 100644 --- a/docs/src/modules/twodnavierstokes.md +++ b/docs/src/modules/twodnavierstokes.md @@ -94,8 +94,6 @@ Other diagnostic include: [`energy_dissipation`](@ref GeophysicalFlows.TwoDNavie - [`examples/twodnavierstokes_decaying.jl`](@ref twodnavierstokes_decaying_example): 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`](@ref twodnavierstokes_stochasticforcing_example): Simulate forced-dissipative two-dimensional turbulence with isotropic temporally delta-correlated stochastic forcing. diff --git a/docs/src/references.bib b/docs/src/references.bib new file mode 100644 index 00000000..151a7cdc --- /dev/null +++ b/docs/src/references.bib @@ -0,0 +1,61 @@ +@article{Held-etal-1995, + title={Surface quasi-geostrophic dynamics}, + author={Held, Isaac M. and Pierrehumbert, Raymond T. and Garner, Stephen T. and Swanson, Kyle L.}, + journal={Journal of Fluid Mechanics}, + volume={282}, + pages={1--20}, + year={1995}, + doi={10.1017/S0022112095000012} +} + +@article{Capet-etal-2008, + title={Surface kinetic energy transfer in surface quasi-geostrophic flows}, + author={Capet, Xavier and Klein, Patrice and Hua, Bach Lien and Lapeyre, Guillaume and Mcwilliams, James C.}, + journal={Journal of Fluid Mechanics}, + volume={604}, + pages={165--174}, + year={2008}, + doi={10.1017/S0022112008001110} +} + +@article{McWilliams-1984, + title={The emergence of isolated coherent vortices in turbulent flow}, + author={Mcwilliams, James C.}, + journal={Journal of Fluid Mechanics}, + volume={146}, + pages={21--43}, + year={1984}, + doi={10.1017/S0022112084001750} +} + +@article{Farrell-Ioannou-2003, + title = {Structural stability of turbulent jets}, + author = {Farrell, Brian F. and Ioannou, Petros J.}, + journal = {Journal of the Atmospheric Sciences}, + pages = {2101--2118}, + volume = 60, + year = 2003, + doi = {10.1175/1520-0469(2003)060<2101:SSOTJ>2.0.CO;2}, +} + +@article{Constantinou-etal-2014, + title = {Emergence and equilibration of jets in beta-plane turbulence: applications of Stochastic Structural Stability Theory}, + author = {Constantinou, Navid C. and Farrell, Brian F. and Ioannou, Petros J.}, + journal = {Journal of the Atmospheric Sciences}, + volume = {71}, + number = {5}, + pages = {1818--1842}, + year = {2014}, + doi = {10.1175/JAS-D-13-076.1}, +} + +@article{Srinivasan-Young-2012, + title = {Zonostrophic instability}, + author = {Srinivasan, Kaushik and Young, William R.}, + journal = {Journal of the Atmospheric Sciences}, + volume = {69}, + number = {5}, + pages = {1633--1656}, + year = {2012}, + doi = {10.1175/JAS-D-11-0200.1}, +} diff --git a/docs/src/references.md b/docs/src/references.md new file mode 100644 index 00000000..78f29bc4 --- /dev/null +++ b/docs/src/references.md @@ -0,0 +1,4 @@ +# References + +```@bibliography +``` diff --git a/examples/surfaceqg_decaying.jl b/examples/surfaceqg_decaying.jl index 4059cc79..5eb5a660 100644 --- a/examples/surfaceqg_decaying.jl +++ b/examples/surfaceqg_decaying.jl @@ -2,7 +2,7 @@ # # A simulation of decaying surface quasi-geostrophic turbulence. # We reproduce here the initial value problem for an elliptical -# vortex as done by Held et al. 1995, _J. Fluid Mech_. +# vortex as done by [Held-etal-1995](@citet). # # An example of decaying barotropic quasi-geostrophic turbulence over topography. # diff --git a/examples/twodnavierstokes_decaying.jl b/examples/twodnavierstokes_decaying.jl index 0163ae46..fbd09160 100644 --- a/examples/twodnavierstokes_decaying.jl +++ b/examples/twodnavierstokes_decaying.jl @@ -1,6 +1,7 @@ # # [2D decaying turbulence](@id twodnavierstokes_decaying_example) # -# A simulation of decaying two-dimensional turbulence. +# A simulation of decaying two-dimensional turbulence closely following +# the paper by [McWilliams-1984](@citet). # # ## Install dependencies # @@ -58,7 +59,7 @@ nothing #hide # ## Setting initial conditions -# Our initial condition tries to reproduce the initial condition used by McWilliams (_JFM_, 1984). +# Our initial condition tries to reproduce the initial condition used by [McWilliams-1984](@citet). seed!(1234) k₀, E₀ = 6, 0.5 ζ₀ = peakedisotropicspectrum(grid, k₀, E₀, mask=prob.timestepper.filter) From a95ca030ce90f1588ed318042561167dd72d1e49 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 10:48:55 -0600 Subject: [PATCH 2/7] drop the draft flag --- docs/Project.toml | 1 - docs/make.jl | 4 +--- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/Project.toml b/docs/Project.toml index 1c92af57..192881bd 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -3,7 +3,6 @@ CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba" CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" -GeophysicalFlows = "44ee3b1c-bc02-53fa-8355-8e347616e15e" JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" diff --git a/docs/make.jl b/docs/make.jl index 6f3a8445..7a8c7aab 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -31,7 +31,7 @@ for example in examples example_filepath = joinpath(EXAMPLES_DIR, example) withenv("JULIA_DEBUG" => "Literate") do Literate.markdown(example_filepath, OUTPUT_DIR; - flavor = Literate.DocumenterFlavor(), execute = false) + flavor = Literate.DocumenterFlavor(), execute = true) end end end @@ -56,11 +56,9 @@ makedocs( modules = [GeophysicalFlows], plugins = [bib], format = format, - draft = true, doctest = true, clean = true, checkdocs = :all, - warnonly = [:footnote, :cross_references], pages = Any[ "Home" => "index.md", "Installation instructions" => "installation_instructions.md", From 8b2471adda2b2e2652facca5aa25a97fc8c35add Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 10:48:55 -0600 Subject: [PATCH 3/7] add some more refs --- docs/src/references.bib | 10 ++++++++++ docs/src/stochastic_forcing.md | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/src/references.bib b/docs/src/references.bib index 151a7cdc..8d95885a 100644 --- a/docs/src/references.bib +++ b/docs/src/references.bib @@ -59,3 +59,13 @@ @article{Srinivasan-Young-2012 year = {2012}, doi = {10.1175/JAS-D-11-0200.1}, } + +@article{vanKampen-Nicolaas-1981, + title={Itô versus Stratonovich}, + author={Van Kampen, Nicolaas G}, + journal={Journal of Statistical Physics}, + volume={24}, + pages={175--187}, + year={1981}, + doi={10.1007/BF01007642} +} \ No newline at end of file diff --git a/docs/src/stochastic_forcing.md b/docs/src/stochastic_forcing.md index 3727a5a2..505f60e8 100644 --- a/docs/src/stochastic_forcing.md +++ b/docs/src/stochastic_forcing.md @@ -141,7 +141,7 @@ the other hand, the chain rule in Stratonovich calculus coincides with that in n This stems from the fact that in the Stratonovich interpretation the white noise process is as a series of colored noise processes with the de-correlation time tending to zero. This made Stratonovich calculus more popular in the physics community. A nice discussion on the differences -and similarities between the two calculi is given by [van Kampen](https://doi.org/10.1007/BF01007642). +and similarities between the two calculi is given by [vanKampen-Nicolaas-1981](@citet). ## A simple Stochastic Differential Equation: the Ornstein--Uhlenbeck process From 831b7e58d5ae27296d41ef874188b12145326c70 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 11:03:50 -0600 Subject: [PATCH 4/7] add a ref --- docs/src/references.bib | 12 +++++++++++- docs/src/stochastic_forcing.md | 4 ++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/src/references.bib b/docs/src/references.bib index 8d95885a..cb619b88 100644 --- a/docs/src/references.bib +++ b/docs/src/references.bib @@ -68,4 +68,14 @@ @article{vanKampen-Nicolaas-1981 pages={175--187}, year={1981}, doi={10.1007/BF01007642} -} \ No newline at end of file +} + +@phdthesis{Constantinou-2015-phd, + title = {Formation of large-scale structures by turbulence in rotating planets}, + author = {Constantinou, N. C.}, + school = {National and Kapodistrian University of Athens}, + address = {Athens}, + url = {http://www.didaktorika.gr/eadd/handle/10442/35501?locale=en}, + year = {2015}, + note = {(also available at arXiv:1503.07644)} +} diff --git a/docs/src/stochastic_forcing.md b/docs/src/stochastic_forcing.md index 505f60e8..d34718b2 100644 --- a/docs/src/stochastic_forcing.md +++ b/docs/src/stochastic_forcing.md @@ -158,7 +158,7 @@ Note that in differential form (1) is written as: ``` Luckily, for (2) we don't need to distinguish between Itô and Stratonovich, since ``g`` is -independent of ``x(t)``. But note that oftentimes this is not the case; that ``g`` is independent +independent of ``x(t)``. But note that often this is not the case; that ``g`` is independent of ``x(t)`` is only a fortuitous coincident for this particular SDE. How do we time-step SDE (2) numerically? Let us assume a discretization of time into time-steps @@ -456,7 +456,7 @@ The forcing ``\xi`` obeys: that is, the forcing is white in time but spatially correlated; its spatial correlation is prescribed by the function ``Q`` which is, necessarily, homogeneous in all its arguments -(see discussion by [Constantinou (2015)](http://arxiv.org/abs/1503.07644); Appendix A). +(see discussion by [Constantinou-2015-phd](@citet); Appendix A). Equation (6) above describes the vorticity evolution of a two-dimensional fluid ``\nabla^2 \psi`` that is stochastically forced while dissipated by linear drag ``\mu``. The energy of the From 50a668d4f7a5e4ab30e5ca4f7422c2038686b143 Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 11:23:39 -0600 Subject: [PATCH 5/7] vanKampen-Nicolaas-1981 -> vanKampen-1981 --- docs/src/stochastic_forcing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/stochastic_forcing.md b/docs/src/stochastic_forcing.md index d34718b2..ce36d903 100644 --- a/docs/src/stochastic_forcing.md +++ b/docs/src/stochastic_forcing.md @@ -141,7 +141,7 @@ the other hand, the chain rule in Stratonovich calculus coincides with that in n This stems from the fact that in the Stratonovich interpretation the white noise process is as a series of colored noise processes with the de-correlation time tending to zero. This made Stratonovich calculus more popular in the physics community. A nice discussion on the differences -and similarities between the two calculi is given by [vanKampen-Nicolaas-1981](@citet). +and similarities between the two calculi is given by [vanKampen-1981](@citet). ## A simple Stochastic Differential Equation: the Ornstein--Uhlenbeck process From 0bb63305779ab3ce8180bf0ef74af116ce233deb Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 11:24:21 -0600 Subject: [PATCH 6/7] add and --- docs/src/modules/barotropicqgql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/modules/barotropicqgql.md b/docs/src/modules/barotropicqgql.md index f945a8d8..67b71c7e 100644 --- a/docs/src/modules/barotropicqgql.md +++ b/docs/src/modules/barotropicqgql.md @@ -11,7 +11,7 @@ e.g., \phi(x, y, t) = \overline{\phi}(y, t) + \phi'(x, y, t) , ``` -where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., [Farrell-Ioannou-2003](@citet), [Srinivasan-Young-2012](@citet), [Constantinou-etal-2014](@citet). +where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., [Farrell-Ioannou-2003](@citet), [Srinivasan-Young-2012](@citet), and [Constantinou-etal-2014](@citet). As in the [SingleLayerQG module](singlelayerqg.md), the flow is obtained through a streamfunction ``\psi`` as ``(u, v) = (-\partial_y \psi, \partial_x \psi)``. All flow fields From 67f109df22ea0e83336c11820466dc511ef9ee6b Mon Sep 17 00:00:00 2001 From: "Navid C. Constantinou" Date: Fri, 27 Oct 2023 13:04:52 -0600 Subject: [PATCH 7/7] vanKampen-Nicolaas-1981 -> vanKampen-1981 --- docs/src/references.bib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/references.bib b/docs/src/references.bib index cb619b88..a172b7e9 100644 --- a/docs/src/references.bib +++ b/docs/src/references.bib @@ -60,7 +60,7 @@ @article{Srinivasan-Young-2012 doi = {10.1175/JAS-D-11-0200.1}, } -@article{vanKampen-Nicolaas-1981, +@article{vanKampen-1981, title={Itô versus Stratonovich}, author={Van Kampen, Nicolaas G}, journal={Journal of Statistical Physics},