Merge pull request #330 from NCAR/CLM5_tutorial

CLM5-DART Tutorial

CHANGELOG.rst

@@ -22,6 +22,15 @@ individual files.
 
 The changes are now listed with the most recent at the top.
 
+**March 22 2022 :: CLM5-DART Tutorial. Tag: v9.15.0**
+
+- New CLM5-DART tutorial providing new users with 13 steps
+  for download, setup, execution, and diagnosis of a simple 
+  global assimilation run.
+- Stage_cesm_files script corrected to re-stage prior inflation
+  files correctly and provide reproducibility
+
+
 **March 10th 2022 :: Tracer advection model. Tag v9.14.0**
 
 - New model for tracer advection based on Lorenz_96 using a

README.rst

@@ -351,8 +351,9 @@ References
    theory/readme
    theory/conditional-probability-bayes-theorem
    guide/DART_LAB/DART_LAB
+   CLM-DART Tutorial <models/clm/tutorial/README>
    WRF-DART Tutorial <models/wrf/tutorial/README>
-
+   
 .. toctree::
    :maxdepth: 2
 .. toctree::

conf.py

@@ -21,7 +21,7 @@
 author = 'Data Assimilation Research Section'
 
 # The full version, including alpha/beta/rc tags
-release = '9.14.0'
+release = '9.15.0'
 master_doc = 'README'
 
 # -- General configuration ---------------------------------------------------

models/clm/readme.rst

@@ -11,14 +11,24 @@ This is the DART interface to the
 `CESM2 Community Land Model. <https://www.cesm.ucar.edu/models/cesm2/land/>`__
 Specifically, CESM **release-cesm2.2.0** using CLM **release-cesm2.2.01**
 
-It is **strongly** recommended that you become familiar with running a multi-instance 
-experiment in CESM **before** you try to run DART/CLM. The DART/CLM facility uses 
-language and concepts that should be familiar to CESM users. The DART/CLM capability 
+This document is most useful if the user has a prior understanding of running CESM
+and also running CLM-DART.  For this reason **we strongly recommend the following
+two steps be completed before reviewing this document**:
+
+**First**, we  recommend that you become familiar with running a single or multi-instance 
+experiment in CESM (i.e. a CLM 'free' run) before you try to run CLM-DART. The CLM-DART
+software uses language and concepts that should be familiar to CESM users. The CLM-DART capability 
 is entirely dependent on the multi-instance capability of CESM, first supported in 
 its entirety in CESM1.1.1.  Consequently, this version or newer is required to run 
 CLM/DART. The 
 `CTSM Documentation <https://escomp.github.io/ctsm-docs/versions/master/html/index.html>`__
 has reference material for CLM.
+
+**Second**, we recommend the user complete the :doc:`CLM5-DART Tutorial. <tutorial/README>` 
+This tutorial provides the user with 13 steps of hands-on experience for downloading, compiling, editing,
+executing,and diagnosing a simple CLM5-DART assimilation run. It will provide users with
+skills to modify the CLM-DART scripts for their own research applications.
+
 
 DART uses the multi-instance capability of CESM, which means that DART is not 
 responsible for advancing the model.  This GREATLY simplifies the traditional DART 
@@ -714,24 +724,18 @@ Future plans:
 1. Implement a lookup table that relates the observation location to a dominant PFT or COLUMN
    so the *model_interpolate* code can average quantities from similar PFTs or COLUMNs instead
    of everything in the entire grid cell.
-2. Implement a robust update_snow() routine that takes the modified SWE and 
-   repartitions it into the respective snow layers in a manner that works with both 
-   CLM4.5 and CLM5. This may mean modifying the clm_variables list to contain 
-   SNOWDP, H2OSOI_LIQ, H2OSOI_ICE, T_SOISNO, and others that may not be in the UPDATE list.
-3. Implement a fast way to get the quantities needed for the calculation of 
+2. Implement a fast way to get the quantities needed for the calculation of 
    radiative transfer models - needs a whole column of CLM variables, redundant if 
    multiple frequencies are used.
-4. Figure out what to do when one or more of the ensemble members does not have 
+3. Figure out what to do when one or more of the ensemble members does not have 
    snow/leaves/etc. when the observation indicates there should be. Ditto for removing 
    snow/leaves/etc. when the observation indicates otherwise.
-5. Right now, the soil moisture observation operator is used by the COSMOS code to 
+4. Right now, the soil moisture observation operator is used by the COSMOS code to 
    calculate the expected neutron intensity counts. This is the right idea, however, 
    the COSMOS forward operator uses m3/m3 and the CLM units are kg/m2. I have not 
    checked to see if they are, in fact, identical. This brings up a bigger issue in 
    that the soil moisture observation operator would also be used to calculate whatever 
    a TDT probe or ??? would measure. What units are they in? Can one operator support both?
