Major documentation refactoring for JOSS (#570)

Major documentation refactoring for JOSS

.appveyor.yml

@@ -1,6 +1,6 @@
 environment:
   matrix:
-  - julia_version: 1.1
+  - julia_version: 1.3
   - julia_version: nightly
 
 platform:

.gitlab-ci.yml

@@ -7,16 +7,9 @@ include:
   - 'https://raw.githubusercontent.com/JuliaGPU/gitlab-ci/master/templates/v5/test.yml'
   - 'https://raw.githubusercontent.com/JuliaGPU/gitlab-ci/master/templates/v5/coverage.yml'
 
-test:v1.1:
-  extends: .test:v1.1
-
 test:v1.2:
   extends: .test:v1.2
 
-test:v1.3:
-  extends: .test:v1.3
-  allow_failure: true
-
 test:dev:
   extends: .test:dev
   allow_failure: true

.travis.yml

@@ -5,7 +5,7 @@ os:
   - osx
 
 julia:
-  - 1.2
+  - 1.3
 
 env:
   global:
@@ -24,6 +24,6 @@ jobs:
       julia: 1.2
       os: linux
       script:
-        - julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.add("Documenter"); Pkg.add("Literate"); Pkg.add("PyPlot"); Pkg.develop(PackageSpec(path=pwd()))'
-        - julia --project=docs/ docs/make.jl
+        - julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.add("Documenter"); Pkg.add("Literate"); Pkg.add("Plots"); Pkg.develop(PackageSpec(path=pwd()))'
+        - JULIA_DEBUG=all julia --project=docs/ docs/make.jl
       after_success: skip

Manifest.toml

@@ -2,9 +2,9 @@
 
 [[AbstractFFTs]]
 deps = ["LinearAlgebra"]
-git-tree-sha1 = "380e36c66edfa099cd90116b24c1ce8cafccac40"
+git-tree-sha1 = "051c95d6836228d120f5f4b984dd5aba1624f716"
 uuid = "621f4979-c628-5d54-868e-fcf4e3e8185c"
-version = "0.4.1"
+version = "0.5.0"
 
 [[Adapt]]
 deps = ["LinearAlgebra"]
@@ -87,11 +87,6 @@ git-tree-sha1 = "3b868935adf4ce2115f5487e789553507739014c"
 uuid = "a9693cdc-2bc8-5703-a9cd-1da358117377"
 version = "0.1.0"
 
-[[Crayons]]
-git-tree-sha1 = "cb7a62895da739fe5bb43f1a26d4292baf4b3dc0"
-uuid = "a8cc5b0e-0ffa-5ad4-8c14-923d3ee1735f"
-version = "4.0.1"
-
 [[CuArrays]]
 deps = ["AbstractFFTs", "Adapt", "CEnum", "CUDAapi", "CUDAdrv", "CUDAnative", "DataStructures", "GPUArrays", "Libdl", "LinearAlgebra", "MacroTools", "NNlib", "Printf", "Random", "Requires", "SparseArrays", "TimerOutputs"]
 git-tree-sha1 = "e99db1397ce85975203a9d736ab37534730996ca"
@@ -122,22 +117,23 @@ deps = ["Random", "Serialization", "Sockets"]
 uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 
 [[FFTW]]
-deps = ["AbstractFFTs", "BinaryProvider", "Conda", "Libdl", "LinearAlgebra", "Reexport", "Test"]
-git-tree-sha1 = "03f8776fbdae28c20c0d1d2ae4e090cd1dfcd247"
+deps = ["AbstractFFTs", "BinaryProvider", "Conda", "Libdl", "LinearAlgebra", "Reexport"]
+git-tree-sha1 = "4cfd3d43819228b9e73ab46600d0af0aa5cedceb"
+pinned = true
 uuid = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
-version = "1.0.0"
+version = "1.1.0"
 
 [[FileIO]]
 deps = ["Pkg"]
-git-tree-sha1 = "6c976460b85527d22d979682222d36767d95e27f"
+git-tree-sha1 = "80c17c711c41416eb0ac68347dc036be68b37682"
 uuid = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
-version = "1.1.0"
+version = "1.2.0"
 
 [[GPUArrays]]
 deps = ["AbstractFFTs", "Adapt", "LinearAlgebra", "Printf", "Random", "Serialization"]
-git-tree-sha1 = "a0a3b927b1a06e63fb8b91950cc7df340b7d912c"
+git-tree-sha1 = "e756da6cee76a5f1436a05827fa8fdf3badc577f"
 uuid = "0c68f7d7-f131-5f86-a1c3-88cf8149b2d7"
-version = "2.0.0"
+version = "2.0.1"
 
 [[GPUifyLoops]]
 deps = ["Cassette", "Requires", "StaticArrays"]
@@ -150,10 +146,10 @@ deps = ["Markdown"]
 uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 
 [[JLD2]]
-deps = ["CodecZlib", "DataStructures", "FileIO", "LinearAlgebra", "Mmap", "Printf", "Random", "Test"]
-git-tree-sha1 = "3ba90ff93e1d5b9b2103588051c2d349fae54dac"
+deps = ["CodecZlib", "DataStructures", "FileIO", "Mmap", "Pkg", "Printf", "UUIDs"]
+git-tree-sha1 = "0193ef8c75ce70584198b95b4a48f9ec0c49ffa8"
 uuid = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
-version = "0.1.2"
+version = "0.1.9"
 
 [[JSON]]
 deps = ["Dates", "Mmap", "Parsers", "Unicode"]
@@ -186,7 +182,6 @@ git-tree-sha1 = "e2fc7a55bb2224e203bbd8b59f72b91323233458"
 uuid = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 version = "0.5.3"
 
-
 [[Markdown]]
 deps = ["Base64"]
 uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
@@ -202,9 +197,9 @@ uuid = "a63ad114-7e13-5084-954f-fe012c677804"
 
 [[NCDatasets]]
 deps = ["BinDeps", "CFTime", "Compat", "CondaBinDeps", "DataStructures", "Dates", "Libdl", "Missings", "Printf", "Random"]
-git-tree-sha1 = "21f833cf06f4e0128726b25aa2fc662b7d66d1bd"
+git-tree-sha1 = "6c0398c68c2f1957a8368b8cc6c8f9ee98ad5738"
 uuid = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
-version = "0.9.3"
+version = "0.9.5"
 
 [[NNlib]]
 deps = ["Libdl", "LinearAlgebra", "Requires", "Statistics", "TimerOutputs"]
@@ -213,9 +208,9 @@ uuid = "872c559c-99b0-510c-b3b7-b6c96a88d5cd"
 version = "0.6.0"
 
 [[OffsetArrays]]
-git-tree-sha1 = "1af2f79c7eaac3e019a0de41ef63335ff26a0a57"
+git-tree-sha1 = "87d0a91efe29352d5caaa271ae3927083c096e33"
 uuid = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
-version = "0.11.1"
+version = "0.11.4"
 
 [[OrderedCollections]]
 deps = ["Random", "Serialization", "Test"]
@@ -276,9 +271,9 @@ uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [[StaticArrays]]
 deps = ["LinearAlgebra", "Random", "Statistics"]
-git-tree-sha1 = "db23bbf50064c582b6f2b9b043c8e7e98ea8c0c6"
+git-tree-sha1 = "1085ffbf5fd48fdba64ef8e902ca429c4e1212d3"
 uuid = "90137ffa-7385-5640-81b9-e52037218182"
-version = "0.11.0"
+version = "0.11.1"
 
 [[Statistics]]
 deps = ["LinearAlgebra", "SparseArrays"]
@@ -289,10 +284,10 @@ deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
 uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [[TimerOutputs]]
-deps = ["Crayons", "Printf", "Test", "Unicode"]
-git-tree-sha1 = "b80671c06f8f8bae08c55d67b5ce292c5ae2660c"
+deps = ["Printf"]
+git-tree-sha1 = "311765af81bbb48d7bad01fb016d9c328c6ede03"
 uuid = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
-version = "0.5.0"
+version = "0.5.3"
 
 [[TranscodingStreams]]
 deps = ["Random", "Test"]
@@ -314,7 +309,6 @@ uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 
 [[VersionParsing]]
-deps = ["Compat"]
-git-tree-sha1 = "c9d5aa108588b978bd859554660c8a5c4f2f7669"
+git-tree-sha1 = "80229be1f670524750d905f8fc8148e5a8c4537f"
 uuid = "81def892-9a0e-5fdd-b105-ffc91e053289"
-version = "1.1.3"
+version = "1.2.0"

Project.toml

@@ -1,6 +1,6 @@
 name = "Oceananigans"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
-version = "0.17.0"
+version = "0.18.0"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
@@ -44,4 +44,8 @@ TimerOutputs = "^0.5, ^1"
 julia = "^1.1"
 
 [extras]
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test", "Plots"]

README.md

@@ -8,41 +8,44 @@
   <strong>🌊 A fast and friendly incompressible fluid flow solver in Julia that can be run in 1-3 dimensions on CPUs and GPUs. http://bit.ly/oceananigans</strong>
 </p>
 
-<!-- Information badge -->
+<!-- Information badges -->
 <p align="center">
   <a href="https://www.repostatus.org/#active">
-    <img alt="Project Status" src="https://www.repostatus.org/badges/latest/active.svg?style=flat-square" />
+    <img alt="Repo status" src="https://www.repostatus.org/badges/latest/active.svg?style=flat-square" />
   </a>
   <a href="https://mit-license.org">
     <img alt="MIT license" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square">
   </a>
   <a href="https://github.com/climate-machine/Oceananigans.jl/issues/new">
     <img alt="Ask us anything" src="https://img.shields.io/badge/Ask%20us-anything-1abc9c.svg?style=flat-square">
   </a>
+  <a href="https://climate-machine.github.io/Oceananigans.jl/stable/">
+    <img alt="Stable documentation" src="https://img.shields.io/badge/docs-stable-blue.svg?style=flat-square">
+  </a>
   <a href="https://climate-machine.github.io/Oceananigans.jl/latest">
-    <img alt="Documents" src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square">
+    <img alt="Latest documentation" src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square">
   </a>
 </p>
 
-<!-- CI/CD badge -->
+<!-- CI/CD badges -->
 <p align="center">
   <a href="https://travis-ci.com/climate-machine/Oceananigans.jl">
-    <img alt="Build Status for CPU" src="https://img.shields.io/travis/com/climate-machine/Oceananigans.jl/master?label=CPU&logo=travis&logoColor=white&style=flat-square">
+    <img alt="CPU build status" src="https://img.shields.io/travis/com/climate-machine/Oceananigans.jl/master?label=CPU&logo=travis&logoColor=white&style=flat-square">
   </a>
   <a href="https://gitlab.com/JuliaGPU/Oceananigans-jl/commits/master">
-    <img alt="Build Status for GPU" src="https://img.shields.io/gitlab/pipeline/JuliaGPU/Oceananigans-jl/master?label=GPU&logo=gitlab&logoColor=white&style=flat-square">
+    <img alt="GPU build status" src="https://img.shields.io/gitlab/pipeline/JuliaGPU/Oceananigans-jl/master?label=GPU&logo=gitlab&logoColor=white&style=flat-square">
   </a>
   <a href="https://ci.appveyor.com/project/ali-ramadhan/oceananigans-jl">
-    <img alt="Build Status for Window" src="https://img.shields.io/appveyor/ci/ali-ramadhan/oceananigans-jl/master?label=Window&logo=appveyor&logoColor=white&style=flat-square">
+    <img alt="Windows build status" src="https://img.shields.io/appveyor/ci/ali-ramadhan/oceananigans-jl/master?label=Window&logo=appveyor&logoColor=white&style=flat-square">
   </a>
   <a href="https://hub.docker.com/r/aliramadhan/oceananigans">
-    <img alt="Build Status for Docker" src="https://img.shields.io/docker/cloud/build/aliramadhan/oceananigans?label=Docker&logo=docker&logoColor=white&style=flat-square">
+    <img alt="Docker build status" src="https://img.shields.io/docker/cloud/build/aliramadhan/oceananigans?label=Docker&logo=docker&logoColor=white&style=flat-square">
   </a>
   <a href="https://codecov.io/gh/climate-machine/Oceananigans.jl">
-    <img alt="Coverage Status for Codecov" src="https://img.shields.io/codecov/c/github/climate-machine/Oceananigans.jl/master?label=Codecov&logo=codecov&logoColor=white&style=flat-square">
+    <img alt="Codecov coverage" src="https://img.shields.io/codecov/c/github/climate-machine/Oceananigans.jl/master?label=Codecov&logo=codecov&logoColor=white&style=flat-square">
   </a>
   <a href="https://coveralls.io/github/climate-machine/Oceananigans.jl?branch=master">
-    <img alt="Coverage Status for Coveralls" src="https://img.shields.io/coveralls/github/climate-machine/Oceananigans.jl/master?label=Coveralls&style=flat-square">
+    <img alt="Coveralls coverage" src="https://img.shields.io/coveralls/github/climate-machine/Oceananigans.jl/master?label=Coveralls&style=flat-square">
   </a>
 </p>
 

benchmark/benchmark_eddying_channel.jl

@@ -3,6 +3,10 @@ using Oceananigans
 
 include("benchmark_utils.jl")
 
+#####
+##### Benchmark setup and parameters
+#####
+
 const timer = TimerOutput()
 
 Ni = 2  # Number of iterations before benchmarking starts.
@@ -14,11 +18,17 @@ Nt = 5  # Number of iterations to use for benchmarking time stepping.
          archs = [CPU()]             # Architectures to benchmark on.
 @hascuda archs = [CPU(), GPU()]      # Benchmark GPU on systems with CUDA-enabled GPUs.
 
+#####
+##### Run benchmarks
+#####
+
 for arch in archs, FT in float_types, N in Ns
     Nx, Ny, Nz = N
     Lx, Ly, Lz = 250e3, 250e3, 1000
 
-    model = ChannelModel(N=(Nx, Ny, Nz), L=(Lx, Ly, Lz), ν=1e-2, κ=1e-2, arch=arch, float_type=FT)
+    model = ChannelModel(architecture = arch, float_type = FT,
+			 grid = RegularCartesianGrid(size=(Nx, Ny, Nz), length=(Lx, Lx, Lz)),
+			 closure = ConstantIsotropicDiffusivity(ν=1e-2, κ=1e-2))
 
     # Eddying channel model setup.
     Ty = 4e-5  # Meridional temperature gradient [K/m].
@@ -37,7 +47,14 @@ for arch in archs, FT in float_types, N in Ns
     end
 end
 
-print_timer(timer, title="Eddying channel benchmarks")
+#####
+##### Print benchmark results
+#####
+
+println()
+print_benchmark_info()
+
+print_timer(timer, title="Eddying channel benchmarks", sortby=:name)
 
 println("\n\nCPU Float64 -> Float32 speedup:")
 for N in Ns

benchmark/benchmark_forcing_functions.jl

@@ -3,12 +3,12 @@ using Oceananigans
 
 include("benchmark_utils.jl")
 
-const timer = TimerOutput()
-
 #####
-##### Benchmark parameters
+##### Benchmark setup and parameters
 #####
 
+const timer = TimerOutput()
+
 Ni = 2   # Number of iterations before benchmarking starts.
 Nt = 10  # Number of iterations to use for benchmarking time stepping.
 
@@ -52,40 +52,51 @@ const λ = 1e-4
 ##### Run benchmarks
 #####
 
-for arch in archs, float_type in float_types, N in Ns
+for arch in archs, FT in float_types, N in Ns
     Nx, Ny, Nz = N
     Lx, Ly, Lz = 1, 1, 1
+
+    forced_model_params = Model(architecture = arch, float_type = FT,
+		                grid = RegularCartesianGrid(size=(Nx, Ny, Nz), length=(Lx, Ly, Lz)),
+                                forcing=ModelForcing(Fu=Fu_params, FT=FT_params), parameters=(K=0.1, λ=1e-4))
 
-    forced_model_params = Model(N=(Nx, Ny, Nz), L=(Lx, Ly, Lz), arch=arch, float_type=float_type,
-                                forcing=Forcing(Fu=Fu_params, FT=FT_params), parameters=(K=0.1, λ=1e-4))
     time_step!(forced_model_params, Ni, 1)  # First 1-2 iterations usually slower.
 
-    bn =  benchmark_name(N, "with forcing (params)", arch, float_type)
+    bn =  benchmark_name(N, "with forcing (params)", arch, FT)
     @printf("Running benchmark: %s...\n", bn)
     for i in 1:Nt
         @timeit timer bn time_step!(forced_model_params, 1, 1)
     end
-
-    forced_model_consts = Model(N=(Nx, Ny, Nz), L=(Lx, Ly, Lz), arch=arch, float_type=float_type,
-                                forcing=Forcing(Fu=Fu_consts, FT=FT_consts))
+
+    forced_model_consts = Model(architecture = arch, float_type = FT,
+		                grid = RegularCartesianGrid(size=(Nx, Ny, Nz), length=(Lx, Ly, Lz)),
+                                forcing=ModelForcing(Fu=Fu_consts, FT=FT_consts))
+
     time_step!(forced_model_consts, Ni, 1)  # First 1-2 iterations usually slower.
 
-    bn =  benchmark_name(N, "with forcing (consts)", arch, float_type)
+    bn =  benchmark_name(N, "with forcing (consts)", arch, FT)
     @printf("Running benchmark: %s...\n", bn)
     for i in 1:Nt
         @timeit timer bn time_step!(forced_model_consts, 1, 1)
     end
 
-    unforced_model = Model(N=(Nx, Ny, Nz), L=(Lx, Ly, Lz), arch=arch, float_type=float_type)
+    unforced_model = Model(architecture = arch, float_type = FT,
+			   grid = RegularCartesianGrid(size=(Nx, Ny, Nz), length=(Lx, Ly, Lz)))
+
     time_step!(unforced_model, Ni, 1)  # First 1-2 iterations usually slower.
 
-    bn =  benchmark_name(N, "  no forcing", arch, float_type)
+    bn =  benchmark_name(N, "  no forcing         ", arch, FT)
     @printf("Running benchmark: %s...\n", bn)
     for i in 1:Nt
         @timeit timer bn time_step!(unforced_model, 1, 1)
     end
 end
 
-print_timer(timer, title="Forcing function benchmarks")
-println("")
+#####
+##### Print benchmark results
+#####
 
+println()
+print_benchmark_info()
+print_timer(timer, title="Forcing function benchmarks")
+println()