Merge tag 'ctsm5.1.dev065' into cn-matrix_v3

This tag refactors the static fire data input methodology to enable a future anthropogenic fire suppression
methodology to FATES as described NGEET/fates#673. This future method requires that FATES have access to
GDP data that was previously defined in CNVegStateType.F90 as part of cnveg_state_type.  As such, the GDP
variable has been moved into fire_base_type in FireDataBaseType.F90 to provide the data to the extended
fates_fire_base_type for eventual use in FATES.  Similarly, the surface dataset read subroutine has been
moved along with the peat and ag-fire variables, which utilize the same read subroutine and where also
originally part of the cnveg_state_type.

 Conflicts:
	src/biogeochem/CNFireLi2014Mod.F90

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -1623,6 +1623,7 @@ lnd/clm2/surfdata_map/release-clm5.0.30/surfdata_ne0np4.CONUS.ne30x8_hist_78pfts
 <light_res    use_fates=".true." fates_spitfire_mode="2" >360x720</light_res>
 <light_res    use_fates=".true." fates_spitfire_mode="3" >360x720</light_res>
 <light_res    use_fates=".true." fates_spitfire_mode="4" >360x720</light_res>
+<light_res    use_fates=".true." fates_spitfire_mode="5" >360x720</light_res>
 
 <stream_year_first_lightng >0001</stream_year_first_lightng>
 <stream_year_last_lightng  >0001</stream_year_last_lightng>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -649,14 +649,15 @@ Switch deciding which nutrient model to use in FATES.
 </entry>
 
 <entry id="fates_spitfire_mode" type="integer" category="physics"
-        group="clm_inparm" valid_values="0,1,2,3,4" value=".false.">
+        group="clm_inparm" valid_values="0,1,2,3,4,5" value=".false.">
 Turn on spitfire module to simulate fire by setting fates_spitfire_mode > 0.
 Allowed values are:
  0 : Simulations of fire are off
  1 : use a global constant lightning rate found in fates_params.
  2 : use an external lightning dataset. 
  3 : use an external confirmed ignitions dataset (not available through standard CSEM dataset collection).
  4 : use external lightning and population datasets to simulate both natural and anthropogenic
+ 5 : use gross domestic production and population datasets to simulate anthropogenic fire supression
 ignitions.
 (Only relevant if FATES is on)
 </entry>

doc/ChangeLog

@@ -1,4 +1,87 @@
 ===============================================================
