Merge pull request #1870 from CliMA/ncc-glw/incompressible-becomes-no…

…nhydrostatic

Rename `IncompressibleModel` to `NonhydrostaticModel`

.buildkite/pipeline.yml

@@ -109,7 +109,7 @@ steps:
     depends_on: "init_cpu"
 
 #####
-##### IncompressibleModel and time stepping (part 1)
+##### NonhydrostaticModel and time stepping (part 1)
 #####
 
   - label: "🦀 gpu time stepping tests 1"
@@ -136,7 +136,7 @@ steps:
     depends_on: "init_cpu"
 
 #####
-##### IncompressibleModel and time stepping (part 2)
+##### NonhydrostaticModel and time stepping (part 2)
 #####
 
   - label: "🦈 gpu time stepping tests 2"

Project.toml

@@ -1,6 +1,6 @@
 name = "Oceananigans"
 uuid = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
-version = "0.59.1"
+version = "0.60.0"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

README.md

@@ -90,7 +90,7 @@ Let's initialize a 3D horizontally periodic model with 100×100×50 grid points
 ```julia
 using Oceananigans
 grid = RegularRectilinearGrid(size=(100, 100, 50), extent=(2π, 2π, 1))
-model = IncompressibleModel(grid=grid)
+model = NonhydrostaticModel(grid=grid)
 simulation = Simulation(model, Δt=60, stop_time=3600)
 run!(simulation)
 ```
@@ -108,7 +108,7 @@ N = Nx = Ny = Nz = 128   # Number of grid points in each dimension.
 L = Lx = Ly = Lz = 2000  # Length of each dimension.
 topology = (Periodic, Periodic, Bounded)
 
-model = IncompressibleModel(
+model = NonhydrostaticModel(
     architecture = CPU(),
             grid = RegularRectilinearGrid(topology=topology, size=(Nx, Ny, Nz), extent=(Lx, Ly, Lz)),
          closure = IsotropicDiffusivity(ν=4e-2, κ=4e-2)

benchmark/README.md

@@ -11,7 +11,7 @@ julia -e 'using Pkg; Pkg.activate(pwd()); Pkg.instantiate(); Pkg.develop(Package
 Once the environment has been instantiated, benchmarks can be run via, e.g.
 
 ```
-julia --project benchmark_incompressible_model.jl
+julia --project benchmark_nonhydrostatic_model.jl
 ```
 
 Most scripts benchmark one feature (e.g. advection schemes, arbitrary tracers). If your machine contains a CUDA-compatible GPU, benchmarks will also run on the GPU. Tables with benchmark results will be printed (and each table will also be saved to an HTML file).
@@ -22,5 +22,5 @@ The `benchmark_multithreading.jl` script will benchmark multithreaded CPU models
 
 ## Measuring performance regression
 
-Running the `benchmark_regression.jl` script will run the incompressible model tests on the current branch and on the master branch for comparison. This is useful to test whether the current branch slows down the code or introduces any performance regression.
+Running the `benchmark_regression.jl` script will run the nonhydrostatic model tests on the current branch and on the master branch for comparison. This is useful to test whether the current branch slows down the code or introduces any performance regression.
 

benchmark/benchmark_abstract_operations.jl

@@ -26,7 +26,7 @@ for Arch in Archs
     N = Arch == CPU ? (32, 32, 32) : (256, 256, 256)
 
     grid = RegularRectilinearGrid(FT, size=N, extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid,
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid,
                                 buoyancy=nothing, tracers=(:α, :β, :γ, :δ, :ζ))
 
     ε(x, y, z) = randn()

benchmark/benchmark_advection_schemes.jl

@@ -10,7 +10,7 @@ using Benchmarks
 
 function benchmark_advection_scheme(Arch, Scheme)
     grid = RegularRectilinearGrid(size=(192, 192, 192), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid, advection=Scheme())
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, advection=Scheme())
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_equations_of_state.jl

@@ -12,7 +12,7 @@ using Benchmarks
 function benchmark_equation_of_state(Arch, EOS)
     grid = RegularRectilinearGrid(size=(192, 192, 192), extent=(1, 1, 1))
     buoyancy = SeawaterBuoyancy(equation_of_state=EOS())
-    model = IncompressibleModel(architecture=Arch(), grid=grid, buoyancy=buoyancy)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, buoyancy=buoyancy)
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_lagrangian_particle_tracking.jl

