This document contains information about the rules used to create Standard Names for use with the Common Community Physics Package (CCPP). It describes the
- CCPP Standard Name rules
- Standard Name qualifiers
- Other common standard name components
- Acronyms, abbreviations, and aliases
- Units
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.
When no suitable standard name exists in the CF conventions, follow their guidelines for standard name construction at this URL: http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html. Standard names may be qualified by the addition of phrases in certain standard forms and order. The "Qualifications" section of the CF guidelines should be used to provide information about a variable's horizontal surface (e.g. at_cloud_base), component (i.e. direction of variable, e.g. downward), medium (e.g. in_stratosphere), process (e.g. due_to_deep convection), or condition (e.g., assuming_clear_sky). The order defined by the CF rules should be observed. These qualifications do not change the units of the quantity.
All of the following phrases in brackets are optional. The words in italic appear explicitly as stated, while the words in
this fontindicate other words or phrases to be substituted. The new standard name is constructed by joining the base standard name to the qualifiers using underscores.[
component] standard_name [atlevel] [inmedium] [due_toprocess] [assumingcondition]See the list of currently-used qualifiers below for help.
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.
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_interfacesis defined at the interfaces between grid cells vertically, including the bottom-most and top-most interfaces.[variable]_at_top_interfacesis defined at the interfaces between grid cells vertically, including the top-most interface but excluding the bottom-most interface.[variable]_at_bottom_interfacesis 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_interfacesis defined on n+1 points,[variable]_at_top_interfacesis defined on n points, and[variable]_at_bottom_interfacesis defined on n points.By default, mixing_ratio refers to mass mixing ratios. The long name 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 specific_humidity should be avoided as there is no consensus on whether it refers to mixing_ratio_of_water_vapor_wrt_moist_air or mixing_ratio_of_water_vapor_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.
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.
When referring to soil quantities, volume_fraction should be used to express the volumetric soil moisture.
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.
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).
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 repesents (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
_xyzunless 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.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.
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.Standard names that start with
ccpp_represent CCPP framework-provided variables. All other standard names should avoid the use ofccppin their name in order to avoid any confusion.No punctuation should appear in standard names except for underscores (_).
Standard names are case insensitive, i.e. example = EXAMPLE.
black = existing CF qualifier
bold = proposed new qualifier
this font = words or phrases to be substituted
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).
N _timesteps_backX_X _to _Y_X_X _source_code_X _from_input_X_X or horizontal_convergence_of _X_X _and _Y [_over _Z]_X _and _Y [_over _Z]_X_X _wrt _Y_X_X or horizontal_divergence_of _X_X [_over _Z]_Y _wrt _X_X_X_X_X [_over _Z]_X [_over _Z]_X _and _Y_X _to _Y_X_X_X_X_X_X_X| 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 |
| 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 |
| 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) |
| Species |
|---|
| carbon_dioxide |
| dimethyl_sulfide |
| nitrate |
| nitrate_and_nitrite |
| nitrite |
| oxygen |
| ozone |
| phosphate |
| silicate |
| sulfate |
| sulfur_dioxide |
The following names are used with consistent meanings and units as elements in other standard names, although they are themselves too general to be chosen as standard names. They are recorded here for reference only. These are not standard names.
| Generic Name | Units |
|---|---|
| amount | kg m-2 |
| area | m2 |
| area_fraction | 1 |
| binary_mask | 1 |
| data_mask | 1 |
| density | kg m-3 |
| energy | J |
| energy_content | J m-2 |
| energy_density | J m-3 |
| frequency | s-1 |
| frequency_of_occurrence | s-1 |
| heat_flux | W m-2 |
| heat_transport | W |
| horizontal_streamfunction | m2 s-1 |
| horizontal_velocity_potential | m2 s-1 |
| mass | kg |
| mass_flux | kg m-2 s-1 |
| mass_fraction | 1 |
| mixing_ratio | kg kg-1 |
| mass_transport k | g s-1 |
| mole_fraction | 1 |
| mole_flux mol | m-2 s-1 |
| momentum_flux | Pa |
| partial_pressure | Pa |
| period | s |
| power | W |
| pressure | Pa |
| probability | 1 |
| radiative_flux | W m-2 |
| specific_eddy_kinetic_energy | m2 s-2 |
| speed | m s-1 |
| stress | Pa |
| temperature | K |
| thickness | m |
| velocity | m s-1 |
| volume | m3 |
| volume_flux | m s-1 |
| volume_fraction | 1 |
| volume_mixing_ratio | mol mol-1 |
| volume_transport | m3 s-1 |
| vorticity | s-1 |
| Short | Meaning |
|---|---|
| ir | infared |
| lwe | liquid water equivalent |
| max | maximum |
| min | minimum |
| nir | near-infrared part of the EM spectrum (radiation) |
| stp | standard temperature (0 degC) and pressure (101325 Pa) |
| tke | turbulent kinetic energy |
| toa | top of atmosphere |
| uv | ultraviolet part of the EM spectrum (radiation) |
| vis | visible part of the EM spectrum (radiation) |
| wrt | with respect to |
- For variables with an existing match in the Climate and Forecast (CF) metadata conventions, the units should be identical to the canonical units listed there
- For variables without an existing match in the CF conventions, the units should follow the International System of Units (SI/metric system)
- 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. |