Landlab is an open-source Python-language package for numerical modeling of Earth surface dynamics. It contains
- A gridding engine which represents the model domain. Regular and irregular grids are supported.
- A library of process components, each of which represents a physical process (e.g., generation of rain, erosion by flowing water). These components have a common interface and can be combined based on a user's needs.
- Utilities that support general numerical methods, file input/output, and visualization.
In addition Landlab contains a set of Jupyter notebook tutorials providing an introduction to core concepts and examples of use.
Landlab was designed for disciplines that quantify Earth surface dynamics such as geomorphology, hydrology, glaciology, and stratigraphy. It can also be used in related fields. Scientists who use this type of model often build their own unique model from the ground up, re-coding the basic building blocks of their landscape model rather than taking advantage of codes that have already been written. Landlab saves practitioners from the need for this kind of re-invention by providing standardized components that they can re-use.
Watch the webinar Landlab Toolkit Overview at CSDMS to learn more.
First you'll need a Python distribution and either the conda or pip package manager. If you don't know what you want, we recommend the Anaconda Python distribution.
Two main installation options exist for Landlab. Most people will likely want to install a prepackaged binary. We distribute through both conda-forge and pip.
In April 2020 Landlab switched to version 2.0. Landlab dropped support of Python 2.7 with this transition.
Landlab supports Python versions >= 3.6. Landlab distributes pre-packaged binaries through conda-forge and PyPI for versions 3.6 through 3.9.
To create a conda environment that installs a pre-packaged binary and all the dependencies necessary to run the notebooks, clone the repository, navigate to within the top level directory and use the following command:
$ conda env create --file=environment.ymlThen activate the environment and open the welcome notebook execute the following:
$ conda activate landlab_notebooks
$ jupyter notebook notebooks/welcome.ipynbIndividuals interested in modifying the Landlab source code should follow the developer installation instructions which describe cloning the source code, creating a conda environment for development, compiling, and testing the code.
In short, clone the repository, navigate to the top level directory, and run the following commands:
$ conda env create --file=environment-dev.yml
$ conda activate landlab_dev
$ pip install -e .Landlab uses pytest to discover and run tests. These include docstring tests
located within the core source code (landlab/landlab directory) and unit
tests located within the landlab/tests directory. Presuming you have used a
source code installation with the above conda environment, you will be able to
test your install with
$ pytest
from within the landlab_dev conda environment. Additional instructions,
including how the unit tests directory is structured can be found under the
testing section of the landlab documentation.
The core package dependencies are specified by requirements.txt and used
by setup.py. There are some additional dependencies that exist for
running the notebooks or modifying the source code and testing.
Details of how we structure our dependencies can be found under the dependencies section of the landlab documentation.
Our documentation is hosted on ReadTheDocs at https://landlab.readthedocs.io/. This includes a User Guide and API reference.
The following paper describes the design of Landlab.
Hobley, D. E. J., Adams, J. M., Nudurupati, S. S., Hutton, E. W. H., Gasparini, N. M., Istanbulluoglu, E. and Tucker, G. E., 2017, Creative computing with Landlab: an open-source toolkit for building, coupling, and exploring two-dimensional numerical models of Earth-surface dynamics, Earth Surface Dynamics, 5, p 21-46, 10.5194/esurf-5-21-2017.
The Landlab package contains a directory at landlab/notebooks which contains
Jupyter notebooks describe core concepts and give examples of using components.
The file landlab/notebooks/welcome.ipynb provides a table of contents to
the notebooks and is the recommended starting place. To launch an instance of
Binder and explore the notebooks click here.
In addition there are a set of notebooks curated to teach physical processes
located in the directory landlab/notebooks/teaching.
To launch an Binder instance that goes straight to these teaching notebooks click here.
MIT (see the file LICENSE.txt)
The following references refer to the entire Landlab package.
Hobley, D. E. J., Adams, J. M., Nudurupati, S. S., Hutton, E. W. H., Gasparini, N. M., Istanbulluoglu, E. and Tucker, G. E., 2017, Creative computing with Landlab: an open-source toolkit for building, coupling, and exploring two-dimensional numerical models of Earth-surface dynamics, Earth Surface Dynamics, 5, p 21-46, 10.5194/esurf-5-21-2017.
Barnhart, K. R., Hutton, E. W. H., Tucker, G. E., Gasparini, N. M., Istanbulluoglu, E., Hobley, D. E. J., Lyons, N. J., Mouchene, M., Nudurupati, S. S., Adams, J. M., and Bandaragoda, C.: Short communication: Landlab v2.0: A software package for Earth surface dynamics, Earth Surf. Dynam. Discuss., https://doi.org/10.5194/esurf-2020-12, in review, 2020.
BibTeX format:
@article{Hobley2017,
Author = {Hobley, D. E. J. and Adams, J. M. and
Nudurupati, S. S. and Hutton, E. W. H.
and Gasparini, N. M. and Istanbulluoglu,
E. and Tucker, G. E.},
Journal = {Earth Surface Dynamics},
Year = {2017},
Title = {Creative computing with Landlab: an open-source
toolkit for building, coupling, and exploring
two-dimensional numerical models of
Earth-surface dynamics},
Number = {5},
Pages = {21-46},
Doi = {10.5194/esurf-5-21-2017}}
@article{barnhart2020short,
Author = {Barnhart, K. R. and Hutton, E. W. H. and
Tucker, G. E. and Gasparini, N. M. and
Istanbulluoglu, E. and Hobley, D. E. J. and
Lyons, N. J. and Mouchene, M. and Nudurupati,
S. S. and Adams, J. M. and Bandaragoda, C.},
Title = {Short communication: Landlab v2.0: A software
package for Earth surface dynamics},
Journal = {Earth Surface Dynamics Discussions},
Volume = {2020},
Year = {2020},
Pages = {1--25},
Url = {https://www.earth-surf-dynam-discuss.net/esurf-2020-12/},
Doi = {10.5194/esurf-2020-12}
}
In addition, depending on what parts of Landlab you use, you may need to cite component-specific. Refer to the References section of each component and this page which discusses the Landlab Citation Registry tool.
Please make an Issue describing the bug so we can address it, or work with you to address it. Please try to provide a minimal, reproducible example.
Please make an Issue describing the what isn't clear to you. Someone will tag the most appropriate member of the core Landlab team. We will work to clarify your question and revise the documentation so that it is clear for the next user.
Thank you for your interest! Refer to CONTRIBUTING.md and
this
page in the documentation that describes contribution guidelines.
The following page in the documentation describes the package structure.
Landlab is funded by the US National Science Foundation. It has been supported by the following grants:
- A Collaborative NSF SI2-SSE proposal to University of Colorado (Greg Tucker, 1147454), and the University of Washington (Erkan Istanbulluoglu, 1148305)
- A Collaborative NSF SI2-SSI proposal to University of Colorado (Greg Tucker and Dan Hobley, 1450409), Tulane University (Nicole Gasparini, 1450338), and the University of Washington (Erkan Istanbulluoglu, 1450412).
- A NSF EAR Postdoctoral Fellowship to Katy Barnhart (1725774).