Provide both English names and abbreviated / symbolic names for parameter functions

[glwagner]

Many of the functions defined in this package do not represent the English names of parameters, but rather abbreviations (grav, year_anom) or approximations of mathematical symbols (R_d, cp_v).

I think it's best practice to use ordinary written names in scientific scripts to minimize barriers to script comprehension --- but I accept that some users prefer to write code that uses abbreviations. As a compromise, is it possible to provide both verbose names and "short aliases" for key functions? Some examples are

• molecular_mass_dry_air
• gravitational_acceleration
• heat_capacity_constant_volume

We can implement the verbose names and aliases in the Planet module, and then ask that the verbose names be overloaded by specific implementations as in

https://github.com/CliMA/CLIMAParameters.jl/blob/master/src/Planet/planet_parameters.jl

One advantage is that module code will then be self-documenting:

Planet.mean_sea_level_pressure(::AbstractEarthParameterSet) = 1.01325e5 # hPa

I am happy to submit a PR for this, though unfortunately I don't know what the ordinary names would be for all of the functions so I am unable to finish the job completely.

[christophernhill]

Greg Do you think there are standard names from the CF conventions and related WMO catalogs we could adopt/coopt? Those tend to be recognized widely and used in downstream tools I think? Chris

…

On Wed, Nov 4, 2020 at 09:23 Gregory L. Wagner ***@***.***> wrote: Many of the functions defined in this package do not represent the English names of parameters, but rather abbreviations (grav, year_anom) or approximations of mathematical symbols (R_d, cp_v). I think it's best practice to use ordinary written names in scientific scripts to minimize barriers to script comprehension --- but I accept that some users prefer to write code that uses abbreviations. As a compromise, is it possible to provide both verbose names and "short aliases" for key functions? Some examples are - molecular_mass_dry_air - gravitational_acceleration - heat_capacity_constant_volume We can implement the verbose names and aliases in the Planet module, and then ask that the verbose names be overloaded by specific implementations as in https://github.com/CliMA/CLIMAParameters.jl/blob/master/src/Planet/planet_parameters.jl One advantage is that module code will then be self-documenting: Planet.mean_sea_level_pressure(::AbstractEarthParameterSet) = 1.01325e5 # N / m^2 I am happy to submit a PR for this, though unfortunately I don't know what the ordinary names would be for all of the functions so I am unable to finish the job completely. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#41>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA27DYE4JYMRNQDFX7IV24TSOFPVJANCNFSM4TKDSM5A> .

[glwagner]

That seems like a fine idea. We can provide both English names (for scripts) and names that correspond to standard mathematical notation (for equations that appear deep inside the code). I'm not sure the place for abbreviations; they often seem to be ad hoc.

[charleskawczynski]

My 2 cents: I'm definitely a fan of self-documenting names, but I think I would prefer sticking with shorter names here. The reason being is that these parameters are not type-stable and, to reduce the number of names of variables, we often use aliases like

_grav = FT(grav(param_set))

so that we don't 2x the number of clima parameters. Following verbose names would look like

_mean_sea_level_pressure = FT(mean_sea_level_pressure(param_set))

And my hunch is that this might get ugly. We could just FT(mean_sea_level_pressure(param_set)) where needed, but I would look around CM.jl (e.g., microphysics) to see how that may impact some people (i.e., @trontrytel).

[glwagner]

to reduce the number of names of variables, we often use aliases

With English names available, mathematical notation becomes an option for type-converted names:

g = convert(FT, gravitational_acceleration(earth_parameters)))

And my hunch is that this might get ugly.

If we provide both aliases and English names, then one can write _grav = FT(grav(param_set)) if they desire, or use the form above that I might prefer instead --- hopefully we can find something that works for everyone.

I do hope that we can ultimately hide type conversion concerns from users, because the proliferation of FT(*) is detrimental to the readability of scripts. Then the "2x" problem would not be a concern.

[trontrytel]

I agree with @charleskawczynski . I think having too long and descriptive names will make the code less readable.

I also thought the full descriptions are provided inside the CLIMAParameters.jl. For example for gravitational acceleration we have:

https://github.com/CliMA/CLIMAParameters.jl/blob/f779db6fa86f0bfce9de4ee31757fed1fe8b75ed/src/Planet/Planet.jl#L122-L123

[glwagner]

Putting aside the debate about literate style versus mathematical notation, what do we think about providing English aliases in addition to the short names that are currently provided?

It's true there are docstrings in `Planet.jl'; however, these are not currently pasted in the module where numerical values of the parameters are defined, which is where you have to look if you are trying to evaluate whether the numerical values are correct, or what you want.

[tapios]

I'm generally in favor of clear (and often that means verbose) variable and parameter names (and way back when wrote something to that effect in the CliMA roadmap). However, readability is important. If we stay close to names we use in equations, it will be both readable and clear, i.e., I don't think we need anything more verbose for common parameters such as cp_v, R_d, g or grav (although all should have a plain language definition that is easily accessible, as they do in CLIMAParameters.jl.

That being said, I think a lot of our variable names (e.g., in the numerics) may benefit from more clarity (as evidenced by the questions just about every new user asks about what they mean).

[christophernhill]

Is it possible to define the base functions differently (or a variant with a special type) e.g.

instead of

""" Molecular weight dry air (kg/mol) """
function molmass_dryair end

in the canonical def, do something more like along the lines of

""" Molecular weight dry air (kg/mol) """
function molmass_dryair (return (cfname="molecular_weight_dry_air", standard_units="kg/mol") )

that would make it possible to get standard names programmatically, which can be useful for REPL and for logging etc...

[glwagner]

Thank @tapios. I just want to make sure that I head off any miscommunication. I'm not suggesting changing the names of anything, but rather adding aliases.

Let's take cp_v as an example. My suggestion is to provide

""" Heat capacity at constant volume (J / K). """
function heat_capacity_constant_volume end
const cp_v = heat_capacity_constant_volume

With this design, a user implementing a simulation on an Earth-like planet with reduced gravity might write

using CLIMAParameters.Planet
import CLIMAParameters.Planet: gravitational_acceleration

struct StrangeEarth <: AbstractEarthParameterSet end

gravitational_acceleration(::StrangeEarth) = 7.0

# Later on...
grav(StrangeEarth()) # returns 7.0

[ali-ramadhan]

The problem of acronyms is especially bad when you cannot even Google the acronym, e.g. TSI and MSLP don't turn up relevant results. I think this makes the package less understandable and accessible.

Just wanted to add a 👍 for aliases, although I'm very much in favor of verbose names.