Docs for zstar vertical coordinate

[simone-silvestri]

This PR adds docs for the derivation of the generalized vertical coordinate equations and their detailed numerical implementation including the formulation we use for a non-linear free surface.

https://clima.github.io/OceananigansDocumentation/previews/PR4588/physics/zstar_vertical_coordinate/

[glwagner]

is there a preview?

[navidcy]

Always, at: https://clima.github.io/OceananigansDocumentation/previews/PR4588/

At the moment there is not much changes tho

[francispoulin]

Always, at: https://clima.github.io/OceananigansDocumentation/previews/PR4588/grids/

At the moment there is not much changes tho

I could not find this page in the physics tabe but found it here, in case others want a quick link.

https://clima.github.io/OceananigansDocumentation/previews/PR4588/physics/zstar_vertical_coordinate/

[navidcy]

My bad! I put the wrong link! Fixed it now!

[navidcy]

given that this section is only relevant for HydrostaticFreeSurfaceModel() perhaps we move it a bit further down in the docs structure?

[navidcy]

@simone-silvestri is this ready to review or are you still working on it? (just asking because it's a Draft PR)

[simone-silvestri]

I am thinking of adding also the momentum equations in vector-invariant form today, and a small code tutorial (probably), then it will be ready for review.

[navidcy]

Cool -- ping me when you are done.

[simone-silvestri]

Ok, I also derived the material derivative of the horizontal velocity in the vector invariant form. All the nomenclature follows very closely the symbols we use in the source code, so it should be very easy to verify the implementation from the docs. I think this is enough for the moment. This PR should be ready to review

[simone-silvestri]

I think I will put off the discretization of the momentum equations in this PR because it probably requires its own section.

[simone-silvestri]

Also the non-linear free surface requires its own section, this is just the vertical coordinate transformation

[glwagner]

I'd like to get rid of the "physics" section of the docs eventually. Can we discuss where this documentation should go?

Note, this is not physics, its numerics.

[simone-silvestri]

Right, maybe it makes more sense to add this section in the numerical implementation section after large eddy simulations? We can probably add a section like large eddy simulations but more about hydrostatic simulations after which we add the vertical coordinates.

[simone-silvestri]

I think this will also be complemented by a section on linear vs non linear free surface which will be similar to the pressure decomposition section that is in numerical implementation

[glwagner]

I would suggest striking the "physics" section, and instead presenting model description and configuration into a single docs section.

Then for numerics, maybe a docs section on "Discretization", where we introduce the staggered grid, second order difference, derivative, and reconstruction, reductions, upwinding and WENO, time-stepping, diffusion, solvers, and then z*.

[simone-silvestri]

Maybe the generalized vertical coordinate section can appear before the "Discretization" and after the hydrostatic free surface model setup so that we refer always to the same equations with $r = z$ or $r = z^\star$

[glwagner]

Or we can do away with trying to distinguish between "equations / physics" and "discretization" and come up with another design?

[glwagner]

Maybe the generalized vertical coordinate section can appear before the "Discretization" and after the hydrostatic free surface model setup so that we refer always to the same equations with r = z or r = z ⋆

Is this $r$ the same as the way we use $r$ in the code? In the code we use $r$ for the grid spacings, and it refers to the "reference" grid. But here you seem to be using the MOM notation, where $r$ refers to the "radial coordinate".

We should use identical notation for math and in the code, I think otherwise it will be easy to get very confused. In the code, $z$ is the radial coordinate?

[simone-silvestri]

Nono, r is exactly the same as in the code, it is the generalized coordinate that we transform into (specifically, in our case it could be only z or zstar).
On purpose I tried to be as close as possible to the source code so that is would be easy to interpret and understand the implementation.

[simone-silvestri]

Note that in the docs $\Delta z = \sigma \Delta r$ which is the same implementation we have here

Oceananigans.jl/src/Operators/time_variable_grid_operators.jl

Lines 34 to 48 in 013f275

	for LX in (:ᶠ, :ᶜ), LY in (:ᶠ, :ᶜ), LZ in (:ᶠ, :ᶜ)
	zspacing = Symbol(:Δz, LX, LY, LZ)
	rspacing = Symbol(:Δr, LX, LY, LZ)
	ℓx = superscript_location(LX)
	ℓy = superscript_location(LY)
	ℓz = superscript_location(LZ)
	@eval begin
	@inline $zspacing(i, j, k, grid::MRG) = $rspacing(i, j, k, grid) * σⁿ(i, j, k, grid, $ℓx(), $ℓy(), $ℓz())
	@inline $zspacing(i, j, k, grid::MLLG) = $rspacing(i, j, k, grid) * σⁿ(i, j, k, grid, $ℓx(), $ℓy(), $ℓz())
	@inline $zspacing(i, j, k, grid::MOSG) = $rspacing(i, j, k, grid) * σⁿ(i, j, k, grid, $ℓx(), $ℓy(), $ℓz())
	end
	end

[simone-silvestri]

Or we can do away with trying to distinguish between "equations / physics" and "discretization" and come up with another design?

Yeah, I like the idea, we can blend both together and write equations and discretizations together. We should start with grids and the C-grid framework and then move to models where we show equations and discretizations together.

[glwagner]

There is already a Grids section, so you can add something to that docs section about MutableVerticalDiscretization. It'd be nice to add a graphic illustrating the grid too!