Teaching examples on the ribbon representation: crossing fault zones, and gouge width

[lmoresi]

Two pages in docs/advanced/, built on the finite-width (ribbon) fault representation. Each tests a prediction rather than illustrating one. Scripts and full working notes live in ~/+Simulations/ribbon_network_2d/.

crossing-fault-zones.md — the measurement #544 asked for

The algebra comes first, and it reframes the question. In plane strain the deviatoric strain-rate space is two-dimensional, and rotating the material by θ rotates a state in it by 2θ. A weak plane is compliant in exactly one mode, so it occupies a single line in that space; two planes separated by Δ in the rock are separated by 2Δ there.

So Δ = 0 and Δ = 90 are the same case — shear on a plane with normal x̂ is shear on a plane with normal ŷ. The 90-degree X that "high angle" suggests is the one geometry where the two rules provably coincide, and the acceptance test as #544 proposed it would have measured nothing.

Checked numerically against the shipped Mühlhaus–Moresi tensor. Two by-products: #539's eta -> 1/(4 eta) substitution is confirmed to round-off, and the orthotropic tensor is itself a TI tensor in 2-D, so it needs no new constitutive machinery — read off an effective director and effective η₀, η₁.

The measurement. Two ribbons crossing at the box centre, fused into one zone, five rheologies per angle on one mesh, differing only in the overlap cells, against a no-fault control on that same mesh. Metric is dissipation weakening, which has no probe geometry in it.

Δ	10°	20°	30°	45°	60°	75°	90°
nearest / orthotropic	70.0%	81.6%	86.2%	93.0%	97.1%	99.2%	100.0%

The Δ = 90 row is the experiment's negative control and it passes exactly — the two dissipations agree to seven significant figures. The algebra requires it, nothing was tuned to produce it, and it is what licenses the other six rows.

The error is largest where the issue expected none. The per-cell tensors differ most at 45°, and the curve shows no feature there. The overlap area goes as 1/sin Δ — 141 overlap cells at 10° against 24 at 90° — so the area wins. The geometry to worry about is the shallow crossing.

Resolution. The host mesh does not enter at all: 0.04, 0.03 and 0.02 give the same ratio to four significant figures, because the embedded zone mesh is identical in all three. The zone mesh does, and refining it always moves the nearest-fault rule closer to the orthotropic one — 70.0 → 73.8 → 75.1% at Δ = 10, converging near 76%. The sweep table is therefore a set of bounds, and the corrected headline is that the rule loses about a quarter of the network's weakening at the worst angle, not a third.

gouge-zones.md — what the matched collapse loses

The collapse eta_I = eta_1 / w is checked rather than assumed: it reproduces slip to 1.7% at w = 0.002 and 12% at w = 0.02, behaving as the w → 0 limit it is.

It preserves the ratio η₁/w and destroys the pair. So the gouge's own temperature excess,

Delta T = eta_1 V^2 / (8 kappa) = (eta_I V^2 / 8 kappa) * w

is proportional to the width at fixed interface law and is zero for a contact at every width. Matched to 1% at three widths with nothing fitted — η₁ and κ are set, V and ΔT are measured independently.

Separately and more sharply: a transport equation posed on a split-node mesh sees a perfect insulator. Plain conduction, uniform diffusivity, no fault properties anywhere, no mechanics — the split mesh loses 19% of the wall flux and develops a temperature discontinuity of 0.47 across the fault. The plain-mesh control reproduces the analytic flux exactly (−0.010000), so that is the mesh and not the solver.

Things recorded so they are not re-derived

