Go to next page Go to previous page Go to top page Go to table of contents

Previous Section Headers

User's Guide to LSM1.1

1. Using LSM1.1

This guide is a brief introduction to the use and overall design of the land surface model (LSM). Most of the changes made between LSM1.1 and LSM1.0 are those to the user interface. The only physics changes were changing the alogorithm for calculating the earth's orbit and solar zenth angle (Berger, 1977). This document is meant to describe these changes as well as to to serve as a companion to the technical description of the land surface model (see the technical description section of A Land Surface Model (LSM Version 1.0) (Bonan 1996) ). In the following, we briefly outline the LSM code design and discuss the types of LSM runs, LSM input variables and input and output LSM datasets. 

1.1 Overview

LSM can be run as part of CCM3 (communicating with the atmospheric component of CCM3 through subroutine calls) or as a stand alone executable communicating with CCM3 via the Climate System Model (CSM) flux coupler (Bryan, 1996).

LSM consists of two main subroutines; lsmdrv and lsmini. Routine lsmini initializes the land surface model and returns as two-dimensional (longitude x latitude) arrays any land surface variables (e.g., surface temperature) required by the atmospheric model. Non-land values are undefined. Subroutine lsmdrv calculates surface fluxes, updates the ecological, hydrologic and thermal state of the land, and updates the LSM history fields. lsmdrv processes the land points by first gathering the lpt land points on the (lsmlon x lsmlat) grid into a ``large" vector of kpt points, allowing for up to msub subgrid points per land point. This "large" vector is processed as smaller vectors by routine lsm. This architecture has the following advantages: (a) only land points are processed; (b) local arrays within subroutine lsm are dimensioned by the number of points processed in each call to lsm rather than by kpt, resulting in small memory requirements when using multiple processors; and (c) multi-tasking results in reasonable load balancing among processors.

CCM3 and LSM exchange information (via the flux coupler or through subroutine calls) in terms of two-dimensional fields. Currently, the LSM grid must be the same as the atmospheric model grid. LSM expects as input atmospheric fields for the entire grid. These input fields are then used to force LSM, which subsequently returns two-dimensional fields, setting only the land points in the domain.

If LSM is run as part of CCM3, subroutines lsmini and lsmdrv are invoked from within CCM3. If LSM is run through the flux coupler, program lsmmain invokes lsmini and lsmdrv. Regardless of the mode, there is always one call to lsmini during initialization and one call per time step to lsmdrv. The calling diagrams for lsmini and lsmdrv are given in "Appendix A: LSM Calling Diagrams".

1.2 Initial Runs

LSM initial datasets are in netCDF file format and consist of both time-invariant and time-variant fields. The time-invariant data fields contain information about each grid cell on the two-dimensional (lsmlon x lsmlat) LSM grid and are oriented from the South Pole to to North Pole, starting at Greenwich and proceeding eastwards. The time invariant data fields are summarized below: Time-variant initial data fields consist of initial water (snow, vegetation, soil) and temperature (vegetation, ground surface, soil) for the kpt subgrid points.

Initial data can either be generated at run time or obtained from an LSM initial dataset. If the LSM namelist variable FINIDAT (see Run Options) is set to ``arbitrary initialization'', LSM initial data are computed at run time and output to the file ``lsmi_arbini.nc'' Alternatively, FINIDAT may be set to the name of a previously created LSM initial dataset, providing that this dataset has the same grid resolution and the same number of subgrid points as the run for which it is to be used.

1.2.1 Initial runs from ``arbitrary initialization''

If FINIDAT is set to ``arbitrary initialization'', initial LSM data is created at run time in routine lsmcrarbi. The time-invariant portion of the initial data is first created in fsurdat using five datasets that are independent of model resolution. Currently, these datasets are hard-wired into the model code and consist of: LSM requires fractional land data at each model grid to determine whether a particular latitude-longitude grid point is to be treated as land or non-land. Fractional land data is obtained from CCM3 or from the flux coupler. If fractional land data obtained from the flux coupler, it will be dependent on the resolution of the ocean/sea-ice models.

