Feature #1518 winds

.github/jobs/set_job_controls.sh

@@ -6,6 +6,7 @@
 run_diff=false
 run_update_truth=false
 met_base_repo=met-base
+# TODO: Change 3.4 back to 3.5 after solving TC-Diag failure
 met_base_tag=3.4-latest
 input_data_version=develop
 truth_data_version=develop

.github/workflows/testing.yml

@@ -148,7 +148,7 @@ jobs:
           - jobid: 'job1' 
             tests: 'ascii2nc'
           - jobid: 'job2'
-            tests: 'pb2nc madis2nc pcp_combine gen_ens_prod regrid'
+            tests: 'pb2nc madis2nc pcp_combine gen_ens_prod regrid winds'
       fail-fast: false
     steps:
       - uses: actions/checkout@v6

data/config/ConfigConstants

@@ -22,6 +22,18 @@ output_precision = 5;
 // MET_TMP_DIR.
 tmp_dir = "/tmp";
 
+////////////////////////////////////////////////////////////////////////////////
+//
+// Settings to define wind vector metadata.
+//
+////////////////////////////////////////////////////////////////////////////////
+
+// Comma-separated lists of wind variable names for rotating and deriving
+u_wind_field_name = "UGRD,U";
+v_wind_field_name = "VGRD,V";
+wind_speed_field_name = "WIND,SP";
+wind_direction_field_name = "WDIR,DD";
+
 ////////////////////////////////////////////////////////////////////////////////
 //
 // Standard unit conversion functions.

docs/Users_Guide/config_options.rst

@@ -661,6 +661,41 @@ Some tools override the temporary directory by the command line argument
 A description of the use of temporary files in MET can be found in
 :numref:`Contributor's Guide Section %s <tmp_file_use>`.
 
+.. _config_wind_field_names:
+
+wind_field_names
+----------------
+
+As described in :numref:`PS_wind_rotation_derivation`, MET can automatically
+derive wind variables and also rotate them from being grid-relative to earth-relative.
+Logic is provided for each supported input file type to identify input wind components
+and determine whether they are defined as being grid-relative or earth-relative.
+
+The following configuration options can be set to refine the metadata, when needed:
+
+.. code-block:: none
+
+  is_u_wind         = boolean;
+  is_v_wind         = boolean;
+  is_grid_relative  = boolean;
+  is_wind_speed     = boolean;
+  is_wind_direction = boolean;
+
+When deriving and rotating winds, MET searches the input file for matching wind
+components. That search is driven by the following configuration options and
+default values found in the "data/config/ConfigConstants" file:
+
+.. code-block:: none
+
+  u_wind_field_name = "UGRD,U";
+  v_wind_field_name = "VGRD,V";
+  wind_speed_field_name = "WIND,SP";
+  wind_direction_field_name = "WDIR,DD";
+
+Each is a comma-separated list of wind variable names to be searched. Users can
+explicity set these options to configure what data should be used in the wind
+derivation and rotation logic.
+
 message_type_group_map
 ----------------------
 

docs/Users_Guide/point-stat.rst

@@ -117,6 +117,35 @@ _______________________
 
 The forecast value at P is chosen as the grid point inside the interpolation area whose value most closely matches the observation value.
 
+.. _PS_wind_rotation_derivation:
+
+Wind Rotation and Derivation
+----------------------------
+
+Numerical weather prediction model output often defines winds relative to the orientation of the model grid rather than true north-south and east-west directions on the earth.
+However point observations typically define winds relative to true earth directions. Prior to comparing them, the model wind data must be rotated from grid-relative to
+to earth-relative. While the degree of grid-to-earth rotation varies based on the projection type and location, failing to rotate the winds can have a significant impact on
+the verification results.
+
+For simplicity, the MET library code attempts to rotate all wind components from being grid-relative to earth-relative regardless of whether they are being compared to point
+observations with the Point-Stat tool or gridded analyses with the Grid-Stat tool. Running the MET tools at verbosity level 3 (-v 3) prints log messages to describing the wind
+rotation process. While the logic to determine whether input winds are grid-relative varies by file type, specifying the **is_grid_relative = FALSE;** configuration option
+manually overrides that logic and prevents winds from being rotated.
+
+Wind fields which must be rotated include wind direction and both the U and V components of the wind vector. While wind direction can be rotated by itself, both U and V are
+required to rotate either component. When processing U-wind data, MET attempts to read corresponding V-wind data and vice-versa.
+
+The configuration options for wind rotation and derivation in MET are described in section :numref:`config_wind_field_names`.
+
+When reading V-wind data to rotate U-wind or U-wind data to rotate V-wind, MET first searches using the same field name, but with both upper and lowercase U's and V's
+swapped (e.g. for "U_PL" search for "V_PL"). If the result is unsuccesful, it searches other common field names specified by the **u_wind_field_name** and **v_wind_field_name**
+configuration options. If needed, users should set these configuration options to indicate how the U-wind and V-wind data should be paired.
+
+In addition to rotating winds, MET can also derive them. If U-wind and V-wind are present in the input file, request field names of **WDIR**, **WIND**, or **KENG**
+to derive wind direction, wind speed, and kinetic engery from the U and V components, respectively. If wind speed and direction are present in the input file, request field
+names of **UGRD** or **VGRD** for MET to derive the U and V components from them. Depending on the wind field naming conventions, the configuration options described in
+:numref:`config_wind_field_names` may be required to configure this derivation logic.
+
 .. _PS_HiRA_framework:
 
 HiRA Framework

