From 2a5277082688f07e0af8ce268d68e158f7f8c475 Mon Sep 17 00:00:00 2001 From: lmoresi Date: Fri, 3 Jul 2026 12:11:38 +1000 Subject: [PATCH] docs(CLAUDE.md): record the free-slip BC preference (rotated strong free-slip) Add a "Boundary Conditions: Free-slip" section so future sessions reach for the right enforcement: prefer rotated strong free-slip (machine-exact v_n=0, correct on curved/tilted/deformed boundaries, works inside the nonlinear SNES + geometric FMG, honours consistent_jacobian, and its reaction is sigma_nn); reserve Nitsche/penalty for BCs that must evolve in time. Points at utilities/rotated_bc.py. Underworld development team with AI support from Claude Code --- CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 73b2ec4b..e75f7095 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -319,6 +319,31 @@ The PETSc-based solvers are carefully optimized and validated. **NO CHANGES with --- +## Boundary Conditions: Free-slip + +**Prefer rotated strong free-slip** (`solver.add_rotated_freeslip_bc(boundary, normal=None)`) +to impose `v·n̂ = 0`: + +- Enforces zero wall-normal flow to **machine precision** (Nitsche / penalty leak ~1e-3). +- Correct on **curved / tilted / deformed** boundaries — the normal is taken per node + (pass an analytic `normal`, e.g. `X/|X|`, for an exact normal on curved faces). +- Works **inside the nonlinear SNES** and with **geometric FMG**. It honours + `solver.consistent_jacobian`: use `True` (consistent Newton) for smooth nonlinear + rheologies; `"continuation"` (staged Picard→Newton) for robustness far from the + solution. The rotated constraint is transparent to the tangent. +- The constraint **reaction** is the boundary normal traction σ_nn + (`solver.boundary_normal_traction(boundary)` / `solver.dynamic_topography(...)`) — no + augmented-Lagrangian splitting. + +**Reserve Nitsche / penalty** (`add_nitsche_bc`) for BCs that must **evolve in time** +(e.g. a Dirichlet→Neumann / traction ramp) — a hard rotated constraint cannot morph. + +**Implementation**: `src/underworld3/utilities/rotated_bc.py` (per-node rotation `Q`, +strong `v_n=0`, reaction = σ_nn); the solve dispatch is in +`src/underworld3/cython/petsc_generic_snes_solvers.pyx`. + +--- + ## Data Access Patterns **Authoritative Reference**: `docs/developer/UW3_Style_and_Patterns_Guide.md`