Subsequent to the computation of time-invariant initial data, the remaining data fields required for an initial run are constructed in lsmcrarbi_dyn and lsmtvi. Initial water (snow, vegetation, soil) and temperature (vegetation, ground surface, soil) for each subgrid point are initialized to constant values in lsmcrarbi_dyn. Other variables needed for initialization are set in lsmtvi and are either calculated based on initial water and temperature values or set to constant values because their exact value is not too important. The one exception is the soot content of snow, which currently is time-invariant.

1.2.2 Initial runs from initial data files

If an initial run does not create its own initialization data, it must start from a previously generated LSM initial dataset. If FINIDAT is set to the name of an LSM initial dataset, that dataset will be read in lsmrdinit. An LSM initial dataset must have the same resolution and the same number of subgrid points (also implying the same fractional land data) as the run for which it is intended. In general, an initial dataset generated from a flux-coupled run cannot be used as initial data for a simulation where the LSM is run as part of CCM3, since the fractional land data will generally be different in the two cases. Similarly, an initial datset from one flux-coupled run cannot be used for another flux-coupled run with a different ocn/ice grid resolution since once again the fractional land will be different.

During a model run, LSM initial datasets may be generated monthly, yearly or not at all, depending on the setting of the LSM namelist variable INITHIST (see "Run Options").

1.3 Output History and Restart Files

LSM writes its own history and restart files. Output history files are in netCDF file format and fall into two categories; files for model analysis and initial dataset files. History files meant for analysis of model output are by default time averaged. Initial dataset files, on the other hand, are instantaneous history files containing only initial data fields. Restart files are in binary format and can be used only to restart or branch runs from previous simulations. The primary LSM routines needed to produce history and restart files all begin with hist or rest (e.g. histcrt.F restwrt.F) (see "LSM Code Description").

Time averaged history files have the names lsmh_xxxxx.nc for non-monthly averaged output and lsmh_yyyy-mm.nc for monthly averaged files. In the first case, xxxxx is unique text determined by the file number (e.g. 00001 to 99999), whereas in the latter case, yyyy and mm specify the year and month, respectively (e.g. 0001-09 is data for September of year 1). Instantaneous history files intended for use as LSM initial datasets have the names lsmi_yyyymmdd_sssss.nc, where yyyy is the year, mm is the month, dd is the day and sssss is the seconds into the day. Finally, restart files have the names lsmr_yyyymmdd_sssss.

Instantaneous history files that can serve as LSM initial datasets may be written monthly, yearly or not at all, depending on the setting of the namelist variable INITHIST. The generation of these datasets is controlled by routines histcrtini and histwrtini. The specific fields output on these datasets are hardwired into the code and may not be modified by namelist settings.

During initialization, routine histtc creates a history file for the time constant vegetation and soil variables. This file is written in the same directory as the time-varying history files and is given the name ``lsmh_timcon''.

A history time sample is written to a history file every NHTFRQ iterations or at the end of the month (if using the monthly average option). Up to MFILT time samples may be written to a file. For monthly average files, MFILT is set to 1. A history file is closed (and archived to the Mass Store if desired) when the file is full or if the end of the model run has been reached. History and restart files are output to the disk directories defined by the LOCPNH and LOCPNR namelist variables. If the NCAR Mass Store is used, history and restart files are archived as follows:

where CASEID corresponds to the CASEID namelist variable.

Routine histlst sets the default history field list (i.e., the name, units, description of the fields and the field type). Fields are segregated as single-level or multi-level, where multi-level refers to the number of soil layers (e.g., soil temperature and soil water are multi-level fields). The field type can be the average over a history interval (the default), the maximum value in the history interval, the minimum value in the history interval, or the instantaneous value at the end of the history interval. The default field type for a given field can be overridden by the setting of the paired (field name, field type) chntyp namelist variables (section "Run Options") All LSM history fields are output on the (lsmlon x lsmlat) grid after a subgrid to 2d-grid mapping has been performed. If certain fields are desired as vectors of kpt points (for single-level fields) or as msl vectors of kpt points (for multi-level fields), this additional output can be specified by setting the FLDS1D namelist variable. The default fields set in histlst can be made inactive by setting the EXCL namelist variable (section "Run Options") to the appropriate field names.

