[release/v1] Third major update in v1 branch: update with changes from main, substitute abbreviations, include base name definitions #104

mkavulich · 2025-03-25T21:56:25Z

Here is the next round of proposed changes, resolving several open issues related to topics of discussion over the past several weeks:

List of changes

Resolve [release/v1] Merge latest changes from main #91: merge in latest relevant changes from the main branch
Resolve [release/v1] Convert instances of weight to scaling_factor for clarity #92: Convert instances of weight to scaling_factor
Resolve [release/v1] Expand on long_name descriptions for base names #93: Expand on long_name descriptions for base names: this was done except for a few very obvious (e.g. area) and/or undefinable (e.g. energy) names, and a few more that I will open an issue for shortly
Resolve some items from [release/v1] Define and include more standard abbreviations in the list of Acronyms, Abbreviations, and Aliases #95: This PR was already becoming too large so I decided to save some of these for later

There were also a few changes not covered by issues:

Added the start of a "Technical specifications" section of the rules, describing the technical details of the dictionary itself. This includes the restrictions previously discussed on including only ASCII characters (and only alphanumeric + _ for standard_names themselves)
Removed references to specific deviations from the CF standard name rules, since we are far diverged at this point.
Added units to base_name entries where appropriate
Removed several duplicate name entries
Removed two generic names that do not exist in CF and are not used in any existing standard names (in this dictionary or CCPP)
- data_mask
- specific_eddy_kinetic_energy
Added an example "comment" entry as an example of how this attribute could be used (see the mixing_ratio entry)
Changed air_potential_temperature --> potential_temperature_of_air per our previous discussions about designating mediums except for variables like air_temperature that are in common use.

Please suggest changes if you think they are needed! This is especially true of the definitions; this effort is far from perfect, I just wanted to get something reasonable down. I started from CF standard names and AMS Glossary of Meteorology where possible, but many of them probably need a lot of work, especially since the general definition may be different from that used in Earth System Modeling (and context may even change within different ESM fields!).

