From 3361e97d5f233f040c5c16af63d2fd0ff7c06621 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 12:09:26 +0000 Subject: [PATCH] docs: src_coherence migration map for the combined _boundaries record Final private names (_device_boundaries/_level_jets/_exchange_*/_level_blocks -> _boundaries record fields / layout.block), public boundaries = host view, and the plan-versus-device (_Level) lifecycle. Doc-only. Co-Authored-By: Claude Opus 5.5 --- docs/development/src_coherence.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/development/src_coherence.md b/docs/development/src_coherence.md index 8d537b0..8c8ab97 100644 --- a/docs/development/src_coherence.md +++ b/docs/development/src_coherence.md @@ -34,14 +34,16 @@ pending a GPU run). | `base_layout`, `fine_layout`, `child_layout` (stepper properties) | `layouts[0]`, `layouts[1]`, `layouts[2]` (`FixedPatchSet2D.fine_layout(block)` is unchanged) | | `fine_boundary`, `child_boundary` | `boundaries[1]`, `boundaries[2]` (host geometry; `None` = no bodies/Jets) | | `_jets` | `jets[1]` | -| `_boundaries[l]` (dict from L1, level keys) | `_device_boundaries[l]` (list from L0, `None` at L0 unless single-level static circles) | -| `_level_boundaries` (private, b4eacf7) | `_device_boundaries` | -| `_fine_tables`, `_actuated`, `_jet_cache` | `_device_boundaries[1].tables` / `.actuated` / `.jet_cache` | +| `_boundaries[l]` (dict from L1, level keys), `_level_boundaries` (b4eacf7), `_device_boundaries` (65339ab) | `_boundaries[l]`: the one combined per-level `_BlockedBoundary` record (list from L0, `None` at L0 unless single-level static circles): host geometry `.host`, `.tables`, `.jets`, `.jet_cache`, exchange `.spacing`/`.centers`, device handles | +| `_fine_tables`, `_actuated`, `_jet_cache` | `_boundaries[1].tables` / `.actuated` / `.jet_cache` | +| `_level_jets` (private) | `_boundaries[l].jets` (public `jets[l]` is derived) | +| `_exchange_spacing[l]`, `_exchange_centers[l]` (private) | `_boundaries[l].spacing` (h_l, root units) / `.centers` (root edge frame); only levels with a boundary report exchange | +| `_level_blocks` (private) | `_layouts[l].block` | | `_remap_cfg` (private) | `_root_cfg` | | `refinement_tables.blocked_base_tables` (also via `refinement_stepper`) | `refinement_tables.blocked_coarse_tables` (import from `refinement_tables`; the stepper no longer re-exports) | | `_fine_leaf`, `_child_leaf` | `leaf[1]`, `leaf[2]` (copies) | | `_middle_kind` | `hierarchy.kinds[1]` | -| `_boundary_hosts` (private) | `_boundaries` (private list behind `boundaries`) | +| `_boundary_hosts` (private) | public `boundaries[l]` = `_boundaries[l].host` (host geometry only; the private record is the combined one) | | `remap_child(rects, child_objects=...)` | `remap_finest(rects, objects=...)` | | `set_jet_amplitude(i, a)` (implicit level 1) | `set_jet_amplitude(i, a, level=l)` (required) | | `read_raw_exchange(b)` / `read_exchange_window(b)` (implicit level 1) | `read_raw_exchange(b, level=l)` / `read_exchange_window(b, level=l)` (required) | @@ -59,6 +61,12 @@ the replaced level relative to its parent). - 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. - 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