Standard for surface level prefix/suffix? #150

Activity

1. svahl991

   assigned

   svahl991

   ,

   mkavulich

   ,

   climbfuji

   and

   nusbaume

   on Jun 13, 2026
2. mkavulich commented on Jul 2, 2026

   

   mkavulich

   on Jul 2, 2026

   Collaborator

   More actions

   @svahl991 Sorry I missed this issue when you opened it. I believe that specific instance (as well as a few others, such as dimensionless_exner_function_wrt_surface_pressure) was just an oversight on my part, missed when I applied the rest of the renamings in #129.

   There are still a few other names that start with surface_, but I believe all of those are names with a specific scientific meaning, such as surface_skin_temperature and surface_roughness. And we can discuss more at today's meeting, but there are some variables such as surface_friction_velocity, and surface_longwave_emissivity, that aren't really properties at the surface interface but rather of or from the surface, so I'm not sure which direction to go.
3. svahl991 commented on Jul 2, 2026

   

   svahl991

   on Jul 2, 2026

   Last edited by svahl991

   CollaboratorAuthor

   More actions

   The surface_skin_temperature name is of particular interest to me. In JEDI we are using skin_temperature_at_surface because I thought that's the direction ESM was going. Compare with the existing name skin_temperature_at_surface_over_ice.
4. svahl991 commented on Jul 6, 2026

   

   svahl991

   on Jul 6, 2026

   CollaboratorAuthor

   More actions

   Related question: is sea_surface_temperature going to stay, or change to sea_temperature_at_surface? Or temperature_of_sea_at_surface?
5. mkavulich commented on Sep 21, 2026

   

   mkavulich

   on Sep 21, 2026

   Last edited by mkavulich

   Collaborator

   More actions

   @svahl991 Sorry this issue is dragging on so long, but I've done a lot of thinking about the use of the word "surface" in the standard names and I believe I have come to the ultimate problem and source of the confusion in all of our discussions. The problem is "surface" is being used interchangeably to mean two different things: the solid/liquid substance below the atmosphere, and the portion of the atmosphere adjacent to that substance. You can see this in a set of the existing names:

   The substance below the atmosphere at a given point

   • surface_skin_temperature: The temperature of the topmost layer of the surface
   • vertical_dimension_of_surface_snow: Vertical dimension of surface snow

   Not to mention the generic term "land surface model" carries this definition implicitly

   Atmospheric layer adjacent to surface as described above

   • air_pressure_at_surface: Air pressure at local surface
   • dimensionless_exner_function_wrt_surface_pressure: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)

   Now, in some cases such as using "surface" as a location/elevation, the difference in definitions is infinitesimal so there is no need to resolve the ambiguity (e.g. geopotential_at_surface, geopotential_height_wrt_surface). But there is a significant subsample above where the different physical quantities between the two is substantial depending on the definition used.

   Proposed solution

   I believe I can eliminate the ambiguity, but it comes at the cost of (as usual) some more clunky/unusual wording. We need to split the current use of "surface" into two definitions:

   1. surface is the solid or liquid substance beneath the atmosphere for a given column. This can be land, ocean, ice, lake, etc.
   2. surface_adjacent_interface is the lowest point of the atmosphere, adjacent to the surface. This could alternatively be called "bottom of atmosphere" (boa), analogous to the term "top of atmosphere" (toa) currently in use and defined in the rules, or "surface_adjacent_interface", analogous to the term "surface_adjacent_layer" currently in use and defined in the rules.

   With these definitions, the difference between surface_ as a prefix or suffix is no longer a problem, as something like "surface_temperature" is a valid name as it uses "surface" as a medium (as described in the name construction rules), rather than as a prefix, and the analogous suffix when describing an atmospheric property becomes "_at_boa" or "_at_surface_adjacent_interface"

   Please chime in with your thoughts, especially if you can see this being a problem for JEDI; I am assuming there are few variables actually making use of this second definition, but I could be wrong. It seems to be particularly for things like "skin_temperature" (see #154) that this distinction really matters.

   I will open a draft PR soon with proposed changes for these new definitions, but I wanted to document my thought process beforehand so these changes don't seem out-of-the-blue.
6. svahl991 commented on Sep 21, 2026

   

   svahl991

   on Sep 21, 2026

   CollaboratorAuthor

   More actions

   Thanks @mkavulich for the thought you've put into this! This seems like a good insight.

   I'm a bit concerned that if we have the terms surface, surface_adjacent_interface, and surface_adjacent_layer all floating around the naming standard, we might start to introduce some confusion about the differences between them. I think I prefer _at_boa over surface_adjacent_interface. That makes it clearer to me that we are talking about a special level of the atmosphere, and I like the parallel with toa.

   I feel like this discussion is also starting to bleed into the territory of issue #154, so I will tag the same scientists that I did on that issue, in hopes that they will chime in if they have an opinion on either of these topics.

   Tagging @ClaraDraper-NOAA @BenjaminRuston @BenjaminTJohnson @mikecooke77
7. mkavulich

   added a commit that references this issue on Oct 8, 2026

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

   ...

   c4a4c7a
8. mkavulich commented on Oct 8, 2026

   

   mkavulich

   on Oct 8, 2026

   Collaborator

   More actions

   Resolved by #157
9. mkavulich

   closed this as completedon Oct 8, 2026