Update the README files

rgknox · Apr 20, 2024 · 1c99a7b · 1c99a7b
1 parent 7746e9f
commit 1c99a7b
Show file tree

Hide file tree

Showing 11 changed files with 92 additions and 81 deletions.
diff --git a/README b/README
@@ -1,6 +1,6 @@
-$CTSMROOT/README                                          06/08/2018
+$CTSMROOT/README                                          04/19/2023
 
-Community Terrestrial Systems Model (CTSM) science version 5.1  series -- source code, tools, 
+Community Terrestrial Systems Model (CTSM) science version 5.2  series -- source code, tools, 
 offline-build and test scripts. This gives you everything you need
 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.
@@ -35,41 +35,47 @@ this checkout. For a CESM checkout $CIMEROOT will be the "cime" directory
 beneath the top level directory. For a CTSM checkout $CIMEROOT will
 be $CTSMROOT/cime.
 
+IMPORTANT NOTE ABOUT (deprecated)
+
+Anything marked with (deprecated) is something is going to be removed in a future update.
+Often this means it will be replaced with something else.
+
+
 General directory structure ($CTSMROOT):
 
 doc --------------- Documentation of CTSM.
-bld --------------- Template, configure and build-namelist scripts for clm.
+bld --------------- build-namelist scripts for CTSM.
 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.
+test -------------- CTSM Testing scripts for CTSM offline tools (deprecated)
 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
+manage_externals -- Script to manage the external source directories (deprecated)
 py_env_create ----- Script to setup the python environment for CTSM python tools using conda
-python ------------ Some python modules mostly for use by run_sys_tests (but could be used elsewhere l
+python ------------ Python modules used in tools and testing and automated checking of ALL CTSM python scirpts
 
 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
+libraries --------- CESM libraries: MCT (Model Coupling Toolkit) and PIO (deprecated)
 share ------------- CESM shared code
 ccs_config -------- CIME configure files (for grids, compsets, and machines) for CESM
 
 cime/scripts --------------- cesm/cime driver scripts
 
 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)
+components/cpl7 --------------------- CESM top level driver for MCT driver (deprecated will be removed)
 
 Top level documentation ($CTSMROOT):
 
 README ------------------- This file
+README.md ---------------- File that displays on github under https::/github.com/ESCOMP/CTSM.git
 README.rst --------------- File that displays under the project in github
-README_EXTERNALS.rst ----- Information on how to work with subversion externals for clm
+README_EXTERNALS.rst ----- Information on how to work with manage_externals for CTSM (deprecated)
 CODE_OF_CONDUCT.md ------- Code of Conduct for how to work with each other on the CTSM project
 Copyright ---------------- CESM Copyright file
 doc/UpdateChangeLog.pl --- Script to add documentation on a tag to the
@@ -93,7 +99,7 @@ bld/namelist_files/namelist_defaults_ctsm.xml ----- Default values
 Important files in main directories (under $CTSMROOT):
 =============================================================================================
 
-Externals.cfg --------------- File for management of the main high level externals
+Externals.cfg --------------- File for management of the main high level external (deprecated)
 Externals_CLM.cfg ----------- File for management of the CTSM specific externals (i.e. FATES)
 
 run_sys_tests --------------- Python script to send the standard CTSM testing off (submits
@@ -104,18 +110,15 @@ parse_cime.cs.status -------- Script to parse test status files cs.status.* crea
                               (can be used along with run_sys_tests)
 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 
+                                                 CTSM, configuration modes and namelist items 
                                                  that are not validated or functional.
 doc/ChangeLog --------------- Detailed list of changes for each model version.
 doc/ChangeSum --------------- Summary one-line list of changes for each 
                               model version.
-doc/README ------------------ Documentation similar to this file
 doc/UsersGuide -------------- CTSM Users Guide
 doc/IMPORTANT_NOTES --------- Some important notes on caveats for some configurations/namelist items
 
-bld/README ------------------ Description of how to use the configure and
-                              build-namelist scripts.
-bld/configure --------------- Script to prepare CTSM to be built.
+bld/README ------------------ Description of how to use the build-namelist scripts.
 bld/build-namelist ---------- Script to build CTSM namelists.
 
 cime_config/buildnml ------------- Build the CTSM namelist for CIME
@@ -128,22 +131,15 @@ cime_config/testdefs ------------- Directory for specification of CTSM testing
 cime_config/testdefs/ExpectedTestFails.xml -- List of tests that are expected to fail
 cime_config/usermods_dirs -------- Directories of sets of user-modification subdirs
                                    (These are directories that add specific user modifications to
-                                    simulations created using "cime/scripts/create_newcase --user-mods-dir".
-                                    Current sub directories are for various CMIP6 configurations)
-
-test/tools/test_driver.sh -- Script for general software testing of 
-                             CTSM's offline tools.
+                                    simulations created using "cime/scripts/create_newcase --user-mods-dir".)
 
 tools/mksurfdata_esmf --------- Directory to build program to create surface dataset 
                                 at any resolution.
 tools/mkprocdata_map ---------- Process history data from unstructed grids to a gridded 
                                 format.
