Make the driver optional and provide entry points for composing ClimaAtmos simulations in Julia scripts Part I: AtmosGrids

docs/make.jl

@@ -25,6 +25,7 @@ makedocs(;
         "Home" => "index.md",
         "Installation instructions" => "installation_instructions.md",
         "Contributor Guide" => "contributor_guide.md",
+        "Performing Simulations" => "atmos_simulations.md",
         "Equations" => "equations.md",
         "EDMF Equations" => "edmf_equations.md",
         "Diagnostics" => "diagnostics.md",

docs/src/atmos_simulations.md

@@ -0,0 +1,61 @@
+# Performing a `ClimaAtmos` simulation
+
+`ClimaAtmos` supports a script-based interface. With this interface, simulations
+are defined in a Julia script which uses `ClimaAtmos` as a library. Simulation
+scripts can also contain post-processing and visualization.
+
+## The computational grid
+
+One of the first step in performing a simulation is defining the computational
+grid. `ClimaAtmos` comes with a variety of pre-defined grids that are commonly
+used in the field:
+
+- `StretchedColumnGrid`, a single column (1D) domain with non-uniform resolution
+  (higher resolution at the bottom of the column). The variant with constant
+  resolution is called `UniformColumnGrid`. Columns can only be run on
+  single-threaded simulations.
+- `VerticallyStretchedBoxGrid`, a periodic box with columns (1D) domain with
+  non-uniform resolution in the vertical direction (higher resolution at the
+  bottom of the column). The variant with vertically uniform resolution is
+  `VerticallyUniformBoxGrid`. Given that `VerticallyStretchedBoxGrid` is a
+  commonly used domain, we also provide an alias `Box` for it.
+- `VerticallyStretchedSphereGrid`, a equiangular cubed sphere with columns (1D)
+  domain with non-uniform resolution in the vertical direction (higher
+  resolution at the bottom of the column). The variant with vertically uniform
+  resolution is `VerticallyUniformSphereGrid`. Given that
+  `VerticallyStretchedSphereGrid` is a commonly used domain, we also provide an
+  alias `Sphere` for it.
+- `VerticallyStretchedPlaneGrid`, a period linear domain with columns (1D)
+  domain with non-uniform resolution in the vertical direction (higher
+  resolution at the bottom of the column). The variant with vertically uniform
+  resolution is `VerticallyUniformPlaneGrid`. Given that
+  `VerticallyStretchedPlaneGrid` is a commonly used domain, we also provide an
+  alias `Plane` for it.
+
+All the cases, except for the `ColumnGrid` and `PlaneGrid`, support bubble
+corrections by passing `enable_bubble` to the constructor.
+
+By convention, all the `AbstractAtmosGrid`s in `ClimaAtmos` have a name that
+ends in `Grid`.
+
+`AbstractAtmosGrid`s support a variety of features. For instance, to see an overview of
+the computational grid:
+```julia
+println(summary(column)) # =>
+# Grid: UniformColumnGrid
+# Number of elements: 10
+# Height: 30000.0 meters
+# Grid stretching: Uniform
+```
+
+Users interested in adding new grids can do so by defining a new concrete
+subtype `MyGrid` of the abstract `AbstractAtmosGrid` type. The only requirement
+for `MyGrid` is that it has to have at least two fields: `center_space` and
+`face_space`, which are `ClimaCore.Spaces` for the center and the face of the
+cells respectively. We refer users to the `ClimaCore` documentation to learn
+more about the notion of `Spaces`.
+
+Developers are encouraged to also define a `Base.summary` method.
+
+
+

src/ClimaAtmos.jl

@@ -6,7 +6,6 @@ include(joinpath("parameters", "Parameters.jl"))
 import .Parameters as CAP
 
 include(joinpath("utils", "abbreviations.jl"))
-include(joinpath("utils", "common_spaces.jl"))
 include(joinpath("solver", "types.jl"))
 include(joinpath("solver", "cli_options.jl"))
 include(joinpath("utils", "utilities.jl"))
@@ -113,6 +112,9 @@ include(joinpath("callbacks", "callbacks.jl"))
 include(joinpath("diagnostics", "Diagnostics.jl"))
 import .Diagnostics as CAD
 
+include(joinpath("simulation", "AtmosGrids.jl"))
+import .Grid as CAG
+
 include(joinpath("solver", "model_getters.jl")) # high-level (using parsed_args) model getters
 include(joinpath("time_stepper", "time_stepper.jl"))
 include(joinpath("solver", "type_getters.jl"))

src/simulation/AtmosGrids.jl

@@ -0,0 +1,43 @@
+# AbstractAtmosGrids.jl
+#
+# In this file we define an abstract type AbstractAtmosGrid which describes the
+# computational domain over which the simulation is run. We provide definitions of concrete
+# AbstractAtmosGrids commonly used in simulations.
+
+module Grid
+
+import ClimaComms
+import ClimaCore: Domains, Geometry, Meshes, Spaces, Topologies
+
+"""
+    AbstractAtmosGrid
+
+
+Computational domain over which the simulation is run. Thin wrapper around two
+`ClimaCore.Space`s, one the cell centers and one for the cell faces, and possibly other
+general information and parameters related to the given grid.
+
+"""
+abstract type AbstractAtmosGrid end
+
+"""
+    float_type(grid)
+
+
+Return the floating-point type associated with the given `grid`.
+
+"""
+float_type(grid::AbstractAtmosGrid) = Spaces.undertype(grid.center_space)
+
+"""
+    context(grid)
+
+
+Return the context of the computational device associated with the given `grid`.
+
+"""
+context(grid::AbstractAtmosGrid) = ClimaComms.context(grid.center_space)
+
+include("atmos_grids.jl")
+
+end