Merge pull request #11 from ekluzek/changelog_readme_update

Updates to the ctsm5.3.0 ChangeLog and README files

README

@@ -1,6 +1,6 @@
-$CTSMROOT/README                                          04/19/2023
+$CTSMROOT/README                                          09/05/2024
 
-Community Terrestrial Systems Model (CTSM) science version 5.2  series -- source code, tools, 
+Community Terrestrial Systems Model (CTSM) science version 5.3 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.
@@ -51,7 +51,7 @@ tools ------------- CTSM Offline tools to prepare input datasets and process out
 cime_config ------- Configuration files of cime for compsets and CTSM settings
 bin/git-fleximod -- Script to manage the needed sub-component source directories (handled with git submodule)
 py_env_create ----- Script to setup the python environment for CTSM python tools using conda
-python ------------ Python modules used in tools and testing and automated checking of ALL CTSM python scirpts
+python ------------ Python modules used in tools and testing and automated checking of ALL CTSM python scripts
 
 Directory structure only for a CTSM checkout:
 
@@ -66,6 +66,8 @@ components/cmeps -------------------- CESM top level driver (for NUOPC driver [w
 components/cdeps -------------------- CESM top level data model shared code (for NUOPC driver).
 components/cism --------------------- CESM Community land Ice Sheet Model.
 components/mosart ------------------- Model for Scale Adaptive River Transport
+components/mizuRoute ---------------- Reached based river transport model for water routing 
+                                      (allows both gridded river and Hydrologic Responce Unit river grids)
 components/rtm ---------------------- CESM River Transport Model.
 
 Top level documentation ($CTSMROOT):
@@ -74,6 +76,7 @@ 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_GITFLEXIMOD.rst --- Information on how to work with git-fleximod for CTSM
+WhatsNewInCTSM5.3.md ----- Overview document of the changes between ctsm5.2.0 and ctsm5.3.0
 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
@@ -104,17 +107,16 @@ 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 NUOPC scripts.
-doc/IMPORTANT_NOTES --------- Some important notes about this version of 
-                                                 CTSM, configuration modes and namelist items 
-                                                 that are not validated or functional.
+doc/IMPORTANT_NOTES.md ------ Some important notes about this version of 
+                              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/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 build-namelist scripts.
-bld/build-namelist ---------- Script to build CTSM namelists.
+bld/build-namelist ---------- Lower level script to build CTSM namelists.
 
 cime_config/buildnml ------------- Build the CTSM namelist for CIME
 cime_config/buildlib ------------- Build the CTSM library
@@ -153,9 +155,9 @@ src/dyn_subgrid --- Dynamic land unit change
 src/init_interp --- Online interpolation
 scr/fates --------- FATES model and sub-directories 
                     Functionally Assembled Terrestrial Ecosystem Simulator (FATES)
-                    Experimental Ecosystem Demography model
+                    Ecosystem Demography model
 src/utils --------- Utility codes
-src/self_tests ---- Internal testing (unit tests run as a part of a CTSM simulation)
+src/self_tests ---- Internal testing (unit tests run as a part of a CTSM system test)
 src/unit_test_shr - Unit test shared modules for unit testing
 src/unit_test_stubs Unit test stubs that replicate CTSM code simpler
 

README.md

@@ -6,7 +6,7 @@
 
 The Community Terrestrial Systems Model.
 
-This includes the Community Land Model (CLM5.0 and CLM4.5) of the Community Earth System Model.
+This includes the Community Land Model of the Community Earth System Model.
 
 For documentation, quick start, diagnostics, model output and
 references, see
@@ -43,7 +43,7 @@ CTSM code management is provided primarily by:
 Software engineering team:
 - [Erik Kluzek](https://github.com/ekluzek)
 - [Bill Sacks](https://github.com/billsacks)
-- [Sam Levis](https://github.com/slevisconsulting)
+- [Sam Levis](https://github.com/slevis-lmwg)
 - [Adrianna Foster](https://github.com/adrifoster)
 - [Sam Rabin](https://github.com/samsrabin)
 - [Greg Lemieux](https://github.com/glemieux)

README_GITFLEXIMOD.rst

@@ -67,10 +67,10 @@ Switching to a different CTSM branch or tag
 
 If you have already checked out a branch or tag and **HAVE NOT MADE ANY
 MODIFICATIONS** it is simple to change your sandbox. Say that you
-checked out ctsm1.0.0 but really wanted to have ctsm1.1.0;
+checked out ctsm5.2.0 but really wanted to have ctsm5.3.0;
 you would simply do the following::
 
-  git checkout ctsm1.1.0
+  git checkout ctsm5.3.0
   ./bin/git-fleximod update
 
 You should **not** use this method if you have made any source code

WhatsNewInCTSM5.3.md

@@ -0,0 +1,53 @@
+Purpose and description of changes since ctsm5.2.005
+----------------------------------------------------
+
+Bring in updates needed for the CESM3.0 science capability/functionality "chill". Most importantly bringing
+in: CN Matrix to speed up spinup for the BGC model, updated surface datasets, updated Leung 2023 dust emissions,
+explicit Air Conditioning for the Urban model, updates to crop calendars. For clm6_0 physics these options are now
+default turned on in addition to Sturm snow, and excess ice.
+
+Changes to CTSM Infrastructure:
+===============================
+
+ - manage_externals removed and replaced by git-fleximod
+ - Ability to handle CAM7 in LND_TUNING_MODE
+
+Changes to CTSM Answers:
+========================
+
+ Changes to defaults for clm6_0 physics:
+  - Urban explicit A/C turned on
+  - Snow thermal conductivity is now Sturm_1997
+  - New IC file for f09 1850
+  - New crop calendars
+  - Dust emissions is now Leung_2023
+  - Excess ice is turned on
+  - Updates to MEGAN for BVOC's
+  - Updates to BGC fire method
+
+ Changes for all physics versions:
+
+  - Parameter files updated
+  - FATES parameter file updated
+  - Glacier region 1 is now undefined
+  - Update in FATES transient Land use
+  - Pass active glacier (CISM) runoff directly to river model (MOSART)
+  - Add the option for using matrix for Carbon/Nitrogen BGC spinup
+
+New surface datasets:
+=====================
+
+- With new surface datasets the following GLC fields have region "1" set to UNSET:
+     glacier_region_behavior, glacier_region_melt_behavior, glacier_region_ice_runoff_behavior
+- Updates to allow creating transient landuse timeseries files going back to 1700.
+- Fix an important bug on soil fields that was there since ctsm5.2.0. This results in mksurfdata_esmf now giving identical answers with a change in number of processors, as it should.
+- Add in creation of ne0np4.POLARCAP.ne30x4 surface datasets.
+- Add version to the surface datasets.
+- Remove the --hires_pft option from mksurfdata_esmf as we don't have the datasets for it.
+- Remove VIC fields from surface datasets.
+
+New input datasets to mksurfdata_esmf:
+======================================
+
+- Updates in PFT/LAI/soil-color raw datasets (now from the TRENDY2024 timeseries that ends in 2023), as well as two fire datasets (AG fire, peatland), and the glacier behavior dataset.
+

bld/README

@@ -4,16 +4,16 @@ CLM build and configure directory and scripts. Scripts to help
 you prepare to build CLM as a component within CESM, and setup
 a namelist for it.
 
+This is a lower level script called from with CESM/CIME.
+
 Important files/directories:
 
---------- Configure and build scripts
---------- (These scripts are also used by the cesm/cime scripts)
+--------- Namelist build scripts
 
 config_files/clm_phys_vers.pm ------------- Perl module to handle different CLM versions
-config_files/config_definition_ctsm.xml --- XML file defining all CTSM configuration items
+config_files/config_definition_ctsm.xml --- XML file defining CTSM configuration items (mainly physics version)
 
 --------- Scripts to build the namelists
---------- (These scripts are also used by the cesm/cime scripts)
 build-namelist --- Build the namelists needed
 
 
@@ -26,17 +26,17 @@ unit_testers --- Directory of scripts to test scipts in this directory
 ---------- XML Files describing namelists in namelist_files
 namelist_files/namelist_defaults_ctsm.xml --------- List of default values for the ctsm namelist
 namelist_files/namelist_defaults_overall.xml ------ List of default values for overall settings
-namelist_files/namelist_defaults_usr_files.xml ---- List of default values for the user-files
-namelist_files/namelist_definition_ctsm.xml -------- Definition of all namelist items for ctsm
+namelist_files/namelist_defaults_usr_files.xml ---- List of default values for the user-files (deprecated)
+namelist_files/namelist_definition_ctsm.xml ------- Definition of all namelist items for ctsm
 namelist_files/namelist_definition.xsl ------------ Describes how to view the xml file as html
-namelist_files/namelist_defaults_drydep.xml ------- List of default values for the dry deposition module.
 namelist_files/use_cases -------------------------- Specific configurations that build-namelist uses
 namelist_files/use_cases/README ------------------- File explaining the naming convention for use_cases
 
 ---------- Driver namelist files, duplicated information from cime/driver/cime_config
 namelist_files/namelist_defaults_drv.xml ---------- List of default values for driver namelist defaults
-namelist_files/namelist_defaults_drydep.xml ------- List of default values for dry deposition fields 
+namelist_files/namelist_defaults_drydep.xml ------- List of default values for dry deposition and MEGAN fields 
 namelist_files/namelist_defaults_fire_emis.xml ---- List of default values for fire emission fields
+namelist_files/namelist_defaults_dust_emis.xml ---- List of default values for the dust emissions module.
 namelist_files/namelist_definition_drv.xml -------- Definition of all driver namelist items
 namelist_files/namelist_definition_drv_flds.xml --- Definition of add driver fieldsnamelist items