@@ -20,7 +20,7 @@ function benchmark_particle_tracking(Arch, N_particles)
         particles = LagrangianParticles(x=x₀, y=y₀, z=z₀)
     end
 
-    model = IncompressibleModel(architecture=Arch(), grid=grid, particles=particles)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, particles=particles)
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_multithreading_single.jl

@@ -7,7 +7,7 @@ using Benchmarks
 
 N = parse(Int, ARGS[1])
 grid = RegularRectilinearGrid(size=(N, N, N), extent=(1, 1, 1))
-model = IncompressibleModel(architecture=CPU(), grid=grid)
+model = NonhydrostaticModel(architecture=CPU(), grid=grid)
 
 time_step!(model, 1) # warmup
 

benchmark/benchmark_incompressible_model.jl → benchmark/benchmark_nonhydrostatic_model.jl

@@ -8,9 +8,9 @@ using Plots
 pyplot()
 # Benchmark function
 
-function benchmark_incompressible_model(Arch, FT, N)
+function benchmark_nonhydrostatic_model(Arch, FT, N)
     grid = RegularRectilinearGrid(FT, size=(N, N, N), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid)
 
     time_step!(model, 1) # warmup
 
@@ -30,7 +30,7 @@ Ns = [32, 64, 128, 256]
 # Run and summarize benchmarks
 
 print_system_info()
-suite = run_benchmarks(benchmark_incompressible_model; Architectures, Float_types, Ns)
+suite = run_benchmarks(benchmark_nonhydrostatic_model; Architectures, Float_types, Ns)
 
 plot_num = length(Ns)
 CPU_Float32 = zeros(Float64, plot_num)
@@ -48,26 +48,26 @@ for i in 1:plot_num
 end
 
 plt = plot(Ns, CPU_Float32, lw=4, label="CPU Float32", xaxis=:log2, yaxis=:log, legend=:topleft,
-          xlabel="Nx", ylabel="Times (ms)", title="Incompressible Model Benchmarks: CPU vs GPU")
+          xlabel="Nx", ylabel="Times (ms)", title="Nonhydrostatic Model Benchmarks: CPU vs GPU")
 plot!(plt, Ns, CPU_Float64, lw=4, label="CPU Float64")
 plot!(plt, Ns, GPU_Float32, lw=4, label="GPU Float32")
 plot!(plt, Ns, GPU_Float64, lw=4, label="GPU Float64")
 display(plt)
-savefig(plt, "incompressible_times.png")
+savefig(plt, "nonhydrostatic_times.png")
 
 
 plt2 = plot(Ns, CPU_Float32./GPU_Float32, lw=4, xaxis=:log2, legend=:topleft, label="Float32",
-            xlabel="Nx", ylabel="Speedup Ratio", title="Incompressible Model Benchmarks: CPU/GPU")
+            xlabel="Nx", ylabel="Speedup Ratio", title="Nonhydrostatic Model Benchmarks: CPU/GPU")
 plot!(plt2, Ns, CPU_Float64./GPU_Float64, lw=4, label="Float64")
 display(plt2)
-savefig(plt2, "incompressible_speedup.png")
+savefig(plt2, "nonhydrostatic_speedup.png")
 
 df = benchmarks_dataframe(suite)
 sort!(df, [:Architectures, :Float_types, :Ns], by=(string, string, identity))
-benchmarks_pretty_table(df, title="Incompressible model benchmarks")
+benchmarks_pretty_table(df, title="Nonhydrostatic model benchmarks")
 
 if GPU in Architectures
     df_Δ = gpu_speedups_suite(suite) |> speedups_dataframe
     sort!(df_Δ, [:Float_types, :Ns], by=(string, identity))
-    benchmarks_pretty_table(df_Δ, title="Incompressible model CPU to GPU speedup")
+    benchmarks_pretty_table(df_Δ, title="Nonhydrostatic model CPU to GPU speedup")
 end

benchmark/benchmark_regression.jl

@@ -5,7 +5,7 @@ using Oceananigans
 using Benchmarks
 
 baseline = BenchmarkConfig(id="master")
-script = joinpath(@__DIR__, "benchmarkable_incompressible_model.jl")
+script = joinpath(@__DIR__, "benchmarkable_nonhydrostatic_model.jl")
 resultfile = joinpath(@__DIR__, "regression_benchmarks.json")
 
 judge(Oceananigans, baseline, script=script, resultfile=resultfile, verbose=true)

benchmark/benchmark_time_steppers.jl

