@@ -21,6 +21,9 @@ for use with Earth System Models. It describes the
2121 ESM Standard Name Rules
2222========================
2323
24+ Constructing names
25+ ------------------
26+
2427#. Standard names should be identical to those from the latest version
2528 of the `Climate and Forecast (CF) metadata
2629 conventions <https://cfconventions.org/standard-names.html> `_ unless
@@ -64,10 +67,34 @@ ESM Standard Name Rules
6467 and ``air_temperature ``. When multiple transformations are present, a more detailed description
6568 should be provided in the ``description `` field to prevent any possible ambiguity.
6669
70+ Variable scope
71+ --------------
72+
6773#. Variables are current and instantaneous unless specified. Variables that are not
6874 current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
6975 should have qualifiers in the standard name to describe what they represent.
7076
77+ #. For accumulated variables, or variables representing a change over some period of time, the
78+ following suffixes are available":
79+
80+ * ``over_[time] `` indicates an accumulation or other change over the previous duration/time
81+ * ``reset_every_[date/time] `` an accumulation or other change reset every set duration/time
82+ since the start of the simulation
83+ * ``since_[date/time] `` indicates an accumulation or other change since a given date/time.
84+
85+ Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601> `
86+ international standard, modified only to use lowercase rather than uppercase letters. Note that
87+ the standard is slightly different for dates and times vs durations. For example:
88+
89+ * ``accumulated_precipitation_over_pt3h `` accumulated precipitation over the last 3 hours
90+ * ``accumulated_precipitation_over_p1dt12h `` accumulated precipitation over the last 1 day 12 hours
91+ * ``accumulated_precipitation_reset_every_pt1h `` accumulated precipitation reset every 1 hour
92+ * ``accumulated_precipitation_reset_every_p1y `` accumulated precipitation reset every 1 year
93+ * ``accumulated_precipitation_reset_every_p2dt12h `` accumulated precipitation reset every 2 days, 12 hours
94+ * ``accumulated_precipitation_since_20230522t120000 `` accumulated precipitation since May 22, 2023 at 12:00
95+ * ``accumulated_precipitation_since_20251225 `` accumulated precipitation since December 25, 2025
96+ * ``accumulated_precipitation_since_t00 `` accumulated precipitation since 00:00:00 (midnight)
97+
7198#. By default (when not specified otherwise), variables are grid means or centers
7299 (defined by the host). If a variable is defined at a different physical location,
73100 a qualifier should be used to denote this. For example, to specify the vertical
@@ -92,6 +119,26 @@ ESM Standard Name Rules
92119 ``[variable]_at_top_interfaces `` is defined on ``n `` points, and
93120 ``[variable]_at_bottom_interfaces `` is defined on ``n `` points.
94121
122+ #. If possible, qualifiers should be limited in order to allow for a wide
123+ applicability of the variable. In other words, don't qualify with ``_for_specific_context ``
124+ unless a variable could not conceivably be used outside of the more
125+ narrowly-defined context or a variable without the scope-narrowing qualifiers
126+ already exists and cannot be reused.
127+
128+ **Discouraged: ** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
129+
130+ **Preferred: ** upward_virtual_potential_temperature_flux
131+
132+ #. If there are two identical quantities from different schemes/processes that
133+ need to be kept apart, suitable qualifiers are added to the names of the processes.
134+ If one process is already established and more common than the other, then it is
135+ sufficient to only prefix the new process with a suitable qualifier. Example:
136+ ``due_to_convective_GWD `` and ``due_to_convective_whole_atmosphere_GWD ``
137+ as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
138+
139+ Terminology
140+ -----------
141+
95142#. By default, *mixing_ratio * refers to mass mixing ratios. The description should
96143 explicitly specify that it refers to the *mass * mixing ratio.
97144 Mass mixing ratios should contain information regarding
@@ -131,23 +178,6 @@ ESM Standard Name Rules
131178 of clouds the variable represents (e.g. *ice_cloud * if only including glaciated clouds, or
132179 *cloud_at_500hPa * if only including clouds that exist at 500 hPa).
133180
134- #. If possible, qualifiers should be limited in order to allow for a wide
135- applicability of the variable. In other words, don't qualify with ``_for_specific_context ``
136- unless a variable could not conceivably be used outside of the more
137- narrowly-defined context or a variable without the scope-narrowing qualifiers
138- already exists and cannot be reused.
139-
140- **Discouraged: ** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
141-
142- **Preferred: ** upward_virtual_potential_temperature_flux
143-
144- #. If there are two identical quantities from different schemes/processes that
145- need to be kept apart, suitable qualifiers are added to the names of the processes.
146- If one process is already established and more common than the other, then it is
147- sufficient to only prefix the new process with a suitable qualifier. Example:
148- ``due_to_convective_GWD `` and ``due_to_convenctive_whole_atmosphere_GWD ``
149- as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
150-
151181#. Spell out acronyms unless they are obvious to a vast majority of
152182 scientists/developers who may come across them. A list of currently-used
153183 aliases is below. Whenever such an alias exist, use the alias in the
@@ -389,6 +419,8 @@ Suffixes
389419| on_previous_timestep
390420| ``N`` _timesteps_back
391421| since_ ``T``
422+ | over_ ``T``
423+ | reset_every_ ``T``
392424
393425Computational
394426-------------
0 commit comments