Skip to content

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

Open
mkavulich wants to merge 13 commits into
ESCOMP:mainfrom
mkavulich:feature/resolve_surface_names_rules
Open

mkavulich wants to merge 13 commits into
ESCOMP:mainfrom
mkavulich:feature/resolve_surface_names_rules

Conversation

@mkavulich

@mkavulich mkavulich commented Sep 22, 2026

Copy link
Copy Markdown
Collaborator

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:

…_skin_temperature" definition, and return proper skin temperature naming accordingly
…ned "friction-temperature", including definition and citation.
…r "at_surface_interface" due to existing conflicting definition of "bottom-of-atmosphere" in radiation community. Will stick with the slightly more ambiguous but overall less confusing "at_surface" as a synonym for "at_surface_interface", with appropriate definitions.
Comment thread StandardNamesRules.rst Outdated
Comment thread StandardNamesRules.rst
@mkavulich

Copy link
Copy Markdown
Collaborator Author

@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
mkavulich force-pushed the feature/resolve_surface_names_rules branch from b211c59 to 36899d1 Compare September 22, 2026 19:06
@mkavulich

Copy link
Copy Markdown
Collaborator Author

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants