Merge branch 'mahf708/eamxx/vert-contraction-diag' (PR #7156)

Adds support for vertically contracted diagnostic fields in EAMxx by introducing
a new diagnostic (VertContractDiag) and integrating it throughout the codebase.

Key changes include adding a new regex in the I/O utilities to recognize
vertical contraction field names, implementing the VertContractDiag class
across header and source files with the associated logic for averaging/summing,
and adding test cases and documentation updates to support and illustrate the new diagnostic.

[BFB]

Author: bartgol

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

@@ -0,0 +1,83 @@
+# Field contraction diagnostics
+
+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.
+
+## Horizontal reduction
+
+We currently offer only one horizontal reduction $C$, and it is defined as
+
+$$
+C_{\dots k} = \sum_{i} w_{i} \cdot F_{i \dots k}
+$$
+
+where $F_\text{i...k}$ is the field at column $i$ and level $k$,
+and $w_{i}$ is the weight at column $i$.
+We note that the field $F$ can have other dimensions ($\dots$).
+The weight $w$ is defined as the area fraction in column $i$,
+that is, the area in column $i$ divided by the total area in all columns.
+
+To select the horizontal reduction, you only need to suffix
+a field name `X` with `_horiz_avg` in the output requests.
+
+| Reduction | Weight | Description |
+| --------- | ------ | ----------- |
+| `X_horiz_avg` | Area fraction | Average across all columns |
+
+## Vertical reduction
+
+We currently offer three vertical reductions $C$, defined as
+
+$$
+C_{\dots} = \sum_{k} w_{k} \cdot F_{\dots k}
+$$
+
+where $F_{\dots k}$ is the field at level $k$,
+and $w_{k}$ is the weight at level $k$.
+
+To select the vertical reduction, you only need to suffix
+a field name `X` with `_vert_(avg|sum)_(dp|dz)_weighted` or
+`_vert_(avg|sum)` in the output yaml files.
+
+| Reduction | Weight | Description |
+| --------- | ------ | ----------- |
+| `X_vert_avg_dp_weighted` | $\Delta p_{k}$ | Average across all levels, weighted by $\Delta p_{k}$ |
+| `X_vert_sum_dp_weighted` | $\Delta p_{k}$ | Sum across all levels, weighted by $\Delta p_{k}$ |
+| `X_vert_avg_dz_weighted` | $\Delta z_{k}$ | Average across all levels, weighted by $\Delta z_{k}$ |
+| `X_vert_sum_dz_weighted` | $\Delta z_{k}$ | Sum across all levels, weighted by $\Delta z_{k}$ |
+| `X_vert_avg` | 1 | Average across all levels |
+| `X_vert_sum` | 1 | Sum across all levels |
+
+The supported weighting options for now are
+
+- `pseudo_density` field in EAMxx, $\Delta p_{k}$, in units of Pa;
+- `dz` field in EAMxx, $\Delta z_{k}$, in units of m;
+- and no weighting, which is equivalent to using a weight of 1.
+
+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$.
+
+## Example
+
+```yaml
+%YAML 1.1
+---
+filename_prefix: monthly.outputs
+averaging_type: average
+max_snapshots_per_file: 1
+fields:
+  physics_pg2:
+    field_names:
+      # in this example, we use T_mid in units of K
+      - T_mid_horiz_avg  # K
+      - T_mid_vert_avg_dp_weighted  # K
+      - T_mid_vert_sum_dp_weighted  # K * Pa * s / (m * m) 
+      - T_mid_vert_avg_dz_weighted  # K
+      - T_mid_vert_sum_dz_weighted  # K * m
+      - T_mid_vert_avg  # K
+      - T_mid_vert_sum  # K
+output_control:
+  frequency: 1
+  frequency_units: nmonths
+```

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

@@ -0,0 +1,7 @@
+# Online diagnostics
+
+EAMxx has facilities to output optional diagnostics
+that are computed during runtime. These diagnostics
+are designed generically and composably, and are requestable by users.
+
+More details to follow.

components/eamxx/mkdocs.yml

@@ -18,6 +18,9 @@ nav:
     - 'IO Metadata': 'user/io_metadata.md'
     - 'Multi-Instance and NBFB': 'user/multi-instance-mvk.md'
     - 'EAMxx runtime parameters': 'user/eamxx_params.md'
+    - 'Diagnostics':
+      - 'Overview': 'user/diags/index.md'
+      - 'Field contraction diagnostics': 'user/diags/field_contraction.md'
     - 'Presentations': 'user/presentations.md'
   - 'Developer Guide':
     # - 'Overview': 'developer/index.md'

components/eamxx/src/diagnostics/CMakeLists.txt

@@ -22,6 +22,7 @@ set(DIAGNOSTIC_SRCS
   virtual_temperature.cpp
   water_path.cpp
   wind_speed.cpp
+  vert_contract.cpp
 )
 
 add_library(diagnostics ${DIAGNOSTIC_SRCS})

components/eamxx/src/diagnostics/register_diagnostics.hpp

@@ -25,6 +25,7 @@
 #include "diagnostics/aerocom_cld.hpp"
 #include "diagnostics/atm_backtend.hpp"
 #include "diagnostics/horiz_avg.hpp"
+#include "diagnostics/vert_contract.hpp"
 
 namespace scream {
 
@@ -53,6 +54,7 @@ inline void register_diagnostics () {
   diag_factory.register_product("AeroComCld",&create_atmosphere_diagnostic<AeroComCld>);
   diag_factory.register_product("AtmBackTendDiag",&create_atmosphere_diagnostic<AtmBackTendDiag>);
   diag_factory.register_product("HorizAvgDiag",&create_atmosphere_diagnostic<HorizAvgDiag>);
+  diag_factory.register_product("VertContractDiag",&create_atmosphere_diagnostic<VertContractDiag>);
 }
 
 } // namespace scream

components/eamxx/src/diagnostics/tests/CMakeLists.txt

@@ -74,3 +74,6 @@ CreateDiagTest(atm_backtend "atm_backtend_test.cpp")
 
 # Test horizontal averaging
 CreateDiagTest(horiz_avg "horiz_avg_test.cpp")
+
+# Test for vertical contraction
+CreateDiagTest(vert_contract "vert_contract_test.cpp")