StandardNamesRules.rst

Earth System Modeling (ESM) Standard Names

This document contains information about the rules used to create Standard Names for use with Earth System Models. It describes the

• ESM Standard Name rules
• Standard Name qualifiers
• Other common standard name components
• Acronyms, abbreviations, and aliases
• Units

ESM Standard Name Rules

Constructing names

1. Standard names should be identical to those from the latest version of the Climate and Forecast (CF) metadata conventions unless an appropriate name does not exist in that standard, or the adoption of said names leads to inconsistencies in the naming convention.

2. When no suitable standard name exists in the CF conventions, the following guidelines should be followed for constructing a new name. The phrases in brackets are optional. The words in italic appear explicitly as stated, while the words in this font indicate other words or phrases to be substituted. The new standard name is constructed by joining the base standard name to the qualifiers using underscores.

   [transformation] [component] [non-instant time] base_name [in/of medium] [at level] [due_to process] [non-current time] [assuming condition]

   This construction was originally based on rules set forth in the CF guidelines, but have since evolved for better consistency and generality across a broader set of fields than was originally envisioned by the CF conventions. "medium" should be specified when the variable in question is a substance or other quantity contained within some other medium (e.g. for mole_fraction_of_ozone_in_air, the base name is "ozone", while the medium is "air"). "Transformation" refers to descriptors such as "tendency_of", "log10", or other operations or processes describing some transformation or adjustment of a variable; a detailed list of possible transformations can be found later in this document. Other parts of the construction provide information about a variable's horizontal surface (e.g. at_cloud_base), component (i.e. direction of variable, e.g. downward), process (e.g. due_to_deep_convection), or condition (e.g., assuming_clear_sky). These qualifications do not change the units of the quantity. This is not an exhaustive list of qualifiers that may be needed for a given standard name; see subsequent rules below for more information.

   The following table provides a few concrete examples of standard names and how they are constructed with respect to the guideline template.

   image of table providing standard name construction examples

   Note that "transformations" are a special case, where multiple transformations may be applied, and multiple quantities may be compared, operated on, etc. For transformations involving multiple quantities (e.g. ratio_of_X_to_Y; see the section on Transformations for more information), the above formula may be extended around multiple base names.

   image of table providing standard name construction examples with multiple transformations

   In the latter example, ln is operating on the quantity water_vapor_partial_pressure_assuming_saturation, while derivative_of is a combined transformation of water_vapor_partial_pressure_assuming_saturation 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

1. 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.

2. 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 <https://en.wikipedia.org/wiki/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)

3. 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 location of a variable with respect to vertical grid cells, the following variants are possible:

   • [variable], with no location suffix, is defined at vertical-cell centers or as vertical-cell averages.
   • [variable]_at_interfaces is defined at the interfaces between grid cells vertically, including the bottom-most and top-most interfaces.
   • [variable]_at_top_interfaces is defined at the interfaces between grid cells vertically, including the top-most interface but excluding the bottom-most interface.
   • [variable]_at_bottom_interfaces is defined at the interfaces between grid cells vertically, including the bottom-most interface but excluding the top-most interface.

   This implies that if [variable] is defined on n points vertically, [variable]_at_interfaces is defined on n+1 points, [variable]_at_top_interfaces is defined on n points, and [variable]_at_bottom_interfaces is defined on n points.

4. 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

5. 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_convective_whole_atmosphere_GWD as discussed in #79.

Terminology

1. 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 with respect to what quantity they are defined, and options are wrt_dry_air, wrt_moist_air, or wrt_moist_air_and_condensed_water, where moist_air refers to dry air plus vapor and moist_air_and_condensed_water refers to dry air plus vapor and hydrometeors.

   Use of the term specific_humidity should be avoided, as there is no consensus on whether it refers to water_vapor_mixing_ratio_wrt_moist_air or water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water. total_water can be used to designate water in every form, i.e. water vapor plus condensed water.

   Volume mixing ratios should be qualified as volume_mixing_ratio.

