replace hidden alias operator ":=:" with "aliases" section

Author: whannah1

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

@@ -60,30 +60,35 @@ still resolves as `FieldPrevDiag(X)` because `binary_ops` does not match
 ## Worked example: the `bt` family
 
 ```yaml
-field_names:
-  # bt1 = atmospheric backward tendency of f
-  - bt1:=f_minus_f_prev_over_dt
-  # Parsing:
-  #   _over_dt suffix matched first → FieldOverDtDiag( f_minus_f_prev )
-  #   f_minus_f_prev → BinaryOpsDiag( f, minus, f_prev )
-  #   f_prev → FieldPrevDiag( f )
-  # Result: (f(t1) − f(t0)) / (t1 − t0)
-
-  # bt2 = tendency of the tendency
-  - bt2:=bt1_minus_bt1_prev
-  # Only one "minus" token → BinaryOpsDiag( bt1, minus, bt1_prev )
-  # bt1_prev → FieldPrevDiag( bt1 )
-
-  # bt_prod = product of the two tendencies
-  - bt_prod:=bt1_times_bt2
-
-  # bt_osc_count = indicator that bt_prod is negative (tendency oscillating)
-  - bt_osc_count:=count_where_bt_prod_lt_0
-  # ConditionalSampling: input=count, condition_field=bt_prod, op=lt, value=0
+fields:
+  physics_pg2:
+    aliases:
+      # bt1 is an intermediate — needed by bt2 and bt_prod but not written to NC
+      - bt1:=f_minus_f_prev_over_dt
+      # Parsing:
+      #   _over_dt suffix matched first → FieldOverDtDiag( f_minus_f_prev )
+      #   f_minus_f_prev → BinaryOpsDiag( f, minus, f_prev )
+      #   f_prev → FieldPrevDiag( f )
+      # Result: (f(t1) − f(t0)) / (t1 − t0)
+
+      # bt2 = tendency of the tendency (also intermediate)
+      - bt2:=bt1_minus_bt1_prev
+      # Only one "minus" token → BinaryOpsDiag( bt1, minus, bt1_prev )
+      # bt1_prev → FieldPrevDiag( bt1 )
+
+    field_names:
+      # bt_prod = product of the two tendencies — IS written to NC
+      - bt_prod:=bt1_times_bt2
+
+      # bt_osc_count = indicator that bt_prod is negative (tendency oscillating)
+      - bt_osc_count:=count_where_bt_prod_lt_0
+      # ConditionalSampling: input=count, condition_field=bt_prod, op=lt, value=0
 ```
 
-The `:=` alias syntax names each sub-expression before composing further,
-giving you full control over evaluation order.
+The `aliases` section names intermediate sub-expressions that are needed
+as inputs to other diagnostics but should not appear in the output file.
+The `field_names` section lists what actually gets written to NetCDF.
+Use `:=` in both sections to give a convenient name to a complex expression.
 
 ## Avoiding ambiguity
 

components/eamxx/docs/user/io_aliases.md

@@ -65,28 +65,33 @@ alias of the former.
 are preserved from the original fields, and `alias_of`
 is added to the netcdf files to document aliasing
 
-## Intermediate-only fields (`:=:` syntax)
+## Intermediate-only fields (`aliases` section)
 
 Sometimes a diagnostic is only needed as a building block for another
 diagnostic, and you do not want it written to the NetCDF output file.
-Use `alias:=:original` (note the extra colon) to declare such fields:
+Declare such fields in an `aliases` subsection of the per-grid block:
 
 ```yaml
-field_names:
-  - "MyDiag:=:T_mid_times_p_mid"   # computed but NOT written to NC
-  - "MyDiagSqrd:=MyDiag_times_MyDiag"  # uses MyDiag; IS written to NC
+fields:
+  physics_pg2:
+    aliases:
+      - "MyDiag:=T_mid_times_p_mid"       # computed but NOT written to NC
+    field_names:
+      - "MyDiagSqrd:=MyDiag_times_MyDiag" # uses MyDiag; IS written to NC
 ```
 
 `MyDiag` is created and registered in the internal field manager so that
 `MyDiagSqrd` can depend on it, but it does not appear in the output file.
 Only `MyDiagSqrd` is written.
 
+The `aliases` section uses the same `alias:=original` syntax as
+`field_names` entries, and the expression on the right-hand side is
+resolved with the same composable-diagnostic parser.
+
 Rules:
 
