landlab / tutorials

Landlab tutorials

Landlab

What does Landlab do?

Landlab is an open-source Python-language package for numerical modeling of Earth surface dynamics. It contains

• A gridding engine which represents the model domain. Regular and irregular grids are supported.
• A library of process components, each of which represents a physical process (e.g., generation of rain, erosion by flowing water). These components have a common interface and can be combined based on a user's needs.
• Utilities that support general numerical methods, file input/output, and visualization.

In addition Landlab contains a set of Jupyter notebook tutorials providing an introduction to core concepts and examples of use.

Landlab was designed for disciplines that quantify Earth surface dynamics such as geomorphology, hydrology, glaciology, and stratigraphy. It can also be used in related fields. Scientists who use this type of model often build their own unique model from the ground up, re-coding the basic building blocks of their landscape model rather than taking advantage of codes that have already been written. Landlab saves practitioners from the need for this kind of re-invention by providing standardized components that they can re-use.

Watch the webinar Landlab Toolkit Overview at CSDMS to learn more.

---

Read the documentation on ReadTheDocs!

---

Installation

To install the latest release of landlab using pip, simply run the following in your terminal of choice:

$ pip install landlab

For a full description of how to install Landlab, including using mamba/conda, please see the documentation for our installation instructions.

Source code

If you would like to modify or contribute code to Landlab or use the very latest development version, please see the documentation that describes how to install landlab from source.

Are there any examples of using Landlab I can look at?

The Landlab package contains a directory, landlab/notebooks, with Jupyter Notebooks describing core concepts and giving examples of using components. The file landlab/notebooks/welcome.ipynb provides a table of contents to the notebooks and is the recommended starting place. Additionally, there are a set of notebooks curated to teach physical processes located in the directory landlab/notebooks/teaching.

Run on Binder

To launch an instance of Binder and explore the notebooks click here.

To launch a Binder instance that goes straight to the teaching notebooks click here.

Run on EarthscapeHub

The Landlab notebooks can also be run on EarthscapeHub. Visit this link to learn how to sign up for a free account. Explore the example notebooks on the lab or jupyter Hub instance. Or, use the teaching notebooks on the lab or jupyter Hub instance. Be sure to run all notebooks with the CSDMS kernel.

License

landlab is licensed under the MIT License.

Citing Landlab

If you use any portion of Landlab, please see the documentation for our citation guidelines.

Contact

The recommended way to contact the Landlab team is with a GitHub Issue.

• Bug reports: Please make an Issue describing the bug so we can address it, or work with you to address it. Please try to provide a minimal, reproducible example.
• Documentation: If something in our documentation is not clear to you, please make an issue describing the what isn't clear. Someone will tag the most appropriate member of the core Landlab team. We will work to clarify your question and revise the documentation so that it is clear for the next user.

Keep in touch with the latest landlab news by following us on Twitter.

During workshops and clinics, we sometimes use the Landlab Slack channel.

tutorials's Issues

Tests fail but Travis Reports a pass

For example this build: https://travis-ci.org/landlab/tutorials/jobs/430344073

Update all tutorial's to point to tutorial page on RTFD instead of the wiki

As part of the LL2.0 update of the tutorials (to occur after @gregtucker 's marathon updating of the tutorials 🏃 !), we will need to remove the references to the wiki

Most of them contain the following text:

For more Landlab tutorials, click here: https://github.com/landlab/landlab/wiki/Tutorials

and this points to the wiki. This URL will need to change to the url on RTFD for the tutorials.

We will also want to make sure that all links between notebooks are relative (e.g., don't reference binder, or nbviewer, or local...) which will mean they will work everywhere.

Similar to @gregtucker 's current 1.x best practices improvements, this can be a pre 2.0 improvement.

Thought from B. Campforts during LL paper review

A very small suggestion would be to add a link to the coupled_params_storms.txt file in the ‘Getting to know the Landlab component library’ tutorial on https://nbviewer.jupyter.org/github/landlab/tutorials/blob/master/component_tutorial/component_tutorial.ipynb, similar to the link given for the coupled_params.txt file.

clarify Part 3 example in Lithology tutorial

This is really just a suggestion, but I spent a while trying to understand the use of the rock_id keyword in lith2.run_one_step(). While it may seem repetitive, I think it will help the reader to follow if you add comments before the run_one_step() calls in Part 3. Of course, I had read in the text above that you were doing this because LinearDiffuser() may deposit material. But, by the time I got down to the code I had forgotten this and spent about 15 min in the docs sorting it out (then ultimately remembering I had seen that above). I think it will save folks a bit of time if you: 1) make an explicit statement in the text at the start of part 3 that you have to use rock_id in run_one_step any time material is deposited. 2) Insert comments above the three calls to run_one_step that remind the reader why that parameter is there, as well as why it is changing from 0 to 1 to 0. In general, clarity would probably be improved by scattering more comments throughout the tutorial code.

