models/lnd/clm/doc/README                                         12/08/2011

Community Land Surface Model (CLM4) in CESM1.0.4  -- source code, tools, 
offline-build and test scripts. This gives you everything you need
to run CLM with CESM with datm8 to provide NCEP forcing data in 
place of a modeled atmosphere.

What is new in this version of CLM (compared to previous CESM and CCSM releases)?

See the ChangeLog file for a summary description of the most recent major
version changes leading up to CLM4.0.00, for CESM1.0.1, CESM1.0.2, CESM1.0.3 and
finally for CESM1.0.4 The User's Guide also has a section on this as well.

General directory structure:

models/lnd/clm/doc ---- Documentation of CLM.
models/lnd/clm/bld ---- Template, configure and build-namelist scripts for clm.
models/lnd/clm/src ---- CLM Source code.
models/lnd/clm/test --- CLM Testing scripts.
models/lnd/clm/tools -- CLM Offline tools to prepare input datasets.

scripts --------------- CPL7 scripts

models/drv/driver ----- CESM top level driver source code.
models/drv/shr -------- CESM top level driver shared code.
models/drv/shr_esmf --- CESM top level driver shared code for ESMF.
models/atm/datm ------- CESM Data model version 8 source code.
models/glc/cism ------- CESM Community land Ice Sheet Model.
models/ice/sice ------- CESM stub sea-ice model source code.
models/ocn/socn ------- CESM stub ocean model source code.
models/glc/sglc ------- CESM stub glacier model source code.
models/utils ---------- CESM utility codes 
                        (Model Coupling Toolkit (MCT)
                        (Earth System Model Framework)
                        (timing -- code timing utility)

Documentation of Namelist Items: (view the following in a web browser)

models/lnd/clm/bld/namelist_files/namelist_definition.xml --- Definition of all namelist items
models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml - Default values

=============================================================================================
Important files in main directories:
=============================================================================================

models/lnd/clm/doc/Quickstart.GUIDE -------- Quick guide to using cpl7 scripts.
models/lnd/clm/doc/Quickstart.userdatasets - Quick guide to using your own datasets.
models/lnd/clm/doc/IMPORTANT_NOTES --------- Some important notes about this version of 
                                             clm, configuration modes and namelist items 
                                             that are not validated or functional.
models/lnd/clm/doc/KnownBugs --------------- List of known bugs.
models/lnd/clm/doc/KnownLimitations -------- List of known limitations and workarounds.
models/lnd/clm/doc/ChangeLog --------------- Detailed list of changes for each model version.
models/lnd/clm/doc/ChangeSum --------------- Summary one-line list of changes for each 
                                             model version.
models/lnd/clm/doc/README ------------------ This file
models/lnd/clm/doc/UsersGuide -------------- CLM Users Guide
models/lnd/clm/doc/CodeReference ----------- CLM Code Reference Guide

models/lnd/clm/bld/configure --------------- Script to prepare CLM to be built.

models/lnd/clm/test/system/test_driver.sh -- Script for general software testing of 
                                             standalone CLM.

models/lnd/clm/tools/mkgriddata --- Directory to build program to create grid dataset
                                    at any resolution.
models/lnd/clm/tools/mksurfdata --- Directory to build program to create surface dataset 
                                    at any resolution.
models/lnd/clm/tools/interpinic --- Directory to build program to interpolate initial 
                                    conditions to any resolution.
models/lnd/clm/tools/mkdatadomain - Directory to build program to create datm7 or docn7 
                                    domain files from clm files.
models/lnd/clm/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.

models/lnd/clm/bld/README --------- Description of how to use the template, configure and
                                    build-namelist scripts.

=============================================================================================
Source code directory structure:
=============================================================================================

models/lnd/clm/src/biogeochem -- Biogeochemisty
models/lnd/clm/src/main -------- Main control and high level code
models/lnd/clm/src/cpl_mct ----- Land model high level MCT driver
models/lnd/clm/src/cpl_esmf ---- Land model high level ESMF driver
models/lnd/clm/src/cpl_share --- Land model high level driver code shared between MCT/ESMF
models/lnd/clm/src/riverroute -- Riverrouting model (RTM)
models/lnd/clm/src/biogeophys -- Biogeophysics (Hydrology)

-------------------------------------- General utility code shared between CESM models
models/csm_share
models/csm_share/unit_testers -------- Unit tests for csm_share code
models/csm_share/shr

models/utils ------------------------- Utility code directory

-------------------------------------- ESMF-WRF time-management library
---- This is an implementation of the ESMF_2_2_2r time-manager API created
---- by the Weather and Research Forecasting Model (WRF) modeling team.
---- (http://wrf-model.org/)
---- Alternatively you can link with the full version of ESMF from
---- (http:/www.earthsystemmodeling.edu/)
models/utils/esmf_wrf_timemgr
models/utils/esmf_wrf_timemgr/unittests ---- Unit testers
-------------------------------------- CESM code timing library
models/utils/timing
-------------------------------------- Model Coupling Toolkit code
-------------------------------------- (http://www-unix.mcs.anl.gov/mct/)
models/utils/mct
models/utils/mct/mct
models/utils/mct/mpi-serial
models/utils/mct/doc
models/utils/mct/doc/texsrc
models/utils/mct/mpeu

