Skip to content

First rules update in v1 branch, fix misspelled standard names #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkavulich merged 8 commits into from
Nov 26, 2024
Merged

First rules update in v1 branch, fix misspelled standard names #85

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1a2b5f1
First round of rules updates, mostly discussed at the last meeting
mkavulich Nov 12, 2024
6fd945a
Fix image embedding
mkavulich Nov 12, 2024
835245f
Fix some links
mkavulich Nov 12, 2024
22a8712
Need a "suffixes" entry for Transformations to accomodate the many, m…
mkavulich Nov 12, 2024
701234f
minor updates
mkavulich Nov 12, 2024
152a0be
Fix spelling in standard names
mkavulich Nov 13, 2024
3e58152
Fix some rules spelling
mkavulich Nov 13, 2024
7a34e22
Update StandardNamesRules.rst
mkavulich Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions Metadata-standard-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Currently, the only dimension which supports all six dimension types is horizont
* `real(kind=kind_phys)`: units = kg m-3
* `ratio_of_water_vapor_to_dry_air_gas_constants_minus_one`: (Rwv / Rdair) - 1.0
* `real(kind=kind_phys)`: units = 1
* `standard_gravitational_acceleration`: scalar constant representing gravitiational acceleration
* `standard_gravitational_acceleration`: scalar constant representing gravitational acceleration
* `real(kind=kind_phys)`: units = m s-2
## coordinates
* `latitude`: Latitude
Expand Down Expand Up @@ -231,9 +231,9 @@ Note that appending '_on_previous_timestep' to standard_names in this section yi
* `real(kind=kind_phys)`: units = m s-2
* `tendency_of_northward_wind_due_to_model_physics`: Total change in northward wind from a physics suite
* `real(kind=kind_phys)`: units = m s-2
* `air_horizontal_streamfunction`: Scalar function describing the stream lines of the wind
* `air_horizontal_streamfunction`: Scalar function describing the streamlines of the horizontal wind
* `real(kind=kind_phys)`: units = m2 s-1
* `air_horizontal_velocity_potential`: Scalar potential of the wind
* `air_horizontal_velocity_potential`: Scalar potential of the horizontal wind
* `real(kind=kind_phys)`: units = m2 s-1
* `air_upward_absolute_vorticity`: The upward (kth) component of the curl of the vector wind field
* `real(kind=kind_phys)`: units = s-1
Expand Down Expand Up @@ -484,7 +484,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = 1
* `aerosol_aware_multiplicative_rain_conversion_parameter_for_shallow_convection`: Aerosol aware multiplicative rain conversion parameter for shallow convection
* `real(kind=kind_phys)`: units = 1
* `number_of_microphysics_varaibles_in_xy_dimensioned_restart_array`: Number of microphysics varaibles in xy dimensioned restart array
* `number_of_microphysics_variables_in_xy_dimensioned_restart_array`: Number of microphysics variables in xy dimensioned restart array
* `integer(kind=)`: units = count
* `number_of_microphysics_variables_in_xyz_dimensioned_restart_array`: Number of microphysics variables in xyz dimensioned restart array
* `integer(kind=)`: units = count
Expand Down Expand Up @@ -682,7 +682,7 @@ Variables related to the compute environment
* `integer(kind=)`: units = 1
* `control_for_land_surface_scheme_dynamic_vegetation`: Control for land surface scheme dynamic vegetation
* `integer(kind=)`: units = 1
* `indentifier_for_exponential_cloud_overlap_method`: Indentifier for exponential cloud overlap method
* `identifier_for_exponential_cloud_overlap_method`: Identifier for exponential cloud overlap method
* `integer(kind=)`: units = 1
* `identifier_for_exponential_random_cloud_overlap_method`: Identifier for exponential random cloud overlap method
* `integer(kind=)`: units = 1
Expand Down Expand Up @@ -848,7 +848,7 @@ Variables related to the compute environment
* `integer(kind=)`: units = 1
* `control_for_land_surface_scheme_runoff_and_groundwater`: Control for land surface scheme runoff and groundwater
* `integer(kind=)`: units = 1
* `identifer_for_scale_aware_mass_flux_deep_convection`: Identifer for scale aware mass flux deep convection
* `identifier_for_scale_aware_mass_flux_deep_convection`: Identifier for scale aware mass flux deep convection
* `integer(kind=)`: units = 1
* `identifier_for_scale_aware_mass_flux_shallow_convection`: Identifier for scale aware mass flux shallow convection
* `integer(kind=)`: units = 1
Expand Down Expand Up @@ -1068,7 +1068,7 @@ Variables related to the compute environment
* `integer(kind=)`: units = index
* `index_of_upward_virtual_potential_temperature_flux_in_xyz_dimensioned_restart_array`: Index of upward virtual potential temperature flux in xyz dimensioned restart array
* `integer(kind=)`: units = index
* `index_of_subgrid_cloud_area_fracation_in_atmosphere_layer_in_xyz_dimensioned_restart_array`: Index of subgrid cloud area fracation in atmosphere layer in xyz dimensioned restart array
* `index_of_subgrid_cloud_area_fraction_in_atmosphere_layer_in_xyz_dimensioned_restart_array`: Index of subgrid cloud area fraction in atmosphere layer in xyz dimensioned restart array
* `integer(kind=)`: units = index
* `index_of_timestep`: Index of timestep
* `integer(kind=)`: units = index
Expand Down Expand Up @@ -1098,7 +1098,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = m
* `do_allow_supersaturation_after_sedimentation`: Do allow supersaturation after sedimentation
* `logical(kind=)`: units = flag
* `autoconverion_to_snow_size_threshold`: Autoconverion to snow size threshold
* `autoconversion_to_snow_size_threshold`: Autoconversion to snow size threshold
* `real(kind=kind_phys)`: units = um
* `bergeron_findeisen_process_efficiency_factor`: Bergeron findeisen process efficiency factor
* `real(kind=kind_phys)`: units = fraction
Expand Down Expand Up @@ -1346,7 +1346,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = 1
* `total_amplitude_of_sppt_perturbation`: Total amplitude of sppt perturbation
* `real(kind=kind_phys)`: units = 1
* `do_turbulent_orographic_form_drag_in_unified_gravity_wave_physics_gravitiy_wave_drag_scheme`: Do turbulent orographic form drag in unified gravity wave physics gravitiy wave drag scheme
* `do_turbulent_orographic_form_drag_in_unified_gravity_wave_physics_gravity_wave_drag_scheme`: Do turbulent orographic form drag in unified gravity wave physics gravity wave drag scheme
* `logical(kind=)`: units = flag
* `updraft_area_fraction_in_scale_aware_tke_moist_edmf_pbl_scheme`: Updraft area fraction in scale aware tke moist edmf pbl scheme
* `real(kind=kind_phys)`: units = fraction
Expand Down Expand Up @@ -1516,7 +1516,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = K2
* `tendency_of_air_temperature_due_to_nonphysics`: Tendency of air temperature due to nonphysics
* `real(kind=kind_phys)`: units = K s-1
* `tendency_of_air_temperature_to_withold_from_sppt`: Tendency of air temperature to withold from sppt
* `tendency_of_air_temperature_to_withhold_from_sppt`: Tendency of air temperature to withhold from sppt
* `real(kind=kind_phys)`: units = K s-1
* `tendency_of_activated_cloud_condensation_nuclei_from_climatology`: Tendency of activated cloud condensation nuclei from climatology
* `real(kind=kind_phys)`: units = kg-1 s-1
Expand All @@ -1536,7 +1536,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = kg kg-1
* `weight_for_momentum_at_top_of_viscous_sublayer`: Weight for momentum at top of viscous sublayer
* `real(kind=kind_phys)`: units = 1
* `weight_for_potental_temperature_at_top_of_viscous_sublayer`: Weight for potental temperature at top of viscous sublayer
* `weight_for_potential_temperature_at_top_of_viscous_sublayer`: Weight for potential temperature at top of viscous sublayer
* `real(kind=kind_phys)`: units = 1
* `weight_for_specific_humidity_at_top_of_viscous_sublayer`: Weight for specific humidity at top of viscous sublayer
* `real(kind=kind_phys)`: units = 1
Expand Down Expand Up @@ -1862,7 +1862,7 @@ Variables related to the compute environment
## GFS_typedefs_GFS_coupling_type
* `cellular_automata_global_pattern_from_coupled_process`: Cellular automata global pattern from coupled process
* `real(kind=kind_phys)`: units = 1
* `convective_cloud_condesate_after_rainout`: Convective cloud condesate after rainout
* `convective_cloud_condensate_after_rainout`: Convective cloud condensate after rainout
* `real(kind=kind_phys)`: units = kg kg-1
* `cumulative_surface_downwelling_diffuse_nir_shortwave_flux_for_coupling_multiplied_by_timestep`: Cumulative surface downwelling diffuse nir shortwave flux for coupling multiplied by timestep
* `real(kind=kind_phys)`: units = J m-2
Expand All @@ -1876,7 +1876,7 @@ Variables related to the compute environment
* `real(kind=kind_phys)`: units = J m-2
* `cumulative_surface_downwelling_shortwave_flux_for_coupling_multiplied_by_timestep`: Cumulative surface downwelling shortwave flux for coupling multiplied by timestep
* `real(kind=kind_phys)`: units = J m-2
* `cumulative_surface_net_downwellling_diffuse_nir_shortwave_flux_for_coupling_multiplied_by_timestep`: Cumulative surface net downwellling diffuse nir shortwave flux for coupling multiplied by timestep
* `cumulative_surface_net_downwelling_diffuse_nir_shortwave_flux_for_coupling_multiplied_by_timestep`: Cumulative surface net downwelling diffuse nir shortwave flux for coupling multiplied by timestep
* `real(kind=kind_phys)`: units = J m-2
* `cumulative_surface_net_downwelling_diffuse_uv_and_vis_shortwave_flux_for_coupling_multiplied_by_timestep`: Cumulative surface net downwelling diffuse uv and vis shortwave flux for coupling multiplied by timestep
* `real(kind=kind_phys)`: units = J m-2
Expand Down
82 changes: 53 additions & 29 deletions StandardNamesRules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,26 +27,31 @@ CCPP Standard Name Rules
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 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.

