Merge remote-tracking branch 'slevisconsulting/hist_fields_table'

Write history fields master list to separate optional file User can choose to write the history fields master list in a separate text file by setting hist_master_list_file = .true. in CTSM's namelist. File contents follow recommended reStructuredText "simple table" formatting (see https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables) for use in CTSM documentation in the sphinx environment. Resolves #34 Resolves #941
ESCOMP · Nov 19, 2020 · 40c70bd · 40c70bd
2 parents 7c8450b + 1ca9047
commit 40c70bd
Show file tree

Hide file tree

Showing 16 changed files with 1,536 additions and 4 deletions.
diff --git a/bld/CLMBuildNamelist.pm b/bld/CLMBuildNamelist.pm
@@ -3891,6 +3891,7 @@ sub setup_logic_misc {
    my ($opts, $nl_flags, $definition, $defaults, $nl) = @_;
 
    add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'for_testing_run_ncdiopio_tests');
+   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'hist_master_list_file');
 }
 
 #-------------------------------------------------------------------------------

diff --git a/bld/namelist_files/namelist_defaults_ctsm.xml b/bld/namelist_files/namelist_defaults_ctsm.xml
@@ -59,6 +59,9 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 
 <for_testing_run_ncdiopio_tests>.false.</for_testing_run_ncdiopio_tests>
 
+<!-- Set to .true. in namelist to write hist fields master list file -->
+<hist_master_list_file>.false.</hist_master_list_file>
+
 <!-- In accelerated spinup mode reduce the amount of history output -->
 <hist_empty_htapes clm_accelerated_spinup="on">.true.</hist_empty_htapes>
 <hist_fincl1 clm_accelerated_spinup="on" use_cn=".true." use_cndv=".true."

diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml
@@ -729,6 +729,11 @@ SNICAR (SNow, ICe, and Aerosol Radiative model) optical data file name
 SNICAR (SNow, ICe, and Aerosol Radiative model) snow aging data file name
 </entry>
 
+<entry id="hist_master_list_file" type="logical" category="history"
+       group="clm_inparm" valid_values="" value=".false.">
+If TRUE, write master field list to separate file for documentation purposes
+</entry>
+
 <entry id="hist_avgflag_pertape" type="char*1(10)" category="history"
        group="clm_inparm" valid_values="A,I,X,M" >
 Per file averaging flag.

diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml
@@ -1053,6 +1053,7 @@
     </machines>
     <options>
       <option name="wallclock">00:20:00</option>
+      <option name="comment"  >Among other extra outputs, ensure that writing the history field master list to a separate file does not cause failure"</option>
     </options>
   </test>
   <test name="ERS_D_Ld3" grid="f10_f10_musgs" compset="I1850Clm50BgcCrop" testmods="clm/default">

diff --git a/cime_config/testdefs/testmods_dirs/clm/extra_outputs/README b/cime_config/testdefs/testmods_dirs/clm/extra_outputs/README
@@ -1 +1,4 @@
 This test mod turns on extra diagnostic fields
+
+It also outputs an optional text file containing a table of the
+history fields master list
diff --git a/cime_config/testdefs/testmods_dirs/clm/extra_outputs/user_nl_clm b/cime_config/testdefs/testmods_dirs/clm/extra_outputs/user_nl_clm
@@ -1 +1,2 @@
 calc_human_stress_indices = 'ALL'
+hist_master_list_file = .true.
diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -1,4 +1,132 @@
 ===============================================================
