状态与对象修复报告

2026-10-10，state agent。按用户新授权实施局部修复；未实现 jet/AMR，未改外部 DynamisLab、原始生成头或 PTX。Simulation 集成由 root 负责。

范围与依据

已读 BRIEF.md 与 .github/skills/lbm-ref-architecture-guard/SKILL.md，复查当前 public API→ObjectManager→patch/field→checkpoint 链及 git 历史 987566c（runtime body sync）、04c2bc7（obs interval）。保留已有 runtime pending/discard 和 sync 重编号设计。物理约束为已有 D2Q9 topology patch、FP32/FP16S、两种 streaming 的地址/编码/阶段不变量；不以未知生产 Re/Ma 阻碍修复这些代数错误。

编码与阶段参考：

ref/FluidX3D/src/lbm.cpp:409–414：FP16S 存储乘 32768、读回除 32768；host 局部 patch 也必须走同一编码。
ref/FluidX3D/src/kernel.cpp:1332–1346：Esoteric Pull 的 load/store 空间映射和时间奇偶不同；推进 store 不是同 count 的读写逆。
ref/FluidX3D/src/kernel.cpp:1141–1154：新流体邻域只从 fluid donor 构建宏观量；本次保留原 BFS 方案，修正其实际读取布局。
ref/FluidX3D_analysis.md §2.1/2.2：本地设计背景；核实公式以实际参考代码及本库 descriptors/storage 为准。
PyCUDA async H2D/D2H 要求 page-locked host buffer。永久测试以拒绝 pageable async 的 driver double 验证调用契约；实际 GPU 验证由 root 统筹。

逐项处置

审查项	处置	具体边界
STATE-01 Q-major vs AoS	fixed	body patch 全部按 `field.ddf.reshape(nq,n)[:,cell]` 访问。EsoPull compact scratch 仍是 cell-major；root 修正 scatter/gather 转换
STATE-02 shift/FP16 越界	fixed	field `_encode_ddf` 是整场/局部编码共用实现；patch 按方向与连续 cell 段上传，用实际 store_bytes，未改 cells 的 GPU 字节保持原样
STATE-03 force action 丢失	fixed	set_force 同时更新现有 force-region `state.vx/vy` aliases；set_body_state 同步 omega。全 action refresh、重编号与 checkpoint 不再丢另一对象控制；未新建第三份控制架构
STATE-04 pre-init ID holes	fixed with explicit ID rule	立即 remove 后将剩余 registry dense 重编号，刷新 action；已有 runtime sync 重编号不变。之前返回的 numeric IDs 失效，由公开 remove 文档说明
STATE-05 checkpoint state/geometry/action	fixed, versioned	v2 保存实际 geometry/role/projection 指纹、host state/control、runtime params、已应用 device action 与 obs interval；不同几何先拒绝，匹配几何重建 compact lists/action。相同 count 不再充当 geometry 相等证明
STATE-06 same-step cache	fixed	load 后始终 invalidate_host_ddf_cache，即使恢复 step 等于缓存 step
STATE-07 field snapshot parity	fixed; field-only design retained	snapshot 不回退 clock/body/control。EsoPull 保存 same-count next-pull 物理分布，restore 按当前 count 编码；direct field EsoPull 调用缺 step_id 报错。精确时间回退用 checkpoint
STATE-08 overlay changes solid	fixed	先合成 solid occupancy，再只对 fluid 加 sensor/force annotations；compact lists 过滤 solid，sensor count 按有效 footprint 更新；实际 fluid footprint 重叠的多个 force_region 明确拒绝，以免并行同 cell 写竞争
STATE-09 async pageable buffers	fixed	action 使用持久 pinned staging；EsoPull scratch pinned，encode 完成后才 free；compact SoA stream upload 使用 pinned staging 并在返回前同步。无 stream 路径使用同步复制

field 的 GPU 入口添加 architecture 提供的 context_bound。root 将 field.ctx 绑定实例 owner；独立低层 field 未附 ctx 时保留“调用者已使 context current”的原约定，CPU driver-double 方法仍可运行。

Checkpoint 兼容性与选择

v2 读档在 GPU 写之前检查：lattice/extent/precision/streaming/shifting，dense IDs、geometry/role、实际投影指纹、重建 flags、array shape/dtype 与非负 step。不同几何不自动替换用户 case；调用者需构造匹配 case。匹配状态恢复后重建 host action、compact lists、params 与 obs，缓存失效。已应用 device action 单独保存，以保留 host 新目标尚未上传时的 run(upload_act=False) 时序。runtime params、obs interval 与 object state/control 在设备写之前完成转换和有限性检查。

