Define naming pattern for diagnostics

[tomchor]

At the moment the diagnostics don't follow a strict naming pattern. Taking the TKEBudgetTerms as an example:

Oceanostics.jl/src/Oceanostics.jl

Lines 4 to 9 in 3b46106

	#+++ TKEBudgetTerms exports
	export TurbulentKineticEnergy, KineticEnergy
	export KineticEnergyTendency, KineticEnergyDiffusiveTerm, KineticEnergyForcingTerm
	export IsotropicKineticEnergyDissipationRate, KineticEnergyDissipationRate
	export XPressureRedistribution, YPressureRedistribution, ZPressureRedistribution
	export XShearProductionRate, YShearProductionRate, ZShearProductionRate

Some diagnostics have Term appended to their names (like KineticEnergyDiffusiveTerm), some don't (like KineticEnergyDissipationRate). Some start with KineticEnergy (like KineticEnergyDiffusiveTerm again) but some don't (like XShearProductionRate).

It would be nice to agree on a naming pattern to use from now on. I think it's more important to be clear than it is to be concise. For example, something like the snippet below (which is made up code just for example sake) isn't 100% clear

using Oceanostics
ε = DissipationRate

Which is why the currently implemented code has a more verbose name:

using Oceanostics
χ = TracerVarianceDissipationRate(model)
ε = KineticEnergyDissipationRate(model)

We could keep following this pattern and make things more verbose, following the pattern "budgeted quantity" + "term name", which would bring KineticEnergyDissipationRate, KineticEnergyPressureRedistribution, TracerVarianceForcing, etc.

Another option is to not export function/diagnostic names at the top/package level and name the modules according to the equations the diagnostic terms come from. That way the snippet above would become something like

using Oceanostics
χ = TracerVarianceEquation.DissipationRate(model)
ε = KineticEnergyEquation.DissipationRate(model)

which, I would argue, is pretty readable, and not too verbose.

cc @glwagner

[glwagner]

I agree that verbose is good and that prefixing the names by the equation the diagnostic is relevant too (especially for the budgets of variances) is helpful.

We rarely regret having more modules so that might a great idea. I think you could also omit "Equation" from the end, ie

using Oceanostics
χ = TracerVariance.DissipationRate(model)
ε = KineticEnergy.DissipationRate(model)

[tomchor]

I agree that verbose is good and that prefixing the names by the equation the diagnostic is relevant too (especially for the budgets of variances) is helpful.

We rarely regret having more modules so that might a great idea. I think you could also omit "Equation" from the end, ie

using Oceanostics
χ = TracerVariance.DissipationRate(model)
ε = KineticEnergy.DissipationRate(model)

I think putting diagnostics explicitly in terms of equations (whenever possible) is helpful since it probably means we don't need to explicitly write Term at the end of terms and people will still understand it refers to a term.

Plus omitting Equation can probably lead to things like KineticEnergy.KineticEnergy, which doesn't look right. So I think I prefer putting "Equation" there somewhere.