[``component``] standard_name [*at* ``level``] [*in* ``medium``]
[*due_to* ``process``] [*assuming* ``condition``]

See the list of currently-used qualifiers below for help.
#. 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``] base_name [*at* ``level``] [*in* ``medium``] [*due_to* ``process``] [*assuming* ``condition``]

This construction was originally based on rules set forth in the
`CF guidelines <http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html>`_),
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 the medium
(e.g. for with air as the medium, 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 <#transformations>`_.
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:: https://raw.githubusercontent.com/wiki/ESCOMP/CCPPStandardNames/images/standard_name_construction_examples.png
:alt: image of table providing standard name construction examples

#. Variables are current and instantaneous unless specified. Variables that are not
current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
Expand Down Expand Up @@ -111,26 +116,29 @@ CCPP Standard Name Rules

#. 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
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 ``_xyz``
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:** surface_upward_specific_humidity_flux_for_mellor_yamada_janjic_surface_layer_scheme

**Preferred:** surface_upward_specific_humidity_flux

#. 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.
list of currently-used acronyms and 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 of ``ccpp`` in their name in order
to avoid any confusion.
#. Reserved names: The prefix ``ccpp_`` represents CCPP framework-provided variables.
All other standard names should avoid the use of ``ccpp`` in their name.

#. No punctuation should appear in standard names except for underscores (_).

Expand Down Expand Up @@ -386,9 +394,25 @@ Prefixes
| **sine_of** ``_X``
| **variance_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
---------------

Expand Down Expand Up @@ -494,9 +518,9 @@ standard names.
+-------------------------------------------+-----------------+
| heat_transport | W |
+-------------------------------------------+-----------------+
| horizontal_streamfunction | m2 s-1 |
| streamfunction | m2 s-1 |
+-------------------------------------------+-----------------+
| horizontal_velocity_potential | m2 s-1 |
| velocity_potential | m2 s-1 |
+-------------------------------------------+-----------------+
| mass | kg |
+-------------------------------------------+-----------------+
Expand Down Expand Up @@ -559,7 +583,7 @@ Acronyms, Abbreviations, and Aliases
+---------------------+---------------------------------------------------------+
| **Short** | **Meaning** |
+=====================+=========================================================+
| ir | infared |
| ir | infrared |
+---------------------+---------------------------------------------------------+
| lwe | liquid water equivalent |
+---------------------+---------------------------------------------------------+
Expand Down
Loading