docs/Users_Guide/release-notes.rst

@@ -182,6 +182,14 @@ MET Version 13.0.0 Upgrade Instructions
      * The "ensemble_flag.eas" and "ensemble_flag.eas_width" entries are added to enable the
        writing of EAS output fields.
 
+   * ConfigConstanst configuration file
+
+     * The "u_wind_field_name", "v_wind_field_name", "wind_speed_field_name", and "wind_direction_field_name"
+       entries are comma-separated lists of field names to search when read wind data needed to derive winds
+       or rotate them from being grid-relative to earth-relative. See :numref:`PS_wind_rotation_derivation`
+       for a description of wind rotation and derivation and :numref:`config_wind_field_names` for the
+       corresponding configuration options.
+
 .. dropdown:: Output format changes - NONE
 
 .. dropdown:: Output format changes - NONE

internal/test_unit/bin/unit_test.sh

@@ -40,6 +40,7 @@ UNIT_XML="unit_ascii2nc.xml \
           unit_gen_ens_prod.xml \
           unit_pcp_combine.xml \
           unit_regrid.xml \
+          unit_winds.xml \
           unit_wwmca_regrid.xml \
           unit_point_stat.xml \
           unit_stat_analysis_ps.xml \

internal/test_unit/xml/unit_grib_tables.xml

@@ -36,8 +36,8 @@
         <param> \
             &DATA_DIR_MODEL;/grib2/um_raw/PS.557WW_SC.U_DI.F_GP.GALWEM-GD_GR.C17KM_AR.GLOBAL_DD.20160424_CY.00_FH.000_DF.GR2 \
             &OUTPUT_DIR;/grib_tables/um_raw/PS.557WW_SC.U_DI.F_GP.GALWEM-GD_GR.C17KM_AR.GLOBAL_DD.20160424_CY.00_FH.000_DF.ps \
-            'name = "TCDC"; level = "L0";' \
-            -title "GRIB2 um_raw L0 TCDC" \
+            'name = "TCC"; level = "L0";' \
+            -title "GRIB2 um_raw L0 TCC" \
             -v 1
         </param>
         <output>

internal/test_unit/xml/unit_plot_data_plane.xml

@@ -615,7 +615,7 @@
     <param> \
       &DATA_DIR_MODEL;/wrf/wrfout_solarwind_d02_2019-08-31_12:00:00 \
       &OUTPUT_DIR;/plot_data_plane/wrf_west_east_stag.ps \
-      'name="U"; level="(0,0,*,*)";' \
+      'name="U"; level="(0,0,*,*)"; is_grid_relative=false;' \
       -title "X-wind component (staggered)" \
       -v 1
     </param>
@@ -629,7 +629,7 @@
     <param> \
       &DATA_DIR_MODEL;/wrf/wrfout_solarwind_d02_2019-08-31_12:00:00 \
       &OUTPUT_DIR;/plot_data_plane/wrf_south_north_stag.ps \
-      'name="V"; level="(0,0,*,*)";' \
+      'name="V"; level="(0,0,*,*)"; is_grid_relative=false;' \
       -title "Y-wind component (staggered)" \
       -v 1
     </param>

