codereference.tex

CCSM Research Tools: Community Atmosphere Model (CAM)

\documentclass[]{article}
\usepackage{html}
\usepackage[T1]{fontenc}
\usepackage{longtable}

\textwidth 6.5in
\textheight 8.5in
\addtolength{\oddsidemargin}{-.75in}

\begin{document}
\bodytext{BGCOLOR=white LINK=#083194 VLINK=#21004A}

\begin{titlepage}

\begin{latexonly}
\noindent {\bf Community Climate System Model} \\
\noindent National Center for Atmospheric Research, Boulder, CO \\
\vspace{2in}
\end{latexonly}

\begin{center}
{\Large\bf CLM2.0 Code Reference} \\
{\bf Version 1.0}
\medskip
{\it Mariana Vertenstein, Sam Levis, Keith Oleson, and Peter Thornton}
\end{center}

\end{titlepage}

\tableofcontents

\newpage
\section{Code Structure}

\subsection {Calling Tree}

The following is a brief outline of the calling sequence for the main
CLM2.0 driver routine, driver.F90.  A comprehensive outline of the
calling sequence for the full CLM2.0 model is provided in the
accompanying html document,
\htmladdnormallink{CLM2.0 Comprehensive Calling Sequence}
{clm_offline_tree.html}.

\begin{itemize}
\item ->  histend 
\item ->  get\_curr\_date 
\item ->  interpMonthlyVeg 
  \begin{itemize}
  \item ->  readMonthlyVegetation 
  \end{itemize}
\item -> {\bf ***begin first loop over patch points**} 
\item ->  Hydrology1 
  \begin{itemize}
  \item ->  Fwet 
  \end{itemize}
\item ->  Biogeophysics1 
  \begin{itemize}
  \item ->  QSat 
  \item ->  SurfaceRadiation 
  \item ->  BareGroundFluxes 
    \begin{itemize}
    \item ->  MoninObukIni 
    \item ->  FrictionVelocity 
    \end{itemize}
  \item ->  CanopyFluxes 
     \begin{itemize}
     \item ->  Qsat 
     \item ->  MoninObukIni 
     \item ->  FrictionVelocity 
     \item ->  Stomata (call for sunlit leaves and shaded leaves) 
     \item ->  SensibleHCond 
     \item ->  LatentHCond 
     \item ->  Qsat 
     \end{itemize}
  \end{itemize}
\item ->  Biogeophysics\_Lake 
  \begin{itemize}
  \item ->  SurfaceRadiation 
  \item ->  Qsat 
  \item ->  MoninObukIni 
  \item ->  FrictionVelocity 
  \item ->  Qsat 
  \item ->  Tridiagonal 
  \end{itemize}
\item ->  Biogeochemistry? 
\item ->  EcosystemDyn 
\item ->  SurfaceAlbedo 
  \begin{itemize}
  \item ->  shr\_orb\_decl 
  \item ->  shr\_orb\_cosz 
  \item ->  SnowAlbedo (called for direct beam and diffuse beam) 
  \item ->  SoilAlbedo 
  \item ->  TwoStream (called for visible direct, visible diffuse, NIR direct and NIR diffuse) 
  \end{itemize}
\item ->  Biogeophysics2 
  \begin{itemize}
  \item ->  SoilTemperature 
    \begin{itemize}
    \item ->  SoilThermalProp 
    \item ->  Tridiagonal 
    \item ->  PhaseChange 
    \end{itemize}
  \end{itemize}
\item -> {\bf ***end first loop over patch points***} 
\item -> {\bf ***begin second loop over patch points***} 
\item ->  Hydrology2 
   \begin{itemize}
   \item ->  SnowWater 
   \item ->  SurfaceRunoff 
   \item ->  Infiltration 
   \item ->  SoilWater 
     \begin{itemize}
     \item -> Tridiagonal 
     \end{itemize}
   \item ->  Drainage 
   \item ->  SnowCompaction 
   \item ->  CombineSnowLayers 
     \begin{itemize}
     \item -> Combo 
     \end{itemize}
   \item ->  DivideSnowLayers 
     \begin{itemize}
     \item -> Combo 
     \end{itemize}
   \item -> WetIceHydrology 
   \end{itemize}
\item ->  Hydrology\_Lake 
\item ->  SnowAge 
\item ->  BalanceCheck 
\item -> {\bf ***end second loop over patch points***} 
\item ->  histUpdate 
\item ->  Rtmriverflux 
   \begin{itemize}
   \item ->  Rtm 
   \end{itemize}
\item ->  histhandler 
\item ->  restwrt 
\item ->  inicwrt 

\end{itemize}

\subsection {Code Flow - Main Interface}

The CLM2.0 model can be built to run in one of three modes. It can run
as a stand alone executable where atmospheric forcing data is
periodically read . This will be referred to as offline mode. It can
also be run as part of the Community Atmosphere Model (CAM) where
communication between the atmospheric and land models occurs via
subroutine calls. This will be referred to as cam mode. Finally, it
can be run as a component in a system of geophysical models (CCSM).
In this mode, the atmosphere, land (CLM2), ocean and sea-ice models
are run as separate executables that communicate with each other via
the CCSM flux coupler. This will be referred to as csm mode. \newline

\noindent {\bf offline mode:} The routine, {\bf program\_off.F90},
provides the program interface for running CLM2.0 in offline
mode. This routine first initializes the CLM2.0 model. Part of this
initialization consists of the the determination of orbital parameters
by a call to the routine {\bf shr\_orb\_params.F90}.  Subsequently,
the time stepping loop of the model is executed by obtaining
atmospheric forcing and calling the CLM2.0 driver. \newline

\noindent {\bf csm mode:} The routine, {\bf program\_csm.F90},
provides the program interface for running CLM2.0 in csm mode. In this
mode, orbital parameters are obtained from the flux coupler during
initialization whereas atmospheric data are obtained from the flux
coupler during the time stepping loop.
\newline

\noindent {\bf cam mode:} The module, {\bf atm\_lndMod.F90}, contains
the subroutine interfaces necessary to run CLM2.0 in cam mode. The
model is initialized by a call to subroutine {\bf atmlnd\_ini} whereas
subroutine {\bf atmlnd\_drv} is called at every time step by the
CAM atmospheric model to update the land state and return the 
necessary states and fluxes back to the atmosphere.
\newline

\subsection {Code Flow - Driver Loop}

\noindent 
The following presents a brief outline of the routines appearing in
the calling sequence for {\bf program\_off.F90}, the main CLM2.0 offline
program. Most of the following routines are invoked from the driver routine,
{\bf driver.F90}.

\medskip

\noindent {\bf shr\_orb\_params:} 
Calculate Earth's orbital parameters. \newline

\noindent {\bf Initialize:} 
Calls a series of subroutines (see \htmladdnormallink{CLM2.0
Comprehensive Calling Sequence} {clm_offline_tree.html}) which
initialize model parameters, read and/or create a surface dataset,
read the initial file (initial simulations only), read the restart
file (restart or branch simulations only). If no initial dataset is
specified in the namelist, the model uses an internal
initialization. If no surface dataset is specified in the namelist,
the model uses a list of raw datasets to create a surface dataset and
read it in. \newline

\noindent {\bf atmdrv:} 
Read in atmospheric fields and generate atmospheric forcing. \newline

\noindent {\bf driver:} 
Driver for CLM2.0 physics. \newline

\noindent {\bf histend:} 
Determine if current time step is the end of history interval. \newline

\noindent {\bf get\_curr\_date:} 
Determine calender information for next time step. \newline

\noindent {\bf interpMonthlyVeg:} 
Determine if two new months of vegetation data need to be read in. \newline

\noindent {\bf readMonthlyVegetation:} 
Read monthly vegetation data for two consecutive months. \newline

\noindent {\bf Hydrology1:} 
Calculation of (1) water storage of intercepted precipitation (2)
direct throughfall and canopy drainage of precipitation (3) the
fraction of foliage covered by water and the fraction of foliage that
is dry and transpiring and (4) snow layer initialization if the snow
accumulation exceeds 10 mm. \newline

\noindent {\bf Fwet:} 
Determine the fraction of foliage covered by water and the fraction of
foliage that is dry and transpiring. \newline

\noindent {\bf Biogeophysics1:} 
Main subroutine to determine leaf temperature and surface fluxes based
on ground temperature from previous time step. \newline

\noindent {\bf QSat:} 
Compute saturation mixing ratio and the change in saturation mixing
ratio with respect to temperature. \newline

\noindent {\bf SurfaceRadiation:} 
Compute Visible and NIR solar fluxes absorbed by vegetation and ground
surface. Split canopy absorption into sunlit and shaded
canopy. Calculate NDVI and reflected solar radiation. This routine is
also used for surface radiation for lake biogeophysics. \newline

\noindent {\bf BareGroundFluxes:}
Compute sensible and latent heat fluxes and their derivatives with
respect to ground temperature using ground temperatures from
previous time step for non-vegetated surfaces or snow-covered
vegetation. Calculate stability and aerodynamic resistances. \newline

\noindent {\bf MoninObukIni:}
Initialize Monin-Obukhov length. \newline

\noindent {\bf FrictionVelocity:}
Calculation of the friction velocity and the relation for potential
temperature and humidity profiles of surface boundary layer. \newline

\noindent {\bf CanopyFluxes:}
Calculates the leaf temperature, leaf fluxes, transpiration,
photosynthesis and updates the dew accumulation due to
evaporation. \newline

\noindent {\bf Stomata:}
Leaf stomatal resistance and leaf photosynthesis. Uses Ball-Berry
formulation for stomatal conductance, and Farquhar photosynthesis
model. \newline

\noindent {\bf SensibleHCond:}
Provides dimensional and non-dimensional sensible heat conductances
for canopy and soil flux calculations. \newline

\noindent {\bf LatentHCond:}
Provides dimensional and non-dimensional latent heat conductances for
canopy and soil flux calculations. \newline

\noindent {\bf Biogeophysics\_Lake:}
Calculates lake temperatures and surface fluxes. Lake temperatures
are determined from a one-dimensional thermal stratification model
based on eddy diffusion concepts to represent vertical mixing of
heat. \newline

\noindent {\bf EcosystemDyn:}
Determine vegetation phenology \newline

\noindent {\bf SurfaceAlbedo:}
Surface albedos, fluxes (per unit incoming direct and diffuse
radiation) reflected, transmitted, and absorbed by vegetation, and
sunlit fraction of the canopy. \newline

\noindent {\bf shr\_orb\_decl:}
Determine solar declination for next time step. \newline

\noindent {\bf shr\_orb\_cosz:}
Determine cosine of solar zenith angle for next time step. \newline

\noindent {\bf SnowAlbedo:}
Determine direct and diffuse visible and NIR snow albedos. \newline

\noindent {\bf SoilAlbedo:}
Determine soil/lake/glacier/wetland albedos. \newline

\noindent {\bf TwoStream:}
Use two-stream approximation to calculate visible and NIR fluxes
absorbed by vegetation, reflected by vegetation, and transmitted
through vegetation for unit incoming direct or diffuse flux given an
underlying surface with known albedo. \newline