Document bounded multigrid and add public remap example

This commit is contained in:
TRON committed 2026-10-16 11:54:43 -07:00
1 parent 60ad6b8b0d
commit f75d543586
3 files changed
+190 -23

No files matched your search

+26 -10
View File
@@ -123,7 +123,7 @@ with CudaContext(0) as ctx, FixedPatchStepper(cfg, (8, 6, 24, 18), context=ctx,
```
Scope and limits:
- D2Q9, SRT, FP32, double buffer, unshifted, no LES or forcing; fixed 2:1 patch(es), two levels (or one nested third).
- D2Q9, SRT, FP32, double buffer, unshifted, no LES or forcing; fixed 2:1 patches, two or three levels with separated rectangles.
- `coarse_boundary="periodic"` (default) or `"slot_reservoir"` (bottom slot, top
reservoir; patch needs `y0 >= 4`, `y1 <= ny-4`). Periodic mode ignores the wall/slot config fields.
- Object centers/radii use the coarse **cell-edge** frame (cell `I` spans `[I, I+1)`),
@@ -144,7 +144,8 @@ Scope and limits:
not matter. `fine_objects`/`jets` work as for one patch: each circle (same
coarse cell-edge frame) must lie wholly inside one patch's active region with
its boundary stencil clear of transfer cells; a jet may not select links of two
different bodies, even across patches. No wall-touching patches or nesting yet.
different bodies, even across patches. Wall-touching patches are unsupported.
Three-level nesting uses the explicit child coordinates described below.
```python
cfg = LBMConfig(nx=32, ny=16, viscosity=.1)
@@ -164,7 +165,10 @@ Scope and limits:
ACTIVE cells, away from L1's ghost band and transfer footprint (checked before
any GPU allocation). `initialize` and `download` take/return three arrays; each
level is NaN on its non-ACTIVE (and child-covered) cells. One coarse step = 2 L1
steps = 4 L2 steps. One L1 patch only. Optional stationary circles and Jets
steps = 4 L2 steps. This scalar `child=` form uses one L1 patch.
For separated L1/L2 sets, use `child_rectangles_in_parent`; see
[coordinate frames and supported layouts](docs/fixed_three_level_multipatch.md).
Optional stationary circles and Jets
live on L2 via `child_objects` and `child_jets`; `fine_objects`/`jets` retain
their L1 meaning and must be empty in this mode. All object and Jet geometry
uses the **L0 edge frame**, not the child bounds' L1 window frame. L2 has
@@ -192,14 +196,26 @@ Scope and limits:
run.step(4)
coarse_g, l1_g, l2_g = run.download() # solids/covered/nonleaves are NaN
```
- Manual synchronized L2 replacement: `replacement = current.remap_child(rectangles,
child_objects=original_objects)` preserves the absolute step count and live Jet
amplitudes. L0/L1 and whole body-containing L2 rectangles stay fixed; separated
fluid rectangles may change. The source remains independently owned. See
[ownership, pinning and transfer rules](docs/synchronized_leaf_remap.md).
- Runnable three-level example: `PYTHONPATH=src python examples/multigrid_remap.py`.
It uses two separated L1 regions, an L2 stationary Circle/Jet and an explicit
fluid-rectangle move, retaining original root-frame body definitions. Add
`--check-geometry` for a CPU-only check or `--verify-jet` for an optional
next-step comparison with an explicitly driven control. No flowfiles are saved.
- Not available: per-link surface exchange/force readout in blocked mode,
checkpoints, moving bodies, L1 bodies/Jets in a three-level chain,
several patches per level with nesting, dynamic refinement, `Simulation`
integration. Validation so far is storage/operator equivalence and short runs,
not accuracy, convergence or long-time stability. The new L2-body GPU gates
(layouts, masks, amplitude reversal, legacy equivalence) and independent
every-substep numerical replay remain required acceptance checks; CPU tests
alone do not establish GPU numerical correctness.
checkpoints, moving bodies, L1 bodies/Jets in a three-level hierarchy,
arbitrary depth, automatic AMR or `Simulation` integration.
Storage/operator equivalence, remap and short-run gates do not establish
convergence or long-time physical accuracy. The earlier shear-decay result is
a research accuracy limitation, not a demonstrated solver bug. Pinned-body
replay conditioned on actual L1 feeds is not an independent whole-body solver.
See [three-level validation scope](docs/fixed_three_level_multipatch.md) and
[remap validation scope](docs/synchronized_leaf_remap.md). The new usage example
has CPU geometry/syntax checks only until its GPU command is run on Horsea.
## Installation