Land Information System (LIS): LIS 7.3 Users' Guide

Land Information System (LIS) is a flexible land surface modeling and data assimilation framework developed with the goal to integrate satellite- and ground-based observational data products and advanced land surface modeling techniques to produce optimal fields of land surface states and fluxes. The LIS infrastructure provides the modeling tools to integrate these observations with model forecasts to generate improved estimates of land surface conditions such as soil moisture, evaporation, snow pack, and runoff, at 1km and finer spatial resolutions and at one-hour and finer temporal resolutions. The fine scale spatial modeling capability of LIS allows it take advantage of the EOS-era observations, such as MODIS leaf area index, snow cover, and surface temperature, at their full native resolution. LIS features a high performance and flexible design, provides infrastructure for data integration and assimilation, and operates on an ensemble of land surface models (LSM) for extension over user-specified regional or global domains. LIS is designed using advanced software engineering principles to enable reuse and community sharing of modeling tools, data resources, and assimilation algorithms. The system is designed as an object-oriented framework, with abstractions defined for customization and extension to different applications. These extensible interfaces allow the incorporation of new domains, LSMs, land surface parameters, meteorological inputs, data assimilation and optimization algorithms. The extensible nature of these interfaces and the component style specification of the system allow rapid prototyping and development of new applications. These features enable LIS to serve both as a Problem Solving Environment (PSE) for hydrologic research to enable accurate global water and energy cycle predictions, and as a Decision Support System (DSS) to generate useful information for application areas including disaster management, water resources management, agricultural management, numerical weather prediction, air quality and military mobility assessment.

LIS currently includes a comprehensive suite of subsystems to support uncoupled and coupled land data assimilation. A schematic of the LIS framework with the associated subsystems are shown in the Figure below. The LIS-LSM subsystem, which is the core of LIS, supports high performance, interoperable and portable land surface modeling with a suite of community land surface models and input data. Further, the LIS-LSM subsystem is designed to encapsulate the land surface component of an Earth System model. The LIS-WRF subsystem supports coupled land-atmosphere modeling through both one-way and two-way coupling to the WRF atmospheric model, leading to a hydrometeorological modeling capability that can be used to evaluate the impact of land surface processes on hydrologic prediction. The Data Assimilation (LIS-DA) subsystem supports multiple data assimilation algorithms that are focused on generating improved estimates of hydrologic model states. Finally, the Optimization (LIS-OPT) subsystem supports a suite of advanced optimization and uncertainty modeling tools in LIS.

The central part of LIS software system is the LIS core that controls program execution. The LIS core is a model control and input/output system (consisting of a number of subroutines, modules written in Fortran 90 source code) that drives multiple offline one-dimensional LSMs. The one-dimensional LSMs such as CLM and Noah, apply the governing equations of the physical processes of the soil-vegetation-snowpack medium. These land surface models aim to characterize the transfer of mass, energy, and momentum between a vegetated surface and the atmosphere. When there are multiple vegetation types inside a grid box, the grid box is further divided into “tiles”, with each tile representing a specific vegetation type within the grid box, in order to simulate sub-grid scale variability.

The execution of the LIS core starts with reading in the user specifications, including the modeling domain, spatial resolution, duration of the run, etc. Section Running the Executable describes the exhaustive list of parameters specified by the user. This is followed by the reading and computing of model parameters. The time loop begins and forcing data is read, time/space interpolation is computed and modified as necessary. Forcing data is used to specify the boundary conditions to the land surface model. The LIS core applies time/space interpolation to convert the forcing data to the appropriate resolution required by the model. The selected model is run for a vector of “tiles” and output and restart files are written at the specified output interval.

Some of the salient features provided by the LIS core include:

Please refer to the software design document for a detailed description of the design of LIS core. The LIS reference manual provides a description of the extensible interfaces in LIS. The “plug and play” feature of different components is described in this document.

Commands are written with a fixed-width font. E.g.:

“…​ compiler flags, then run gmake.”

