Merge branch 'b4b-dev' into swenson_ctsm_docs

Author: slevis-lmwg

doc/source/tech_note/References/CLM50_Tech_Note_References.rst

@@ -1754,6 +1754,10 @@ Xiaodong, Y. and H.H. Shugart, 2005. FAREAST: a forest gap model to simulate dyn
 
 Xu, C., R. Fisher, S. D. Wullschleger, C. J. Wilson, M. Cai, and N. G. McDowell, 2012: Toward a mechanistic modeling of nitrogen limitation on vegetation dynamics. PloS one, 7:e37914.
 
+.. _Yangetal1995:
+
+Yang, Z.-L., R.E. Dickinson, A. Henderson-Sellers, and A.J. Pitman, 1995. Preliminary study of spin-up processes in land surface models with the first stage data of Project for Intercomparison of Land Surface Parameterization Schemes Phase 1(a). J. Geophys. Res. 100:16,553-16,578.
+
 .. _Yang1998:
 
 Yang, Z.-L. 1998. Technical note of a 10-layer soil moisture and temperature model. Unpublished manuscript.

doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png

@@ -6,20 +6,77 @@
  Spinning up the Satellite Phenology Model
 ===========================================
 
-To spin-up the CLMSP model you merely need to run CLMSP for about 50 simulation years starting from arbitrary initial conditions. You then use the final restart file for initial conditions in other simulations. Because this is a straight forward operation we will NOT give the details on how to do that here, but leave it as an exercise for the reader. See the Example :numref:`eg-final-clmbgc-spinup` as an example of doing this as the last step for CLMCN.
+The spin-up of a land surface model is generally defined as an adjustment process as the model approaches equilibrium in its state variables (:ref:`Yang et al. 1995<Yangetal1995>`). This is usually accomplished by forcing the model with repeated years of identical atmospheric forcing until the model state at year ``n+1`` is the same as that at year ``n`` within some defined threshold in the state variables. 
 
-You can also start from a default initial file that is setup as part of the selected compset. :numref:`Figure SP spinup plot for 1850` shows spinup behavior for an 1850 SP case that loops over one year of coupler history output for atmospheric forcing (generated from the fully coupled model), initialized with an initial file generated from a GSWP3 atmospheric forcing case. Note that it takes less than 10 years for state variables such as FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), H2OSOI (soil water), and TSOI (soil temperature) to reach a specified equilibrium state (denoted by the dotted lines) due to the different atmospheric forcing. TWS (total water storage) may take a bit longer.
+To spin-up the CLM60SP model you generally need to run CLM60SP for a few cycles of repeated atmospheric forcing starting from arbitrary initial conditions, the main goal being to ensure that the turbulent fluxes and soil water and temperature have reached equilibrium (minimal trends). You then use the final restart file resulting from that simulation as initial conditions in other simulations.  Alternatively, you can also start from an initial file that is typically already provided for you as part of the selected compset. Generally, this will allow for shorter spinup times if your simulation configuration is similar to the one run to generate the default initial file.
 
-.. _Figure SP spinup plot for 1850:
+The following steps illustrate how to setup and run a 51 year CLM60SP spinup from arbitrary initial conditions using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution.  From a checkout of the CLM code (choose your own case name):
+::
 
-.. figure:: image1.png
+   cd cime/scripts
+   ./create_newcase --case Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX
+   cd Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000/
+   ./case.setup
+   ./xmlchange CLM_FORCE_COLDSTART=on
+   ./xmlchange RUN_STARTDATE=0001-01-01
+   ./xmlchange DATM_YR_START=1991
+   ./xmlchange DATM_YR_END=2000
+   ./xmlchange DATM_YR_ALIGN=1
+   ./xmlchange STOP_OPTION=nyears
+   ./xmlchange STOP_N=51
+   ./case.build
+   ./case.submit
 
- SP spinup plot for year 1850. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl.
+Setting ``CLM_FORCE_COLDSTART=on`` forces the model to use arbitrary initial conditions (see Section :numref:`Initialization` for a description of these initial conditions).  This will result in ``finidat=' '`` in the ``lnd_in`` namelist. Spinups are generally started at year 1 (``RUN_STARTDATE=0001-01-01``). Here we've chosen to loop over years 1991-2000 (``DATM_YR_START=1991``, ``DATM_YR_END=2000``) of the atmospheric forcing (10 years total), align model year 1 (``DATM_YR_ALIGN=1``) with the first year of atmospheric forcing, and run for 51 years (``STOP_OPTION=nyears``, ``STOP_N=51``). Ten years of atmospheric forcing was chosen to introduce some interannual variability in the forcing, e.g., to increase the chances of the model being forced by wet and dry years.
 
