Add wolf-sheep-soil-creep tutorial

changelog-entries/793.md

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

wolf-sheep-soil-creep/README.md

@@ -0,0 +1,54 @@
+---
+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 is an implementation of 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, coupled via preCICE. We couple the [Wolf-Sheep model from MESA](https://mesa.readthedocs.io/latest/examples/advanced/wolf_sheep.html) with a soil creep model implemented in Landlab.
+
+## 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. 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)

wolf-sheep-soil-creep/clean-tutorial.sh

@@ -0,0 +1 @@
+../tools/clean-tutorial-base.sh

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>

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 .

wolf-sheep-soil-creep/soil-creep-landlab/requirements.txt

@@ -0,0 +1,4 @@
+numpy >1, <2
+matplotlib
+landlab
+pyprecice~=3.0

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 output
+python3 soil_creep.py
+
+close_log

wolf-sheep-soil-creep/soil-creep-landlab/soil_creep.py

@@ -0,0 +1,116 @@
+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
+hstar = 0.2
+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, and set parameters for two
+# rates: slow (full grass cover) and fast (partial or "eaten" grass cover)
+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
+
+    # Adjust the creep coefficient to account for soil depth
+    creep_coef *= 1.0 - np.exp(-soil / hstar)
+
+    # Run the soil-creep model
+    prior_elev[:] = elev
+    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()

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 .

wolf-sheep-soil-creep/wolf-sheep-grass-mesa/requirements.txt

@@ -0,0 +1,5 @@
+numpy >1, <2
+matplotlib
+mesa>=3
+pyprecice~=3.0
+networkx

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