File names are written in italics. E.g.:

/path/to/LISv7.0/src

LIS is developed on Linux/Unix platforms. Its build process expects a case sensitive file system. Please make sure that you unpack and/or git clone the LIS code into a directory within a case sensitive file system. In particular, if you are using LIS within a Linux-based virtual machine hosted on a Windows or Macintosh system, do not compile/run LIS from within a shared folder. Move the LIS source code into a directory within the virtual machine.

The LIS public release 7.3 source code is available both on LISF’s web-site under the “Source” menu and on GitHub under the NASA-LIS organization at https://github.com/NASA-LIS/LISF under the “Releases” link.

After downloading the LISF tar-file:

The LIS source code is maintained in a git repository hosted on GitHub. If you wish to work with the latest development code (in the master branch), then you must use the git client to obtain the LIS source code. If you need any help regarding git or GitHub, please go to https://github.com.

Unpacking or cloning the LISF source code (according to the instructions in Section Obtaining the Source Code) will create a directory named LISF. The LIS specific source code is in LISF/lis.

The structure of LISF/lis is as follows:

Processed documentation may be found on LISF’s web-site under the “Docs” menu.

This code has been compiled and run on Linux PC (Intel/AMD based) systems and Cray systems. These instructions expect that you are using such a system. In particular you need:

In order to build the LIS executable, the following libraries must be installed on your system:

The following libraries are not required to compile LIS. They are used to extend the functionality of LIS.

LIS [-f <file> | --file <file>]

The new LIS framework (LISF) set of public testcases include a full end-to-end suite of LDT, LIS, and LVT cases that build off each other with several different steps, which are outlined in the table below. The suite of testcases include generating model parameter and assimilation-based input files using LDT, running the Noah land surface model (LSM) for a sample "open-loop" (or baseline) experiment and a data assimilation (DA) experiment using LIS, and then comparing output from the sample experiments using LVT.

The new public test cases are available from our main LIS webpage:

https://lis.gsfc.nasa.gov/tests/lis

All required input and data files are bundled with each of the cases from the above website. Also, documentation is provided that accompanies each of the cases for additional details and information. Below the table of test cases on the webpage, users will find information about which version, compiler and libraries used to generate and test the different test cases provided.

The main purpose of these test cases is for the LIS development team to internally test various components of the LIS source code. These test cases are comprised of three parts: a testcases sub-directory included in the LIS source code, input data, and output data.

For these test cases, we do not provide any of the input or output datasets, but users are welcome to use the config files in these subdirectory cases as a guide to setting up their own individual experiments and for their own testing purposes.

For the Fortran binary format, LIS writes the output data as 4-byte REALs in sequential access mode.

The order in which the variables are written is the same order as in the statistical summary file; e.g., SURFACEMODEL.d01.stats.

The generated output can be written in a 2-D grid format or as a 1-d vector. See Section Runtime options for more details. If written as a 1-d vector, the output must be converted into a 2-d grid before it can be visualized. This is left as an exercise for the reader.

GRIB1 is a self-describing data format. The output files produced in GRIB1 can be inspected by using either the utility wgrib (http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html) or the utility grib_dump (provided with GRIB-API; see Section Required Software Libraries).

NetCDF is a self-describing format. The output files produced in NetCDF can be inspected by using the utility ncdump (provided with NetCDF; see Section Required Software Libraries).

Running mode: specifies the running mode used in LIS. Acceptable values are:

Map projection of the LIS domain: specifies the map projection of the LIS domain used for the run. Acceptable values are:

Number of nests: specifies the number of nests used for the run. Values 1 or higher are acceptable. The maximum number of nests is limited by the amount of available memory on the system. The specifications for different nests are done using white spaces as the delimiter. Please see below for further explanations. Note that all nested domains should run on the same projection and same land surface model.

Number of surface model types: specifies the number of surface model types used for the run. Values of 1 through LIS_rc%max_model_types (currently equal to 3) are acceptable.

