$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)