@@ -9,7 +9,7 @@ using Benchmarks
 
 function benchmark_time_stepper(Arch, N, TimeStepper)
     grid = RegularRectilinearGrid(size=(N, N, N), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid, timestepper=TimeStepper)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, timestepper=TimeStepper)
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_topologies.jl

@@ -9,7 +9,7 @@ using Benchmarks
 
 function benchmark_topology(Arch, N, topo)
     grid = RegularRectilinearGrid(topology=topo, size=(N, N, N), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid)
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_tracers.jl

@@ -31,7 +31,7 @@ end
 function benchmark_tracers(Arch, N, n_tracers)
     n_active, n_passive = n_tracers
     grid = RegularRectilinearGrid(size=(N, N, N), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid, buoyancy=buoyancy(n_active),
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, buoyancy=buoyancy(n_active),
                                 tracers=tracer_list(n_active, n_passive))
 
     time_step!(model, 1) # warmup

benchmark/benchmark_turbulence_closures.jl

@@ -10,7 +10,7 @@ using Benchmarks
 
 function benchmark_closure(Arch, Closure)
     grid = RegularRectilinearGrid(size=(128, 128, 128), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid, closure=Closure())
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid, closure=Closure())
 
     time_step!(model, 1) # warmup
 

benchmark/benchmark_vertically_stretched_incompressible_model.jl → benchmark/benchmark_vertically_stretched_nonhydrostatic_model.jl

@@ -7,9 +7,9 @@ using Benchmarks
 
 # Benchmark function
 
-function benchmark_vertically_stretched_incompressible_model(Arch, FT, N)
+function benchmark_vertically_stretched_nonhydrostatic_model(Arch, FT, N)
     grid = VerticallyStretchedRectilinearGrid(architecture=Arch(), size=(N, N, N), x=(0, 1), y=(0, 1), z_faces=collect(0:N))
-    model = IncompressibleModel(architecture=Arch(), grid=grid)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid)
 
     time_step!(model, 1) # warmup
 
@@ -29,14 +29,14 @@ Ns = [32, 64, 128, 256]
 # Run and summarize benchmarks
 
 print_system_info()
-suite = run_benchmarks(benchmark_vertically_stretched_incompressible_model; Architectures, Float_types, Ns)
+suite = run_benchmarks(benchmark_vertically_stretched_nonhydrostatic_model; Architectures, Float_types, Ns)
 
 df = benchmarks_dataframe(suite)
 sort!(df, [:Architectures, :Float_types, :Ns], by=(string, string, identity))
-benchmarks_pretty_table(df, title="Vertically-stretched incompressible model benchmarks")
+benchmarks_pretty_table(df, title="Vertically-stretched nonhydrostatic model benchmarks")
 
 if GPU in Architectures
     df_Δ = gpu_speedups_suite(suite) |> speedups_dataframe
     sort!(df_Δ, [:Float_types, :Ns], by=(string, identity))
-    benchmarks_pretty_table(df_Δ, title="Vertically-stretched incompressible model CPU to GPU speedup")
+    benchmarks_pretty_table(df_Δ, title="Vertically-stretched nonhydrostatic model CPU to GPU speedup")
 end

benchmark/benchmarkable_incompressible_model.jl

@@ -19,7 +19,7 @@ for Arch in Architectures, FT in Float_types, N in Ns
     @info "Setting up benchmark: ($Arch, $FT, $N)..."
 
     grid = RegularRectilinearGrid(FT, size=(N, N, N), extent=(1, 1, 1))
-    model = IncompressibleModel(architecture=Arch(), grid=grid)
+    model = NonhydrostaticModel(architecture=Arch(), grid=grid)
 
     time_step!(model, 1) # warmup
 

benchmark/strong_scaling_incompressible_model.jl → benchmark/strong_scaling_nonhydrostatic_model.jl

@@ -23,9 +23,9 @@ print_system_info()
 for R in ranks
     Nx, Ny, Nz = grid_size(R, decomposition)
     Rx, Ry, Rz = rank_size(R, decomposition)
-    @info "Benchmarking distributed incompressible model strong scaling with $(typeof(decomposition)) decomposition [N=($Nx, $Ny, $Nz), ranks=($Rx, $Ry, $Rz)]..."
+    @info "Benchmarking distributed nonhydrostatic model strong scaling with $(typeof(decomposition)) decomposition [N=($Nx, $Ny, $Nz), ranks=($Rx, $Ry, $Rz)]..."
     julia = Base.julia_cmd()