Surface model types: specifies the surface model types used for the run. Acceptable values are:

Surface model output interval: specifies the surface model output interval.

See Section Defining a time interval for a description of how to specify a time interval.

Land surface model: specifies the land surface model to run. Acceptable values are:

Lake model: specifies the lake model to run. Acceptable values are:

Open water model: specifies the open water model to run. Acceptable values are:

land slide model: specifies the land slide model to run. Acceptable values are:

Number of met forcing sources: specifies the number of met forcing datasets to be used. Acceptable values are 0 or higher.

Met forcing chosen ensemble member: specifies the desired ensemble member from a given forcing data source to be assigned across all LIS ensemble members. This option is enabled only if the met forcing data source contains its own ensembles.

Blending method for forcings: specifies the blending method to combine forcings when one or more forcing datasets are used. Acceptable values are:

Met forcing sources: specifies the met forcing data sources for the run. The values should be specified in a column format. Acceptable values for the sources are:

Topographic correction method (met forcing): specifies whether to use elevation correction for base forcing. Acceptable values are:

Enable spatial downscaling of precipitation: specifies whether to use spatial downscaling of precipitation. Acceptable values are:

Spatial interpolation method (met forcing): specifies the type of interpolation scheme to apply to the met forcing data. Acceptable values are:

Bilinear interpolation uses 4 neighboring points to compute the interpolation weights. The conservative approach uses 25 neighboring points. If the conservative option is turned on, it is used to interpolate the precipitation field only (to conserve water). Other fields will still be interpolated with the bilinear option.

Spatial upscaling method (met forcing): specifies the type of upscaling scheme to apply to the met forcing data. Acceptable values are:

Please note that not all met forcing readers support upscaling of the met forcing data.

Temporal interpolation method (met forcing): specifies the type of temporal interpolation scheme to apply to the met forcing data. Acceptable values are:

The linear temporal interpolation method computes the temporal weights based on two points. Ubernext computes weights based on three points. Currently the ubernext option is implemented only for the GSWP forcing.

Enable new zterp correction (met forcing): specifies whether to enable the new zterp correction. Acceptable values are:

Defaults to .false..

This is a scalar option, not per nest.

This new zterp correction addresses an issue that potentially can occur at sunrise/sunset for some forcing datasets when running at small time steps (like 15mn). In some isolated cases, SWdown may have a large unrealistic spike. This correction removes the spike. It also can affect SWdown around sunrise/sunset by up 200 W/m2. Users are advised to run their own tests and review SWdown to determine which setting is best for them.

For comparison against older LIS runs, set this option to .false..

Forcing variables list file: specifies the file containing the list of forcing variables to be used. Please refer to the sample forcing_variables.txt (Section Specification of Input Forcing Variables) file for a complete specification description.

Output methodology: specifies whether to write output as a 1-D array containing only land points or as a 2-D array containing both land and water points. 1-d tile space includes the subgrid tiles and ensembles. 1-d grid space includes a vectorized, land-only grid-averaged set of values. Acceptable values are:

When writing output using the “2d gridspace” setting with ensembles enabled, LIS will average the ensemble members into one field to write into the output file; when using the “2d ensemble gridspace” option, LIS will write each ensemble member into the output file.

Note that the “2d ensemble gridspace” setting requires setting the Output data format: option to “netcdf”.

Output model restart files: specifies whether to write model restart files. Acceptable values are:

Output data format: specifies the format of the model output data. Acceptable values are:

Output naming style: specifies the style of the model output names and their organization. Acceptable values are:

Enable output statistics: specifies whether to write the ASCII statistics file for the output data. Acceptable values are:

Defaults to .true..

Output GRIB Table Version: specifies GRIB table version.

Output GRIB Center Id: specifies GRIB center id.

Output GRIB Subcenter Id: specifies GRIB sub-center id.

Output GRIB Grid Id: specifies GRIB grid id.

