feat(esopull): runtime body sync for EsoPull streaming mode

- New esopull_sync.cu: DecodeCellsToPhysical + EncodePhysicalToCells
  (compact-list mode, ddf_shifting-aware, encode applies collision).
- sync_bodies() now branches for double_buffer vs esopull: decode
  backing layout to physical DDF on GPU -> host patch -> collide +
  encode back to backing layout. No temp_gpu, no full-grid copy.
- 4 new integration tests covering esopull add/remove/cycle/roundtrip.
- ddf_shifting + esopull + sync_bodies jointly verified (1300 steps
  stable after add/remove).
- Bump version to 0.5.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Frank14fandCursor committed 2026-06-21 22:31:02 +08:00
1 parent 04c2bc75ea
commit 00b957f904
10 files changed
+343 -75

No files matched your search

+3 -4
View File
@@ -195,7 +195,6 @@ kernel launches on a user-provided stream, then sync and read later.
`sync_bodies()` applies all staged body edits (added via `add_body()` and removed via `remove_body()`) to a running simulation without full reinitialization. The GPU flow field is preserved; only the body-related topology is rebuilt.
**Limitations:**
- Requires `streaming: "double_buffer"` (esopull raises `NotImplementedError`)
- Abrupt body introduction causes a transient; force readback is finite but may take 50+ steps to settle
- Verified for `"circle"` type bodies; sensors and force_regions are also expected to work
(they produce no curved links so the DDF patch is simpler)
@@ -365,6 +364,7 @@ Current verification scope:
- 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)
- 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
@@ -389,13 +389,12 @@ Stores `f_i - w_i` instead of `f_i` to improve FP16 accuracy. Supported with th
|-----------|-----------|-------|-------------|--------|
| 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 | any | any | Not yet verified |
| MRT | esopull | zou_he_local | cylinder | Verified (sync_bodies tested) |
| SRT | double_buffer | any | cylinder | Expected to work (f-feq style) |
**Known limitations (ddf_shifting):**
- Verified configuration: **D2Q9 + MRT + double_buffer + zou_he_local** only
- 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`
- `esopull + ddf_shifting` has not been jointly validated
- 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)