Add research measured-strain fluid refinement example

research/shear_refinement/README.md

@@ -0,0 +1,70 @@
+# One measured-strain refinement example
+
+Research only: one completed base-time observation, one possible growth-only
+fluid L2 enlargement, then two more base steps. L0/L1 and the Circle-containing
+L2 rectangle stay fixed. No scheduler, coarsening, packing, CUDA changes, or
+claim of accuracy, stable long-time adaptation, or optimal mesh selection.
+
+The periodic initial shear wave is evolved for two base steps. The downloaded
+postcollision G moments supply actual L1 velocity, at dx=.5 and the parent's
+physical origin. The tagger measures |S|=sqrt(2 S:S), not vorticity. We use
+s*=|S|/0.05, cutoff .001, no wall band/history/buffer. This deliberately small
+cutoff exercises the mechanism; it is not an error estimator or calibrated
+physical criterion. A high cutoff yields no change with the same observation.
+
+The eligible corridor is L1 indices [72,76) x [20,36), immediately right of the
+fluid child. Only L1 fluid leaves are valid gradient donors and owned voters;
+covered cells, holes and ghosts cannot supply gradients. L1 has no physical
+solid cells: the Circle is entirely in the fixed L2 patch. The cropped sparse
+arrays are never treated as a full periodic domain. One-sided derivatives may
+be used at missing-neighbor edges. Unknown gradients, unavailable corridor
+cells, and tags outside the corridor are reported separately. Ignored tags do
+not certify adequate resolution elsewhere. Old coverage is always retained.
+
+`grow_rectangle` knows only a rectangle, boolean requests, alignment and area
+cap. It returns an unchanged/enlarged tuple or raises ValueError before any
+solver mutation. The caller validates the entire proposed mesh with the
+existing RemapTopology and sparse-layout guards; remap_child repeats its full
+runtime checks. This example targets exactly the original mesh once, not a
+reusable adaptation loop. A rejection propagates explicitly; no partial
+proposal is installed. All solver instances are independently closed.
+
+## Run
+
+From repository root, with dependencies already available:
+
+    PYTHONPATH=src:. python -m unittest discover -s tests/unit -p test_shear_refinement_example.py -v
+
+Only on an approved idle CUDA device:
+
+    PYTHONPATH=src:. python -m research.shear_refinement.example
+    PYTHONPATH=src:.:tests/validation/multigrid python -m unittest discover -s tests/validation/multigrid -p test_shear_refinement_example_gpu.py -v
+
+The GPU gate compares automatic selection to an explicitly identical manual
+rectangle after short continuation, requires finite leaves, exact NaN masks,
+and an unchanged source. It does not replace independent numerical replay.
+GPU execution has not been performed in the implementation cloud environment.
+
+## Tagger provenance and license
+
+`boundary_shear_tagging.py` is the unchanged accepted Grok standalone v0.2
+preparation (2026-10-16), SHA256
+`12bc70ab989953501a752a2dc23e3712b6e69bfd47e67664c1771ff2dfa4da0b`.
+The delivered `README_boundary_shear_tagging_v0.2.md` identifies it as original
+code under MIT, the same license as CelerisLab (see repository LICENSE), with
+nothing copied from upstream examples. Its source ledger/review is in the
+preparation/grok_amr_review/v0.2 handoff. Vendoring keeps this example runnable
+without external preparation paths; it is not installed as production API.
+The separate reviewed level-request policy v0.2.1 is intentionally not copied:
+this example observes only L1 and can request only the existing L2 level.
+
+## Local implementation checks (2026-10-16)
+
+Seven focused example tests passed. The combined CPU suite below passed all
+60 tests, including existing topology, pinned-body and synchronized remap gates:
+
+    PYTHONPATH=src:. python -m unittest tests.unit.test_refinement tests.unit.test_refinement_three_level_multipatch tests.unit.test_pinned_body_remap tests.unit.test_runtime_child_remap tests.unit.test_synchronized_remap tests.unit.test_shear_refinement_example -q
+
+Broad unit discovery was also attempted; 14 legacy module imports failed
+because PyCUDA is absent. That broad run is not a pass. No installation or GPU
+execution was attempted. The example uses a passive Circle, with no Jet drive.