-tools/mkmapgrids -------------- NCL script to create a SCRIP grid file for a regular lat/lon grid
-tools/modify_fsurdat ---------- Script to modify existing surface datasets in standard ways
-tools/ncl_scripts  ------------ Directory of NCL and perl scripts to do various
-                                tasks. Most notably to plot perturbation error growth
-                                testing and to extract regional information from
-                                global datasets for single-point/regional simulations.
+tools/mkmapgrids -------------- NCL script to create a SCRIP grid file for a regular lat/lon grid (deprecated)
+tools/crop_calendars ---------- Tools to process and process and create crop calendar datasets for CTSM
+tools/modify_input_files ------ Script to modify existing CTSM input datasets in standard ways
 tools/site_and_regional ------- Scripts to create input datasets for single site and regional
                                 cases, primarily by modifying existing global datasets
 tools/contrib ----------------- Miscellansous useful scripts for pre and post processing
@@ -166,6 +162,7 @@ scr/fates --------- FATES model and sub-directories
                     Functionally Assembled Terrestrial Ecosystem Simulator (FATES)
                     Experimental Ecosystem Demography model
 src/utils --------- Utility codes
+src/self_tests ---- Internal testing (unit tests run as a part of a CTSM simulation)
 src/unit_test_shr - Unit test shared modules for unit testing
 src/unit_test_stubs Unit test stubs that replicate CTSM code simpler
 
@@ -175,11 +172,10 @@ src/unit_test_stubs Unit test stubs that replicate CTSM code simpler
 
          cd $CIMEROOT/scripts
          ./create_newcase            # get help on how to run create_newcase
-         ./create_newcase --case testI --res f19_g17_gl4 --compset I2000Clm50BgcCrop
+         ./create_newcase --case testI --res f19_g17_gl4 --compset I2000Clm60BgcCrop
                                      # create new "I" case for default machine at 1.9x2.5_gx1v7 
-                                     # with 4km greenland ice sheetres resolution
-                                     # "I2000Clm50BgcCrop" case is clm5_0 active, datm8, and inactive ice/ocn
-                                     # With no-evolve ice-sheet, and MOSART for river-routing
+                                     # "I2000Clm60BgcCrop" case is clm6_0 physics, CDEPS, and inactive ice/ocn/glc
+                                     # and MOSART for river-routing
          cd testI
          ./case.setup                # create the $CASE.run file
          ./case.build                # build model and create namelists

diff --git a/README.CHECKLIST.new_case b/README.CHECKLIST.new_case
@@ -22,6 +22,8 @@ General Checklist to always do:
    (./xmlquery LND_TUNING_MODE)
  - For an "I compset" make sure you are running over the right forcing years 
    (usually ./xmlquery -p DATM_YR)
+ - Again for an "I compset" make sure the DATM streams are operating over the right years
+   (look at the CaseDocs/datm.streams.xml file)
  - 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)

diff --git a/README.NUOPC_driver.md b/README.NUOPC_driver.md
@@ -41,15 +41,10 @@ nuopc.runseq is a text file that determines how the driver operates. You can cha
 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.
+## What if I want to use the MCT driver?
 
+The MCT driver is now deprecated, and will be removed. So at this point we don't
+suggest using it anymore.
 
 For more notes see:
 