Output GRIB Process Id: specifies GRIB process id.

Output GRIB Packing Type: specifies the algorithm used to pack data into the GRIB message. Acceptable values are:

Though untested, there are more packingType available as listed at https://confluence.ecmwf.int/display/ECC/GRIB+Keys

For GRIB-2 try:

Start mode: specifies if a restart mode is being used. Acceptable values are:

When the cold start option is specified, the program is initialized using the LSM-specific initial conditions (typically assumed uniform for all tiles). When a restart mode is used, it is assumed that a corresponding restart file is provided depending upon which LSM is used. The user also needs to make sure that the ending time of the simulation is greater than model time when the restart file was written.

The start time is specified in the following format:

The end time is specified in the following format:

LIS time window interval: specifies the interval at which the LIS run loop cycles, used in the “ensemble smoother” running mode.

Undefined value: specifies the undefined value. The default is set to -9999.

Output directory: specifies the name of the top-level output directory. Acceptable values are any 40 character string. The default value is set to OUTPUT. For simplicity, throughout the rest of this document, this top-level output directory shall be referred to by its default name, $WORKING/LIS/OUTPUT.

Diagnostic output file: specifies the name of run time diagnostic file. Acceptable values are any 40 character string.

Number of ensembles per tile: specifies the number of ensembles of tiles to be used. The value should be greater than or equal to 1.

The following options are used for subgrid tiling based on vegetation

Maximum number of surface type tiles per grid: defines the maximum surface type tiles per grid (this can be as many as the total number of vegetation types).

Minimum cutoff percentage (surface type tiles): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

Maximum number of soil texture tiles per grid: defines the maximum soil texture tiles per grid (this can be as many as the total number of soil texture types).

Minimum cutoff percentage (soil texture tiles): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

Maximum number of soil fraction tiles per grid: defines the maximum soil fraction tiles per grid (this can be as many as the total number of soil fraction types).

Minimum cutoff percentage (soil fraction tiles): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

Maximum number of elevation bands per grid: defines the maximum elevation bands per grid (this can be as many as the total number of elevation band types).

Minimum cutoff percentage (elevation bands): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

Maximum number of slope bands per grid: defines the maximum slope bands per grid (this can be as many as the total number of slope band types).

Minimum cutoff percentage (slope bands): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

Maximum number of aspect bands per grid: defines the maximum aspect bands per grid (this can be as many as the total number of aspect band types).

Minimum cutoff percentage (aspect bands): defines the smallest percentage of a cell for which to create a tile. The percentage value is expressed as a fraction.

This section specifies the 2-d layout of the processors in a parallel processing environment. There are two ways that the user can specify the 2-d layout.

One way is the user can specify the number of processors along the east-west dimension and north-south dimension using Number of processors along x: and Number of processors along y:, respectively. Note that the layout of processors should match the total number of processors used. For example, if 8 processors are used, the layout can be specified as 1x8, 2x4, 4x2, or 8x1. When choosing this way, the option Decompose by processes: must be set to .false.. This way is useful when you must match a specific layout.

The other way is the user can allow LIS to create a load-balanced layout based on the number of processes. For example, if 8 processors are used, LIS will create a 4x2 layout where each process contains roughly the same amount of land-based grid-cells. When this way is chosen, LIS ignores both the Number of processors along x: and the Number of processors along y: options. This way is useful when your running domain contains a large number of ocean-based grid-cells, which would result in many under-utilized processes when using a specified layout.

Acceptable values for Decompose by processes are:

Defaults to .false..

Further, this section also allows the specification of halos around the domains on each processor using Halo size along x: and Halo size along y:.

Routing model: specifies the routing model to run. Acceptable values are:

External runoff data source: Specifices the data source to be used for reading the surface runoff and baseflow fields for offline routing.

Acceptable values are:

Number of application models: specifies the number of application models to run.

This section specifies the choice of forecast options.