New fields can be added to the history files by modifying histlst. The variable nflds needs to be incremented by one for each new field. The field name fldnam, units flduni, level fldlev, and type fldtyp, and field description flddes variables need to be set to appropriate values. This process must be repeated for however many new active fields are added. The parameters mslflds and mmlflds set in lsmpar.h should be increased depending on the number of added single- and multi-level fields. Finally, since field values for the current iteration are accumulated by histslf and histmlf for single-level and multi-level fields, respectively, new calls to these routines will have added in routine lsm in order to accumulate the new fields over the history interval. Note that accumulated values for all history fields are contained in the arrays slfval and mlfval. Time averaged fields are normalized by the length of the history interval before being written to the history file.

An LSM restart file is a binary file containing the variables needed to either restart or branch a model run. For example, lsmr_000010101_1200 will restart or branch a model simulation starting from 1200 seconds into January 1 of year 1. Whenever a restart file is written, a corresponding restart pointer file on local disk is overwritten. The namelist variable REST_PFILE specifies the ASCII file that contains the name of the current restart file. If LSM is run as part of CCM3, restart files are written and disposed to the Mass Store whenever a history file is closed or at the end of a run. It is enforced at startup that NHTFRQ and MFILT be the same for LSM and CCM3. This ensures that restart files are obtained for both models at the same times. If the LSM model is run through the flux coupler, restart files are written only when the flux coupler specifies or at the end of a run. 

1.4 Continuation Runs

Two types of continuation runs are possible, restart and branch runs. A restart run continues an earlier run using the most recent restart file. Run control variables set in the restart namelist must be the same as in the original run. The model does not check for consistency. The appropriate restart file (e.g., ``lsmr_000001001_36000'') is read from the disk restart pointer file specified by the namelist variable REST_PFILE (which by default is set to `` ~/lnd.CASEID.rpointer''). If the associated LSM history file (e.g., lsmh_00100) is not full, it is opened such that subsequent time samples may be added until the file is full.

A branch run allows the user to begin a new simulation by ``branching'' from an existing control run. In this case, the model restarts from a specified restart file set by the namelist variable NREVSN (see Run Options). The value of NREVSN msut be either a local or Mass Store full pathname. Because a branch run must be a new case, the length of the history interval and the active field list do not have to be the same as in the control simulation. For example, the branching option can be used to repeat a specified time interval of a run in which daily-average history files were written. However, in the branched run, selected fields may be written to a history file every iteration, thereby resolving the diurnal cycle. Note that in a branch run, a new time constant history file is created at startup. 

1.5 Run Control Parameters

Four files set the control parameters for the model: pre-processor directives are set in preproc.h and misc.h; parameters for grid dimensions and history fields and other miscellaneous LSM parameters are defined in lsmpar.h; and run control variables are set in the LSMEXP namelist.

1.5.1 Pre-Processor Directives

The model utilizes the following C pre-processor ''cpp'' directives: The following #define and #undef directives are set in the file preproc.h:

Table 1.1: preproc.h preprocessor tokens
CPP Variable Name
Description
LSMLON Defines the number of longitudes on the LSM grid. 
LSMLAT Defines the number of latitudes on the LSM grid. 
If LSM is run as part of CCM3, the header file misc.h is used by both CCM3 and LSM code. Therefore, it is important that no resolution dependent variables be contained in misc.h. The contents of misc.h are described in the following table.