+Tag name:  ctsm5.1.dev017
+Originator(s):  slevis (Samuel Levis,303-665-1310)
+Date:  Tue Nov 17 18:19:20 MST 2020
+One-line Summary: Write history filds master list to separate optional file
+
+Purpose of changes
+------------------
+
+ User can choose to write the history fields master list in a separate
+ text file by setting hist_master_list_file = .true. in CTSM's namelist.
+
+ File contents follow recommended reStructuredText "simple table"
+ formatting (see
+ https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables)
+ for use in CTSM documentation in the sphinx environment.
+
+Bugs fixed or introduced
+------------------------
+
+Issues fixed (include CTSM Issue #): #34 #941 
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm5_1
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+Notes of particular relevance for users
+---------------------------------------
+
+Caveats for users (e.g., need to interpolate initial conditions):
+ None
+
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+ New namelist option hist_master_list_file. Setting to true generates a
+ new text output file containing the history fields master list.
+
+Changes made to namelist defaults (e.g., changed parameter values):
+ Default for hist_master_list_file = .false.
+
+Changes to the datasets (e.g., parameter, surface or initial files):
+ None
+
+Substantial timing or memory changes:
+ No
+
+Notes of particular relevance for developers: (including Code reviews and testing)
+---------------------------------------------
+NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+ None
+
+Changes to tests or testing:
+ Introduced testing for the new namelist option within the existing test
+ ERP_P36x2_D_Ld3.f10_f10_musgs.I1850Clm50BgcCrop.cheyenne_gnu.clm-extra_outputs
+ by adding hist_master_list_file = .true. to the test's user_nl_clm
+
+CTSM testing:
+
+[... Remove before making master tag.  Available test levels:
+
+    a) regular (must be run before handing off a tag to SEs and must be run
+     before committing a tag)
+    b) build_namelist (if namelists and/or build_system changed))
+    c) tools (only if tools are modified and no CTSM source is modified)
+    d) short (for use during development and in rare cases where only a small
+          change with known behavior is added ... eg. a minor bug fix)
+    e) doc (no source testing required)
+
+... ]
+
+ [PASS means all tests PASS and OK means tests PASS other than expected fails.]
+
+  build-namelist tests:
+
+    cheyenne - 
+
+  tools-tests (test/tools):
+
+    cheyenne - 
+
+  PTCLM testing (tools/shared/PTCLM/test):
+
+    cheyenne - 
+
+  python testing (see instructions in python/README.md; document testing done):
+
+    (any machine) - 
+
+  regular tests (aux_clm):
+
+    cheyenne ---- OK (NLCOMP tests fail as expected)
+    izumi ------- OK (NLCOMP tests fail as expected)
+
+If the tag used for baseline comparisons was NOT the previous tag, note that here:
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline:
+ No
+
+Detailed list of changes
+------------------------
+
+ Added section to subr. hist_printflds (called by subr. initialize2).
+ The new section runs when hist_master_list_file = .true.
+
+List any externals directories updated (cime, rtm, mosart, cism, fates, etc.):
+ None
+
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/CTSM/pull/1209
+
+===============================================================
+===============================================================
 Tag name:  ctsm5.1.dev016
 Originator(s): mvertens (Mariana Vertenstein), jedwards (Jim Edwards),
                sacks (Bill Sacks), erik (Erik Kluzek)

diff --git a/doc/ChangeSum b/doc/ChangeSum
@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+  ctsm5.1.dev017   slevis 11/17/2020 Write history filds master list to separate optional file
   ctsm5.1.dev016 multiple 11/17/2020 Updates for nuopc
   ctsm5.1.dev015    sacks 11/13/2020 A few small fixes
   ctsm5.1.dev014 dll/oles 11/07/2020 Grass/crop snow burial fraction fix, and some other fixes

diff --git a/doc/source/users_guide/setting-up-and-running-a-case/README_master_list_file b/doc/source/users_guide/setting-up-and-running-a-case/README_master_list_file
@@ -0,0 +1,9 @@
+2020/11/16 slevis
+
+The file master_list_file.rst contains a table of the history fields,
+active and inactive, available in the CTSM case that gets generated by
+this test:
+ERP_P36x2_D_Ld3.f10_f10_musgs.I1850Clm50BgcCrop.cheyenne_gnu.clm-extra_outputs
+
+To reproduce master_list_file.rst, run the above test and the file
+will appear in the run directory.
diff --git a/...urce/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst b/...urce/users_guide/setting-up-and-running-a-case/customizing-the-clm-namelist.rst
@@ -43,7 +43,7 @@ Included in the table are the following pieces of information:
 
 Table 1-3. CLM History Fields
 -----------------------------
-Table goes here.
+For Table, please see :doc:`master_list_file`.
 
 
 ---------------------------------------------

diff --git a/doc/source/users_guide/setting-up-and-running-a-case/index.rst b/doc/source/users_guide/setting-up-and-running-a-case/index.rst
@@ -18,4 +18,5 @@ Setting Up and Running a Case
    customizing-the-clm-configuration.rst
    customizing-the-clm-namelist.rst
    customizing-the-datm-namelist.rst
+   master_list_file