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.

MIT License

Copyright (c) 2018 TerrainBento

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.