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/Metadata-standard-names.md b/Metadata-standard-names.md index 2d3458a..5360554 100644 --- a/Metadata-standard-names.md +++ b/Metadata-standard-names.md @@ -41,7 +41,7 @@ The following names are too general to be chosen as standard names, but they can * `real`: units = kg m-3 * `energy`: Energy * `real`: units = J -* `energy_content`: Total energy within some surface +* `energy_content`: Total energy within some ideal surface * `real`: units = J m-2 * `energy_density`: Total energy within some volume * `real`: units = J m-3 @@ -64,6 +64,7 @@ The following names are too general to be chosen as standard names, but they can * `mass_transport`: Movement of some specified mass by advection * `real`: units = kg s-1 * `mixing_ratio`: A ratio of the amount of one substance to another; when unqualified refers to the ratio of the mass of one substance to the total mass in a given volume +* `comment`: See Standard Name Rules for further details about disambiguation of this term * `real`: units = kg kg-1 * `mole_flux`: The number of molecules or atoms of a substance traveling through an area per unit time * `real`: units = mol m-2 s-1 @@ -151,7 +152,7 @@ These names are used as bases for other names, but may also be considered standa * `air_temperature`: The temperature of air * Equivalent CF name: `air_temperature` * `real`: units = K -* `albedo`: The fraction of incident radiation reflected by a surface +* `albedo`: The fraction of incident radiation reflected by a physical surface * `real`: units = 1 * `atmosphere_heat_diffusivity`: Atmosphere heat diffusivity * Equivalent CF name: `atmosphere_heat_diffusivity` @@ -173,6 +174,7 @@ These names are used as bases for other names, but may also be considered standa * `diffuse_vis_albedo`: Albedo of diffuse incident visible radiation * `real`: units = 1 * `dimensionless_exner_function`: Dimensionless formulation of the Exner function with respect to 1000 hPa +* `comment`: The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the surface pressure as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. * Equivalent CF name: `dimensionless_exner_function` * `real`: units = 1 * `direct_nir_albedo`: Albedo of direct incident near-infrared radiation @@ -190,12 +192,13 @@ These names are used as bases for other names, but may also be considered standa * `dry_air_enthalpy_at_constant_pressure`: Specific enthalpy of dry air, h = Cp*T; Cp = Specific heat of dry air at constant pressure, T = temperature * `real`: units = J kg-1 * `exner_function`: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference pressure (1000 hPa if not specified), Rd is the dry air specific gas constant, and cp is the dry air specific heat capacity. +* `comment`: The formulation for the exner function comes in two forms: a dimensional form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp) = (T/theta). In the standard names, we use the unqualified exner_function to refer to the dimensional form, and dimensionless_exner_function to refer to the dimensionless form. See the base name entry for dimensionless_exner_function for further comments. * `real`: units = 1 * `filename`: Filename * `character`: units = none * `forecast_time`: Forecast time * `real`: units = h -* `friction_velocity`: A measure of shear stress within a fluid layer with units of distance per time +* `friction_velocity`: A measure of shear stress within a fluid layer due to friction against a surface, with units of distance per time * `real`: units = m s-1 * `geopotential`: Gravitational potential energy of a unit mass relative to sea level * Equivalent CF name: `geopotential` @@ -245,7 +248,8 @@ These names are used as bases for other names, but may also be considered standa * `solar_zenith_angle`: The angle between the direction to the sun and the local zenith (vertical direction) * Equivalent CF name: `solar_zenith_angle` * `real`: units = degrees -* `surface_skin_temperature`: The temperature of the topmost layer of the surface +* `surface_skin_temperature`: The temperature of the interface of the surface and the atmosphere +* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity, though for water specifically there may be special considerations for measured quantities (see comment on 'sea_surface_skin_temperature'). This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya. This quantity should not be confused with 'skin_temperature_at_toa' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'. * Equivalent CF name: `surface_skin_temperature` * `real`: units = K * `temperature_flux`: Flux of temperature across a unit surface @@ -273,6 +277,7 @@ These names are used as bases for other names, but may also be considered standa ## Dimensions Names indicating the size, extent, or bounds of data structures in a model. * `horizontal_dimension`: Length of the horizontal dimension +* `comment`: In CCPP, horizontal_dimension refers to all horizontal grid columns that an MPI process owns/is responsible for * `integer`: units = count * `horizontal_loop_extent`: The horizontal extent of data passed to CCPP physics from the host model during time integration (i.e. in the *run* phase) * `integer`: units = count @@ -401,7 +406,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `air_pressure_at_mean_sea_level`: Air pressure at mean sea level * Equivalent CF name: `air_pressure_at_mean_sea_level` * `real`: units = Pa -* `air_pressure_at_surface`: Air pressure at local surface +* `air_pressure_at_surface`: Air pressure at surface; i.e. surface pressure * Equivalent CF name: `surface_air_pressure` * `real`: units = Pa * `air_pressure_at_surface_adjacent_layer`: Air pressure at surface adjacent layer @@ -460,7 +465,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = 1 * `dimensionless_exner_function_at_surface_adjacent_layer`: Dimensionless exner function (p/p0)^(Rd/cp), where p0 is 1000 hPa and p is the pressure at the surface-adjacent layer * `real`: units = 1 -* `dimensionless_exner_function_wrt_surface_pressure`: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp) +* `dimensionless_exner_function_wrt_pressure_at_surface`: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp) * `real`: units = 1 * `dry_static_energy`: Dry static energy content of atmosphere layer * Equivalent CF name: `dry_static_energy_content_of_atmosphere_layer` @@ -543,6 +548,8 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = K * `potentially_advected_quantities`: Potentially advected quantities * `real`: units = various +* `pressure_of_dry_air_at_surface`: surface pressure of dry air + * `real`: units = Pa * `ratio_of_water_vapor_gas_constant_to_composition_dependent_dry_air_gas_constant_minus_one`: Ratio of gas constants of water vapor to composition-dependent dry air minus one; (Rwv / Rdair) - 1.0 * `real`: units = 1 * `reciprocal_of_air_pressure_thickness`: Reciprocal of air pressure thickness @@ -553,9 +560,11 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = 1 * `reference_air_pressure_normalized_by_air_pressure_at_surface`: reference pressure normalized by surface pressure * `real`: units = 1 +* `reference_pressure_at_surface`: Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.) + * `real`: units = Pa * `reference_pressure_in_atmosphere_layer`: Reference pressure in atmosphere layer * `real`: units = Pa -* `reference_pressure_in_atmosphere_layer_normalized_by_surface_reference_pressure`: Reference pressure in atmosphere layer normalized by surface reference pressure +* `reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface`: Reference pressure in atmosphere layer normalized by surface reference pressure * `real`: units = 1 * `relative_humidity_at_2m`: Relative humidity at 2m * `real`: units = fraction @@ -567,16 +576,12 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = kg kg-1 * `subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air`: Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air * `real`: units = kg kg-1 -* `surface_pressure_of_dry_air`: Surface pressure of dry air - * `real`: units = Pa -* `surface_reference_pressure`: Reference pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.) - * `real`: units = Pa * `timestep_for_physics`: Timestep for physics * `integer`: units = s * `upward_absolute_vorticity_of_air`: The upward (kth) component of the curl of the vector wind field * Equivalent CF name: `atmosphere_upward_absolute_vorticity` * `real`: units = s-1 -* `upward_heat_flux_in_air_at_surface`: Upward heat flux in air at surface +* `upward_heat_flux_in_air_at_surface`: Upward heat flux in air at surface interface * Equivalent CF name: `surface_upward_heat_flux_in_air` * `real`: units = W m-2 * `us_standard_air_pressure_at_mean_sea_level`: US Standard Atmospheric pressure at sea level @@ -599,7 +604,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = kg kg-1 * `water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array`: Specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in XYZ-dimensioned restart array * `real`: units = kg kg-1 -* `water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back`: Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back +* `water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back`: Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep * `real`: units = kg kg-1 * `wind_from_direction_at_10m`: Direction (clockwise from north) wind vector is pointing away from, at 10 meters above surface. * `real`: units = degrees @@ -655,6 +660,10 @@ Variables defining or relating to timing, dates, calendar, and related concepts * `real`: units = m * `reference_sea_surface_temperature`: Foundation/reference temperature for calculating diurnal ocean temperature changes * `real`: units = K +* `sea_surface_skin_temperature`: The temperature of the upper layer of sea surface, typically ~10-100 micrometers, as measured by an infrared radiometer +* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'sea_surface_skin_temperature', derived from the CF Standard Names. While there may be some dependence on the IR wavelength used for a measurement, per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface Skin Temperature Measurements for Climate Research', the difference should not be significant. This quantity should not be confused with 'skin_temperature_at_toa' or 'surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'. + * Equivalent CF name: `sea_surface_skin_temperature` + * `real`: units = K * `sea_surface_temperature`: Sea surface temperature * Equivalent CF name: `sea_surface_temperature` * `real`: units = K @@ -809,9 +818,9 @@ Tracers are numerically zero-mass particles advected in fluid flow, typically re * `real`: units = 1 * `aerosol_aware_multiplicative_rain_conversion_parameter_for_shallow_convection`: Aerosol aware multiplicative rain conversion parameter for shallow convection * `real`: units = 1 -* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Cloud condensed water mass mixing ratio with respect to moist air at surface over ice +* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Cloud condensed water mass mixing ratio with respect to moist air at surface interface over ice * `real`: units = kg kg-1 -* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land`: Cloud condensed water mass mixing ratio with respect to moist air at surface over land +* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land`: Cloud condensed water mass mixing ratio with respect to moist air at surface interface over land * `real`: units = kg kg-1 * `cloud_ice_mixing_ratio_wrt_dry_air`: Ratio of the mass of cloud ice to the mass of dry air * Equivalent CF name: `cloud_ice_mixing_ratio` @@ -1313,7 +1322,7 @@ Variables that indicate or control some action. * `real`: units = 1 * `control_for_vegetation_dataset`: Control for vegetation dataset * `integer`: units = 1 -* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from toa to surface, 1 indicates index from surface to toa +* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from top-of-atmosphere to surface, 1 indicates index from surface to top-of-atmosphere * `integer`: units = 1 * `do_aerosol_physics`: Do aerosol physics * `logical`: units = flag @@ -1629,9 +1638,9 @@ Values indicating the index of some array or other data structure * `real`: units = 1 * `cumulative_min_vertical_index_at_cloud_base_between_sw_radiation_calls`: Cumulative min vertical index at cloud base between sw radiation calls * `real`: units = 1 -* `index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of air pressure at surface on previous timestep in xyz dimensioned restart array +* `index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of surface pressure on previous timestep in xyz-dimensioned restart array * `integer`: units = index -* `index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array`: Index of air pressure at surface two timesteps back in xyz dimensioned tracer array +* `index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array`: Index of surface pressure two timesteps before the current timestep in xyz-dimensioned tracer array * `integer`: units = index * `index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of air temperature on previous timestep in xyz dimensioned restart array * `integer`: units = index @@ -1707,7 +1716,7 @@ Values indicating the index of some array or other data structure * `integer`: units = index * `index_of_water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in xyz dimensioned restart array * `integer`: units = index -* `index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back in xyz dimensioned restart array +* `index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep in xyz dimensioned restart array * `integer`: units = index * `index_of_water_vegetation_category`: Index of water vegetation category * `integer`: units = index @@ -1783,7 +1792,7 @@ Coefficients includes scaling factors, tunable parameters, and other similar var * `real`: units = 1 * `coefficient_w_d`: Coefficient w d * `real`: units = 1 -* `critical_relative_humidity_at_surface`: Critical relative humidity at surface +* `critical_relative_humidity_at_surface`: Critical relative humidity at the surface interface * `real`: units = fraction * `critical_relative_humidity_at_toa`: Critical relative humidity at the top of the atmosphere * `real`: units = fraction @@ -1895,7 +1904,7 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = m s-1 * `cloud_phase_transition_threshold_temperature`: Cloud phase transition threshold temperature * `real`: units = K -* `lower_bound_for_depth_of_sea_temperature_for_nsstm`: Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme +* `lower_bound_for_depth_of_ocean_temperature_for_nsstm`: Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme * `integer`: units = mm * `max_critical_relative_humidity`: Maximum critical relative humidity * `real`: units = fraction @@ -1935,7 +1944,7 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = fraction * `sigma_pressure_threshold_at_upper_extent_of_background_diffusion`: Sigma pressure threshold at upper extent of background diffusion * `real`: units = 1 -* `upper_bound_for_depth_of_sea_temperature_for_nsstm`: Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme +* `upper_bound_for_depth_of_ocean_temperature_for_nsstm`: Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme * `integer`: units = mm ## Stochastic physics variables * `atmosphere_heat_diffusivity_from_shoc`: Atmospheric heat diffusivity from Simplified Higher-Order Closure stochastic physics scheme @@ -2043,6 +2052,8 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = W m-2 * `downwelling_shortwave_flux_at_surface_on_radiation_timestep`: Downwelling shortwave flux at surface on radiation timestep * `real`: units = W m-2 +* `lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep`: longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep + * `ddt`: units = W m-2 * `net_downwelling_diffuse_nir_shortwave_flux_at_surface_for_coupling`: net downwelling diffuse near-infrared shortwave flux at the surface level for coupling * `real`: units = W m-2 * `net_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling`: net downwelling diffuse ultraviolet and visible shortwave flux at the surface level for coupling @@ -2095,10 +2106,11 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = W m-2 * `sine_of_solar_declination_angle`: Sine of solar declination angle * `real`: units = 1 +* `skin_temperature_at_toa`: The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium +* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'. + * `real`: units = K * `solar_constant`: Solar constant * `real`: units = W m-2 -* `surface_lw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep`: Surface lw fluxes assuming total and clear sky on radiation timestep - * `ddt`: units = W m-2 * `upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep * `real`: units = W m-2 * `upwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse ultraviolet and visible shortwave flux at the surface level on the radiation timestep @@ -2112,11 +2124,11 @@ Thresholds represent some value at which the behavior of some process changes, i * `upwelling_longwave_flux_at_surface_on_radiation_timestep`: Upwelling longwave flux at surface on radiation timestep * `real`: units = W m-2 ## Atmospheric surface and boundary layer -* `air_pressure_at_surface_for_coupling`: Air pressure at surface for coupling +* `air_pressure_at_surface_for_coupling`: Surface pressure for coupling * `real`: units = Pa -* `air_pressure_at_surface_on_previous_timestep`: Air pressure at surface on previous timestep +* `air_pressure_at_surface_on_previous_timestep`: Surface pressure on previous timestep * `real`: units = Pa -* `air_pressure_at_surface_two_timesteps_back`: Air pressure at surface two timesteps back +* `air_pressure_at_surface_two_timesteps_back`: Surface pressure two timesteps before the current timestep * `real`: units = Pa * `critical_relative_humidity_at_top_of_atmosphere_boundary_layer`: Critical relative humidity at top of atmosphere boundary layer * `real`: units = fraction @@ -2154,9 +2166,9 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = m * `updraft_area_fraction_in_scale_aware_tke_moist_edmf_pbl_scheme`: Updraft area fraction in scale-aware turbulent kinetic energy moist eddy-diffusivity/mass-flux planetary boundary layer scheme * `real`: units = fraction -* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface +* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface * `real`: units = kg kg-1 m s-1 -* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme`: Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface for MYJ surface layer scheme +* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme`: Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for MYJ surface layer scheme * `real`: units = m s-1 kg kg-1 * `upward_latent_heat_flux_at_surface_for_coupling`: Upward latent heat flux at surface for coupling * `real`: units = W m-2 @@ -2174,23 +2186,23 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = K m s-1 * `water_vapor_mixing_ratio_wrt_moist_air_at_2m_for_coupling`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at 2 meters above surface used for coupling * `real`: units = kg kg-1 -* `water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface +* `water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface * `real`: units = kg kg-1 -* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes`: Surface specific humidity (water vapor mass mixing ratio with respect to moist air) for Mellor-Yamada-Janjic physics schemes +* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for Mellor-Yamada-Janjic physics schemes * `real`: units = kg kg-1 * `water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at the top of the viscous sublayer * `real`: units = kg kg-1 -* `x_momentum_flux_at_surface_for_coupling`: X momentum flux at surface for coupling +* `x_momentum_flux_at_surface_for_coupling`: Momentum flux in the x-direction at the surface interface for coupling * `real`: units = Pa -* `x_momentum_flux_at_surface_from_coupled_process`: X momentum flux at surface from coupled process +* `x_momentum_flux_at_surface_from_coupled_process`: Momentum flux in the x-direction at the surface interface from a coupled process * `real`: units = Pa * `x_wind_at_10m_for_coupling`: X wind at 10m for coupling * `real`: units = m s-1 * `x_wind_at_top_of_viscous_sublayer`: X wind at top of viscous sublayer * `real`: units = m s-1 -* `y_momentum_flux_at_surface_for_coupling`: Y momentum flux at surface for coupling +* `y_momentum_flux_at_surface_for_coupling`: Momentum flux in the y-direction at the surface interface for coupling * `real`: units = Pa -* `y_momentum_flux_at_surface_from_coupled_process`: Y momentum flux at surface from coupled process +* `y_momentum_flux_at_surface_from_coupled_process`: Momentum flux in the y-direction at the surface interface from a coupled process * `real`: units = Pa * `y_wind_at_10m_for_coupling`: Y wind at 10m for coupling * `real`: units = m s-1 @@ -2280,6 +2292,11 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = g m-2 * `fine_root_mass_content`: Fine root mass content * `real`: units = g m-2 +* `friction_temperature`: Friction temperature, a.k.a. temperature scale +* `comment`: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u* + * `real`: units = K +* `friction_velocity_for_momentum`: Friction velocity for momentum + * `real`: units = m s-1 * `frozen_precipitation_density`: Frozen precipitation density * `real`: units = kg m-3 * `graupel_precipitation_rate_on_previous_timestep`: Graupel precipitation rate on previous timestep @@ -2308,9 +2325,9 @@ Thresholds represent some value at which the behavior of some process changes, i * `lwe_snowfall_rate`: Liquid water equivalent snowfall rate * Equivalent CF name: `lwe_snowfall_rate` * `real`: units = mm s-1 -* `lwe_surface_snow`: Liquid water equivalent surface snow +* `lwe_surface_snow`: Liquid water equivalent of snow accumulated on surface * `real`: units = mm -* `lwe_surface_snow_from_coupled_process`: Liquid water equivalent surface snow from coupled process +* `lwe_surface_snow_from_coupled_process`: Liquid water equivalent of snow accumulated on surface from coupled process * `real`: units = m * `lwe_thickness_of_convective_precipitation_on_previous_timestep`: Liquid water equivalent thickness of convective precipitation amount on previous timestep * `real`: units = m @@ -2318,11 +2335,11 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = m * `lwe_thickness_of_graupel_on_previous_timestep`: Liquid water equivalent thickness of graupel amount on previous timestep * `real`: units = m -* `lwe_thickness_of_ice_in_surface_snow`: Liquid water equivalent thickness of ice in surface snow +* `lwe_thickness_of_ice_in_surface_snow`: Liquid water equivalent thickness of ice in snow accumulated on surface * `real`: units = mm * `lwe_thickness_of_ice_precipitation_on_previous_timestep`: Liquid water equivalent thickness of ice precipitation amount on previous timestep * `real`: units = m -* `lwe_thickness_of_liquid_water_in_surface_snow`: Liquid water equivalent thickness of liquid water in surface snow +* `lwe_thickness_of_liquid_water_in_surface_snow`: Liquid water equivalent thickness of liquid water in snow accumulated on surface * `real`: units = mm * `lwe_thickness_of_rain_on_dynamics_timestep_for_coupling`: Liquid water equivalent thickness of rain amount on dynamics timestep for coupling * `real`: units = m @@ -2330,7 +2347,7 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = m * `lwe_thickness_of_snowfall_on_previous_timestep`: Liquid water equivalent thickness of snowfall amount on previous timestep * `real`: units = mm -* `lwe_thickness_of_surface_snow`: Liquid water equivalent thickness of surface snow amount +* `lwe_thickness_of_surface_snow`: Liquid water equivalent thickness of snow accumulated on surface * Equivalent CF name: `lwe_thickness_of_surface_snow_amount` * `real`: units = mm * `mass_content_of_water_in_top_soil_layer`: mass per unit area of water in top layer of soil @@ -2361,14 +2378,6 @@ Thresholds represent some value at which the behavior of some process changes, i * `sea_ice_thickness`: Sea ice thickness * Equivalent CF name: `sea_ice_thickness` * `real`: units = m -* `skin_temperature_at_surface_over_ice`: Skin temperature at surface over (or where) ice - * `real`: units = K -* `skin_temperature_at_surface_over_land`: Skin temperature at surface over (or where) land - * `real`: units = K -* `skin_temperature_at_surface_over_ocean`: Skin temperature at surface over (or where) ocean - * `real`: units = K -* `skin_temperature_at_surface_over_snow`: Skin temperature at surface over (or where) snow - * `real`: units = K * `slow_soil_pool_mass_content_of_carbon`: Slow soil pool mass content of carbon * Equivalent CF name: `slow_soil_pool_mass_content_of_carbon` * `real`: units = g m-2 @@ -2382,9 +2391,9 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = mm s-1 * `soil_temperature_for_lsm`: Soil temperature for land surface model * `real`: units = K -* `specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface +* `specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface * `real`: units = kg kg-1 m s-1 -* `specified_upward_temperature_flux_at_surface`: Specified upward temperature flux at surface +* `specified_upward_temperature_flux_at_surface`: Specified upward temperature flux at surface interface * `real`: units = K m s-1 * `standard_deviation_of_subgrid_orography`: Standard deviation of subgrid orography * `real`: units = m @@ -2396,10 +2405,6 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = g m-2 * `strong_cosz_area_fraction`: Area fraction for albedo with strong dependence on cosine of zenith angle * `real`: units = fraction -* `surface_friction_velocity`: Surface friction velocity - * `real`: units = m s-1 -* `surface_friction_velocity_for_momentum`: Surface friction velocity for momentum - * `real`: units = m s-1 * `surface_longwave_emissivity`: Surface longwave emissivity * Equivalent CF name: `surface_longwave_emissivity` * `real`: units = fraction @@ -2409,14 +2414,20 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = fraction * `surface_sensible_heat_due_to_rainfall`: Surface sensible heat due to rainfall * `real`: units = W +* `surface_skin_temperature_over_ice`: Surface skin temperature over (or where) ice + * `real`: units = K +* `surface_skin_temperature_over_land`: Surface skin temperature over (or where) land + * `real`: units = K +* `surface_skin_temperature_over_ocean`: Surface skin temperatura over (or where) ocean + * `real`: units = K +* `surface_skin_temperature_over_snow`: Surface skin temperature over (or where) snow + * `real`: units = K * `surface_snow_mass_content_over_ice`: Surface snow mass content over ice * `real`: units = kg m-2 * `surface_snow_mass_content_over_land`: Surface snow mass content over land * `real`: units = kg m-2 * `surface_sw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep`: Surface sw fluxes assuming total and clear sky on radiation timestep * `ddt`: units = W m-2 -* `surface_temperature_scale`: Surface temperature scale - * `real`: units = K * `temperature_in_ice_layer`: Temperature in ice layer * `real`: units = K * `temperature_in_surface_snow`: Temperature in surface snow @@ -2431,7 +2442,7 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = s * `upper_bound_of_max_albedo_assuming_deep_snow`: Upper bound of maximum albedo assuming deep snow * `real`: units = fraction -* `upward_latent_heat_flux_at_surface`: Upward latent heat flux at surface +* `upward_latent_heat_flux_at_surface`: Upward latent heat flux at surface interface * Equivalent CF name: `surface_upward_latent_heat_flux` * `real`: units = W m-2 * `urban_area_fraction_of_cell_area`: fraction of horizontal area of grid cell that is urban @@ -2480,9 +2491,9 @@ Thresholds represent some value at which the behavior of some process changes, i * `real`: units = kg kg-1 * `water_vapor_mixing_ratio_wrt_moist_air_at_2m`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at two meters above surface * `real`: units = kg kg-1 -* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over ice +* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over ice * `real`: units = kg kg-1 -* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over land +* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over land * `real`: units = kg kg-1 * `weak_cosz_area_fraction`: Area fraction for albedo with weak dependence on cosine of zenith angle * `real`: units = fraction diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml index 8879757..c3f56d5 100644 --- a/Metadata-standard-names.yaml +++ b/Metadata-standard-names.yaml @@ -37,7 +37,7 @@ section: type: real units: J - name: energy_content - description: Total energy within some surface + description: Total energy within some ideal surface type: real units: J m-2 - name: energy_density @@ -84,6 +84,8 @@ section: description: A ratio of the amount of one substance to another; when unqualified refers to the ratio of the mass of one substance to the total mass in a given volume + comment: See Standard Name Rules for further details about disambiguation of + this term type: real units: kg kg-1 - name: mole_flux @@ -266,7 +268,7 @@ section: type: real units: K - name: albedo - description: The fraction of incident radiation reflected by a surface + description: The fraction of incident radiation reflected by a physical surface type: real units: 1 - name: atmosphere_heat_diffusivity @@ -309,6 +311,15 @@ section: cfname: dimensionless_exner_function description: Dimensionless formulation of the Exner function with respect to 1000 hPa + comment: 'The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), + where p0 is some reference pressure. For the purposes of the standard names, + this reference pressure is assumed as 1000 hPa unless specified otherwise; + i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the + surface pressure as P0. Note that this is numerically equivalent to T/theta + (temperature divided by potential temperature), where again theta is calculated + with respect to 1000 hPa if not specified. Note that this definition is distinct + from the dimensional exner_function standard name; see that entry for further + comments. ' type: real units: 1 - name: direct_nir_albedo @@ -344,6 +355,12 @@ section: description: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference pressure (1000 hPa if not specified), Rd is the dry air specific gas constant, and cp is the dry air specific heat capacity. + comment: 'The formulation for the exner function comes in two forms: a dimensional + form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp) + = (T/theta). In the standard names, we use the unqualified exner_function + to refer to the dimensional form, and dimensionless_exner_function to refer + to the dimensionless form. See the base name entry for dimensionless_exner_function + for further comments.' type: real units: 1 - name: filename @@ -355,8 +372,8 @@ section: type: real units: h - name: friction_velocity - description: A measure of shear stress within a fluid layer with units of distance - per time + description: A measure of shear stress within a fluid layer due to friction + against a surface, with units of distance per time type: real units: m s-1 - name: geopotential @@ -457,7 +474,18 @@ section: units: degrees - name: surface_skin_temperature cfname: surface_skin_temperature - description: The temperature of the topmost layer of the surface + description: The temperature of the interface of the surface and the atmosphere + comment: 'Usage of the term ''skin temperature'' varies among different fields + in the literature. In the Standard Names we have adopted what we deem the + most common definition for ''surface_skin_temperature'': the temperature of + the interface of the atmosphere and the surface below. This may be considered + equivalent to the radiometric temperature derived from satellite or airborne + radiometers, provided a known surface_emissivity, though for water specifically + there may be special considerations for measured quantities (see comment on + ''sea_surface_skin_temperature''). This definition derives from discussion + in Chapter 4 of ''Introduction to Micrometeorology'' by S. Pal Arya. This + quantity should not be confused with ''skin_temperature_at_toa'' or ''sea_surface_skin_temperature'', + which are both sometimes referred to simply as ''skin_temperature''.' type: real units: K - name: temperature_flux @@ -509,6 +537,8 @@ section: standard_names: - name: horizontal_dimension description: Length of the horizontal dimension + comment: In CCPP, horizontal_dimension refers to all horizontal grid columns that + an MPI process owns/is responsible for type: integer units: count - name: horizontal_loop_extent @@ -765,7 +795,7 @@ section: units: Pa - name: air_pressure_at_surface cfname: surface_air_pressure - description: Air pressure at local surface + description: Air pressure at surface; i.e. surface pressure type: real units: Pa - name: air_pressure_at_surface_adjacent_layer @@ -882,7 +912,7 @@ section: and p is the pressure at the surface-adjacent layer type: real units: 1 - - name: dimensionless_exner_function_wrt_surface_pressure + - name: dimensionless_exner_function_wrt_pressure_at_surface description: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp) type: real units: 1 @@ -1046,6 +1076,10 @@ section: description: Potentially advected quantities type: real units: various + - name: pressure_of_dry_air_at_surface + description: surface pressure of dry air + type: real + units: Pa - name: ratio_of_water_vapor_gas_constant_to_composition_dependent_dry_air_gas_constant_minus_one description: Ratio of gas constants of water vapor to composition-dependent dry air minus one; (Rwv / Rdair) - 1.0 @@ -1068,11 +1102,16 @@ section: description: reference pressure normalized by surface pressure type: real units: 1 + - name: reference_pressure_at_surface + description: Reference surface air pressure used in definition of some other quantity + (e.g. potential temperature, Exner function, etc.) + type: real + units: Pa - name: reference_pressure_in_atmosphere_layer description: Reference pressure in atmosphere layer type: real units: Pa - - name: reference_pressure_in_atmosphere_layer_normalized_by_surface_reference_pressure + - name: reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface description: Reference pressure in atmosphere layer normalized by surface reference pressure type: real @@ -1098,15 +1137,6 @@ section: moist air type: real units: kg kg-1 - - name: surface_pressure_of_dry_air - description: Surface pressure of dry air - type: real - units: Pa - - name: surface_reference_pressure - description: Reference pressure used in definition of some other quantity (e.g. - potential temperature, Exner function, etc.) - type: real - units: Pa - name: timestep_for_physics description: Timestep for physics type: integer @@ -1118,7 +1148,7 @@ section: units: s-1 - name: upward_heat_flux_in_air_at_surface cfname: surface_upward_heat_flux_in_air - description: Upward heat flux in air at surface + description: Upward heat flux in air at surface interface type: real units: W m-2 - name: us_standard_air_pressure_at_mean_sea_level @@ -1167,7 +1197,7 @@ section: units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back description: Specific humidity (water vapor mass mixing ratio with respect to - moist air) two timesteps back + moist air) two timesteps before the current timestep type: real units: kg kg-1 - name: wind_from_direction_at_10m @@ -1287,6 +1317,21 @@ section: changes type: real units: K + - name: sea_surface_skin_temperature + cfname: sea_surface_skin_temperature + description: The temperature of the upper layer of sea surface, typically ~10-100 + micrometers, as measured by an infrared radiometer + comment: Usage of the term 'skin temperature' varies among different fields in + the literature. In the Standard Names we have adopted what we deem the most + common definition for 'sea_surface_skin_temperature', derived from the CF Standard + Names. While there may be some dependence on the IR wavelength used for a measurement, + per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface + Skin Temperature Measurements for Climate Research', the difference should not + be significant. This quantity should not be confused with 'skin_temperature_at_toa' + or 'surface_skin_temperature', which are both sometimes referred to simply as + 'skin_temperature'. + type: real + units: K - name: sea_surface_temperature cfname: sea_surface_temperature description: Sea surface temperature @@ -1607,12 +1652,12 @@ section: units: 1 - name: cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice description: Cloud condensed water mass mixing ratio with respect to moist air - at surface over ice + at surface interface over ice type: real units: kg kg-1 - name: cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land description: Cloud condensed water mass mixing ratio with respect to moist air - at surface over land + at surface interface over land type: real units: kg kg-1 - name: cloud_ice_mixing_ratio_wrt_dry_air @@ -2671,7 +2716,7 @@ section: units: 1 - name: control_for_vertical_index_direction description: control flag for direction of vertical index; 0 indicates index from - toa to surface, 1 indicates index from surface to toa + top-of-atmosphere to surface, 1 indicates index from surface to top-of-atmosphere type: integer units: 1 - name: do_aerosol_physics @@ -3329,13 +3374,13 @@ section: type: real units: 1 - name: index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array - description: Index of air pressure at surface on previous timestep in xyz dimensioned + description: Index of surface pressure on previous timestep in xyz-dimensioned restart array type: integer units: index - name: index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array - description: Index of air pressure at surface two timesteps back in xyz dimensioned - tracer array + description: Index of surface pressure two timesteps before the current timestep + in xyz-dimensioned tracer array type: integer units: index - name: index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array @@ -3513,7 +3558,8 @@ section: units: index - name: index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array description: Index of specific humidity (water vapor mass mixing ratio with respect - to moist air) two timesteps back in xyz dimensioned restart array + to moist air) two timesteps before the current timestep in xyz dimensioned restart + array type: integer units: index - name: index_of_water_vegetation_category @@ -3667,7 +3713,7 @@ section: type: real units: 1 - name: critical_relative_humidity_at_surface - description: Critical relative humidity at surface + description: Critical relative humidity at the surface interface type: real units: fraction - name: critical_relative_humidity_at_toa @@ -3911,7 +3957,7 @@ section: description: Cloud phase transition threshold temperature type: real units: K - - name: lower_bound_for_depth_of_sea_temperature_for_nsstm + - name: lower_bound_for_depth_of_ocean_temperature_for_nsstm description: Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme type: integer @@ -3998,7 +4044,7 @@ section: description: Sigma pressure threshold at upper extent of background diffusion type: real units: 1 - - name: upper_bound_for_depth_of_sea_temperature_for_nsstm + - name: upper_bound_for_depth_of_ocean_temperature_for_nsstm description: Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme type: integer @@ -4246,6 +4292,11 @@ section: description: Downwelling shortwave flux at surface on radiation timestep type: real units: W m-2 + - name: lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep + description: longwave total sky fluxes at surface interface, assuming clear sky, + on radiation timestep + type: ddt + units: W m-2 - name: net_downwelling_diffuse_nir_shortwave_flux_at_surface_for_coupling description: net downwelling diffuse near-infrared shortwave flux at the surface level for coupling @@ -4361,14 +4412,25 @@ section: description: Sine of solar declination angle type: real units: 1 + - name: skin_temperature_at_toa + description: The temperature that a theoretical infinitely thin air layer above + the atmosphere would have in radiative equilibrium + comment: Usage of the term 'skin temperature' varies among different fields in + the literature. In the Standard Names we have adopted what we deem the most + common definition for 'skin_temperature_at_toa', which is commonly referred + to as simply 'skin_temperature' but top-of-atmosphere is included in the name + for clarity and disambiguation. This definition is taken directly from Goessling + and Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating + model perspective', but very similar definitions can be found broadly in the + literature. This quantity should not be confused with 'surface_skin_temperature' + or 'sea_surface_skin_temperature', which are both sometimes referred to simply + as 'skin_temperature'. + type: real + units: K - name: solar_constant description: Solar constant type: real units: W m-2 - - name: surface_lw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep - description: Surface lw fluxes assuming total and clear sky on radiation timestep - type: ddt - units: W m-2 - name: upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep description: upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep @@ -4401,15 +4463,15 @@ section: comment: null standard_names: - name: air_pressure_at_surface_for_coupling - description: Air pressure at surface for coupling + description: Surface pressure for coupling type: real units: Pa - name: air_pressure_at_surface_on_previous_timestep - description: Air pressure at surface on previous timestep + description: Surface pressure on previous timestep type: real units: Pa - name: air_pressure_at_surface_two_timesteps_back - description: Air pressure at surface two timesteps back + description: Surface pressure two timesteps before the current timestep type: real units: Pa - name: critical_relative_humidity_at_top_of_atmosphere_boundary_layer @@ -4491,12 +4553,12 @@ section: units: fraction - name: upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface description: Upward specific humidity (water vapor mass mixing ratio with respect - to moist air) flux at surface + to moist air) flux at surface interface type: real units: kg kg-1 m s-1 - name: upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme description: Upward flux of specific humidity (water vapor mass mixing ratio with - respect to moist air) at surface for MYJ surface layer scheme + respect to moist air) at surface interface for MYJ surface layer scheme type: real units: m s-1 kg kg-1 - name: upward_latent_heat_flux_at_surface_for_coupling @@ -4534,12 +4596,12 @@ section: units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface description: Specific humidity (water vapor mass mixing ratio with respect to - moist air) at surface + moist air) at surface interface type: real units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes - description: Surface specific humidity (water vapor mass mixing ratio with respect - to moist air) for Mellor-Yamada-Janjic physics schemes + description: Specific humidity (water vapor mass mixing ratio with respect to + moist air) at surface interface for Mellor-Yamada-Janjic physics schemes type: real units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer @@ -4548,11 +4610,12 @@ section: type: real units: kg kg-1 - name: x_momentum_flux_at_surface_for_coupling - description: X momentum flux at surface for coupling + description: Momentum flux in the x-direction at the surface interface for coupling type: real units: Pa - name: x_momentum_flux_at_surface_from_coupled_process - description: X momentum flux at surface from coupled process + description: Momentum flux in the x-direction at the surface interface from a + coupled process type: real units: Pa - name: x_wind_at_10m_for_coupling @@ -4564,11 +4627,12 @@ section: type: real units: m s-1 - name: y_momentum_flux_at_surface_for_coupling - description: Y momentum flux at surface for coupling + description: Momentum flux in the y-direction at the surface interface for coupling type: real units: Pa - name: y_momentum_flux_at_surface_from_coupled_process - description: Y momentum flux at surface from coupled process + description: Momentum flux in the y-direction at the surface interface from a + coupled process type: real units: Pa - name: y_wind_at_10m_for_coupling @@ -4748,6 +4812,17 @@ section: description: Fine root mass content type: real units: g m-2 + - name: friction_temperature + description: Friction temperature, a.k.a. temperature scale + comment: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer + Scheme' as negative sensible heat flux divided by the product of density, specific + heat Cp, and friction velocity u* + type: real + units: K + - name: friction_velocity_for_momentum + description: Friction velocity for momentum + type: real + units: m s-1 - name: frozen_precipitation_density description: Frozen precipitation density type: real @@ -4801,11 +4876,12 @@ section: type: real units: mm s-1 - name: lwe_surface_snow - description: Liquid water equivalent surface snow + description: Liquid water equivalent of snow accumulated on surface type: real units: mm - name: lwe_surface_snow_from_coupled_process - description: Liquid water equivalent surface snow from coupled process + description: Liquid water equivalent of snow accumulated on surface from coupled + process type: real units: m - name: lwe_thickness_of_convective_precipitation_on_previous_timestep @@ -4823,7 +4899,7 @@ section: type: real units: m - name: lwe_thickness_of_ice_in_surface_snow - description: Liquid water equivalent thickness of ice in surface snow + description: Liquid water equivalent thickness of ice in snow accumulated on surface type: real units: mm - name: lwe_thickness_of_ice_precipitation_on_previous_timestep @@ -4832,7 +4908,8 @@ section: type: real units: m - name: lwe_thickness_of_liquid_water_in_surface_snow - description: Liquid water equivalent thickness of liquid water in surface snow + description: Liquid water equivalent thickness of liquid water in snow accumulated + on surface type: real units: mm - name: lwe_thickness_of_rain_on_dynamics_timestep_for_coupling @@ -4852,7 +4929,7 @@ section: units: mm - name: lwe_thickness_of_surface_snow cfname: lwe_thickness_of_surface_snow_amount - description: Liquid water equivalent thickness of surface snow amount + description: Liquid water equivalent thickness of snow accumulated on surface type: real units: mm - name: mass_content_of_water_in_top_soil_layer @@ -4912,22 +4989,6 @@ section: description: Sea ice thickness type: real units: m - - name: skin_temperature_at_surface_over_ice - description: Skin temperature at surface over (or where) ice - type: real - units: K - - name: skin_temperature_at_surface_over_land - description: Skin temperature at surface over (or where) land - type: real - units: K - - name: skin_temperature_at_surface_over_ocean - description: Skin temperature at surface over (or where) ocean - type: real - units: K - - name: skin_temperature_at_surface_over_snow - description: Skin temperature at surface over (or where) snow - type: real - units: K - name: slow_soil_pool_mass_content_of_carbon cfname: slow_soil_pool_mass_content_of_carbon description: Slow soil pool mass content of carbon @@ -4955,11 +5016,11 @@ section: units: K - name: specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface description: Specified upward specific humidity (water vapor mass mixing ratio - with respect to moist air) flux at surface + with respect to moist air) flux at surface interface type: real units: kg kg-1 m s-1 - name: specified_upward_temperature_flux_at_surface - description: Specified upward temperature flux at surface + description: Specified upward temperature flux at surface interface type: real units: K m s-1 - name: standard_deviation_of_subgrid_orography @@ -4983,14 +5044,6 @@ section: angle type: real units: fraction - - name: surface_friction_velocity - description: Surface friction velocity - type: real - units: m s-1 - - name: surface_friction_velocity_for_momentum - description: Surface friction velocity for momentum - type: real - units: m s-1 - name: surface_longwave_emissivity cfname: surface_longwave_emissivity description: Surface longwave emissivity @@ -5008,6 +5061,22 @@ section: description: Surface sensible heat due to rainfall type: real units: W + - name: surface_skin_temperature_over_ice + description: Surface skin temperature over (or where) ice + type: real + units: K + - name: surface_skin_temperature_over_land + description: Surface skin temperature over (or where) land + type: real + units: K + - name: surface_skin_temperature_over_ocean + description: Surface skin temperatura over (or where) ocean + type: real + units: K + - name: surface_skin_temperature_over_snow + description: Surface skin temperature over (or where) snow + type: real + units: K - name: surface_snow_mass_content_over_ice description: Surface snow mass content over ice type: real @@ -5020,10 +5089,6 @@ section: description: Surface sw fluxes assuming total and clear sky on radiation timestep type: ddt units: W m-2 - - name: surface_temperature_scale - description: Surface temperature scale - type: real - units: K - name: temperature_in_ice_layer description: Temperature in ice layer type: real @@ -5054,7 +5119,7 @@ section: units: fraction - name: upward_latent_heat_flux_at_surface cfname: surface_upward_latent_heat_flux - description: Upward latent heat flux at surface + description: Upward latent heat flux at surface interface type: real units: W m-2 - name: urban_area_fraction_of_cell_area @@ -5153,12 +5218,12 @@ section: units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice description: Specific humidity (water vapor mass mixing ratio with respect to - moist air) at surface over ice + moist air) at surface interface over ice type: real units: kg kg-1 - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land description: Specific humidity (water vapor mass mixing ratio with respect to - moist air) at surface over land + moist air) at surface interface over land type: real units: kg kg-1 - name: weak_cosz_area_fraction 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 44e8d66..521e134 100644 --- a/StandardNamesRules.rst +++ b/StandardNamesRules.rst @@ -1,697 +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 ------------ - -#. 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 obvious to a vast majority of - scientists/developers who may come across them. A list of currently-used - aliases is below. Whenever such an alias exist, use the alias in the - standard name and the full term in the description. - -#. 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). - -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 | -+------------------------+-------------------------------------------------------------------------------------+ -| 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/standard_names.xml b/standard_names.xml index 92723cc..6792042 100644 --- a/standard_names.xml +++ b/standard_names.xml @@ -21,7 +21,7 @@ real - + real @@ -196,7 +196,7 @@ air_temperature real - + real @@ -228,7 +228,7 @@ real - + dimensionless_exner_function real @@ -262,7 +262,7 @@ real - + real @@ -338,7 +338,7 @@ solar_zenith_angle real - + surface_skin_temperature real @@ -568,7 +568,7 @@ air_pressure_at_mean_sea_level real - + surface_air_pressure real @@ -655,7 +655,7 @@ real - + real @@ -776,6 +776,9 @@ real + + real + real @@ -791,10 +794,13 @@ real + + real + real - + real @@ -812,12 +818,6 @@ real - - real - - - real - integer @@ -825,7 +825,7 @@ atmosphere_upward_absolute_vorticity real - + surface_upward_heat_flux_in_air real @@ -859,7 +859,7 @@ real - + real @@ -942,6 +942,10 @@ real + + sea_surface_skin_temperature + real + sea_surface_temperature real @@ -1167,10 +1171,10 @@ real - + real - + real @@ -1916,7 +1920,7 @@ integer - + integer @@ -2389,10 +2393,10 @@ real - + integer - + integer @@ -2506,7 +2510,7 @@ integer - + integer @@ -2619,7 +2623,7 @@ real - + real @@ -2786,7 +2790,7 @@ real - + integer @@ -2846,7 +2850,7 @@ real - + integer @@ -3009,6 +3013,9 @@ real + + ddt + real @@ -3087,12 +3094,12 @@ real + + real + real - - ddt - real @@ -3113,13 +3120,13 @@
- + real - + real - + real @@ -3176,10 +3183,10 @@ real - + real - + real @@ -3206,19 +3213,19 @@ real - + real - + real real - + real - + real @@ -3227,10 +3234,10 @@ real - + real - + real @@ -3363,6 +3370,12 @@ real + + real + + + real + real @@ -3403,10 +3416,10 @@ lwe_snowfall_rate real - + real - + real @@ -3418,13 +3431,13 @@ real - + real real - + real @@ -3436,7 +3449,7 @@ real - + lwe_thickness_of_surface_snow_amount real @@ -3481,18 +3494,6 @@ sea_ice_thickness real - - real - - - real - - - real - - - real - slow_soil_pool_mass_content_of_carbon real @@ -3512,10 +3513,10 @@ real - + real - + real @@ -3533,12 +3534,6 @@ real - - real - - - real - surface_longwave_emissivity real @@ -3552,6 +3547,18 @@ real + + real + + + real + + + real + + + real + real @@ -3561,9 +3568,6 @@ ddt - - real - real @@ -3585,7 +3589,7 @@ real - + surface_upward_latent_heat_flux real @@ -3657,10 +3661,10 @@ real - + real - + real diff --git a/tools/write_standard_name_table.py b/tools/write_standard_name_table.py index 72a5f80..bca9de3 100755 --- a/tools/write_standard_name_table.py +++ b/tools/write_standard_name_table.py @@ -118,27 +118,22 @@ 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 + '#') continue stdn_name = std_name.get('name') stdn_description = std_name.get('description') + stdn_comment = std_name.get('comment') if stdn_description is None: sdict = {'standard_name': stdn_name} stdn_description = standard_name_to_description(sdict) snl.write(f"* `{stdn_name}`: {stdn_description}\n") + if stdn_comment is not None: + snl.write(f"* `comment`: {stdn_comment}\n") # Should only be type or cfname as subelements of standard_name for item in std_name: if item.tag == 'cfname': @@ -194,12 +189,14 @@ def parse_section_for_yaml(section): stdn_description = standard_name_to_description(sdict) std_type = std_name.find('type') - + std_comment = std_name.get('comment') std_name_data = OrderedDict() std_name_data['name'] = stdn_name if stdn_cfname: std_name_data['cfname'] = stdn_cfname std_name_data['description'] = stdn_description + if std_comment is not None: + std_name_data['comment'] = std_comment if std_type is not None: std_name_data['type'] = std_type.text