From 740db23ff9f0fbbc2190921e9022671ccb51a1ef Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Wed, 25 Feb 2026 14:43:53 -0700 Subject: [PATCH 1/2] Reorganize rules a bit, add a section on times/dates/durations for accumulated and similar variables --- StandardNamesRules.rst | 66 +++++++++++++++++++++++++++++++----------- 1 file changed, 49 insertions(+), 17 deletions(-) diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst index 95d12c0..fe49635 100644 --- a/StandardNamesRules.rst +++ b/StandardNamesRules.rst @@ -21,6 +21,9 @@ for use with Earth System Models. It describes the ESM Standard Name Rules ======================== +Constructing names +------------------ + #. Standard names should be identical to those from the latest version of the `Climate and Forecast (CF) metadata conventions `_ unless @@ -64,10 +67,34 @@ ESM Standard Name Rules and ``air_temperature``. When multiple transformations are present, a more detailed description should be provided in the ``description`` field to prevent any possible ambiguity. +Variable scope +-------------- + #. Variables are current and instantaneous unless specified. Variables that are not current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values) should have qualifiers in the standard name to describe what they represent. +#. For accumulated variables, or variables representing a change over some period of time, the + following suffixes are available": + + * ``over_[time]`` indicates an accumulation or other change over the previous duration/time + * ``reset_every_[date/time]`` an accumulation or other change reset every set duration/time + since the start of the simulation + * ``since_[date/time]`` indicates an accumulation or other change since a given date/time. + + Dates, times, and durations should follow the `ISO 8601 ` + international standard, modified only to use lowercase rather than uppercase letters. Note that + the standard is slightly different for dates and times vs durations. For example: + + * ``accumulated_precipitation_over_pt3h`` accumulated precipitation over the last 3 hours + * ``accumulated_precipitation_over_p1dt12h`` accumulated precipitation over the last 1 day 12 hours + * ``accumulated_precipitation_reset_every_pt1h`` accumulated precipitation reset every 1 hour + * ``accumulated_precipitation_reset_every_p1y`` accumulated precipitation reset every 1 year + * ``accumulated_precipitation_reset_every_p2dt12h`` accumulated precipitation reset every 2 days, 12 hours + * ``accumulated_precipitation_since_20230522t120000`` accumulated precipitation since May 22, 2023 at 12:00 + * ``accumulated_precipitation_since_20251225`` accumulated precipitation since December 25, 2025 + * ``accumulated_precipitation_since_t00`` accumulated precipitation since 00:00:00 (midnight) + #. By default (when not specified otherwise), variables are grid means or centers (defined by the host). If a variable is defined at a different physical location, a qualifier should be used to denote this. For example, to specify the vertical @@ -92,6 +119,26 @@ ESM Standard Name Rules ``[variable]_at_top_interfaces`` is defined on ``n`` points, and ``[variable]_at_bottom_interfaces`` is defined on ``n`` points. +#. If possible, qualifiers should be limited in order to allow for a wide + applicability of the variable. In other words, don't qualify with ``_for_specific_context`` + unless a variable could not conceivably be used outside of the more + narrowly-defined context or a variable without the scope-narrowing qualifiers + already exists and cannot be reused. + + **Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme + + **Preferred:** upward_virtual_potential_temperature_flux + +#. If there are two identical quantities from different schemes/processes that + need to be kept apart, suitable qualifiers are added to the names of the processes. + If one process is already established and more common than the other, then it is + sufficient to only prefix the new process with a suitable qualifier. Example: + ``due_to_convective_GWD`` and ``due_to_convenctive_whole_atmosphere_GWD`` + as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79. + +Terminology +----------- + #. By default, *mixing_ratio* refers to mass mixing ratios. The description should explicitly specify that it refers to the *mass* mixing ratio. Mass mixing ratios should contain information regarding @@ -131,23 +178,6 @@ ESM Standard Name Rules of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or *cloud_at_500hPa* if only including clouds that exist at 500 hPa). -#. If possible, qualifiers should be limited in order to allow for a wide - applicability of the variable. In other words, don't qualify with ``_for_specific_context`` - unless a variable could not conceivably be used outside of the more - narrowly-defined context or a variable without the scope-narrowing qualifiers - already exists and cannot be reused. - - **Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme - - **Preferred:** upward_virtual_potential_temperature_flux - -#. If there are two identical quantities from different schemes/processes that - need to be kept apart, suitable qualifiers are added to the names of the processes. - If one process is already established and more common than the other, then it is - sufficient to only prefix the new process with a suitable qualifier. Example: - ``due_to_convective_GWD`` and ``due_to_convenctive_whole_atmosphere_GWD`` - as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79. - #. Spell out acronyms unless they are obvious to a vast majority of scientists/developers who may come across them. A list of currently-used aliases is below. Whenever such an alias exist, use the alias in the @@ -389,6 +419,8 @@ Suffixes | on_previous_timestep | ``N`` _timesteps_back | since_ ``T`` +| over_ ``T`` +| reset_every_ ``T`` Computational ------------- From be0e5d5ec3433e7aa5e130afe66a6dad35b3774d Mon Sep 17 00:00:00 2001 From: Michael Kavulich Date: Mon, 16 Mar 2026 11:40:28 -0600 Subject: [PATCH 2/2] Update StandardNamesRules.rst Fixing typo caught by Jesse Co-authored-by: Jesse Nusbaumer --- StandardNamesRules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst index fe49635..ef476d7 100644 --- a/StandardNamesRules.rst +++ b/StandardNamesRules.rst @@ -133,7 +133,7 @@ Variable scope need to be kept apart, suitable qualifiers are added to the names of the processes. If one process is already established and more common than the other, then it is sufficient to only prefix the new process with a suitable qualifier. Example: - ``due_to_convective_GWD`` and ``due_to_convenctive_whole_atmosphere_GWD`` + ``due_to_convective_GWD`` and ``due_to_convective_whole_atmosphere_GWD`` as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79. Terminology