Improve mission statement and description in README (#189)

* Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Use MinimumTemperatureSeaIce as default * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md Co-authored-by: Navid C. Constantinou <[email protected]> * Update README.md Co-authored-by: Navid C. Constantinou <[email protected]> * Update README.md Co-authored-by: Navid C. Constantinou <[email protected]> * Update README.md Co-authored-by: Navid C. Constantinou <[email protected]> * Update README.md Co-authored-by: Navid C. Constantinou <[email protected]> * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * ClimaOcean is registered * Update README.md * Update README.md * Update README.md --------- Co-authored-by: Navid C. Constantinou <[email protected]>
CliMA · Oct 23, 2024 · d56812f · d56812f
1 parent 887bc46
commit d56812f
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
 <!-- description -->
 <p align="center">
-  <strong>🌎 Tools for building realistic ocean-only and coupled ocean + sea-ice simulations based on
+  <strong>🌎 A framework for realistic ocean-only and coupled ocean + sea-ice simulations driven by prescribed atmospheres and based on
           <a href="https://github.com/CliMA/Oceananigans.jl">Oceananigans</a>
           and <a href="https://github.com/CliMA/ClimaSeaIce.jl">ClimaSeaIce</a>.</strong>
 </p>
@@ -29,12 +29,12 @@
 
 ## Installation
 
-To install from a Julia REPL:
+ClimaOcean is a registered package. To install from a Julia REPL:
 
 ```julia
 julia> using Pkg
 
-julia> Pkg.add(url="https://github.com/CliMA/ClimaOcean.jl.git")
+julia> Pkg.add("ClimaOcean")
 
 julia> Pkg.instantiate()
 ```
@@ -44,20 +44,67 @@ For more information, see the [documentation for `Pkg.jl`](https://pkgdocs.julia
 
 ## Why? What's the difference between ClimaOcean and [Oceananigans](https://github.com/CliMA/Oceananigans.jl)?
 
-`ClimaOcean` is for _realistic_ ocean-only and ocean + sea-ice simulations, in a region of the ocean ("regional") or covering the whole Earth.
-[Oceananigans](https://github.com/CliMA/Oceananigans.jl) is a lower-level package for simulating the dynamics of ocean-flavored fluids that can be used for _both_ idealized problems and, given enough effort, realistic problems as well.
-While "idealized" problems come in multifarious shapes and sizes, "realistic" problems tend to be more narrowly defined, and require
+Oceananigans is a general-purpose library for ocean-flavored fluid dynamics. 
+ClimaOcean implements a framework for driving realistic Oceananigans simulations with prescribed atmospheres, and coupling them to prognostic sea ice simulations.
 
-* Simulating the evolution of specific tracers: ocean temperature (or heat), salinity, and sometimes ocean biogeochemistry.
-* Computing fluxes of heat, water vapor, momentum, and trace gases between the ocean and atmosphere (where the atmospheric state is either prescribed or "coupled" and itself evolving) -- and also between sea ice and the atmosphere, when a sea ice component is included.
-* Initializing the ocean model with realistic initial conditions derived from observations of the ocean, and realistic bathymetry.
-
-`ClimaOcean` leverages `Oceananigans` and `ClimaSeaIce` to build `OceanSeaIceModel`s capable of meeting these requirements to simulate the dynamics of specific regions of the Earth's ocean.
-So if you're using `ClimaOcean`, it's a very good idea to become proficient in [`Oceananigans`](https://github.com/CliMA/Oceananigans.jl) as well.
-Note also that, at least at the moment, `ClimaOcean` is focused on hydrostatic modeling with `Oceananigans`' `HydrostaticFreeSurfaceModel`.
+### A core abstraction: `ClimaOcean.OceanSeaIceModel`
 
-In summary, if you're interested in realistic, hydrostatic regional or global simulations you may find `ClimaOcean` useful.
-Otherwise, you can stick with [Oceananigans](https://github.com/CliMA/Oceananigans.jl).
+Our system for realistic modeling is anchored by `ClimaOcean.OceanSeaIceModel`, which encapsulates the ocean simulation, sea ice simulation, prescribed atmospheric state, and specifies how the three communicate.
+To illustrate how `OceanSeaIceModel` works we set up a simulation on a grid with 10 vertical levels and 1/4-degree horizontal resolution:
 
-
+```julia
+using Oceananigans
+using Oceananigans.Units
+using Dates, CFTime
+import ClimaOcean
+
+arch = GPU()
+grid = LatitudeLongitudeGrid(arch,
+                             size = (1440, 560, 10),
+                             halo = (7, 7, 7),
+                             longitude = (0, 360),
+                             latitude = (-70, 70),
+                             z = (-3000, 0))
+
+bathymetry = ClimaOcean.regrid_bathymetry(grid) # builds gridded bathymetry based on ETOPO1
+grid = ImmersedBoundaryGrid(grid, GridFittedBottom(bathymetry))
+
+# Build an ocean simulation initialized to the ECCO state estimate on Jan 1, 1993
+ocean = ClimaOcean.ocean_simulation(grid)
+date  = DateTimeProlepticGregorian(1993, 1, 1)
+set!(ocean.model, T = ClimaOcean.ECCOMetadata(:temperature; date),
+                  S = ClimaOcean.ECCOMetadata(:salinity; date))
+
+# Build and run an OceanSeaIceModel (with no sea ice component) forced by JRA55 reanalysis
+atmosphere = ClimaOcean.JRA55_prescribed_atmosphere(arch)
+coupled_model = ClimaOcean.OceanSeaIceModel(ocean; atmosphere)
+simulation = Simulation(coupled_model, Δt=5minutes, stop_time=30days)
+run!(simulation)
+```
+
+The simulation above achieves approximately 8 simulated years per day of wall time on an Nvidia H100 GPU.
+
+Since `ocean.model` is an `Oceananigans.HydrostaticFreeSurfaceModel`, we can leverage `Oceananigans` features in our scripts.
+For example, to plot the surface speed at the end of the simulation we write
+
+```julia
+u, v, w = ocean.model.velocities
+speed = Field(sqrt(u^2 + v^2))
+compute!(speed)
+
+using GLMakie
+heatmap(view(speed, :, :, ocean.model.grid.Nz), colorrange=(0, 0.5), colormap=:magma, nan_color=:lightgray)
+```
+
+which produces
+
+<img width="1590" alt="image" src="https://github.com/user-attachments/assets/4c484b93-38fe-4840-bf7d-63a3a59d29e1">
+
+### Additional features: a utility for `ocean_simulation`s and data wrangling
+
+A second core abstraction in ClimaOcean is `ocean_simulation`. `ocean_simulation` configures an Oceananigans model for realistic simulations including temperature and salinity, the TEOS-10 equation of state, boundary conditions to store computed air-sea fluxes, the automatically-calibrated turbulence closure `CATKEVerticalDiffusivity`, and the [`WENOVectorInvariant` advection scheme](http://doi.org/10.1029/2023MS004130) for mesoscale-turbulence-resolving simulations.
+
+ClimaOcean also provides convenience features for wrangling datasets of bathymetry, ocean temperature, salinity, ocean velocity fields, and prescribed atmospheric states.
 
+ClimaOcean is built on top of Oceananigans and [ClimaSeaIce](https://github.com/CliMA/ClimaSeaIce.jl), so it's important that ClimaOcean users become proficient with [Oceananigans](https://github.com/CliMA/Oceananigans.jl).
+Note that though ClimaOcean is currently focused on hydrostatic modeling with `Oceananigans.HydrostaticFreeSurfaceModel`, realistic nonhydrostatic modeling is also within the scope of this package.
diff --git a/src/OceanSeaIceModels/ocean_sea_ice_model.jl b/src/OceanSeaIceModels/ocean_sea_ice_model.jl
@@ -69,7 +69,7 @@ function heat_capacity(eos::TEOS10EquationOfState{FT}) where FT
     return convert(FT, cₚ⁰)
 end
 
-function OceanSeaIceModel(ocean, sea_ice=nothing;
+function OceanSeaIceModel(ocean, sea_ice=MinimumTemperatureSeaIce();
                           atmosphere = nothing,
                           radiation = nothing,
                           similarity_theory = nothing,