• clearance is not monotone: a 30° crossing builds only at 1.3, a 45° one at 1.0 but not 1.3. Walk a ladder and record which value was used.
• A fixed probe standoff is wrong at a shallow crossing — a probe at 0.75 w from one trace sits inside the other ribbon and read 0.006 against a peak of 0.18. Even walked clear of the union, the local probe cannot be trusted at the crossing itself, which is why the metric is a dissipation.
• The rotated contact path builds its own prefixed KSP that stokes.petsc_options never reaches; on its default the velocity sub-solve hit its 200-iteration cap and warned while the outer SNES still reported convergence. Use _rotated_use_lu at this size, and take the verdict from the constraint (the no-opening leak, 5.5e-17 here) rather than from a SNES reason that does not describe that solver.
• Do not take a dissipation profile through uw.function.evaluate — it L2-projects derivative composites (uw.function.evaluate returns negative values for a squared DERIVATIVE expression #491) and the smoothing lands on the structure being measured. Project to discontinuous degree 0, where the L2 projection is the cell average.

Not included

Example 3 of the session plan (a large-scale single surface, where the contact should win outright) is blocked on #553 — the contact cannot daylight, and daylighting is the use case.

Underworld development team with AI support from Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[lmoresi]

Adversarial review

Reviewed wide — the diff, the two sweeps behind it, #544, #539, #553, and the split-node and fault-network pages this one links to. Findings first, then what we could not fault.

Fixed in 519743e

The central algebraic result is two-dimensional and the page did not say so. The 90-degree null exists because the deviatoric space here has two dimensions, so two lines in it either coincide or do not. In 3-D that space has five dimensions, two weak planes at any angle occupy different subspaces, and there is no null. A reader taking "a 90-degree crossing is safe" into a 3-D model would be wrong, and the page as written invited exactly that. It now refuses the reading explicitly.

We measured a distance to a choice and reported it as a distance to an answer. There is no external reference for what an overlap should be, and there cannot be one without modelling the fabric — both orthotropic constructions are assumptions. The page said "neither is obviously right" in passing and then quoted percentages as if one were. What actually carries the argument is that the two constructions differ by a factor of two in overlap weakness and still bracket the answer tightly (61.8% against 70.0% at the worst angle; 92.3% against 93.0% at 45 degrees), so the conclusion is insensitive to the assumed part. That inference was available in the tables and left for the reader to make; it is now stated.

The headline is a small difference of larger numbers. At Δ = 10 the dissipations are 3.9521 and 3.9225 against a control of 4.0000 — the entire signal is about 0.03 between numbers agreeing to 1%. Now said next to the metric, with what makes it readable: the control hits the analytic 4.000000 exactly, and the refinement study moves the ratio in a controlled, contracting sequence.

Standing limitations, not fixed

One point along the fault carries the gouge oracle. ΔT is measured at the fault midpoint only. The 1% agreement at three widths is strong, but nothing checks that it holds toward the tips where slip and therefore Φ fall away. The claim is about the peak, which is the quantity of interest, so this is scope rather than error — but it is untested scope.

The gouge oracle's input is a probe. ΔT = η₁V²/8κ takes V from a velocity-jump probe with the ribbon's standoff convention, and V enters squared. The 1% agreement is therefore also a check on that probe, not only on the physics. It cannot be disentangled from the data we have.

The sweep confounds crossing angle with fault orientation — unavoidable geometrically, since the pair is symmetric about the loading axes and two planes cannot change their mutual angle while both keep their orientation. Stated on the page; worth repeating that no absolute slip should be compared across angles.

What survived

• The Δ = 90 null (3.243286 against 3.243286, seven significant figures) is required by the algebra, was predicted before it was run, and nothing in the setup was tuned toward it. It is the strongest thing here.
• The host-mesh independence (three sizes, same ratio to four figures) is a genuine check on the embedding contract rather than a convenience.
• The no-fault control landing on the analytic 4.000000 validates the dissipation integral independently.
• On the gouge side, the plain-mesh conduction control reproducing −0.010000 exactly is what makes the split-mesh insulation result attributable to the mesh and not the solver. Without it the 19% flux deficit would be an assertion.

Related, unblocked by this PR

#544 has its measurement and a recommendation; it can close on a modelling decision rather than more work. #539 is confirmed incidentally — the eta -> 1/(4 eta) substitution reproduces the compliance to round-off, and the director round-trips exactly mod 90 degrees. #553 still gates the third teaching example; nothing here moves it.

Underworld development team with AI support from Claude Code