Resolve ambiguity in terminology for "surface", "ocean vs sea", "skin temperature"

[mkavulich]

Description

This PR seeks to resolve several open issues:

• Standard for surface level prefix/suffix? #150 Carifies when the terms "surface", "at_surface", and "at_surface_adjacent_layer" should be used, and updates names to match. Also clarifies other uses of "surface" in some variable descriptions, when used in the mathematical sense, and drops the use of surface all together when unnecessary (e.g. surface_friction_velocity --> friction_velocity)
• Questions about "skin temperature" definitions #154 Add a detailed definition of surface_skin_temperature, sea_surface_skin_temperature, and skin_temperature_at_toa, with detailed comments on the definitions for each.
• Usage of "sea" vs "ocean" in names #156 Add description of "ocean" and "sea" as synonyms, with guidelines for use based on common terminology.

In addition to these issues, additional clarity is added to the rules for definitions of "layer" vs "interface" (including a fancy diagram!), and the term surface_temperature_scale is renamed to the synonymous and less ambiguous friction_temperature.

Issues

Resolves:

• Standard for surface level prefix/suffix? #150
• Questions about "skin temperature" definitions #154
• Usage of "sea" vs "ocean" in names #156

[mkavulich]

@svahl991 Here is the pull request for your review. There are a few changes since the last time I checked in:

1. I decided to keep the _at_surface suffix with additional definitions. I understand your reluctance to accept _at_surface_adjacent_interface as too wordy and confusing, and my alternate proposal _at_boa (bottom of atmosphere), after some further research, has an existing meaning in the radiation community that is at odds with my proposed usage. It seems worth the mild ambiguity to continue to allow "_at_surface" to refer to the surface-atmosphere interface, so long as the definition in the rules is clear and the variable descriptions allude to this. This has the benefits of allowing shorter names (vs _at_surface_interface), sticking to more familiar definitions, and introducing fewer changes to existing names.
2. I will need your feedback on the resolution to Questions about "skin temperature" definitions #154 (surface_skin_temperature). You mentioned that JEDI went ahead with skin_temperature_at_surface, but I think surface_skin_temperature is more scientifically accurate as a stand-alone term (skin_temperature unqualified seems to typically refer to the top-of-atmosphere value, so skin_temperature_at_surface is confusing to anyone familiar with the term). I have also added definitions for sea_surface_skin_temperature and skin_temperature_at_toa. Let me know if this will be a problem.

[mkavulich]

@climbfuji Thanks for your review; note I pushed one more change with additional "skin_temperature" variables after your review. I've also updated the figure to use k rather than n for the vertical level numbering, which better aligns with traditional use for a variable in the middle of a range (and neatly fits with k as the typical vertical coordinate index), to use the updated "at_surface" wording for the surface interface, and with a few more over_X terms

[svahl991]

This system seems to work OK, especially given the description in the rules. I don't know if it feels self-explanatory to me, however (easily understood without reading the rules), but maybe that's too hard to achieve.

It's unfortunate that once again, JEDI has "guessed wrong" and moved forward with names that we thought would become part of the standard but did not, leaving us in a position where we must re-change names we've already changed once in order to conform. But that's just complaining, and of course can't be considered when trying to determine the best names.

The use of the word "interface" seems slightly different in different places. In this PR, it is referring to a physical interface between the atmosphere and the surface, but around line 107 of the Rules file it is used to refer to the interface(s) between vertical levels of a column. Not inconsistent exactly, but subtly different.

[svahl991]

Why pressure_at_surface in this name instead of air_pressure_at_surface? Seems internally inconsistent. I notice this in other names as well. It seems like in other names the word pressure implies air_pressure, and we only include the word air in air_pressure_at_surface. See also reference_pressure_at_surface and pressure_of_dry_air_at_surface.

[mkavulich]

This is a good point; we should probably have more rules about when and how a medium should be explicitly spelled out (air_pressure vs just pressure). I think in most (all?) cases it should be explicitly stated, especially across different modeling systems where the medium can't just be assumed to be air unless otherwise specified. I'd need to do a thorough review of the existing names to see what exists and what is missing; I can open an issue for this.

[mkavulich]

Now detailed in #161

[svahl991]

The "dry" qualifier shifts the syntax from air_pressure_at_surface to pressure_of_dry_air_at_surface.

[mkavulich]

The difference between air_pressure and pressure_of_dry_air is the inclusion of air_pressure as a base name...this was done to avoid the more clunky and verbose language when it is a very common term, while keeping names technically following our rules.

[svahl991]

For example, surface_skin_temperature
is a fundamentally different quantity than the unqualified skin_temperature.

skin_temperature (unqualified) does not appear to be a valid name (it appears to be skin_temperature_at_toa), so maybe a different example would be better?

[mkavulich]

I think this is the only example currently; I have updated the wording to hopefully be more clear.

[mkavulich]

@svahl991 I have made a few updates based on your comments, including hopefully making the use of the "interface" term more clear.