feat(free-surface): uw.systems.FreeSurface manager#375
Open
lmoresi wants to merge 2 commits into
Open
Conversation
…ace integrator
Package the validated free-slip + prognostic dynamic-topography recipe as a
single user-facing object, uw.systems.FreeSurface. The user configures one
stress-free-top Stokes solve (constitutive model, driving body force, wall BCs,
options); FreeSurface reads it and owns the rest:
- derives the held rotated free-slip lid (constraint reaction sigma_nn -> h_inf
via dynamic_topography) and the consistent solve (prescribed surface-normal
velocity, so the surface stays a material boundary);
- runs the three-number L-stable exponential surface step;
- transports a composition (mesh level set / temperature) with enclosed-area
conservation;
- carries the surface increment inward with a Laplacian diffuser and deforms.
Surface nodes come from the DMPlex boundary stratum (label-based, parallel-correct)
rather than a |y-H| radial heuristic; estimate_dt adds a surface-motion cap on top
of the advective CFL; continuous pressure is checked (CBF recovery requirement).
Reproduces the reference driver (crameri_study Case-2, res48) to < 0.2% on surface
amplitude over two steps. Serial and np2 regression tests included.
v1 scope (documented in code): Cartesian vertical topography, and linear /
field-dependent viscosity (a strain-rate-dependent law is not yet supported on the
derived solves). Tangent-advection is deferred. These are the next work items.
Underworld development team with AI support from Claude Code
The derived held/consistent solves inherited two linear-only assumptions from the
Crameri driver; both are FreeSurface-local (the nonlinear solver subsystem is
unchanged and correct):
1. snes_type was hardcoded to "ksponly" on the derived solves — a single linear
solve. Now mirror the free solve's nonlinear configuration (snes_type +
consistent_jacobian): a nonlinear free solve gives nonlinear derived solves, a
linear one keeps its ksponly one-shot. (The rotated held solve additionally
auto-detects nonlinearity and dispatches its own linear/Newton path.)
2. The constitutive-model copy carried the free solve's velocity and velocity-
gradient symbols into the derived solves, so a strain-rate-dependent viscosity
computed itself from the free solution. This is a solver-copy / model-retarget
problem: a constitutive expression is tagged with its source solver's variable
identity. _copy_constitutive_model now unwraps the copied viscosity and rebinds
the source u and Unknowns.L atoms onto each derived solve's own (extracted as
_velocity_rebind_map; a no-op for linear / field-dependent viscosity). The derived
held solve is now bit-identical to an independently built self-consistent solve.
The retarget pitfall (and its adjoint-operator relevance) is documented in
docs/developer/subsystems/constitutive-models.md ("Retargeting a model to another
solver") so it is not re-hit.
Regression test (test_1070): a power-law free surface whose FreeSurface held solve
must equal a hand-built held solve using its own velocity — fails without the rebind,
passes with it. Linear Crameri result and np2 parallel test unchanged.
Underworld development team with AI support from Claude Code
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A user-facing manager,
uw.systems.FreeSurface, that packages the validated free-slip + prognostic dynamic-topography free-surface recipe (design note:FREESLIP_DYNAMIC_TOPOGRAPHY_FREESURFACE.md) as one object.The user configures a single stress-free-top Stokes solve;
FreeSurfacereads it and owns the rest:dynamic_topography) and the consistent solve (prescribed surface-normal velocity → material-boundary advection);mesh.deforms.Hardening (the three gaps)
|y-H|radial heuristic.estimate_dton top of the advective CFL.Nonlinear (strain-rate-dependent) viscosity
The derived held/consistent solves mirror the free solve's nonlinear configuration (
snes_type+consistent_jacobian) instead of a hardcodedksponly. The constitutive-model copy is a solver-retarget: a strain-rate viscosity is tagged with its source solver's velocity identity, so_copy_constitutive_modelunwraps and rebinds the free solve'su/Unknowns.Latoms onto each derived solve's own (_velocity_rebind_map). The derived held solve is then bit-identical to an independently built self-consistent solve. The retarget pitfall (and its adjoint-operator relevance) is documented indocs/developer/subsystems/constitutive-models.md.Validation
tests/test_1070_free_surface_plume.py: linear rise+relaxation+conservation, nonlinear self-consistency (power-law held solve == hand-built), and np2 parallel — all green.Remaining scope (next work items, documented in code)
Additive only: a new class behind a new export, plus a FreeSurface-local solver-copy fix; the nonlinear solver subsystem is unchanged.
🤖 Generated with Claude Code
Underworld development team with AI support from Claude Code