internal/test_unit/xml/unit_winds.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+<!DOCTYPE met_test [
+  <!ENTITY MET_BIN        "${MET_BASE}/../../bin">
+  <!ENTITY TEST_DIR       "${MET_TEST_BASE}">
+  <!ENTITY INPUT_DIR      "${MET_TEST_INPUT}">
+  <!ENTITY OUTPUT_DIR     "${MET_TEST_OUTPUT}">
+
+  <!ENTITY CONFIG_DIR     "&TEST_DIR;/config">
+  <!ENTITY DATA_DIR_MODEL "&INPUT_DIR;/model_data">
+  <!ENTITY DATA_DIR_OBS   "&INPUT_DIR;/obs_data">
+]>
+
+<!-- Requires: None -->
+
+<met_test>
+
+  <test_dir>&TEST_DIR;</test_dir>
+  <exit_on_fail>true</exit_on_fail>
+
+  <!--                                          -->
+  <!--  GRIB1 wind rotation and U/V derivation  -->
+  <!--  with grid-relative input                -->
+  <!--                                          -->
+
+  <test name="pcp_combine_winds_from_u_and_v_GRIB1">
+    <exec>&MET_BIN;/pcp_combine</exec>
+    <param> \
+      -add &DATA_DIR_MODEL;/grib1/nam/nam_2012040900_F012.grib \
+      -field 'name="UGRD"; level="Z10"; set_attr_name="UWIND_GRID"; is_grid_relative=false;' \
+      -field 'name="UGRD"; level="Z10"; set_attr_name="UWIND_EARTH";' \
+      -field 'name="VGRD"; level="Z10"; set_attr_name="VWIND_GRID"; is_grid_relative=false;' \
+      -field 'name="VGRD"; level="Z10"; set_attr_name="VWIND_EARTH";' \
+      -field 'name="WDIR"; level="Z10"; set_attr_name="D_WDIR_GRID"; is_grid_relative=false;' \
+      -field 'name="WDIR"; level="Z10"; set_attr_name="D_WDIR_EARTH";' \
+      -field 'name="WIND"; level="Z10"; set_attr_name="D_WIND";' \
+      -field 'name="KENG"; level="Z10"; set_attr_name="D_KENG";' \
+      &OUTPUT_DIR;/winds/pcp_combine_nam_winds_GRIB1.nc \
+      -v 3
+    </param>
+    <output>
+      <grid_nc>&OUTPUT_DIR;/winds/pcp_combine_nam_winds_GRIB1.nc</grid_nc>
+    </output>
+  </test>
+
+  <!--                                             -->
+  <!--  GRIB2 wind speed and direction derivation  -->
+  <!--  with earth-relative input                  -->
+  <!--                                             -->
+
+  <test name="pcp_combine_rotate_winds_from_speed_and_direction_GRIB2">
+    <exec>&MET_BIN;/pcp_combine</exec>
+    <param> \
+      -add &DATA_DIR_MODEL;/grib2/nbm/blend.t13z.core.f119.co.grib2 \
+      -field 'name="UGRD"; level="Z10"; set_attr_name="D_UWIND";' \
+      -field 'name="VGRD"; level="Z10"; set_attr_name="D_VWIND";' \
+      -field 'name="WDIR"; level="Z10"; set_attr_name="WDIR";' \
+      -field 'name="WDIR"; level="Z10"; set_attr_name="WDIR_ROTATE"; is_grid_relative=true;' \
+      -field 'name="WIND"; level="Z10"; set_attr_name="WIND";' \
+      &OUTPUT_DIR;/winds/pcp_combine_nbm_winds_GRIB2.nc \
+      -v 3
+    </param>
+    <output>
+      <grid_nc>&OUTPUT_DIR;/winds/pcp_combine_nbm_winds_GRIB2.nc</grid_nc>
+    </output>
+  </test>
+
+  <!--                    -->
+  <!--  NetCDF WRF winds  -->
+  <!--                    -->
+
+  <test name="pcp_combine_winds_from_u_and_v_NETCDF_WRF">
+    <exec>&MET_BIN;/pcp_combine</exec>
+    <param> \
+      -add &DATA_DIR_MODEL;/wrf/wrfout_solarwind_d02_2019-08-31_12:00:00 \
+      -field 'name="U10"; level="(0,*,*)"; set_attr_name="U10_GRID"; is_grid_relative=false;' \
+      -field 'name="U10"; level="(0,*,*)"; set_attr_name="U10_EARTH";' \
+      -field 'name="V10"; level="(0,*,*)"; set_attr_name="V10_GRID"; is_grid_relative=false;' \
+      -field 'name="V10"; level="(0,*,*)"; set_attr_name="V10_EARTH";' \
+      -field 'name="WDIR10"; level="(0,*,*)"; set_attr_name="WDIR10_GRID"; is_wind_direction=true; u_wind_field_name="U10"; v_wind_field_name="V10"; is_grid_relative=false;' \
+      -field 'name="WDIR10"; level="(0,*,*)"; set_attr_name="WDIR10_EARTH"; is_wind_direction=true; u_wind_field_name="U10"; v_wind_field_name="V10";' \
+      -field 'name="WIND10"; level="(0,*,*)"; is_wind_speed=true; u_wind_field_name="U10"; v_wind_field_name="V10";' \
+      &OUTPUT_DIR;/winds/pcp_combine_winds_NETCDF_WRF.nc \
+      -v 3
+    </param>
+    <output>
+      <grid_nc>&OUTPUT_DIR;/winds/pcp_combine_winds_NETCDF_WRF.nc</grid_nc>
+    </output>
+  </test>
+
+</met_test>

