diff --git a/.gitignore b/.gitignore index 0d20b64..073067c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *.pyc +docs/_build/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..0f4624e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,17 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index f7bf2e1..35fb967 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,10 @@ The Earth System Modeling Standard Names Repository contains community-accepted Standard Names, publishing tools, and search tools. -Rules governing the designation and format of standard names can be found in [StandardNamesRules.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst). +Rules governing the designation and format of standard names are published as a chaptered +Sphinx/Read the Docs site built from the [docs/](docs/) directory; see +[docs/index.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/docs/index.rst) for the +table of contents, or build it locally with `sphinx-build -b html docs docs/html`. A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [YAML version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml). diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst index 2672e01..521e134 100644 --- a/StandardNamesRules.rst +++ b/StandardNamesRules.rst @@ -1,736 +1,20 @@ -.. # define a hard line break for HTML -.. |br| raw:: html +Standard Name Rules Have Moved +=============================== -
+The ESM Standard Name rules have moved into a proper `Sphinx `_ +documentation set, built by `Read the Docs `_, so that they can be +organized into browsable chapters instead of one long file. -******************* -Earth System Modeling (ESM) Standard Names -******************* +The source for the rules now lives under `docs/chapters/ `_ in this repository: -This document contains information about the rules used to create Standard Names -for use with Earth System Models. It describes the +* `docs/chapters/naming_rules.rst `_ -- ESM Standard Name rules +* `docs/chapters/technical_specifications.rst `_ -- Technical specifications +* `docs/chapters/qualifiers.rst `_ -- Qualifiers +* `docs/chapters/common_components.rst `_ -- Other common standard name components +* `docs/chapters/aliases.rst `_ -- Acronyms, abbreviations, and aliases +* `docs/chapters/units.rst `_ -- Units -* ESM Standard Name rules -* Standard Name qualifiers -* Other common standard name components -* Acronyms, abbreviations, and aliases -* Units +See `docs/index.rst `_ for the table of contents, or build the docs locally with:: -.. _Rules - -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 - 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, 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 <#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 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 <#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 --------------- - -#. 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 - 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. - -#. 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_convective_whole_atmosphere_GWD`` - as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79. - -Terminology ------------ - - In this section we define terms that are used within these rules, the Standard Names, and their descriptions. - - `annotated image detailing some of the terminology in this section `_ - -#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical - centerpoint of a level, or the vertical average of a level, as defined by the host (see above). - An "interface" is the boundary at the top or bottom of a layer. - -#. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere - for a given vertical column. This can be land, ocean, ice, lake, etc. - - For variables describing properties of the atmosphere near/adjacent to the actual surface, - care should be taken to specify the specific "surface variable" quantity needed for a specific application: - - * ``[variable]_at_surface`` is the lowest interface of the atmospheric model, adjacent to the surface. - This is equivalent to the surface-adjacent/bottom interface (as described above). - * ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model - * ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m`` - - Note that some commonly used terms with a prefix ``surface_`` are unavoidable due to the common - definition being fundamentally different from unqualified ``X``. For example, ``surface_skin_temperature`` - is a fundamentally different quantity than the unqualified ``skin_temperature`` (as in the name - ``skin_temperature_at_toa``). In cases such as these, a comment should be included noting this - special usage of the word "surface". - -#. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas, - fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names - should default to using `ocean` unless part of one of the following phrases: - * sea_water - * sea_ice - * sea_level - * sea_salt - * sea_surface - * sea_floor - * sea_binary_mask - * sea_area - -#. 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*. - -#. 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 represents (e.g. *ice_cloud* if only including glaciated clouds, or - *cloud_at_500hPa* if only including clouds that exist at 500 hPa). - -#. Spell out acronyms unless they are defined in the list of "Acronyms, Abbreviations, and Aliases" - below. Whenever such an alias exist, use the alias in the - standard name and the full term in the description. - -#. 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`` - -#. 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`` - -#. For control-oriented variables, there are a few different prefixes that should be used depending on - the use case for that specific variable: - - +-------------------+-----------+-----------------------------------------------------------------------------------------------+ - | **Prefix** | **Type** | **Use case** | **Example** | - +===================+===========+=================================+=============================================================+ - | `is_` | `logical` | A flag indicating some state or | `is_mpi_root` indicates whether or not the code is running | - | | | condition is true or false | on the MPI root process | - +-------------------+-----------+-------------------------------- +-------------------------------------------------------------+ - | `do_` | `logical` | A flag whose value directs some | `do_chemical_tracer_diagnostics` indicates to a physics | - | | | behavior | scheme that it should compute chemical tracer diagnostics | - +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ - | `identifier_for_` | `integer` | A parameter indicating some | `identifier_for_noah_land_surface_scheme` is an integer | - | | | state or condition | identifying the Noah land surface model | - +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ - | `control_for_` | `integer` | A control whose value directs | `control_for_land_surface_scheme` is an integer identifying | - | | | some behavior | the land surface scheme type | - +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ - | `index_of_` | `integer` | An index entry for an array | `index_of_ice_vegetation_category` is an index describing | - | | | | the location of the ice vegetation category in the array of | - | | | | vegetation categories | - +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ - -#. The ``direction`` of a vector, unless noted otherwise, is the geographical bearing measured in the positive clockwise direction from due north. For example, ``wind_to_direction = 90`` is the same as ``wind_from_direction = 270``, meaning wind blowing towards the east. - -#. **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`` - -#. **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. - - -.. _tech_specs: - -Technical specifications -======================== - -#. 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 <#units>`_). For example, the element - for the variable name ``exner_function`` may look similar to this: - - - real - - - 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 <#units>`_ - for more details. - - The standard_name elements are grouped into sections by "section" elements. These are parsed out into human-readable sections - in the generated markdown file (``Metadata-standard-names.md``). Sections can contain nested sections for further categorization. - Standard Names should be sorted alphabetically by name within a given section. A python tool ``tools/sort_standard_names.py`` is - provided to sort the names automatically. - -#. 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). - -#. The `` element should include a value that is one of the following valid Fortran types: - - - ``integer`` - - ``real`` - - ``logical`` - - ``character`` - - ``complex`` - - ``ddt`` (derived data type) - -#. 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: - -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), as well as -reducing ambiguity between different uses of the word "surface" (see above). - -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 -| is -| do -| identifier_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 - -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 | -+------------------------+-------------------------------------------------------------------------------------+ -| interface | The vertical boundary of a model layer. | -+------------------------+-------------------------------------------------------------------------------------+ -| 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 | -+------------------------+-------------------------------------------------------------------------------------+ -| surface | The top of the solid or liquid medium below the atmosphere | -+------------------------+-------------------------------------------------------------------------------------+ -| 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) | -+------------------------+-------------------------------------------------------------------------------------+ - -.. _Aliases: - -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. | -+------------------------+-----------------------------------------------------------------------------------------------+ + python -m pip install -r docs/requirements.txt + sphinx-build -b html docs docs/html diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/chapters/aliases.rst b/docs/chapters/aliases.rst new file mode 100644 index 0000000..ad4684c --- /dev/null +++ b/docs/chapters/aliases.rst @@ -0,0 +1,67 @@ +.. _Aliases: + +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 | ++---------------------+---------------------------------------------------------+ diff --git a/docs/chapters/common_components.rst b/docs/chapters/common_components.rst new file mode 100644 index 0000000..f6dca9c --- /dev/null +++ b/docs/chapters/common_components.rst @@ -0,0 +1,57 @@ +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 | ++------------------------+-------------------------------------------------------------------------------------+ +| interface | The vertical boundary of a model layer. | ++------------------------+-------------------------------------------------------------------------------------+ +| 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 | ++------------------------+-------------------------------------------------------------------------------------+ +| surface | The top of the solid or liquid medium below the atmosphere | ++------------------------+-------------------------------------------------------------------------------------+ +| 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) | ++------------------------+-------------------------------------------------------------------------------------+ diff --git a/docs/chapters/naming_rules.rst b/docs/chapters/naming_rules.rst new file mode 100644 index 0000000..3bb144d --- /dev/null +++ b/docs/chapters/naming_rules.rst @@ -0,0 +1,270 @@ +.. _Rules: + +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 + 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, 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* or *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 :ref:`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. + + .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_construction_examples.png + :alt: Table of example standard names showing how each is built from a base name plus qualifiers such as component, medium, level, and process, according to the naming guideline template. + + Examples of standard names and how they are constructed with respect to the guideline template. + + 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 :ref:`section on Transformations ` + for more information), the above formula may be extended around multiple base names. + + .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_transformation_examples.png + :alt: Table of example standard names showing how the construction template extends around multiple base names when more than one transformation or quantity is involved. + + Examples of standard name construction for transformations involving multiple quantities. + + 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 +-------------- + +#. 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 + 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. + +#. 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_convective_whole_atmosphere_GWD`` + as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79. + +Terminology +----------- + + .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png + :alt: Annotated diagram illustrating standard-name terminology such as layer, interface, and surface as used throughout this section. + + Annotated diagram detailing some of the terminology used in this section. + +#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical + centerpoint of a level, or the vertical average of a level, as defined by the host (see above). + An "interface" is the boundary above or below a layer. + +#. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere + for a given vertical column. This can be land, ocean, ice, lake, etc. + + For variables describing properties of the atmosphere near/adjacent to the actual surface, + care should be taken to specify the specific "surface variable" quantity needed for a specific application: + + * ``[variable]_at_surface`` is the lowest interface of the atmospheric model, adjacent to the surface. + This is equivalent to the surface-adjacent/bottom interface (as described above). + * ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model + * ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m`` + + Note that some commonly used terms with a prefix ``surface_`` are unavoidable due to the common + definition being fundamentally different from unqualified ``X``. For example, ``surface_skin_temperature`` + is a fundamentally different quantity than the unqualified ``skin_temperature``. In cases such as these, + a comment should be included noting this special usage of the word "surface". + +#. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas, + fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names + should default to using `ocean` unless part of one of the following phrases: + + * ``sea_water`` + * ``sea_ice`` + * ``sea_level`` + * ``sea_salt`` + * ``sea_surface`` + * ``sea_floor`` + * ``sea_binary_mask`` + * ``sea_area`` + +.. _mixing_ratio: + +#. 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 are differing + conventions as to 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``. + +#. 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 :ref:`*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_X``. 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_X``. + +#. 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 represents (e.g. ``ice_cloud`` if only including glaciated clouds, or + ``cloud_at_500hPa`` if only including clouds that exist at 500 hPa). + +#. Spell out acronyms unless they are defined in the + :ref"`list of "Acronyms, Abbreviations, and Aliases" `. Whenever such an alias exists, + use the alias in the standard name and the full term in the description. + +#. 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`` + +#. 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`` + +#. For control-oriented variables, there are a few different prefixes that should be used depending on + the use case for that specific variable: + + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + | **Prefix** | **Type** | **Use case** | **Example** | + +===================+===========+=================================+=============================================================+ + | ``is_`` |``logical``| A flag indicating some state or | ``is_mpi_root`` indicates whether or not the code is running| + | | | condition is true or false | on the MPI root process | + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + | ``do_`` |``logical``| A flag whose value directs some | ``do_chemical_tracer_diagnostics`` indicates to a physics | + | | | behavior | scheme that it should compute chemical tracer diagnostics | + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + |``identifier_for_``|``integer``| A parameter indicating some | ``identifier_for_noah_land_surface_scheme`` is an integer | + | | | state or condition | identifying the Noah land surface model | + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + | ``control_for_`` |``integer``| A control whose value directs | ``control_for_land_surface_scheme`` is an integer | + | | | some behavior | identifying the land surface scheme type | + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + | ``index_of_`` |``integer``| An index entry for an array | ``index_of_ice_vegetation_category`` is an index describing | + | | | | the location of the ice vegetation category in the array of | + | | | | vegetation categories | + +-------------------+-----------+---------------------------------+-------------------------------------------------------------+ + +#. The ``direction`` of a vector, unless noted otherwise, is the geographical bearing measured in the positive clockwise direction from due north. For example, ``wind_to_direction = 90`` is the same as ``wind_from_direction = 270``, meaning wind blowing towards the east. + +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`` + +Reserved names +-------------- + +Currently there is only one "reserved" phrase that should only be used by a specific modeling +system component. Others may be added here in the future as needed. + +#. The prefix ``ccpp_`` is reserved for CCPP framework-provided variables. All other standard names + should avoid the use of ``ccpp`` in their name. diff --git a/docs/chapters/qualifiers.rst b/docs/chapters/qualifiers.rst new file mode 100644 index 0000000..22f54df --- /dev/null +++ b/docs/chapters/qualifiers.rst @@ -0,0 +1,261 @@ +.. _qualifiers: + +Qualifiers +======================== + + * ``X``, ``Y``, ``Z``, etc. = words or phrases to be substituted + * ``something[_optional]`` = "_optional" is an optional portion of the qualifier to include as needed + +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), as well as +reducing ambiguity between different uses of the word "surface" (see above). + +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_`` +| ``is_`` +| ``do_`` +| ``identifier_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`` + +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: + +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`` diff --git a/docs/chapters/technical_specifications.rst b/docs/chapters/technical_specifications.rst new file mode 100644 index 0000000..3d1e2d5 --- /dev/null +++ b/docs/chapters/technical_specifications.rst @@ -0,0 +1,45 @@ +.. _tech_specs: + +Technical specifications +======================== + +#. 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 :ref:`section on Units `). For example, the element + for the variable name ``exner_function`` may look similar to this:: + + + real + + + 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 :ref:`section on Units ` + for more details. + + The standard_name elements are grouped into sections by "section" elements. These are parsed out into human-readable sections + in the generated markdown file (``Metadata-standard-names.md``). Sections can contain nested sections for further categorization. + Standard Names should be sorted alphabetically by name within a given section. A python tool ``tools/sort_standard_names.py`` is + provided to sort the names automatically. + +#. 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). + +#. The `` element should include a value that is one of the following valid Fortran types: + + - ``integer`` + - ``real`` + - ``logical`` + - ``character`` + - ``complex`` + - ``ddt`` (derived data type) + +#. 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. diff --git a/docs/chapters/units.rst b/docs/chapters/units.rst new file mode 100644 index 0000000..1a24552 --- /dev/null +++ b/docs/chapters/units.rst @@ -0,0 +1,38 @@ +.. _units_section: + +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. | ++------------------------+-----------------------------------------------------------------------------------------------+ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..c3ad2ac --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,18 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +project = "ESM Standard Names" +copyright = "ESCOMP" +author = "ESCOMP" + +extensions = [] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------- + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7e21610 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,28 @@ +.. # define a hard line break for HTML +.. |br| raw:: html + +
+ +******************************************* +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 + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + chapters/naming_rules + chapters/technical_specifications + chapters/qualifiers + chapters/common_components + chapters/aliases + chapters/units diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..0126369 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx>=7.0 +sphinx_rtd_theme>=2.0 diff --git a/tools/write_standard_name_table.py b/tools/write_standard_name_table.py index 72a5f80..8b4c9b3 100755 --- a/tools/write_standard_name_table.py +++ b/tools/write_standard_name_table.py @@ -118,17 +118,9 @@ def parse_section(snl, sec, level='##'): snl.write(f'{level} {sec_name}\n') if sec_comment is not None: # First, squeeze out the spacing - while sec_comment.find(' ') >= 0: - sec_comment = sec_comment.replace(' ', ' ') - while sec_comment: - sec_comment = sec_comment.lstrip() - cind = sec_comment.find('\\n') - if cind > 0: - snl.write(f'{sec_comment[0:cind]}\n') - sec_comment = sec_comment[cind + 2:] - else: - snl.write(f'{sec_comment}\n') - sec_comment = '' + sec_comment = re.sub(' +', ' ', sec_comment) + for line in sec_comment.split('\\n'): + snl.write(f'{line.strip()}\n') for std_name in sec: if std_name.tag == 'section': parse_section(snl, std_name, level + '#')