-- A name declared with `:=:` must not also appear as a regular output field.
-- The same alias name cannot be used for both `:=:` and `:=`.
-- The expression after `:=:` is resolved with the same composable-diagnostic
-  parser as any other field name.
+- A name declared in `aliases` must not also appear in `field_names`.
+- The same alias name cannot appear in both `aliases` and `field_names`.
 
 ## Caveats
 

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

@@ -137,6 +137,13 @@ AtmosphereOutput::AtmosphereOutput(const ekat::Comm &comm, const ekat::Parameter
             m_fields_names.clear();
           }
         }
+        if (pl.isParameter("aliases")) {
+          if (pl.isType<vos_t>("aliases")) {
+            m_intermediate_aliases = pl.get<vos_t>("aliases");
+          } else {
+            m_intermediate_aliases.push_back(pl.get<std::string>("aliases"));
+          }
+        }
       }
     }
     EKAT_REQUIRE_MSG (grid_found,
@@ -982,40 +989,31 @@ process_requested_fields()
   auto fm_model = m_field_mgrs[FromModel];
   auto fm_grid = m_field_mgrs[FromModel]->get_grid();
 
-  // First, find intermediate-only fields declared with the ':=:' syntax.
-  // These are created and added to the field manager (so dependents can use them),
-  // but are NOT registered with scorpio and do NOT appear in NC output.
+  // Process intermediate-only fields declared in the 'aliases' YAML section.
+  // Each entry has the form "alias:=original". These are created and registered
+  // in the field manager so that dependents can use them, but are NOT written
+  // to the NC output file.
   std::set<std::string> intermediate_names;
-  for (auto& name : m_fields_names) {
-    auto sep3 = name.find(":=:");
-    if (sep3 != std::string::npos) {
-      auto alias = name.substr(0, sep3);
-      auto orig  = name.substr(sep3 + 3);
-      EKAT_REQUIRE_MSG(!alias.empty() && !orig.empty(),
-          "Error! Invalid intermediate field request. Should be 'alias:=:original'.\n"
-          " - request: " + name + "\n");
-      EKAT_REQUIRE_MSG (m_alias_to_orig.count(alias)==0,
-          "Error! Intermediate-only alias conflicts with an existing alias.\n"
-          " - stream name: " + m_stream_name + "\n"
-          " - alias: " + alias + "\n");
-      m_alias_to_orig[alias] = orig;
-      intermediate_names.insert(alias);
-      name = "";  // mark for removal from m_fields_names
-    }
-  }
-  // Remove blanked entries (intermediate-only fields)
-  {
-    std::vector<std::string> tmp;
-    for (const auto& n : m_fields_names)
-      if (!n.empty()) tmp.push_back(n);
-    m_fields_names = std::move(tmp);
+  for (const auto& spec : m_intermediate_aliases) {
+    auto tokens = ekat::split(spec, ":=");
+    EKAT_REQUIRE_MSG(tokens.size()==2 && !tokens[0].empty() && !tokens[1].empty(),
+        "Error! Invalid entry in 'aliases' section. Should be 'alias:=original'.\n"
+        " - entry: " + spec + "\n");
+    const auto& alias = tokens[0];
+    const auto& orig  = tokens[1];
+    EKAT_REQUIRE_MSG(m_alias_to_orig.count(alias)==0,
+        "Error! Intermediate alias conflicts with an existing alias.\n"
+        " - stream name: " + m_stream_name + "\n"
+        " - alias: " + alias + "\n");
+    m_alias_to_orig[alias] = orig;
+    intermediate_names.insert(alias);
   }
 
   // Check that no intermediate name also appears as a regular output field
   for (const auto& iname : intermediate_names) {
     for (const auto& fname : m_fields_names) {
       EKAT_REQUIRE_MSG(fname != iname,
-          "Error! A field declared as intermediate-only (':=:') also appears as a regular output.\n"
+          "Error! A field declared in the 'aliases' section also appears in 'field_names'.\n"
           " - stream name: " + m_stream_name + "\n"
           " - field name: " + iname + "\n");
     }

components/eamxx/src/share/io/scorpio_output.hpp

@@ -214,6 +214,11 @@ class AtmosphereOutput
   // Internal maps to the output fields, how the columns are distributed, the file dimensions and
   // the global ids.
   strvec_t m_fields_names;
+  // Intermediate-only aliases declared in the 'aliases' YAML section.
+  // Each entry has the form "alias:=original". These fields are created and
+  // registered in the field manager so that other diagnostics can depend on
+  // them, but they are NOT written to the NC output file.
+  strvec_t m_intermediate_aliases;
   strmap_t<Field> m_field_to_avg_count;
   std::vector<Field> m_avg_counts;
   strmap_t<std::string> m_field_to_avg_cnt_suffix;