Forecast forcing source mode: specifies the forecast run-mode and source option (e.g., ensemble streamflow prediction, or ESP), and depends on the number of forcing datasets selected. Acceptable values are:

ESP conventional start time of the forcing archive: specifies the ESP conventional forcing start date (YYYY MM DD).

ESP conventional end time of the forcing archive: specifies the ESP conventional forcing end date (YYYY MM DD).

ESP conventional include targeted forecast year: is an option if the user wants to include the year from the historical archive that is the same target year being forecasted. This is to provide a check of the climatology, but it is not recommended for hindcast evaluations.

ESP boot sampling time window interval: specifies the ESP bootstrapping (“boot”) temporal sampling window.

ESP boot start time of the forcing archive: specifies the ESP bootstrapping (“boot”) forcing start date (YYYY MM DD).

ESP boot end time of the forcing archive: specifies the ESP bootstrapping (“boot”) forcing end date (YYYY MM DD).

Forecast forcing start mode: specifies the type of forecast start mode, either coldstart or restart. If restart is specified, a restart file name needs to be supplied.

Forecast forcing restart filename: specifies the restart filename.

This section specifies the choice of data assimilation options.

Number of data assimilation instances: specifies the number of data assimilation instances. Valid values are 0 (no assimilation) or higher.

Data assimilation algorithm: specifies the choice of data assimilation algorithms. Acceptable values are:

Data assimilation set: specifies the “assimilation set”, which is the instance related to the assimilation of a particular observation. Acceptable values are:

Data assimilation exclude analysis increments: specifies whether the analysis increments are to be skipped. This option is typically used along with the dynamic bias estimation algorithm. The user can choose to apply only the bias increments or both the bias increments and analysis increments. Acceptable values are:

Data assimilation output interval for diagnostics: specifies the output diagnostics interval.

See Section Defining a time interval for a description of how to specify a time interval.

Data assimilation number of observation types: specifies the number of observation species/types used in the assimilation.

Data assimilation output ensemble spread: specifies whether to output the ensemble spread. Acceptable values are:

Data assimilation output processed observations: specifies whether the processed, quality-controlled observations are to be written (Note that a corresponding observation plugin routine needs to be implemented). Acceptable values are:

Data assimilation output innovations: specifies whether a binary output of the normalized innovations is to be written. Acceptable values are:

Data assimilation use a trained forward model: specifies whether to use a trained forward model. Acceptable values are:

Data assimilation trained forward model output file: specifies the name of the output file for the trained forward model. The training is done by LDT, and thus, this file is produced by LDT.

Data assimilation scaling strategy: specifies the scaling strategy. Acceptable values are:

Data assimilation observation domain file: specifies the observation domain file, which will be used as the domain to compute the innovations.

Bias estimation algorithm: specifies the dynamic bias estimation algorithm to use. Acceptable values are:

Bias estimation attributes file: ASCII file that specifies the attributes of the bias estimation. A sample file is shown below, which lists the variable name first. This is followed by the nparam value (0-no bias correction, 1- constant bias correction without diurnal cycle, 3- diurnal sine/cosine bias correction, 5 - semi-diurnal sine/cosine bias correction, 2-“time of day” bias correction with 2 separate bias estimates per day, 4 - “time of day” bias correction with 4 separate estimates per day, 8 - “time of day” bias correction with 8 separate bias estimates per day), tconst (which describes the time scale relative to the temporal spacing of the observations), and trelax (which specifies temporal relaxation parameter, in seconds)

#nparam tconst trelax
Soil Temperature
1.0 0.05 86400.0

Bias estimation restart output frequency: Specifies the frequency of bias restart files.

See Section Defining a time interval for a description of how to specify a time interval.

Bias estimation start mode: This option specifies whether the bias parameters are to be read from a checkpoint file. Acceptable values are:

Bias estimation restart file: Specifies the restart file to be used for initializing bias parameters

Perturbations start mode: specifies if the perturbations settings should be read from a restart file. Acceptable values are:

