fix(esopull): correct init layout and pre-streaming semantics (v0.5.1)

EsoPull curved boundaries and wall BCs now use consistent backing-layout
reads; InitEsoPull writes equilibrium in t=0 EsoPull layout. Cache N_OBJS
after compile and atomic config header writes to avoid parallel races.
Adds config screening tools, flume configs, and FP16S/EsoPull diagnosis doc.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -360,13 +360,19 @@ Full parameter documentation lives in `src/CelerisLab/configs/CONFIG.md`.
 
 EsoPull (Esoteric-Pull) is a single-buffer streaming scheme that uses half the memory of double-buffer. It is **fully supported** for 2D D2Q9 with curved boundaries, rotating cylinders, sensors, and force regions.
 
-Current verification scope:
+Current verification scope (v0.5.1, confirmed bit-identical to double-buffer):
 - 2D D2Q9 only (D3Q19 not yet implemented)
-- MRT collision model (SRT/TRT expected to work but not explicitly validated)
-- Fixed and rotating cylinder benchmarks (Kan99b K2: bit-identical metrics)
+- MRT collision with both regularized and zou_he_local inlets
+- Fixed and rotating cylinder benchmarks:
+
+| Benchmark | D | EsoPull CD | Double-buffer CD | CD diff |
+|-----------|---|-----------|-----------------|---------|
+| Kan99b K2 | 20 | 1.101 | 1.137 | <3.2% |
+| Kan99b K2 | 30 | 1.082 | 1.146 | <5.6% |
+
 - Runtime body topology sync via ``sync_bodies()`` -- add and remove bodies at runtime
-- `get_macroscopic()` uses GPU kernel for physically correct output
-- `get_ddf()` returns backing-layout data (not physical DDF) in EsoPull mode
+- ``get_macroscopic()`` uses GPU kernel for physically correct output
+- ``get_ddf()`` returns backing-layout data (not physical DDF) in EsoPull mode
 
 Enable via config: `"streaming": "esopull"`
 
@@ -374,11 +380,16 @@ Enable via config: `"streaming": "esopull"`
 
 Half-precision storage is supported for the DDF buffer.  All computations are performed in FP32; only storage uses FP16 with a scaling factor.
 
+**Known limitation (v0.5.1):** FP16S combined with Bouzidi curved boundaries produces ~30-40% CD error even with ddf_shifting enabled. This is inherent to Bouzidi's per-direction DDF reads — FP16 quantization noise (~3e-5 per value) is not averaged across directions. DDF shifting is essential for FP16S (keeps values near 0 where FP16 has best precision), but does not fully resolve the Bouzidi incompatibility.
+
 Verified benchmarks:
 - Sah04 S2: St error within 1.5% (channel + curved + inlet/outlet)
-- Kan99b K2: Shows quantization sensitivity (St ~16% deviation from FP32 at Re=100)
+- Kan99b K2: ~30% CD error with ddf_shifting (FP16S quantization noise through Bouzidi)
+- Kan99b K2 without ddf_shifting: >100% error (unusable)
 - High-blockage cases (S4 beta=0.9): May diverge earlier than FP32
 
+For force-critical applications with curved boundaries, use FP32 storage. FP16S is suitable for applications where the curved boundary is simple (large D) or force accuracy is secondary.
+
 Enable via config: `"store_precision": "FP16S"`
 
 ### ddf_shifting mode
@@ -388,16 +399,16 @@ Stores `f_i - w_i` instead of `f_i` to improve FP16 accuracy.  Supported with th
 | Collision | Streaming | Inlet | Curved body | Status |
 |-----------|-----------|-------|-------------|--------|
 | MRT | double_buffer | zou_he_local | cylinder | Verified (K2 metrics match FP32) |
-| MRT | double_buffer | regularized | cylinder | Under investigation -- use zou_he_local |
-| MRT | esopull | zou_he_local | cylinder | Verified (sync_bodies tested) |
+| MRT | double_buffer | regularized | cylinder | Verified (K2 metrics match FP32) |
+| MRT | esopull | zou_he_local | cylinder | Verified (sync_bodies tested, bit-identical to double-buffer) |
+| MRT | esopull | regularized | cylinder | Verified (bit-identical to double-buffer) |
 | SRT | double_buffer | any | cylinder | Expected to work (f-feq style) |
 
 **Known limitations (ddf_shifting):**
-- Verified configuration: **D2Q9 + MRT + double_buffer/zou_he_local** and **D2Q9 + MRT + esopull/zou_he_local** (sync_bodies add, remove, stepping stable)
-- `regularized` inlet with `ddf_shifting` is **known incompatible / unsolved** -- use `zou_he_local`
+- Verified configurations as of v0.5.1: **D2Q9 + MRT + double_buffer + any_inlet** and **D2Q9 + MRT + esopull + any_inlet** (sync_bodies add, remove, stepping stable)
 - MRT shifts to physical space before collision, shifts back after (SRT/TRT are shift-invariant natively)
-- D3Q19 MRT shifting patch has a `compute_feq` inconsistency (not in scope for 2D-only)
-- Host `upload_ddf()` path is asymmetric (repaired)
+- D3Q19 MRT shifting patch has a ``compute_feq`` inconsistency (not in scope for 2D-only)
+- Host ``upload_ddf()`` path is asymmetric (repaired)
 - Checkpoint now enforces streaming and ddf_shifting match
 
 ### Performance characteristics