THE NCEP/OH/OSU LAND-SURFACE MODEL (LSM) User's Guide Public Release Version 1.1 08 March 1999 (This document is filename README_1.1 in /pub/gcp/ldas/nceplsm/ver_1.1 on ftp.ncep.noaa.gov) Author: Ken Mitchell Point of Contact: Dag Lohmann, dlohmann@ncep.noaa.gov, phone-301-763-8000 x 7278) Acknowledgment to Pablo Grunman for key technical, testing, and configuration support. PROGRAM HISTORY LOG (see last section of this document for revision contents) 01 Mar 99 : Ver_1.0 08 Mar 99 : Ver_1.1 TABLE OF CONTENTS 1.0 Introduction 2.0 Model Heritage 3.0 Directory Contents and Quick 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 the land-surface and other parameters 9.0 Execution Output Files 10.0 Overview of Model Physics 11.0 Current known problems 12.0 Technical References and Validation Studies 13.0 Program Revision Log 1.0 INTRODUCTION This User's Guide provides execution guidance for and physical description of the public version of the NCEP/OH/OSU Land-Surface Model (LSM). This version of the NCEP/OH/OSU 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, traditional near-surface atmospheric forcing data is required as input forcing (see Sec 7.0). This LSM simulates soil moisture (both liquid and frozen), soil temperature, skin temperature, snowpack water equivalent, snowpack density, canopy water content, and the traditional energy flux and water flux terms of the surface energy balance and surface water balance. See Sec 4 and Sec 9 for details on the model physics and governing equations. The public server directory in which this User's Guide resides also contains the complete self-contained 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 valid at the NOAA/ARL Illinois surface flux site of GCIP PI Tilden Meyers located at lat/lon coordinates of (40.01 N, 88.37 W). See Sec 2 for a "Quick-Start" guide to executing the LSM code in this directory to duplicate this 1998 simulation at this site. To execute LSM simulations at other sites for other initial times, study Secs 4 thru 8. This public version represents a rather current version, very close for example to a) the version used in the NCEP-OH submission to the PILPS-2d tests for the Valdai, Russia site, and b) the version being used in NCEP's emerging, realtime, U.S.-domain, Land Data Assimilation System (LDAS). Somewhat less current versions run operationally in a) the coupled NCEP mesoscale Eta model (Chen et al, 1997) and the Eta model's companion 4-D Data Assimilation System (EDAS) (Rogers et al, 199x), as well as in b) the coupled NCEP global Medium-Range Forecast model (MRF) and its companion 4-D 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://nic.fb4.noaa.gov:8000/research/gcip.html). 2.0 MODEL HERITAGE Beginning in 1994, with sponsorship from the GEWEX/GCIP Program Office and collaboration with numerous GCIP 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 jointly pursue and refine a modern-era LSM suitable for use in NCEP operational weather and climate prediction models. Along the way, this evolving LSM has been exercised and validated numerous times in both uncoupled and coupled studies (see review of these in Mitchell et al, 1999). 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 16 Feb 97, 09 Feb 98, and 03 Jun 99. Recently, with a) the 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/OH LSM (e.g. GCIP PIs), we decided the NCEP/OH LSM had advanced to a stage appropriate for formal public release. This public release milestone represents one point in time within the long continuing multi-group heritage of this LSM, going back to the early 1980's. Since its beginning then at Oregon State University (Mahrt, Pan, Ek), the evolution of the present NCEP LSM herein has spanned significant ongoing development efforts by the following groups: NCEP/EMC: National Centers for Environmental Prediction (Mitchell, Chen, Lin, Manikin, Grunman, Marshall, Ek, Lohmann, Pan) OH: NWS Office of Hydrology (Schaake, Koren, Duan) NESDIS/ORA: NESDIS Office of Research and Applications (Tarpley, Gutman, Ramsay) OSU: Oregon State University (Mahrt, Ek) PL: Air Force Phillips Lab (Mitchell, Hahn, Chang) (formerly AFGL) AFWA: Air Force Weather Agency (Mitchell, Moore, Neil) (formerly AFGWC) In addition to "in-house" validations by the above LSM developers, the following external PIs (primarily GCIP), have also performed valuable NCEP LSM validations: Berbery and Rasmusson: U. Maryland (ARM/CART) Marshall: U. Oklahoma (OU Mesonet) Yucel and Shuttleworth: U. Arizona (ARM/CART, Arizona Net) Betts: Atmospheric Res Inc (ISLSCP/FIFE) Hinkelman and Ackerman: Penn State (ARM/CART) Chen and Hendersen Sellers: (PILPS-2a) Wood, Lettenmaier, Liang, Lohmann: Princeton.U, U.Wash. (PILPS-2c) Schlosser and Robock U.Maryland (PILPS-2d) Angevine: NOAA/AL (Flatland Exp.) See Sec 11 and Sec 12 for specific technical references by above developers and validators. 3.0 DIRECTORY CONTENTS AND QUICK-START EXECUTION GUIDE The directory /pub/gcp/ldas/nceplsm/ver_1.0 on anonymous server ftp.ncep.noaa.gov contains ten files: this User's Guide (file README_1.0), the complete self-contained LSM source code file, input control file, input atmospheric forcing file, documentation file describing the observation site yielding this forcing file, and the five execution-time LSM output files for a full one-year 1998 simulation valid at the NOAA/ARL Illinois surface flux site of GCIP PI Tilden Meyers, located at the lat/lon coordinates of (40.01 N, 88.37 W). These 11 files are: Filename Byte Count/Format Contents 1 -- LSM_SRC.f 215485 / ascii NCEP LSM source code 2 -- controlfile 2895 / ascii Input control file 3 -- obs98.dat.Z 1077065 / ascii Input atmospheric forcing file 4 -- PRT_SCREEN.TXT.Z 7813 / ascii Execution "print * " output 5 -- DAILY.TXT.Z 9589 / ascii Execution Output Data File 1 6 -- HYDRO.TXT.Z 520848 / ascii Execution Output Data File 2 7 -- THERMO.TXT.Z 964365 / ascii Execution Output Data File 3 8 -- OBS_DATA.TXT.Z 1402485 / ascii Execution Output Data File 4 9 -- CHAMP_IL.doc MS Word Observing site description 10 -- README_1.1.doc MS Word User's Guide document 11 -- README_1.1.txt ascii User's Guide document All files are ascii, except files README_y.x and CHAMP_IL, which are MS Word files. Download all ten files to your workstation. After reviewing this README_y.x file, you can accomplish a test LSM execution as described below. LSM_SRC.f -- This file is the complete LSM source code. It is Fortran 77 compatible and compiles free of warning and error messages using "f77" on SGI, SUN, and HP workstations. The unix command "f77 LSM_SRC.f" will create the executable "a.out". Lets assume here that we rename "a.out" to "lsm.x". After creating lsm.x, it will prove useful to copy LSM_SRC.f to a sister directory and therein invoke "fsplit LSM_SRC.f" to create an individual "*.f" file for each subroutine in LSM_SRC.f. For this Version 1.0, this will yield an even 40 subroutines. Of these, one is the MAIN driver and 14 are called by the main driver -- the most important of which is the "physics" sub-driver routine SFLX., which is called every time step. The remaining 25 routines are the "core" LSM model physics routines all subordinate to SFLX. 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 two lower-case files "controlfile" and "obs98.dat" are the two 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-surface characteristics and some model parameters. The file obs98.dat (see Sec 7) contains one year's worth (1998) of 30-min observed atmospheric forcing data and independent observed validation data (e.g. surface energy fluxes and soil temperature) valid at the NOAA/ARL Illinois surface flux site of GCIP PI Tilden Meyers located at lat/lon coordinates of (40.01 N, 88.37 W). Now invoking "lsm.x >PRT_SCREEN.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 PRT_SCREEN.TXT contains the output from "Print *" write statements in the MAIN program. In this Version 1.0, these are the block of four "Print *" located in the PROGRAM MAIN source code shortly after the return from CALL SFLX . These four Print * statements output the time step counter and the small surface energy balance residual during each of the first 25 time steps and then every 50 time steps thereafter. The other four output files are the execution output data files of 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 together in PROGRAM MAIN (search for NOUT1, NOUT3, NOUT5, and NDAILY). The sign of these unit numbers invokes logic to provide either ascii output files (negative unit numbers) or binary output files (positive unit numbers). 4.0 SUBROUTINE SUMMARY AND CALLING TREE Below, we split up the subroutine calling tree into that of the MAIN program and that of the SFLX family of LSM physics routines. 4.1 The MAIN Program Briefly the chief functions of the MAIN program are: 1) read in LSM control file ( model configuration, site characteristics, and initial conditions) 2) open output file unit numbers 3) invoke time-step loop, 4) read atmospheric forcing data , 5) interpolate monthly-mean surface characteristics to julian day of time step 6) assign downward solar and longwave radiation 7) calculate actual and saturated specific humidity of atmospheric forcing 8) call LSM physics to update state variables and sfc fluxes over one time step, 9) write simulation output data each time step to four output files PROGRAM MAIN Calling Tree - READCNTL: read control file (including LSM initial conditions and site characteristics) - ------------------------------- Begin: Time Step Loop ------------------------ -- - READBND : read atmospheric forcing data (and observed validation variables) - MONTH-D: interpolate monthly albedo, veg greenness, LAI 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 LSM family of 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 ----------------------- --- - 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 SUBROUTINE SFLX Calling Tree REDPRM - set land-surface parameters PRMSOI - set soil-type dependent land-surface parameters PRMVEG - set veg-type dependent 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 PENMAN - compute potential evaporation 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 TDFCND - compute soil thermal diffusivity 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 TBND - (function) 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 SNOPAC - this path invoked if NONZERO snowpack on ground or NONZERO snowfall - 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 SMFLX - see above DEVAP - 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 ROSR12 - 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 5.0 CONTROL FILE CONTENTS AND FUNCTION The filename of the control file is "controlfile". 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) land-surface characteristics for the site, d ) some model physical parameters, and e) initial values of all the model state variables. NOTE: The control file only provides a few of the model parameters. The vast majority of such parameters are set in subroutine REDPRM, and in the subroutines PRMVEG and PRMSOI, which are called by REDPRM and use the veg-type index and soil-type index read from the control file. Control file parameters are distinct from REDPRM/PRMVEG/PRMSOI parameters in that in coupled atmospheric model runs (e.g. the NCEP Eta model), the former are provided to the coupled model as 2-d horizontal surface fields across the coupled model spatial domain (e.g. all of N. America in the Eta model, or the entire globe in the NCEP MRF global model). The control file consists of 30 data lines, that contain the following: Line 01: LAT - simulation site latitude (positive N from equator, hundredths of a degree) Line 02: LON - simulation site longitude (positive W from Greenwich, hundredths of a degree) Note: The above serve only to document the valid site of the input forcing data. The physics do not use the above, since forcing data provides downward solar radiation. Above would be needed by a MAIN driver that had to calculate downward solar radiation Line 03: JDAY - Integer Julian Day (1-365) of start of forcing data (start of simulation) Line 04: TIME - Initial time (local) of start of forcing data (see control file for note on format) Note: The above serve only to document the valid start date/time of the input forcing data. The physics do not use the above, since forcing data provides downward solar radiation. Above would be needed by a MAIN driver that had to calculate downward solar radiation Line 05: NRUN - integer number of physical integration time steps Line 06: DT - floating point length of time step (secs) used in physical integration Note: DT should NOT be larger than one hour (3600 secs) Note: There must be one forcing data record in forcing file for each time step Line 07: NSOIL - integer number of soil layers (must be 4 !! ) Line 08: NROOT - integer number of root layers (at least 2 and no greater than NSOIL) !Note: NSOIL must be 4 (arbitrary # of soil layers of 4 or more is imminent in a future release) Line 09: Z - height in meters above ground of atmospheric forcing data Note: In observed forcing data, the height of the temperature/humidity observation (e.g. 2 m) is often different from the height of the wind observation (e.g. 10 m ). When that is the case, we recommend using the height of the wind observation for Z. Line 10: thickness values of the four soil layers in meters (chosen by user) Note: Layer 1 thickness generally set between 05-10 cm. Layer 2 thickness generally set between 20-30 cm Layer 3 thickness generally set between 60-75cm Layer 4 thickness generally set around 100 cm (We generally have layers 1-3 span 1-meter, and layer 4 span 1-meter) Note: The physical equations in the LSM predict the soil moisture/temperature state variables at the midpoint of each model soil layer. The layer thicknesses used herein in the file "controlfile" were 10, 20, 60, and 110 cm. Thus the LSM predicted soil moisture/temperature values are nominally valid at soil depths of 5, 20, 60, and 145 cm. The upper three of these predicted levels match the three observed soil moisture levels in file "obs98.dat" (see Sec 6). Line 11: FILENAME - ASCII 8-character filename of observed atmospheric forcing file NOTE !! : User should contact NCEP Point of Contact given at top of Page 1 for recommended values for Lines 12-18 Line 12: SOILTP - soil type index (range 1-9), see index definitions at top of routine PRMSOI Line 13: VEGTYP veg type index (range 1-13), see index definitions at top of routine PRMVEG Line 14: SLOPTYP sfc slope index (range 1-9), see index definitions at top of routine REDPRM Note: Lines 12-14 are integers Line 15: ALBEDO - 12 monthly values of surface albedo fraction (snow-free) for simulation site Note: LSM physics will internally add snow cover effects to ALBEDO Line 16: SHDFAC - 12 monthly values of green vegetation fraction for simulation site Line 17: LAI - 12 monthly values of floating point leaf-area index NOTE !! NCEP now sets SHDFAC and LAI using the database and publication of Gutman, G. and A. Ignatov, 1998: The derivation of the green vegetation fraction from NOAA/AVHRR for use in numerical weather prediction models. International Journal of Remote Sensing, 19, 1533-1543. The latter work provides a 5-year, monthly mean, global database of green vegetation fraction at 0.144 degree resolution, obtained from NDVI. The authors forcefully argue that the two AVHRR channels that are used to derive NDVI do NOT provide sufficient degrees of freedom to derive BOTH vegetation greenness and LAI independently. They instead argue for embracing all the seasonality of vegetation in the greenness fraction and holding the LAI at a fixed constant annual value in the range of 1-5 (thus LAI becomes a tuning parameter). NCEP has obtained reasonable behavior with LAI=2. Line 18: SNOALB - maximum albedo expected over deep snow NOTE !! NCEP takes the above from the 1-degree, N. Hemisphere, digital database of Robinson, D.A., and G. Kukla, 1985: Maximum surface albedo of seasonally snow- Covered Lands in the Northern Hemisphere. J. Climate Appl. Meteor., 23, 1626-1634. (See Fig. 4 therein for depiction from digital database) Line 19: ICE - Flag to invoke sea-ice physics (always set to 0 for land-mass simulations) NOTE: The integer flag "ICE" forces branch to sea-ice physics in LSM. Be aware that this ICE flag has no bearing on soil ice physics in NCEP LSM. Line 20: TBOT - set to the climatological annual mean air temperature (K) for the modeled site . NOTE: TBOT serves as the annually fixed soil temperature bottom boundary condition at a soil depth of ZBOT, where ZBOT (currently 3-m) is set in routine REDPRM. ZBOT is the assumed nominal soil depth where the amplitude of the soil temperature annual cycle is practically zero. Line 21: Z0 - momentum roughness length (m) for modeled site Line 22: CZIL - Zilintikevich parameter NOTE: CZIL is a tuneable parameter, that controls the ratio of the roughness length for heat to the roughness length for momentum. Known as the Zilintikevich coefficient. Recommended range is .05-.50. This parameter effectively allows tuning of the aerodynamic resistance of the atmospheric surface layer. Increasing CZIL increases aerodynamic resistance. NCEP now recommends CZIL = 0.2 See next publication (Secs 2.1, 2.2, 3.2, Eqn 1, and Appendix A): Chen, F, Z. Janjic, and K. Mitchell, 1997: Impact of the atmospheric surface- layer parameterizations in the new land-surface scheme of the NCEP mesoscale Eta model. Boundary-Layer Meteor., 85, 391-421 . Line 23: REFKDT - surface runoff parameter (nominal range of 0.5 - 5.0) NOTE: REFKDT is a tuneable parameter that significantly impacts surface infiltration and hence the partitioning of total runoff into surface and subsurface runoff. Increasing REFKDT decreases surface runoff. See next publication: Schaake, J., V. Koren, Q.-Y. Duan, K. Mitchell, and F. Chen, 1996: Simple water balance model for estimating runoff at different spatial and temporal scales. J. Geophysical Res., 101, No. D3. Line 24: T1 - initial skin temperature (K). Can be set to initial air temperature. Model physics rapidly spins this up in first few 2-3 time steps. Line 25: STC (1-NSOIL): initial soil temperature (K), in each soil layer Line 26: SMC (1-NSOIL): initial volumetric total soil moisture (liquid and frozen) in each layer Line 27: SH2O (1-NSOIL): initial volumetric liquid soil moisture (unfrozen) in each layer NOTE: During conditions of no soil freezing, SH2O=SMC in each layer. Line 28: CMC - initial canopy water content (m). Set to zero as physics rapidly spins this up. Line 29: SNOWH - initial snow depth (m) Line 30: SNEQV - initial water equivalent (m) of above snowdepth. If not observed, dividing SNOWH by 5 gives a nominal initial value. FINAL NOTE: At other simulation sites that external users might choose as NCEP LSM test sites, we urge these users to contact NCEP for guidance on choices of the following controlfile parameter values (see Point of Contact at top): SOILTP, VEGTYP, SLOPTYP, ALBEDO, SHDFAC (greenness fraction), LAI, SNOALB, TBOT, Z0, CZIL, and REFKDT. 6.0 ATMOSPHERIC FORCING FILE As is typical with many off-line, uncoupled LSMs, the NCEP LSM requires the following near-surface atmospheric forcing data, preferably at 30-minute time intervals (or interpolated to 30-minute time intervals from say 1-6 hour interval observations -- Aside note: for observation intervals longer than 1-hour, the incoming surface solar insolation needs to be interpolated with a solar zenith angle weighting, in order to capture the full amplitude of the diurnal solar insolation) Air temperature at height Z above ground Air humidity at height Z above ground Surface pressure at height Z above ground Wind speed at height Z above ground Surface downward longwave radiation Surface downward solar radiation Precipitation For the example one-year LSM simulation provided with this User's Guide, we were extremely fortunate to benefit from the collaboration of GCIP-sponsored PI Tilden Meyers of NOAA/ARL, who operates a flux site located just south of Champaign, IL (40.01 N lat, 88.37 W long). The site characteristics and observing instrumentation are described in the MS Word document CHAMP_IL, provided by courtesy of Tilden Meyers, and available in same directory as this User's Guide. The 1998 forcing file from the above flux site is available as filename "obs98.dat" in the same directory as this User's Guide. This file contains one record for each 30-minute observation time and the file spans the entire calendar year of 1998 (hence 2 X 24 X 365 = 17520 records). Each 30-min record provides the following 33 observed variables (including the 7 required LSM forcing variables, marked by "**"), listed in the order they appear in each record of the file: jday Julian Day time LST, half hour ending w_speed propeller anemometer (10 meters, Bondville ISIS) w_dir wind direction (10 meters, Bondville ISIS) ** Ta air temperature (C), at 3 m ** RH relative humidity at 3 m (list continued) ** Pres surface pressure in mb ** Rg incoming solar radiation (W/m2) Par_in incoming visible radiation (0.4-0.7 um) in uE/m2/s Par_out outgoing or reflected visible light Rnet net radiation (W/m2) GHF soil or ground heat flux (W/m2) ** rain total rain for half hour (inches) wet wetness sensor (in voltage with higher values indicating wetness) IRT surface or skin temp (C) 2_cm soil temp at 2 cm (C) 4_cm soil temp at 4 cm 8_cm soil temp at 8 cm 16_cm soil temp at 16 cm 32_cm soil temp at 32 cm 64_cm soil temp at 64 cm ** u_bar average wind vector speed at 6-meters (m/s) u'w' kinematic shear stress (m2/s2) u'2 streamwise velocity variance (m2/s2) v'2 crosswind velocity variance (m2/s2) w'2 vertical velocity variance(m2/s2) H sensible heat flux (W/m2) LE latent energy flux (W/m2) CO2 CO2 flux (mg CO2/m2/s) ** LW_in downwelling longwave from sky (W/m2) sm_5 soil volumetric water content at 5 cm zone (after November 19 1997) sm_20 soil volumetric water content at 20 cm zone (after November 19 1997) sm_60 soil volumetric water content at 60 cm zone (after November 19 1997) In the LSM, program MAIN reads in all 33 of the above variables at each time step via the call to subroutine READBND, which also fills in occasional missing observations. Missing obs are very sparse and virtually always involve missing values of the wind speed (u_bar at 6 m), for which the READBND software substitutes (w_speed at 10 m). Finally, the last section of routine READBND performs unit conversions on "rain", "Ta", and "Pres" to convert them to the units expected in the call to SFLX . In addition to the LSM-required atmospheric forcing variables in the above list, the other variables in the list represent either a) independent validation data or b) useful initial conditions for the LSM state variables. LSM initial conditions are discussed in the next section. At each time step in the MAIN program, after the return from the physics update in CALL SFLX, useful LSM validation data from the above observation file is written out to validation output file OBS_DATA.TXT via call to routine PRTBND (e.g. LE, H, GHF, RNET, IRT, and the layer by layer soil moisture and temperature). 7.0 LSM INITIAL CONDITIONS The LSM requires input values (read-in from control file in routine READCNTL, see Sec 5 for details on units) of the following state variable initial conditions : 1 - SMC: total volumetric soil moisture (liquid and frozen) in each soil layer 2 - SH2O: liquid volumetric soil moisture in each soil layer 3 - STC: temperature in each soil layer 4 - T1: skin temperature 5 - CMC: canopy water content 6- SNOWH: snow depth 7 - SNEQV: water-equivalent snow depth Typically, a number of these state variables are not observed at a given validating observation site. The following initial variables were not available in the site observation file (obs98.dat): SNEQV, SNOWH, CMC, SMC, (and SH2O below 60 cm) Since January 1998 was mild (El'Nino) at the given site, we assumed a) zero snow cover (SNOWH=0.0, SNEQV=0.0) and b) zero soil ice (SMC=SH2O), plus we set CMC=0. As sited earlier in Sec 5, the four soil layer thicknesses specified in the control file were chosen so that the top three predicted layer midpoint levels of 5, 20, and 60 cm matched the observed soil moisture. But that still leaves open the question of initializing layer 4 soil moisture, which we assumed to be equal to that of layer 3. While we in general found the physical behavior of the observed data in file obs98.dat to be very good, inspection of the observed soil moisture at the 20 and 60 cm levels showed them to be virtually time invariant over the entire year, despite substantial wetting and drying periods. Hence their accuracy is rather suspect. Thus, the initial soil moisture values used for the simulation herein have considerable uncertainty. Given this, we intuitively feel that the first 3.5 months of the simulation should be viewed as spin-up, until mid-April of 1998, following heavy rains in early April. It is typical for LSM simulations at a particular observation site to be hampered by non-observed (e.g. snowdepth, frozen soil moisture, deep soil moisture ) or ill-observed initial state variables (.e.g. soil moisture). Facing this dilemma, the Project for Intercomparison of Land-Surface Process Schemes (PILPS) has come to urge modelers to use a one-year spin-up protocol, whereby the simulation for a desired period (1998 here) is preceded by a spin-up year (say 1997 in this case) where the spin-up year forcing is repeated several years to allow the LSM to essentially achieve equilibrium. Tilden Meyers has provided us with the 1997 forcing data for his site, and we plan to pursue the PILPS-recommended spin-up protocol in a near-future re-execution of our 1998 control run. Therein, we plan to use 5 soil layers and match our predicted soil depth levels with Tilden Meyer's observed soil temperature levels. 8.0 SPECIFYING THE LAND-SURFACE PARAMETERS Several of the model land-surface parameters are read from the control file, but the vast majority are specified in subroutine REDPRM. As discussed in Sec 5, the free parameters from the control file are XLAI, CZIL, and REFKDT. In a broader sense, one may also consider NROOT and the number and thickness of the soil layers (especially thickness of top soil layer) to be free parameters. Finally, we remind users that NCEP does not consider the control file parameter SHDFAC (i.e. vegetation greenness fraction) to be a free parameter, but rather a parameter specified from a given satellite-derived database. External users should contact NCEP to get our operational SHDFAC values for their test site of interest. The vast majority of the LSM land-surface parameters are set in subroutine REDPRM. However, the assignment of some land-surface parameters have not yet been "collected" into the REDPRM setting and remain buried deep in the LSM code. We feel these exceptions are primarily parameters of secondary importance. A few exceptions may be some parameters used in a) snowpack physics and b) soil thermal diffusivity and heat capacity. We are working to identify these and bring them into the REDPRM setting in a future model release. Also for our next release, we are working to add a namelist-directed I/O option in REDPRM, to allow easy testing/calibrating of alternative parameter values without the need to recompile code. As an overview, there are five groups of land-surface parameters: a) controlfile universal values b) REDPRM universal values c) REDPRM values dependent on the surface slope index (1-7) d) REDPRM values dependent on the veg class index (1-13) via CALL PRMVEG e) REDPRM values dependent on the soil class index (1- 9) via CALL PRMSOI A) Universal values in controlfile (4) (already described in Sec 5 above) XLAI (range 1.0 - 5.0) CZIL (range .05 - .50) REFKDT NROOT (1 to NSOIL) B) Universal parameters (7) in REDPRM ZBOT =3.0 m: nominal depth of TBOT: lower boundary condition on soil temp (range 3-20m) SALP=2.6:shape parameter used in function to infer percent area snow cover from snowdepth CFACTOR =0.5 exponent used in function for canopy water evaporation CMCMAX =0.0005 (m) maximum canopy water capacity used in canopy water evaporation REFDK=2.0E-6 a parameter used with REFKDT above to compute sfc runoff parameter KDT FRZK=0.15 a reference parameter for frozen soil freeze factor RSMAX=5000 (s/m) maximum stomatal resistance used in canopy resistance routine CANRES TOPT= 298(K) optimum air temperature for transpiration in canopy resistance routine CANRES Note: RSMAX and TOPT are not yet functions of vegetation class C) Surface-slope dependent parameter (1) in REDPRM Routine REDPRM embodies 7 categories of surface slope. These categories are described in a comment block near the top of routine REDPRM. The parameter dependent on slope class is: SLOPE - a coefficient between 0.1-1.0 that modifies the drainage out the bottom of the bottom soil layer. A larger surface slope implies larger drainage D) Vegetation-class dependent parameters (4) in REDPRM, via CALL PRMVEG Routine PRMVEG applies the 13 "SiB" vegetation classes. These classes are described in the comment block at the top of routine PRMVEG. The four parameters dependent on veg class are: RCMIN (s/m) : minimal stomatal resistance used in canopy resistance of routine CANRES RGL: radiation stress parameter used in F1 term in canopy resistance of routine CANRES HS: coefficient used in vapor pressure deficit term F2 in canopy resistance of routine CANRES SNUP: the water-equivalent snowdepth upper threshold at which 1) 100 percent snow cover is achieved for given veg class 2) maximum snow albedo is achieved for given veg class RTDIS: array specifying vertical root distribution, i.e. the fraction of total root mass present in each soil layer NOTE: Presently, RTDIS is set universally (not dependent on veg class) and assumes a uniform root distribution throughout the universal number of root layers (NROOT) E) Soil-class dependent parameters (11) in REDPRM, via CALL PRMSOI Routine PRMSOI applies 9 soil texture classes. These classes are described in the comment block at the top of routine PRMSOI. The nine parameters dependent on soil class are: SMCMAX: maximum volumetric soil moisture (porosity) SMCREF: soil moisture threshold for onset of some transpiration stress SMCWLT: soil moisture wilting point at which transpiration ceases SMCDRY: top layer soil moisture threshold at which direct evaporation from soil ceases DKSAT: saturated soil hydraulic conductivity PSISAT: saturated soil matric potential B: the "b" parameter in hydraulic functions DWSAT: saturated soil water diffusivity QUARTZ: quartz content, used to compute soil thermal diffusivity KDT: surface runoff parameter (dependent on DKSAT, REFDK, and REFKDT) FRZX: soil ice content threshold (m) above which frozen soil is impermeable 9.0 EXECUTION OUTPUT FILES There are five execution-time output files: PRT_SCREEN.TXT: holds results from "Print * " output via execution command line syntax of "lsm.x >PRT_SCREEN.TXT" (i.e. capture of "screen" print). Presently this output file contains the surface energy balance residual and time step value at every 50 time steps. a) DAILY.TXT: contains daily-defined output values once-per-day, from routine PRTDAILY, such as daily total evaporation and precipitation. b) HYDRO.TXT: contains water related outputs at every time step, from routine PRTHYDF , such as actual and potential evaporation, soil moisture, snowdepth, snowmelt, runoff. c) THERMO.TXT: contains energy related outputs at every time step, from routine PRTHMF, such as skin temperature, soil temperature, and all surface energy fluxes e) OBS_DATA.TXT: output of observed input forcing/validation data, from routine PRTBND, such as incoming radiation, skin temperature, soil temperature, precip, net radiation, latent, sensible, and ground heat fluxes (i.e. this file echoes the input observation file "obs98.dat", but with some units conversion for compatibility with other model outputs) 10.0 OVERVIEW OF MODEL PHYSICS (Further details pending) See Sections 3.1.1 and 3.1.2 of Chen, F., K. Mitchell, et al, 1996: Modeling of land surface evaporation by four schemes and comparison with FIFE observations. J. Geophys. Res., 101, No. D3, 7251-7268 For snowpack and frozen ground physics, see all of Koren, V., J. Schaake, et al., 1999: A parameterization of snowpack and frozen ground intended for NCEP weather and climate models. J. Geophys. Res. Accepted (request from NCEP point of contact given at top) 11.0 KNOWN PROBLEMS Overly large subsurface heat flux under shallow or trace snow pack. In this event, subsurface heat flux is arbitrarily capped, but surface energy balance is violated. Solution imminent. 12.0 TECHNICAL REFERENCES (Explicit references pending -- see below for rough outline) OSU heritage prior to 1991 (Full details pending) Mahrt and Ek, 1984, J. Clim. Appl. Meteorol, 23, 222-234. Marht and Pan, 1984, Boundary Layer Meteorol, 29, 1-20. Pan and Mahrt, 1987, Boundary Layer Meteorol, 38, 185-202. OSU Model User's Guide, 1988. OSU Model User's Guide, 1991. Air Force heritage prior to 1991 (AFGL, AFGWC) Yang et al, 1985 (AFGL Tech Report) Mitchell, 1985 (AFGWC Tech Report) Moore et al, 1988. (AMS Preprint Paper) NCEP heritage after 1992 (NCEP, OH, NESDIS, PILPS, GSWP) Chen, Mitchell, Schaake, et al, 1996, J. Geophys. Res, 101, No. D3, 7251-7268. Chen, Janjic, Mitchell, 1997, Boundary-Layer Meteorol, 85, 391-421. Betts, Chen, Mitchell, Janjic, 1997, Mon. Wea. Rev., 125, 2896-2916. Koren, Schaake, Mitchell, Duan, Chen, Baker, 1999: A parameterization of snowpack and frozen ground intended for NCEP Weather and Climate Models. Accepted, J. Geophys. Res. (copy may be requested from NCEP Point of Contact at top of page 1) 12.1 Uncoupled LSM Physics and/or Uncoupled Validation (This section pending) FIFE PILPS-2a PILPS-2c PILPS-2d GSWP (ISLSCP) 12.2 Coupled Validation Studies Yucel et al (1997) Chen et al (1997) Berbery et al (1998) (continued) Marshall et al (1998) Hinkelman et al (1998) Mitchell et al (1999) 13.0 PROGRAM REVISION LOG 01 Mar 99 : Ver_1.0 -- Original version released 08 Mar 99 : Ver_1.1 -- Fix coding error in snow albedo -- Moved CALL SFCDIF (to calculate sfc exch coeff for heat) from MAIN to routine SFLX, to facilitate creation of personal versions of MAIN driver by external users -- Removed air density (RHO) from COMMON /RITE/ -- Added output of two more albedo vars to routine PRTHYDF -- Added several more parameters to routine REDPRM arg list