保留有意的 collision/LES 等 parameter-study restart。若 viscosity 改变，使用当前 config 的 omega；不让 saved omega 覆盖用户新黏性。相同黏性可恢复原 runtime omega/forcing。

安全 v1 兼容范围：内置 CircleGeometry 的 circle/sensor，位置/半径/type/flags 必须一致；缺失 obs 明确清零 interval。v1 force_region 未保存真实控制，拒绝该类型并给出具体错误，不虚构恢复值；custom geometry 也不猜测。v1 无法恢复它从未记录的任意 runtime param，未宣称旧档具有 v2 完整性。

snapshot 明确保留 field-only 公共语义：跨奇偶恢复保证所保存的 next-pull 物理 field，不恢复时间与控制，也不声称恢复 t=0 初始化的特殊 wall 分支或整个运行历史。禁止把它描述成完整 checkpoint。

改动文件

src/CelerisLab/body/ddf_patch.py
src/CelerisLab/body/manager.py
src/CelerisLab/body/preprocess/flag_overlay.py
src/CelerisLab/lbm/field.py
src/CelerisLab/lbm/curved_links.py
src/CelerisLab/common/checkpoint.py
tests/unit/test_state_regressions.py
tests/integration/test_state_gpu.py（13 个有界 GPU cases，交 root 运行）

新增测试使用真实 class/method 与真实 h5py HDF5。仅 driver/device allocation/kernel invocation 用隔离 double；不是 AST 摘录、不是另写一份 host 实现。double 对每次复制检查 allocation 边界，async 时检查 pinned 来源；snapshot 的简化 parity 映射只检查 host 阶段协议，真实 EsoPull CUDA 数学由 numerical 的 actual-header 测试和 root GPU 验证负责。

实测

导入来源已核对为 /home/frank14f/CelerisLab/src/CelerisLab/__init__.py，解释器明确为 /home/frank14f/anaconda3/envs/pycuda_3_10/bin/python。

PYTHONPATH=/home/frank14f/CelerisLab/src \
/home/frank14f/anaconda3/envs/pycuda_3_10/bin/python -m pytest \
 tests/unit/test_state_regressions.py tests/unit/test_body_flags.py \
 tests/unit/test_pending_edits.py tests/unit/test_sync_plan.py -q

60 passed（0.38 s，2026-10-10 最终 state 范围）。覆盖四种 precision×shift、Q-major BFS donor、无关 cell 字节、control→remove→sync、双顺序 overlay、有效 sensor counts、force overlap rejection、pinned action/scratch/compact、field-only snapshot parity、checkpoint v2 roundtrip/拒绝前零设备写/同step缓存/黏性参数研究及 v1 兼容范围、malformed metadata 的拒绝前零设备写、host pending/device applied action 分别恢复。

交叉复核与剩余验证

已复核 numerical 的 same-time store 使用与 load 相同的 src_cell + slot，Encode 不碰撞且先转 shifted 表示；PrepareEsoPullWalls 在 curved apply 和 in-place streaming 之前同 stream 完成，pre-stream donors 不再被后续写入污染。接受其阶段修复。architecture 已独立复核 checkpoint/context/lifetime，接受核心修复；指出的 metadata late coercion 已修复并加入回归。其指出的 interval checkpoint obs 计数与外部 stream 同步由 root 修复。numerical 也独立读 field/checkpoint 并重跑 state 回归通过。

本 agent 独立重跑 tests/unit/test_numerical_operators.py：36 passed（28.57 s），支持上述跨模块复核。本 agent 未运行 GPU；root 已收到 ready 通知，并负责真实 CUDA、集成、资源关闭与 TRON handoff。D3 geometry topology patch 仍未实现，不在此修复中伪装支持。BFS 仍是已有的新流体初始化策略，本轮未给动态运动边界新增守恒算法或稳定性保证。

GPU 专项测试覆盖：4 个 EsoPull snapshot precision×shift 跨一步 parity；4 个 shifted topology add/remove；2 个两布局 checkpoint bitwise continuation；geometry mismatch 不修改设备；interval checkpoint observation normalization；host pending/device applied controls 的 upload_act=False 续跑。这里记录测试定义，不提前宣称 GPU 通过；实测由 root 最终日志给出。

8.3 KiB Raw Permalink Blame History Unescape Escape