From d56812fa4f11985bd32ea68278325a1ac03e45b4 Mon Sep 17 00:00:00 2001 From: "Gregory L. Wagner" Date: Wed, 23 Oct 2024 14:01:20 -0600 Subject: [PATCH] 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 * Update README.md Co-authored-by: Navid C. Constantinou * Update README.md Co-authored-by: Navid C. Constantinou * Update README.md Co-authored-by: Navid C. Constantinou * Update README.md Co-authored-by: Navid C. Constantinou * 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 --- README.md | 79 ++++++++++++++++---- src/OceanSeaIceModels/ocean_sea_ice_model.jl | 2 +- 2 files changed, 64 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index d132b62b..37f9eaab 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

- šŸŒŽ Tools for building realistic ocean-only and coupled ocean + sea-ice simulations based on + šŸŒŽ A framework for realistic ocean-only and coupled ocean + sea-ice simulations driven by prescribed atmospheres and based on Oceananigans and ClimaSeaIce.

@@ -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 + +image + +### 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 index b3d7a800..5e125774 100644 --- 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,