Tectonic rifting and subduction with DynEarthSol¶
A one-day tutorial in two parts. Part 1 stretches a 10 km brittle layer until a
single fault rolls over into a metamorphic core complex; it is the smallest DES model
that shows a fault, and it runs in about 12 minutes. Part 2 pushes an oceanic
plate under a fixed one while two metamorphic reactions run on the markers, and it
needs everything Part 1 left out: several materials, viscous creep, a geotherm, a
.poly mesh and material flowing in through a wall.
The web version of this tutorial, with the same figures and more explanation of the
physics, is at https://geoflac.github.io/des3d/docs/tutorial/tectonics. This notebook
is the hands-on companion. It runs nothing itself; it only reads and plots DES output.
You launch each run from a JupyterLab terminal with the bash command shown, and every
panel uses your own run once it has written the frame that panel shows, and the supplied
reference results until then; line plots draw your run so far over the faded reference.
Schedule¶
| Slot | What you do | Start these runs |
|---|---|---|
| Morning, 75 min | Setup check, Part 1, Exercises 1–2 | core-complex at once (12 min); one ex1-* and one ex2-* |
| Lunch | subduction (22 min) |
|
| Afternoon, 75 min | Part 2, Exercise 3 | optionally one ex3-* (17–21 min) |
| Afternoon, 90 min | Restart case, ParaView, your own changes | restart-stop (2 min) |
Times are for 6 threads on an Apple M3 Max; on the default 4 threads allow about a third longer.
Setup check¶
Do resources/SETUP.md before the day. Then run the cell below. It checks the DES
executable, says whether the build is recent enough for Part 2, and, for each run,
how far your own results (results/<run>/output/) have got; the plots take each
frame from your run once it is written, else from the supplied reference. For a DES built somewhere else, give the check its path:
tt.check_executable("/path/to/dynearthsol2d").
Optional: download and build DES¶
Skip this if the check below finds DES. Otherwise, in the terminal beside this notebook (in the tutorial directory), clone DES and build it in 2D with MMG and HDF5:
git clone https://github.com/GeoFLAC/DynEarthSol.git DynEarthSol
cd DynEarthSol
make ndims=2 usemmg=1 hdf5=1 -j4
cd ..
The build takes a few minutes and needs the compilers and libraries of
resources/SETUP.md, step 1. A DES built for another tutorial with a plain make is 3D
without MMG and cannot run this one. When the build has finished, run the cell below
(again).
from pathlib import Path
import sys
import numpy as np
import matplotlib.pyplot as plt
ROOT = Path.cwd().resolve()
assert (ROOT / "resources/tutorial_tools.py").is_file(), "Open the notebook from the DES-Tectonics-Tutorial directory."
sys.path.insert(0, str(ROOT / "resources"))
import tutorial_tools as tt
tt.configure_plotting()
RUN_NAMES = ["core-complex", "ex1-diffusivity-1e-6", "ex1-diffusivity-1e-5",
"ex2-smallest-size-1", "ex2-smallest-size-0.001", "ex2-smallest-size-0.001-coeff-10",
"subduction", "ex3-no-serpentinite", "ex3-thickness-10km", "restart-stop"]
# Your own runs. Each plot reads a frame from your run once it has written that frame, and
# from the supplied reference of the same name until then (tt.source); a panel drawn from a
# reference says so. Last-frame panels need the whole run, so they switch when your run has
# finished; line plots draw your run so far over its reference, which stays faded behind it.
RUNS = {name: ROOT / "results" / name for name in RUN_NAMES}
tt.check_executable() # or tt.check_executable("/path/to/dynearthsol2d")
# To force the reference for one run: RUNS["core-complex"] = tt.REFERENCE / "core-complex"
for name, path in RUNS.items():
own, last = tt.frames(path), tt.frames(tt.REFERENCE / name)[-1]
if not own:
print(f"{name:34s} reference")
elif own[-1] >= last:
print(f"{name:34s} your run, finished ({len(own)} frames)")
else:
print(f"{name:34s} your run at frame {own[-1]} of {last}; the reference for frames it has not written")
DES executable: DynEarthSol/dynearthsol2d Part 2 ready: --help lists the serpentinization parameters. core-complex reference ex1-diffusivity-1e-6 reference ex1-diffusivity-1e-5 reference ex2-smallest-size-1 reference ex2-smallest-size-0.001 reference ex2-smallest-size-0.001-coeff-10 reference subduction reference ex3-no-serpentinite reference ex3-thickness-10km reference restart-stop reference
Part 1: rifting a brittle crust (core complex)¶
resources/models/core-complex.cfg is DynEarthSol's examples/core-complex.cfg with
max_time_in_yr raised from 50 to 100 kyr and the output directed into output/. A
100 × 10 km elasto-plastic layer is pulled apart at 3.15 cm/yr on each wall. A planar
weak zone dipping 60° in the lower half of the layer, already softened to pls1, seeds
the fault. Cohesion drops from 44 to 4 MPa over a plastic strain of 0.5; friction stays
at 30°. The mesh is 1 km in the central 40 km and coarser outside, and MMG refines it
along the fault as plastic strain accumulates.
The rolling hinge, sketched: the seed fault cuts to the surface, the hanging wall drops into a basin, and the rising footwall bends the fault into a dome as it is exhumed.
The setup of core-complex.cfg, with the parameter names that set each part.
Strain softening: cohesion falls from 44 to 4 MPa between plastic strain 0 and 0.5, friction stays at 30°, and the seed starts fully softened.
Step 1: start the run¶
Use the terminal beside this notebook (File → New → Terminal opens another). It starts in the tutorial directory. Once in each new terminal, set how many CPU cores DES may use and where DES is:
export OMP_NUM_THREADS=4 # raise it if your machine has more cores to spare
DES=$PWD/DynEarthSol/dynearthsol2d # or the path of a DES built elsewhere
Then start the run. Every run in this tutorial is these lines with its own case name:
mkdir -p results/core-complex/output
cp resources/models/core-complex.cfg results/core-complex/
cd results/core-complex
"$DES" core-complex.cfg
cd ../..
The run gets its own directory, results/core-complex/, holding a copy of the config
and an output/ folder; the config's modelname = output/model sends the frames
there. DES runs inside that directory and prints its progress to the terminal. About
12 minutes, during which the terminal is busy; when the run ends, cd ../.. brings you
back to the tutorial directory. Ctrl-C stops a run early; the terminal then stays in the case's directory,
so type cd ../.. to come back.
To see from another terminal how far it has got, list the frames it has written so far
(model.save.NNNNNN.vtkhdf, one per saved frame; this run writes 67):
ls results/core-complex/output
The terminal shows a line per saved frame (Output #) with the model time and dt, a
progress line every 50000 steps, and a Remeshing starts block whenever the mesh is
rebuilt. A finished run ends with Ending simulation. and a time summary. Runs at the same time
share the machine's cores, so start the exercises once this one has finished. Leave it running and
carry on with the plots below: rerun a plot cell later and every panel whose frame
your run has written by then shows your run instead of the reference.
Look at it in ParaView or VisIt. ParaView opens the frames as they are: File →
Open, pick output/model.save.…vtkhdf (ParaView groups the series), Apply, and colour
by plastic strain. For VisIt, or to add the derived fields and the markers, convert
with DES's own script, which needs scipy (in resources/requirements.txt):
python DynEarthSol/2vtk.py -m results/core-complex/output/model
It writes output/model.NNNNNN.vtu for the mesh fields and .vtp for the markers. This
is for your own runs only: the supplied reference frames are stripped to the fields the
notebook plots, so neither 2vtk.py nor ParaView can open them.
Step 2: read the configuration¶
Open resources/models/core-complex.cfg next to the notebook. Things to find:
[mesh]:meshing_option = 2refines the centralrefined_zonex = [0.3, 0.7]atresolution = 1e3;smallest_sizeandlargest_sizebound the element area MMG may use;remeshing_option = 11restores the bottom at every remesh.[ic]:weakzone_xcenter = 0.5is x = 50 km,weakzone_depth_min/max = 0.5, 1.0is the lower 5 km, andweakzone_plstrain = 0.5equalspls1, so the seed is pre-softened.[mat]: one material;cohesion0/1 = 4.4e7, 4e6soften overpls0/1 = 0, 0.5;friction_angle0 = friction_angle1 = 30.[control]:inertial_scaling = 1e5sets the mass scaling that lengthens the elastic time step; with no viscosity in play, this and the smallest element setdt.
Step 3: what to look for¶
Plastic strain on the mesh (left) and strain rate with velocity arrows (right) at four times. The left column is where slip has accumulated and how the mesh follows it; the right is where slip is happening now.
fig = tt.plot_core_complex(RUNS["core-complex"], times_kyr=(25, 50, 75, 100))
Look for: the seed cutting to the surface at about 13 kyr; the footwall rising and the hanging wall sliding left in the arrows; a second, antithetic band at x = 55–65 km in the strain rate that never shows in plastic strain; and the fault band rotating from steep to gentle as it is exhumed. The next plot measures that rotation.
fig = tt.plot_relief_and_dip([RUNS["core-complex"]], ["core-complex"])
The dip of the fault band steepens to about 50° while it breaks through, then rolls steadily to 35° by 100 kyr as relief grows to 3.8 km. That is the rolling hinge.
Questions. Where does the relief curve change slope, and what is happening to the fault then? Why does the strain-rate panel show the antithetic band but the plastic-strain panel does not?
Exercise 1: change the surface diffusivity¶
Three runs differ only in surface_diffusivity: 1e-7 m²/s (stock), 1e-6 and 1e-5.
Supplied results are used by default. To run them yourself, one at a time:
# Exercise 1: surface_diffusivity = 1e-6 m²/s, about 8 minutes
mkdir -p results/ex1-diffusivity-1e-6/output
cp resources/models/ex1-diffusivity-1e-6.cfg results/ex1-diffusivity-1e-6/
cd results/ex1-diffusivity-1e-6
"$DES" ex1-diffusivity-1e-6.cfg
cd ../..
# Exercise 1: surface_diffusivity = 1e-5 m²/s, about 4 minutes
mkdir -p results/ex1-diffusivity-1e-5/output
cp resources/models/ex1-diffusivity-1e-5.cfg results/ex1-diffusivity-1e-5/
cd results/ex1-diffusivity-1e-5
"$DES" ex1-diffusivity-1e-5.cfg
cd ../..
and, once it has finished, optionally for ParaView or VisIt:
python DynEarthSol/2vtk.py -m results/ex1-diffusivity-1e-5/output/model
The plot draws passive horizons: every node carries its initial position through
remeshing in the coord0 field, so contouring the initial depth on the present mesh
shows where each layer of the original crust has gone. The fault band is shaded.
fig = tt.plot_horizons([RUNS["core-complex"], RUNS["ex1-diffusivity-1e-6"], RUNS["ex1-diffusivity-1e-5"]],
["1e-7 m²/s (stock)", "1e-6 m²/s", "1e-5 m²/s"], frame=66)
Before reading on, write down which of these you expect erosion to change: the dip of the fault, the depth the horizons rise from, the relief, the depth of the rock exposed at the surface.
What the runs show: the fault is the same in all three (41–42° at 50 kyr, 34–36° at 100 kyr, plastic strain 3.7), the 8 km horizon has risen to about 4 km depth in all three, and the rock exposed at the surface came from 1.4 to 2.3 km in every run. Only the topography changes: at 1e-5 m²/s the relief stops growing at about 50 kyr because the crest is planed as fast as the fault lifts it. Relief alone is a poor measure of what a fault has done.
Exercise 2: change how small the elements may get¶
Two parameters decide how fine the mesh becomes along the fault. smallest_size is the
floor: the smallest allowed element area relative to one of edge resolution, and with
MMG the smallest edge is resolution × (smallest_size × 1.5)^(1/2). mmg_metric_refine_coeff
is the target: MMG aims for an element area of the initial one over
1 + coeff × plastic strain. Four supplied runs:
| Run | smallest_size |
mmg_metric_refine_coeff |
Smallest edge allowed |
|---|---|---|---|
ex2-smallest-size-1 |
1 | 5 | 1.2 km, the resolution |
core-complex (stock) |
0.01 | 5 | 0.12 km |
ex2-smallest-size-0.001 |
0.001 | 5 | 0.04 km |
ex2-smallest-size-0.001-coeff-10 |
0.001 | 10 | 0.04 km |
To run them yourself, one at a time (core-complex is the run of Step 1):
# Exercise 2: smallest_size = 1, about 1.5 minutes
mkdir -p results/ex2-smallest-size-1/output
cp resources/models/ex2-smallest-size-1.cfg results/ex2-smallest-size-1/
cd results/ex2-smallest-size-1
"$DES" ex2-smallest-size-1.cfg
cd ../..
# Exercise 2: smallest_size = 0.001, about 12 minutes
mkdir -p results/ex2-smallest-size-0.001/output
cp resources/models/ex2-smallest-size-0.001.cfg results/ex2-smallest-size-0.001/
cd results/ex2-smallest-size-0.001
"$DES" ex2-smallest-size-0.001.cfg
cd ../..
# Exercise 2: smallest_size = 0.001 and mmg_metric_refine_coeff = 10, about 14 minutes
mkdir -p results/ex2-smallest-size-0.001-coeff-10/output
cp resources/models/ex2-smallest-size-0.001-coeff-10.cfg results/ex2-smallest-size-0.001-coeff-10/
cd results/ex2-smallest-size-0.001-coeff-10
"$DES" ex2-smallest-size-0.001-coeff-10.cfg
cd ../..
Convert a finished run with 2vtk.py -m, as in Exercise 1, to look at the mesh refining
along the fault in ParaView.
fig = tt.plot_mesh_comparison([RUNS["ex2-smallest-size-1"], RUNS["core-complex"],
RUNS["ex2-smallest-size-0.001"], RUNS["ex2-smallest-size-0.001-coeff-10"]],
["smallest_size = 1", "0.01 (stock)", "0.001", "0.001, coeff = 10"], frame=66)
Predict before you look: does lowering the floor from 0.01 to 0.001 make the band finer?
It does not. The stock run's smallest element is 0.17 km, above the 0.12 km floor, so the
floor was never what stopped the refinement; the target was. Lowering the floor alone
only changes the tiny-element remesh trigger and costs 5 % more steps for the same mesh.
Raising the target as well is what refines the band: 559 elements in the band instead of
325, at a median edge of 0.29 km instead of 0.43, and a second fault splays off into the
hanging wall from about 50 kyr. Going the other way, at smallest_size = 1 the band cannot
be narrower than its 1 km elements, so the strain spreads over 3 km and the fault never
sharpens, in an eighth of the run time. The two parameters act as a pair.
Part 2: subduction¶
resources/models/subduction.cfg with poly-subduction.poly pushes an oceanic plate at
3.15 cm/yr into a fixed overriding plate. A 7 km slab is already in the mantle, dipping 30°
to 40 km depth, so the interface exists from the first step. Two marker phase changes run
every 10 steps (phase_change_option = 3): mantle just above the slab top becomes
serpentinite, a weak and light layer that lubricates the interface, when a cell of the
background grid within serpentinization_thickness below it is mostly crust; and slab crust
past the basalt–eclogite boundary becomes eclogite, dense enough to add slab pull. The
restored side walls (remeshing_option = 13) keep the incoming plate's layering, which is
why the MMG build is required.
The initial geometry around the trench, from poly-subduction.poly, with the background grid that decides where mantle becomes serpentinite.
Step 1: the run¶
If you started it at lunch, it is in
results/subduction/. Otherwise, start it now and use the reference meanwhile:
mkdir -p results/subduction/output
cp resources/models/subduction.cfg resources/models/poly-subduction.poly results/subduction/
cd results/subduction
"$DES" subduction.cfg
cd ../..
These are the commands of Part 1, Step 1 with one addition: the cp line also copies the
mesh file the config names, poly-subduction.poly.
A smoke run first is a good habit: copy resources/models/subduction.cfg to
resources/models/smoke.cfg, set max_time_in_yr = 500e3 and
output_time_interval_in_yr = 25e3 in the copy, and running it as case smoke checks in 2 to 3
minutes that the build, MMG and the phase changes all work.
To look at it in ParaView, open output/model.save.…vtkhdf and colour by material
or viscosity. The serpentinite and eclogite live on the markers, so convert with the
marker option and open the .vtp files too:
python DynEarthSol/2vtk.py -m results/subduction/output/model
Step 2: the initial geometry and the configuration¶
Open resources/models/poly-subduction.poly. Its header sketches the five regions: a 2 km
sediment layer, the oceanic crust from 2 to 9 km, the slab, a 10 km halo of refined mantle
around it, and the coarse mantle. No region holds serpentinite or eclogite; the phase
changes make them. In subduction.cfg, find the ten mattype_* slots and which six are
populated, the has_* switches that turn each reaction on, serpentinization_thickness = 5e3, and vt_size = 0.5, the background grid cell as a fraction of resolution.
Step 3: what to look for¶
Material with velocity arrows (left) and viscosity with isotherms (right) at 0.5, 1, 2.5 and 5 Myr. With the reference run those are frames 10, 20, 50 and 100.
fig = tt.plot_subduction(RUNS["subduction"], (10, 20, 50, 100))
Look for: serpentinite along the slab top from the first frame, since the slab is already in place; eclogite starting at the slab tip near 50 km and growing to about 380 markers by 5 Myr; the slab tip at 50, 90 and 125 km with a steady 30–35° dip; the wedge corner converting wholesale, a geometric rule rather than a thermal one; and the incoming plate keeping its three layers at the left wall.
How the mesh keeps up¶
The mesh nearly doubles over the run. The left panel classifies every element by its plastic
strain at every frame, from your run once it has frames (over the faded reference while it is
still going). DES reports its remeshes only on the screen, so their triggers, marked on the
left and counted on the right, come from the supplied reference, which keeps them in
remesh.csv.
fig = tt.plot_remeshing(RUNS["subduction"], time_unit="Myr")
Elements with no plastic strain fall as the deforming band widens into them and stay
coarse; fully softened elements grow from none to 42 % of the mesh at a third of the
nominal size. The three remesh triggers are tiny elements (area below smallest_size of
nominal), low quality (below min_quality = 0.2) and bottom drift (a bottom node more than
max_boundary_distortion × resolution = 6 km from the base). Bottom drift belongs to the
first million years, while the slab tip sinks and the Winkler base adjusts; after that it stops.
Exercise 3: change the thickness of the serpentinite layer¶
serpentinization_thickness is counted in 3 km grid cells and must be positive, so the
zero case is has_serpentinization = no. The three supplied runs are 0, 5 (stock) and
10 km, all to 5 Myr. To run the other two yourself, one at a time, with the mesh file
copied as for subduction:
# Exercise 3: has_serpentinization = no, about 17 minutes
mkdir -p results/ex3-no-serpentinite/output
cp resources/models/ex3-no-serpentinite.cfg resources/models/poly-subduction.poly results/ex3-no-serpentinite/
cd results/ex3-no-serpentinite
"$DES" ex3-no-serpentinite.cfg
cd ../..
# Exercise 3: serpentinization_thickness = 10 km, about 21 minutes
mkdir -p results/ex3-thickness-10km/output
cp resources/models/ex3-thickness-10km.cfg resources/models/poly-subduction.poly results/ex3-thickness-10km/
cd results/ex3-thickness-10km
"$DES" ex3-thickness-10km.cfg
cd ../..
fig = tt.plot_subduction_arms([RUNS["ex3-no-serpentinite"], RUNS["subduction"], RUNS["ex3-thickness-10km"]],
["none (has_serpentinization = no)", "5 km (stock)", "10 km"])
Without the weak layer the interface locks: the slab falls behind from 2 Myr on and reaches only 100 km at 5 Myr, it necks and tears below the overriding plate, and both plates thicken and buckle, with a 9 km trench at 2.5 Myr, 3 km deeper than the 5 km run. The velocity arrows show the whole overriding plate being pushed instead of the slab sliding under it. With 10 km the trench is about 1 km shallower on average and swings less, the wedge body is larger, and eclogite is a quarter lower because the slab crust stays shallower and warmer. The weak layer is what makes this model subduct.
The 5 km and 10 km runs were each made twice, on the pull request's branch and on
master after the merge. The pairs agree on all of the above but differ in detail (the 10 km
trench ended 1 km shallower than the 5 km run in one pair and 0.5 km deeper in the other),
which is the chaotic scatter of a remeshing model. Differences of that size are suggestive;
the locking of the 0 km case is robust.
Restart case: stop the convergence and see what carries on¶
DES writes a checkpoint every checkpoint_frame_interval frames (10 by default), so the
reference run leaves its last one at frame 100, 5 Myr. resources/models/restart-stop.cfg
continues it for two million years with the push switched off:
is_restarting = yes
restarting_from_frame = 100
max_time_in_yr = 7e6
vbc_val_x0 = 0 # the left plate is held still
A restart needs the parent's frame and checkpoint in its own output/, so these
commands copy the subduction run's output there before starting DES. Use your own subduction
run only once it has finished; otherwise copy the supplied reference, which ships
frame 100 whole with its checkpoint:
mkdir -p results/restart-stop/output
cp results/subduction/output/model.* results/restart-stop/output/
# no finished subduction run of your own? copy the reference instead:
# cp resources/reference/subduction/output/model.* results/restart-stop/output/
cp resources/models/restart-stop.cfg resources/models/poly-subduction.poly results/restart-stop/
cd results/restart-stop
"$DES" restart-stop.cfg
cd ../..
It takes about two minutes.
The question it answers is which parts of the model were driven by the push and which carry on by themselves once convergence stops, as after a collision or a plate reorganisation.
fig = tt.plot_stop_convergence(RUNS["subduction"], RUNS["restart-stop"])
- The slab stops. Its tip sank 13 km per million years while pushed and less than 1 km in the two million years after. There is no slab pull to speak of: the plate it hangs from is held at the wall, and sinking further would mean stretching a plate at the 10²⁴ Pa s viscosity cap. This model subducts because it is pushed.
- The surface rebounds first, then smooths. Within the first million years the trench shallows from 3.8 to 1.8 km and the forearc high rises from 2.6 to 5.3 km: isostatic rebound, the shear on the plate interface that held the overriding plate down is gone. After that the levels hardly move and surface diffusion rounds the slopes without removing the relief. The incoming plate next to the held wall sags by up to 6 km, a wall effect to be aware of.
- The slab warms and reacts until it runs out of crust. Nothing cold arrives any more, so the deep slab warms by 50 °C over the two million years. Eclogite is the one thing that speeds up: 381 markers become 588 by 5.75 Myr as the stationary crust heats across the basalt–eclogite boundary; then it saturates near 610, because the crust above 71 km is too shallow to cross the boundary however warm it gets. Serpentinite grows by 190 markers and stops too: its rule is geometric and needs new mantle to be brought over crust.
The restart's frames 100 to 140 sit in results/restart-stop/output/ beside the copied parent
frame; to look at them in ParaView, convert from frame 100 on:
python DynEarthSol/2vtk.py -m results/restart-stop/output/model 100
Two cautions. Pick a restart frame that is not a remesh step, since a checkpoint written on one is not bit-recoverable. And a restart is a new realization of a chaotic run, so compare it with the parent's trend, as the bottom row does, rather than with a single frame.
Saving figures¶
tt.save_figure(fig, "my-figure") writes PNG and PDF to results/figures/.
Troubleshooting¶
| Symptom | Check |
|---|---|
make cannot find Boost or HDF5 |
Install the packages in resources/SETUP.md; run make config ndims=2 usemmg=1 hdf5=1 and read the paths it prints |
--help does not list serpentinization |
The build predates the 30 October 2026 merge of PR #110: git pull and rebuild with usemmg=1 |
remeshing_option 13 refused |
Restored side walls need the MMG build |
.poly file not found |
Run from the directory holding both subduction.cfg and poly-subduction.poly |
The setup cell says No DES executable |
DES is not built inside the tutorial directory (resources/SETUP.md, step 2); for a build elsewhere, give the cell its path |
: command not found or No such file or directory when starting a run |
DES is not set in this terminal, or names the wrong path: set it as in Part 1, Step 1 (a new terminal forgets it) |
| Running a case a second time | Move the first run away before starting: mv results/<run> results/<run>-old; otherwise DES overwrites its frames |
| A panel says "reference" although you started that run | Your run has not written that panel's frame yet (last-frame panels need the whole run; in line plots the faded line is the reference, yours grows over it). The setup cell says which frame it is at; rerun the plot cell later |
Next steps¶
The web tutorial at https://geoflac.github.io/des3d/docs/tutorial/tectonics has the physics
background, the model-setup figures and the references. From here: examples/rifting-2d.cfg
adds a mantle, a geotherm and viscous creep to Part 1; the GoSPL coupling tutorial adds
surface processes to models like these.