THE
COMMUNITY
NOAH
LAND-SURFACE MODEL (LSM)
N: National Centers for Environmental Prediction (NCEP)
O: Oregon State University (Dept of Atmospheric Sciences)
A: Air Force (both AFWA and AFRL - formerly AFGL, PL)
H: Hydrologic Research Lab - NWS (now Office of Hydrologic Dev -- OHD)
This document is filename
README_2.2.doc at
ftp://ftp.ncep.noaa.gov/pub/gcp/ldas/noahlsm/ver_2.2
Collaborators:
Mike Ek, Dag Lohmann, Fei Chen, George Gayno, Brian Moore, Hua-Lu Pan, John
Schaake, Victor Koren, Qingyun Duan, Ying Lin, Pablo Grunmann, Dan Tarpley,
Tilden Meyers, Curtis Marshall, Larry Mahrt, Jinwon Kim, Paul Rusher
08
Mar 99: Ver_1.1
27
Jul 99: Ver_2.0
23
Oct 00: Ver_2.1
25
Mar 01: Ver_2.2
1.0
Introduction
2.0
Model Heritage
3.0
Directory Contents and Quick-Start Guide to
Execution
4.0
Subroutine Summary and Calling Tree
5.0
Control File Contents and Function
6.0
Input Atmospheric Forcing File
7.0
LSM Initial Conditions
8.0
Specifying Model Parameters
9.0
Execution Output Files
10.0
Issues
to be Addressed in Future Releases
11.0
Technical References
12.0
Revisions History (pending)
1.0 INTRODUCTION
This
User’s Guide provides execution guidance for and physical description of the
public version of the community NOAH LSM.
This version of the NOAH LSM is a stand-alone, uncoupled, 1-D column
version used to execute single-site land-surface simulations. In this traditional 1-D uncoupled mode,
near-surface atmospheric forcing data is required as input forcing (see Sec
6.0). This LSM simulates soil moisture
(both liquid and frozen), soil temperature, skin temperature, snowpack depth,
snowpack water equivalent (and hence snowpack density), canopy water content,
and the energy flux and water flux terms of the surface energy balance and
surface water balance. See Sec 11 for
the lineage of key technical references.
The
public server directory in which this User’s Guide resides also contains the
complete, self-contained NOAH LSM source code file, input control file, input
atmospheric forcing file, and example execution-time LSM output files for a
full one-year 1998 simulation. This
simulation is valid at the Champaign, Illinois surface-flux site (40.01 N,
88.37 W) of NOAA/ARL investigator Tilden Meyers. See Sec 3 for a “Quick-Start” guide to executing the NOAH LSM
code in this directory to duplicate the cited 1998 simulation at this
site. To execute NOAH LSM simulations
at other sites for other initial times, study Secs 5 through 8.
This
Version 2.2 of the NOAH LSM is the most current public-release version at the
time of posting of this User’s Guide (see date cited at top). It is the version currently executing in the
NCEP realtime Land Data Assimilation System - LDAS (Mitchell et al.,
2000). Related ancestors of the NOAH
LSM are used in a) the NCEP-OH submissions to PILPS-2a, 2c, 2d, 2e, b) the
operational coupled NCEP mesoscale Eta model (Chen et al., 1997) and its
companion Eta Data Assimilation System (EDAS) (Rogers et al., 1996), and c) the
coupled NCEP global Medium-Range Forecast model (MRF) and its companion Global
Data Assimilation System (GDAS). The operational
coupled Eta/EDAS suite is the source of the multi-year Eta/EDAS GCIP archive at
NCAR, going back to April 01, 1995 (http://www.emc.ncep.noaa.gov
/mmb/gcp/access.perm.html).
(Reminder:
See Sec 3 for a “Quick-Start” guide to executing the NOAH LSM.)
2.0 MODEL HERITAGE
Beginning
in 1990, and accelerating after 1993 under sponsorship from the GEWEX/GCIP
Program Office of NOAA/OGP via collaboration with numerous GCIP Principal
Investigators (PIs), the Environmental Modeling Center (EMC) of the National Centers for
Environmental Prediction (NCEP) joined with the NWS Office of Hydrology (OH)
and the NESDIS Office of Research and Applications (ORA) to pursue and refine a
modern-era LSM suitable for use in NCEP operational weather and climate prediction
models. Early in this effort, NCEP
carried out an intercomparison of four LSMs, including 1) a simple bucket
model, 2) the OSU LSM (known as the
CAPS model in some PILPS studies), 3) the SSiB model, and 4) the Simple Water
Balance model (SWB) of OH. The results
of this intercomparison were reported in Chen et al. (1996, see references
therein for the four cited LSMs). As a
result of the good performance of the OSU LSM in this study and pre-existing
hands-on experience with this LSM by various EMC staff members, including
Hua-Lu Pan and Ken Mitchell, EMC chose the OSU LSM for further refinement and
implementation in NCEP regional and global coupled weather and climate models
(and their companion data assimilation systems). The results of the cited LSM intercomparison
and the initial EMC refinements to the OSU LSM were reported in Chen et al.
(1996).
At
the beginning of the EMC LSM effort in 1990, the OSU LSM already had a 10-year
history. Its initial development was
carried out by OSU in a series of three papers (Mahrt and Ek, 1984; Mahrt and
Pan, 1984; and Pan and Mahrt, 1987). As
the EMC LSM effort unfolded during the 1990's, a series of NCEP extensions to
the OSU LSM were a) added by EMC and its GCIP collaborators and b) tested and
validated in both uncoupled and coupled studies (see review of these in
Mitchell et al, 1999, 2000). At NCEP,
the LSM was first coupled to the operational NCEP mesoscale Eta model on 31 Jan
96, with significant Eta LSM refinements subsequently implemented on 18 Feb 97,
09 Feb 98, and 03 Jun 98. Recently in
1999, with a) the new addition and testing of frozen soil and patchy snow cover
physics in the uncoupled LSM used for the NCEP-OH submission to PILPS-2d
(Valdai, Russia), and b) the growing number of external user requests for
access to and use of the NCEP LSM (e.g. GCIP PIs), we decided the NCEP LSM had
advanced to a stage appropriate for formal public release (first in March 99).
Most
recently in 2000, given a) the advent of the "New Millenium", b) a
strong desire by EMC to better recognize its LSM collaborators, and c) a new
NCEP goal to more strongly pursue and offer "Community Models", EMC
decided to coin the new name "NOAH" for the LSM that had emerged at
NCEP during the 1990s. With our choice
of the "NOAH" acronym, already defined at the top of this User's
Guide, we in EMC strive to explicitly acknowledge both the multi-group heritage
and informal "community" useage of this LSM, going back to the early
1980’s. Since its beginning then at
Oregon State University, the evolution of the present NOAH LSM herein has
spanned significant ongoing development efforts by the following groups:
NCEP/EMC: NCEP Environmental Modeling Center
(EMC)
(Mitchell, Chen,
Ek, Lin, Marshall, Janjic, Manikin, Lohmann, Grunmann, Pan)
OSU:
Oregon
State University
(Mahrt, Pan, Ek,
Kim, Rusher)
HL: NWS Hydrology Lab - formerly
Office of Hydrology
(Schaake, Koren,
Duan)
AFWA:
Air Force Weather Agency -
formerly AFGWC
(Moore, Mitchell,
Gayno)
AFRL: Air Force Research Lab - formerly
AFGL and PL
(Mitchell, Hahn,
Chang, Yang)
In
addition to “in-house” NOAH LSM development and validation by the above
organizations, the following external PIs (primarily GCIP), have also performed
valuable validations of the NOAH LSM and its immediate NCEP 1990's
predecessors:
E.H.
Berbery and Rasmusson: U.
Maryland (ARM/CART)
C.
Marshall and Crawford U.
Oklahoma (OU Mesonet)
I.
Yucel and Shuttleworth: U. Arizona (ARM/CART, AZNET)
A.K.
Betts: Atmospheric
Res Inc (ISLSCP/FIFE)
C.D.
Peters-Lidard, Wood Princeton
U. (TOPLATS
extensions)
L.
Hinkelman and Ackerman: Penn State U. (ARM/CART)
T.H.
Chen, W. Qu, Henderson-Sellers, et al. RMIT (PILPS-2a)
E.
Wood, Lettenmaier, Liang, Lohmann: Princeton
U. (PILPS-2c)
A.
Schlosser, A.G. Slater, Robock, et al.
U. Maryland (PILPS-2d)
R.
Angevine NOAA/AL (Flatland Exp)
See
Sec 11 for technical references on the above external validations.
Lastly,
one crucial collaborator deserves special
mention, namely the NESDIS Office of Research and Applications (Tarpley,
Gutman, Ramsay), which has been the source of critical global surface
fields of a) vegetation greenness and its seasonality and b) realtime snow
cover, plus important GOES, satellite-based, hourly surface validation fields
of c) land surface skin temperature and
d) solar insolation, both on a 0.50-degree lat/lon CONUS grid.
3.0
DIRECTORY CONTENTS AND QUICK-START GUIDE TO EXECUTION
The
directory /pub/gcp/ldas/noahlsm/ver_2.2 on anonymous server ftp.ncep.noaa.gov
contains fifteen files as follows: 1)
this User’s Guide (file README_2.2.doc), 2) a complete self-contained NOAH-LSM
source code file, 3-4) the latter file split for the User's convenience into
two mutually exclusive files representing a) "driver" routines and b)
"physics" routines, 5) an input control file that defines model
configuration and provides initial conditions, 6) an input atmospheric forcing
file, 7) a doc file describing the source and valid period/location of this
forcing file, 8-10) an input "namelist" file triad that allows input
of non-default physical parameters, 11-15)
five execution-time output files, resulting from an entire one-year 1998
simulation valid near the Champaign, Illinois surface-flux site of Tilden
Meyers of NOAA/ARL. This site is
located at the lat/lon coordinates of
(40.01 N, 88.37 W). The15
filenames are:
Filename Contents
1
-- README_2.2.doc This User's Guide
2
-- NOAHLSM_SRC_VER_2.2.f
Self-contained NOAH LSM source
code
3
-- DRIVER_SRC_VER_2.2.f "DRIVER"
family of routines from file 2 above
4
-- SFLXALL_SRC_VER_2.2.f "PHYSICS"
family of routines from file 2 above
5
-- controlfile_ver_2.2 Input control file
6
-- obs98.dat.Z Input near-surface atmospheric
forcing file
7
-- CHAMP_IL.doc Observing site description
8
-- namelist_filename.txt 1-line 50-char name of namelist-read
input file
9
-- soil_veg_namelist_ver_2.2 namelist-read
input file
10- namelist_chg_example alternate
namelist-read input file
11- PRTSCREEN.TXT.Z Execution “print * “ screen output
12- DAILY.TXT.Z Execution Output File 1
13- HYDRO.TXT.Z Execution
Output File 2
14- THERMO.TXT.Z Execution
Output File 3
15- OBS_DATA.TXT.Z Execution Output Data File 4
All
files are text files, except files README_2.2 and CHAMP_IL, which are MS Word
files. Download all 15 files to your
workstation. Proceed with a NOAH LSM
execution test as described below.
Compile/load
file NOAHLSM_SRC_VER_2.2.f . This file
is the complete NOAH LSM source code.
It is Fortran 90 compatible and compiles free of warning and error
messages using “f90” on SGI Origin 2000 Workstations. The Unix command “f90 NOAHLSM_SRC_VER_2.2.f” will create the
executable “a.out”. Lets assume here
that we rename “a.out” to “lsm.x”.
To
prepare to execute lsm.x, first uncompress the “.Z” files with the Unix
uncompress command.
The
uncompress yields file “obs98.dat” and five upper-case “*.TXT” files. These TXT files are lsm.x execution-time output files. Move these “TXT* files to
a separate sister directory for later comparison to the equivalent output files
from your own local lsm.x execution.
The
four lower-case files given by filenames
controlfile_ver_2.2
obs98.dat
namelist_filename.txt
soil_veg_namelist_ver_2.2
are
the four input files required during the execution of lsm.x. The “controlfile” (see Sec 5) contains model
configuration variables such as number and thickness of soil layers, number and
length of time steps, initial date/time of the simulation, lat/lon location of
the simulation site, initial conditions for all state variables, and
site-specific land classifications (integer indexes for vegetation-type,
soil-type, and surface-slope category).
The
file obs98.dat (see Sec 6) contains one year’s worth (1998) of 30-min observed
atmospheric forcing data and independent observed verification data (e.g. surface
energy fluxes and soil temperature) valid at the Champaing, Illinois
surface-flux site operated and maintained by Tilden Meyers of NOAA/ARL. The site is located at the lat/lon
coordinates of (40.01 N, 88.37 W).
Now
invoking “lsm.x >PRTSCREEN.TXT” will launch and complete the 1998 one-year
LSM simulation for the aforementioned Illinois site, producing the same 5
“*.TXT” output files that you obtained originally from the NCEP server. Normal termination of the execution is
marked by the termination message “STOP: 0”.
Since all the “*.TXT” files are ascii files, one can and should confirm
that the 5 output files from the local simulation agree very closely with the
originally downloaded output files from NCEP.
The
output file PRTSCREEN.TXT contains the output from “Print *” write statements
in the
MAIN
program. In this Version 2.2, these are
the block of three “Print *” statements located within the time-step loop in the
PROGRAM MAIN source shortly
after the return from CALL SFLX . These
three Print * statements output the time step counter and the small surface
energy balance residual during each of the first 50 time steps and then every
50 time steps thereafter.
The
other four output files are the execution output data files of greater interest
and their contents are described in Sec 9.
One
important degree of freedom regarding these remaining four output files must be
cited here. The unit numbers for these
output files are 43, 45, 47, and 49, which are explicitly assigned in PROGRAM
MAIN (via variable names NOUT1, NOUT3, NOUT5, and NDAILY). The sign of these assigned unit numbers
controls whether the output is ascii or binary. The sign of all four unit numbers is determined by a signed
parameter (IBINOUT) read-in from the control file (see Sec 5). When the sign of IBINOUT is positive
(negative), the format of these four output files is binary (ascii). When the output format is ascii (binary)
then the extension *.TXT (*.GRS, meaning GrADS-readable) appears on the
generated filename. The ascii choice
(negative unit number sign) was invoked in the default control run you obtain
from the server.
4.0 SUBROUTINE SUMMARY AND CALLING TREE
Below,
we split up the subroutine calling tree into that portion associated with
PROGRAM MAIN in the "Driver family" of subroutines (file
DRIVER_SRC_VER_2.2.f) and that portion associated with the "Physics
family" of subroutines (file SFLXALL_SRC_VER_2.2.f), comprised of physics
"sub-driver" routine SFLX and all subordinate subroutines.
4.1 The Driver Routines
Briefly
the ten main steps of the MAIN program are:
1)
read
in control file ( model configuration, site characteristics, and initial conditions)
2)
open
output file unit numbers
3)
invoke
time-step loop (including optional spin-up loop if indicated by control file)
4)
read
atmospheric forcing data and change its sign and units as expected by SFLX
5)
interpolate
monthly-mean surface greenness and albedo to julian day of time step
6)
assign
downward solar and longwave radiation from input forcing
7)
calculate
actual and saturated specific humidity from input atmospheric forcing
8)
assign
wind speed from input forcing
9)
invoke
LSM physics (CALL SFLX) to update state variables / sfc fluxes over one time
step
10)
write simulation output data each time step to four output files
The
section in driver PROGRAM MAIN associated with each of the above ten steps is
clearly delineated with comment line "DRIVER STEP n".
NOTE:
The section of PROGRAM MAIN for Step 6 includes optional code (presently
commented out) for calculating the downward radiation from the input air
temperature and humidity if the input forcing file does not provide it.
NOTE: The section of PROGRAM MAIN for Step 8
includes optional code (presently commented out) for invoking a User-provided
routine to calculate the surface exchange coefficient for heat (Ch) in place
of the default scheme.
-
READCNTL:
read control file (including LSM initial conditions and site characteristics)
-
-----------
Begin optional Multi-year Spin-Up Loop: if invoked by control file
-------------
-
---------------------------------------
Begin: Time Step Loop -------------------------------------
-
READBND
: read atmospheric forcing data
(and observed validation variables)
-
MONTH-D: interpolate monthly albedo and veg
greenness to current julian day
-- JULDATE:
determine julian day for current time
-
QDATAP: calculate actual and saturated
specific humidity
-- E (function) calculate vapor pressure
-
DQSDT
(function): slope of sat specific humidity wrt air temp (needed in PENMAN)
-- DQS (function)
intermediate value for routine dqsdt
-
SFLX: call to family of physics routines (see Sec
4.2) **** key call ****
-
PRTDAILY: write daily total values to output file 1 (once a day only)
-
PRTHYDF: write LSM water related
variables to output file 2 (every
time step)
-
PRTHMF: write LSM energy related
variables to output file 3 (every time
step)
-
PRTBND: write out input atmospheric forcing to output file 4 (every time step)
-
-------------------------------
End: Time Step Loop
----------------------------------------------
-
------------------------End:
Optional Multi-year Spin-Up Loop---------------------------------
-
STOP
0
4.2 The SFLX Family of Subroutines
The SFLX family of subroutines contain the physics of the LSM and is rather self-contained. Each user should become familiar with the argument list of SFLX. This argument list is thoroughly documented at the top of subroutine SFLX. Once becoming familiar with the argument list, users could if they so choose create their own MAIN driver program with reasonably little effort. Calling SFLX each time step updates and returns all the LSM state variables and all the surface energy balance and surface water balance terms. In using SFLX in a coupled atmospheric model, the output arguments needed from SFLX are:
ETA - latent heat flux
H - sensible heat flux
T1 - skin temperature (from which to
calculate upward longwave radiation)
ALBEDO - (including snowpack effects) for
calculating upward solar radiation
REDPRM
-- set land-surface parameters
-- set soil-type dependent parameters
-- set veg-type dependent parameters
-- set other land-surface parameters
SFCDIF
-- calculate surface exchange
coefficient for heat/moisture
CSNOW
– (function): compute thermal conductivity of snow
SNO_NEW
– update snow depth and snow density to account for new snowfall
TDFCND
– compute soil thermal diffusivity
CANRES
– compute canopy resistance
NOPAC – this path invoked if ZERO
snowpack on ground and zero snowfall (frozen precip)
-- surface skin
temperature updated via surface energy balance
SMFLX – compute a) surface water
fluxes and b) layer soil moisture update
DEVAP-
compute direct evaporation from top soil layer
TRANSP
– compute transpiration from vegetation canopy
SRT
– compute time-rate-of-change of soil moisture
WDFCND – compute hydraulic conductivity and diffusivity
SSTEP
– forward time-step integration of soil moisture rate-of-change
ROSR12 – tri-diagonal matrix solver
SHFLX
– compute a) ground heat flux and b) layer soil temperature update
HRT
– compute time-rate-of-change of soil temperature
TDFCND – compute soil thermal diffusivity (dependent on
soil moist.)
TBND – determine
soil layer interface temperature
SNKSRC –(function) compute heat sink/source from soil ice
phase change
TDFCND –
compute soil thermal diffusivity
FRH2O –
(function) calculate subzero unfrozen soil water
HSTEP
– forward time step integration of soil temperature rate-of-change
ROSR12 – tri-diagonal matrix solver
-
surface
skin temperature updated via surface energy balance
-
new
patchy snow cover treatment in above
-
snowmelt
computed if thermal and available energy conditions warrant
CSNOW – see above
TRANSP
– see above
SRT
– see above
WDFCND – see above
SSTEP
– see above
ROSR12 – see above
TDFCND – see above
SNOWPACK – update snow depth and
snow density owing to snow compaction
SHFLX
– see above
HRT
– see above
TDFCND – see above
TBND – see above
SNKSRC – see above
TDFCND –
see above
FRH2O –
see above
HSTEP
– see above
NOTES on SFLX Calling Tree:
1 –
Both the NOPAC and SNOPAC branches treat freezing processes within soil
2 –
Calling sequences under NOPAC and
SNOPAC via SMFLX and SHFLX are very similar
3
–
Snowpack physics in SNOPAC are treated mainly “in-line”, before calls to
SMFLX/SHFL
4
–
SHFLX and subordinates do heat fluxes and soil temperature update
5
–
SMFLX and subordinates do water fluxes and soil moisture update
-- SMFLX operates independently of the soil
thermodynamics (SHFLX) and can stand
alone,
requiring only inputs of precipitation and potential evaporation
-- SHFLX cannot operate independently of soil
hydraulics, unless thermal conductivity
dependence on soil moisture dependence is removed (in routine TDFCND)
5.0
CONTROL FILE CONTENTS AND FUNCTION
The
filename of the control file is “controlfile_ver_2.2”. The user may want to have a printout of the
control file handy (about one page) when reviewing the comments below.
The
control file is read-in early in the MAIN program and provides inputs of the
following types of information: a)
valid location and start date/time of simulation, b) model configuration,
c)
name of input forcing file, d) integer indexes for land-sfc classes for the
site, e ) initial values of all the model state variables.
NOTE: The control file does not provide model physical parameters, except for the lower boundary condition on the soil temperature (which should be assigned the value of the annual mean sfc air temperature for the simulation location). Physical parameter