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

+1 -1
View File
@@ -14,7 +14,7 @@ Usage::
force = sim.read_force(0)
"""
__version__ = "0.4.0"
__version__ = "0.5.0"
from . import common, cuda, lbm, body, config
+3 -3
View File
@@ -28,7 +28,7 @@ Python `config.py` 只负责读取和校验,不是配置位置。
| 字段 | 类型 | 默认 | 允许值 | 说明 |
|------|------|------|--------|------|
| `collision` | string | `"SRT"` | `SRT`, `TRT`, `MRT` | 碰撞算子 |
| `streaming` | string | `"double_buffer"` | `double_buffer`, `esopull` | 流传输方式。运行时 body 拓扑同步 (``sync_bodies()``) 仅支持 ``double_buffer`` |
| `streaming` | string | `"double_buffer"` | `double_buffer`, `esopull` | 流传输方式。运行时 body 拓扑同步 (``sync_bodies()``) 两种模式均支持 |
| `store_precision` | string | `"FP32"` | `FP32`, `FP16S`, `FP16C` | GPU 存储精度。当前运行时已实现 `FP32` 与 `FP16S`,`FP16C` 仍为保留选项 |
| `ddf_shifting` | bool | false | | 存储 f−w 而非 f,提升 FP16 精度 |
| `les.enabled` | bool | false | | LES Smagorinsky 子格模型 |
@@ -93,8 +93,8 @@ step/one_step_*.cu → kernel 编排
### 运行时 body 拓扑同步
- 运行时增删 body(`add_body()` / `remove_body()` + `sync_bodies()`)仅支持 `streaming: "double_buffer"`。
- `esopull` 模式下调用 `sync_bodies()` 会抛出 `NotImplementedError`。
- 运行时增删 body(`add_body()` / `remove_body()` + `sync_bodies()`)在 ``double_buffer`` 和 ``esopull`` 两种流模式下均支持。
- 用法相同,无需特别的运行时检查。
### 力区域标记(Force region flag)
+51
View File
@@ -407,6 +407,57 @@ class LBMField:
# directly from Simulation.sync_bodies(). They are no longer methods on
# LBMField.
# -- EsoPull sync decode/encode (compact list) --------------------------
def esopull_sync_decode(self, patch_indices, step_count, stream=None):
"""Decode a subset of cells from EsoPull backing to physical DDF.
Args:
patch_indices: uint32 array of cell indices to decode.
step_count: Current step count (for EsoPull parity).
stream: Optional CUDA stream.
Returns:
(scratch_gpu, scratch_host, idx_gpu): scratch buffer handles.
"""
n = len(patch_indices)
nq = self.nq
scratch_gpu = cuda.mem_alloc(n * nq * 4)
scratch_host = np.empty(n * nq, dtype=np.float32)
idx_gpu = cuda.mem_alloc(n * 4)
cuda.memcpy_htod(idx_gpu, np.asarray(patch_indices, dtype=np.uint32))
fn = self.module.get_function("DecodeCellsToPhysical")
tpb = self.cfg.threads_per_block
fn(self.ddf_gpu, scratch_gpu, idx_gpu, np.uint32(n),
np.uint64(step_count),
block=(tpb, 1, 1), grid=((n + tpb - 1) // tpb, 1, 1),
stream=stream)
cuda.memcpy_dtoh_async(scratch_host, scratch_gpu, stream)
stream.synchronize()
return scratch_gpu, scratch_host, idx_gpu
def esopull_sync_encode(self, scratch_gpu, scratch_host, idx_gpu,
n, step_count, stream=None):
"""Upload patched physical DDF, collide + encode to EsoPull layout.
The backing layout stores post-collision values. This method
applies collision to the patched physical DDF before encoding,
matching the store_f_esopull convention at parity *step_count*.
Frees scratch_gpu and idx_gpu after encoding.
"""
cuda.memcpy_htod_async(scratch_gpu, scratch_host, stream)
fn = self.module.get_function("EncodePhysicalToCells")
tpb = self.cfg.threads_per_block
fn(self.ddf_gpu, scratch_gpu, idx_gpu, np.uint32(n),
np.uint64(step_count),
block=(tpb, 1, 1), grid=((n + tpb - 1) // tpb, 1, 1),
stream=stream)
scratch_gpu.free()
idx_gpu.free()
def snapshot(self):
self.download_ddf(force=True)
self._ddf_snap = self.ddf.copy()
+1
View File
@@ -69,5 +69,6 @@ extern "C"
#include "step/one_step_esopull.cu"
#include "step/aux_kernels.cu"
#include "step/esopull_macro.cu"
#include "step/esopull_sync.cu"
} // extern "C"
@@ -0,0 +1,81 @@
// CelerisLab -- step/esopull_sync.cu
// Compact-list EsoPull decode/encode for runtime body topology sync.
//
// Decodes a subset of cells from EsoPull backing layout to physical DDF,
// or encodes physical DDF back to EsoPull backing layout.
// Each thread handles one cell from a compact index list.
//
// Included by kernel_v2.cu. No standalone compilation.
// ============================================================================
#ifndef CELERIS_STEP_ESOPULL_SYNC_CU
#define CELERIS_STEP_ESOPULL_SYNC_CU
// ---------------------------------------------------------------------------
// DecodeCellsToPhysical: backing layout -> physical DDF (compact list)
//
// Uses ``t`` as the step count for EsoPull semantic parity decoding.
// ---------------------------------------------------------------------------
__global__ void DecodeCellsToPhysical(
const fpxx* fi,
float* fi_phys,
const unsigned int* cell_idx,
unsigned int n_cells,
unsigned long t)
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_cells) return;
unsigned long k = (unsigned long)cell_idx[tid];
unsigned int x, y; coordinates(k, x, y);
unsigned long j[NQ]; compute_neighbors(x, y, j);
float f[NQ];
load_physical_node_esopull(k, fi, j, t, f);
// DDF-shifting: backing layout stores f-w, unshift to physical for host patch
#if USE_DDF_SHIFTING
#pragma unroll
for (int i = 0; i < NQ; i++)
f[i] += (float)d_w[i];
#endif
for (int i = 0; i < NQ; i++)
fi_phys[tid * NQ + i] = f[i];
}
// ---------------------------------------------------------------------------
// EncodePhysicalToCells: physical DDF -> backing layout (compact list)
//
// Reads physical (pre-collision) DDF from *fi_phys*, applies collision
// to produce post-collision DDF, then encodes into the EsoPull backing
// layout on *fi*. The backing layout stores post-collision values,
// matching what store_f_esopull would produce at step *t*.
// ---------------------------------------------------------------------------
__global__ void EncodePhysicalToCells(
fpxx* fi,
const float* fi_phys,
const unsigned int* cell_idx,
unsigned int n_cells,
unsigned long t)
{
unsigned int tid = threadIdx.x + blockIdx.x * blockDim.x;
if (tid >= n_cells) return;
unsigned long k = (unsigned long)cell_idx[tid];
unsigned int x, y; coordinates(k, x, y);
unsigned long j[NQ]; compute_neighbors(x, y, j);
float f[NQ];
for (int i = 0; i < NQ; i++)
f[i] = fi_phys[tid * NQ + i];
// Collide: physical (pre-collision) -> post-collision
float rho_n, ux, uy;
compute_rho_u(f, rho_n, ux, uy);
collide_dispatch(f, rho_n, ux, uy);
store_physical_node_esopull(k, f, fi, j, t);
}
#endif // CELERIS_STEP_ESOPULL_SYNC_CU
+85 -30
View File
@@ -391,17 +391,9 @@ class Simulation:
def sync_bodies(self) -> None:
"""Apply pending body edits (add/remove) to a running simulation.
This is the main entry point for runtime body topology changes.
It downloads the current DDF, rebuilds topology, recompiles the
kernel for the new object count, patches the DDF for geometry
changes, and re-uploads everything to GPU.
Currently only supports ``double_buffer`` streaming mode.
``esopull`` mode raises ``NotImplementedError``.
Raises:
RuntimeError: If called before ``initialize()``.
NotImplementedError: If streaming mode is ``esopull``.
Supports both ``double_buffer`` and ``esopull`` streaming modes.
In EsoPull mode, the backing layout is decoded to physical DDF on
GPU for the patched cells only, patched on host, then encoded back.
"""
if not self._initialized:
raise RuntimeError("Call initialize() before sync_bodies()")
@@ -413,28 +405,34 @@ class Simulation:
if not self.bodies.has_pending_edit():
return
# 3. Check streaming mode
if self.lbm_cfg.streaming == "esopull":
raise NotImplementedError(
"Runtime body sync is not yet supported for esopull "
"streaming mode. Use double_buffer instead.")
is_esopull = (self.lbm_cfg.streaming == "esopull")
# 3. Build sync plan (same for both modes)
plan = self.bodies.build_sync_plan(self.field)
# 4. Obtain physical DDF on host (mode-dependent path)
if is_esopull:
patch_set = _build_patch_set(
plan.added_solid_mask, plan.released_fluid_mask,
plan.curved_host[0], nx=self.field.nx, ny=self.field.ny)
scratch_gpu, scratch_host, idx_gpu = \
self.field.esopull_sync_decode(
patch_set, self.stepper.step_count, self.stream)
_scatter_to_field(self.field, scratch_host, patch_set)
else:
self.field.download_ddf(
step_id=self.stepper.step_count, force=True)
# 4. Download current DDF to host (snapshot for patching)
self.field.download_ddf(
step_id=self.stepper.step_count, force=True)
old_ddf = self.field.ddf.copy()
old_flags = self.field.flag.copy()
# 5. Build sync plan
plan = self.bodies.build_sync_plan(self.field)
# 6. Runtime recompile for new object count
# 5. Runtime recompile for new object count
self._recompile(plan.next_count)
# 7. Apply new topology data (flags, compact lists, params)
# 6. Apply new topology data (flags, compact lists, params)
self.bodies.apply_sync_plan(self.field, plan)
# 8. DDF patch for geometry changes
# 7. DDF patch for geometry changes (works on physical DDF, mode-agnostic)
cl_fluid_idx = plan.curved_host[0]
patch_ddf_for_body_sync(
self.field,
@@ -442,11 +440,20 @@ class Simulation:
plan.added_solid_mask, plan.released_fluid_mask,
curved_fluid_indices=cl_fluid_idx,
)
upload_patched_ddf(
self.field,
plan.added_solid_mask, plan.released_fluid_mask,
curved_fluid_indices=cl_fluid_idx,
)
# 8. Upload patched DDF (mode-dependent path)
if is_esopull:
_gather_from_field(self.field, scratch_host, patch_set)
n = len(patch_set)
self.field.esopull_sync_encode(
scratch_gpu, scratch_host, idx_gpu,
n, self.stepper.step_count, self.stream)
else:
upload_patched_ddf(
self.field,
plan.added_solid_mask, plan.released_fluid_mask,
curved_fluid_indices=cl_fluid_idx,
)
# 9. Commit formal objects and clear pending
self.bodies.commit_pending(plan.next_objects, plan.new_sensor_counts)
@@ -649,3 +656,51 @@ class Simulation:
"""Validate object-count and obs layout contracts before stepping."""
self._assert_object_count_contract()
self._assert_obs_layout_contract()
# -- Module-level helpers -------------------------------------------------------
def _build_patch_set(added_solid_mask, released_fluid_mask, curved_fluid_idx,
nx=None, ny=None):
"""Return sorted uint32 array of cell indices that need DDF patching.
Includes a 1-cell halo because ``store_physical_node_esopull`` writes
to neighbor slots (D2Q9 directions 1,3,5,7). Neighbors must be
decoded/encoded together to avoid corrupting the backing layout.
"""
s = set()
s.update(np.where(added_solid_mask)[0].tolist())
s.update(np.where(released_fluid_mask)[0].tolist())
if curved_fluid_idx is not None:
s.update(curved_fluid_idx.tolist())
if nx is None or ny is None:
return np.array(sorted(s), dtype=np.uint32)
# Expand to include 1-cell halo (D2Q9 Moore neighbourhood)
expanded = set(s)
for idx in s:
x = idx % nx
y = idx // nx
for dx in (-1, 0, 1):
for dy in (-1, 0, 1):
if dx == 0 and dy == 0:
continue
xn, yn = x + dx, y + dy
if 0 <= xn < nx and 0 <= yn < ny:
expanded.add(xn + yn * nx)
return np.array(sorted(expanded), dtype=np.uint32)
def _scatter_to_field(field, scratch_host, patch_indices):
"""Copy decoded physical DDF from scratch buffer into field.ddf."""
nq = field.nq
for j, idx in enumerate(patch_indices):
field.ddf[idx * nq:(idx + 1) * nq] = scratch_host[j * nq:(j + 1) * nq]
def _gather_from_field(field, scratch_host, patch_indices):
"""Copy patched physical DDF from field.ddf back to scratch buffer."""
nq = field.nq
for j, idx in enumerate(patch_indices):
scratch_host[j * nq:(j + 1) * nq] = field.ddf[idx * nq:(idx + 1) * nq]