Thing	Badge
CI Status
Coverage
Docs
Notebooks
License
Style
DOI
Conda Recipe
Downloads
Version
Platforms
Binder

terrainbento

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 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,
    "fields":["topographic__elevation"],

    # 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)
model.run()

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)
    filenames.append(filename)
model.remove_output_netcdfs()

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)
        writer.append_data(image)
        os.remove(filename)

Installation instructions

Before installing terrainbento you will need a Python distribution. We recommend that you use the Anaconda python distribution. We strongly suggest that you install the current 3.* version of Python.

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 https://github.com/TerrainBento/terrainbento.git
cd terrainbento
conda env create -f environment-dev.yml
conda activate terrainbento_dev
pip install .

Notes for developers

If you plan to develop with terrainbento, please fork terrainbento, clone the forked repository, and create an editable install with:

pip install -e .

We use nox for most project tasks in terrainbento. Install nox and list the available sessions with:

pip install -e ".[dev]"
nox --list

To use nox to run the terrainbento tests, for example, call the test session:

nox -s test

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, https://doi.org/10.5194/gmd-12-1267-2019, 2019.