Skip to content

docs: tectonic rifting and subduction tutorial - #89

Merged
echoi merged 18 commits into
mainfrom
tutorial/tectonics
Oct 29, 2026
Merged

docs: tectonic rifting and subduction tutorial#89
echoi merged 18 commits into
mainfrom
tutorial/tectonics

Conversation

@chaseshyu

@chaseshyu chaseshyu commented Oct 26, 2026

Copy link
Copy Markdown
Member

New tutorial page Tectonic rifting and subduction (docs/tutorial/tectonics.md), placed after Rate-and-state friction and before the GoSPL coupling tutorial, with a downloadable workshop package.

Part 1, rifting a brittle crust: examples/core-complex.cfg on DynEarthSol master (PR #95's MMG refinement parameters). Setup geometry, strain softening and the rolling-hinge mechanism as SVG schematics, evolution figure from a 100 kyr run, Exercise 1 on surface_diffusivity (passive horizons show exhumation is unchanged), Exercise 2 on smallest_size with mmg_metric_refine_coeff.

Part 2, subduction with phase changes: examples/subduction.cfg from the feature/virtual-topology branch (GeoFLAC/DynEarthSol#110, phase_change_option = 3), flagged in a caution box until that PR merges. Geometry figure drawn from the .poly file, 5 Myr evolution with velocity arrows, remeshing history, Exercise 3 on serpentinite thickness including a run that fails on purpose, and a troubleshooting case that restarts it with max_boundary_distortion = 0.5.

Workshop package static/downloads/des-tectonics/DES-Tectonics-Tutorial.zip (11 MB) for a 90-minute class: a Jupyter notebook that plots every figure from DES output, all configs behind a one-command run.sh, a short build recipe, and reference results stripped to the fields the notebook plots so the class never waits for a run. Only the zip is tracked, as for the RSF package.

Figures come from real runs; the generator scripts for the SVGs are in docs/tutorial/img/tectonics/_src/.

Checked: yarn build renders the page and the download link; the notebook executes end to end from a clean unzip.

🤖 Generated with Claude Code

chaseshyu and others added 18 commits October 16, 2026 15:55
@chaseshyu @claude
docs: add skeleton for tectonic rifting and subduction tutorial
29c202e 
New tutorial page following the layout of the GoSPL coupling page:
physics background, a rifting part built on examples/rifting-2d.cfg,
an open subduction part, exercises and troubleshooting. Section bodies
to be written are marked with MDX TODO comments so the page renders
while incomplete; figure links are commented out until the images
exist in docs/tutorial/img/tectonics/.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: write Part 1 of the tectonics tutorial around core-complex.cfg
073b701 
Part 1 now uses examples/core-complex.cfg: full config walkthrough,
most-changed parameters, run and visualize steps, an optional MMG box
using the smallest_size/largest_size size band, three exercises (seed
dip, surface diffusivity, MMG refinement) and a pointer to rifting-2d.cfg.
The shared rheology table gains a "Used in" column. Part 2 carries a
visible work-in-progress notice; all authoring notes are MDX comments so
nothing marked TODO renders.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: flag unmerged MMG dependency in tectonics Part 1
adc3fb0 
A caution box at the top of Part 1 says the MMG box and Exercise 3 use
parameters from a pull request not yet merged, while the stock run works
on the current release.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: add strain-softening and rolling-hinge figures to tectonics Part 1
7768d6b 
Two hand-written SVGs in the style of the GoSPL tutorial graphics. The
strain-softening sketch plots cohesion and friction against plastic
strain for core-complex.cfg and marks where the weak-zone seed starts.
The rolling-hinge figure animates the setup (walls, seed, free surface,
Winkler foundation) through fault breakthrough, footwall uplift and
fault flattening over a 14 s SMIL loop.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: update tectonics Part 1 for merged DynEarthSol PR #95
3ffeb3a 
MMG is now a submodule built with make usemmg=1, and the conservative
remeshing parameters are on master, so the unmerged-PR caution is removed,
the build wording follows the README, and the parameter reference points
at examples/defaults.cfg and --help until the MMG page catches up.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: write tectonics Part 2 around examples/subduction.cfg
ea7fc99 
Part 2 follows examples/subduction.cfg on the DynEarthSol branch
feature/virtual-topology: settings table, poly geometry with a region
table, abridged config walkthrough, the phase_change_option = 3 rules and
the virtual-topology grid, run and smoke-run instructions, what to look
for in the reference run, and two exercises. Adds the geometry sketch
(SVG) and a material/viscosity evolution figure from the 5 Myr run, and
stores the SVG generator scripts under img/tectonics/_src.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: align tectonics Part 2 with DynEarthSol PR #110, drop the frict…
e2f5686 
…ion exercise

The caution box names the open pull request. The rule table and the
virtual-topology paragraph follow the PR head: a grid cell is crust when
more than half its markers are oceanic crust or sediment, serpentinite
dehydrates back above 550 C, reach is counted in whole cells, and the
rules read the element mean stress. The interface-friction exercise is
removed; the one Part 2 exercise is now the serpentinite layer thickness
at 0, 5 and 10 km, with 0 as has_serpentinization = no since a positive
thickness is required.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: draw the subduction halo region as the poly file bounds it
da99a1f 
The refined-mantle halo polygon detoured through the slab end (nodes 11
and 10) and so omitted the wedge beyond the slab tip that segment 14-15
of poly-subduction.poly encloses. It now follows the outer boundary of
the file, 12-8-9-13-15-14, with the slab drawn on top. Node coordinates,
dip (30.00 deg) and thickness (7.00 km) were checked against the parsed
file and already matched.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics Part 2 exercise and figures from the PR #110 referenc…
0b02bf7 
…e runs

Exercise 3 (serpentinite layer none / 5 km / 10 km) is filled from three
5 Myr runs on the PR #110 head binary. Without the layer the interface
locks, the slab stalls near 75 km and necks off, the plates buckle and
the run ends at 3.45 Myr in a remeshing failure; with 10 km the trench is
1.5 km shallower and eclogite drops by 40 %. The evolution and thickness
figures are regenerated from those runs and restyled for the page:
cropped to the slab, surface drawn, corner boxes with tip depth and
marker counts, common 3.4 Myr comparison time. Reference-run numbers in
the text follow the new figure.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics Part 2 figures with velocity arrows, remeshing histor…
4a0c82e 
…y and a restart case

The evolution and thickness figures gain time-averaged velocity arrows,
the thickness figure spans the whole domain with its time-series row
aligned to the panels above, and the reference-run numbers follow the
figures. Two figures are new: the remeshing history of the reference run
(elements by plastic-strain class with each remesh marked by its trigger,
and cumulative counts by trigger) under a "How the mesh keeps up"
subsection, and a troubleshooting case after Exercise 3 showing the
locked no-serpentinite run restarted from its 3.0 Myr checkpoint with
max_boundary_distortion halved to 0.5, which reaches 5 Myr with the
physics unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: place the tectonics tutorial before GoSPL, fix its links, finis…
07e75b7 
…h the thickness figure

The tutorial moves to sidebar position 7, after rate-and-state friction,
and the GoSPL page to 8. Prerequisites are rewritten around the pages
that now precede it. Internal links become file-path links, since the
installation page is published at /docs/usage and the bare URL form was
a dead link on the deployed site. "What you will learn" covers phase
changes, remeshing triggers and the restart case. The thickness figure
shows the 5 and 10 km runs at 5 Myr and the failed run where it stopped,
with its restart as a dashed history in the time series.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics Part 1 figures and Exercise 1 from runs of core-compl…
10e31f3 
…ex.cfg

Three 100 kyr runs of examples/core-complex.cfg on an MMG build at the
PR #95 merge commit back Part 1. The evolution figure shows plastic
strain on the mesh beside strain rate with velocity arrows at 25, 50, 75
and 100 kyr, then the surface profiles and relief and fault-band dip
against time (the hinge rolls from 46 to 35 degrees). Exercise 1 is
filled with its own figure built on passive horizons from the coord0
field: the fault and the exhumation are identical at diffusivities of
1e-7, 1e-6 and 1e-5 m2/s, only the topography differs. Step 2 says the
stock file stops at 50 kyr and gives the one-line change for 100 kyr;
the cost paragraph quotes the measured run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: add a geometry-and-mesh figure for core-complex.cfg, make the h…
2ff53a1 
…inge animation a pure sketch

A new SVG beside the Part 1 settings table shows the initial geometry and
mesh of core-complex.cfg with the parameters that set them: the box, the
refined zone with a 1 km element against a 3 km one outside, the planar
weak-zone seed drawn from the formula in ic.cxx (dipping toward -x), the
wall velocities, the free surface and the Winkler bottom. The rolling-hinge
animation loses its setup annotations so the two no longer overlap, and
moves up to the intro paragraph that names the mechanism.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics tutorial uses core-complex.cfg alone and states the M…
e60f43e 
…MG build requirement

The Part 1 MMG box no longer lists how core-complex-mmg.cfg differs; it
gives the size band the stock parameters imply and compares the Triangle
and MMG builds of the same file. Prerequisites name the MMG build as the
one requirement, and the build tip says Part 1 runs on either build while
Part 2 needs MMG for its restored side walls.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics tutorial in one style with a progressive workflow; Ex…
9bfa847 
…ercise 2 on smallest_size

Both parts now share four steps (geometry and mesh, configuration, run,
what to look for) followed by exercises; a roadmap table after "What you
will learn" shows what Part 2 adds to Part 1. The remaining TODOs are
written out: continental temperature options, troubleshooting rows marked
by what was observed, and a References section. Exercise 2 changes
smallest_size to 1, the stock 0.01 and 0.001, all three run: at 1 the band
cannot sharpen and the run is ten times faster; at 0.001 the mesh is the
same as stock because the refinement target, not the floor, limits it,
and the run takes 60 % more steps.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: Exercise 2 adds a stronger-target run and splits its figure; le…
37e0c8c 
…gends moved below the panels

A fourth run, smallest_size = 0.001 with mmg_metric_refine_coeff = 10,
shows that the floor alone did not limit the band: with the doubled target
the band holds 584 elements at a median edge of 0.29 km against 0.38, so
the two parameters act as a pair. The exercise table is trimmed to one
point per row, the figure is split into the four meshes and a second
figure with topography, time series and a stacked bar of elements by
plastic-strain class, and the diffusivity figure's legend moves below its
bottom row.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: tectonics tutorial ships a workshop package
79695dc 
Adds static/downloads/des-tectonics/DES-Tectonics-Tutorial.zip (11 MB), a
90-minute class package like the RSF one: a Jupyter notebook that plots every
figure of the tutorial from DES output, the configs of both parts and all
exercise variants behind a one-command run.sh launcher, a short build recipe,
and reference results of every run stripped to the fields the notebook plots
so the class never waits for a run. The failed no-serpentinite run ships its
frame-60 checkpoint so the restart troubleshooting case can be tried.

tectonics.md links the package in a tip box after the introduction.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu @claude
docs: move the GoSPL coupling tutorial after the tectonics tutorial
2d4c812 
The tectonics tutorial sits at position 7, after Rate-and-state friction;
GoSPL coupling, which builds on models like these, follows it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@chaseshyu
chaseshyu requested review from echoi and sungho91 October 26, 2026 15:34
@chaseshyu chaseshyu added the documentation Improvements or additions to documentation label Oct 26, 2026
@chaseshyu
chaseshyu marked this pull request as ready for review October 26, 2026 15:35
@echoi
echoi merged commit b726026 into main Oct 29, 2026
2 checks passed
echoi added a commit that referenced this pull request Oct 30, 2026
@echoi @claude
docs: fix Tutorial sidebar order after tectonics.md merge
0ec1927 
PR #89 (tectonics tutorial) bumped couplinggospl.md's sidebar_position
from 2 to 8 incidentally, which combined with tectonics.md's own
position (7) broke the alphabetical-by-title order set in #97: the
sidebar showed A, M, R, V, W, T, C instead of A, C, M, R, T, V, W.

Reassign positions 1-7 across all seven Tutorial items so they sort
alphabetically by title: Adaptive mesh refinement with MMG, Coupling
with GoSPL, Making a complex mesh with .poly file, Rate-and-state
friction (2D), Tectonic rifting and subduction, Velocity boundary
conditions (3D), Weak zones.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MyXyjvBfCbpMgZ6ttvJXf3
@echoi echoi mentioned this pull request Oct 30, 2026
Merged
3 tasks done
echoi added a commit that referenced this pull request Oct 30, 2026
@echoi @claude
docs: add a tip on using an AI assistant to get oriented with DES3D (#98
f7097d6 
)

* docs: add a tip on using an AI assistant to get oriented with DES3D

Distilled from a user's account of learning DES3D with an AI coding
assistant (feeding it the docs and background papers, describing a
tectonic scenario in plain language, iterating on the .cfg together).
Written generically, without the original interview's project-specific
or personal details.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MyXyjvBfCbpMgZ6ttvJXf3

* docs: fix Tutorial sidebar order after tectonics.md merge

PR #89 (tectonics tutorial) bumped couplinggospl.md's sidebar_position
from 2 to 8 incidentally, which combined with tectonics.md's own
position (7) broke the alphabetical-by-title order set in #97: the
sidebar showed A, M, R, V, W, T, C instead of A, C, M, R, T, V, W.

Reassign positions 1-7 across all seven Tutorial items so they sort
alphabetically by title: Adaptive mesh refinement with MMG, Coupling
with GoSPL, Making a complex mesh with .poly file, Rate-and-state
friction (2D), Tectonic rifting and subduction, Velocity boundary
conditions (3D), Weak zones.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MyXyjvBfCbpMgZ6ttvJXf3

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@echoi echoi mentioned this pull request Oct 31, 2026
Merged
3 tasks done
echoi added a commit that referenced this pull request Oct 31, 2026
@echoi @claude
docs: meshing_verbosity, bottom_shear_zone_thickness unit fix (DynEar…
38757f7 
…thSol #113, #114) (#103)

- bottom_shear_zone_thickness is in metres, not km (DynEarthSol #113 fixed
  the --help text to match the code, which always used metres).
- Document mesh.meshing_verbosity, the parameter gating DES's own remesh
  stage log (distinct from MMG's mmg_verbose); at the new quieter default
  (-1) a remesh prints only its trigger/start/end lines (DynEarthSol #114).
- Bump the announcement bar to DynEarthSol #114. DynEarthSol #110 (phase
  change option 3) needed no further doc changes: docs/tutorial/tectonics.md
  (#89) already documents it under its final parameter names.


Claude-Session: https://claude.ai/code/session_01MyXyjvBfCbpMgZ6ttvJXf3

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@echoi echoi Awaiting requested review from echoi
@sungho91 sungho91 Awaiting requested review from sungho91

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@chaseshyu @echoi