README.rst

Landlab

What does Landlab do?

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.

How do I install Landlab?

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.

Landlab 2.0

In April 2020 Landlab switched to version 2.0. Landlab dropped support of Python 2.7 with this transition.

Supported Python Versions

Landlab supports Python versions >= 3.6. Landlab distributes pre-packaged binaries through conda-forge and PyPI for versions 3.6 through 3.9.

Conda Environment with Pre-packaged Binary Distribution

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.yml

Then activate the environment and open the welcome notebook execute the following:

$ conda activate landlab_notebooks
$ jupyter notebook notebooks/welcome.ipynb

Developer Installation

Individuals 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 create -n landlab python
$ conda install -n landlab --file=requirements.txt
$ conda activate landlab
$ pip install -e .

This will install landlab and it's dependencies. You may want to install some additional utilities used for developing, testing, and running landlab notebooks. This can be done with the following:

$ conda install --file=requirements-dev.txt
$ conda install --file=requirements-testing.txt
$ conda install --file=requirements-notebooks.txt

How do I verify I've installed Landlab correctly?

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.

What are Landlab's dependencies?

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.

How do I learn more about Landlab?

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.

Are there any examples of using Landlab I can look at?

The Landlab package contains a directory, landlab/notebooks, with Jupyter Notebooks describing core concepts and giving examples of using components. The file landlab/notebooks/welcome.ipynb provides a table of contents to the notebooks and is the recommended starting place. Additionally, there are a set of notebooks curated to teach physical processes located in the directory landlab/notebooks/teaching.

Run on Binder

To launch an instance of Binder and explore the notebooks click here.

To launch a Binder instance that goes straight to the teaching notebooks click here.

Run on the CSDMS JupyterHub

The Landlab notebooks can also be run on the CSDMS JupyterHub. To sign up for a free account, visit the CSDMS wiki and follow the instructions there. Then, click to explore the example notebooks, or to go straight to the teaching notebooks.

What License does Landlab use?

MIT (see the file LICENSE.txt)

I used Landlab and want to cite it. How do I do this correctly?

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.

I think I found a bug. What should I do?

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.

I found something in the documentation that isn't clear. What should I do?

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.

I'm interested in contributing to Landlab. Where do I get started?

Thank you for your interest! Refer to CONTRIBUTING.md and this page in the documentation that describes contribution guidelines.

How is the Landlab package structured?

The following page in the documentation describes the package structure.

How was Landlab funded?

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).