diff --git a/README.md b/README.md
@@ -50,12 +50,18 @@ Software engineering team:
 - [Ryan Knox](https://github.com/rgknox)
 
 Science team:
-- [Dave Lawrence](https://github.com/dlawrenncar)
 - [Will Wieder](https://github.com/wwieder)
+- [Dave Lawrence](https://github.com/dlawrenncar)
 - [Danica Lombardozzi](https://github.com/danicalombardozzi)
 - [Keith Oleson](https://github.com/olyson)
 - [Sean Swenson](https://github.com/swensosc)
-- [Jackie Shuman](https://github.com/jkshuman)
 - [Peter Lawrence](https://github.com/lawrencepj1)
-- [Rosie Fisher](https://github.com/rosiealice)
 - Gordon Bonan
+
+FATES Project:
+- https://github.com/NGEET/fates?tab=readme-ov-file
+
+Perturbed Parameter Experiment (PPE) Science team:
+- [Katie Dagon] (https://github.com/katiedagon)
+- [Daniel Kennedy] (https://github.com/djk2120)
+- [Linnea Hawkins] (https://github.com/linniahawkins)
diff --git a/README_EXTERNALS.rst b/README_EXTERNALS.rst
@@ -1,6 +1,11 @@
 Obtaining the full model code and associated scripting infrastructure
 =====================================================================
 
+[!CAUTION]
+This is deprecated and will be replaced with git submodules. See
+https://github.com/ESCOMP/CTSM/pull/2443
+
+
 CTSM is released via GitHub. You will need some familiarity with git in order
 to modify the code and commit these changes. However, to simply checkout and run the
 code, no git knowledge is required other than what is documented in the following steps.

diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml
@@ -171,7 +171,7 @@ dust optics type for SNICAR snow albedo calculation
 <entry id="snicar_snw_shape" type="char*25" category="clm_physics"
        group="clm_inparm" valid_values="sphere,spheroid,hexagonal_plate,koch_snowflake" value="hexagonal_plate" >
 snow grain shape used in SNICAR snow albedo calculation
-(snicar_dust_optics='hexagonal_plate' is supported in ctsm5.1 and 'sphere' in older model versions; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
+(snicar_snw_shape='hexagonal_plate' is supported in ctsm5.1 and 'sphere' in older model versions; others are EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
 </entry>
 
 <entry id="snicar_use_aerosol" type="logical" category="clm_physics"
@@ -1719,7 +1719,6 @@ prescribed data.
 <entry id="use_lai_streams" type="logical" category="physics"
         group="clm_inparm" valid_values="" value=".false.">
 Toggle to turn on use of LAI streams in place of the LAI on the surface dataset when using Satellite Phenology mode.
-(EXPERIMENTAL, UNSUPPORTED, and UNTESTED!)
 </entry>
 
 <entry id="stream_year_first_lai" type="integer" category="datasets"

diff --git a/doc/.ChangeLog_template b/doc/.ChangeLog_template
@@ -31,7 +31,7 @@ Bugs fixed
 ----------
 [Remove any lines that don't apply. Remove entire section if nothing applies.]
 
-CTSM issues fixed (include CTSM Issue #):
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
 
 Notes of particular relevance for users
 ---------------------------------------
@@ -67,11 +67,7 @@ Testing summary:
 Nearly all CTSM tags should undergo 'regular' (aux_clm) testing.
 However, it occasionally makes sense to do more or less system testing;
 here is guidance on different available levels of system testing:
-    a) no system testing (for use when the only changes are ones that
-                          have absolutely no impact on system runs; this
-                          includes documentation-only tags, tags that
-                          just change the tools or some python code that
-                          does not impact system runs, etc.)
+    a) no system testing (this would normally be something that would go to the b4b-dev branch)
     b) minimal (for use in rare cases where only a small change with
                 known behavior is added ... eg. a minor bug fix. This
 		might be to just run the "short" test list, or to run
@@ -80,10 +76,10 @@ here is guidance on different available levels of system testing:
                     run the python testing listed below)
     d) regular (regular tests on normal machines if CTSM source is modified)
     e) release (regular tests plus the fates, ctsm_sci, mosart and rtm test lists
-                and normally all of the ancillary tests (build-namelist, python, ptclm, etc.)
+                and normally all of the ancillary tests (build-namelist, python, etc.)
 		would be run as well)
 
-In addition, various other tests of the tools, python and perl
+In addition, various other tests of the tools, python and namelist script
 infrastructure should be run when appropriate, as described below.
 
 ...]

diff --git a/doc/.release-ChangeLog_template b/doc/.release-ChangeLog_template
@@ -44,11 +44,6 @@ Testing:
     cheyenne - 
     izumi ----
 
-  PTCLM testing (components/clm/tools/shared/PTCLM/test):
-
-     cheyenne - 
-     izumi ----
-
   regular tests (aux_clm):
 
     cheyenne_intel ---- 

diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -172,19 +172,20 @@ Testing summary: regular ctsm_sci fates mosart rtm tools python
     izumi ------- OK
 
   fates tests: (give name of baseline if different from CTSM tagname, normally fates baselines are fates-sci.1.72.2_api.34.0.0-ctsm5.2.0)
-    derecho -----
-    izumi -------
+    derecho ----- OK
+    izumi ------- OK (also ERS_D_Ld30.f45_f45_mg37.I2000Clm50FatesCruRsGs.izumi_nag.clm-FatesColdLandUse FAIL because of conda issues)
 
   any other testing (give details below):
 
   ctsm_sci
      derecho ---- PASS
 
   rtm  (rtm1_0_79_ctsm5.2.0)
-     derecho ----
+     derecho ---- PASS
 
   mosart (mosart1_0_49_ctsm5.2.0)
-     derecho ----
+     derecho ---- OK
+     izumi ------ (conda issues)
 
 If the tag used for baseline comparisons was NOT the previous tag, note that here: ctsm5.1.dev175
 
@@ -211,6 +212,7 @@ Other details
 Pull Requests that document the changes (include PR ids):
 (https://github.com/ESCOMP/ctsm/pull)
 
+  #2464 -- Update ctsm5.2 branch to ctsm5.1.dev176 and some small updates
   #2417 -- Addition of clm6_0 physics option
   #2447 -- Update ctsm5.2 branch to ctsm5.1.dev175
   #2427 -- Merge ctsm5.2 branch up to ctsm5.1.dev174

diff --git a/doc/IMPORTANT_NOTES b/doc/IMPORTANT_NOTES
@@ -1,5 +1,5 @@
-$CTSMROOT/doc/IMPORTANT_NOTES					Jun/08/2018
-								Erik Kluzek
+$CTSMROOT/doc/IMPORTANT_NOTES					Apr/19/2024
+    								            Erik Kluzek
 
 Namelist items that are not regularly tested or used. Some aren't even implemented.
 
@@ -13,31 +13,46 @@ Namelist items that are not regularly tested or used. Some aren't even implement
     allowlakeprod
     carbon_resp_opt
     ch4offline
-    fin_use_fsat
-    lake_decomp_fact
+    do_sno_oc
+    finundation_method = h2osfc
     no_frozen_nitrif_denitrif
     perchroot
     perchroot_alt
     reduce_dayl_factor
     replenishlakec
+    snicar_dust_optics /= sahara
+    snicar_numrad_snw /= 5
+    snicar_snobc_intmix /= TRUE
+    snicar_snodst_intmix /= TRUE
+    snicar_snw_shape /= hexagonal_plate
+    snicar_solarspec /= mid_latitude_winter
+    snicar_use_aerosol /= FALSE
     urban_traffic
+    usefrootc
+    use_cndv (deprecated)
     use_extralakelayers
-    use_lai_streams
-    use_cndv
-    use_snicar_frc
+    use_soil_moisture_streams
     use_vichydro
-    usefrootc
     vcmax_opt = 4
 
     FATES namelist options: FATES is a new experiemental subcomponent where all of it's options are
                             under current development. As such FATES and all of it's options should
                             be considered experimental.
 
+   fates_history_dimlevel
+   fates_inventory_ctrl_filename
+   fates_parteh_mode
+   fates_spitfire_mode
    use_fates
-   use_fates_spitfire
+   use_fates_cohort_age_tracking
+   use_fates_ed_prescribed_phys
+   use_fates_ed_st3
+   use_fates_fixed_biogeog
    use_fates_logging
+   use_fates_luh
+   use_fates_nocomp
    use_fates_planthydro
-   use_fates_ed_st3
-   use_fates_ed_prescribed_phys
+   use_fates_sp
+   use_fates_spitfire
+   use_fates_tree_damage
    use_fates_inventory_init
-   fates_inventory_ctrl_filename