CelerisLab/docs/development/src_coherence.md

src coherence stage (from main 914906e)

Owner direction 2026-10-28: unified style over historical compatibility, inside src. 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). All three received parent/candidate generated-config and host/GPU equality checks. Only the collision slice ran a new PTX matrix (a4fc46d, whose src is identical to c5a3cdb); 65339ab and 442979b reused prior PTX evidence after unchanged CUDA/compiler and generated-input checks. In the collision matrix, only the two channel-root SRT modules changed PTX (omega load/clamp moved); their parent/candidate outputs matched exactly in the exercised cases.

Conventions (defined once, in lbm.hierarchy.Hierarchy)

• Level l = 0 .. depth-1 (0 = root). Pair hierarchy.pairs[l-1] builds level l.
• Array shapes are (ny, nx); rectangles, origins and centers are (x, y).
• Coarse/fine name the two members (parent/child) of ANY pair, not absolute L0/L1: fine_shape, fine_origin, prepare_fine_boundary, blocked_fine_tables, blocked_coarse_tables.
• Refined levels (l >= 1) of FixedPatchStepper place bodies/Jets in the root EDGE frame (root cell i = [i, i+1)). Uniform Simulation objects AND the static circles of a single-level (depth 1) FixedPatchStepper use the integer-NODE frame. Nothing converts between them. This concerns input placement only: within the EDGE frame, refined levels still project root-edge coordinates to fine-local cell indices with the half-cell shift (prepare_fine_boundary: (v - o)/dx - .5; hits back via fine_hits_to_edge_frame origin + dx*(hit + .5)), using edge_frame/fine_origin below.
• Hierarchy.edge_frame(l) -> ((ox, oy), h): cell (i, j) of level l's allocated array (ghost band and holes included) covers [o + h*i, o + h*(i+1)). A scalar FixedPatch2D window carries the half-coarse-cell ghost shift bounds - HALO/2 in fine_origin; a set's level-wide grid has origin 0. Level 1 boundaries are built from the root config (the wall-aware fields live there); deeper ones from the parent frame.
• FixedPatch2D.fine_level_offset (was fine_level_origin) is an array INDEX offset (y, x), not an (x, y) origin.

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]
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), _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)	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)
_level_name(l) "base/fine/child" messages	"level l"
refinement.MIN_PATCH_GAP	deleted (no gap policy exists)
params.cuh HaloPlan, collide_trt_no_force	deleted (zero references)

Kept: step_count, constructor keywords (refinements, level_blocks, level_objects, level_jets, coarse_boundary, explosion), Simulation.set_jet_amplitude(i, a) (one level), RemapTopology.from_config(..., child_objects=, child_jets=) (internal remap helper; "child" = the replaced level relative to its parent).

Responsibilities

• 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. 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

• Two per-level config derivations stay distinct on purpose: Hierarchy.configs (_middle_config, wall fields reset on every refined level, geometry validation) vs. 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. 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).