Examples in ClimaOcean

[glwagner]

The purpose of this issue is to lay out a rough plan and vision for examples in ClimaOcean.

I think we would like to demonstrate both idealized and realistic use cases for the HydrostaticFreeSurfaceModel here. Note that there isn't much in Oceananigans right now for hydrostatic modeling --- just a simple internal tide example and a baroclinic adjustment. In some ways I think this makes sense. Oceananigans is oriented towards lower-level usage. "Direct" users of Oceananigans are probably more interested in the nonhydrostatic model.

ClimaOcean has a different focus though, which is hydrostatic ocean modeling at relatively large scales, where, typically, small-scale turbulence is parameterized. This class of models is a bit more complicated, most problems have bathymetry, and many problems require computing fluxes via bulk formula and some prescribed atmospheric state.

To generate documentation and examples for this use case is a bit more challenging than what we have in Oceananigans. To solve the problem fully I think we need to be able to run expensive 3D examples on GPUs. We may even want to have examples that run on multiple GPUs, if we can manage that.

To implement this I think we should adapt our documentation to be built and pushed via buildkite. Moreover, we should only build all of the examples infrequently, because they will be expensive --- nightly or weekly. This means that in order to run doctests during CI / every commit, we need to have two pathways for making docs: one cheap pathway with no examples, and no deploydocs, and a second pathway that builds all the examples using GPUs on the caltech cluster and then deploys the documentation from there.

#84 starts down that road. Next we need to implement the separated "doctest docs" and "example docs" pipelines. Once we've done that, we're ready to implement some bigger examples, and that's where the fun starts.

Here's what I propose for a list of examples to start:

1. Realistic single column model with CATKE, forced by bulk formula + JRA55 and initialized to ECCO. This will illustrate a set up where the user can select a date, and the simulation will run from there.
2. One or two 2D problems that illustrate bathymetry plus CATKE. Wind-driven coastal upwelling, tidal sloshing over bathymetry (eg derived from a realistic spectrum)?
3. At least one idealized 3D example with complex bathymetry, but simple non-bulk-formula forcing.
4. At least one "realistic" regional 3D example with real bathymetry and bulk formula forcing.

In addition to those "simulation examples", I think we should also include some "analysis examples" that illustrate how to analyze the data we are presenting. We have some of these already, they just need to be literated and run. For example, an analysis of the JRA55 forcing, the ECCO dataset, and perhaps also an analysis of "climatological fluxes" that uses both ECCO and JRA55.

The analysis examples are important because we want to show users how to inspect the forcing that is being applied to their realistic simulations. We also want to motivate the design of nice abstractions for downloading, working with, and analyzing the data that we use to force our simulations: ECCO and JRA55 now, but probably ERA5, GLORYS, and maybe others in the future.

cc @simone-silvestri @navidcy @rafferrari

[francispoulin]

Would a regional model of a subtropical gyre with realistic bathymetry fit into 3?

I recently got a double gyre example working, very similar to what is in the MITgcm baroclinic gyre example. I thought I would update the oceananigans PR from yields ago but then wonder if this is a better spot for it? The example I have is with simple winds but I imagine we could add realistic winds using JRA55, if people wanted.

@glwagner , happy to chat sometime if you like.

[glwagner]

@francispoulin I think a double gyre with bathymetry could definitely satisfy 3. However we have also discussed a channel-like geometry that has a continental shelf + winds that induce upwelling.

For 3 we have propose simple forcing. So I don't think we want to force that with JRA55. (It's unclear how we would do that, I guess we would have to put the simulation in a particular place in Earth's ocean).

[francispoulin]

The channel-like geometry sounds a lot simpler, and a great idea!

I am not sure what stage it's at but I would be happy to get involved if you are looking for more support.

[glwagner]

You can put together the example in a PR if you like. We haven't started working on it yet.