clm/README                                          4/13/2007

Community Land Surface Model (CLM) version 3.5 -- source code, tools, 
offline-build and test scripts. This gives you everything you need
to run CLM in a offline mode with NCEP forcing data in place of a
modeled atmosphere. In order to run with stand-alone CAM or concurrent
CCSM -- you also need other component models which are NOT provided in
this release.

What is new in CLM3.5 (compared to CLM3.0)?

CLM3.5 is considerably different to CLM3.0, particularly with respect to its 
simulation of the hydrologic cycle. The modifications consist of new surface 
datasets based on Moderate Resolution Imaging Spectroradiometer (MODIS) 
products (Lawrence and Chase 2007), an improved canopy integration scheme 
(Thornton and Zimmermann 2007), scaling of canopy interception 
(Lawrence et al. 2007), a simple TOPMODEL-based model for surface and 
sub-surface runoff (Niu et al. 2005), a simple groundwater model for 
determining water table depth (Niu et al. 2007), and a new frozen soil scheme 
(Niu and Yang 2006). Theree are four additional modifications. Three of these, 
an improved description of soil water availability, a resistance term to 
reduce excessive soil evaporation, and the introduction of a factor to 
simulate nitrogen limitation on plant productivity, can be categorized as new 
or improved parameterizations from the perspective of CLM3. The other may be 
categorized as fixing an algorithmically defective existing parameterization 
(correction to snowage calculation so that snowage increases monotonically) 
(Dickinson et al. 2006).

Additionally, a number of small problems or bugs have been corrected including 
a revision of RTM-subcycling and corrections to a few land-locked grid cells, 
a more efficient soil evaporation calculation based on PFT demand, and a fix 
to aggregation of LAI from high-resolution source data to CLM surface data. 

General directory structure:

doc ---- Documentation
bld ---- configure script, Makefile and run scripts to run model
src ---- Source code
test --- Testing scripts
tools -- Offline tools to prepare input datasets

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

SVN_EXTERNAL_DIRECTORIES --- File in top directory used by Subversion repository to give externals used.
bld/configure ---- Script to create Makefile and needed files to build offline CLM
bld/run-ibm.csh -- Complete script to build and run offline CLM on an IBM-SP (bluevista.ucar.edu)
bld/run-pc.csh --- Complete script to build and run offline CLM on an Linux-PC (bangkok.cgd.ucar.edu)

test/system/test_driver.sh --- Script for general software testing of offline CLM

tools/mkgriddata --- Directory to build program to create grid dataset at any resolution.
tools/mksurfdata --- Directory to build program to create surface dataset at any resolution.
tools/interpinic --- Directory to build program to interpolate initial conditions to any resolution.
doc/KnownBugs ------ List of known bugs
doc/ChangeLog ------ Detailed list of changes for each model version
bld/README --------- Description of how to use the configure and build/run scripts

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

src/biogeochem ----- Biogeochemisty
src/main ----------- Main control and high level code
src/riverroute ----- Riverrouting model (RTM)
src/biogeophys ----- Biogeophysics (Hydrology)

-------------------------------------- General utility code shared between CCSM models
src/csm_share
src/csm_share/dshr
src/csm_share/eshr
src/csm_share/flds
src/csm_share/flds/dust
src/csm_share/flds/default
src/csm_share/flds/gensom
src/csm_share/unit_testers ------------- Unit tests for csm_share code
src/csm_share/unit_testers/nl
src/csm_share/shr
src/csm_share/cpl

src/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_2_2_2r from
---- (http:/www.esmf.ucar.edu/)
---- (use the -esmf_libdir option in configure to link with the full ESMF library)
src/utils/esmf_wrf_timemgr
src/utils/esmf_wrf_timemgr/unittests ---- Unit testers
-------------------------------------- CCSM code timing library
src/utils/timing
-------------------------------------- Model Coupling Toolkit code
---- (http://www-unix.mcs.anl.gov/mct/)
src/utils/mct
src/utils/mct/mct
src/utils/mct/mpi-serial
src/utils/mct/doc
src/utils/mct/doc/texsrc
src/utils/mct/mpeu