Add wolf-sheep-soil-creep tutorial (#793)

joargu · web-flow · commit 4ee1b1311d1c · 2026-06-01T12:00:42.000+02:00
diff --git a/changelog-entries/793.md b/changelog-entries/793.md
@@ -0,0 +1 @@
+- Added the `wolf-sheep-soil-creep` tutorial [#793](https://github.com/precice/tutorials/pull/793)
diff --git a/tools/tests/tests.yaml b/tools/tests/tests.yaml
@@ -487,6 +487,16 @@ test_suites:
         reference_result: ./water-hammer/reference-results/fluid1d-left-nutils_fluid3d-right-openfoam.tar.gz
       # More case combinations are possible, but they requite calling set-case.sh
 
+  wolf-sheep-soil-creep:
+    tutorials:
+      - &wolf-sheep-soil-creep_soil-creep-landlab_wolf-sheep-grass-mesa
+        path: wolf-sheep-soil-creep
+        case_combination:
+          - soil-creep-landlab
+          - wolf-sheep-grass-mesa
+        max_time: 20
+        reference_result: ./wolf-sheep-soil-creep/reference-results/soil-creep-landlab_wolf-sheep-grass-mesa.tar.gz
+
 #####################################################################
 ## Test suites referring to the test suites defined above
 
@@ -539,6 +549,7 @@ test_suites:
       - *volume-coupled-diffusion_source-fenics_drain-fenics
       - *volume-coupled-flow_fluid-openfoam_source-nutils
       - *water-hammer_fluid1d-left-nutils_fluid3d-right-openfoam
+      - *wolf-sheep-soil-creep_soil-creep-landlab_wolf-sheep-grass-mesa
 
   # These test suites take longer to run. They are available, but not regularly executed.
   extra:
diff --git a/wolf-sheep-soil-creep/README.md b/wolf-sheep-soil-creep/README.md
@@ -0,0 +1,58 @@
+---
+title: Wolf-sheep-grass model with soil creep
+permalink: tutorials-wolf-sheep-soil-creep.html
+keywords: MESA, Landlab, wolf-sheep-grass, soil creep, ABM, agent-based modeling
+summary: Example of bi-directional ABM-PDE coupling via preCICE.
+---
+
+{% note %}
+Get the [case files of this tutorial](https://github.com/precice/tutorials/tree/develop/wolf-sheep-soil-creep), as continuously rendered here, or see the [latest released version](https://github.com/precice/tutorials/tree/master/wolf-sheep-soil-creep) (if there is already one). Read how in the [tutorials introduction](https://precice.org/tutorials.html).
+{% endnote %}
+
+## Setup
+
+This tutorial is based on Landlab's [Wolf-Sheep-Grass Model with Soil Creep](https://landlab.csdms.io/tutorials/agent_based_modeling/wolf_sheep/wolf_sheep_with_soil_creep.html) example, which couples the [Wolf-Sheep model from Mesa](https://mesa.readthedocs.io/latest/examples/advanced/wolf_sheep.html) with a Landlab soil creep model in a single notebook-based workflow. The [source notebook](https://github.com/landlab/landlab/blob/master/docs/source/tutorials/agent_based_modeling/wolf_sheep/wolf_sheep_with_soil_creep.ipynb) is licensed under [MIT](https://landlab.csdms.io/about/license.html).
+
+The purpose of this tutorial is to demonstrate a simple two-way coupling between an agent-based model (ABM) and a grid-based continuum model via preCICE. The example extends the canonical wolf-sheep-grass ABM with a simple soil-creep feedback on a shared sloping raster grid. When sheep eat grass, the soil beneath the damaged grass becomes more mobile, increasing the local soil transport efficiency and affecting downslope soil transport. The feedback also acts in the other direction: soil thickness affects grass growth by preventing grass from growing where the soil becomes too thin.
+
+In this implementation, the Mesa wolf-sheep-grass model and the Landlab soil creep model are two separate preCICE participants, exchanging grass cover and soil depth during the simulation. The Mesa participant extracts the current grass map from the wolf-sheep-grass model and sends it to the Landlab participant. The Landlab participant uses this grass map to adapt the soil creep coefficient, evolves the soil thickness, and sends the updated soil depth back to the Mesa participant, where it is used to limit grass growth. This example is intentionally simple and should be understood as a demonstration case for coupling ABM and PDE-style models via preCICE, rather than as a physically calibrated landscape evolution model.
+
+## Configuration
+
+preCICE configuration (image generated using the [precice-config-visualizer](https://precice.org/tooling-config-visualization.html)):
+
+![preCICE configuration visualization](images/tutorials-wolf-sheep-soil-creep-precice-config.png)
+
+## Available solvers
+
+Soil-Creep PDE participant:
+
+* Landlab. Numerical modeling of Earth surface dynamics. For more information, have a look at the [Landlab documentation](https://landlab.csdms.io/index.html).
+
+Wolf-Sheep-Grass ABM participant:
+
+* MESA. Agent-based modeling (or ABM) framework. For more information have a look at the [MESA documentation](https://mesa.readthedocs.io/latest/index.html)
+
+## Running the simulation
+
+Open two separate terminals and start the soil creep and wolf sheep participants by calling the respective run scripts `run.sh` located in each of the participants' directories. For example:
+
+```bash
+cd soil-creep-landlab
+./run.sh
+```
+
+and
+
+```bash
+cd wolf-sheep-grass-mesa
+./run.sh
+```
+
+## Post-processing
+
+The soil-creep participant generates Python-based visualizations, which are written to `soil-creep-landlab/output`. The following examples were generated by setting `rng=42` in the `WolfSheepScenario` for the wolf-sheep-grass participant.
+
+![erosion/deposition patterns](images/tutorials-wolf-sheep-soil-creep-erosion_deposition_patterns.png)
+![soil thickness](images/tutorials-wolf-sheep-soil-creep-soil_thickness.png)
+![grass map](images/tutorials-wolf-sheep-soil-creep-grass_map.png)
diff --git a/wolf-sheep-soil-creep/clean-tutorial.sh b/wolf-sheep-soil-creep/clean-tutorial.sh
@@ -0,0 +1 @@
+../tools/clean-tutorial-base.sh
diff --git a/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-erosion_deposition_patterns.png b/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-erosion_deposition_patterns.png
diff --git a/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-grass_map.png b/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-grass_map.png
diff --git a/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-precice-config.png b/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-precice-config.png
diff --git a/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-soil_thickness.png b/wolf-sheep-soil-creep/images/tutorials-wolf-sheep-soil-creep-soil_thickness.png
diff --git a/wolf-sheep-soil-creep/metadata.yaml b/wolf-sheep-soil-creep/metadata.yaml
@@ -0,0 +1,20 @@
+name: Wolf-sheep-grass soil creep
+path: wolf-sheep-soil-creep
+url: https://precice.org/tutorials-wolf-sheep-soil-creep.html
+
+participants:
+  - Soil-Creep
+  - Wolf-Sheep-Grass
+
+cases:
+  soil-creep-landlab:
+    participant: Soil-Creep
+    directory: ./soil-creep-landlab
+    run: ./run.sh
+    component: python-bindings
+  
+  wolf-sheep-grass-mesa:
+    participant: Wolf-Sheep-Grass
+    directory: ./wolf-sheep-grass-mesa
+    run: ./run.sh
+    component: python-bindings
diff --git a/wolf-sheep-soil-creep/precice-config.xml b/wolf-sheep-soil-creep/precice-config.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<precice-configuration>
+  <log>
+    <sink
+      filter="%Severity% > debug"
+      format="---[precice] %ColorizedSeverity% %Message%"
+      enabled="true" />
+  </log>
+
+  <data:scalar name="Grass" />
+  <data:scalar name="Soil" />
+
+  <mesh name="Wolf-Sheep-Grass-Mesh" dimensions="2">
+    <use-data name="Grass" />
+  </mesh>
+
+  <mesh name="Soil-Creep-Mesh" dimensions="2">
+    <use-data name="Grass" />
+  </mesh>
+
+  <mesh name="Soil-Grass-Mesh" dimensions="2">
+    <use-data name="Soil" />
+  </mesh>
+
+  <mesh name="Soil-Depth-Mesh" dimensions="2">
+    <use-data name="Soil" />
+  </mesh>
+
+  <participant name="Wolf-Sheep-Grass">
+    <receive-mesh name="Soil-Depth-Mesh" from="Soil-Creep" />
+    <provide-mesh name="Wolf-Sheep-Grass-Mesh" />
+    <provide-mesh name="Soil-Grass-Mesh" />
+    <write-data name="Grass" mesh="Wolf-Sheep-Grass-Mesh" />
+    <read-data name="Soil" mesh="Soil-Grass-Mesh" />
+    <mapping:nearest-neighbor
+      direction="read"
+      from="Soil-Depth-Mesh"
+      to="Soil-Grass-Mesh"
+      constraint="consistent" />
+  </participant>
+
+  <participant name="Soil-Creep">
+    <receive-mesh name="Wolf-Sheep-Grass-Mesh" from="Wolf-Sheep-Grass" />
+    <provide-mesh name="Soil-Creep-Mesh" />
+    <provide-mesh name="Soil-Depth-Mesh" />
+    <read-data name="Grass" mesh="Soil-Creep-Mesh" />
+    <write-data name="Soil" mesh="Soil-Depth-Mesh" />
+    <mapping:nearest-neighbor
+      direction="read"
+      from="Wolf-Sheep-Grass-Mesh"
+      to="Soil-Creep-Mesh"
+      constraint="consistent" />
+  </participant>
+
+  <m2n:sockets acceptor="Wolf-Sheep-Grass" connector="Soil-Creep" exchange-directory=".." />
+
+  <coupling-scheme:serial-explicit>
+    <participants first="Soil-Creep" second="Wolf-Sheep-Grass" />
+    <time-window-size value="2" />
+    <max-time value="100" />
+    <exchange
+      data="Grass"
+      mesh="Wolf-Sheep-Grass-Mesh"
+      from="Wolf-Sheep-Grass"
+      to="Soil-Creep"
+      initialize="true" />
+    <exchange data="Soil" mesh="Soil-Depth-Mesh" from="Soil-Creep" to="Wolf-Sheep-Grass" />
+  </coupling-scheme:serial-explicit>
+</precice-configuration>
diff --git a/wolf-sheep-soil-creep/soil-creep-landlab/.gitignore b/wolf-sheep-soil-creep/soil-creep-landlab/.gitignore
@@ -0,0 +1 @@
+output/
diff --git a/wolf-sheep-soil-creep/soil-creep-landlab/clean.sh b/wolf-sheep-soil-creep/soil-creep-landlab/clean.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -e -u
+
+rm -rfv ./output/
+
+. ../../tools/cleaning-tools.sh
+
+clean_precice_logs .
+clean_case_logs .
diff --git a/wolf-sheep-soil-creep/soil-creep-landlab/requirements.txt b/wolf-sheep-soil-creep/soil-creep-landlab/requirements.txt
@@ -0,0 +1,4 @@
+numpy >1, <2
+matplotlib
+landlab
+pyprecice~=3.0
diff --git a/wolf-sheep-soil-creep/soil-creep-landlab/run.sh b/wolf-sheep-soil-creep/soil-creep-landlab/run.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -e -u
+
+. ../../tools/log.sh
+
+exec > >(tee --append "$LOGFILE") 2>&1
+
+if [ ! -v PRECICE_TUTORIALS_NO_VENV ]; then
+
+    if [ ! -d ".venv" ]; then
+        python3 -m venv .venv
+        source .venv/bin/activate
+        pip install -r requirements.txt && pip freeze > pip-installed-packages.log
+    else
+        source .venv/bin/activate
+    fi
+
+fi
+
+mkdir -p output
+python3 soil_creep.py
+
+close_log
diff --git a/wolf-sheep-soil-creep/soil-creep-landlab/soil_creep.py b/wolf-sheep-soil-creep/soil-creep-landlab/soil_creep.py
@@ -0,0 +1,122 @@
+import copy
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+from landlab import RasterModelGrid, imshow_grid
+from landlab.components import LinearDiffuser
+import precice
+
+initial_soil_depth = 0.3
+
+# Set the soil-thickness scale for limiting creep where little soil is available
+hstar = 0.2
+
+# Set parameters for two soil creep coefficients: slow (full grass cover) and fast (partial or "eaten" grass cover)
+fast_creep = 0.1
+slow_creep = 0.001
+
+ground_cover_cmap = copy.copy(mpl.colormaps["YlGn"])
+
+# Create a grid the same size as the W-S-G model's grid
+width = 20
+height = 20
+
+rmg = RasterModelGrid((width, height))
+
+# Create elevation field and have it slope down to the south at 10% gradient
+elev = rmg.add_zeros("topographic__elevation", at="node")
+elev[:] = 0.1 * rmg.y_of_node
+
+# Have one open boundary on the south side
+rmg.set_closed_boundaries_at_grid_edges(True, True, True, False)
+
+# Remember the starting elevation so we can calculate cumulative erosion/deposition
+initial_elev = np.zeros(rmg.number_of_nodes)
+initial_elev[:] = elev
+
+# Also remember the elevation of the prior time step, so we can difference
+prior_elev = np.zeros(rmg.number_of_nodes)
+
+# Create a field for the creep coefficient
+creep_coef = rmg.add_zeros("creep_coefficient", at="node")
+
+# Create a soil-thickness field
+soil = rmg.add_zeros("soil__depth", at="node")
+soil[:] = initial_soil_depth
+
+# Instantiate a LinearDiffuser (soil creep) Landlab component
+diffuser = LinearDiffuser(rmg, linear_diffusivity=creep_coef)
+
+# preCICE setup
+participant_name = "Soil-Creep"
+config_file_name = "../precice-config.xml"
+solver_process_index = 0
+solver_process_size = 1
+participant = precice.Participant(participant_name, config_file_name, solver_process_index, solver_process_size)
+
+positions = [[x, y] for x in range(width) for y in range(height)]
+vertex_gm_ids = participant.set_mesh_vertices("Soil-Creep-Mesh", positions)
+vertex_soil_ids = participant.set_mesh_vertices("Soil-Depth-Mesh", positions)
+
+participant.initialize()
+
+while participant.is_coupling_ongoing():
+    solver_dt = 0.2 * rmg.dx * rmg.dx / fast_creep
+    precice_dt = participant.get_max_time_step_size()
+    dt = np.minimum(solver_dt, precice_dt)
+
+    gm = participant.read_data("Soil-Creep-Mesh", "Grass", vertex_gm_ids, dt)
+
+    # Assign the higher creep coefficient to cells where the grass has
+    # been eaten and not yet recovered; the slower value is assigned to
+    # "fully grown" grass patches.
+    creep_coef[gm.flatten() == 1] = fast_creep
+    creep_coef[gm.flatten() == 2] = slow_creep
+
+    # Limit the creep coefficient according to the soil-thickness field, so absent soil cannot move.
+    creep_coef *= 1.0 - np.exp(-soil / hstar)
+
+    # Remember the current elevation before LinearDiffuser updates the grid's
+    # topographic__elevation field in place.
+    prior_elev[:] = elev
+
+    # Run the soil-creep model
+    diffuser.run_one_step(dt)
+
+    # Update the soil cover
+    soil += elev - prior_elev
+
+    participant.write_data("Soil-Depth-Mesh", "Soil", vertex_soil_ids, soil)
+
+    participant.advance(dt)
+
+participant.finalize()
+
+# Calculate and plot the erosion/deposition patterns
+plt.figure()
+ero_dep = elev - initial_elev
+maxchange = np.amax(np.abs(ero_dep))
+imshow_grid(
+    rmg,
+    ero_dep,
+    vmin=-maxchange,
+    vmax=maxchange,
+    cmap="coolwarm_r",
+    colorbar_label="Depth of soil accumulation (+) or loss (-), m",
+)
+plt.savefig("output/erosion_deposition_patterns.png")
+plt.close()
+
+# Soil thickness
+plt.figure()
+imshow_grid(rmg, soil, colorbar_label="Soil thickness, m")
+plt.savefig("output/soil_thickness.png")
+plt.close()
+
+# Ground cover
+plt.figure()
+imshow_grid(
+    rmg, gm, cmap=ground_cover_cmap, colorbar_label="Ground cover (1 = bare, 2 = grass)"
+)
+plt.savefig("output/grass_map.png")
+plt.close()
diff --git a/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/clean.sh b/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/clean.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+set -e -u
+
+. ../../tools/cleaning-tools.sh
+
+clean_precice_logs .
+clean_case_logs .
diff --git a/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/requirements.txt b/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/requirements.txt
@@ -0,0 +1,5 @@
+numpy >1, <2
+matplotlib
+mesa>=3
+pyprecice~=3.0
+networkx
diff --git a/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/run.sh b/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/run.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -e -u
+
+. ../../tools/log.sh
+
+exec > >(tee --append "$LOGFILE") 2>&1
+
+if [ ! -v PRECICE_TUTORIALS_NO_VENV ]; then
+
+    if [ ! -d ".venv" ]; then
+        python3 -m venv .venv
+        source .venv/bin/activate
+        pip install -r requirements.txt && pip freeze > pip-installed-packages.log
+    else
+        source .venv/bin/activate
+    fi
+
+fi
+
+python3 wolf_sheep_grass.py
+
+close_log
diff --git a/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/wolf_sheep_grass.py b/wolf-sheep-soil-creep/wolf-sheep-grass-mesa/wolf_sheep_grass.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+- Added the `wolf-sheep-soil-creep` tutorial [#793](https://github.com/precice/tutorials/pull/793)