Rename Model to IncompressibleModel (#626)

Rename Model to IncompressibleModel

Author: ali-ramadhan

README.md

@@ -82,11 +82,12 @@ At this time, updating should be done with care, as Oceananigans is under rapid
 **Note**: Oceananigans requires at least Julia v1.1 to run correctly.
 
 ## Running your first model
-Let's initialize a 3D model with 100×100×50 grid points on a 2×2×1 km domain and simulate it for 10 time steps using steps of 60 seconds each (for a total of 10 minutes of simulation time).
+Let's initialize a 3D model with 100×100×50 grid points on a 2×2×1 km domain and simulate it for 1 time step of 60 seconds.
 ```julia
 using Oceananigans
-model = Model(grid = RegularCartesianGrid(size=(100, 100, 50), length = (2000, 2000, 1000)))
-time_step!(model; Δt=60, Nt=10)
+grid = RegularCartesianGrid(size=(100, 100, 50), length = (2000, 2000, 1000))
+model = IncompressibleModel(grid=grid)
+time_step!(model, 60)
 ```
 You just simulated what might have been a 3D patch of ocean, it's that easy! It was a still lifeless ocean so nothing interesting happened but now you can add interesting dynamics and visualize the output.
 
@@ -97,9 +98,11 @@ using Oceananigans
 
 # We'll set up a 2D model with an xz-slice so there's only 1 grid point in y
 # and use an artificially high viscosity ν and diffusivity κ.
-model = Model(architecture = CPU(),
-                      grid = RegularCartesianGrid(size=(128, 128, 128), length=(2000, 2000, 2000)),
-                   closure = ConstantIsotropicDiffusivity(ν=4e-2, κ=4e-2))
+model = IncompressibleModel(
+    architecture = CPU(),
+            grid = RegularCartesianGrid(size=(128, 128, 128), length=(2000, 2000, 2000)),
+         closure = ConstantIsotropicDiffusivity(ν=4e-2, κ=4e-2)
+)
 
 # Set a temperature perturbation with a Gaussian profile located at the center
 # of the vertical slice. This will create a buoyant thermal bubble that will
@@ -109,7 +112,8 @@ x₀, z₀ = Lx/2, Lz/2
 T₀(x, y, z) = 20 + 0.01 * exp(-100 * ((x - x₀)^2 + (z - z₀)^2) / (Lx^2 + Lz^2))
 set!(model; T=T₀)
 
-time_step!(model; Δt=10, Nt=5000)
+simulation = Simulation(model, Δt=10, stop_iteration=5000)
+run!(simulation)
 ```
 By changing `arch=CPU()` to `arch=GPU()`, the example will run on an Nvidia GPU!
 

src/Diagnostics/cfl.jl

@@ -34,7 +34,7 @@ for advection across a cell.
 Example
 =======
 ```julia
-julia> model = Model(grid=RegularCartesianGrid(size=(16, 16, 16), length=(8, 8, 8)));
+julia> model = IncompressibleModel(grid=RegularCartesianGrid(size=(16, 16, 16), length=(8, 8, 8)));
 
 julia> cfl = AdvectiveCFL(1.0);
 
@@ -59,7 +59,7 @@ returned.
 Example
 =======
 ```julia
-julia> model = Model(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
+julia> model = IncompressibleModel(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
 
 julia> dcfl = DiffusiveCFL(0.1);
 

src/Diagnostics/field_maximum.jl

@@ -7,7 +7,7 @@ element-wise to `field`.
 Examples
 =======
 ```julia
-julia> model = Model(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
+julia> model = IncompressibleModel(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
 
 julia> max_abs_u = FieldMaximum(abs, model.velocities.u);
 

src/Diagnostics/time_series.jl

@@ -19,7 +19,7 @@ A `TimeSeries` `Diagnostic` that records a time series of `diagnostic(model)`.
 Example
 =======
 ```julia
-julia> model = Model(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
+julia> model = IncompressibleModel(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1)));
 
 julia> max_u = TimeSeries(FieldMaximum(abs, model.velocities.u), model; frequency=1)
 
@@ -55,7 +55,7 @@ A `TimeSeries` `Diagnostic` that records a `NamedTuple` of time series of
 Example
 =======
 ```julia
-julia> model = Model(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1))); Δt = 1.0;
+julia> model = IncompressibleModel(grid=RegularCartesianGrid(size=(16, 16, 16), length=(1, 1, 1))); Δt = 1.0;
 
 julia> cfl = TimeSeries((adv=AdvectiveCFL(Δt), diff=DiffusiveCFL(Δt)), model; frequency=1);
 

src/Fields/set!.jl

@@ -14,7 +14,7 @@ a function with arguments `(x, y, z)`, or any data type for which a
 Example
 =======
 ```julia
-model = Model(grid=RegularCartesianGrid(size=(32, 32, 32), length=(1, 1, 1))
+model = IncompressibleModel(grid=RegularCartesianGrid(size=(32, 32, 32), length=(1, 1, 1))
 
 # Set u to a parabolic function of z, v to random numbers damped
 # at top and bottom, and T to some silly array of half zeros,

src/Forcing/model_forcing.jl

@@ -11,7 +11,7 @@ Example
 
 julia> u_forcing = SimpleForcing((x, y, z, t) -> exp(z) * cos(t))
 
-julia> model = Model(forcing=ModelForcing(u=u_forcing))
+julia> model = IncompressibleModel(forcing=ModelForcing(u=u_forcing))
 """
 function ModelForcing(; u=zeroforcing, v=zeroforcing, w=zeroforcing, tracer_forcings...)
     u = at_location((Face, Cell, Cell), u)

src/Models/Models.jl

@@ -1,6 +1,6 @@
 module Models
 
-export Model, ChannelModel, NonDimensionalModel, Clock
+export IncompressibleModel, NonDimensionalModel, Clock
 
 using Oceananigans.Architectures
 using Oceananigans.Fields
@@ -20,7 +20,7 @@ Abstract supertype for models.
 abstract type AbstractModel end
 
 include("clock.jl")
-include("model.jl")
+include("incompressible_model.jl")
 include("non_dimensional_model.jl")
 include("show_models.jl")
 

src/Models/model.jl renamed to src/Models/incompressible_model.jl

@@ -6,8 +6,8 @@ using Oceananigans.Architectures: AbstractArchitecture
 using Oceananigans.Buoyancy: validate_buoyancy
 using Oceananigans.TurbulenceClosures: ν₀, κ₀, with_tracers
 
-mutable struct Model{TS, E, A<:AbstractArchitecture, G, T, B, R, SW, U, C, Φ, F,
-                     BCS, S, K, Θ} <: AbstractModel
+mutable struct IncompressibleModel{TS, E, A<:AbstractArchitecture, G, T, B, R, SW, U, C, Φ, F,
+                                   BCS, S, K, Θ} <: AbstractModel
 
            architecture :: A         # Computer `Architecture` on which `Model` is run
                    grid :: G         # Grid of physical points on which `Model` is solved
@@ -28,7 +28,7 @@ mutable struct Model{TS, E, A<:AbstractArchitecture, G, T, B, R, SW, U, C, Φ, F
 end
 
 """
-    Model(;
+    IncompressibleModel(;
                    grid,
            architecture = CPU(),
              float_type = Float64,
@@ -48,7 +48,7 @@ end
         pressure_solver = PressureSolver(architecture, grid, PressureBoundaryConditions(boundary_conditions.u))
     )
 
-Construct an `Oceananigans.jl` model on `grid`.
+Construct an incompressible `Oceananigans.jl` model on `grid`.
 
 Keyword arguments
 =================
@@ -63,7 +63,7 @@ Keyword arguments
   or `ModelBoundaryConditions`. See `BoundaryConditions`, `HorizontallyPeriodicSolutionBCs`, and `ChannelSolutionBCs`.
 - `parameters`: User-defined parameters for use in user-defined forcing functions and boundary condition functions.
 """
-function Model(;
+function IncompressibleModel(;
                    grid,
            architecture = CPU(),
              float_type = Float64,
@@ -97,7 +97,7 @@ function Model(;
     closure = with_tracers(tracernames(tracers), closure)
     boundary_conditions = ModelBoundaryConditions(tracernames(tracers), diffusivities, boundary_conditions)
 
-    return Model(architecture, grid, clock, buoyancy, coriolis, surface_waves, velocities, tracers,
-                 pressures, forcing, closure, boundary_conditions, timestepper,
-                 pressure_solver, diffusivities, parameters)
+    return IncompressibleModel(architecture, grid, clock, buoyancy, coriolis, surface_waves,
+                               velocities, tracers, pressures, forcing, closure, boundary_conditions,
+                               timestepper, pressure_solver, diffusivities, parameters)
 end

src/Models/non_dimensional_model.jl

@@ -18,14 +18,14 @@ forcing.
 
 Note that `N`, `L`, and `Re` are required.
 
-Additional `kwargs` are passed to the regular `Model` constructor.
+Additional `kwargs` are passed to the regular `IncompressibleModel` constructor.
 """
 function NonDimensionalModel(; grid, float_type=Float64, Re, Pr=0.7, Ro=Inf,
     buoyancy = BuoyancyTracer(),
     coriolis = FPlane(float_type, f=1/Ro),
      closure = ConstantIsotropicDiffusivity(float_type, ν=1/Re, κ=1/(Pr*Re)),
     kwargs...)
 
-    return Model(; float_type=float_type, grid=grid, closure=closure,
-                   coriolis=coriolis, tracers=(:b,), buoyancy=buoyancy, kwargs...)
+    return IncompressibleModel(; float_type=float_type, grid=grid, closure=closure,
+                               coriolis=coriolis, tracers=(:b,), buoyancy=buoyancy, kwargs...)
 end

src/Models/show_models.jl

@@ -2,8 +2,8 @@ using Oceananigans.Grids: short_show
 using Oceananigans.Utils: prettytime, ordered_dict_show
 
 """Show the innards of a `Model` in the REPL."""
-Base.show(io::IO, model::Model) =
-    print(io, "Oceananigans.Model on a $(typeof(model.architecture)) architecture ",
+Base.show(io::IO, model::IncompressibleModel) =
+    print(io, "Oceananigans.IncompressibleModel on a $(typeof(model.architecture)) architecture ",
         "(time = $(prettytime(model.clock.time)), iteration = $(model.clock.iteration)) \n",
         "├── grid: $(short_show(model.grid))\n",
         "├── tracers: $(tracernames(model.tracers))\n",

src/Oceananigans.jl

@@ -46,7 +46,7 @@ export
     TimeStepWizard, update_Δt!,
 
     # Models
-    Model, ChannelModel, NonDimensionalModel,
+    IncompressibleModel, NonDimensionalModel,
 
     # Simulations
     Simulation, run!,

src/OutputWriters/checkpointer.jl

@@ -125,7 +125,7 @@ function restore_from_checkpoint(filepath; kwargs=Dict())
         end
     end
 
-    model = Model(; kwargs...)
+    model = IncompressibleModel(; kwargs...)
 
     # Now restore fields.
     for p in cps

src/TimeSteppers/adams_bashforth.jl

@@ -31,12 +31,12 @@ end
 #####
 
 """
-    time_step!(model::Model{<:AdamsBashforthTimeStepper}, Δt; euler=false)
+    time_step!(model::IncompressibleModel{<:AdamsBashforthTimeStepper}, Δt; euler=false)
 
 Step forward `model` one time step `Δt` with a 2nd-order Adams-Bashforth method and
 pressure-correction substep. Setting `euler=true` will take a forward Euler time step.
 """
-function time_step!(model::Model{<:AdamsBashforthTimeStepper}, Δt; euler=false)
+function time_step!(model::IncompressibleModel{<:AdamsBashforthTimeStepper}, Δt; euler=false)
     χ = ifelse(euler, convert(eltype(model.grid), -0.5), model.timestepper.χ)
 
     # Convert NamedTuples of Fields to NamedTuples of OffsetArrays

test/regression_tests/ocean_large_eddy_simulation_regression_test.jl

@@ -58,7 +58,7 @@ function run_ocean_large_eddy_simulation_regression_test(arch, closure)
     S_bcs = TracerBoundaryConditions(grid, top = BoundaryCondition(Flux, 5e-8))
 
     # Model instantiation
-    model = Model(
+    model = IncompressibleModel(
              architecture = arch,
                      grid = grid,
                  coriolis = FPlane(f=1e-4),

test/regression_tests/rayleigh_benard_regression_test.jl

@@ -31,7 +31,7 @@ function run_rayleigh_benard_regression_test(arch)
     bbcs = TracerBoundaryConditions(grid,    top = BoundaryCondition(Value, 0.0),
                                           bottom = BoundaryCondition(Value, Δb))
 
-    model = Model(
+    model = IncompressibleModel(
                architecture = arch,
                        grid = grid,
                     closure = ConstantIsotropicDiffusivity(ν=ν, κ=κ),

test/regression_tests/thermal_bubble_regression_test.jl

@@ -5,7 +5,7 @@ function run_thermal_bubble_regression_test(arch)
 
     grid = RegularCartesianGrid(size=(Nx, Ny, Nz), length=(Lx, Ly, Lz))
     closure = ConstantIsotropicDiffusivity(ν=4e-2, κ=4e-2)
-    model = Model(architecture=arch, grid=grid, closure=closure, coriolis=FPlane(f=1e-4))
+    model = IncompressibleModel(architecture=arch, grid=grid, closure=closure, coriolis=FPlane(f=1e-4))
     simulation = Simulation(model, Δt=6, stop_iteration=10)
 
     model.tracers.T.data.parent .= 9.85

test/test_abstract_operations.jl

@@ -354,7 +354,7 @@ end
             for FT in float_types
                 @info "    Testing computation of abstract operations [$FT, $(typeof(arch))]..."
 
-                model = Model(
+                model = IncompressibleModel(
                     architecture = arch,
                       float_type = FT,
                             grid = RegularCartesianGrid(FT, size=(16, 16, 16), length=(1, 1, 1))

test/test_boundary_conditions.jl

@@ -13,11 +13,11 @@ function test_z_boundary_condition_simple(arch, FT, fldname, bctype, bc, Nx, Ny)
     fieldbcs = TracerBoundaryConditions(grid, top=bc)
     modelbcs = SolutionBoundaryConditions(grid; Dict(fldname=>fieldbcs)...)
 
-    model = Model(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
 
     time_step!(model, 1e-16, euler=true)
 
-    return typeof(model) <: Model
+    return model isa IncompressibleModel
 end
 
 function test_z_boundary_condition_top_bottom_alias(arch, FT, fldname)
@@ -29,7 +29,7 @@ function test_z_boundary_condition_top_bottom_alias(arch, FT, fldname)
     fieldbcs = TracerBoundaryConditions(grid, top=top_bc, bottom=bottom_bc)
     modelbcs = SolutionBoundaryConditions(grid; Dict(fldname=>fieldbcs)...)
 
-    model = Model(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
 
     bcs = getfield(model.boundary_conditions.solution, fldname)
 
@@ -53,7 +53,7 @@ function test_z_boundary_condition_array(arch, FT, fldname)
     fieldbcs = TracerBoundaryConditions(grid, top=value_bc)
     modelbcs = SolutionBoundaryConditions(grid; Dict(fldname=>fieldbcs)...)
 
-    model = Model(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT, boundary_conditions=modelbcs)
 
     bcs = getfield(model.boundary_conditions.solution, fldname)
 
@@ -72,8 +72,8 @@ function test_flux_budget(arch, FT, fldname)
     modelbcs = SolutionBoundaryConditions(grid; Dict(fldname=>fieldbcs)...)
 
     closure = ConstantIsotropicDiffusivity(FT, ν=κ, κ=κ)
-    model = Model(grid=grid, closure=closure, architecture=arch,
-                  float_type=FT, buoyancy=nothing, boundary_conditions=modelbcs)
+    model = IncompressibleModel(grid=grid, closure=closure, architecture=arch,
+                                float_type=FT, buoyancy=nothing, boundary_conditions=modelbcs)
 
     if fldname ∈ (:u, :v, :w)
         field = getfield(model.velocities, fldname)
@@ -121,8 +121,9 @@ function fluxes_with_diffusivity_boundary_conditions_are_correct(arch, FT)
     model_bcs = ModelBoundaryConditions(tracer_names, diffusivities, solution_bcs;
                                         diffusivities=diffusivities_bcs)
 
-    model = Model(grid=grid, architecture=arch, float_type=FT, tracers=tracer_names, buoyancy=BuoyancyTracer(),
-                  closure=closure, diffusivities=diffusivities, boundary_conditions=model_bcs)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT, tracers=tracer_names,
+                                buoyancy=BuoyancyTracer(), closure=closure, diffusivities=diffusivities,
+                                boundary_conditions=model_bcs)
 
     b₀(x, y, z) = z * bz
     set!(model, b=b₀)

test/test_diagnostics.jl

@@ -1,6 +1,6 @@
 function horizontal_average_is_correct(arch, FT)
     grid = RegularCartesianGrid(size=(16, 16, 16), length=(100, 100, 100))
-    model = Model(grid=grid, architecture=arch, float_type=FT)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT)
 
     T₀(x, y, z) = 20 + 0.01*z
     set!(model; T=T₀)
@@ -14,7 +14,7 @@ end
 
 function nan_checker_aborts_simulation(arch, FT)
     grid=RegularCartesianGrid(size=(16, 16, 2), length=(1, 1, 1))
-    model = Model(grid=grid, architecture=arch, float_type=FT)
+    model = IncompressibleModel(grid=grid, architecture=arch, float_type=FT)
 
     # It checks for NaNs in w by default.
     nc = NaNChecker(model; frequency=1, fields=Dict(:w => model.velocities.w.data.parent))
@@ -26,14 +26,16 @@ function nan_checker_aborts_simulation(arch, FT)
 end
 
 TestModel(::GPU, FT, ν=1.0, Δx=0.5) =
-    Model(grid = RegularCartesianGrid(FT, size=(16, 16, 16), length=(16Δx, 16Δx, 16Δx)),
+    IncompressibleModel(
+          grid = RegularCartesianGrid(FT, size=(16, 16, 16), length=(16Δx, 16Δx, 16Δx)),
        closure = ConstantIsotropicDiffusivity(FT, ν=ν, κ=ν),
   architecture = GPU(),
     float_type = FT
 )
 
 TestModel(::CPU, FT, ν=1.0, Δx=0.5) =
-    Model(grid = RegularCartesianGrid(FT, size=(3, 3, 3), length=(3Δx, 3Δx, 3Δx)),
+    IncompressibleModel(
+          grid = RegularCartesianGrid(FT, size=(3, 3, 3), length=(3Δx, 3Δx, 3Δx)),
        closure = ConstantIsotropicDiffusivity(FT, ν=ν, κ=ν),
   architecture = CPU(),
     float_type = FT