Improve mission statement and description in README

README.md

@@ -44,20 +44,66 @@ 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 package for ocean-flavored fluid dynamics. 
+`ClimaOcean` _specializes_ `Oceananigans` for a specific application: realistic ocean simulations, and coupled ocean + 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`.
+To illustrate how `ClimaOcean` extends `Oceananigans`, we set up a 10-layer near-global model at 1/4 degree 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=10minutes, stop_time=30days)
+run!(simulation)
+```
+
+ClimaOcean's core abstractions are `ocean_simulation` and `ClimaOcean.OceanSeaIceModel`:
+
+* `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](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2023MS004130) for mesoscale-turbulence-resolving simulations.
 
-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).
+* `OceanSeaIceModel` provides a framework for coupled modeling with an ocean component, prescribed atmosphere, and optionally, a sea ice component.
+`OceanSeaIceModel` computes air-sea, air-ice, and ice-ocean fluxes of momentum, heat, and freshwater.
 
+In addition to these core abstractions `ClimaOcean` provides convenience features for wrangling datasets of bathymetry, ocean temperature, salinity, and velocity fields, and prescribed atmospheric states.
 
+`ClimaOcean` is built on top of `Oceananigans` and `ClimaSeaIce`, so it's important that `ClimaOcean` users become proficient with [`Oceananigans`](https://github.com/CliMA/Oceananigans.jl).
+Note that `ClimaOcean` is currently focused on hydrostatic modeling with `Oceananigans`' `HydrostaticFreeSurfaceModel`.
+
+This simulation achieves approximately 8 years per day of wall time on an Nvidia H100.
+Since, for example, `ocean.model` is an Oceananigans.HydrostaticFreeSurfaceModel`, we can leverage all of 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, 1), nan_color=:gray)
+```
+
+which produces
 
+<img width="955" alt="image" src="https://github.com/user-attachments/assets/10f338ee-d873-4a99-ae03-ef8cc8797e81">

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,