2. By default, mole_fraction_of_X_in_Y refers to the total amount of Y. So, for example, mole_fraction_of_ozone_in_air refers to the total amount of (moist) air. (In the case of air, the default meaning is moist air, as described in the mixing ratio rule.) When this is not the case, a qualifier should be used to denote this. e.g., mole_fraction_of_ozone_in_dry_air.

3. When referring to soil quantities, volume_fraction should be used to express the volumetric soil moisture.

4. Number concentration should appear as a prefix, that is, number_concentration_of. By default, number concentrations are specified per unit of volume. When they are specified per unit of mass, they should be written as mass_number_concentration_of.

5. By default, precipitation refers to the sum of all phases of precipitating hydrometeors, for example rain plus graupel plus hail. The term frozen_precipitation refers to the sum of all frozen precipitating hydrometers, for example graupel plus hail (but not rain). Otherwise the standard name should explicitly state the type of hydrometeor(s) the named quantity represents (e.g. graupel).

6. By default, the term cloud refers to all cloud phases and cloud types. Otherwise an additional prefix or suffix should be added to the standard name specifying what kind(s) 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).

7. 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 standard name and the full term in the description.

8. Chemical species in standard names should be denoted by chemical formulae (e.g. co2, ch4, c5h8) or commonly accepted designations (e.g. cfc12); generally when there are multiple options the shorter name is preferred. A few species with well-established and unambiguous common names (e.g. water, ozone) are also included. In all cases, the standard name should include specific details about the substance's chemical makeup, as well as the phase/state of matter if relevant; e.g. water_vapor, liquid_h2so4

9. If the ionization of the chemical species is relevant, "ionized" should be included in the standard name as a prefix to the substance; e.g. number_density_of_ionized_he for ionized helium. If relevant, the net ionization charge should be included as a prefix (in words, because +/- are not valid standard name characters); e.g. number_density_of_plus_1_ionized_he

10. For control-oriented variables, if the variable is a Fortran logical, use flag_for _X. If it is any other data type, use control_for _X. All flags should be Fortran logicals.

11. Disallowed terms: A few terms are disallowed as standard name components for various reasons; mostly due to ambiguity.

    • specific_humidity Disallowed due to ambiguity and different definitions between different fields. See above section describing mixing_ratio for more information.
    • amount In most contexts this word is superfluous, and in all contexts it is non-descriptive. Consider a more specific term such as mass_content

12. Reserved names: The prefix ccpp_ is reserved for CCPP framework-provided variables. All other standard names should avoid the use of ccpp in their name.

Technical specifications

1. The standard name dictionary consists of a number of individual XML elements: one standard_name element for each entry. A standard name entry consist of a name attribute that represents the variable name, and (optionally) a description attribute that gives a detailed description of what that name represents. Note that the description field is only provided for information and disambiguation only (though it should be unique), and does not need to be included for individual implementations of the standard names. This is not necessarily the same as the long_name entry as described in the CCPP Technical Documentation, but it can be used to inform the contents of that field. The standard_name XML entry also contains a nested type entry, indicating the data type that a standard_name should represent, and as an attribute the physical units of that variable quantity (see the section on Units). For example, the element for the variable name exner_function may look similar to this:

   <standard_name name="exner_function"

   description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">

   <type units="1">real</type>

   </standard_name>

   This XML element indicates that the variable exner_function represents the quantity described by the description attribute. It is a real variable with units of "1", meaning it is non-dimensional and does not correspond to a more descriptive non-dimensional type such as "fraction"; see the section on Units for more details.

   These standard_name elements can optionally be separated by "section" elements. These are parsed out into human-readable sections in the generated markdown file (Metadata-standard-names.md).

2. Only alphanumeric, punctuation, and whitespace characters from the ASCII character set may be used in the standard_names dictionary. The "name" attributes of standard_name entries (i.e. the standard names themselves) are further restricted to the character set of capital/lowercase letters, numerals, and _ (underscore).