src/basic/vx_config/config_constants.h

@@ -294,9 +294,17 @@
    ~InterpInfo() { clear(); }
    InterpInfo(InterpInfo const &i) { *this = i; }
    InterpInfo &operator=(const InterpInfo &a) noexcept; // SonarQube findings
-   bool operator==(const InterpInfo &) const;
    void clear();
    void validate(); // Ensure that width and method are accordant
+
+   friend bool operator==(const InterpInfo &lhs, const InterpInfo &rhs) {
+      return(lhs.field      == rhs.field      &&
+             lhs.vld_thresh == rhs.vld_thresh &&
+             lhs.n_interp   == rhs.n_interp   &&
+             lhs.method     == rhs.method     &&
+             lhs.width      == rhs.width      &&
+             lhs.shape      == rhs.shape);
+   }
 };
 
 ////////////////////////////////////////////////////////////////////////
@@ -450,8 +458,47 @@
    ~MaskLatLon() { clear(); }
    MaskLatLon(MaskLatLon const &i) { *this = i; }
    MaskLatLon &operator=(const MaskLatLon &a) noexcept;
-   bool operator==(const MaskLatLon &) const;
    void clear();
+
+   friend bool operator==(const MaskLatLon &lhs, const MaskLatLon &rhs) {
+      return(lhs.name       == rhs.name       &&
+             lhs.lat_thresh == rhs.lat_thresh &&
+             lhs.lon_thresh == rhs.lon_thresh);
+   }
+};
+
+////////////////////////////////////////////////////////////////////////
+
+//
+// Struct to store wind vector metadata
+//
+
+struct WindMetadata {
+   StringArray u_wind;         // U-wind field names
+   StringArray v_wind;         // V-wind field names
+   StringArray wind_speed;     // Wind speed field names
+   StringArray wind_direction; // Wind direction field names
+
+   WindMetadata() { clear(); }
+   ~WindMetadata() { clear(); }
+   WindMetadata(WindMetadata const &i) { *this = i; }
+   WindMetadata &operator=(const WindMetadata &a) noexcept;
+   void clear();
+
+   bool is_u_wind(const std::string &s) const { return u_wind.has(s); }
+   bool is_v_wind(const std::string &s) const { return v_wind.has(s); }
+   bool is_wind_speed(const std::string &s) const { return wind_speed.has(s); }
+   bool is_wind_direction(const std::string &s) const { return wind_direction.has(s); }
+
+   // Supported derivations
+   bool is_kinetic_energy(const std::string &s) const { return s == "KENG"; }
+
+   friend bool operator==(const WindMetadata &lhs, const WindMetadata &rhs) {
+      return(lhs.u_wind         == rhs.u_wind     &&
+             lhs.v_wind         == rhs.v_wind     &&
+             lhs.wind_speed     == rhs.wind_speed &&
+             lhs.wind_direction == rhs.wind_direction);
+   }
 };
 
 ////////////////////////////////////////////////////////////////////////
@@ -751,6 +798,15 @@
 static const char conf_key_ugrid_max_distance_km[]  = "ugrid_max_distance_km";
 static const char conf_key_ugrid_metadata_map[]     = "ugrid_metadata_map";
 
+//
+// Entries to define wind vector metadata
+//
+
+static const char conf_key_u_wind_field_name[]         = "u_wind_field_name";
+static const char conf_key_v_wind_field_name[]         = "v_wind_field_name";
+static const char conf_key_wind_speed_field_name[]     = "wind_speed_field_name";
+static const char conf_key_wind_direction_field_name[] = "wind_direction_field_name";
+
 //
 // Entries to override file metadata 
 //
@@ -1329,8 +1385,6 @@
 static const char conf_key_delta_range[] = "delta_range_km";
 static const char conf_key_rmw_scale[]   = "rmw_scale";
 static const char conf_key_compute_tangential_and_radial_winds[] = "compute_tangential_and_radial_winds";
-static const char conf_key_u_wind_field_name[] = "u_wind_field_name";
-static const char conf_key_v_wind_field_name[] = "v_wind_field_name";
 static const char conf_key_radial_velocity_field_name[] = "radial_velocity_field_name";
 static const char conf_key_tangential_velocity_field_name[] = "tangential_velocity_field_name";
 static const char conf_key_radial_velocity_long_field_name[] = "radial_velocity_long_field_name";