Resolve issues: #24, #64, #82, #118, other fixes (#148)

## Description
Resolving several open issues and items noted on previous PRs:

 - Fix #24
   - Renaming "vertical_layer_dimension" to just "vertical_dimension" for consistency with other dimension names
   - Add a definition of "interface" for clarity
 - Fix #64
   - Replacing the use of  "volumetric" with "volume_fraction" where appropriate
 - Resolve #82 
   - Changed all mentions of "sea level" to "mean sea level" for clarity and consistency with CF standard names
 - Finish fixing #118 
   - Changing the remaining format statements to f-strings
 - Other fixes
   - Updating github action versions per comments on #145 
   - More appropriate error types for exceptions raised in `tools/lib/xml_tools.py`
   - Remove @mwaxmonsky and @mattldawson from CODEOWNERS


## Issues
Resolves #24, #64, #82, #118

Author: mkavulich

.github/workflows/pull_request_ci.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
 
@@ -34,7 +34,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install dependencies
         run: |
@@ -50,10 +50,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
 
@@ -74,10 +74,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
 
@@ -95,10 +95,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
 

CODEOWNERS

@@ -3,7 +3,7 @@
 
 # These owners will be the default owners for everything in the repo.
 
-*       @cacraigucar @climbfuji @dustinswales @grantfirl @mattldawson @mkavulich @mwaxmonsky @nusbaume @peverwhee @MarekWlasak @svahl991 @ss421
+*       @cacraigucar @climbfuji @dustinswales @grantfirl @mkavulich @nusbaume @peverwhee @MarekWlasak @svahl991 @ss421
 
 # Order is important. The last matching pattern has the most precedence.
 # So if a pull request only touches javascript files, only these owners

Metadata-standard-names.md

@@ -286,8 +286,14 @@ Names indicating the size, extent, or bounds of data structures in a model.
     * `real`: units = 1
 * `upper_bound_of_vertical_dimension_of_surface_snow`: upper bound of of snow-related arrays for land surface model
     * `integer`: units = count
+* `vertical_dimension`: number of vertical layers
+    * `integer`: units = count
+* `vertical_dimension_extended_up_by_1`: number of vertical layers extended up by 1
+    * `integer`: units = count
 * `vertical_dimension_for_radiation`: Vertical dimension for radiation
     * `integer`: units = count
+* `vertical_dimension_minus_one`: Vertical dimension minus one
+    * `integer`: units = count
 * `vertical_dimension_of_sea_ice`: Vertical dimension of sea ice
     * `integer`: units = count
 * `vertical_dimension_of_soil`: Vertical dimension of soil
@@ -302,12 +308,6 @@ Names indicating the size, extent, or bounds of data structures in a model.
     * `integer`: units = count
 * `vertical_interface_dimension_interstitial`: Vertical interface dimension interstitial
     * `integer`: units = count
-* `vertical_layer_dimension`: number of vertical layers
-    * `integer`: units = count
-* `vertical_layer_dimension_extended_up_by_1`: number of vertical layers extended up by 1
-    * `integer`: units = count
-* `vertical_layer_dimension_minus_one`: Vertical layer dimension minus one
-    * `integer`: units = count
 ## Constants
 Constant parameters that should be identical across a full modeling system
 * `avogadro_number`: Avogadro number
@@ -398,7 +398,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = Pa
 * `air_pressure_at_lowest_model_interface`: Air pressure at lowest model interface
     * `real`: units = Pa