Update StandardNamesRules.rst: add _due_to_planetary_boundary_layer (ESCOMP#80) * Update StandardNamesRules.rst: add _due_to_PBL_processes and other process suffixes

Add/modify skin temperature at surface variables. (ESCOMP#84) * Add JEDI skin temperature variables * Change sea to ocean

add emissions names (ESCOMP#86) This adds emissions names to the CCPP standard names

- start adding more units

… for velocity_potential

…ion between original CF standard names and ESM standard names (since we are so far removed now)

…lude long_name descriptions for each

…ones like "energy" and "volume" - Add new generic name "heat" - Remove some generic names that do not exist in CF and are not used in any existing standard names (in this dictionary or CCPP in general) - data_mask - specific_eddy_kinetic_energy - Add the first "comment" entry as an example of how it might be used - Add a couple new "base name" entries

…ous ones or others I will open an issue for) - Removing a few base names that don't make sense in isolation (date) - Remove duplicates (density, heat_flux, ozone, streamfunction)

climbfuji · 2025-03-31T13:44:03Z

Metadata-standard-names.md

+* `stress`: A deformation force across a unit area
    * `real`: units = Pa
-* `streamfunction`: streamfunction
+* `streamfunction`: Streamfunction


Should this be one or two words?

From a quick survey of the internet and my bookshelf it seems that both are acceptable, with a slight preference for the single-word streamfunction in atmospheric science:

streamfunction

https://glossary.ametsoc.org/wiki/Streamfunction

Wallace and Hobbes Atmospheric Science

Holton Dynamic Meteorology

Kalnay Atmospheric Modeling, Data Assimilation and Predictability

stream function

https://en.wikipedia.org/wiki/Stream_function

Djurić Weather Analysis

climbfuji · 2025-03-31T13:45:45Z

Metadata-standard-names.md

 * `vertical_index_at_top_interface`: Vertical index at top interface
    * `integer`: units = index
-* `number_of_openmp_threads`: Total number of thread blocks which the host model may use to call CCPP physics run groups during the CCPP run phase.
+* `number_of_openmp_threads`: Total number of thread blocks OpenMP (shared-memory) parallel threads.


Suggested change

* `number_of_openmp_threads`: Total number of thread blocks OpenMP (shared-memory) parallel threads.

* `number_of_openmp_threads`: Total number of OpenMP (shared-memory) parallel threads.

climbfuji · 2025-03-31T13:46:41Z

Metadata-standard-names.md

+* `ccpp_block_count`: Ccpp block count
+    * `integer(kind=)`: units = count
+* `ccpp_block_sizes`: Ccpp block sizes
+    * `integer(kind=)`: units = count
+* `ccpp_thread_number`: Number of current thread block. This variable may only be used during CCPP run phase


Suggested change

* `ccpp_block_count`: Ccpp block count

* `integer(kind=)`: units = count

* `ccpp_block_sizes`: Ccpp block sizes

* `integer(kind=)`: units = count

* `ccpp_thread_number`: Number of current thread block. This variable may only be used during CCPP run phase

* `ccpp_block_count`: CCPP block count

* `integer(kind=)`: units = count

* `ccpp_block_sizes`: CCPP block sizes

* `integer(kind=)`: units = count

* `ccpp_thread_number`: Number of current OpenMP thread. This variable may only be used during CCPP run phase

climbfuji · 2025-03-31T13:49:14Z

StandardNamesRules.rst

 | due_to_dry_convection
-| due_to_gravity_wave_drag
+| due_to_gwd
+| due_to_convective_


Is the trailing underscore intentional?

Good catch, this should have been due_to_convective_gwd. Fixed.

nusbaume

Thanks for all of these great updates @mkavulich! I just had some wording-related requests and a few other small changes.

README.md

StandardNamesRules.rst

standard_names.xml

StandardNamesRules.rst

dustinswales · 2025-05-06T21:19:59Z

StandardNamesRules.rst

+---------------------+---------------------------------------------------------+
+| shoc                | simplified higher-order closure stochastic scheme       |
+---------------------+---------------------------------------------------------+
+| shum                | Stochastic HUMidity stochastic physics option           |


I included the capitalization to make the term easier to parse (since "stochastic" appears twice, once as the title of the option, the other as a descriptor). I did some digging and found a potentially better description of the scheme, let me know if this looks okay

dustinswales · 2025-05-06T21:53:40Z

StandardNamesRules.rst

+---------------------+---------------------------------------------------------+
+| mynn                | Mellor-Yamada-Nakanishi-Niino scheme                    |
+---------------------+---------------------------------------------------------+
 | nir                 | near-infrared part of the EM spectrum (radiation)       |


Is near-infrared still considered shortwave? I thought that any wavelengths longer than visible would fall in the "longwave" category.

In the radiation parameterizations, UV-B, nearIR and uv-vis are in the SW. But yeah , it's confusing.
Your call. Leave as is, or maybe change EM to electromagnetic?

dustinswales · 2025-05-06T21:59:11Z

Metadata-standard-names.md

+    * `real`: units = m2 s-1
+* `cloud_area_fraction`: Fraction of an area (usually within a grid cell) containing cloud
+    * `real`: units = fraction
 * `cloud_condensate`: cloud_condensate


Suggested change

* `cloud_condensate`: cloud_condensate

* `cloud_condensate`: Amount of condensed water in cloud

dustinswales · 2025-05-06T22:44:34Z

Metadata-standard-names.md

-* `tendency_of_air_temperature_to_withhold_from_sppt`: Tendency of air temperature to withhold from sppt
+* `tendency_of_air_temperature_to_withhold_from_sppt`: Tendency of air temperature to withhold from stochastically perturbed physics tendencies
    * `real(kind=kind_phys)`: units = K s-1
 * `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Tendency of activated cloud condensation nuclei from climatology


Suggested change

* `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Tendency of activated cloud condensation nuclei from climatology

* `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Change of activated cloud condensation nuclei from climatology per unit time

dustinswales · 2025-05-06T22:48:42Z

standard_names.xml

      </standard_name>
      <standard_name name="thickness"
-                     long_name="thickness">
+                     long_name="The vertical distance between two constant-pressure surfaces">


Suggested change

long_name="The vertical distance between two constant-pressure surfaces">

long_name="The distance between two surfaces">

dustinswales · 2025-05-06T22:52:41Z

standard_names.xml

    </standard_name>
    <standard_name name="tendency_of_dry_air_enthalpy_at_constant_pressure"
-                   long_name="Tendency of dry air enthalpy at constant pressure">
+                   long_name="Tendency of dry air enthalpy at constant pressure; d/dt(Cp*T)">


If you agree with the long_name changes int Metadata-standard-names.md, should we also make them here? (i.e. tendency yadayada -> Change of yadayada per unit time.)

dustinswales · 2025-05-06T22:52:57Z

standard_names.xml

      </standard_name>
-      <standard_name name="do_shoc">
+      <standard_name name="do_shoc"
+                   long_name="Do Simplified Higher-order Closure stochastic physics scheme">


Suggested change

long_name="Do Simplified Higher-order Closure stochastic physics scheme">

long_name="Do Simplified Higher-Order Closure stochastic physics scheme">

dustinswales · 2025-05-06T22:53:05Z

standard_names.xml

      </standard_name>
-      <standard_name name="do_shoc_after_convection">
+      <standard_name name="do_shoc_after_convection"
+                   long_name="Do Simplified Higher-order Closure stochastic physics scheme after convection parameterization">


Suggested change

long_name="Do Simplified Higher-order Closure stochastic physics scheme after convection parameterization">

long_name="Do Simplified Higher-Order Closure stochastic physics scheme after convection parameterization">

Co-authored-by: Jesse Nusbaumer <[email protected]>

Co-authored-by: Dustin Swales <[email protected]>

mkavulich

Thanks for your thorough reviews! @nusbaume I think I have addressed all your suggestions. @dustinswales I have addressed most of your comments and had a couple follow-up questions.

mkavulich · 2025-05-09T17:30:27Z

StandardNamesRules.rst

+---------------------+---------------------------------------------------------+
+| mynn                | Mellor-Yamada-Nakanishi-Niino scheme                    |
+---------------------+---------------------------------------------------------+
 | nir                 | near-infrared part of the EM spectrum (radiation)       |


Is near-infrared still considered shortwave? I thought that any wavelengths longer than visible would fall in the "longwave" category.

mkavulich · 2025-05-09T17:32:27Z

StandardNamesRules.rst

+---------------------+---------------------------------------------------------+
+| shoc                | simplified higher-order closure stochastic scheme       |
+---------------------+---------------------------------------------------------+
+| shum                | Stochastic HUMidity stochastic physics option           |


I included the capitalization to make the term easier to parse (since "stochastic" appears twice, once as the title of the option, the other as a descriptor). I did some digging and found a potentially better description of the scheme, let me know if this looks okay

mkavulich · 2025-05-09T17:38:05Z

Metadata-standard-names.md

+* `diffuse_nir_albedo`: Albedo of diffuse incident near-infrared radiation
+    * `real`: units = 1
+* `diffuse_nir_shortwave_flux`: Flux of diffuse near-infrared and shortwave radiation
+    * `real`: units = 1


Thanks for catching these, I think I just forgot to finish my review of correct units for this section. And I don't even know how some of them got J s-1 instead of W s-1...

mkavulich · 2025-05-09T17:47:20Z

Metadata-standard-names.md

+* `graupel`: Precipitation consisting of heavily rimed ice crystals
+* `gravitational_acceleration`: Gravitational acceleration
+    * `real`: units = m s-2
+* `hail`: Precipitation consisting of large pieces of ice formed in convective clouds


It was hard for me to find a concise and accurate description of what "hail" actually is that excludes ice pellets. Graupel doesn't need the "convective" descriptor because it doesn't happen from non-convective clouds, but I don't know how best to distinguish hail without including that descriptor.

I gave it another shot to hopefully satisfy both of us.

mkavulich · 2025-05-09T17:48:25Z

Metadata-standard-names.md

+* `pressure`: Pressure
+    * `real`: units = Pa
+* `rain`: Precipitation of liquid water from clouds
+* `rain_water`: Liquid water precipitation


Good point; there was only a single instance of the literal rain_water string so I just consolidated it to rain.

mkavulich · 2025-05-09T17:53:09Z

Metadata-standard-names.md

+* `temperature`: Temperature
+    * `real`: units = K
+* `temperature_flux`: Flux of temperature across a unit surface
+    * `real`: units = K m s-1


This is specifically "temperature flux" not heat flux, so I'm pretty sure these units are correct. See, for example, Table 1 here

Metadata-standard-names.md

mkavulich · 2025-05-09T18:08:59Z

Metadata-standard-names.md

+* `potential_temperature_of_air`: air potential temperature
    * `real(kind=kind_phys)`: units = K
-* `air_potential_temperature_on_previous_timestep`: air potential temperature on previous timestep
+* `potential_temperature_of_air_on_previous_timestep`: air potential temperature on previous timestep


The suffix listed in the Standard Name rules is "on_previous_timestep" (and it's used in a number of other names) so this would require a larger change if you think it's needed.

nusbaume

Everything looks good to me now. Thanks again @mkavulich!

## Description This PR merges The `release/v1` branch into the `main` branch. The `release/v1` branch was split off from `main` about a year ago, with the intention to make major rules and name changes to improve the consistency and maintainability of both the rules and the names, without giving major inconveniences/disruption to those currently making use of the main branch. After a year of discussion and changes, it is time to bring these changes to their final resting place in the main branch. The major breaking and/or non-back-compatible changes can be summarized as such (See the subsections below for specific details about these changes): - the physics `kind` field is removed - the `long_name` field is changed to `description` - Several changes to particular terms and components of existing names have been made After this PR is merged, a `v1.0.0` tag will be created, representing the first true "versioned" version of the ESM Standard Names. While more rule changes are likely in the future to resolve open and future issues, this should be a more stable jumping-off point to allow updates and reconciliation with the names in the CCPP physics repository, which has not been resolved in many years now. For those who have not been following along with the discussion and changes related to the **v1** branch, here is a summary of each of the changes made on this branch: ### #85 First rules update, fixing misspelled standard names This first change introduced some changes to the Rules document based on discussion in the CCPP framework regular meetings. These rules changes can be summarized as follows - Introduced a more rigorous and standardized formula for constructing new standard names, with specific rules and definitions of each component of the name, attempting to cover all possible cases - Introduced the concept of "suffixes" to compliment prefixes, with mixing_ratio_wrt``_Y`` being the first example - Introduced the concept of "Reserved phrases"...for now only including "CCPP" as a reference to CCPP-specific variables In addition, a large number of misspellings within the existing names and rules were fixed. ### #87 Second rules update in v1 branch, update several name types This second change introduced the concept of "base names"; representing the main entity from which a standard name is constructed. Some existing prefixes (`surface_X` and `air_X`) were converted to suffixes (`X_at_surface` and `X_of_air`) to improve consistency with other existing names and rules, and some superfluous `surface` wording was removed from several names. The definitions for mixing ratios were improved, and the rules for constructing new names were updated and improved. ### #104 Add techincal specification, substitute abbreviations, include base name definitions This third rules change included some info about technical specifications of the standard names repository, and some formatting improvements. Instances of the term `weight` were changed to `scaling_factor` to avoid potential confusion with the physical property of weight. `long_name` descriptions were added for all the new "base names" with a few minor exceptions. Some new abbreviations were defined to help shorten names. Some unused and duplicate entries were removed. Finally, CCPP-specific variables were consolidated into their own section. ### #116 Rename long_name --> description, update description rules, expand list of abbreviations This fourth change renamed the `long_name` field to `description`, clarifying that this field should be unique, and improving/fixing some existing descriptions. Some more duplicate entries were removed. Some additional new abbreviations were defined to continue shortening names. Finally, continued defining more abbreviations to help shorten standard names further. ### #124 Remove `kind` entry, clarify rules for units and disallowed terms This fifth and final change to the v1 branch (aside from another PR to resolve intervening changes from the main branch) updated the rules to clarify disallowed terms and the role of `units`, and removed the `kind` entry. The `constants` section was organized alphabetically, and changed some names regarding `dry_air`. ## Issues Resolves - #48 - #68 - #94 - #102 Also reference already-closed issues: - #92 - #93 - #95 - #103 --------- Co-authored-by: Jesse Nusbaumer <[email protected]> Co-authored-by: Dom Heinzeller <[email protected]>

climbfuji and others added 14 commits March 4, 2025 15:37

Cherry-picked from main:

fbe2796

Update StandardNamesRules.rst: add _due_to_planetary_boundary_layer (ESCOMP#80) * Update StandardNamesRules.rst: add _due_to_PBL_processes and other process suffixes

Cherry-picked from main:

bfadf30

Add/modify skin temperature at surface variables. (ESCOMP#84) * Add JEDI skin temperature variables * Change sea to ocean

Cherry-picked from main:

26950e2

add emissions names (ESCOMP#86) This adds emissions names to the CCPP standard names

- Bring in changes from rename PR (ESCOMP#98)

0cb8805

- start adding more units

Add the last of the "non-controversial" units; remove duplicate entry…

a2fb618

… for velocity_potential

Add a section on the technical details of the dictionary XML

8988c38

Add new abbreviation definitions per Issue ESCOMP#95, remove distinct…

bb26e3b

…ion between original CF standard names and ESM standard names (since we are so far removed now)

Substitute existing acronyms/abbreviations in standard names, and inc…

561407e

…lude long_name descriptions for each

New abbreviations: skeb, shoc, shum, and sppt

3474336

Fix typo

56fb492

More abbreviations: edmf and pdf

7ff5e99

air_potential_temperature --> potential_temperature_of_air

4c676a9

- Definitions for the rest of the base names (except a few very obvi…

974b271

…ous ones or others I will open an issue for) - Removing a few base names that don't make sense in isolation (date) - Remove duplicates (density, heat_flux, ozone, streamfunction)

mkavulich requested review from MayeulDestouches, cacraigucar, climbfuji, dustinswales, gold2718, grantfirl, mattldawson, mwaxmonsky, nusbaume, peverwhee, ss421 and svahl991 as code owners March 25, 2025 21:56

climbfuji reviewed Mar 31, 2025

View reviewed changes

mkavulich added 2 commits April 14, 2025 12:03

Suggestions from Dom

4eb688a

Fix inadvertant deletion

2c096ee

mkavulich requested a review from climbfuji April 17, 2025 15:29

climbfuji approved these changes Apr 17, 2025

View reviewed changes

nusbaume requested changes May 6, 2025

View reviewed changes

dustinswales requested changes May 6, 2025

View reviewed changes

mkavulich and others added 4 commits May 9, 2025 11:24

Apply Jesse's suggestions from code review

4ad526c

Co-authored-by: Jesse Nusbaumer <[email protected]>

One more fix based on Jesse's review, update Metadata file

07a1085

Apply suggestions from Dustin's code review

4c171e5

Co-authored-by: Dustin Swales <[email protected]>

Rest of changes from Dustin's review

6b6ab3f

mkavulich commented May 9, 2025

View reviewed changes

mkavulich requested review from dustinswales and nusbaume May 9, 2025 18:33

dustinswales approved these changes May 9, 2025

View reviewed changes

nusbaume approved these changes May 12, 2025

View reviewed changes

mkavulich merged commit faf4b6d into ESCOMP:release/v1 May 13, 2025
3 checks passed

This was referenced May 13, 2025

[release/v1] Merge latest changes from main #91

Closed

[release/v1] Convert instances of weight to scaling_factor for clarity #92

Closed

mkavulich mentioned this pull request Nov 10, 2025

Merging "Release/v1" branch to main #129

Merged

	* `number_of_openmp_threads`: Total number of thread blocks OpenMP (shared-memory) parallel threads.
	* `number_of_openmp_threads`: Total number of OpenMP (shared-memory) parallel threads.

	\| shum \| Stochastic HUMidity stochastic physics option \|
	\| shum \| stochastic humidity stochastic physics option \|

	\| nir \| near-infrared part of the EM spectrum (radiation) \|
	\| nir \| near-infrared part of the shortwave spectrum (radiation) \|

	* `cloud_condensate`: cloud_condensate
	* `cloud_condensate`: Amount of condensed water in cloud

	* `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Tendency of activated cloud condensation nuclei from climatology
	* `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Change of activated cloud condensation nuclei from climatology per unit time

	long_name="The vertical distance between two constant-pressure surfaces">
	long_name="The distance between two surfaces">

	long_name="Do Simplified Higher-order Closure stochastic physics scheme">
	long_name="Do Simplified Higher-Order Closure stochastic physics scheme">

[release/v1] Third major update in v1 branch: update with changes from main, substitute abbreviations, include base name definitions #104

[release/v1] Third major update in v1 branch: update with changes from main, substitute abbreviations, include base name definitions #104

Uh oh!

Conversation

mkavulich commented Mar 25, 2025

List of changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

streamfunction

stream function

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nusbaume left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mkavulich left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nusbaume left a comment

Choose a reason for hiding this comment