terrainbento 1.1b4

TerrainBento suite of landscape evolution models

Thing	Badge
CI Status
Coverage
Docs
License
Health
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. 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 https://github.com/TerrainBento/terrainbento.git
cd terrainbento
cconda env create -f environment-dev.yml
conda activate terrainbento-dev
python setup.py install

A note to developers

If you plan to develop with terrainbento, please fork terrainbento, clone the forked repository, and replace python setup.py install with python setup.py 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, https://doi.org/10.5194/gmd-12-1267-2019, 2019.