-:numref:`Figure SP spinup plot for 2000 CO2` shows spinup behavior for the same case but also changes CO2 to present-day conditions (379ppmv). Again, it takes about 10 years to reach equilibrium.
+The spinup stability script available in the CLM checkout at ``tools/contrib/SpinupStability_SP_v10.ncl`` can be used to assess the stability or equilibrium of key model variables. Key settings in that script for this example simulation are
+::
 
-.. _Figure SP spinup plot for 2000 CO2:
+   caseid = "Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000"
+   subper = 10
 
-.. figure:: image2.png
+The ``subper`` setting tells the script how many years of atmospheric forcing were repeated, thus the equilibrium state of the model in this example is evaluated every 10 years.
 
- SP spinup plot for year 2000 CO2. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using .../tools/contrib/SpinupStability_SP.ncl.
+:numref:`Figure CLM60SP spinup plot for arbitrary initial conditions` shows spinup behavior for this simulation. Variables are plotted every 10 years, hence six points (years 1, 11, 21, 31, 41, and 51) are plotted in the leftmost plots for each variable.  These include FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), FPSN (photosynthesis), H2OSOI (soil water at layer 8 which is about 1 meter), TSOI (soil temperature at layer 10 which is about 3 meters), and TWS (total water storage). The speed at which these variables reach a specified equilibrium state (denoted by falling within the dotted lines in the rightmost plots for each variable) varies by variable, TWS generally takes the longest to equilibrium.  The plot in the lower left denotes the percent of land area that is not in TWS equilibrium. The contour plots show which grid cells are not in equilibrium for the last two cycles of atmospheric forcing. The equilibrium thresholds are fairly arbitrary for the SP configuration and can be chosen by the user.  The current settings are
+::
+
+  glob_thresh_fsh = 0.02         ; global threshold for FSH equilibrium (delta W m-2 / yr)
+  glob_thresh_lh = 0.02          ; global threshold for EFLX_LH_TOT equilibrium (delta W m-2 / yr)
+  glob_thresh_gpp = 0.02         ; global threshold for FPSN equilibrium (delta PgC / yr)
+  glob_thresh_tws = 0.001        ; global threshold for TWS equilibrium (delta m / yr)
+  glob_thresh_h2osoi = 0.01      ; global threshold for H2OSOI equilibrium (delta mm mm-3 / yr)
+  glob_thresh_tsoi = 0.02        ; global threshold for TSOI equilibrium (delta K / yr)
+  glob_thresh_area = 3.0         ; global threshold percent area with TWS disequilibrium gt 0.01 m
+
+.. _Figure CLM60SP spinup plot for arbitrary initial conditions:
+
+.. figure:: Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png
+
+ SP spinup plot for arbitrary initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``.
+
+You can also start from a default initial file that is provided as part of the selected compset. The following steps illustrate how to setup and run a 51 year CLM60SP spinup from default initial conditions again using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution.  From a checkout of the CLM code (choose your own case name):
+::
+
+   cd cime/scripts
+   ./create_newcase --case Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX
+   cd Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000/
+   ./case.setup
+   echo "use_init_interp = .true" >> user_nl_clm
+   ./xmlchange RUN_STARTDATE=0001-01-01
+   ./xmlchange DATM_YR_START=1991
+   ./xmlchange DATM_YR_END=2000
+   ./xmlchange DATM_YR_ALIGN=1
+   ./xmlchange STOP_OPTION=nyears
+   ./xmlchange STOP_N=51
+   ./case.build
+   ./case.submit
+
+The difference from the previous simulation is that we don't set ``CLM_FORCE_COLDSTART=on`` so that the model uses the default provided initial conditions.  In this case, setting ``use_init_interp = .true`` is required because the model configuration used is slightly different from that used to generate the initial file.
+
+:numref:`Figure CLM60SP spinup plot for default initial conditions` shows spinup behavior for this simulation. Here we can see that equilbrium is reached much sooner because the default initial file is from a spinup where the model configuration was very similar to this one.
+
+.. _Figure CLM60SP spinup plot for default initial conditions:
+
+.. figure:: Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png
+
+ SP spinup plot for default initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``.

doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png

@@ -12,3 +12,5 @@ Many of our Python-based tools require non-standard Python modules to be install
    ./py_env_create
 
 and that script will install the ``ctsm_pylib`` environment for you. If ``ctsm_pylib`` already exists, it will give you options on how to handle that.
+
+As CTSM Python tools continue to be developed, they may evolve to require an updated version of ``ctsm_pylib``. If you encounter "Module not found" errors, you may need to run ``py_env_create`` again; for a given CTSM commit (version), this will always install what's needed to run all the CTSM Python tools in that commmit.