EAMxx: add zonal average diagnostic and update IO for custom CMP-like tag names

components/eamxx/docs/user/diags/field_contraction.md

@@ -3,6 +3,8 @@
 In EAMxx, we can automatically calculate field reductions
 across the horizontal columns and across the model vertical levels.
 We call these horizontal and vertical reductions.
+We can also automatically calculate zonal averages,
+albeit with additional flexibility (see below).
 
 ## Horizontal reduction
 
@@ -58,6 +60,25 @@ The supported weighting options for now are
 In the case of `pseudo_density`, the weighting is scaled by 1/g,
 where g is the gravitational acceleration, in units of m/s$^2$.
 
+## Zonal reduction
+
+We currently have a utility to calculate zonal averages online.
+To select the zonal average, you only need to suffix
+a field name `X` with `_zonal_avg` and optionally the
+number of bins `num_lat`. All zonal averages are calculated
+using the area fraction in each bin as the weight.
+
+For 180 latitude bins (the default), the bins are defined
+as follows: [-90, -89), [-89, -88), ..., [89, 90).
+For 90 latitude bins, the bins are defined as follows:
+[-90, -88), [-88, -85), ..., [88, 90).
+And so on...
+
+| Reduction | Weight | Description |
+| --------- | ------ | ----------- |
+| `X_zonal_avg` | Area fraction | Average across 180 latitude bins |
+| `X_zonal_avg_with_Y_bins` | Area fraction | Average across Y latitude bins |
+
 ## Example
 
 ```yaml
@@ -77,6 +98,8 @@ fields:
       - T_mid_vert_sum_dz_weighted  # K * m
       - T_mid_vert_avg  # K
       - T_mid_vert_sum  # K
+      - T_mid_zonal_avg  # K
+      - T_mid_zonal_avg_with_90_bins  # K
 output_control:
   frequency: 1
   frequency_units: nmonths

components/eamxx/src/share/io/eamxx_io_utils.cpp

@@ -140,7 +140,7 @@ create_diagnostic (const std::string& diag_field_name,
   std::regex vert_layer ("(z|geopotential|height)_(mid|int)$");
   std::regex horiz_avg ("([A-Za-z0-9_]+)_horiz_avg$");
   std::regex vert_contract ("([A-Za-z0-9_]+)_vert_(avg|sum)(_((dp|dz)_weighted))?$");
-  std::regex zonal_avg (R"(([A-Za-z0-9_]+)_zonal_avg_with_(\d+)_bins$)");
+  std::regex zonal_avg (R"(([A-Za-z0-9_]+)_zonal_avg(_with_(\d+)_bins)?$)");
 
   std::string diag_name;
   std::smatch matches;
@@ -215,7 +215,14 @@ create_diagnostic (const std::string& diag_field_name,
     diag_name = "ZonalAvgDiag";
     params.set("grid_name", grid->name());
     params.set<std::string>("field_name", matches[1].str());
-    params.set<std::string>("number_of_zonal_bins", matches[2].str());
+    // The second match is optional
+    if (matches[2].matched) {
+      // note that the 3rd match is the number of bins
+      params.set<std::string>("number_of_zonal_bins", matches[3].str());
+    } else {
+      // set number_of_zonal_bins to default 180
+      params.set<std::string>("number_of_zonal_bins", "180");
+    }
   }
   else
   {