From d2cd1114ed9b89bbec5694ffbef4daf3735b8857 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 06:59:02 +0000 Subject: [PATCH 1/4] docs: supported settings for the 2D Jet + multilevel candidate One page listing supported settings, each with the guard enforcing it (file:line at c95a7ba) and the existing tests exercising it. Measured observations are labelled by their exact tested case (SRT strict-parity 1/4320 values ~2 ULP with unresolved cause; V3 TG constant explosion aggregate; curved-wall r1 pilot; V4 NOT_STEADY), not stated as general bounds. Documentation only. Co-Authored-By: Claude Opus 5.5 --- docs/supported_settings.md | 82 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/supported_settings.md diff --git a/docs/supported_settings.md b/docs/supported_settings.md new file mode 100644 index 0000000..6cd7d56 --- /dev/null +++ b/docs/supported_settings.md @@ -0,0 +1,82 @@ +# Supported settings: 2D Jet + fixed multilevel refinement (candidate c95a7ba) + +Every entry names the guard that enforces it (file:line at c95a7ba) and, where one +exists, an existing test that exercises it. A setting not listed here is not +claimed. Observations at the end are tied to the exact case in which they were +measured; they are not general bounds. + +## Lattice, storage, collision + +| Setting | Supported | Guard | +|---|---|---| +| Dimension / lattice | 2D D2Q9 only (3D refinement is future work) | `lbm/refinement.py:65`, `lbm/kernels/blocks.cu:25`, `lbm/kernels/refinement.cu:26` | +| Precision / streaming | FP32 storage, double buffer | same guards | +| Collision on refinement levels | SRT or MRT; TRT and LES rejected | `lbm/refinement.py:65`, `lbm/refinement.py:457` | +| Shifted (ddf_shifting) storage | only when every level is blocked; dense or mixed rejected | `lbm/refinement_stepper.py:198`, `:469`; `lbm/kernels/refinement.cu:26` (dense patch kernel unshifted only) | +| Fine relaxation | 1/tau_fine must lie inside the configured omega guards | `lbm/refinement.py:80` | +| Uniform blocked backend `PeriodicBlockStepper` | doubly periodic, SRT only, stationary passive circles | `lbm/block_stepper.py:84`, `:91`, `:45`-`:67` | + +Tests: `tests/unit/test_refinement_mrt.py`, `tests/validation/multigrid/test_refinement_mrt_gpu.py`, +`tests/unit/test_shifted_storage.py`, `tests/unit/test_shifted_block_operators.py`. + +## Refinement hierarchy (`FixedPatchStepper(cfg, *, context, refinements, ...)`) + +| Setting | Supported | Guard | +|---|---|---| +| Depth | at least one refinement level; one entry per level in `level_blocks`/`level_objects`/`level_jets` | `lbm/refinement_stepper.py:72`, `:75` | +| Single L1 rectangle | two-coarse-cell margin to the domain edge | `lbm/refinement.py:73` | +| Several L1 rectangles (union) | require `level_blocks[0]` and `level_blocks[1]`; transfers must close (dependency checks, no fixed gap rule) | `lbm/refinement_stepper.py:84`; `lbm/refinement.py:283`-`:295` | +| Nested levels | depth >= 3 must be all blocked; a blocked level requires blocked levels below; a scalar child needs a scalar parent | `lbm/refinement_stepper.py:82`, `:87`; `lbm/hierarchy.py:54` | +| Nested transfer support | child only over inherited ACTIVE cells, donors/receivers uncovered ACTIVE, no child over the parent restriction footprint | `lbm/refinement.py:391`-`:407` | +| Tile shape | `(by, bx)`; the level allocation must be divisible by the tile (no partial tiles yet) | `lbm/refinement_stepper.py:78`; `lbm/refinement.py:246` | +| Coarse boundary | `periodic`, `slot_reservoir` or `channel` | `lbm/refinement_stepper.py:177` | +| `slot_reservoir` | on-site velocity bottom slot, reservoir top, velocity 0, 2 <= slot width < nx, patch rows 4..ny-4 | `lbm/refinement_stepper.py:205`, `:212`; `lbm/refinement.py:546` | +| `channel` | all levels blocked; Zou-He inlet, pressure-NEQ outlet, stationary bounce-back walls; transfers away from the closure | `lbm/channel.py:22`, `:26`, `:43`, `:54` | +| Explosion | `constant` (default); `projected_linear` only periodic, all-blocked SRT, no bodies/Jets, no LES (experimental) | `lbm/refinement_stepper.py:188`, `:193` | +| L2 runtime remap (`remap_child`) | periodic three-level L2 sets only, no L0/L1 bodies, identical pinned boundary | `lbm/refinement_stepper.py:557`, `:567`-`:581` | + +Tests: `tests/unit/test_refinement_three_level_multipatch.py`, `tests/validation/multigrid/test_refinement_multipatch.py`, +`test_refinement_three_level.py`, `test_refinement_three_level_multipatch_gpu.py`, `test_refinement_blocked_base.py`, +`test_refinement_blocked_fine.py`, `test_channel_root_gpu.py`, `tests/unit/test_channel_root.py`, +`tests/unit/test_projected_pair_stepper.py`, `test_runtime_child_remap_gpu.py`, `test_pinned_body_remap_gpu.py`. + +## Bodies and Jets on refined levels + +| Setting | Supported | Guard | +|---|---|---| +| Bodies | stationary circles without sensor/force-region roles, entirely inside the patch union, fully resolved, disjoint, stencil away from the two-hop transfer footprint | `lbm/refinement.py:474`-`:542` | +| Level | not on L0; only on the finest level of a nested hierarchy | `lbm/refinement_stepper.py:80`, `:89` | +| Jet condition | velocity only; `pressure` is reserved and raises NotImplementedError | `body/jets.py:148`, `:150` | +| Jet geometry | each Jet selects resolved links of exactly one stationary body; no Jet/Jet or Jet/SurfaceActuation overlap; abs(amplitude) < 1 lattice | `body/jets.py:155`, `:175`, `:177`, `:255`, `:261`, `:263` | +| Jets with shifted storage | only in the all-blocked stepper with SRT and no LES | `body/jets.py:249` | +| SurfaceActuation | unshifted storage only | `body/objects.py:155` | +| Raw boundary exchange (force) | blocked body levels only; the window ledger requires `observe_raw_exchange` | `lbm/refinement_stepper.py:264`, `:269` | +| Checkpoint with Jets | refused | `simulation.py:687` | + +Raw exchange is the cut-link momentum reaction (wall + aperture), not a validated +nozzle thrust or stress load. Jet amplitude is a lattice velocity, not a flow rate. + +Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`, `test_raw_exchange.py`, +`tests/validation/multigrid/test_refinement_jets.py`, `test_shifted_jets_gpu.py`, `test_raw_exchange_gpu.py`, +`test_exchange_window.py`, `test_fine_surface_gpu.py`. + +## Observations from specific tested cases (not general bounds) + +- SRT channel root vs uniform OneStep, strict-parity case + (`tests/validation/multigrid/test_channel_root_gpu.py`): 1 of 4320 compared values differs, + max abs 2.33e-10, max rel 1.77e-7 (about 2 ULP). The test remains failed; its cause and any + general bound are unresolved. The corresponding MRT comparison is bitwise equal. +- Periodic Taylor-Green Re 100, current checkout 36ffc8b1 (V3 matched pair, N128 depth 2): + every per-sample screen passed; the constant explosion's aggregate worst velocity L2, + 0.004418, exceeds its preregistered 0.002 budget, while projected_linear passed that budget. +- Curved-wall pressure (pilot harness, exact-q analytic annulus, tau 0.8): the coarse swirl r1 + case exceeded its terminal density-gain cap (1.105e-4 vs 1e-4); r2/r4 stayed within the + frozen matrix limits. No validated fix exists. +- DFG 2D-1 Re 20 (V4, SRT, t* 60, pressure-NEQ outlet and local Zou-He inlet): refined and uniform + runs were NOT_STEADY under the frozen steady rule, so no interval verdict was given. + +## Not supported in this release + +3D, dynamic/automatic AMR (tagging, time-varying hierarchies beyond `remap_child`), +moving bodies on refined levels, pressure Jets, Jet checkpoints, LES or TRT on refined +levels, partial (non-dividing) tiles. From 8e9fc72e1901a6387122d139a07fed545b7bbcf6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 06:59:14 +0000 Subject: [PATCH 2/4] docs: curved-wall observation states only the recorded matrix outcome Co-Authored-By: Claude Opus 5.5 --- docs/supported_settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/supported_settings.md b/docs/supported_settings.md index 6cd7d56..8c09158 100644 --- a/docs/supported_settings.md +++ b/docs/supported_settings.md @@ -70,8 +70,8 @@ Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`, every per-sample screen passed; the constant explosion's aggregate worst velocity L2, 0.004418, exceeds its preregistered 0.002 budget, while projected_linear passed that budget. - Curved-wall pressure (pilot harness, exact-q analytic annulus, tau 0.8): the coarse swirl r1 - case exceeded its terminal density-gain cap (1.105e-4 vs 1e-4); r2/r4 stayed within the - frozen matrix limits. No validated fix exists. + case exceeded its terminal density-gain cap (1.105e-4 vs 1e-4), so the frozen 9-case matrix + is NOT_ESTABLISHED. No validated fix exists. This is a pilot harness, not production code. - DFG 2D-1 Re 20 (V4, SRT, t* 60, pressure-NEQ outlet and local Zou-He inlet): refined and uniform runs were NOT_STEADY under the frozen steady rule, so no interval verdict was given. From 1c47cb8570d5bef0c603a095b9986b407085311b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 07:05:34 +0000 Subject: [PATCH 3/4] docs: supported settings review fixes (exact parity test IDs, divisibility guard) Names the exact SRT/MRT parity tests and their sub-case scope (SRT: one of 18 sub-cases, unidentified; MRT: 12 sub-cases, default outlet settings, with the runs that recorded the pass), cites blocks.py:134 for tile divisibility, labels refinement.py:457 as the fine-boundary re-check, and says 'measured at 36ffc8b1' for the Taylor-Green observation. Co-Authored-By: Claude Opus 5.5 --- docs/supported_settings.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/supported_settings.md b/docs/supported_settings.md index 8c09158..cb58569 100644 --- a/docs/supported_settings.md +++ b/docs/supported_settings.md @@ -11,7 +11,7 @@ measured; they are not general bounds. |---|---|---| | Dimension / lattice | 2D D2Q9 only (3D refinement is future work) | `lbm/refinement.py:65`, `lbm/kernels/blocks.cu:25`, `lbm/kernels/refinement.cu:26` | | Precision / streaming | FP32 storage, double buffer | same guards | -| Collision on refinement levels | SRT or MRT; TRT and LES rejected | `lbm/refinement.py:65`, `lbm/refinement.py:457` | +| Collision on refinement levels | SRT or MRT; TRT and LES rejected | `lbm/refinement.py:65` (re-checked for fine boundaries at `lbm/refinement.py:457`) | | Shifted (ddf_shifting) storage | only when every level is blocked; dense or mixed rejected | `lbm/refinement_stepper.py:198`, `:469`; `lbm/kernels/refinement.cu:26` (dense patch kernel unshifted only) | | Fine relaxation | 1/tau_fine must lie inside the configured omega guards | `lbm/refinement.py:80` | | Uniform blocked backend `PeriodicBlockStepper` | doubly periodic, SRT only, stationary passive circles | `lbm/block_stepper.py:84`, `:91`, `:45`-`:67` | @@ -28,7 +28,7 @@ Tests: `tests/unit/test_refinement_mrt.py`, `tests/validation/multigrid/test_ref | Several L1 rectangles (union) | require `level_blocks[0]` and `level_blocks[1]`; transfers must close (dependency checks, no fixed gap rule) | `lbm/refinement_stepper.py:84`; `lbm/refinement.py:283`-`:295` | | Nested levels | depth >= 3 must be all blocked; a blocked level requires blocked levels below; a scalar child needs a scalar parent | `lbm/refinement_stepper.py:82`, `:87`; `lbm/hierarchy.py:54` | | Nested transfer support | child only over inherited ACTIVE cells, donors/receivers uncovered ACTIVE, no child over the parent restriction footprint | `lbm/refinement.py:391`-`:407` | -| Tile shape | `(by, bx)`; the level allocation must be divisible by the tile (no partial tiles yet) | `lbm/refinement_stepper.py:78`; `lbm/refinement.py:246` | +| Tile shape | positive `(by, bx)`; the level allocation must be divisible by the tile (no partial tiles yet) | `lbm/refinement_stepper.py:78`, `lbm/refinement.py:246` (shape); `lbm/blocks.py:134` (divisibility) | | Coarse boundary | `periodic`, `slot_reservoir` or `channel` | `lbm/refinement_stepper.py:177` | | `slot_reservoir` | on-site velocity bottom slot, reservoir top, velocity 0, 2 <= slot width < nx, patch rows 4..ny-4 | `lbm/refinement_stepper.py:205`, `:212`; `lbm/refinement.py:546` | | `channel` | all levels blocked; Zou-He inlet, pressure-NEQ outlet, stationary bounce-back walls; transfers away from the closure | `lbm/channel.py:22`, `:26`, `:43`, `:54` | @@ -62,11 +62,16 @@ Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`, ## Observations from specific tested cases (not general bounds) -- SRT channel root vs uniform OneStep, strict-parity case - (`tests/validation/multigrid/test_channel_root_gpu.py`): 1 of 4320 compared values differs, - max abs 2.33e-10, max rel 1.77e-7 (about 2 ULP). The test remains failed; its cause and any - general bound are unresolved. The corresponding MRT comparison is bitwise equal. -- Periodic Taylor-Green Re 100, current checkout 36ffc8b1 (V3 matched pair, N128 depth 2): +- SRT channel root vs uniform OneStep, strict-parity test + `tests/validation/multigrid/test_channel_root_gpu.py::ChannelRootGPU::test_uniform_matched_root`: + in one of its 18 sub-cases (2 storage modes x 3 profile/clamp/damp settings x 3 blocks; which + one is not recorded), 1 of the 4320 compared values differs, max abs 2.33e-10, max rel 1.77e-7 + (about 2 ULP). The test remains failed; its cause and any general bound are unresolved. +- MRT root parity test + `tests/validation/multigrid/test_refinement_mrt_gpu.py::RefinementMRTGPU::test_uniform_matched_mrt_root` + (12 sub-cases: 2 storage modes x 2 profiles x 3 blocks, default outlet settings) passed bitwise + in the Horsea GPU runs at K1 7813334 and on the combined tree f4372a8 (2026-10-21). +- Periodic Taylor-Green Re 100, measured at 36ffc8b1 (V3 matched pair, N128 depth 2): every per-sample screen passed; the constant explosion's aggregate worst velocity L2, 0.004418, exceeds its preregistered 0.002 budget, while projected_linear passed that budget. - Curved-wall pressure (pilot harness, exact-q analytic annulus, tau 0.8): the coarse swirl r1 From decd419e9413ecd9d2d34c890dcde753027e7a08 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 07:08:31 +0000 Subject: [PATCH 4/4] docs: cite only the recorded MRT parity pass (K1 7813334) Co-Authored-By: Claude Opus 5.5 --- docs/supported_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/supported_settings.md b/docs/supported_settings.md index cb58569..d217e4c 100644 --- a/docs/supported_settings.md +++ b/docs/supported_settings.md @@ -70,7 +70,7 @@ Tests: `tests/unit/test_jets.py`, `test_jets_review.py`, `test_shifted_jets.py`, - MRT root parity test `tests/validation/multigrid/test_refinement_mrt_gpu.py::RefinementMRTGPU::test_uniform_matched_mrt_root` (12 sub-cases: 2 storage modes x 2 profiles x 3 blocks, default outlet settings) passed bitwise - in the Horsea GPU runs at K1 7813334 and on the combined tree f4372a8 (2026-10-21). + in the Horsea focused GPU run at K1 7813334 (2026-10-21). - Periodic Taylor-Green Re 100, measured at 36ffc8b1 (V3 matched pair, N128 depth 2): every per-sample screen passed; the constant explosion's aggregate worst velocity L2, 0.004418, exceeds its preregistered 0.002 budget, while projected_linear passed that budget.