Better tests for next

Rather than testing PRs that want to merge into next against the conda install (which we should expect to break). We should test these PRs against the developer version master branch.

Travis test fails

The travis tests seem to be generating

ImportError: no module named landlab

@mcflugen any ideas?

user warning in flexure tutorial

at step 3 get this user warning:

/Users/jennyknuth/anaconda/lib/python2.7/site-packages/matplotlib/init.py:1350: UserWarning: This call to matplotlib.use() has no effect
because the backend has already been chosen;
matplotlib.use() must be called before pylab, matplotlib.pyplot,
or matplotlib.backends is imported for the first time.

warnings.warn(_use_error_msg)

Link to `landlab-fault-scarp.py` is broken

The link to landlab-fault-scarp.py in this tutorial is broken and needs to be removed or replaced. Line 401.

Minor inconvenience but if anybody knows where this file went (I tried searching the landlab repos), do throw it into this tutorial to fix this.

Components tutorial needs to be updated in line with reverting channel profiler

See landlab/landlab#695

Update tutorials for Landlab 2.0

Prior to the release of Landlab 2.0, we need to:

• update tutorial notebooks for current (1.x) usage where needed
• update tutorials to work with 2.0 where needed
• verify each tutorial (either it will work with 2.0 or has a version ready for 2.0)

wrong link to Lithology docs

In the Lithology and LithoLayers tutorial the link to the full Litholayers documentation is incorrect. It points to layers.litholayers. I think it should be components.litholayers.

DataRecord Tutorial error raised by xarray module when passing axis to Dataset through the calc_aggregate_value method

In the DataRecord Tutorial, an error is raised in cell 16, when running:

mean_size = dr_2.calc_aggregate_value(func=np.mean,
data_variable='boulder_size')

Error message from the xarray module:
passing 'axis' to Dataset reduce methods is ambiguous. Please use 'dim' instead.

Is there any way to produce less channels?

I created a 500*1000 grid. After evolving over thousands of years, almost 30 channels formed. But the more rivers there are, the easier it is to river capture. So I want tu focus on just about 5 rivers. Is there any way to control the number of rivers?

future warning in component tutorial

https://nbviewer.jupyter.org/github/landlab/tutorials/blob/master/component_tutorial/component_tutorial.ipynb

at step 12, get the following warning:
//anaconda/lib/python2.7/site-packages/matplotlib/collections.py:590: FutureWarning: elementwise comparison failed; returning scalar instead, but in the future will perform elementwise comparison
if self._edgecolors == str('face'):

CI broken

Around the time 3.8 was released, everything started breaking.

I'm on vacation, so I'm not going to deal with this, but the issue serves to put a pin in it.

.travis.yml has a duplicate mkdir -p $MPLCONFIGDIR

This occurred because @mcflugen and I were working on fixing the .travis.yml file at the same time and our changes were not in conflict with one another.

MatplotlibDeprecationWarning on gca() in the FlowDirector and FlowAccumulator nbks

The function surf_plot() in the three notebooks compare_FlowDirectors, the_FlowAccumulator, the_FlowDirectors, instantiate the axes of a figure by the call
ax = fig.gca(projection='3d').

This call raises the following warning:
/srv/conda/envs/notebook/lib/python3.7/site-packages/ipykernel_launcher.py:26: MatplotlibDeprecationWarning: Calling gca() with keyword arguments was deprecated in Matplotlib 3.4. Starting two minor releases later, gca() will take no keyword arguments. The gca() function should only be used to get the current axes, or if no axes exist, create new axes with default keyword arguments. To create a new axes with non-default arguments, use plt.axes() or plt.subplot().

travis test fails

Some test are failing for #18. The error looks like: python[version='>=3.6,<3.7.0a0'].

@mcflugen, is this a similar issue that was resolved in landlab/landlab#633?

Binder: dask module absent, which make lithology_and_litholayers nbk fail

