Skip to main content

TerrainBento suite of landscape evolution models

Project description

Thing Badge
CI Status Build Status Build status
Coverage Coverage Status
Docs Documentation Status
License License: MIT
Health Code Health Codacy Badge
Style Code style: black
Conda Recipe Conda Recipe
Downloads Conda Downloads
Version Conda Version
Platforms Conda Platforms
Binder Binder


A modular landscape evolution modeling package built on top of the Landlab Toolkit.

terrainbento"s User Manual is located at our Read The Docs page.

We recommend that you start with a set of Jupyter notebooks Binder that introduce terrainbento and the model description paper Barnhart et al. (2019). The link above goes to a Binder instance, if you want the notebooks themselves clone the repo and navigate to the directory notebooks.

A quick example

The following is all the code needed to run the Basic model. There are a few different options available to create a model, here we will create one from a file-like object. The string will contain the same information as a YAML style input file that specifies the model construction and run.

from terrainbento import Basic

params = {
    # create the Clock.
    "clock": {"start": 0,
              "step": 10,
              "stop": 1e5},

    # Create the Grid
    "grid": {
        "RasterModelGrid": [
            (200, 320),
                "xy_spacing": 10
                "fields": {
                    "node": {
                        "topographic__elevation": {
                            "random": [{
                                "where": "CORE_NODE"

    # Set up Boundary Handlers
    "boundary_handlers":{"NotCoreNodeBaselevelHandler": {"modify_core_nodes": True,
                                                         "lowering_rate": -0.001}},
    # Parameters that control output.
    "output_interval": 1e3,
    "save_first_timestep": True,

    # Parameters that control process and rates.
    "water_erodibility" : 0.001,
    "m_sp" : 0.5,
    "n_sp" : 1.0,
    "regolith_transport_parameter" : 0.2,           

model = Basic.from_dict(params)

Next we make an image for each output interval.

from landlab import imshow_grid

filenames = []
ds = model.to_xarray_dataset()
for i in range(ds.topographic__elevation.shape[0]):
    filename = "temp_output."+str(i)+".png"
    imshow_grid(model.grid, ds.topographic__elevation.values[i, :, :], cmap="viridis", limits=(0, 12), output=filename)

Finally we compile the images into a gif.

import os
import imageio
with imageio.get_writer("terrainbento_example.gif", mode="I") as writer:
    for filename in filenames:
        image = imageio.imread(filename)

Example terrainbento run

Installation instructions

Before installing terrainbento you will need a python distribution. We recommend that you use the Anaconda python distribution. Unless you have a specific reason to want Python 2.7 we strongly suggest that you install Python 3.7 (or the current 3.* version provided by Anaconda).

To install the release version of terrainbento (this is probably what you want) we support conda and pip package management.

Using conda

Open a terminal and execute the following:

conda config --add channels conda-forge
conda install terrainbento

Using pip

Open a terminal and execute the following:

pip install terrainbento

From source code

To install the terrainbento source code version of terrainbento we recommend creating a conda environment for terrainbento.

git clone
cd terrainbento
cconda env create -f environment-dev.yml
conda activate terrainbento-dev
python install

A note to developers

If you plan to develop with terrainbento, please fork terrainbento, clone the forked repository, and replace python install with python develop. If you have any questions, please contact us by making an Issue.

How to cite

Barnhart, K. R., Glade, R. C., Shobe, C. M., and Tucker, G. E.: Terrainbento 1.0: a Python package for multi-model analysis in long-term drainage basin evolution, Geosci. Model Dev., 12, 1267-1297,, 2019.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

terrainbento-2.0.0-py3-none-any.whl (251.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page