Merge remote-tracking branch 'origin/ctsm5.2.mksurfdata' into dynurb_…

…mksurf

.gitattributes

@@ -4,3 +4,4 @@
 *.jpeg filter=lfs diff=lfs merge=lfs -text
 *.gif filter=lfs diff=lfs merge=lfs -text
 *.pdf filter=lfs diff=lfs merge=lfs -text
+*.nc filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: CESM forums
-    url: https://xenforo.cgd.ucar.edu/cesm/
+    url: https://bb.cgd.ucar.edu/cesm/forums/ctsm-clm-mosart-rtm.134/
     about: For support with model use, troubleshooting, etc., please use the CTSM forum

.gitignore

@@ -13,8 +13,10 @@ manage_externals.log
 **/.svn/**
 .svn/
 
-# binary files
+# netcdf files
 *.nc
+# but don't ignore netcdf files here:
+!/python/ctsm/test/testinputs/*.nc
 
 # editor files
 *.swp

.lfsconfig

@@ -1,2 +1,7 @@
 [lfs]
-        fetchexclude = *
+	# We auto-fetch any netCDF files, because they are needed for
+	# running tests; however, we do NOT auto-fetch other binary
+	# files, in particular image files that are part of the
+	# documentation source (these are fetched as part of the
+	# documentation build process).
+	fetchinclude = *.nc

Externals.cfg

@@ -8,22 +8,22 @@ required = True
 local_path = components/cism
 protocol = git
 repo_url = https://github.com/ESCOMP/CISM-wrapper
-tag = cismwrap_2_1_87
+tag = cismwrap_2_1_93
 externals = Externals_CISM.cfg
 required = True
 
 [rtm]
 local_path = components/rtm
 protocol = git
 repo_url = https://github.com/ESCOMP/RTM
-tag = rtm1_0_77
+tag = rtm1_0_78
 required = True
 
 [mosart]
 local_path = components/mosart
 protocol = git
 repo_url = https://github.com/ESCOMP/MOSART
-tag = mosart1_0_43
+tag = mosart1_0_45
 required = True
 
 [mizuRoute]
@@ -37,33 +37,33 @@ required = True
 local_path = cime
 protocol = git
 repo_url = https://github.com/ESMCI/cime
-tag = cime6.0.4
+tag = cime6.0.11
 required = True
 
 [cmeps]
-tag = cmeps0.13.23
+tag = cmeps0.13.43
 protocol = git
 repo_url = https://github.com/ESCOMP/CMEPS.git
 local_path = components/cmeps
 required = True
 
 [cdeps]
-tag = cdeps0.12.19
+tag = cdeps0.12.32
 protocol = git
 repo_url = https://github.com/ESCOMP/CDEPS.git
 local_path = components/cdeps
 externals =  Externals_CDEPS.cfg
 required = True
 
 [cpl7]
-tag = cpl7.0.3
+tag = cpl7.0.7
 protocol = git
 repo_url = https://github.com/ESCOMP/CESM_CPL7andDataComps
 local_path = components/cpl7
 required = True
 
 [share]
-tag = share1.0.2
+tag = share1.0.10
 protocol = git
 repo_url = https://github.com/ESCOMP/CESM_share
 local_path = share
@@ -87,7 +87,7 @@ required = True
 local_path = doc/doc-builder
 protocol = git
 repo_url = https://github.com/ESMCI/doc-builder
-tag = v1.0.5
+tag = v1.0.8
 required = False
 
 [externals_description]

Externals_CLM.cfg

@@ -2,16 +2,8 @@
 local_path = src/fates
 protocol = git
 repo_url = https://github.com/NGEET/fates
-tag = sci.1.46.2_api.16.1.0
-required = True
-
-[PTCLM]
-local_path = tools/site_and_regional/PTCLM
-protocol = git
-repo_url = https://github.com/ESCOMP/PTCLM
-tag = PTCLM2_20210810
+tag = sci.1.52.0_api.20.0.0
 required = True
 
 [externals_description]
 schema_version = 1.0.0
-

README

@@ -2,12 +2,24 @@ $CTSMROOT/README                                          06/08/2018
 
 Community Terrestrial Systems Model (CTSM) science version 5.1  series -- source code, tools, 
 offline-build and test scripts. This gives you everything you need
-to run CTSM with CESM with datm8 to provide CRU NCEP or GSWP3 forcing data in 
+to run CTSM with CESM with the CMEPS driver and CDEPS data models to provide CRU NCEP or GSWP3 forcing data in 
 place of a modeled atmosphere.
 
+CMEPS is the Community Mediator for Earth Prediction Systems. And CDEPS is the
+Community Data Models for Earth Prediction System. They are both NUOPC based models
+used to drive the CESM (Community Earth System Model) of which CTSM is a component of.
+NUOPC is the National Unified Operational Prediction Capability a standard way of building
+coupled model systems. The NUOPC layer is based on the Earth System Modeling Framework (ESMF).
+
 For lists of current bugs (issues) and current development see the CTSM GitHub page:
 
-https://github.com/ESCOMP/ctsm
+https://github.com/ESCOMP/CTSM
+
+INFORMATION ON THE CMEPS DRIVER:
+
+https://escomp.github.io/CMEPS
+
+https://earthsystemmodeling.org/nuopc/
 
 IMPORTANT NOTE ON CESM CHECKOUT VERSUS A CTSM CHECKOUT:
 
@@ -28,32 +40,28 @@ General directory structure ($CTSMROOT):
 doc --------------- Documentation of CTSM.
 bld --------------- Template, configure and build-namelist scripts for clm.
 src --------------- CTSM Source code.
+lilac ------------- Lightweight Infrastructure for Land-Atmosphere Coupling (for coupling to a host atmosphere model)
 test -------------- CTSM Testing scripts for CTSM offline tools.
 tools ------------- CTSM Offline tools to prepare input datasets and process output.
 cime_config ------- Configuration files of cime for compsets and CTSM settings
 manage_externals -- Script to manage the external source directories
-python ------------ Some python modules mostly for use by run_sys_tests (but could be used elsewhere)
+python ------------ Some python modules mostly for use by run_sys_tests (but could be used elsewhere l
 
 Directory structure only for a CTSM checkout:
 
 components -------- Other active sub-components needed for CTSM to run (river routing and land-ice models)
+libraries --------- CESM libraries: MCT (Model Coupling Toolkit) and PIO
+share ------------- CESM shared code
 
 cime/scripts --------------- cesm/cime driver scripts
 
-cime/src/drivers/mct/main ----------- CESM top level driver source code.
-cime/src/drivers/mct/shr ------------ CESM top level driver shared code.
-cime/src/components/data_comps/datm - CESM Data model version 8 source code.
-cime/src/components/stub_comps/sice - CESM stub sea-ice model source code.
-cime/src/components/stub_comps/socn - CESM stub ocean model source code.
-cime/src/components/stub_comps/sglc - CESM stub glacier model source code.
-cime/src/externals ------------------ CESM external utility codes 
-                                      (Model Coupling Toolkit (MCT)
-                                      (Earth System Model Framework)
-                                      (timing -- code timing utility)
-                                      (pio -- Parallel Input/Output)
+components/cmeps -------------------- CESM top level driver (for NUOPC driver [which is the default]) source code.
+components/cdeps -------------------- CESM top level data model shared code (for NUOPC driver).
+cime/src/externals ------------------ CESM external utility codes  (genf90)
 components/cism --------------------- CESM Community land Ice Sheet Model.
 components/mosart ------------------- Model for Scale Adaptive River Transport
 components/rtm ---------------------- CESM River Transport Model.
+components/cpl7 --------------------- CESM top level driver for MCT driver (being deprecated)
 
 Top level documentation ($CTSMROOT):
 
@@ -92,7 +100,7 @@ run_sys_tests --------------- Python script to send the standard CTSM testing of
 
 parse_cime.cs.status -------- Script to parse test status files cs.status.* created by create_test
                               (can be used along with run_sys_tests)
-doc/Quickstart.GUIDE -------- Quick guide to using cpl7 scripts.
+doc/Quickstart.GUIDE -------- Quick guide to using NUOPC scripts.
 doc/IMPORTANT_NOTES --------- Some important notes about this version of 
                                                  clm, configuration modes and namelist items 
                                                  that are not validated or functional.
@@ -149,7 +157,7 @@ Source code directory structure:
 
 src/biogeochem ---- Biogeochemisty
 src/main ---------- Main control and high level code
-src/cpl ----------- Land model high level MCT and ESMF drivers
+src/cpl ----------- Land model high level caps for NUOPC driver (and MCT and LILAC)
 src/biogeophys ---- Biogeophysics (Hydrology)
 src/dyn_subgrid --- Dynamic land unit change
 src/init_interp --- Online interpolation
@@ -161,7 +169,7 @@ src/unit_test_shr - Unit test shared modules for unit testing
 src/unit_test_stubs Unit test stubs that replicate CTSM code simpler
 
 =============================================================================================
-    QUICKSTART: using the CPL7 scripts
+    QUICKSTART: using the NUOPC driver scripts
 =============================================================================================
 
          cd $CIMEROOT/scripts

README.CHECKLIST.new_case

@@ -0,0 +1,40 @@
+$CTSMROOT/README.CHECKLIST.new_case                       03/01/2021
+
+This is a check list of things to do when setting up a new case in order to help ensure everything is correct. There
+are lots of tiny details that need to be right and it's easy to get something wrong. So the first screening to make
+sure it's right is for you to carefully check through your case and make sure it's right.
+
+The following assumes you have created a new case and are in it's case directory.
+
+General Checklist to always do:
+
+ - Make sure CLM_ env settings are correct 
+   (./xmlquery -p CLM)
+ - Make sure you are using the correct CLM_PHYSICS_VERSION
+   (./xmlquery -p CLM_PHYSICS_VERSION)
+ - Make sure you are running the appropriate overall CLM vegetation model. 
+   The "-bgc" option of either Satellite Phenology (sp), or
+   Full BioGeoChemistry (bgc), or FATES (fates)
+   (./xmlquery -p CLM_BLDNML_OPTS)
+ - Also if you are running the bgc model, check to see if you should be running the prognostic crop model 
+   (option -crop in CLM_BLDNML_OPTS)
+ - Make sure the LND_TUNING_MODE is correct 
+   (./xmlquery LND_TUNING_MODE)
+ - For an "I compset" make sure you are running over the right forcing years 
+   (usually ./xmlquery -p DATM_YR)
+ - First and align year for streams should be the start year of a historical simulation 
+   (./xmlquery RUN_STARTDATE)
+   (grep stream_year_first CaseDocs/lnd_in; grep model_year_align CaseDocs/lnd_in)
+ - Last year for streams should be the last year you are going to run to (or beyond it) 
+   (grep stream_year_last CaseDocs/lnd_in)
+ - Make sure you are starting from appropriate spunup initial conditions 
+   (Check the run-type with: ./xmlquery RUN_TYPE)
+   (check finidat for a startup or hybrid simulation: grep finidat CaseDocs/lnd_in)
+   (check nrevsn for a branch simulation: grep nrevsn CaseDocs/lnd_in)
+ - Run for a month (or some short period) and go over the log files and especially the settings and files read in them.
+   (For an I case you especially want to look at the lnd.log and atm.log files)
+
+Some other suggestions on things that can be done:
+
+- Compare namelist files to an existing case if you are doing something almost the same as a previous simulation.
+- Ask another collaborator to look over your case directory

README.NUOPC_driver.md

@@ -0,0 +1,56 @@
+# $CTSMROOT/README.NUOPC_driver
+
+CTSM now by default uses the NUOPC based CMEPS driver!
+
+
+## What's new?
+
+MESH Files:
+Mesh files to describe grids are new in both the driver namelist and for example in any
+streams files.
+Full ESMF Library is used:
+The full ESMF Library is used and required to be built in order to run the model.
+Single Point cases:
+Single point cases can now set their location using PTS_LAT and PTS_LON.
+
+## What's removed?
+
+Domain files are no longer used. And mapping for regriding is created on the fly
+rather than using fixed mapping files in almost all cases. Runoff mapping files
+still need to be generated offline.
+
+## What files change?
+
+rpointer.drv becomes rpointer.cpl
+cpl.log.* files get's split into med.log.* and drv.log.*
+user_datm.streams.txt.* file changes goes into the user_nl_datm_streams files
+datm.streams.txt.* files are all in one file called datm.streams.xml
+
+## What XML variables change in your case?
+
+DATM_CLMNCEP_YR_* variables change to DATM_YR_*
+
+## New obscure options:
+
+ESMF_AWARE_THREADING --- ESMF is aware of threading (can have differing number of threads in components)
+CREATE_ESMF_PET_FILES -- Create output log files from ESMF for each Processor (PET)
+ESMF_VERBOSITY_LEVEL --- Verbosity level for ESMF logging
+ESMF_PROFILING_LEVEL --- Verbosity level for ESMF profiling
+
+nuopc.runseq is a text file that determines how the driver operates. You can change the operation
+by having an updated copy in your case directory.
+
+
+## What if I want to use the previous MCT driver?
+
+The MCT driver will be available for sometime going forward, but
+new development won't go into it, and it will eventually be removed.
+But, if you have to...
+Use the "--driver mct" command line option to create_newcase
+You can set COMP_INTERFACE in a case as well, but it won't create it with everything needed
+so we recommend setting up a case from scratch.
+
+
+For more notes see:
+
+https://docs.google.com/presentation/d/1yjiKSEV53JDAJbYxhpY2T9GTxlWFzQAn

README.md

@@ -25,10 +25,9 @@ and
 
 https://github.com/ESCOMP/ctsm/wiki/Recommended-git-setup
 
-For support with model use, troubleshooting, etc., please use the CTSM forum (or other
-appropriate forum) here:
-
-https://xenforo.cgd.ucar.edu/cesm/
+For support with model use, troubleshooting, etc., please use the [CTSM
+forum](https://bb.cgd.ucar.edu/cesm/forums/ctsm-clm-mosart-rtm.134/) or other appropriate forum (e.g., for
+infrastructure/porting questions) through the [CESM forums](https://bb.cgd.ucar.edu/cesm/).
 
 To get updates on CTSM tags and important notes on CTSM developments
 join our low traffic email list:

README_EXTERNALS.rst

@@ -30,10 +30,9 @@ More details on checkout_externals
 
 The file **Externals.cfg** in your top-level CTSM directory tells
 **checkout_externals** which tag/branch of each component should be
-brought in to generate your sandbox. (This file serves the same purpose
-as SVN_EXTERNAL_DIRECTORIES when CLM was in a subversion repository.)
+brought in to generate your sandbox. **Externals_CLM.cfg** is used similarly to point to the correct version of FATES (and possibly other CTSM-specific externals in the future); the below instructions referring to **Externals.cfg** also apply to modifying **Externals_CLM.cfg**.
 
-NOTE: Just like svn externals, checkout_externals will always attempt
+NOTE: checkout_externals will always attempt
 to make the working copy exactly match the externals description. If
 you manually modify an external without updating Externals.cfg, e.g. switch
 to a different tag, then rerunning checkout_externals will switch you
@@ -96,7 +95,7 @@ example below)::
   tag = cime5.4.0-alpha.20
   required = True
 
-Each entry specifies either a tag or a branch. To point to a new tag:
+Each entry specifies either a tag, a hash or a branch. To point to a new tag:
 
 #. Modify the relevant entry/entries in **Externals.cfg** (e.g., changing
    ``cime5.4.0-alpha.20`` to ``cime5.4.0-alpha.21`` above)
@@ -105,6 +104,10 @@ Each entry specifies either a tag or a branch. To point to a new tag:
 
      ./manage_externals/checkout_externals
 
+To point to a hash, the process is the same, except also change ``tag = ...`` to ``hash = ...``.
+
+To point to a branch, use ``branch = ...``. Pointing to a branch means that, each time you run ``manage_externals/checkout_externals`` you will get the current latest version of that branch. This can be convenient for in-progress development work, but should not be used when you need a stable version for scientific simulations. There are a number of gotchas with this workflow, so in general you should default to pointing to fixed hashes. (For CTSM master, we require a fixed hash or, usually, a tag.)
+
 Keep in mind that changing individual components from a tag may result
 in an invalid model (won't compile, won't run, not scientifically
 meaningful) and is unsupported.