Documentation 2.0

[glwagner]

This issue describes an overhaul / refactoring of the "Model setup" part of the documentation. We've noticed that while our examples and docstrings seem to be useful, the "model setup" is less so, and also leaves out a lot of information necessary for running more complex simulations.

What we have now

The basic idea is to flatten the current structure a bit. Right now it reads:

- Home
- Quick start
- Examples > 
- Physics > 
- Numerical implementation > 
- Model setup > 
- <etc>

What we propose

We propose to create top-level sections for important concepts such as Grids, Fields, Simulations etc. Then less important details would be subsumed into the Models section (which would overlap strongly with the current Model setup section).

Here's an outline:

- Home
- Quick start
- Examples >
- Grids, architectures, and number types
- Fields and operations
- Models
    - Setting initial conditions
    - Tracers
    - Advection schemes
    - Turbulence closures
    - Buoyancy models and equations of state
    - Rotation and Coriolis forces
    - Turbulence closures
    - Forcing functions
    - Background fields
    - Lagrangian particles
    - Clocks
- Simulations
    - Callbacks
    - Output writers
    - Checkpointing and picking up from a checkpoint
- Physics > 
- Numerical implementation > 
- <etc>

The ordering of subjects is carefully chosen here, so please comment on that if you think it should be changed.

To do this incrementally, I will open a PR that adds the Grids and Fields sections. Then we can build the Models section incrementally by porting material from Model setup. While we are working I will add the qualifer Model setup (legacy).

Related issues:

• Simulation tips may be a little misleading #3594
• Benchmarks in Docs & README #3166
• Proposed enhancements/changes in Docs #2448
• Adding a "Why Julia?" and Mission/Goals section on the Documentation  #2308
• Document the fact that you can pass a Tuple as closure to models #1879
• Update Coord system and Notation page in docs #1779
• Documenting advection schemes #1318
• Document how the pressure solver and fractional step method describe pressure gradients on boundaries #1232

cc @simone-silvestri @seamanticscience @sandreza @rafferrari @navidcy @siddharthabishnu

[glwagner]

Here are some thoughts for the grid and fields tutorial:

Grids tutorial

1. Basic information: domains, resolution, architectures, number types
2. First example: equally-spaced RectilinearGrid.
   • meaning of the keyword arguments and different options
   • emphasize explaining topology
   • emphasize explaining architecture: CPU, GPU, distributed
3. Second example: single column grid with vertical stretching via vector
4. Third example: two-dimensional grid (short)
5. Fourth example: channel grid with function-specified y and z
   • Explain how to use functions to build a grid
   • Intro to some helper functions: yspacing, ynodes, etc.
6. Fifth example: LatitudeLongitudeGrid with equal spacing
   • Explain different keyword args
   • Explain that only longitude can be periodic
7. Sixth example: LatitudeLongitudeGrid with stretched latitude

Q: should we show tripolar grid / other examples with OrthogonalSphericalShellGrid? (At the very least we should reference this.)

Fields tutorial

1. Explain the purpose of Field: data structure, plus infrastructure for building expression trees
2. Field basics
   • The staggered grid, Field locations
   • Field size + data, staggered nodes, staggered spacings
3. AbstractOperations and expression trees
   • The concept of a lazy operator
   • Arithmetic and derivatives
   • Difference between a Field and Operation
   • KernelFunctionOperation
   • what else?
4. Averaging, intergrals, and reduced fields

What else?

@navidcy @simone-silvestri

[siddharthabishnu]

1. purpose of Field: data structure, plus infrastructure for building expression trees

2. Field basics

   • The staggered grid, Field locations
   • Field size + data, staggered nodes, staggered spacings

3. AbstractOperations and expression trees

   • The concept of a lazy operator
   • Arithmetic and derivatives
   • Difference between a Field and Operation
   • KernelFunctionOperation
   • what else?

4. Averaging, intergrals, and reduced fields

What else?

@navidcy @simone-silvestri

Visualization always helps, so I recommend adding plots of various grid types (periodic, non-periodic, stretched, etc.) directly below the corresponding code snippets that generate them. Additionally, it would be nice to illustrate how to access the different components of Fields and the output of abstract operations with code snippets.

[francispoulin]

I vote yes to including tripolar.

[glwagner]

I think we should also have a tutorial for NonhydrostaticModel. We can use that to also discuss the basics of incompressible flow; for example why set! can produce unexpected behavior when the divergence is projected out of a velocity field. This is being discussed on #3941.