+Tag name: ctsm5.1.dev065
+Originator(s): glemieux (Gregory Lemieux,LBL/NGEET,510-486-5049)
+Date: Thu Dec  2 00:13:37 MST 2021
+One-line Summary: Refactor static fire data input by moving variables into fire_base_type from cnveg_state_type
+
+Purpose and description of changes
+----------------------------------
+
+This tag refactors the static fire data input methodology to enable a future anthropogenic fire suppression 
+methodology to FATES as described NGEET/fates#673. This future method requires that FATES have access to 
+GDP data that was previously defined in CNVegStateType.F90 as part of cnveg_state_type.  As such, the GDP
+variable has been moved into fire_base_type in FireDataBaseType.F90 to provide the data to the extended 
+fates_fire_base_type for eventual use in FATES.  Similarly, the surface dataset read subroutine has been
+moved along with the peat and ag-fire variables, which utilize the same read subroutine and where also
+originally part of the cnveg_state_type.
+
+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
+
+
+Bugs fixed or introduced
+------------------------
+
+Issues fixed (include CTSM Issue #):
+    Fixes #1104 -- Move static fire data into Fire class
+
+Notes of particular relevance for developers:
+---------------------------------------------
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+    The ncd_io calls for the gdp, peat, and ag-fire data has been moved from the 
+    cnveg_state_type InitCold procedure into a new subroutine called surfdataread
+    which is a new fire_base_type procedure.
+
+    The function GetGDP has been introduced to get the pointer to the GDP data.  This has
+    been implemented in clmfates_interfaceMod.F90, but the assignment of this pointer
+    to a FATES-side bc_in variable has been commented out pending a future update to 
+    define the necessary FATES GDP variable.
+
+    A new namelist option has been added to the fates_spitfire_mode series.  This option
+    is intended as a simple placeholder for a future FATES fire supression mode.  The 
+    option is currently being included as a check in clmfates_interfaceMod.F90 to allow
+    for the exercise of the GetGDP function.
+
+Testing summary:
+----------------
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    cheyenne ---- OK
+    izumi ------- OK
+
+  fates tests: (give name of baseline if different from CTSM tagname, normally fates baselines are fates-<FATES TAG>-<CTSM TAG>)
+    cheyenne ---- N/A
+    izumi ------- N/A
+
+  any other testing (give details below):
+    A simple fates branch was created to test the potential handoff of the GDP data to FATES, which successfully
+    output the global gdp data.  The branch is located here: https://github.com/glemieux/fates/tree/fire-gdp-simpletest
+    Note that this branch was not used in the standard regression tests above.
+
+Other details
+-------------
+
+Pull Requests that document the changes (include PR ids):
+(https://github.com/ESCOMP/ctsm/pull)
+    #1536 -- Refactor static fire data to enable future use of GDP data in SPITFIRE
+
+===============================================================
+===============================================================
 Tag name:  ctsm5.1.dev064
 Originator(s):  afoster (Adrianna Foster)
 Date: Mon Nov 29 09:50:50 MST 2021

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+    ctsm5.1.dev065 glemieux 12/02/2021 Refactor static fire data input by moving variables into fire_base_type from cnveg_state_type
     ctsm5.1.dev064  afoster 11/29/2021 Updates to facilitate FATES history variable overhaul
     ctsm5.1.dev063 glemieux 11/23/2021 Provide access to the fraction of canopy covered by snow variable to fates
     ctsm5.1.dev062     erik 11/19/2021 Make NUOPC the default driver rather than MCT

doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst

@@ -183,7 +183,7 @@ where the single scattering albedo is
 .. math::
    :label: 3.16
 
-   \begin{array}{rcl} {a_{s} \left(\mu \right)_{\Lambda } } & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \int _{0}^{1}\frac{\mu 'G\left(\mu \right)}{\mu G\left(\mu '\right)+\mu 'G\left(\mu \right)}  d\mu '} \\ {} & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \frac{G\left(\mu \right)}{\min (\mu \phi _{2} +G\left(\mu \right),1e-6)} \left[1-\frac{\mu \phi _{1} }{\min (\mu \phi _{2} +G\left(\mu \right),1e-6)} \ln \left(\frac{\mu \phi _{1} +\min (\mu \phi _{2} +G\left(\mu \right),1e-6)}{\mu \phi _{1} } \right)\right].} \end{array}
+   \begin{array}{rcl} {a_{s} \left(\mu \right)_{\Lambda } } & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \int _{0}^{1}\frac{\mu 'G\left(\mu \right)}{\mu G\left(\mu '\right)+\mu 'G\left(\mu \right)}  d\mu '} \\ {} & {=} & {\frac{\omega _{\Lambda }^{veg} }{2} \frac{G\left(\mu \right)}{\max (\mu \phi _{2} +G\left(\mu \right),1e-6)} \left[1-\frac{\mu \phi _{1} }{\max (\mu \phi _{2} +G\left(\mu \right),1e-6)} \ln \left(\frac{\mu \phi _{1} +\max (\mu \phi _{2} +G\left(\mu \right),1e-6)}{\mu \phi _{1} } \right)\right].} \end{array}
 
 Note here the restriction on :math:`\mu \phi _{2} +G\left(\mu \right)`.  We have seen cases where small values
 can cause unrealistic single scattering albedo associated with the log calculation, 

manage_externals/checkout_externals

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Main driver wrapper around the manic/checkout utility.
 

manage_externals/manic/checkout.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """
 Tool to assemble repositories represented in a model-description file.
@@ -392,7 +392,7 @@ def main(args):
             # exit gracefully
             msg = """The external repositories labeled with 'M' above are not in a clean state.
 
