Files
SPHLite/docs/cclite_worker_diagnostics.md
T
2026-07-05 21:41:34 +08:00

2.8 KiB
Raw Blame History

CCLite Worker Diagnostics

文档状态:0.8.x worker adapter 当前实现说明

本文记录 worker 诊断输出的文件名、字段和验收边界。当前实现已经提供 log、particle report 和 force report 的路径解析、header 写入、记录追加和单元测试;真实跨进程 CCLite 联调仍需后续 self-test 验收。

1. 输出文件

文件 内容
sphlite_cclite_worker.log worker 启动参数、IPC 名称、命令、ack、状态、导出/导入计数、总力、总力矩和错误信息
sphlite_cclite_particle_report.csv 每次 EXPORT_INTERFACE 导出的粒子摘要和拒绝原因
sphlite_cclite_force_report.csv 每次 IMPORT_LOADS 接收的外部力、力矩、接触状态和拒绝原因

路径规则:

  • --log 指向 worker log 文件。
  • particle report 和 force report 默认写入 --log 所在目录。
  • 未提供 --log 时使用当前工作目录下的默认文件名。

2. Worker Log 字段

solver_id,case_file,ipc_name,command_block,data_prefix,command_event,
done_event,timeout_ms,worker_id,command_id,step_id,ack_sequence,
worker_state,exported_particles,exported_facets,received_forces,
total_fx,total_fy,total_fz,total_mx,total_my,total_mz,
nonfinite_particles,error_code,error_message

说明:

  • command_block、data_prefix、command_event、done_event 来自 worker IPC adapter。
  • exported_particles 来自粒子数据块 header。
  • exported_facets 当前保留为 0,等待 facet 数据块接入。
  • received_forces、total_force 和 total_moment 来自 force 数据块分析结果。
  • nonfinite_particles 记录导出粒子状态非有限拒绝计数。
  • error_code 和 error_message 记录启动、READY、命令执行和异常退出路径。

3. CSV 字段

particle report:

step_id,region_index,export_index,internal_index,external_id,
phase,status,material,section,x,y,z,vx,vy,vz,reject_reason

force report:

step_id,region_index,source_id,pair_id,target_id,export_index,
internal_index,fx,fy,fz,mx,my,mz,contact_state,reject_reason

拒绝原因使用 worker 契约中的枚举名称:

  • unmatched_particle
  • nonfinite_force
  • nonfinite_contact
  • invalid_weight
  • stale_epoch
  • repeated_import

4. 当前边界

  • worker 已能把有效 particle force 映射到 sphlite_coupling_apply_particle_forces。
  • worker 已能把 active/candidate/tied contact state 映射到 sphlite_coupling_apply_contact_state。
  • stale step、重复 force record、非有限值和无效权重会在进入 CouplingInterface 前拒绝并计数。
  • facet export、facet load 和 motion boundary 的真实数据块仍是后续工作。
  • VTU/PVD 仍是 SPHLite 求解输出复核手段,不替代 worker log 和 CSV 诊断。