When I try to run the landlab notebook lithology_and_litholayers
(https://hub.gke2.mybinder.org/user/landlab-landlab-2wyz3sai/notebooks/notebooks/tutorials/lithology/lithology_and_litholayers.ipynb) on binder, an error is raised:

ModuleNotFoundError Traceback (most recent call last)
/tmp/ipykernel_640/3503426862.py in
5 import numpy as np
6 import xarray as xr
----> 7 import dask
8
9 import matplotlib

ModuleNotFoundError: No module named 'dask'

Is there any way to produce less channels?

I created a 500*1000 grid. After evolving over thousands of years, almost 30 channels formed. But the more rivers there are, the easier it is to river capture. So I want tu focus on just about 5 rivers. Is there any way to control the number of rivers?

Tutorial teaches creating blank grid fields

But this seems not to be the preferred approach in polished Landlab components. The tutorial should reflect whichever approach (create a blank field, throw an error, whatever) is preferred.

Update animation tutorial

The animation tutorial seems to be producing blank output in some cases. I recommend modifying it to use MPL's FuncAnimation, which I've had good luck with recently.

Unexpanded and Python script tutorials

In most of the tutorial folders we have three versions of each tutorial. Two are Jupyter notebooks that should be the same except one is unexpanded (ends in _unexpanded.ipynb) and the other expanded. The third is the notebook saved as a .py file.

I propose we get rid of the _unexpanded.ipynb and .py files and just keep a single version of the tutorial in our repository. The main reasons being it's easier to maintain one version and reduces the risk of the three files falling out of sync.

What do folks think?

New notebooks break the CI tests

@ChristinaB - your merge for PR #40 broke the tutorials continuous integration. One of the reasons for this is that the notebooks rely on geopandas but nowhere is the dependency described (e.g. in a requirements.txt file). Since the builds fail on that line, its hard to tell if that is the only place there is a problem or if there are others (e.g. if these notebooks take a long time to run, the tests will time out and fail).

I've assigned @saisiddu only because I can't seem to assign @ChristinaB

Is topographic__gradient really an input field in making_components.ipynb?

In the component making tutorial, topographic__gradient doesn’t appear to be an input field. I say that because:

1. It’s created if it’s missing.
2. Even if it isn’t missing, it automatically gets immediately overwritten during instantiation with a new set of values.

That sounds like an output field to me, not an input field. It might be ambiguous if there was some testing performed to use the values if provided but to calculate gradients if not, but that's not happening. Ergo, this is a straight-up output field as written.

Probably needs to be fixed by @gregtucker, as he wrote this and it feels a bit cheeky just to change.

v2_dev ci

@mcflugen I'm having an issue with checking out the landlab/landlab/v2_dev branch...

See for example: https://travis-ci.org/landlab/tutorials/jobs/609818281#L389

Any recommendations?

Until I get this branch functioning... I'm just pushing directly to it. So feel free to do that if you see an easy fix.

Unable to import FlowAccumulator

It appears that the flow direction and accumulation tutorials are not working with the latest landlab release. The error that I get is,

>>> from landlab.components import FlowAccumulator 
ImportError: cannot import name FlowAccumulator

I think the problem is probably just that the tutorials under flow_direction_and_accumulation were written for the development version of landlab that's in master - not the latest release (v1.0.3). I propose we move these tutorials to a new branch (and remove them from master) until we have a new release that fixes this problem.

All the tutorials on the master branch should work with the latest released version of landlab. (at least that's what I remember us agreeing to)

Or we could do something like we do with landlab and have a release branch with tags that point to the version of landlab that the tutorials work with and have master work with the development version of landlab. But that that's another issue.

Component tutorial needs to be updated with FlowAccumulator instead of FlowRouter

also, the Landlab logo goes missing if you copy the notebook (unlike the fault scarp tutorial)

Adding a note to install landlab_dev wiki

I recently did a re-install of anaconda and the landlab development code as per the instructions on:
https://github.com/landlab/landlab/wiki/Installing-Landlab-from-source-code-(%22developer-install%22)

It took a hint from @kbarnhart, though, to realize that I needed to run conda install spyder (and then spyder) while in the landlab_dev environment in order run an instance of spyder that can access landlab. It might be nice to include a more generalized note about this on the landlab source code wiki page.

Running tests locally

I don't appear to be able to run the tests locally using the unix script (or the python script come to that, as the error below indicates). The shell script throws:

Traceback (most recent call last):
Traceback (most recent call last):
  File "./run_notebook.py", line 14, in <module>
  File "./run_notebook.py", line 14, in <module>
    from scripting.unix import system, check_output
    from scripting.unix import system, check_output
ImportError: ImportErrorNo module named scripting.unix: 
No module named scripting.unix

I tried conda install scripting, but it claimed such a package doesn't exist.

What's up here? I should note I'm running zsh, not bash, if that's relevant.