From 6d046f91c13f8563f1f4423529f30e1c45024a9b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 12:13:06 +0000 Subject: [PATCH] docs: sync src_coherence with the landed slices Stage history and verification, historical label on the migration map, host-preparation/device order, pair accessors, per-level state split into fixed plan structure / mutable boundary data / runtime _Level, the two block_collide families, and the deferred items with their evidence needs. Doc-only. Co-Authored-By: Claude Opus 5.5 --- docs/development/src_coherence.md | 58 +++++++++++++++++++++++-------- 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/docs/development/src_coherence.md b/docs/development/src_coherence.md index 8c8ab97..137b4a6 100644 --- a/docs/development/src_coherence.md +++ b/docs/development/src_coherence.md @@ -1,8 +1,11 @@ # src coherence stage (from main 914906e) Owner direction 2026-10-28: unified style over historical compatibility, inside `src`. -No numerical change is intended; kernel text was moved verbatim (PTX/bit parity is -pending a GPU run). +No numerical change is intended. Stages after 5f69eba: 65339ab (one boundary/Jet record, +host preparation helpers, pair accessors), c5a3cdb (`block_collide` families), 442979b +(exchange metadata on the boundary record). Each was checked by parent/candidate +config.h/PTX comparison and host/GPU equality runs; c5a3cdb changed the PTX of the two +channel-root SRT modules only (omega load/clamp moved, outputs exact). ## Conventions (defined once, in `lbm.hierarchy.Hierarchy`) @@ -28,6 +31,9 @@ pending a GPU run). ## FixedPatchStepper migration map +Historical: left column = names at or after 914906e that no longer exist; right column = +the current name. + | removed / changed | replacement | |---|---| | `patch`, `child_patch` | `hierarchy.pairs[0]`, `hierarchy.pairs[1]` | @@ -58,19 +64,35 @@ the replaced level relative to its parent). ## Responsibilities -- Construction: `_check_levels` (inputs), `_kernel_configs` (per-level kernel configs), - `Hierarchy.edge_frame` (geometry frames), `_build_level` / `_build_pair` / `_upload_boundary` - (device). Observation reads share `_observed_boundary` + `_summarize`. -- Lifecycles: `_layouts`, `_level_cfgs`, `_boundaries`, `_leaf`, `_state` are the immutable - construction plan (only a record's Jets/velocity column change, in `set_jet_amplitude`). They - are built and read by `_planned_bytes()` before any device allocation and stay readable after - `close()` (public views). `_Level` stays device-only: created after the memory preflight, - cleared on `close()`; its `.layout`/`.boundary` are references into the plan for `_hop`. - Folding the plan into `_Level` would mix both lifecycles in one record. +- Construction: `_check_levels` (inputs); host preparation, numpy only, before any device + work: `_level_layouts`, `_kernel_configs` (per-level kernel configs), `_host_boundaries`, + `_prepare_blocked_boundary`, `_fluid_leaves`; `Hierarchy.edge_frame` (geometry frames); + then `_planned_bytes()` (memory preflight) and `_build_level` / `_build_pair` / + `_upload_boundary` (device). A construction failure closes the partial instance. + Observation reads share `_observed_boundary` + `_summarize`. +- Pair accessors: `rectangles` (a scalar FixedPatch2D gives `(bounds,)`) and + `fine_level_offset` (`(0, 0)` for a set) on both pair types; the types and their + storage frames stay distinct. +- Per-level state, by lifecycle: + - Fixed plan structure (built once in `__init__`, read by `_planned_bytes()` before any + allocation, readable after `close()` through the public views): `_layouts`, + `_level_cfgs`, `_leaf`, `_state`, and in each `_boundaries[l]` record the host geometry + `.host`, link tables, `.jet_cache`, `.spacing`, `.centers`. + - Mutable boundary data in the same record: `.jets` and `.tables["surface_velocity"]`, + changed only by `set_jet_amplitude` (host prepare -> device write -> commit; an uncertain + write fails the instance); device handles (`.flags`, `.device`, `.kernel`, ledgers) are + set by `_upload_boundary` and cleared by `close()`. + - Runtime: `_levels` (`_Level`) holds compiled modules, kernels, the two population + buffers (swapped per step) and transfer/kind handles. It is created only after the + memory preflight and cleared on `close()`; `.layout`/`.boundary` reference the plan for + `_hop`. Folding the plan into `_Level` would mix both lifecycles in one record. - Blocked kernels: `operators/block_collision.cuh block_collide` is the one collision extension - point of `BlockStep` and `BlockChannelStep`. MRT shares one path; SRT keeps its two explicit - arithmetic variants (level: unclamped, no-force, shifted direct-momentum feq; channel: uniform - OneStep arithmetic with omega clamp), selected by `BLOCK_ROOT_BC`. + point of `BlockStep` and `BlockChannelStep`. It computes rho/u once and reads no runtime + force (`d_params.fx/fy`). Two compile-time families: uniform-equivalent (MRT on any level, + SRT on the channel root `BLOCK_ROOT_BC == 2`): clamped omega, `collide_mrt_no_force` or + `collide_srt` with its zero Guo term; and level SRT (`BLOCK_ROOT_BC` 0/1): unclamped omega, + `collide_srt_no_force`, with the shifted direct-momentum feq under `USE_DDF_SHIFTING`. + The uniform path keeps `collide_dispatch` (runtime force, LES, TRT). - `explosion="projected_linear"` stays an optional capability; `"constant"` stays default. ## Not done / open @@ -80,6 +102,12 @@ the replaced level relative to its parent). `FixedPatchStepper._kernel_configs` (reset only on level 1 of a slot_reservoir root; generates each level's config.h). Folding them needs a config.h/PTX diff gate. - No single-`Simulation` facade over FixedPatchStepper: the two own different state models - (uniform node frame, body sync, forcing, checkpoint vs. immutable blocked hierarchy, edge + (uniform node frame, body sync, forcing, checkpoint vs. fixed blocked hierarchy, edge frame, remap-as-new-instance). A facade would only forward calls; no concrete need found. +- Deferred, each needing its own evidence first: sharing the channel-root cell/donor selector + with OneStep (the closure functions are already shared; a shared selector changes uniform + signatures and needs a uniform PTX gate); merging FixedPatch2D into FixedPatchSet2D + (different origin, ghost band, layout size and addressing; needs a geometry/parity table and + would need tiles that are not grid-aligned); one `clamp_omega` helper for uniform and + blocked paths (it lives in the hash-pinned LES header `turbulence_smag.cuh`). - Tests, examples and validation callers are migrated separately (pinned runners stay frozen).