Reorganizing examples in the docs

[tomchor]

As pointed out in https://github.com/CliMA/Oceananigans.jl/issues/2309 the examples are taking too long to build, which isn't good. One option is already pointed out in https://github.com/CliMA/Oceananigans.jl/issues/2309, but another one is to decrease the amount of examples.

Examples "Convecting Plankton", "Ocean wind mixing and convection" and "Langmuir turbulence" are pretty similar and could probably be combined if not into one, maybe into two examples.

What do people think about that?

This is relevant to https://github.com/CliMA/Oceananigans.jl/pull/1498, where I'm hoping to add another example to the list...

[glwagner]

@tomchor do you mind if I generalize this issue to talk about refactoring the examples in general?

Here are my thoughts:

1. I agree we should combine Langmuir turbulence and Ocean wind mixing and convection. I think we should implement one LES example with all bells and whistles: surface waves, wind forcing and buoyancy forcing, temperature/salinity, and potentially also a nonlinear equation of state.

2. I think we should keep convecting plankton and continue to develop that as a pedagogical example for both time-dependent boundary conditions and to illustrate Oceananigans' potential for chemistry / biology modeling via nonlinear forcing functions.

3. I think we should convert the Eady turbulence example to something that uses the hydrostatic model with bathymetry (perhaps some baroclinic instability example with bathymetry).

4. We should get rid of the geostrophic adjustment example.

5. We need an example on LatitudeLongitudeGrid.

I also think we should generate rough timings for all the examples so we understand which ones are costing us the most.

[francispoulin]

I like @glwagner 's suggestions.

One question: if we remove examples can they still reside in tests of somewhere else where people can dig them up if they want to see them or will they disappear?

[glwagner]

I like @glwagner 's suggestions.

One question: if we remove examples can they still reside in tests of somewhere else where people can dig them up if they want to see them or will they disappear?

That's a great question, since there are really two points at stake here and there's more than one way to provide "examples" to users. In any case, providing "assured" examples required testing. That's perhaps why we're hesitant to advertise the huge amount of code in validation as a resource for users. It is a resource, but only if you know what you're doing, because the scripts often go stale and we don't have the mojo to test them all in CI right now.

"Examples" are scripts that we'd like to offer to users as guaranteed-to-work pieces of code to get them started.

Right now, we build all of our examples with Documenter.jl. This both tests that the examples work correctly, and also allows users to browse the examples in html (pretty sweet). But currently (and just because we haven't devoted time to cracking the problem) this means we have limited computational resources for examples.

But another possible solution is to test examples in CI without piping them through documenter. Those scripts would then be available for viewing on github (and we can link to them in the docs); it's just that we wouldn't get the pretty markdown / images / movies. If we don't use Documenter then we can run these tests like any others, and also test examples for GPU.

We currently test just one script this way, namely the stratified couette flow validation test:

https://github.com/CliMA/Oceananigans.jl/blob/e796a5de99e791466ef43ab1ed8628b4c4d62f64/test/test_validation.jl#L13-L27

[tomchor]

We can apply 4 pretty immediately and start speeding up things if everyone agrees.

@glwagner I'm curious as to why you think we should remove that example

Also, do we need the diffusion example? One might argue that the 2D turbulence example is almost as simple and introductory, while being more illustrative of ocean simulations.

[glwagner]

I think we want one 1D example. But maybe we should do a column model with CATKE rather than a random diffusion example.

@glwagner I'm curious as to why you think we should remove that example

I think it has only limited utility so that doesn't justify the cost of an example. It used to be just about the only interesting thing the hydrostatic model could do. Now the hydrostatic model can do much more.

[navidcy]

As part of the examples refactor I'm wondering whether we should we also change some of the examples to use a Makie variant for plotting?

[glwagner]

As part of the examples refactor I'm wondering whether we should we also change some of the examples to use a Makie variant for plotting?

I agree Makie is way better. Can we do animations too though? I'll explore. Sadly tartarus is not open CL enabled.

[navidcy]

A movie was produced!

https://github.com/CliMA/OceananigansDocumentation/blob/gh-pages/previews/PR2333/generated/baroclinic_adjustment.mp4

[francispoulin]

And I'm happy to have seen it!

[navidcy]

I'm reopening since #2333 didn't really make the building of the docs faster.

[glwagner]

That makes sense --- didn't we add a new plotting library? We probably need to use just one in all examples for compilation reasons.

[glwagner]

I'm closing this issue because I'm judging that it's not of current, timely relevance to Oceananigans development. If you would like to make it a higher priority or if you think the issue was closed in error please feel free to re-open.