Improve mission statement and description in README

[glwagner]

This PR tries to clarify the README statement about the motivation for ClimaOcean as a software package separate from Oceananigans.

I included a "hello world" code snippet to illustrate how ClimaOcean extends Oceananigans:

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)

[glwagner]

@tapios @Sbozzolo criticism welcome!

[tapios]

This is fine as far as it goes. However, the central issue is that we, collectively as CliMA, agreed on a naming convention for models about 6 years ago, to have ClimaAtmos, ClimaLand, ClimaOcean etc. Oceananigans went its own way, and now we are going through Cirque-du-Soleil worthy contortions to rectify this. This remains hard to understand or appreciate by outside users. Let's talk about it when we see each other.

[glwagner]

Here's the figure we get from this simulation

[glwagner]

now we are going through Cirque-du-Soleil worthy contortions to rectify this

The organization of software is logical. If changing the names benefits us, others, or the world, we can consider it.

[tapios]

What makes this hard to understand is that Oceananigans is advertised as a "fast and friendly ... ocean model", and entire ocean simulations are conducted with it and have been published. This contrasts, e.g., with ClimaCore, which just provides a set of operators to assemble an atmosphere model, but no atmosphere model in itself. Now saying that Oceananigans is for "ocean-flavored fluid dynamics" and ClimaOcean the real model is just confusing.

[glwagner]

I agree that referring to Oceananigans as “a model” is a miscommunication. Oceananigans is better described as a collection of tools, while ClimaOcean defines something (ocean_simulation) that is more appropriately described as a particular model.

Users can build their own models with Oceananigans, but it's a lot of work to build a realistic model. For example, right now Oceananigans doesn’t even provide a utility for drag laws (just ways to specify boundary fluxes, in a general way). That motivates developing ClimaOcean to encapsulate the major additional specific functionality required for realistic models.

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 1 line in your changes missing coverage. Please review.

Project coverage is 0.00%. Comparing base (08f1b4d) to head (3aba336).

Files with missing lines	Patch %	Lines
src/OceanSeaIceModels/ocean_sea_ice_model.jl	0.00%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #189   +/-   ##
=====================================
  Coverage   0.00%   0.00%           
=====================================
  Files         31      31           
  Lines       1730    1730           
=====================================
  Misses      1730    1730           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Sbozzolo]

For what is worth (and ignoring the issue of branding), the distinction between Oceananigans and ClimaOcean has always made sense to me. The way I understood it is that Oceananigans is a library for building ocean simulations and ClimaOcean a specific application of this library that, given the complexities associated to fully realistic simulations, is its own package. In some ways, ClimaOcean is just a large driver script. Having this split is an relatively easy way to make the model accessible to those who wish to run other types of simulations.

[glwagner]

Here's are some more detailed responses, plus a bit of background that may be helpful:

What makes this hard to understand is that Oceananigans is advertised as a "fast and friendly ... ocean model"

I think this comment is referring to the Gordon Bell submission whose title is sadly sloppy and confusing. We changed the title when @simone-silvestri adapted that work for a paper, but some damage was clearly done.

and entire ocean simulations are conducted with it and have been published.

This is true. But those simulations used prescribed fluxes + restoring rather than a prescribed atmospheric state, substantially simplifying the setup. With prescribed fluxes, a modest Oceananigans script can implement a global ocean simulation.

The script-only strategy is really untenable when using bulk formula + prescribed atmosphere rather than prescribed fluxes. At some point we need to elevate the implementation to a software package and design a user interface for it.

This contrasts, e.g., with ClimaCore, which just provides a set of operators to assemble an atmosphere model, but no atmosphere model in itself.

This is a useful parallel. ClimaCore provides operators. However, users can assemble those operators into a model in a script. ClimaCore does actually provide an example implementation of a shallow water model to illustrate this.

There is an analogy between ClimaAtmos+ClimaCore, and ClimaOcean+Oceananigans. But the two make different choices about how to divide up the functionality: ClimaCore is designed only to support larger applications and end users are directed to ClimaAtmos. Oceananigans, in contrast, targets both end users and larger applications like ClimaOcean. This is no "contortion": it's an intentional, optimized design premised in the benefit users derive from different interfaces for idealized geophysical fluid dynamics vs realistic simulations coupled to an atmosphere.

With languages like Python or Julia we have some freedom to design where a package ends and the user implementation begins. We have an opportunity to make something really far more productive than the tools of the past, but we are also presented with a novel design challenge. Oceananigans' popularity should be interpreted as indicating its successful design, I think.

Now saying that Oceananigans is for "ocean-flavored fluid dynamics" and ClimaOcean the real model is just confusing.

This isn't new --- it's the way we have described Oceananigans since at least December 2020 when it was first announced.

I can see why this could be described as a "contortion" if it were perceived as new to this PR, though.

There is some history regarding the concept of Oceananigans as a library. In September 2020, Trixi was announced on Julia discourse:

https://discourse.julialang.org/t/ann-trixi-jl-a-tree-based-numerical-simulation-framework-for-hyperbolic-pdes/45886

The ensuing discussion praised Trixi's application but comments suggested that Trixi's user interface should be redesigned and modeled after Oceananigans --- a "library" based on scripting, vs a "monolith" based on configuration. It's somewhat hidden by the mists of time but I believe that prior to this, we had not yet explicitly described Oceananigans as a "library". The community provided that interpretation. The authors of Trixi subsequently redesigned their user interface to resemble Oceananigans and have since argued for the benefits of such a design, and we realized that this is the right way to describe what Oceananigans gives to users.

[navidcy]

One minor comment: Sometimes the README uses "ClimaOcean" and some other times "ClimaOcean".

[glwagner]

Better figure:

[navidcy]

so good!