Table 1.2: misc.h preprocessor tokens
CPP Variable Name
Description
CRAY, SGI or SUN Defines the platform for the model run. Currently, these are the only platforms supported. 
COUP_CSM If COUP_CSM is not defined, LSM is run as part of CCM3. The case name, the land fraction at each grid point, the model time step, base calendar information, run type (initial, restart, branch), type of time averaging for history fields, history file write frequency, number of time samples per history file, the solar radiation frequency and the current time,are obtained from the CCM3 model. 
If COUP_CSM is defined, LSM is coupled to CCM3 via the flux coupler. The fractional land at each model grid point is obtained from the flux coupler. Namelist variables supplied by CCM3 when COUP_CSM is not defined must now be specified (see below). 
SHELL_MSS If on a NCAR Cray, the Fortran mass store interface will be used if the cpp token SHELL_MSS is not defined. For other platforms, this token needs to be defined. If SHELL_MSS is not defined, the model requires the Fortran library routines unlink, msread, and mswrite. 
PVP (Parallel vector processor) must be defined if the CRAY platform is used. 
FORTFFT Define for non-NCAR platform. 
SPMD Enables message passing if defined. Should not be defined on CRAY platform. 
NCPREC Precision of output NetCDF history file. Must be set to NF_FLOAT or NF_DOUBLE. 
REALTYPE Define REALTYPE MPI_REAL for CRAY platform. Define as REALTYPE MPI_DOUBLE_PRECISION for non-CRAY platform. 

1.5.2 Parameters

Parameters that set the grid dimensions (lsmlon, lsmlat), the maximum number of subgrid points (msub), and the maximum size of the ``little vectors'' (mpt), are defined in lsmpar.h. This file also defines parameters for the number of solar radiation wavebands, the number of soil layers, the number of plant types, the number of soil color classes, and the number of ``soil" types. Finally, it sets the maximum number of single-level and multi-level variables for output on history files. Note that the number of longitude and latitude points on the LSM grid (as defined by lsmlon and lsmlat) must currently be the same as the atmospheric model grid.

The land surface model works by gathering the lpt land points on the lsmlon by lsmlat grid into a ``big" vector of kpt subgrid points, allowing for up to msub subgrid points per land point. The kpt subgrid points are processed as as ``little" vectors of mpt points and possibly one ``little'' vector of mod(kpt,mpt) points. The multiple calls to the ``little vector" land surface code can be multi-tasked if desired. The parameter mpt specifies the maximum number of points to be processed by the ``little vector" code. Whereas values for lpt and kpt are determined at run time, mpt is specified by a parameter declaration. Currently, mpt is set to 64. The user may want to modifiy this setting.

1.5.3 Run Options

Variables that control run options are set through the LSMEXP namelist. Default values for these variables are set in lsmctli.

The minimum namelist input required to run LSM as part of CCM3 is FINIDAT. Other namelist variables are obtained from the CCM3 model and should not be specified separately in the LSM namelist. If values for the following variables are specified when LSM is run as part of CCM3, they will be overwritten with values obtained from from the CCM3:

The minimum namelist variables required to run LSM through the flux coupler are: The following table describles the LSMEXP namelist variables:

