Use English names instead of mathematical symbols in the user API?

[glwagner]

The user API is currently inconsistent: sometimes users identify parameters (and of course model properties) with English names like thermal_expansion

https://github.com/CliMA/Oceananigans.jl/blob/2a7d2a1644997a6400bac41a88a7f6879d93d23d/src/BuoyancyModels/linear_equation_of_state.jl#L18

or gravitational acceleration,

https://github.com/CliMA/Oceananigans.jl/blob/2a7d2a1644997a6400bac41a88a7f6879d93d23d/src/Models/HydrostaticFreeSurfaceModels/explicit_free_surface.jl#L21

but other times, users identify parameters with mathematical symbols like ν,

https://github.com/CliMA/Oceananigans.jl/blob/2a7d2a1644997a6400bac41a88a7f6879d93d23d/src/TurbulenceClosures/turbulence_closure_implementations/scalar_diffusivity.jl#L12-L18

or f₀:

https://github.com/CliMA/Oceananigans.jl/blob/2a7d2a1644997a6400bac41a88a7f6879d93d23d/src/Coriolis/beta_plane.jl#L14-L15

I think we have basically decided that English names are preferred. But the "legacy API" is still around. BetaPlane is not even internally consistent: it asks for rotation_rate and radius, as well as f₀ and β.

Should we fix the issue? This would of course be a huge breaking change. But in that case, we should do it sooner rather than later. Sometimes this may not make sense --- I think colloquially it is more common to say "β" than "planetary vorticity gradient". Sometimes, the mathematical symbols has become the English name. But many other times it does: we typically say "viscosity" rather than "ν".

The "legacy" interface will become more and more prominent as we build out the ecosystem into ClimaOcean and ClimaSeaIce, where (hopefully) we will be using English names for everything. (Hopefully also OceanBiome is on the same page here.) Consistency helps us understand each other.

[navidcy]

I applaud this.

Sometimes however I don't even know the English name. E.g. what's the name for β? Meridional planetary vorticity gradient?

[glwagner]

I mean, the very type is called "beta plane" 😄

I think we should use viscosity and diffusivity though.

[navidcy]

Definitely viscosity and diffusivity over ν and κ!

[glwagner]

It's also been pointed out that we should provide a way to use the code that doesn't require unicode. So things like dt instead of Δt.

This is a big change, but we can start by just allowing objects to be constructed via the alternative names...

Let's make a list of the important ones.

[glwagner]

Here's a start:

• Simulation.Δt -> Simulation.dt
• ∂x -> dx (same for ∂y, ∂z)
• ν and κ to viscosity and diffusivity
• BetaPlane.f₀ -> BetaPlane.f0
• BetaPlane.β -> BetaPlane.beta

It's pretty easy to add this. Is there anything else?

[iuryt]

For TimeStepWizard : max_Δt -> max_dt. NonTraditionalBetaPlane also has $\beta$ and $\gamma$

[apaloczy]

In HydrostaticFreeSurfaceModel: free_surface.η -> free_surface.eta.

[navidcy]

damn... I actually like the unicode as it makes the code more readable.. but I do understand that it's a bit cumbersome to type them!

[glwagner]

There's a bigger problem when systems don't support unicode, it means you may not be able to use Oceananigans at all! (cumbersome is one thing, broken is another). We haven't encountered that yet ourselves as far as I know but others have with other software.

[glwagner]

We can solve it just by having aliases, so we support both (or we can decide to only support one API).