-* `air_pressure_at_sea_level`: Air pressure at sea level
+* `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
@@ -579,7 +579,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
 * `upward_heat_flux_in_air_at_surface`: Upward heat flux in air at surface
     * Equivalent CF name: `surface_upward_heat_flux_in_air`
     * `real`: units = W m-2
-* `us_standard_air_pressure_at_sea_level`: US Standard Atmospheric pressure at sea level
+* `us_standard_air_pressure_at_mean_sea_level`: US Standard Atmospheric pressure at sea level
     * `real`: units = Pa
 * `variance_of_air_temperature`: Variance of air temperature
     * `real`: units = K2
@@ -2434,6 +2434,8 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `volume_fraction_of_condensed_water_in_soil`: Volume fraction of condensed water in soil
     * Equivalent CF name: `volume_fraction_of_condensed_water_in_soil`
     * `real`: units = fraction
+* `volume_fraction_of_equilibrium_soil_moisture`: Volume fraction of equilibrium soil moisture
+    * `real`: units = fraction
 * `volume_fraction_of_frozen_soil_moisture_for_lsm`: Volume fraction of frozen soil moisture for land surface model
     * `real`: units = fraction
 * `volume_fraction_of_liquid_water_in_soil_at_critical_point`: volume fraction of water in liquid phase in soil at critical point
@@ -2442,16 +2444,14 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = m3 m-3
 * `volume_fraction_of_liquid_water_in_soil_at_wilting_point`: volume fraction of water in liquid phase in soil at wilting point
     * `real`: units = m3 m-3
+* `volume_fraction_of_soil_moisture_between_soil_bottom_and_water_table`: Volume fraction of soil moisture between soil bottom and water table
+    * `real`: units = fraction
 * `volume_fraction_of_soil_moisture_for_lsm`: Volume fraction of soil moisture for land surface model
     * `real`: units = fraction
 * `volume_fraction_of_unfrozen_soil_moisture_for_lsm`: Volume fraction of unfrozen soil moisture for land surface model
     * `real`: units = fraction
 * `volume_fraction_of_unfrozen_water_in_soil`: Volume fraction of unfrozen water in soil
     * `real`: units = fraction
-* `volumetric_equilibrium_soil_moisture`: Volumetric equilibrium soil moisture
-    * `real`: units = m3 m-3
-* `volumetric_soil_moisture_between_soil_bottom_and_water_table`: Volumetric soil moisture between soil bottom and water table
-    * `real`: units = m3 m-3
 * `water_storage_in_aquifer`: Water storage in aquifer
     * `real`: units = mm
 * `water_storage_in_aquifer_and_saturated_soil`: Water storage in aquifer and saturated soil

Metadata-standard-names.yaml

@@ -536,10 +536,22 @@ section:
     description: upper bound of of snow-related arrays for land surface model
     type: integer
     units: count
+  - name: vertical_dimension
+    description: number of vertical layers
+    type: integer
+    units: count
+  - name: vertical_dimension_extended_up_by_1
+    description: number of vertical layers extended up by 1
+    type: integer
+    units: count
   - name: vertical_dimension_for_radiation
     description: Vertical dimension for radiation
     type: integer
     units: count
+  - name: vertical_dimension_minus_one
+    description: Vertical dimension minus one
+    type: integer
+    units: count
   - name: vertical_dimension_of_sea_ice
     description: Vertical dimension of sea ice
     type: integer
@@ -568,18 +580,6 @@ section:
     description: Vertical interface dimension interstitial
     type: integer
     units: count
-  - name: vertical_layer_dimension
-    description: number of vertical layers
-    type: integer
-    units: count
-  - name: vertical_layer_dimension_extended_up_by_1
-    description: number of vertical layers extended up by 1
-    type: integer
-    units: count
-  - name: vertical_layer_dimension_minus_one
-    description: Vertical layer dimension minus one
-    type: integer
-    units: count
 - name: Constants
   comment: Constant parameters that should be identical across a full modeling system
   standard_names:
@@ -758,9 +758,9 @@ section:
     description: Air pressure at lowest model interface
     type: real
     units: Pa
-  - name: air_pressure_at_sea_level
+  - name: air_pressure_at_mean_sea_level
     cfname: air_pressure_at_mean_sea_level
-    description: Air pressure at sea level
+    description: Air pressure at mean sea level
     type: real
     units: Pa
   - name: air_pressure_at_surface
@@ -1121,7 +1121,7 @@ section:
     description: Upward heat flux in air at surface
     type: real
     units: W m-2
-  - name: us_standard_air_pressure_at_sea_level
+  - name: us_standard_air_pressure_at_mean_sea_level
     description: US Standard Atmospheric pressure at sea level
     type: real
     units: Pa
@@ -5049,6 +5049,10 @@ section:
     description: Volume fraction of condensed water in soil
     type: real
     units: fraction
+  - name: volume_fraction_of_equilibrium_soil_moisture
+    description: Volume fraction of equilibrium soil moisture
+    type: real
+    units: fraction
   - name: volume_fraction_of_frozen_soil_moisture_for_lsm
     description: Volume fraction of frozen soil moisture for land surface model
     type: real
@@ -5065,6 +5069,10 @@ section:
     description: volume fraction of water in liquid phase in soil at wilting point
     type: real
     units: m3 m-3
+  - name: volume_fraction_of_soil_moisture_between_soil_bottom_and_water_table
+    description: Volume fraction of soil moisture between soil bottom and water table
+    type: real
+    units: fraction
   - name: volume_fraction_of_soil_moisture_for_lsm
     description: Volume fraction of soil moisture for land surface model
     type: real
@@ -5077,14 +5085,6 @@ section:
     description: Volume fraction of unfrozen water in soil
     type: real
     units: fraction
-  - name: volumetric_equilibrium_soil_moisture
-    description: Volumetric equilibrium soil moisture
-    type: real
-    units: m3 m-3
-  - name: volumetric_soil_moisture_between_soil_bottom_and_water_table
-    description: Volumetric soil moisture between soil bottom and water table
-    type: real
-    units: m3 m-3
   - name: water_storage_in_aquifer
     description: Water storage in aquifer
     type: real

StandardNamesRules.rst

@@ -544,6 +544,8 @@ Special phrases
 +------------------------+-------------------------------------------------------------------------------------+
 | 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                                               |

standard_names.xml

@@ -401,9 +401,18 @@
     <standard_name name="upper_bound_of_vertical_dimension_of_surface_snow" description="upper bound of of snow-related arrays for land surface model">
       <type units="count">integer</type>
     </standard_name>
+    <standard_name name="vertical_dimension" description="number of vertical layers">
+      <type units="count">integer</type>
+    </standard_name>
+    <standard_name name="vertical_dimension_extended_up_by_1" description="number of vertical layers extended up by 1">
+      <type units="count">integer</type>
+    </standard_name>
     <standard_name name="vertical_dimension_for_radiation">
       <type units="count">integer</type>
     </standard_name>
+    <standard_name name="vertical_dimension_minus_one">
+      <type units="count">integer</type>
+    </standard_name>
     <standard_name name="vertical_dimension_of_sea_ice">
       <type units="count">integer</type>
     </standard_name>
@@ -425,15 +434,6 @@
     <standard_name name="vertical_interface_dimension_interstitial">
       <type units="count">integer</type>
     </standard_name>
-    <standard_name name="vertical_layer_dimension" description="number of vertical layers">
-      <type units="count">integer</type>
-    </standard_name>
-    <standard_name name="vertical_layer_dimension_extended_up_by_1" description="number of vertical layers extended up by 1">
-      <type units="count">integer</type>
-    </standard_name>
-    <standard_name name="vertical_layer_dimension_minus_one">
-      <type units="count">integer</type>
-    </standard_name>
   </section>
   <section name="Constants" comment="Constant parameters that should be identical across a full modeling system">
     <standard_name name="avogadro_number">
@@ -564,7 +564,7 @@
     <standard_name name="air_pressure_at_lowest_model_interface">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_sea_level">
+    <standard_name name="air_pressure_at_mean_sea_level">
       <cfname>air_pressure_at_mean_sea_level</cfname>
       <type units="Pa">real</type>
     </standard_name>
@@ -829,7 +829,7 @@
       <cfname>surface_upward_heat_flux_in_air</cfname>
       <type units="W m-2">real</type>
     </standard_name>
-    <standard_name name="us_standard_air_pressure_at_sea_level" description="US Standard Atmospheric pressure at sea level">
+    <standard_name name="us_standard_air_pressure_at_mean_sea_level" description="US Standard Atmospheric pressure at sea level">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="variance_of_air_temperature">
@@ -3588,6 +3588,9 @@
       <cfname>volume_fraction_of_condensed_water_in_soil</cfname>
       <type units="fraction">real</type>
     </standard_name>
+    <standard_name name="volume_fraction_of_equilibrium_soil_moisture">
+      <type units="fraction">real</type>
+    </standard_name>
     <standard_name name="volume_fraction_of_frozen_soil_moisture_for_lsm" description="Volume fraction of frozen soil moisture for land surface model">
       <type units="fraction">real</type>
     </standard_name>
@@ -3600,6 +3603,9 @@
     <standard_name name="volume_fraction_of_liquid_water_in_soil_at_wilting_point" description="volume fraction of water in liquid phase in soil at wilting point">
       <type units="m3 m-3">real</type>
     </standard_name>
+    <standard_name name="volume_fraction_of_soil_moisture_between_soil_bottom_and_water_table">
+      <type units="fraction">real</type>
+    </standard_name>
     <standard_name name="volume_fraction_of_soil_moisture_for_lsm" description="Volume fraction of soil moisture for land surface model">
       <type units="fraction">real</type>
     </standard_name>
@@ -3609,12 +3615,6 @@
     <standard_name name="volume_fraction_of_unfrozen_water_in_soil">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="volumetric_equilibrium_soil_moisture">
-      <type units="m3 m-3">real</type>
-    </standard_name>
-    <standard_name name="volumetric_soil_moisture_between_soil_bottom_and_water_table">
-      <type units="m3 m-3">real</type>
-    </standard_name>
     <standard_name name="water_storage_in_aquifer">
       <type units="mm">real</type>
     </standard_name>

tools/lib/xml_tools.py

@@ -64,26 +64,20 @@ def validate_xml_file(filename, schema_file, logger, error_on_noxmllint=False):
     """
     # Check the filename
     if not os.path.isfile(filename):
-        raise ValueError(f"validate_xml_file: Filename, '{filename}', does not exist")
-    if not os.access(filename, os.R_OK):
-        raise ValueError(f"validate_xml_file: Cannot open '{filename}'")
+        raise FileNotFoundError(f"validate_xml_file: Filename, '{filename}', does not exist")
     if not os.path.isfile(schema_file):
-        raise ValueError(f"validate_xml_file: Cannot find schema file {schema_file}")
-    if not os.access(schema_file, os.R_OK):
-        emsg = "validate_xml_file: Cannot open schema, '{}'"
-        raise ValueError(emsg.format(schema_file))
+        raise FileNotFoundError(f"validate_xml_file: Cannot find schema file '{schema_file}' ")
     if _XMLLINT is not None:
         if logger is not None:
-            lmsg = "Checking file {} against schema {}"
-            logger.debug(lmsg.format(filename, schema_file))
+            logger.debug(f"Checking file {filename} against schema {schema_file}")
         cmd = [_XMLLINT, '--noout', '--schema', schema_file, filename]
         result = call_command(cmd, logger)
         return result
-    lmsg = "xmllint not found, could not validate file {}"
+    lmsg = f"xmllint not found, could not validate file {filename}"
     if error_on_noxmllint:
-        raise ValueError("validate_xml_file: " + lmsg.format(filename))
+        raise ImportError("validate_xml_file: " + lmsg)
     if logger is not None:
-        logger.warning(lmsg.format(filename))
+        logger.warning(lmsg)
     return True # We could not check but still need to proceed
 
 ###############################################################################

tools/write_standard_name_table.py

@@ -148,8 +148,7 @@ def parse_section(snl, sec, level='##'):
                 units = item.get('units')
                 snl.write(f'    * `{txt}`: units = {units}\n')
             else:
-                emsg = "Unknown standard name property, '{}'"
-                raise ValueError(emsg.format(item.tag))
+                raise ValueError(f"Unknown standard name property, '{item.tag}'")
 
 
 def convert_xml_to_yaml(root, library_name, yaml_file):