3. The <type> element should include a value that is one of the following valid Fortran types:

   • integer
   • real
   • logical
   • character
   • complex
   • ddt (derived data type)

4. The standard name dictionary XML file should validate according to the schema file standard_names.xsd All of the above specifications should be coded into this schema file as is appropriate.

Qualifiers

this font = words or phrases to be substituted

XY-surface

Prefixes

None. Note that this is a departure from the CF conventions, which in many cases - but not all - use surface_ as a prefix. This departure from the CF convention is to maintain consistency with all other level qualifiers that are used as _at_level-qualifier (i.e. as suffix).

Suffixes

at_adiabatic_condensation_level

at_cloud_top

at_convective_cloud_top

at_cloud_base

at_convective_cloud_base

at_freezing_level

at_ground_level

at_maximum_wind_speed_level

at_sea_ice_base

at_sea_level

at_top_of_atmosphere_boundary_layer

at_top_of_atmosphere_model

at_top_of_dry_convection

at_interfaces

at_toa

at_tropopause

at_surface

at_surface_adjacent_layer

at_2m

at_10m

at_bottom_interface

at_pressure_levels

at_top_of_viscous_sublayer

at_various_atmosphere_layers

extended_up_by_1

Component

Prefixes

upward

downward

northward

southward

eastward

westward

x

y

Special Radiation Component

Prefixes

net

upwelling

downwelling

incoming

outgoing

Medium

Suffixes

in_air

in_atmosphere_boundary_layer

in_mesosphere

in_sea_ice

in_sea_water

in_soil

in_soil_water

in_stratosphere

in_thermosphere

in_troposphere

in_atmosphere

in_surface_snow

in_diurnal_thermocline

in_canopy

in_lake

in_aquifer

in_aquifer_and_saturated_soil

in_convective_tower

between_soil_bottom_and_water_table

Process

Suffixes

due_to_advection

due_to_convection

due_to_deep_convection

due_to_diabatic_processes

due_to_diffusion

due_to_dry_convection

due_to_gwd

due_to_convective_gwd

due_to_convective_whole_atmosphere_gwd

due_to_orographic_gwd

due_to_gyre

due_to_isostatic_adjustment

due_to_large_scale_precipitation

due_to_longwave_heating

due_to_moist_convection

due_to_overturning

due_to_shallow_convection

due_to_pbl_processes

due_to_shortwave_heating

due_to_thermodynamics

due_to_background

due_to_subgrid_scale_vertical_mixing

due_to_convective_microphysics

due_to_model_physics

due_to_shoc

due_to_dynamics

Condition

Suffixes

assuming_clear_sky

assuming_deep_snow

assuming_no_snow

over_land

over_ocean

over_ice

for_momentum

for_heat

for_moisture

for_heat_and_moisture

assuming_shallow

assuming_deep

Time

Suffixes

of_new_state

on_physics_timestep

on_dynamics_timestep

on_radiation_timestep

on_previous_timestep

N _timesteps_back

since_ T

over_ T

reset_every_ T

Computational

Prefixes

lower_bound_of

upper_bound_of

unfiltered

nonnegative

flag_for

control_for

number_of

index_of

vertical_index_at

vertical_dimension_of

cumulative

iounit_of

filename_of

frequency_of

period_of

XYZ_dimensioned

tendency_of X

generic_tendency

one_way_coupling_of _X _to _Y

tunable_parameter[s]_for _X

map_of

Infixes

directory_for _X _source_code

flag_for_reading _X _from_input

Suffixes

for_coupling

for_chemistry_coupling

from_coupled_process

from_wave_model

collection_array

multiplied_by_timestep

for_current_mpi_rank

for_current_cubed_sphere_tile

plus_one

minus_one

for_radiation

for_deep_convection

for_microphysics

Transformations

Prefixes

change_over_time_in _X

convergence_of _X or horizontal_convergence_of _X

correlation_of _X _and _Y [_over _Z]

cosine_of _X

covariance_of _X _and _Y [_over _Z]

component_derivative_of _X

derivative_of _X _wrt _Y