-    run(`mpiexec -np $R $julia --project strong_scaling_incompressible_model_single.jl $(typeof(decomposition)) $Nx $Ny $Nz $Rx $Ry $Rz`)
+    run(`mpiexec -np $R $julia --project strong_scaling_nonhydrostatic_model_single.jl $(typeof(decomposition)) $Nx $Ny $Nz $Rx $Ry $Rz`)
 end
 
 # Collect and merge benchmarks from all ranks
@@ -38,7 +38,7 @@ for R in ranks
     case = ((Nx, Ny, Nz), (Rx, Ry, Rz))
 
     for local_rank in 0:R-1
-        filename = string("strong_scaling_incompressible_model_$(R)ranks_$(typeof(decomposition))_$local_rank.jld2")
+        filename = string("strong_scaling_nonhydrostatic_model_$(R)ranks_$(typeof(decomposition))_$local_rank.jld2")
         jldopen(filename, "r") do file
             if local_rank == 0
                 suite[case] = file["trial"]
@@ -67,22 +67,22 @@ for i in 1:plot_num
 end
 
 plt = plot(rank_num, run_times, lw=4, xaxis=:log2, legend=:none,
-          xlabel="Cores", ylabel="Times (ms)", title="Strong Scaling Incompressible Times")
+          xlabel="Cores", ylabel="Times (ms)", title="Strong Scaling Nonhydrostatic Times")
 display(plt)
-savefig(plt, "ss_incompressible_times.png")
+savefig(plt, "ss_nonhydrostatic_times.png")
 
 
 plt2 = plot(rank_num, eff_ratio, lw=4, xaxis=:log2, legend=:none, ylims=(0,1.1),
-            xlabel="Cores", ylabel="Efficiency", title="Strong Scaling Incompressible Efficiency")
+            xlabel="Cores", ylabel="Efficiency", title="Strong Scaling Nonhydrostatic Efficiency")
 display(plt2)
-savefig(plt2, "ss_incompressible_efficiency.png")
+savefig(plt2, "ss_nonhydrostatic_efficiency.png")
 
 df = benchmarks_dataframe(suite)
 sort!(df, :ranks)
-benchmarks_pretty_table(df, title="Incompressible model strong scaling benchmark")
+benchmarks_pretty_table(df, title="Nonhydrostatic model strong scaling benchmark")
 
 base_case = (grid_size(1, decomposition), rank_size(1, decomposition))
 suite_Δ = speedups_suite(suite, base_case=base_case)
 df_Δ = speedups_dataframe(suite_Δ, efficiency=:strong, base_case=base_case, key2rank=k->prod(k[2]))
 sort!(df_Δ, :ranks)
-benchmarks_pretty_table(df_Δ, title="Incompressible model strong scaling speedup")
+benchmarks_pretty_table(df_Δ, title="Nonhydrostatic model strong scaling speedup")

benchmark/strong_scaling_incompressible_model_single.jl → benchmark/strong_scaling_nonhydrostatic_model_single.jl

@@ -27,18 +27,18 @@ Rz = parse(Int, ARGS[7])
 
 @assert Rx * Ry * Rz == R
 
-@info "Setting up distributed incompressible model with N=($Nx, $Ny, $Nz) grid points and ranks=($Rx, $Ry, $Rz) ($decomposition decomposition) on rank $local_rank..."
+@info "Setting up distributed nonhydrostatic model with N=($Nx, $Ny, $Nz) grid points and ranks=($Rx, $Ry, $Rz) ($decomposition decomposition) on rank $local_rank..."
 
 topo = (Periodic, Periodic, Periodic)
 distributed_grid = RegularRectilinearGrid(topology=topo, size=(Nx, Ny, Nz), extent=(1, 1, 1))
 arch = MultiCPU(grid=distributed_grid, ranks=(Rx, Ry, Rz))
-model = DistributedIncompressibleModel(architecture=arch, grid=distributed_grid)
+model = DistributedNonhydrostaticModel(architecture=arch, grid=distributed_grid)
 
-@info "Warming up distributed incompressible model on rank $local_rank..."
+@info "Warming up distributed nonhydrostatic model on rank $local_rank..."
 
 time_step!(model, 1) # warmup
 
-@info "Benchmarking distributed incompressible model on rank $local_rank..."
+@info "Benchmarking distributed nonhydrostatic model on rank $local_rank..."
 
 trial = @benchmark begin
     @sync_gpu time_step!($model, 1)