-The following are three options for how to proceed:
+The following are four options for how to proceed:
 
 (1) Go into each external that is not in a clean state and issue either a 'git status' or
     an 'svn status' command (depending on whether the external is managed by git or
@@ -412,12 +412,17 @@ def main(args):
     {program_name}. Excluding externals labeled with 'M' will allow {program_name} to
     update the other, non-excluded externals.
 
+(4) As a last resort, if you are confident that there is no work that needs to be saved
+    from a given external, you can remove that external (via "rm -rf [directory]") and
+    then rerun the {program_name} tool. This option is mainly useful as a workaround for
+    issues with this tool (such as https://github.com/ESMCI/manage_externals/issues/157).
+
 
 The external repositories labeled with '?' above are not under version
 control using the expected protocol. If you are sure you want to switch
 protocols, and you don't have any work you need to save from this
-directory, then run "rm -rf [directory]" before re-running the
-checkout_externals tool.
+directory, then run "rm -rf [directory]" before rerunning the
+{program_name} tool.
 """.format(program_name=program_name, config_file=args.externals)
 
             printlog('-' * 70)

manage_externals/manic/externals_description.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Model description
 
@@ -193,6 +193,9 @@ def parse_submodules_desc_section(section_items, file_path):
 def read_gitmodules_file(root_dir, file_name):
     # pylint: disable=deprecated-method
     # Disabling this check because the method is only used for python2
+    # pylint: disable=too-many-locals
+    # pylint: disable=too-many-branches
+    # pylint: disable=too-many-statements
     """Read a .gitmodules file and convert it to be compatible with an
     externals description.
     """

manage_externals/manic/repository_git.py

@@ -109,35 +109,34 @@ def _clone_repo(self, base_dir_path, repo_dir_name, verbosity):
     def _current_ref(self):
         """Determine the *name* associated with HEAD.
 
-        If we're on a branch, then returns the branch name; otherwise,
-        if we're on a tag, then returns the tag name; otherwise, returns
+        If we're on a tag, then returns the tag name; otherwise, returns
         the current hash. Returns an empty string if no reference can be
         determined (e.g., if we're not actually in a git repository).
+
+        If we're on a branch, then the branch name is also included in
+        the returned string (in addition to the tag / hash).
         """
         ref_found = False
 
-        # If we're on a branch, then use that as the current ref
-        branch_found, branch_name = self._git_current_branch()
-        if branch_found:
-            current_ref = branch_name
+        # If we're exactly at a tag, use that as the current ref
+        tag_found, tag_name = self._git_current_tag()
+        if tag_found:
+            current_ref = tag_name
             ref_found = True
 
-        if not ref_found:
-            # Otherwise, if we're exactly at a tag, use that as the
-            # current ref
-            tag_found, tag_name = self._git_current_tag()
-            if tag_found:
-                current_ref = tag_name
-                ref_found = True
-
         if not ref_found:
             # Otherwise, use current hash as the current ref
             hash_found, hash_name = self._git_current_hash()
             if hash_found:
                 current_ref = hash_name
                 ref_found = True
 
-        if not ref_found:
+        if ref_found:
+            # If we're on a branch, include branch name in current ref
+            branch_found, branch_name = self._git_current_branch()
+            if branch_found:
+                current_ref = "{} (branch {})".format(current_ref, branch_name)
+        else:
             # If we still can't find a ref, return empty string. This
             # can happen if we're not actually in a git repo
             current_ref = ''

manage_externals/manic/utils.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 """
 Common public utilities for manic package
 

manage_externals/test/test_sys_checkout.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals
 
@@ -38,7 +38,6 @@
 import os
 import os.path
 import shutil
-import sys
 import unittest
 
 from manic.externals_description import ExternalsDescription

manage_externals/test/test_sys_repository_git.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Tests of some of the functionality in repository_git.py that actually
 interacts with git repositories.

manage_externals/test/test_unit_externals_description.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals
 

manage_externals/test/test_unit_externals_status.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for the manic external status reporting module.
 

manage_externals/test/test_unit_repository.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals
 

manage_externals/test/test_unit_repository_git.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals
 
@@ -101,7 +101,7 @@ def test_ref_branch(self):
             True, 'feature3')
         self._repo._git_current_tag = self._git_current_tag(True, 'foo_tag')
         self._repo._git_current_hash = self._git_current_hash(True, 'abc123')
-        expected = 'feature3'
+        expected = 'foo_tag (branch feature3)'
         result = self._repo._current_ref()
         self.assertEqual(result, expected)
 

manage_externals/test/test_unit_repository_svn.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals
 

manage_externals/test/test_unit_utils.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 """Unit test driver for checkout_externals