Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
61 changes: 61 additions & 0 deletions docs/src/atmos_simulations.md
Original file line number Diff line number Diff line change
@@ -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.



4 changes: 3 additions & 1 deletion src/ClimaAtmos.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down Expand Up @@ -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"))
Expand Down
43 changes: 43 additions & 0 deletions src/simulation/AtmosGrids.jl
Original file line number Diff line number Diff line change
@@ -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
Loading