@@ -47,6 +47,6 @@ end samples=10
 t_median = BenchmarkTools.prettytime(median(trial).time)
 @info "Done benchmarking on rank $(local_rank). Median time: $t_median"
 
-jldopen("strong_scaling_incompressible_model_$(R)ranks_$(decomposition)_$local_rank.jld2", "w") do file
+jldopen("strong_scaling_nonhydrostatic_model_$(R)ranks_$(decomposition)_$local_rank.jld2", "w") do file
     file["trial"] = trial
 end

docs/make.jl

@@ -92,8 +92,8 @@ model_setup_pages = [
 physics_pages = [
     "Coordinate system and notation" => "physics/notation.md",
     "Boussinesq approximation" => "physics/boussinesq.md",
-    "`IncompressibleModel`" => [
-        "Incompressible model" => "physics/incompressible_model.md",
+    "`NonhydrostaticModel`" => [
+        "Nonhydrostatic model" => "physics/nonhydrostatic_model.md",
         ],
     "`HydrostaticFreeSurfaceModel`" => [
         "Hydrostatic model with a free surface" => "physics/hydrostatic_free_surface_model.md"

docs/src/appendix/fractional_step.md

@@ -1,14 +1,14 @@
 # Fractional step method
 
-In some models (e.g., `IncompressibleModel` or `HydrostaticFreeSurfaceModel`) solving the momentum 
+In some models (e.g., `NonhydrostaticModel` or `HydrostaticFreeSurfaceModel`) solving the momentum 
 coupled with the continuity equation can be cumbersome so instead we employ a fractional step 
 method. To approximate the solution of the coupled system we first solve an approximation to 
 the discretized momentum equation for an intermediate velocity field ``\boldsymbol{v}^\star`` 
 without worrying about satisfying the incompressibility constraint. We then project ``\boldsymbol{v}^\star`` 
 onto the space of divergence-free velocity fields to obtain a value for ``\boldsymbol{v}^{n+1}`` 
 that satisfies continuity.
 
-For example, for the `IncompressibleModel`, if we ignore the background velocity fields and the
+For example, for the `NonhydrostaticModel`, if we ignore the background velocity fields and the
 surface waves, we thus discretize the momentum equation as
 ```math
   \frac{\boldsymbol{v}^\star - \boldsymbol{v}^n}{\Delta t}

docs/src/appendix/library.md

@@ -166,7 +166,7 @@ Modules = [Oceananigans.Models]
 Private = false
 Pages   = [
     "Models/Models.jl",
-    "Models/IncompressibleModels/incompressible_model.jl",
+    "Models/NonhydrostaticModels/nonhydrostatic_model.jl",
     "Models/HydrostaticFreeSurfaceModels/hydrostatic_free_surface_model.jl",
     "Models/ShallowWaterModels/shallow_water_model.jl"
 ]

docs/src/model_setup/background_fields.md

@@ -48,7 +48,7 @@ U(x, y, z, t) = 0.2 * z
 
 grid = RegularRectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1))
 
-model = IncompressibleModel(grid = grid, background_fields = (u=U,))
+model = NonhydrostaticModel(grid = grid, background_fields = (u=U,))
 
 model.background_fields.velocities.u
 
@@ -61,7 +61,7 @@ FunctionField located at (Face, Center, Center)
 ```
 
 `BackgroundField`s are specified by passing them to the kwarg `background_fields`
-in the `IncompressibleModel` constructor. The kwarg `background_fields` expects
+in the `NonhydrostaticModel` constructor. The kwarg `background_fields` expects
 a `NamedTuple` of fields, which are internally sorted into `velocities` and `tracers`,
 wrapped in `FunctionField`s, and assigned their appropriate locations.
 
@@ -85,12 +85,12 @@ BackgroundField{typeof(B), NamedTuple{(:α, :N, :f), Tuple{Float64, Float64, Flo
 └── parameters: (α = 3.14, N = 1.0, f = 0.1)
 ```
 
-When inserted into `IncompressibleModel`, we get out
+When inserted into `NonhydrostaticModel`, we get out
 
 ```jldoctest moar_background
 grid = RegularRectilinearGrid(size=(1, 1, 1), extent=(1, 1, 1))
 
-model = IncompressibleModel(grid = grid, background_fields = (u=U_field, b=B_field),
+model = NonhydrostaticModel(grid = grid, background_fields = (u=U_field, b=B_field),
                             tracers=:b, buoyancy=BuoyancyTracer())
 
 model.background_fields.tracers.b