Docstring for ShallowWaterScalarDiffusivity

[navidcy]

I made an attempt. But it can be definitely improved...

So this diffusivity is applied to the dynamics regardless the formulation?

@francispoulin can you edit the docstring? Or @simone-silvestri?

Closes #2939

[francispoulin]

Looks great! Thank you @navidcy for doing this.

[navidcy]

So is what I wrote ok? Does it apply for both formulations or should we distinguish?

[simone-silvestri]

It applies to both formulations. sw_∂ⱼ_τ₁ⱼ uses fields u and v to calculate t. Both formulations have a u and v field, in the ConservativeFormulation, they are diagnostic quantities while in the VectorInvariant they are the prognostic velocity

Oceananigans.jl/src/Models/ShallowWaterModels/shallow_water_model.jl

Lines 219 to 234 in b6cf30e

	function shallow_water_velocities(solution, formulation)
	if formulation isa VectorInvariantFormulation
	return (u = solution.u, v = solution.v, w = nothing)
	else
	u = Field(@at (Face, Center, Center) solution.uh / solution.h)
	v = Field(@at (Center, Face, Center) solution.vh / solution.h)
	compute!(u)
	compute!(v)
	return (; u, v, w = nothing)
	end
	end
	shallow_water_fields(velocities, solution, tracers, ::ConservativeFormulation) = merge(velocities, solution, tracers)
	shallow_water_fields(velocities, solution, tracers, ::VectorInvariantFormulation) = merge(solution, (; w = velocities.w), tracers)

[simone-silvestri]

The only distinction is that in the VectorInvariantFormulation (that evolves $u$ and $v$) you want to compute
$h^{-1} \nabla \nu h \nabla t$,
while in the ConservativeFormulation (that evolves $uh$ and $vh$)
$\nabla \nu h \nabla t$

[navidcy]

Ok. Will add a remark and merge ;)