ARCHIVED CONTENT: In December 2020, the CZO program was succeeded by the Critical Zone Collaborative Network (CZ Net) ×


Jump to Description ▼

Logo for the Landlab project.

Landlab: A Python-language library for 2D numerical modeling

Landlab enables researchers to efficiently create and/or combine 2D numerical models.

Model Category: Numerical

Image: Logo for the Landlab project.

Dan Hobley - CIRES/CU

Eric Hutton - CSDMS/Instaar/CU

Nicole Gasparini - Tulane University

Jordan Adams - Tulane University

Erkan Istanbulluoglu - University of Washington

Sai Siddhartha Nudurupati - University of Washington

Landlab is a Python-language software library that facilitates writing and coupling two-dimensional numerical models, with an emphasis on earth-surface dynamics models. The current prototype version of Landlab (0.1.28) was developed on behalf of CSDMS by a team of Terrestrial Working Group members , with support from NSF’s SI2-SSE program.

The present version of Landlab provides three general capabilities. First, Landlab provides a gridding engine. A model grid is implemented as a data object, which means that a Landlab user can create and configure a grid in just one or a few lines of Python code. Landlab provides several grid types, including raster, hexagonal, Voronoi-Delaunay, and radial. Because the various grid types share the same fundamental data structures, users can change grid types quite easily, without needing substantial changes to their algorithms. A model developer can also attach data fields to the grid to represent state variables and boundary conditions. These fields then become part of the grid object, which makes it easy for individual components to share both the grid and a common set of data.

The grid data structures make it simple to associate state variables either with grid nodes (computational points associated with polygonal cells) or grid links (directed line segments that connect pairs of adjacent nodes). This configuration makes it easy to implement staggered-grid finite-difference and finite-volume schemes. For example, an application that simulates shallow water flow over topography could map scalar quantities (such as water depth) onto nodes, and vector quantities (such as flow velocity) onto links. The gridding engine also provides built-in functions to handle common numerical operations, such as calculation of gradients between pairs of adjacent cells.

A second Landlab capability is the coupling of components. A Landlab component, like a CSDMS component, is a piece of code that models a particular natural process. Landlab provides a simple architecture for coupling components, which share a common grid and its associated data fields. Components can query the grid to determine whether a particular data field (say, water depth at nodes) exists, and if not, create it. To facilitate sharing of data, each data field is given a name, using either CSDMS standard names or shorter variable names that can be mapped to their CSDMS equivalents. A Landlab user can create a coupled model by instantiating two or more components and running them sequentially.

Landlab version 1.24 includes several process components; these include, for example, components that model landscape evolution by soil creep and fluvial erosion, components that model shallow water flow over topography, and components that model soil moisture dynamics. Additional work is now underway to have components automatically inherit a BMI, such that any Landlab component can also function as a CSDMS component.

Finally, Landlab reduces model-development time by providing a set of utility functions to handle common software operations. These include, for example, reading parameter-input data from a formatted text file, reading and writing data to/from netCDF-format files, reading data in from ESRI ASCII files, and plotting user-selected data fields using the Matplotlib plotting library.

There is much more to be done to enhance Landlab’s capabilities, documentation, and scope. Further development will be conducted over five years beginning in August 2015, through support from NSF’s SI2-SSI program. Landlab is publically available through a GitHub repository (, and contributions from the community are highly encouraged.