-6. One of the ``CESM_DART_config`` *stage* scripts should reset the inflation pointer 
-   files based on the restart date?
 
 
 

models/clm/shell_scripts/cesm2_2/CLM5_setup_assimilation

@@ -397,8 +397,18 @@ cat << EndOfText >! stage_cesm_files
 #                           the very first one.
 #  2) be sure 'restart_time' is set to the day and time that you want to
 #     restart from if not the initial time.
+#
+#  3) be sure the prior inflation files are re-staged 
+#     STAGE_INFLATION FALSE => no restage, default setting when case is first created
+#     STAGE_INFLATION TRUE  => you are starting from a previous step or
+#                              from the initial time            
+#
+#
+#
 
 set restart_time = $init_time
+set STAGE_INFLATION = FALSE
+
 
 # get the settings for this case from the CESM environment
 cd ${caseroot}
@@ -523,6 +533,93 @@ else     # CONTINUE_RUN == FALSE
    echo "All files set to run the FIRST experiment step at time" $init_time
 
 endif
+
+   #----------------------------------------------------------------------
+   # This block modifies the inflation rpointer files (priorinf_pointer_d{01-03}.txt)
+   # such that the DART code uses the inflation files (clm_output_priorinf*.nc) from the 
+   # previous time step (e.g. restart_time)
+   # e.g. the following files:
+   # clm_output_priorinf_mean_d01.2011-01-03-00000.nc
+   # clm_output_priorinf_sd_d01.2011-01-03-00000.nc
+   # would be used to apply inflation for time step: 2011-01-04
+   #----------------------------------------------------------------------
+
+if ( \${STAGE_INFLATION} == TRUE) then
+
+# Confirm inflation is being used.
+
+set  MYSTRING = \`grep inf_flavor input.nml\`
+set  MYSTRING = \`echo \$MYSTRING | sed -e "s#[=,'\.]# #g"\`
+set  PRIOR_INF = \$MYSTRING[2]
+set  POSTE_INF = \$MYSTRING[3]
+
+  if ( \$PRIOR_INF != 0 ) then
+
+    if  ( \${CONTINUE_RUN} == FALSE) then
+       # Generate cookie such that fill_inflation_restart 
+       # generates inflation files
+
+       date >! \${RUNDIR}/clm_inflation_cookie
+
+    else  # CONTINUE_RUN=TRUE
+
+         if ( ! -e priorinf_pointer_d01.txt ) then
+
+         echo "ERROR: priorinf_pointer_d01.txt file not found"
+         echo "At least 1 domain pointer file should exist if assimilation run is re-staged"
+         echo "Prior inflation files will not be re-staged"
+         exit 2
+
+         endif
+
+       @ domaincount = 0
+       echo "     "
+       echo "Re-setting priorinf pointer files for " \$restart_time
+       echo "     "
+
+     foreach POINTERFILE ( priorinf_pointer*.txt )
+
+        @ domaincount ++
+
+        set POINTERFILE = \`printf priorinf_pointer_d%02d.txt \$domaincount\`
+        echo "Located inflation pointer file: " \$POINTERFILE
+        set DOMAIN = \`printf _d%02d \$domaincount\`
+        set FILE   = \`printf clm_output_priorinf_mean\${DOMAIN}.\${restart_time}.nc\`
+
+         if ( ! -e \${FILE} ) then
+         echo "ERROR: \${FILE} not found"
+         echo "This file must exist to be inserted in \${POINTERFILE}"
+         echo "Prior inflation file will not be re-staged"
+         exit 3
+         endif
+
+        set SDFILE = \`echo \$FILE | sed -e "s#mean#sd#"\`
+        echo "Inserting the prior inflation file into pointer: " \$FILE
+        echo \$FILE   >! \$POINTERFILE
+        echo \$SDFILE >> \$POINTERFILE
+
+     end
+
+     echo "The priorinf pointer files are reset to rerun experiment at: " \$restart_time
+     echo "    "
+
+    endif
+
+  else   # \$PRIOR_INF==0
+
+    echo "Warning: Prior inflation is turned off for this assimilation"
+    echo "Inflation files will not be re-staged"
+    echo "Check your input.nml inflation settings"
+
+  endif
+
+   if ( \$POSTE_INF != 0 ) then
+      echo "ERROR: stage_cesm_files not configured to stage posterior inflation files."
+      exit 4
+   endif
+
+endif
+
 exit 0
 
 EndOfText