Skip to content

Commit

Permalink
Use latest Documenter + DocumenterCitations (#3186)
Browse files Browse the repository at this point in the history 
* use latest Documenter + DocumenterCitations

* better citations; can use citet, citep now

* add css styling for citations

* add compat for DocumenterCitations
  • Loading branch information
@navidcy
navidcy authored Jul 28, 2023
1 parent 2447ea7 commit f7acd8d
Show file tree
Hide file tree
Showing 21 changed files with 106 additions and 86 deletions.
46 changes: 23 additions & 23 deletions docs/Manifest.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ version = "0.0.1"

[[deps.AbstractFFTs]]
deps = ["LinearAlgebra"]
git-tree-sha1 = "8bc0aaec0ca548eb6cf5f0d7d16351650c1ee956"
git-tree-sha1 = "cad4c758c0038eea30394b1b671526921ca85b21"
uuid = "621f4979-c628-5d54-868e-fcf4e3e8185c"
version = "1.3.2"
version = "1.4.0"
weakdeps = ["ChainRulesCore"]

[deps.AbstractFFTs.extensions]
Expand Down Expand Up @@ -142,9 +142,9 @@ version = "1.16.0"

[[deps.CodecZlib]]
deps = ["TranscodingStreams", "Zlib_jll"]
git-tree-sha1 = "9c209fb7536406834aa938fb149964b985de6c83"
git-tree-sha1 = "02aa26a4cf76381be7f66e020a3eddeb27b0a092"
uuid = "944b1d66-785c-5afd-91f1-9de20f533193"
version = "0.7.1"
version = "0.7.2"

[[deps.ColorBrewer]]
deps = ["Colors", "JSON", "Test"]
Expand Down Expand Up @@ -205,9 +205,9 @@ version = "0.5.1"

[[deps.ConcurrentUtilities]]
deps = ["Serialization", "Sockets"]
git-tree-sha1 = "96d823b94ba8d187a6d8f0826e731195a74b90e9"
git-tree-sha1 = "5372dbbf8f0bdb8c700db5367132925c0771ef7e"
uuid = "f0e56b4a-5159-44fe-b623-3e5288b988bb"
version = "2.2.0"
version = "2.2.1"

[[deps.ConstructionBase]]
deps = ["LinearAlgebra"]
Expand Down Expand Up @@ -276,10 +276,10 @@ uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
version = "0.27.25"

[[deps.DocumenterCitations]]
deps = ["Bibliography", "DataStructures", "Documenter", "Markdown", "Unicode"]
git-tree-sha1 = "256f098ebde08780f058a9c84b4d08601b4ed2b4"
deps = ["Bibliography", "Documenter", "Markdown", "OrderedCollections", "Unicode"]
git-tree-sha1 = "b4b45d64eea45d96b5d35ec9ef4a0de15b7f2cdb"
uuid = "daee34ce-89f3-4625-b898-19384cb65244"
version = "0.2.12"
version = "1.0.0"

[[deps.Downloads]]
deps = ["ArgTools", "FileWatching", "LibCURL", "NetworkOptions"]
Expand Down Expand Up @@ -355,9 +355,9 @@ uuid = "7b1f6079-737a-58dc-b8bc-7a2ca5c1b5ee"

[[deps.FillArrays]]
deps = ["LinearAlgebra", "Random", "SparseArrays", "Statistics"]
git-tree-sha1 = "2250347838b28a108d1967663cba57bfb3c02a58"
git-tree-sha1 = "e5556303fd8c9ad4a8fceccd406ef3433ddb4c45"
uuid = "1a297f60-69ca-5386-bcde-b61e274b549b"
version = "1.3.0"
version = "1.4.0"

[[deps.FixedPointNumbers]]
deps = ["Statistics"]
Expand Down Expand Up @@ -466,9 +466,9 @@ version = "1.12.2+2"

[[deps.HTTP]]
deps = ["Base64", "CodecZlib", "ConcurrentUtilities", "Dates", "ExceptionUnwrapping", "Logging", "LoggingExtras", "MbedTLS", "NetworkOptions", "OpenSSL", "Random", "SimpleBufferStream", "Sockets", "URIs", "UUIDs"]
git-tree-sha1 = "7f5ef966a02a8fdf3df2ca03108a88447cb3c6f0"
git-tree-sha1 = "cb56ccdd481c0dd7f975ad2b3b62d9eda088f7e2"
uuid = "cd3eb016-35fb-5094-929b-558a96fad6f3"
version = "1.9.8"
version = "1.9.14"

[[deps.HarfBuzz_jll]]
deps = ["Artifacts", "Cairo_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "Graphite2_jll", "JLLWrappers", "Libdl", "Libffi_jll", "Pkg"]
Expand All @@ -478,9 +478,9 @@ version = "2.8.1+1"

[[deps.HypergeometricFunctions]]
deps = ["DualNumbers", "LinearAlgebra", "OpenLibm_jll", "SpecialFunctions"]
git-tree-sha1 = "0ec02c648befc2f94156eaef13b0f38106212f3f"
git-tree-sha1 = "83e95aaab9dc184a6dcd9c4c52aa0dc26cd14a1d"
uuid = "34004b35-14d8-5ef3-9330-4cdb6864b03a"
version = "0.3.17"
version = "0.3.21"

[[deps.IOCapture]]
deps = ["Logging", "Random"]
Expand Down Expand Up @@ -585,9 +585,9 @@ version = "1.0.0"

[[deps.JLD2]]
deps = ["FileIO", "MacroTools", "Mmap", "OrderedCollections", "Pkg", "Printf", "Reexport", "Requires", "TranscodingStreams", "UUIDs"]
git-tree-sha1 = "42c17b18ced77ff0be65957a591d34f4ed57c631"
git-tree-sha1 = "5df8278ad24772c0c6dbbeb97b162ccf29ced2a9"
uuid = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
version = "0.4.31"
version = "0.4.32"

[[deps.JLLWrappers]]
deps = ["Preferences"]
Expand Down Expand Up @@ -1233,18 +1233,18 @@ version = "0.1.1"

[[deps.StaticArrays]]
deps = ["LinearAlgebra", "Random", "StaticArraysCore"]
git-tree-sha1 = "0da7e6b70d1bb40b1ace3b576da9ea2992f76318"
git-tree-sha1 = "fffc14c695c17bfdbfa92a2a01836cdc542a1e46"
uuid = "90137ffa-7385-5640-81b9-e52037218182"
version = "1.6.0"
version = "1.6.1"
weakdeps = ["Statistics"]

[deps.StaticArrays.extensions]
StaticArraysStatisticsExt = "Statistics"

[[deps.StaticArraysCore]]
git-tree-sha1 = "6b7ba252635a5eff6a0b0664a41ee140a1c9e72a"
git-tree-sha1 = "1d5708d926c76a505052d0d24a846d5da08bc3a4"
uuid = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
version = "1.4.0"
version = "1.4.1"

[[deps.Statistics]]
deps = ["LinearAlgebra", "SparseArrays"]
Expand Down Expand Up @@ -1279,9 +1279,9 @@ version = "1.3.0"

[[deps.StringEncodings]]
deps = ["Libiconv_jll"]
git-tree-sha1 = "33c0da881af3248dafefb939a21694b97cfece76"
git-tree-sha1 = "b765e46ba27ecf6b44faf70df40c57aa3a547dcb"
uuid = "69024149-9ee7-55f6-a4c4-859efe599b68"
version = "0.3.6"
version = "0.3.7"

[[deps.StructArrays]]
deps = ["Adapt", "DataAPI", "GPUArraysCore", "StaticArraysCore", "Tables"]
Expand Down
1 change: 1 addition & 0 deletions docs/Project.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,5 @@ TimesDates = "bdfc003b-8df8-5c39-adcd-3a9087f5df4a"

[compat]
CairoMakie = "0.10 - 0.10.4" # v0.10.5, v0.10.6 very slow with contourf + prescribed levels
DocumenterCitations = "1"
Literate = "≥2.9.0"
5 changes: 3 additions & 2 deletions docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ end
using Oceananigans.BoundaryConditions: Flux, Value, Gradient, Open

bib_filepath = joinpath(dirname(@__FILE__), "oceananigans.bib")
bib = CitationBibliography(bib_filepath)
bib = CitationBibliography(bib_filepath, style=:authoryear)

#####
##### Generate examples
Expand Down Expand Up @@ -170,7 +170,8 @@ pages = [
format = Documenter.HTML(collapselevel = 1,
prettyurls = get(ENV, "CI", nothing) == "true",
canonical = "https://clima.github.io/OceananigansDocumentation/stable/",
mathengine = MathJax3())
mathengine = MathJax3(),
assets = String["assets/citations.css"])

makedocs(bib, sitename = "Oceananigans.jl",
authors = "Climate Modeling Alliance and contributors",
Expand Down
18 changes: 9 additions & 9 deletions docs/oceananigans.bib
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ @book{Hesthaven07
}

@article{Marshall97FV,
title = {A finite-volume, incompressible {Navier--Stokes} model for studies of the ocean on parallel computers},
title = {A finite-volume, incompressible Navier--Stokes model for studies of the ocean on parallel computers},
volume = {102},
doi = {10.1029/96JC02775},
number = {C3},
Expand Down Expand Up @@ -176,9 +176,9 @@ @book{Boussinesq1903
}

@book{Boussinesq1877,
title={Essai sur la th{\'e}orie des eaux courantes},
title={Essai sur la théorie des eaux courantes},
author={Boussinesq, J.},
series={M{\'e}moires pr{\'e}sent{\'e}s par divers savants {\`a} l'Acad{\'e}mie des sciences de l'Institut national de France},
series={Mémoires présentés par divers savants à l'Académie des sciences de l'Institut national de France},
year={1877},
publisher={Impr. Nationale}
}
Expand Down Expand Up @@ -219,7 +219,7 @@ @article{Orszag86
}

@article{Brown01,
title = {Accurate projection methods for the incompressible {Navier--Stokes} equations},
title = {Accurate projection methods for the incompressible Navier--Stokes equations},
volume = {168},
doi = {10/djz53c},
number = {2},
Expand Down Expand Up @@ -253,7 +253,7 @@ @article{Harlow65


@book{Kumar16,
title = {Local {BVP} methods for the computation of cell-face velocities in the incompressible {Navier--Stokes} equations},
title = {Local {BVP} methods for the computation of cell-face velocities in the incompressible Navier--Stokes equations},
author = {N. Kumar and Boonkkamp, J.H.M. and B. Koren},
year = {2016},
series = {CASA-report},
Expand All @@ -262,7 +262,7 @@ @book{Kumar16
}

@article{Sani81,
title = {The cause and cure (?) of the spurious pressures generated by certain {FEM} solutions of the incompressible {Navier--Stokes} equations: {Part} 1},
title = {The cause and cure (?) of the spurious pressures generated by certain {FEM} solutions of the incompressible Navier--Stokes equations: {Part} 1},
volume = {1},
doi = {10.1002/fld.1650010104},
number = {1},
Expand Down Expand Up @@ -643,7 +643,7 @@ @article{Verstappen18
title = {How much eddy dissipation is needed to counterbalance the nonlinear production of small, unresolved scales in a large-eddy simulation of turbulence?},
volume = {176},
doi = {10.1016/j.compfluid.2016.12.016},
journal = {Computers \& Fluids},
journal = {Computers & Fluids},
author = {Verstappen, Roel},
year = {2018},
pages = {276--284}
Expand All @@ -664,7 +664,7 @@ @article{Bruneau06
volume = {35},
doi = {10/fvshbk},
number = {3},
journal = {Computers \& Fluids},
journal = {Computers & Fluids},
author = {Bruneau, Charles-Henri and Saad, Mazen},
year = {2006},
pages = {326--348}
Expand All @@ -675,7 +675,7 @@ @article{Botella98
volume = {27},
doi = {10/chbd5b},
number = {4},
journal = {Computers \& Fluids},
journal = {Computers & Fluids},
author = {Botella, O. and Peyret, R.},
year = {1998},
pages = {421--433}
Expand Down
2 changes: 1 addition & 1 deletion docs/src/appendix/fractional_step.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ problem for the pressure ``p^{n+1}`` with the boundary condition
\boldsymbol{\hat{n}} \boldsymbol{\cdot} \boldsymbol{\nabla} p^{n+1} |_{\partial\Omega} = 0 \, .
```

[Orszag86](@cite) and [Brown01](@cite) raise an important issue regarding these fractional step
[Orszag86](@citet) and [Brown01](@citet) raise an important issue regarding these fractional step
methods, which is that "*while the velocity can be reliably computed to second-order accuracy
in time and space, the pressure is typically only first-order accurate in the ``L_\infty``-norm.*"
The numerical boundary conditions must be carefully accounted for to ensure the second-order
Expand Down
16 changes: 8 additions & 8 deletions docs/src/appendix/staggered_grid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ on the top and bottom edges of the pressure control volumes. The indexing conven

This staggered arrangement of variables is more complicated than the collocated grid arrangement but is greatly
beneficial as it avoids the odd-even decoupling between the pressure and velocity if they are stored at the same
positions. §6.1 of [Patankar80](@cite) discusses this problem in the presence of a zigzag pressure field: on a 1D
positions. §6.1 of [Patankar80](@citet) discusses this problem in the presence of a zigzag pressure field: on a 1D
collocated grid the velocity at the point ``i`` is influenced by the pressure at points ``i-1`` and ``i+1``, and a zigzag
pressure field will be felt as a uniform pressure, which is obviously wrong and would reduce the accuracy of the
solution. The pressure is effectively taken from a coarser grid than what is actually used. The basic problem is that
Expand All @@ -29,23 +29,23 @@ From the viewpoint of linear algebra, these spurious pressure modes correspond t
pressure projection operator with eigenvalue zero and are thus indistinguishable from a uniform pressure field
[Sani81](@cite).

The staggered grid was first introduced by [Harlow65](@cite) with their *marker and cell* method. In meteorology
and oceanography, this particular staggered grid configuration is referred to as the Arakawa C-grid after [Arakawa77](@cite), who
The staggered grid was first introduced by [Harlow65](@citet) with their *marker and cell* method. In meteorology
and oceanography, this particular staggered grid configuration is referred to as the Arakawa C-grid after [Arakawa77](@citet), who
investigated four different staggered grids and the unstaggered A-grid for use in an atmospheric model.

[Arakawa77](@cite) investigated the dispersion relation of inertia-gravity waves[^2] traveling in the ``x``-direction
[Arakawa77](@citet) investigated the dispersion relation of inertia-gravity waves[^2] traveling in the ``x``-direction
```math
\omega^2 = f^2 + gHk^2 \, ,
```
in the linearized rotating shallow-water equations for five grids. Here ``\omega`` is the angular frequency, ``H`` is the
height of the fluid and ``k`` is the wavenumber in the ``x``-direction. Looking at the effect of spatial discretization
error on the frequency of these waves they find that the B and C-grids reproduce the dispersion relation most closely
out of the five [Arakawa77](@cite) (Figure 5). In particular, the dispersion relation for the C-grid is given by
out of the five [Arakawa77](@citet) (Figure 5). In particular, the dispersion relation for the C-grid is given by
```math
\omega^2 = f^2 \left[ \cos^2 \left( \frac{k\Delta}{2} \right)
+ 4 \left( \frac{\lambda}{\Delta} \right)^2 \sin^2 \left( \frac{k\Delta}{2} \right) \right] \, ,
```
where ``\lambda`` is the wavelength and ``\Delta`` is the grid spacing. Paraphrasing p. 184 of [Arakawa77](@cite): The
where ``\lambda`` is the wavelength and ``\Delta`` is the grid spacing. Paraphrasing p. 184 of [Arakawa77](@citet): The
wavelength of the shortest resolvable wave is ``2\Delta`` with corresponding wavenumber ``k = \pi/\Delta`` so it is
sufficient to evaluate the dispersion relation over the range ``0 < k \Delta < \pi``. The frequency is monotonically
increasing for ``\lambda / \Delta > \frac{1}{2}`` and monotonically decreasing for ``\lambda / \Delta < \frac{1}{2}``. For the
Expand All @@ -55,8 +55,8 @@ oscillations or stationary waves, which is bad.

The B and C-grids are less oscillatory than the others and quite faithfully simulate geostrophic adjustment. However,
the C-grid is the only one that faithfully reproduces the two-dimensional dispersion relation ``\omega^2(k, \ell)``, all
the other grids have false maxima, and so [Arakawa77](@cite) conclude that the C-grid is best for simulating geostrophic
the other grids have false maxima, and so [Arakawa77](@citet) conclude that the C-grid is best for simulating geostrophic
adjustment except for abnormal situations in which ``\lambda / \Delta`` is less than or close to 1. This seems to have held
true for most atmospheric and oceanographic simulations as the C-grid is popular and widely used.

[^2]: Apparently also called Poincaré waves, Sverdrup waves, and *rotational gravity waves* §13.9 of [Kundu15](@cite).
[^2]: Apparently also called Poincaré waves, Sverdrup waves, and *rotational gravity waves* §13.9 of [Kundu15](@citet).
18 changes: 18 additions & 0 deletions docs/src/assets/citations.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
.citation dl {
display: grid;
grid-template-columns: max-content auto; }
.citation dt {
grid-column-start: 1; }
.citation dd {
grid-column-start: 2;
margin-bottom: 0.75em; }
.citation ul {
padding: 0 0 2.25em 0;
margin: 0;
list-style: none;}
.citation ul li {
text-indent: -2.25em;
margin: 0.33em 0.5em 0.5em 2.25em;}
.citation ol li {
padding-left:0.75em;}

4 changes: 2 additions & 2 deletions docs/src/model_setup/buoyancy_and_equation_of_state.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ SeawaterBuoyancy{Float64}:
### Idealized nonlinear equations of state

Instead of a linear equation of state, six idealized (second-order) nonlinear equations of state
as described by [Roquet15Idealized](@cite) may be used. These equations of state are provided
as described by [Roquet15Idealized](@citet) may be used. These equations of state are provided
via the [SeawaterPolynomials.jl](https://github.com/CliMA/SeawaterPolynomials.jl) package.

```jldoctest buoyancy
Expand All @@ -208,7 +208,7 @@ SeawaterBuoyancy{Float64}:
### TEOS-10 equation of state

A high-accuracy 55-term polynomial approximation to the TEOS-10 equation of state suitable for use in
Boussinesq models as described by [Roquet15TEOS](@cite) is implemented in the
Boussinesq models as described by [Roquet15TEOS](@citet) is implemented in the
[SeawaterPolynomials.jl](https://github.com/CliMA/SeawaterPolynomials.jl) package and may be used.

```jldoctest buoyancy
Expand Down
12 changes: 6 additions & 6 deletions docs/src/numerical_implementation/elliptic_solvers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ Discretizing elliptic problems that can be solved via a classical separation-of-
equation, results in a linear system of equations ``M \boldsymbol{x} = \boldsymbol{y}`` where ``M`` is a real symmetric matrix of block
tridiagonal form. This allows for the matrix to be decomposed and solved efficiently, provided that the eigenvalues and
eigenvectors of the blocks are known (§2) [Buzbee70](@cite). In the case of Poisson's equation on a rectangle,
[Hockney65](@cite) has taken advantage of the fact that the fast Fourier transform can be used to perform the matrix
multiplication steps resulting in an even more efficient method. [Schumann88](@cite) describe the implementation of such
[Hockney65](@citet) has taken advantage of the fact that the fast Fourier transform can be used to perform the matrix
multiplication steps resulting in an even more efficient method. [Schumann88](@citet) describe the implementation of such
an algorithm for Poisson's equation on a staggered grid with Dirichlet, Neumann, and periodic boundary conditions.

The method can be explained easily by taking the Fourier transform of both sides of \eqref{eq:poisson-pressure} to yield
Expand All @@ -51,7 +51,7 @@ coefficients of the solution are easily solved for
\widehat{p}_{NH}(i, j, k) = - \frac{\widehat{\mathscr{F}}(i, j, k)}{\lambda^x_i + \lambda^y_j + \lambda^z_k} \, .
```

The eigenvalues are given by [Schumann88](@cite) and can also be tediously derived by plugging in the definition of the
The eigenvalues are given by [Schumann88](@citet) and can also be tediously derived by plugging in the definition of the
discrete Fourier transform into \eqref{eq:poisson-spectral}:
```math
\begin{align}
Expand Down Expand Up @@ -81,8 +81,8 @@ system along one of the dimensions and utilizing cyclic reduction. This results
reduction* or ``\text{FACR}(\ell)`` algorithm (with ``\ell`` cyclic reduction steps) which requires only
``\mathcal{O}(N \log_2\log_2 N)`` operations provided the optimal number of cyclic reduction steps is taken, which is
``\ell = \log_2 \log_2 n`` where ``n`` is the number of grid points in the cyclic reduction dimension. The FACR algorithm
was first developed by [Hockney69](@cite) and is well reviewed by [Swarztrauber77](@cite) then further benchmarked and
extended by [Temperton79](@cite) and [Temperton80](@cite).
was first developed by [Hockney69](@citet) and is well reviewed by [Swarztrauber77](@citet) then further benchmarked and
extended by [Temperton79](@citet) and [Temperton80](@citet).

Furthermore, the FACR algorithm removes the restriction that the grid is uniform in one of the dimensions so it can
be utilized to implement a fast Poisson solver for vertically stretched grids if the cyclic reduction is applied in the
Expand Down Expand Up @@ -113,7 +113,7 @@ Discretizing the ``\partial_z^2`` derivative and equating the term inside the br
## Cosine transforms on the GPU

Unfortunately cuFFT does not provide cosine transforms and so we must write our own fast cosine
transforms for the GPU. We implemented the fast 1D and 2D cosine transforms described by [Makhoul80](@cite)
transforms for the GPU. We implemented the fast 1D and 2D cosine transforms described by [Makhoul80](@citet)
which compute it by applying the regular Fourier transform to a permuted version of the array.

In this section we will be using the DCT-II as the definition of the forward cosine transform
Expand Down
Loading

0 comments on commit f7acd8d

Please sign in to comment.