| Thing | Badge |
| :---: | :---: |
| CI Status | [](https://github.com/TerrainBento/terrainbento/actions/workflows/test.yml) |
| Coverage | [](https://coveralls.io/github/TerrainBento/terrainbento?branch=master) |
| Docs | [](http://terrainbento.readthedocs.io/en/latest/?badge=latest) |
| Notebooks | [](https://github.com/TerrainBento/terrainbento/actions/workflows/test-notebooks.yml) |
| License | [](https://opensource.org/licenses/MIT) |
| Style | [](https://github.com/ambv/black) |
| DOI | [](https://zenodo.org/badge/latestdoi/123941145) |
| Conda Recipe | [](https://anaconda.org/conda-forge/terrainbento) |
| Downloads | [](https://anaconda.org/conda-forge/terrainbento) |
| Version | [](https://anaconda.org/conda-forge/terrainbento) |
| Platforms | [](https://anaconda.org/conda-forge/terrainbento) |
| Binder | [](https://mybinder.org/v2/gh/TerrainBento/terrainbento/master?filepath=notebooks%2FWelcome_to_TerrainBento.ipynb) |
# terrainbento
A modular landscape evolution modeling package built on top of the [Landlab Toolkit](http://landlab.github.io).
terrainbento"s User Manual is located at our [Read The Docs page](http://terrainbento.readthedocs.io/).
We recommend that you start with a set of Jupyter notebooks [](https://mybinder.org/v2/gh/TerrainBento/terrainbento/master?filepath=notebooks%2FWelcome_to_TerrainBento.ipynb) that introduce terrainbento and the model description paper [Barnhart et al. (2019)](https://doi.org/10.5194/gmd-12-1267-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.
```python
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.
```python
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.
```python
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](https://www.anaconda.com/download/).
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:
```bash
pip install -e .
```
We use [nox](https://nox.thea.codes/en/stable/) for most project tasks in terrainbento.
Install nox and list the available sessions with:
```bash
pip install -e ".[dev]"
nox --list
```
To use nox to run the terrainbento tests, for example, call the _test_ session:
```bash
nox -s test
```
If you have any questions, please contact us by making an [issue](https://github.com/TerrainBento/terrainbento/issues).
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "terrainbento",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "earth science, landlab, landscape evolution modeling, numerical modeling",
"author": "Katy Barnhart",
"author_email": "barnhark@colorado.edu",
"download_url": "https://files.pythonhosted.org/packages/b8/1b/14a2b74924c2afc0efc6848b0c50ad4e033b909df01e2669d438d2d7b515/terrainbento-2.0.1.tar.gz",
"platform": null,
"description": "| Thing | Badge |\n| :---: | :---: |\n| CI Status | [](https://github.com/TerrainBento/terrainbento/actions/workflows/test.yml) |\n| Coverage | [](https://coveralls.io/github/TerrainBento/terrainbento?branch=master) |\n| Docs | [](http://terrainbento.readthedocs.io/en/latest/?badge=latest) |\n| Notebooks | [](https://github.com/TerrainBento/terrainbento/actions/workflows/test-notebooks.yml) |\n| License | [](https://opensource.org/licenses/MIT) |\n| Style | [](https://github.com/ambv/black) |\n| DOI | [](https://zenodo.org/badge/latestdoi/123941145) |\n| Conda Recipe | [](https://anaconda.org/conda-forge/terrainbento) |\n| Downloads | [](https://anaconda.org/conda-forge/terrainbento) |\n| Version | [](https://anaconda.org/conda-forge/terrainbento) |\n| Platforms | [](https://anaconda.org/conda-forge/terrainbento) |\n| Binder | [](https://mybinder.org/v2/gh/TerrainBento/terrainbento/master?filepath=notebooks%2FWelcome_to_TerrainBento.ipynb) |\n\n# terrainbento\n\nA modular landscape evolution modeling package built on top of the [Landlab Toolkit](http://landlab.github.io).\n\nterrainbento\"s User Manual is located at our [Read The Docs page](http://terrainbento.readthedocs.io/).\n\nWe recommend that you start with a set of Jupyter notebooks [](https://mybinder.org/v2/gh/TerrainBento/terrainbento/master?filepath=notebooks%2FWelcome_to_TerrainBento.ipynb) that introduce terrainbento and the model description paper [Barnhart et al. (2019)](https://doi.org/10.5194/gmd-12-1267-2019). The link above goes to a Binder instance, if you want the notebooks themselves clone the repo and navigate to the directory `notebooks`.\n\n\n## A quick example\n\nThe following is all the code needed to run the Basic model. There are a few\ndifferent options available to create a model, here we will create one from a\nfile-like object. The string will contain the same information as a YAML style\ninput file that specifies the model construction and run.\n\n```python\nfrom terrainbento import Basic\n\nparams = {\n # create the Clock.\n \"clock\": {\"start\": 0,\n \"step\": 10,\n \"stop\": 1e5},\n\n # Create the Grid\n \"grid\": {\n \"RasterModelGrid\": [\n (200, 320),\n {\n \"xy_spacing\": 10\n },\n {\n \"fields\": {\n \"node\": {\n \"topographic__elevation\": {\n \"random\": [{\n \"where\": \"CORE_NODE\"\n }]\n }\n }\n }\n },\n ]\n },\n\n # Set up Boundary Handlers\n \"boundary_handlers\":{\"NotCoreNodeBaselevelHandler\": {\"modify_core_nodes\": True,\n \"lowering_rate\": -0.001}},\n # Parameters that control output.\n \"output_interval\": 1e3,\n \"save_first_timestep\": True,\n \"fields\":[\"topographic__elevation\"],\n\n # Parameters that control process and rates.\n \"water_erodibility\" : 0.001,\n \"m_sp\" : 0.5,\n \"n_sp\" : 1.0,\n \"regolith_transport_parameter\" : 0.2,\n }\n\nmodel = Basic.from_dict(params)\nmodel.run()\n```\n\nNext we make an image for each output interval.\n\n```python\nfrom landlab import imshow_grid\n\nfilenames = []\nds = model.to_xarray_dataset()\nfor i in range(ds.topographic__elevation.shape[0]):\n filename = \"temp_output.\"+str(i)+\".png\"\n imshow_grid(model.grid, ds.topographic__elevation.values[i, :, :], cmap=\"viridis\", limits=(0, 12), output=filename)\n filenames.append(filename)\nmodel.remove_output_netcdfs()\n\n```\n\nFinally we compile the images into a gif.\n\n```python\nimport os\nimport imageio\nwith imageio.get_writer(\"terrainbento_example.gif\", mode=\"I\") as writer:\n for filename in filenames:\n image = imageio.imread(filename)\n writer.append_data(image)\n os.remove(filename)\n```\n\n\n\n## Installation instructions\n\nBefore installing terrainbento you will need a Python distribution. We recommend that you use the [Anaconda python distribution](https://www.anaconda.com/download/).\nWe strongly suggest that you install the current 3.* version of Python.\n\nTo install the release version of terrainbento (this is probably what you want) we support conda and pip package management.\n\n### Using conda\nOpen a terminal and execute the following:\n\n```\nconda config --add channels conda-forge\nconda install terrainbento\n```\n\n### Using pip\nOpen a terminal and execute the following:\n\n```\npip install terrainbento\n```\n\n### From source code\n\nTo install the terrainbento source code version of terrainbento we recommend creating a conda environment for terrainbento.\n\n```\ngit clone https://github.com/TerrainBento/terrainbento.git\ncd terrainbento\nconda env create -f environment-dev.yml\nconda activate terrainbento_dev\npip install .\n```\n\n#### Notes for developers\n\nIf you plan to develop with terrainbento, please fork terrainbento, clone the forked repository, and create an editable install with:\n```bash\npip install -e .\n```\n\nWe use [nox](https://nox.thea.codes/en/stable/) for most project tasks in terrainbento.\nInstall nox and list the available sessions with:\n```bash\npip install -e \".[dev]\"\nnox --list\n```\nTo use nox to run the terrainbento tests, for example, call the _test_ session:\n```bash\nnox -s test\n```\n\nIf you have any questions, please contact us by making an [issue](https://github.com/TerrainBento/terrainbento/issues).\n\n\n## How to cite\n\nBarnhart, 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.\n\nMIT License\n\nCopyright (c) 2018 TerrainBento\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "TerrainBento suite of landscape evolution models",
"version": "2.0.1",
"project_urls": {
"documentation": "https://terrainbento.readthedocs.io",
"repository": "https://github.com/TerrainBento/terrainbento"
},
"split_keywords": [
"earth science",
" landlab",
" landscape evolution modeling",
" numerical modeling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d54d1041da7bdff5092c295df7e6b411069c1e31f18ce210926d92a23d9a31ae",
"md5": "f936bf2036ee4777150851ae1279767a",
"sha256": "5c92ca8101daf2bbd331e2553bc442bbfad86bc6aa5123cbe9816f024d97dd92"
},
"downloads": -1,
"filename": "terrainbento-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f936bf2036ee4777150851ae1279767a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 156984,
"upload_time": "2024-09-11T19:20:06",
"upload_time_iso_8601": "2024-09-11T19:20:06.793490Z",
"url": "https://files.pythonhosted.org/packages/d5/4d/1041da7bdff5092c295df7e6b411069c1e31f18ce210926d92a23d9a31ae/terrainbento-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b81b14a2b74924c2afc0efc6848b0c50ad4e033b909df01e2669d438d2d7b515",
"md5": "82a8c3eeda661e72769bc04da2f0c3ee",
"sha256": "7a93d3c15f423dd68aaaa292d5178e917e13f10412c1eef94e7c79a8baddad32"
},
"downloads": -1,
"filename": "terrainbento-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "82a8c3eeda661e72769bc04da2f0c3ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 173400,
"upload_time": "2024-09-11T19:20:08",
"upload_time_iso_8601": "2024-09-11T19:20:08.561791Z",
"url": "https://files.pythonhosted.org/packages/b8/1b/14a2b74924c2afc0efc6848b0c50ad4e033b909df01e2669d438d2d7b515/terrainbento-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 19:20:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TerrainBento",
"github_project": "terrainbento",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "dask",
"specs": []
},
{
"name": "landlab",
"specs": [
[
">=",
"2.6"
]
]
},
{
"name": "numpy",
"specs": [
[
"<",
"2"
],
[
">=",
"1.20"
]
]
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "xarray",
"specs": [
[
">=",
"0.16"
]
]
}
],
"lcname": "terrainbento"
}
JSON
