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

72 lines
2.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 字段
```text
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:
```text
step_id,region_index,export_index,internal_index,external_id,
phase,status,material,section,x,y,z,vx,vy,vz,reject_reason
```
force report:
```text
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 诊断。