$CTSMROOT/README 06/08/2018 Community Land Surface Model (CLM) science version 5.0.0 series -- source code, tools, offline-build and test scripts. This gives you everything you need to run CLM with CESM with datm8 to provide CRU NCEP or GSWP3 forcing data in place of a modeled atmosphere. For lists of current bugs (issues) and current development see the CTSM GitHub page: https://github.com/ESCOMP/ctsm IMPORTANT NOTE ON CESM CHECKOUT VERSUS A CTSM CHECKOUT: If this is the top level directory from making a clone of CTSM the directory structure is a little bit different than if CTSM is from a clone of the entire CESM. If this is part of CESM this directory will be under components/clm alongside other CESM component models. For a CTSM checkout this will be the top level directory. Other documentation will refer to $CTSMROOT and it means the directory that this file is at. CIMEROOT is the directory where "cime" is for 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. General directory structure ($CTSMROOT): doc --------------- Documentation of CLM. bld --------------- Template, configure and build-namelist scripts for clm. src --------------- CLM Source code. test -------------- CLM Testing scripts for CLM offline tools. tools ------------- CLM Offline tools to prepare input datasets and process output. cime_config ------- Configuration files of cime for compsets and CLM settings manage_externals -- Script to manage the external source directories Directory structure only for a CTSM checkout: components -------- Other active sub-components needed for CLM to run (river routing and land-ice models) 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/cism --------------------- CESM Community land Ice Sheet Model. components/mosart ------------------- Model for Scale Adaptive River Transport components/rtm ---------------------- CESM River Transport Model. Top level documentation ($CTSMROOT): README ------------------- This file README.rst --------------- File that displays under the project in github README_EXTERNALS.rst ----- Information on how to work with subversion externals for clm 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 ChangeLog/ChangeSum files doc/ChangeLog ---------------- Documents different CLM versions doc/ChangeSum ---------------- Summary documentation of different CLM versions Documentation of Namelist Items: (view the following in a web browser) bld/namelist_files/namelist_definition.xml --- Definition of all namelist items bld/namelist_files/namelist_defaults_clm4_5.xml - Default values for CLM4.5/CLM5.0 ============================================================================================= Important files in main directories (under $CTSMROOT): ============================================================================================= Externals.cfg --------------- File for management of the main high level externals Externals_CLM.cfg ----------- File for management of the CLM specific externals (i.e. FATES) parse_cime.cs.status -------- Script to parse test status files cs.status.* created by create_test doc/Quickstart.GUIDE -------- Quick guide to using cpl7 scripts. doc/IMPORTANT_NOTES --------- Some important notes about this version of clm, 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 -------------- CLM Users Guide doc/CodeReference ----------- CLM Code Reference Guide bld/README ------------------ Description of how to use the configure and build-namelist scripts. bld/configure --------------- Script to prepare CLM to be built. bld/build-namelist ---------- Script to build CLM namelists. cime_config/buildnml ------------- Build the CLM namelist for CIME cime_config/buildlib ------------- Build the CLM library cime_config/config_compsets.xml -- Define CLM compsets cime_config/config_component.xml - Define CLM XML settings cime_config/config_tests.xml ----- Define CLM specific tests cime_config/config_pes.xml ------- Define Processor layouts for various CLM grids and compsets cime_config/testdefs ------------- Directory for specification of CLM 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 CLM's offline tools. tools/mksurfdata_map ---------- Directory to build program to create surface dataset at any resolution. tools/mkdatadomain ------------ Directory to build program to create datm7 or docn7 domain files from clm files. 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/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. ============================================================================================= 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/biogeophys ---- Biogeophysics (Hydrology) 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 src/utils --------- Utility codes src/unit_test_shr - Unit test shared modules for unit testing src/unit_test_stubs Unit test stubs that replicate CTSM code simpler src_clm40 --------- CLM4.0 source code directory ============================================================================================= QUICKSTART: using the CPL7 scripts ============================================================================================= cd $CIMEROOT/scripts ./create_newcase # get help on how to run create_newcase ./create_newcase --case testI --res f19_g17_gl4 --compset I2000Clm50BgcCrop # 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 cd testI ./case.setup # create the $CASE.run file ./case.build # build model and create namelists ./case.submit # submit script # (NOTE: ./xmlchange RESUBMIT=10 to set RESUBMIT to number # # of times to automatically resubmit -- 10 in this example)