Merge pull request #3982 from billsacks/glc_multigrids

This is intended to support the GLC component having multiple grids (e.g., Greenland & Antarctica), but the implementation handles any component having multiple grids.

At a high level: If a component's grid is a colon-delimited string, then it is assumed to specify multiple grids, separated by the colons. Then, anywhere where we use the component's grid to create derived variables (domain name, mapping file names, etc.), I have introduced a loop over the list of grids for each component. For a component with multiple grids, the derived variables then also end up as colon-delimited strings, with one colon-delimited element per grid. I introduced similar loops in two places in nmlgen where we process file names.

To avoid adding more complexity and deep nesting to the Grids class, I have refactored it significantly in a few places. Main goals of the refactoring were (1) extracting some logic into a helper class, _ComponentGrids; among other things, this replaces various lookups that were being done using tuples and dicts; and (2) extracting the bodies of nested loops into new methods to avoid super-deep nesting. I also applied some refactorings like (2) to the nmlgen class for a similar reason.

I have also added unit tests of grids.py. The high-level tests of the Grids class work by constructing little fake xml files on the fly. There are also some tests of the lower-level helper functions. These unit tests don't cover all of the logic in grids.py, but they do cover a lot of the logic, with a particular focus on any parts of the code that I had to change significantly for this work.

A caveat about this implementation – particularly for the changes in nmlgen – is that it assumes that colons will only appear in file paths for this purpose of using multiple files. If people feel that is a dangerous assumption, we will either need to change the delimiter or more significantly rework the implementation. (I considered using an array of strings instead of a colon-delimited string. However, I prefer the colon-delimited approach because (1) @mvertens suggested it as an approach that could work well with the Fortran code in CMEPS, (2) I believe that changing this to use lists of strings would require many changes to namelist_definition xml files as well as a need to be vigilant moving forward that all relevant variables are declared as lists in the xml files, and (3) I'm not sure if the list-of-strings approach would work at all for the case xml files.) I did check all of the CESM inputdata that I could find on both cheyenne and izumi. The only files in CESM's inputdata that I can find that have a colon are these two very old files, which I don't believe would ever appear in inputdata lists in modern code bases:

    ./atm/ccm3/SEP1.T05.0198.nc:t.adump
    ./lnd/clm2/rawdata/urban_data_Feddema:080410_0.5x0.5_avg_c080908.nc

The driver/mediator code will also need to be extended to permit colon-delimited strings for various variables. However, this only needs to be done on an as-needed basis: As long as no component has multiple grids (the status quo), there will be no changes to the namelist variables. Soon, we will allow multiple grids for the GLC component with nuopc/cmeps in CESM, so we will extend CMEPS accordingly. We have no plans to extend the MCT driver/coupler to allow this, but the changes in this PR will work fine with the existing code.

@mvertens has provided guidance for the high-level design of this feature.

Test suite:

    scripts_regression_tests on cheyenne: all pass
    cime_developer test suite on cheyenne: all pass and bit-for-bit
    CESM's aux_cime_baselines on cheyenne: all pass and bit-for-bit
    CESM's prealpha tests on cheyenne and izumi: all pass and bit-for-bit except for tests that seem to have failed or weren't run at all in the baselines (SMS_D_Ln9.f09_f09_mg17.FCHIST.cheyenne_intel.cam-outfrq9s_ocnemis and the equivalent nuopc test had an exception in NLCOMP, but hand comparisons showed that namelists were effectively identical)

Test baseline: cime5.8.47, cesm2_3_alpha03a
Test namelist changes: none
Test status: bit for bit

Fixes #3962

User interface changes?: N

Update gh-pages html (Y/N)?: N

Author: jedwards4b

config/cesm/config_grids.xml

@@ -482,6 +482,22 @@
       <mask>gx1v7</mask>
     </model_grid>
 
+    <model_grid alias="f09_g17_ais8" compset="_CISM">
+      <grid name="atm">0.9x1.25</grid>
+      <grid name="lnd">0.9x1.25</grid>
+      <grid name="ocnice">gx1v7</grid>
+      <grid name="glc">ais8</grid>
+      <mask>gx1v7</mask>
+    </model_grid>
+
+    <model_grid alias="f09_g17_ais8gris4" compset="_CISM">
+      <grid name="atm">0.9x1.25</grid>
+      <grid name="lnd">0.9x1.25</grid>
+      <grid name="ocnice">gx1v7</grid>
+      <grid name="glc">ais8:gris4</grid>
+      <mask>gx1v7</mask>
+    </model_grid>
+
     <model_grid alias="f09_g17_gris20" compset="_CISM">
       <grid name="atm">0.9x1.25</grid>
       <grid name="lnd">0.9x1.25</grid>
@@ -1862,6 +1878,12 @@
       <desc>4-km Greenland grid, for use with the glissade dycore</desc>
     </domain>
 
+    <domain name="ais8">
+      <nx>704</nx> <ny>576</ny>
+      <mesh driver="nuopc">$DIN_LOC_ROOT/share/meshes/antarctica_8km_epsg3031_ESMFmesh_c201222.nc</mesh>
+      <desc>8-km Antarctica grid</desc>
+    </domain>
+
     <!-- ======================================================== -->
     <!-- WW3 domains-->
     <!-- ======================================================== -->

config/cesm/config_grids_common.xml

@@ -135,6 +135,11 @@
       <map name="GLC2OCN_ICE_RMAPNAME">cpl/gridmaps/gland20km/map_gland20km_to_gx3v7_nnsm_e1000r500_180502.nc</map>
     </gridmap>
 
+    <gridmap ocn_grid="gx1v7" glc_grid="ais8" >
+      <map name="GLC2OCN_LIQ_RMAPNAME">cpl/gridmaps/ais8/map_ais8_to_gx1v7_nn_open_ocean_nnsm_e1000r300_marginal_sea_TOBECREATED.nc</map>
+      <map name="GLC2OCN_ICE_RMAPNAME">cpl/gridmaps/ais8/map_ais8_to_gx1v7_nnsm_e1000r300_TOBECREATED.nc</map>
+    </gridmap>
+
     <!-- ======================================================== -->
     <!-- wav->ocn, ocn->wav, ice->wav -->
     <!-- ======================================================== -->