direction_of _X

divergence_of _X or horizontal_divergence_of _X

histogram_of _X [_over _Z]

integral_of _Y _wrt _X

ln _X

log10 _X

lwe_thickness_of _X

magnitude_of _X

probability_distribution_of _X [_over _Z]

probability_density_function_of _X [_over _Z]

product_of _X _and _Y

ratio_of _X _to _Y

reciprocal_of _X

sine_of _X

square_of _X

standard_deviation_of _X

tendency_of _X

variance_of _X

volume_mixing_ratio_of _X

Suffixes

X_ mixing_ratio_wrt _Y

Other common standard name components

Reserved phrase

These words/phrases should not be used outside of the described context

Phrase	Usage
ccpp	Variable names provided by the CCPP framework

Special phrases

Phrase	Meaning
anomaly	difference from climatology
area	horizontal area unless otherwise stated
atmosphere	used instead of in_air for quantities which are large-scale rather than local
condensed_water	liquid and ice
frozen_water	ice
longwave	Longwave radiation. Defined as thermal emission of radiation from the planet.
moisture	water in all phases contained in soil
ocean	used instead of in_sea_water for quantities which are large-scale rather than local
shortwave	Shortwave radiation. Defined as electromagnetic emissions from the sun
specific	per unit mass unless otherwise stated
unfrozen_water	liquid and vapor
water	water in all phases if not otherwise qualified
dimensionless	lacking units
kinematic	refers to surface fluxes in "native" units (K m s-1 and kg kg-1 m s-1)
direct	used in radiation (as opposed to diffuse)
diffuse	used in radiation (as opposed to direct)

Acronyms, Abbreviations, and Aliases

Short	Meaning
cnvc90	GFS Convective Cloud Diagnostics
edmf	eddy-diffusivity/mass-flux
gwd	gravity wave drag
gfdl	Geophysical Fluid Dynamics Laboratory
gfs	Global Forecast System
ir	infrared
lwe	liquid water equivalent
max	maximum
min	minimum
myj	Mellor-Yamada-Janjic scheme
mynn	Mellor-Yamada-Nakanishi-Niino scheme
nir	near-infrared part of the EM spectrum (radiation)
nrl	Naval Research Lab
nsstm	GFS near-surface sea temperature scheme
pbl	planetary boundary layer
pdf	probability density function
rrtmgp	Rapid Radiative Transfer Model for General circulation model applications - Parallel
sas	simplified Arakawa-Schubert scheme
skeb	stochastic kinetic energy backscatter
shoc	simplified higher-order closure stochastic scheme
shum	stochastically perturbed boundary-layer humidity scheme
sppt	stochastically perturbed physics tendencies
stp	standard temperature (0 degC) and pressure (101325 Pa)
tke	turbulent kinetic energy
toa	top of atmosphere
ugwp	Unified Gravity Wave Physics
uv	ultraviolet part of the EM spectrum (radiation)
vis	visible part of the EM spectrum (radiation)
wrt	with respect to

Units

Entries in the Standard Names dictionary contain a "units" property that serves to indicate the typical/recommended units for a given variable. It is not mandatory to use the indicated units exactly, but any use of a given standard name variable should have units of the same dimensionality.

When adding a new standard name, units should follow the International System of Units (SI/metric system). If the new standard name has an existing match in the Climate and Forecast (CF) metadata conventions, the units should be identical to the canonical units listed there

For dimensionless variables, the following units can be used:

Unit	Use case
count	integers that describe the dimension/length of an array
flag	logicals/booleans that can be either true or false
index	integers that can be an index in an array
kg kg-1	mass mixing ratios
m3 m-3	volume fraction (e.g. for soil moisture)
mol mol-1	molar mixing ratios (also volumetric mixing ratio for gases)
none	strings and character arrays
fraction	fractions not listed above, typically valid in the range [0,1]
percent	fractions expressed in percent, typically ranging from 0% to 100%
1	any number (integer, real, complex) not listed above, e.g. scaling factors, error codes, etc.