Table 1.3: LSMEXP namelist input variables

 
Variable Name
Type
Default
Value
Description
Define the type and length of run
CASEID C*8 blanks Case identifier. Used as part of the MSS path name for history and restart files. 
Required for flux coupled runs.
CTITLE C*80 blanks Case title. 
Not required. 
DTIME Real -9999999. Model timestep in seconds. 
Required for flux coupled runs.
NSREST Integer -9999999 Run type: 0=initial, 1=restart, 3=branch. 
Required for flux coupled runs.
NNBDAT Integer -9999999 Base date for run as yyyymmdd ( 010625 is June 25, year 1). . 
Required for flux coupled runs.
NNBSEC Integer -9999999 Seconds of base date. 
Required for flux coupled runs.
NNDBAS Integer -9999999 Base Model day for run 
Required for flux coupled runs.
NNDBAS Integer -9999999 Seconds of base Model day for run. 
Required for flux coupled runs.
Input data sets
FINIDAT C*80 "not_specified" Initial dataset name. If FINIDAT is equal to "arbitrary initialization", an initial file lsmi_arbini.nc is created at startup. 
Required.
NREVSN C*80 blanks Full restart pathname for branch runs. 
Required only if branch run. 
DATADIR C*80 blanks Disk directory where input datasets may be found by Model. 
Not required. 
Generation of initital surface data
ANTARTICA Logical true  If set to true, Antartica is extended for the Ross Ice Shelf. Only used if COUP_CSM is not defined. Antartica is NEVER extended for flux coupled runs. 
Not required 
History and Restart Files Variables
NHTFRQ Integer -24 Write frequencies for history time samples in hours (negative) or iterations (positive). 
Not required. 
MFILT Integer 1 Integer number of time samples per history file. 
Not required. 
NINAVG C*1 blanks If equal to ``q" or ``Q" the monthly average history option is used (one time sample per file, overriding settings for NHTFRQ and MFILT). 
Not required. 
FLDS1D C*8 blanks Names of fields to output as 1-dimensional fields of kpt points in addition to the 2-dimensional output (up to malflds names). 
Not required. 
EXCL C*8 blanks Array of variables to exclude from the history files. For example, setting EXCL = `TV', `TAM' deletes the fields TV and TAM from the history files. 
Not required. 
CHNTYP C*8 blanks Paired 8 character array of field names and field types to override the default settings. Valid field types are average, maximum, minimum, or instant. For example, setting CHNTYP = `FPSN', `maximum' results in the maximum value of FPSN over the history interval to be output. 
Not required. 
LOCPNH C*80 '.' Sets the disk directory for history files. 
Not required. 
LOCPNR C*80 '.' Sets the disk directory for restart files. 
Not required. 
REST_PFILE C*80 ~/lnd. 
CASEID.rpointer		 Full UNIX pathname of the restart pointer file. This file is overwritten and updated every time new restart datasets are output. 
Not required. 
NSWRPS C*8 blanks MSS write password. 
Not required. 
IRT Integer -24 MSS retention period. 
Not required. 
Model Physics Variables
HYDRO Logical True Set to false if the prognostic hydrology is not used. In this case, canopy, snow, and soil water pools will not change from the initial conditions. 
Not required. 
PERGRO Logical False Set to true for random perturbation growth tests. A perturbation growth test, in which initial conditions are randomly perturbed by some small amount, is a useful means to ensure the model is working correctly when using different compilers, operating systems, or other changes that result in a small perturbation. When compared to a control run, the land surface model generally has large, rapid solution separation due to the following reasons: (a) the large sensitivity of the vegetated latent heat flux to small changes in the wetted fraction of the canopy and (b) the strong non-linearity of the latent and sensible heat fluxes to atmospheric stability. This option reduces the solution separation due to a small random perturbation by setting the wetted fraction of the canopy to zero and setting atmospheric stability to neutral. PERGRO should be set to false unless a perturbation growth test is being performed. 
Not required. 
Flux Coupled Runs Only
IRAD Integer -1 The frequency for solar radiation calculations in hours (negative) or model iterations (positive). 
Required for flux coupled runs.
FLXAVE Logical True If true, flux averaging (over the duration IRAD is set to) is performed when running the model through the flux coupler. 
Not required. 

Sub Sections

    1.1 Overview
    1.2 Initial Runs
    1.3 Output History and Restart Files
    1.4 Continuation Runs
    1.5 Run Control Parameters

Go to next page Go to previous page Go to top page Go to table of contents

 Search for keywords in the LSM1.1 as coupled to CCM3.6 Users GuideSearch page

Questions on these pages can be sent to... mvertens@ucar.edu . 

$Name: ccm3_6_6_latest2 $ $Revision: 1.12.4.1 $ $Date: 1999/03/25 21:40:12 $ $Author: erik $