Apply perturbation bias correction: specifies whether to apply the Ryu et al. algorithm, (JHM 2009), to forcing and model states to avoid undesirable biases resulting from perturbations. Acceptable values are:

Perturbations restart output interval: specifies the perturbations restart output writing interval.

See Section Defining a time interval for a description of how to specify a time interval.

Perturbations restart filename: specifies the name of the restart file, which is used to initialize perturbation settings if a cold start option is not employed.

Forcing perturbation algorithm: specifies the algorithm for perturbing the forcing variables. Acceptable values are:

Forcing perturbation frequency: specifies the forcing perturbation interval.

See Section Defining a time interval for a description of how to specify a time interval.

Forcing attributes file: ASCII file that specifies the attributes of the forcing (for perturbations) A sample file is shown below, which lists 3 forcing variables. For each variable, the name of the variable is specified first, followed by the min and max values in the next line. This is repeated for each additional variable.

#varmin varmax
Incident Shortwave Radiation Level 001
0.0 1300.0
Incident Longwave Radiation Level 001
-50.0 800.0
Rainfall Rate Level 001
0.0 0.001

Forcing perturbation attributes file: ASCII file that specifies the attributes of the forcing perturbations. A sample file is shown below, which lists 3 forcing variables. There are three lines of specifications for each variable. The first line specifies the name of the variable. The second line specifies the perturbation type (0-additive, 1-multiplicative) and the perturbation type for standard deviation (0-additive, 1-multiplicative). The third line specifies the following values in that order: standard deviation of perturbations, coefficient of standard deviation (if perturbation type for standard deviation is 1),standard normal max, whether to enable zero mean in perturbations, temporal correlation scale (in seconds), x and y -correlations and finally the cross correlations with other variables.

#ptype std std_max zeromean tcorr xcorr ycorr ccorr
Incident Shortwave Radiation Level 001
1 0
0.50 2.5 1 86400 0 0 1.0 -0.5 -0.8
Incident Longwave Radiation Level 001
0 1
50.0 0.2 2.5 1 86400 0 0 -0.5 1.0 0.5
Rainfall Rate Level 001
1 0
0.50 2.5 1 86400 0 0 0.8 0.5 1.0

State perturbation algorithm: specifies the algorithm for perturbing the state prognostic variables. Acceptable values are:

State perturbation frequency: specifies the prognostic variable perturbation interval.

See Section Defining a time interval for a description of how to specify a time interval.

State attributes file: ASCII file that specifies the attributes of the prognostic variables. A sample file is shown below, which lists 2 model state variables. For each variable, the name of the variable is specified first, followed by the min and max values in the next line. This is repeated for each additional variable.

#name varmin varmax
SWE
0.0 100.0
Snowdepth
0.0 100.0

State perturbation attributes file: ASCII file that specifies the attributes of the prognostic variable perturbations. A sample file is provided below, which follows the same format as that of the forcing perturbations attributes file:

#perttype std std_max zeromean tcorr xcorr ycorr ccorr
SWE
1 0
0.01 2.5 1 10800 0 0 1.0 0.9
Snowdepth
1 0
0.02 2.5 1 10800 0 0 0.9 1.0

Observation perturbation algorithm: specifies the algorithm for perturbing the observations. Acceptable values are:

Observation perturbation frequency: specifies the observation perturbation interval.

See Section Defining a time interval for a description of how to specify a time interval.

Observation attributes file: ASCII file that specifies the attributes of the observation variables. A sample file is provided below, which follows the same format as that of the forcing attributes file and state attributes file.

#error rate varmin varmax
ANSA SWE
10.0 0.01 500

Observation perturbation attributes file: ASCII file that specifies the attributes of the observation variable perturbations. A sample file is provided below, which follows the same format as that of the forcing perturbations attributes file:

#perttype std std_max zeromean tcorr xcorr ycorr ccorr
ANSA SWE
0 10 2.5 1 10800 0 0 1

IMS data directory: specifies the location of the IMS data.