diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..aa5cff4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +build*/ +*.o +*.obj +*.mod +*.smod +*.a +*.lib +*.dll +*.exe +*.pdb +*.ilk +*.log +*.tmp +__pycache__/ +*.pyc +*.csv +*.vtk +*.vtu +*.vtp +*.restart +verification_report.json diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..816fd42 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,41 @@ +cmake_minimum_required(VERSION 3.20) + +project(CCLite VERSION 0.1.0 LANGUAGES Fortran) + +set(CMAKE_Fortran_STANDARD 2018) +set(CMAKE_Fortran_STANDARD_REQUIRED ON) + +enable_testing() + +set(CCL_COMMON_SOURCES + src/common/ccl_version.f90 + src/common/ccl_errors.f90 + src/common/ccl_log.f90 +) + +add_library(ccl_common STATIC ${CCL_COMMON_SOURCES}) + +add_executable(cclite + src/app/cclite_main.f90 +) +target_link_libraries(cclite PRIVATE ccl_common) + +add_library(ccl_mock_common STATIC + src/mock_workers/ccl_mock_worker.f90 +) +target_link_libraries(ccl_mock_common PRIVATE ccl_common) + +add_executable(mock_sph_worker + src/mock_workers/mock_sph_worker_main.f90 +) +target_link_libraries(mock_sph_worker PRIVATE ccl_mock_common ccl_common) + +add_executable(mock_fem_worker + src/mock_workers/mock_fem_worker_main.f90 +) +target_link_libraries(mock_fem_worker PRIVATE ccl_mock_common ccl_common) + +add_test(NAME smoke_cclite_version COMMAND cclite --version) +add_test(NAME smoke_cclite_help COMMAND cclite --help) +add_test(NAME smoke_mock_sph_worker_version COMMAND mock_sph_worker --version) +add_test(NAME smoke_mock_fem_worker_version COMMAND mock_fem_worker --version) diff --git a/cases/README.md b/cases/README.md new file mode 100644 index 0000000..7d5a1c7 --- /dev/null +++ b/cases/README.md @@ -0,0 +1,5 @@ +# cases + +CCLite verification and acceptance cases. + +0.1.x will add `v0_1_ipc_empty_coupling` for `V010_EMPTY_COUPLING`. diff --git a/cases/v0_1_ipc_empty_coupling/README.md b/cases/v0_1_ipc_empty_coupling/README.md new file mode 100644 index 0000000..da49f30 --- /dev/null +++ b/cases/v0_1_ipc_empty_coupling/README.md @@ -0,0 +1,5 @@ +# V010_EMPTY_COUPLING + +0.1.x empty coupling acceptance case. + +The case will be filled after the `.inp` parser, IPC layer and mock workers are implemented. diff --git a/docs/04_mathematical_model_and_algorithms.md b/docs/04_mathematical_model_and_algorithms.md new file mode 100644 index 0000000..e7dba6a --- /dev/null +++ b/docs/04_mathematical_model_and_algorithms.md @@ -0,0 +1,1123 @@ +# CCLite 数学模型与算法说明书 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文档版本**:V0.2 草案 +**软件名称**:CCLite +**文档定位**:全开发周期数学模型与算法总纲 +**实现基线**:Fortran95 算法核心 + Fortran2018/C IPC 数据通信层 +**输入基线**:Abaqus 风格 `.inp` +**第一阶段平台**:Windows / gfortran / 本机共享内存 + +--- + +# 1. 文档定位与算法边界 + +## 1.1 文档目的 + +本文档定义 CCLite 在整个开发周期内采用的数学模型、算法边界、符号体系、几何模型、接触模型、耦合模型、时间耦合框架、稳定性控制和诊断量。 + +本文档是 CCLite 的算法理论总纲,不是单一版本实现清单。具体实现结构、通信接口和测试验收分别由 03、05、06 号文档进一步约束。 + +## 1.2 算法责任 + +CCLite 只处理 SPHLite 与 FEMLite 之间的跨域界面问题,包括: + +1. SPH 粒子/边界粒子与 FEM 边界面之间的几何搜索; +2. SPH-FEM 接触检测; +3. SPH-FEM 接触力、界面力、压力、牵引和冲量传递; +4. SPH-FEM tied coupling、release 和 tie-to-contact 转换; +5. SPH-FEM FSI 界面压力、速度和边界状态传递; +6. 时间耦合、子循环、松弛和强耦合迭代框架; +7. 界面守恒、能量、动量、接触和通信诊断。 + +CCLite 不处理: + +1. SPH 内部控制方程、EOS、本构和邻域求和; +2. FEM 单元刚度、质量、内力、本构和内部接触; +3. SPHLite/FEMLite 的网格、粒子和几何前处理; +4. SPHLite/FEMLite 私有状态更新。 + +## 1.3 引用与自洽规则 + +第 4 章和第 5 章会直接影响软件架构,必须遵守以下规则: + +1. 采用成熟算法时,正文给出引用标号,并在第 13 章列出出处; +2. 没有明确出处时,必须补充完整公式、变量定义和伪代码; +3. CCLite 自行规定的算法写为“CCLite 工程约定”; +4. 未进入当前实现周期的算法必须明确标注实现版本; +5. 引用、公式、伪代码和实现状态必须能被 05 号接口文档和 06 号测试文档追踪。 + +--- + +# 2. 符号、坐标与单位约定 + +## 2.1 基本符号 + +| 符号 | 含义 | +| --- | --- | +| `i` | SPH 粒子编号 | +| `a` | FEM facet 编号 | +| `A` | FEM 节点编号 | +| `x_i` | SPH 粒子当前位置 | +| `v_i` | SPH 粒子速度 | +| `a_i` | SPH 粒子加速度 | +| `m_i` | SPH 粒子质量 | +| `rho_i` | SPH 粒子密度 | +| `p_i` | SPH 粒子压力 | +| `h_i` | SPH 粒子光滑长度 | +| `r_i` | SPH 粒子接触半径 | +| `x_A` | FEM 节点当前位置 | +| `v_A` | FEM 节点速度 | +| `n_a` | FEM facet 单位法向 | +| `A_a` | FEM facet 面积 | +| `t_a` | FEM 壳厚度 | +| `N_A` | facet 最近点处节点权重 | +| `x_c` | SPH 粒子到 FEM facet 的最近点 | +| `v_c` | 最近点处 FEM 速度 | +| `g` | 法向间隙 | +| `d` | 穿透量 | +| `f_i` | CCLite 作用于 SPH 粒子的界面力 | +| `F_A` | CCLite 作用于 FEM 节点的界面力 | +| `dt` | CCLite 耦合时间步 | + +## 2.2 坐标和法向 + +CCLite 采用全局笛卡尔坐标系。向量默认按三维列向量理解。 + +FEM facet 法向 `n_a` 优先由 FEMLite 导出。CCLite 可在单个接触对内部构造修正法向 `n`,但不得修改 FEMLite 原始 facet 法向。 + +法向正负约定: + +```text +n 由 FEM 最近点 x_c 指向 SPH 粒子 x_i +``` + +若 FEMLite 导出的 `n_a` 与该方向相反,则接触对局部采用: + +```text +n = -n_a +``` + +## 2.3 单位 + +CCLite 不强制单位体系。SPHLite、FEMLite 和 CCLite 输入必须使用一致单位。CCLite 输出不做单位换算。 + +--- + +# 3. 界面数据抽象 + +## 3.1 SPH 侧数学对象 + +SPH 粒子数学状态记为: + +```text +P_i = { id_i, phase_i, status_i, material_i, section_i, + m_i, rho_i, p_i, h_i, r_i, x_i, v_i, a_i } +``` + +SPH 侧 region 是粒子集合: + +```text +R_s = { P_i | i in I_s } +``` + +后续版本可引入 SPH 壳粒子、boundary particle、ghost particle 和 SPH facet proxy。它们均视为 SPH 侧公开界面对象,不视为 CCLite 私有求解状态。 + +## 3.2 FEM 侧数学对象 + +FEM facet 数学状态记为: + +```text +S_a = { facet_id_a, node_ids_a, x_A, v_A, n_a, A_a, t_a } +``` + +FEM surface 是 facet 集合: + +```text +S_f = { S_a | a in I_f } +``` + +FEM facet 上任意点的坐标和速度由节点插值得到: + +```text +x(u,v) = sum_A N_A(u,v) x_A +v(u,v) = sum_A N_A(u,v) v_A +``` + +## 3.3 界面对象 + +CCLite 界面对象为: + +```text +I = { R_s, S_f, M } +``` + +其中 `M` 是界面算法族,例如 contact、tie、pressure projection 或 Riemann FSI。 + +--- + +# 4. 几何搜索与接触检测模型 + +## 4.1 本章定位 + +本章定义 CCLite 所有接触与耦合算法共用的几何基础。宽相搜索、最近点、壳厚度、边缘 fallback 等算法直接决定 05 号文档中的数据字段和后续 Fortran 数据结构。 + +本章中通用碰撞检测、AABB、最近点和层次包围体概念参考计算几何和实时碰撞检测资料 [Ericson2005]。BVH/OBBTree 作为后续预留时参考 [Gottschalk1996]。uniform spatial hashing 作为动态点-面宽相搜索方案时参考 [Teschner2003]。 + +## 4.2 几何 primitive + +### 4.2.1 SPH 粒子 primitive + +第一阶段将 SPH 粒子建模为球形接触 primitive: + +```text +B_i = { x | ||x - x_i|| <= r_i } +``` + +其中 `x_i` 是粒子中心,`r_i` 是接触半径。 + +CCLite 工程约定: + +1. 若 SPHLite 显式导出 `r_i`,则直接使用; +2. 若 SPHLite 只导出 `h_i`,则允许通过输入参数 `alpha_r` 定义 `r_i = alpha_r h_i`; +3. `alpha_r` 必须写入 `cclite.inp` 或采用文档化默认值; +4. 该半径只用于跨域接触,不改变 SPHLite 内部光滑核。 + +### 4.2.2 FEM facet primitive + +FEM 三角形 facet: + +```text +T_a = { x_1, x_2, x_3, n_a, A_a, t_a } +``` + +FEM 四边形 facet: + +```text +Q_a = { x_1, x_2, x_3, x_4, n_a, A_a, t_a } +``` + +四边形第一阶段采用三角形拆分: + +```text +Q_a -> T_a^1 = (x_1, x_2, x_3) +Q_a -> T_a^2 = (x_1, x_3, x_4) +``` + +该方案是 CCLite 工程约定。优点是实现简单、可复用 point-triangle 算法;局限是非平面四边形的最近点会依赖拆分对角线。后续版本可增加双线性四边形投影。 + +### 4.2.3 FEM 壳 primitive + +FEM 壳面采用中面 + 厚度模型: + +```text +S_a^shell = { mid-surface facet S_a, thickness t_a } +``` + +CCLite 不在几何层重构壳截面;壳厚度只进入接触距离和诊断。 + +## 4.3 AABB 与包围盒扩展 + +SPH 粒子的 AABB: + +```text +AABB_i.min = x_i - (r_i + delta_s) [1,1,1] +AABB_i.max = x_i + (r_i + delta_s) [1,1,1] +``` + +其中 `delta_s` 是搜索裕量。 + +FEM facet 的 AABB: + +```text +AABB_a.min_k = min_A x_Ak - (0.5 t_a + delta_s) +AABB_a.max_k = max_A x_Ak + (0.5 t_a + delta_s) +``` + +对于实体 facet,`t_a = 0`。 + +## 4.4 宽相搜索 + +第一阶段采用 uniform hash grid。其目标是从 SPH 粒子集合 `R_s` 和 FEM facet 集合 `S_f` 中生成候选对集合: + +```text +C = { (i,a) | AABB_i intersects AABB_a } +``` + +cell size 取: + +```text +l_cell = beta_cell * max(r_i + 0.5 t_a + delta_s) +``` + +第一阶段默认 `beta_cell >= 1`。若局部粒径差异很大,应在 0.8.x 后引入多层 grid 或 BVH。 + +宽相伪代码: + +```text +build_fem_grid(fem_facets): + clear grid + for each facet a: + box_a = expanded_aabb(a) + cells = cells_overlapped_by(box_a) + for each cell c in cells: + insert a into grid[c] + +query_candidates(sph_particles): + candidates = empty + for each particle i: + box_i = particle_aabb(i) + cells = cells_overlapped_by(box_i) + for each cell c in cells: + for each facet a in grid[c]: + if aabb_overlap(box_i, box_a): + add candidate(i, a) + sort candidates by (i, a) + remove duplicate candidates +``` + +该流程参考 spatial hashing 的基本思想 [Teschner2003]。CCLite 对 cell size、去重和每步 rebuild 的具体选择属于工程实现。 + +## 4.5 窄相最近点 + +### 4.5.1 点到线段 + +线段端点为 `x_0`、`x_1`,粒子点为 `x_i`: + +```text +e = x_1 - x_0 +s = dot(x_i - x_0, e) / dot(e, e) +s_bar = min(1, max(0, s)) +x_e = x_0 + s_bar e +``` + +若 `dot(e,e)` 小于退化阈值,则该边退化为点,取 `x_e = x_0`。 + +### 4.5.2 点到三角形 + +三角形顶点为 `x_1, x_2, x_3`。最近点可按 Voronoi 区域分区计算 [Ericson2005]。 + +CCLite 文档采用等价工程伪代码描述: + +```text +closest_point_triangle(p, a, b, c): + compute barycentric coordinates of projection on triangle plane + if barycentric all inside [0,1]: + return projected point and weights + + q_ab = closest_point_segment(p, a, b) + q_bc = closest_point_segment(p, b, c) + q_ca = closest_point_segment(p, c, a) + + return q with minimum distance among q_ab, q_bc, q_ca +``` + +投影在三角形内部时: + +```text +x_c = lambda_1 x_1 + lambda_2 x_2 + lambda_3 x_3 +lambda_1 + lambda_2 + lambda_3 = 1 +lambda_A >= 0 +``` + +节点权重取: + +```text +N_A = lambda_A +``` + +若最近点在边上,边端点权重由线段参数 `s_bar` 给出,第三点权重为 0。 + +### 4.5.3 点到四边形 + +第一阶段四边形拆为两个三角形: + +```text +T1 = (x_1, x_2, x_3) +T2 = (x_1, x_3, x_4) +``` + +分别计算 `x_c^1`、`x_c^2`,取距离更小者。 + +为避免同一四边形两半产生重复接触,最终仍只生成一个 `(i,a)` contact pair。 + +## 4.6 法向间隙、壳厚度和穿透量 + +最近点为 `x_c`,初始 facet 法向为 `n_a`。 + +CCLite 接触对局部法向: + +```text +if dot(x_i - x_c, n_a) >= 0: + n = n_a +else: + n = -n_a +``` + +法向间隙: + +```text +g = dot(x_i - x_c, n) +``` + +有效接触距离: + +```text +r_c = r_i + 0.5 t_a +``` + +穿透量: + +```text +d = r_c - g +``` + +接触判定: + +```text +contact if d > 0 +``` + +这是 CCLite 工程约定。它适用于 SPH 粒子与 FEM facet 的离散点-面接触。对于真实厚壳截面、非平面壳、复杂边界曲率和大滑移,该模型只是近似。 + +## 4.7 Edge fallback + +点到面检测可能漏掉 facet 边缘附近的接触。CCLite 在以下情况下执行 edge fallback: + +1. 最近点落在三角形/四边形边界区域; +2. point-face 未接触,但粒子 AABB 与 facet AABB 重叠; +3. 输入要求启用边缘增强检测。 + +边缘接触流程: + +```text +edge_fallback(particle i, facet a): + best_dist = infinity + for each edge e of facet a: + x_e = closest_point_segment(x_i, edge.start, edge.end) + dist = norm(x_i - x_e) + if dist < best_dist: + best_dist = dist + best_point = x_e + best_edge = e + + if best_dist < r_c: + n = normalize(x_i - best_point) + d = r_c - best_dist + create edge contact +``` + +若 `norm(x_i - best_point)` 小于阈值,法向退化。此时优先使用 facet 法向;若 facet 法向也无效,则丢弃该候选并计入诊断。 + +## 4.8 退化和异常几何 + +必须诊断以下情况: + +1. facet 面积小于阈值; +2. facet 法向非有限或长度接近零; +3. edge 长度接近零; +4. 四边形拆分后三角形退化; +5. 最近点权重非有限; +6. AABB min/max 非有限。 + +退化候选不得产生接触力。 + +## 4.9 第 4 章算法实现版本 + +| 算法项 | 首次实现 | 完整/补强版本 | +| --- | --- | --- | +| SPH 粒子球形 primitive | 0.2.x | 0.4.x | +| FEM 三角形/四边形 facet primitive | 0.2.x | 0.3.x | +| FEM 壳中面 + 厚度 | 0.3.x | 0.4.x | +| uniform hash grid | 0.2.x | 0.8.x | +| point-triangle 最近点 | 0.2.x | 0.3.x | +| point-quad 拆三角形 | 0.2.x | 0.3.x | +| point-edge fallback | 0.3.x | 0.4.x | +| BVH/AABB tree | 预留 | 0.8.x 或以后 | +| SPH 壳粒子 primitive | 0.5.x | 0.7.x | +| SPH facet proxy | 0.6.x | 0.7.x | + +--- + +# 5. 接触力与摩擦模型 + +## 5.1 本章定位 + +本章定义 SPH-FEM 接触力模型。接触力模型以接触力学中的单侧接触约束和 penalty 正则化思想为基础 [Wriggers2006, Laursen2002]。第一阶段采用显式友好的 penalty damping 接触;摩擦和接触历史在后续版本补齐。 + +## 5.2 单侧接触约束 + +理想无粘接法向接触满足 Signorini 条件: + +```text +g >= 0 +p_n >= 0 +g p_n = 0 +``` + +其中 `g` 是真实间隙,`p_n` 是法向接触压力或等效法向接触反力。 + +离散 SPH-FEM 接触中,CCLite 使用穿透量 `d`: + +```text +d = max(0, r_c - g) +``` + +若 `d = 0`,不产生法向接触力。 + +## 5.3 Penalty 法向力 + +法向 penalty 力: + +```text +f_n = k_n d n +``` + +其中: + +| 符号 | 含义 | +| --- | --- | +| `k_n` | 法向 penalty 刚度 | +| `d` | 穿透量 | +| `n` | 从 FEM 最近点指向 SPH 粒子的局部法向 | + +CCLite 施加给 SPH 粒子的法向力为: + +```text +f_i^n = f_n +``` + +施加给 FEM facet 的合力为: + +```text +F_a^n = -f_i^n +``` + +## 5.4 法向阻尼 + +最近点 FEM 速度: + +```text +v_c = sum_A N_A v_A +``` + +法向相对速度: + +```text +v_n = dot(v_i - v_c, n) +``` + +只在闭合速度时加入阻尼: + +```text +f_d = c_n max(0, -v_n) n +``` + +法向总力: + +```text +f_i = (k_n d + c_n max(0, -v_n)) n +``` + +这是 CCLite 的显式接触工程模型。它是 penalty contact 在跨求解器点-面接触上的离散形式。 + +## 5.5 FEM 节点力分配 + +FEM facet 反力: + +```text +F_a = -f_i +``` + +分配到节点: + +```text +F_A = N_A F_a +``` + +节点力平衡: + +```text +sum_A F_A = F_a +``` + +若使用三角形权重,`N_A` 为 barycentric 权重;若接触来自 edge fallback,边上两个节点使用线段权重,其余节点权重为 0。 + +## 5.6 接触力矩一致性 + +关于参考点 `x_ref` 的 SPH 侧力矩: + +```text +M_s = (x_i - x_ref) cross f_i +``` + +FEM 侧节点力矩: + +```text +M_f = sum_A (x_A - x_ref) cross F_A +``` + +离散分配导致的力矩误差: + +```text +e_M = || M_s + M_f || +``` + +`e_M` 必须输出诊断。第一阶段不强制力矩完全一致,但不允许非有限或无界增长。 + +## 5.7 Coulomb 摩擦模型 + +切向相对速度: + +```text +v_t = (v_i - v_c) - v_n n +``` + +切向单位方向: + +```text +if ||v_t|| > eps_v: + t = -v_t / ||v_t|| +else: + t = 0 +``` + +滑动摩擦力: + +```text +f_t = mu ||f_n|| t +``` + +为避免速度接近零时不连续,后续版本采用正则化: + +```text +f_t = mu ||f_n|| min(1, ||v_t|| / v_reg) t +``` + +摩擦模型参考计算接触力学中的 Coulomb 摩擦处理 [Wriggers2006, Laursen2002]。第一阶段仅预留,不进入 0.2.x 验收;0.4.x 进入工程可用接触模型。 + +## 5.8 Penalty 参数估计 + +### 5.8.1 基于时间步的刚度 + +给定等效质量 `m_eff` 和目标接触时间步 `dt_c`: + +```text +k_n = gamma_k m_eff / dt_c^2 +``` + +其中 `gamma_k` 为安全系数。 + +等效质量可取: + +```text +m_eff = m_i +``` + +若 FEM facet 节点质量可用,可取两侧等效质量: + +```text +1/m_eff = 1/m_i + 1/m_f +``` + +### 5.8.2 阻尼估计 + +临界阻尼形式: + +```text +c_crit = 2 sqrt(k_n m_eff) +c_n = eta_c c_crit +``` + +其中 `eta_c` 为阻尼比。 + +这些参数估计是 CCLite 工程约定,必须在输入和输出中记录。 + +## 5.9 接触力算法伪代码 + +```text +compute_contact_force(pair): + d = pair.penetration + if d <= 0: + return zero force + + n = pair.normal + v_c = sum_A N_A v_A + v_rel = v_i - v_c + v_n = dot(v_rel, n) + + f = (k_n * d + c_n * max(0, -v_n)) * n + + if friction_enabled: + v_t = v_rel - v_n * n + f = f + regularized_coulomb_force(v_t, f, mu) + + write SPH force +f + distribute FEM force -f by N_A + update diagnostics +``` + +## 5.10 第 5 章算法实现版本 + +| 算法项 | 首次实现 | 完整/补强版本 | +| --- | --- | --- | +| 单侧接触变量 `g,d,n` | 0.2.x | 0.3.x | +| penalty 法向力 | 0.2.x | 0.4.x | +| 法向阻尼 | 0.2.x | 0.4.x | +| FEM 节点力分配 | 0.2.x | 0.4.x | +| 力/力矩平衡诊断 | 0.2.x | 0.8.x | +| Coulomb 摩擦 | 0.4.x | 0.8.x | +| 自动 penalty 参数 | 0.4.x | 0.8.x | +| 接触历史与 persistence | 0.3.x | 0.8.x | + +--- + +# 6. Tied Coupling 与 Release 模型 + +## 6.1 Penalty tie + +SPH 粒子 `i` 与 FEM facet 最近点 `x_c` 建立 bond: + +```text +b = { i, a, N_A, x_i^0, x_c^0, delta_0 } +``` + +当前相对位移: + +```text +delta = x_i - sum_A N_A x_A +``` + +Penalty tie 力: + +```text +f_i^tie = -k_tie (delta - delta_0) - c_tie (v_i - sum_A N_A v_A) +``` + +FEM 节点反力: + +```text +F_A^tie = -N_A f_i^tie +``` + +该方法属于 CCLite 工程化 penalty tie。更严格的 kinematic constraint、mortar tie 或 Lagrange multiplier tie 可作为后续高级方法。 + +## 6.2 Release 准则 + +Bond release 可由损伤、拉开位移或界面力触发: + +```text +release if D >= D_crit +release if ||delta - delta_0|| >= delta_crit +release if ||f_i^tie|| >= f_crit +``` + +释放后: + +```text +bond_state = RELEASED +if contact_after_release: + activate contact detection for same interface +``` + +## 6.3 能量记录 + +Tie 弹性能: + +```text +E_tie = 0.5 k_tie ||delta - delta_0||^2 +``` + +Release 时必须记录释放能量,并在诊断中区分: + +1. tie 储能; +2. release 损失能; +3. release 后接触功。 + +## 6.4 实现版本 + +Penalty tie 在 0.5.x 首次实现。Release 与 tie-to-contact 在 0.5.x 建立闭环,0.8.x 补强能量一致性、历史变量和异常诊断。 + +--- + +# 7. FSI 压力、速度与边界粒子模型 + +## 7.1 Pressure projection + +SPH 压力投影到 FEM facet 的目标是从 SPH 粒子压力得到 facet 等效压力: + +```text +p_a = sum_i w_ia p_i / sum_i w_ia +``` + +权重可采用核函数或距离权重: + +```text +w_ia = W(||x_i - x_a||, h_i) +``` + +其中 `x_a` 可取 facet 中心或积分点。投影压力产生 FEM 侧合力: + +```text +F_a^p = -p_a A_a n_a +``` + +节点力: + +```text +F_A^p = N_A F_a^p +``` + +该模型是 CCLite 的压力投影工程模型。SPH 基本理论参考 [Gingold1977, Lucy1977, Monaghan1992];SPH 边界和流固耦合处理可参考 [Adami2012, Akinci2012]。 + +## 7.2 FEM 运动边界到 SPH + +FEM facet 最近点速度: + +```text +v_c = sum_A N_A v_A +``` + +CCLite 可向 SPHLite 输出: + +```text +boundary_velocity = v_c +boundary_position = x_c +boundary_normal = n_a +``` + +SPHLite 如何把该边界状态纳入内部 SPH 邻域求和不由 CCLite 决定。 + +## 7.3 Boundary/ghost particle + +若 CCLite 生成 boundary particle,其状态应由 FEM facet 采样得到: + +```text +x_b = sample_point_on_facet(a) +v_b = sum_A N_A(x_b) v_A +n_b = n_a +``` + +Ghost state 可按镜像速度构造: + +```text +v_ghost = 2 v_b - v_i +``` + +这是边界处理的工程约定,后续必须结合 SPHLite 内部 SPH 边界模型校准。0.6.x 建立基础能力,0.8.x 做稳定化和诊断补强。 + +--- + +# 8. Riemann FSI 界面模型 + +## 8.1 界面状态 + +Riemann FSI 用于强冲击、水下爆炸和可压缩流固界面。界面法向为 `n`。 + +SPH 侧状态: + +```text +rho_L, p_L, u_L = dot(v_L, n), c_L +``` + +FEM/结构侧等效状态: + +```text +rho_R, p_R, u_R = dot(v_R, n), c_R +``` + +其中 `c_L`、`c_R` 是声速或等效阻抗参数。SPH EOS 由 SPHLite 提供,CCLite 只使用导出的压力、密度和声速/阻抗。 + +## 8.2 声阻抗近似 Riemann 解 + +声阻抗: + +```text +Z_L = rho_L c_L +Z_R = rho_R c_R +``` + +CCLite 可采用线性声学近似: + +```text +p_star = (Z_R p_L + Z_L p_R + Z_L Z_R (u_L - u_R)) / (Z_L + Z_R) +u_star = (Z_L u_L + Z_R u_R + p_L - p_R) / (Z_L + Z_R) +``` + +该公式是 CCLite 的近似界面 Riemann 工程模型。若后续采用完整非线性 Riemann solver,应以可压缩流理论和 SPH Riemann 方法文献为准。 + +## 8.3 界面载荷 + +Riemann 压力作用于 FEM facet: + +```text +F_a^R = -p_star A_a n +``` + +反作用于 SPH 侧边界: + +```text +f_sph^R = +p_star A_a n +``` + +实际分配给 SPH 粒子或 boundary particle 的方式由 SPHLite 可接受接口决定。 + +## 8.4 实现版本 + +Riemann FSI 在 0.7.x 完成主要算法引入。0.8.x 后进行稳定化、EOS 接口细化、冲击场景验收和能量诊断补强。 + +--- + +# 9. 时间耦合数学框架 + +## 9.1 显式-显式同步 + +同步耦合时间步: + +```text +dt = min(dt_sph, dt_fem, dt_contact) +``` + +流程: + +```text +for each step n: + SPHLite exports U_s^n + FEMLite exports U_f^n + CCLite computes interface loads L^n + SPHLite imports L_s^n + FEMLite imports L_f^n + SPHLite advances to n+1 + FEMLite advances to n+1 +``` + +该模式在 0.2.x 起作为基础接触主流程。 + +## 9.2 显式-显式异步子循环 + +若 `dt_sph < dt_fem`: + +```text +m = ceil(dt_fem / dt_sph) +dt_sub = dt_fem / m +``` + +SPH 子循环累积冲量: + +```text +J = sum_{k=1}^m f_k dt_sub +``` + +传给 FEM 的平均力: + +```text +F_bar = J / dt_fem +``` + +该模式在 0.7.x 完成主要算法实现,0.8.x 补强能量和稳定性诊断。 + +## 9.3 SPH 显式 + FEM 隐式弱耦合 + +弱耦合流程: + +```text +FEM predicts interface motion +SPH advances with prescribed interface state +CCLite accumulates SPH interface impulse +FEM implicit step uses averaged interface load +``` + +弱耦合适合 added-mass 效应不强的场景。强 added-mass 问题需要强耦合或松弛,相关稳定性问题参考 partitioned FSI 文献 [Causin2005]。 + +## 9.4 强耦合迭代 + +每个宏步内迭代: + +```text +for k = 1..kmax: + SPH solve/predict with interface state q^k + CCLite transfers load/displacement + FEM solve with transferred load + compute residual r^k + if ||r^k|| < tol: + accept + q^{k+1} = q^k + omega_k correction +``` + +Aitken 动态松弛: + +```text +omega_k = -omega_{k-1} * dot(r^{k-1}, r^k - r^{k-1}) / + ||r^k - r^{k-1}||^2 +``` + +动态松弛参考 partitioned FSI 中固定点迭代加速方法 [Kuttler2008]。 + +--- + +# 10. 稳定性控制 + +## 10.1 接触稳定时间步 + +接触振子估计: + +```text +omega_c = sqrt(k_n / m_eff) +dt_contact = gamma_dt / omega_c +``` + +其中 `gamma_dt < 1`。 + +## 10.2 Force relaxation + +载荷松弛: + +```text +f_relaxed^n = alpha f_raw^n + (1 - alpha) f_relaxed^{n-1} +``` + +`alpha in (0,1]`。 + +## 10.3 接触 persistence + +为避免接触对闪烁,可引入激活/释放阈值: + +```text +activate if d > d_on +keep active if d > -d_off +release if d <= -d_off +``` + +其中 `d_off >= 0`。 + +## 10.4 非有限值保护 + +以下量必须检查有限性: + +```text +x, v, n, g, d, f, F, p, rho, dt +``` + +发现非有限值时,当前接触对不应写入载荷;若数量超过阈值,应终止当前步。 + +--- + +# 11. 守恒与诊断量 + +## 11.1 总力误差 + +```text +E_F = || sum_i f_i + sum_A F_A || +``` + +相对误差: + +```text +e_F = E_F / max(eps, ||sum_i f_i|| + ||sum_A F_A||) +``` + +## 11.2 总力矩误差 + +```text +E_M = || sum_i (x_i - x_ref) cross f_i + + sum_A (x_A - x_ref) cross F_A || +``` + +## 11.3 接触功 + +每步接触功: + +```text +W_c^n = sum_pairs f_pair^n dot v_rel^n dt +``` + +累计接触功: + +```text +W_c = sum_n W_c^n +``` + +## 11.4 冲量交换 + +```text +J_s = sum_n sum_i f_i^n dt +J_f = sum_n sum_A F_A^n dt +``` + +诊断要求: + +```text +J_s + J_f approx 0 +``` + +## 11.5 接触诊断 + +必须输出: + +1. active pair count; +2. candidate count; +3. max penetration; +4. max contact force; +5. edge fallback count; +6. degenerate geometry count; +7. nonfinite count。 + +--- + +# 12. 算法实现版本映射 + +本章只说明各版本实现目标,不改变前文数学模型的组织方式。 + +| 版本线 | 目标 | 算法状态 | +| --- | --- | --- | +| 0.1.x | 三进程主控、`.inp`、IPC、共享内存、空耦合 | 无真实界面算法,仅验证数据闭环 | +| 0.2.x | SPH 粒子-FEM 面/壳基础 penalty contact | 基础接触算法首次实现 | +| 0.3.x | 壳厚度、边缘接触、四边形面、接触 persistence | 接触检测基本完整 | +| 0.4.x | 阻尼、摩擦、自动 penalty、接触稳定时间步 | 接触算法工程可用 | +| 0.5.x | tied coupling、penalty tie、damage release、tie-to-contact | 固-固/局部破坏耦合可用 | +| 0.6.x | pressure projection、FEM 运动边界、boundary/ghost 状态 | 基础 FSI 可用 | +| 0.7.x | Riemann FSI、显式异步子循环、显隐弱耦合、强耦合框架 | 主要算法体系全部实现 | +| 0.8.x | 稳定化、松弛、接触历史、能量修正、异常处理 | 算法鲁棒性增强 | +| 0.9.x | 工程算例覆盖、参数推荐、验收矩阵、性能优化 | 工程试用候选 | +| 0.10.x | 接口冻结、文档冻结、回归体系、工程发布候选 | 工程化基线候选 | + +--- + +# 13. 参考文献与出处管理 + +## 13.1 计算几何与碰撞检测 + +[Ericson2005] Christer Ericson. *Real-Time Collision Detection*. Morgan Kaufmann, 2005. Companion site: https://realtimecollisiondetection.net/ + +[Gottschalk1996] S. Gottschalk, M. C. Lin, D. Manocha. OBBTree: A Hierarchical Structure for Rapid Interference Detection. SIGGRAPH 1996. UNC RAPID/OBBTree site: https://gamma.cs.unc.edu/OBB/ + +[Teschner2003] M. Teschner, B. Heidelberger, M. Muller, D. Pomeranets, M. Gross. Optimized Spatial Hashing for Collision Detection of Deformable Objects. VMV 2003. + +## 13.2 SPH 与边界处理 + +[Gingold1977] R. A. Gingold, J. J. Monaghan. Smoothed particle hydrodynamics: theory and application to non-spherical stars. *Monthly Notices of the Royal Astronomical Society*, 1977. + +[Lucy1977] L. B. Lucy. A numerical approach to the testing of the fission hypothesis. *The Astronomical Journal*, 1977. + +[Monaghan1992] J. J. Monaghan. Smoothed Particle Hydrodynamics. *Annual Review of Astronomy and Astrophysics*, 1992. + +[Adami2012] S. Adami, X. Y. Hu, N. A. Adams. A generalized wall boundary condition for smoothed particle hydrodynamics. *Journal of Computational Physics*, 2012. + +[Akinci2012] N. Akinci, M. Ihmsen, G. Akinci, B. Solenthaler, M. Teschner. Versatile Rigid-Fluid Coupling for Incompressible SPH. *ACM Transactions on Graphics*, 2012. + +## 13.3 接触力学 + +[Wriggers2006] P. Wriggers. *Computational Contact Mechanics*. 2nd edition, Springer, 2006. + +[Laursen2002] T. A. Laursen. *Computational Contact and Impact Mechanics*. Springer, 2002. + +## 13.4 FSI 与分区耦合 + +[Causin2005] P. Causin, J. F. Gerbeau, F. Nobile. Added-mass effect in the design of partitioned algorithms for fluid-structure problems. *Computer Methods in Applied Mechanics and Engineering*, 2005. + +[Kuttler2008] U. Kuttler, W. A. Wall. Fixed-point fluid-structure interaction solvers with dynamic relaxation. *Computational Mechanics*, 2008. + +## 13.5 Riemann 方法 + +[Toro2009] E. F. Toro. *Riemann Solvers and Numerical Methods for Fluid Dynamics*. 3rd edition, Springer, 2009. diff --git a/docs/05_interface_control_document.md b/docs/05_interface_control_document.md new file mode 100644 index 0000000..435aad7 --- /dev/null +++ b/docs/05_interface_control_document.md @@ -0,0 +1,1067 @@ +# CCLite 接口控制文档 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文档版本**:V0.1 草案 +**软件名称**:CCLite +**文档定位**:CCLite 与 SPHLite/FEMLite 的外部接口契约 +**实现基线**:独立主控程序 + CCLite worker/service 模式 + Windows shared memory + named event +**数据布局基线**:AoR v1,0.8.x 预留 SoA v2 +**编码要求**:中文,UTF-8 without BOM + +--- + +# 1. 文档定位与接口边界 + +## 1.1 编写目的 + +本文档定义 CCLite 与 SPHLite/FEMLite 之间的外部接口契约,包括: + +1. worker/service 启动方式; +2. CCLite `.inp` 输入关键词接口; +3. 控制 IPC; +4. 共享内存 block; +5. command shared block; +6. AoR payload 布局; +7. 命令、状态、错误码和超时; +8. 接口版本兼容策略; +9. 0.1.x 到 0.10.x 的接口演进路线。 + +## 1.2 接口边界 + +本文档只冻结外部接口,不规定 SPHLite/FEMLite 内部 Fortran API、内部模块、内部数组或内部求解流程。 + +CCLite 与求解器之间只通过以下通道交互: + +```text +control IPC: + named event + command shared block + +data IPC: + Windows shared memory data blocks + +process interface: + worker/service command line + +case interface: + cclite.inp keywords +``` + +## 1.3 第一阶段平台约束 + +0.1.x 到 0.2.x 的接口实现范围: + +```text +OS: Windows +Compiler: gfortran +Communication: local shared memory +Control sync: named event +Data layout: AoR v1 +``` + +Linux shared memory、MPI、socket、pipe 和 SoA v2 只作为后续预留。 + +--- + +# 2. 总体接口架构 + +## 2.1 三进程关系 + +```text + CCLite.exe + Controller / Contact / Transfer / Output + / \ + command/event command/event + / \ + SPHLite.exe FEMLite.exe + --cclite-worker --cclite-worker + + shared memory: + SPH_TO_CCL_PARTICLE + SPH_TO_CCL_FACET + FEM_TO_CCL_FACET + CCL_TO_SPH_FORCE + CCL_TO_FEM_LOAD + CCL_DIAGNOSTIC + CCL_COMMAND_SPH + CCL_COMMAND_FEM +``` + +## 2.2 接口所有权 + +| 对象 | 创建者 | 写入者 | 读取者 | +| --- | --- | --- | --- | +| command block | CCLite | CCLite / Solver | CCLite / Solver | +| named event | CCLite | CCLite / Solver | CCLite / Solver | +| SPH_TO_CCL_PARTICLE | CCLite | SPHLite | CCLite | +| SPH_TO_CCL_FACET | CCLite | SPHLite | CCLite | +| FEM_TO_CCL_FACET | CCLite | FEMLite | CCLite | +| CCL_TO_SPH_FORCE | CCLite | CCLite | SPHLite | +| CCL_TO_FEM_LOAD | CCLite | CCLite | FEMLite | +| CCL_DIAGNOSTIC | CCLite | CCLite / Solver | CCLite | + +CCLite 负责创建和销毁所有共享内存和 named event。求解器 worker 只打开、映射和使用这些对象。 + +## 2.3 命名原则 + +共享对象名称由 `prefix + role + solver` 组成: + +```text +__ +``` + +示例: + +```text +CCLITE_CASE001_COMMAND_SPH +CCLITE_CASE001_COMMAND_FEM +CCLITE_CASE001_SPH_TO_CCL_PARTICLE +CCLITE_CASE001_FEM_TO_CCL_FACET +CCLITE_CASE001_CCL_TO_SPH_FORCE +CCLITE_CASE001_CCL_TO_FEM_LOAD +``` + +`PREFIX` 由 `*CCLITE IPC` 的 `PREFIX=` 参数指定。名称只能包含字母、数字和下划线。 + +--- + +# 3. Worker/Service 模式接口 + +## 3.1 启动方式 + +SPHLite 和 FEMLite 必须增加 CCLite worker/service 模式。 + +推荐命令行: + +```powershell +sphlite.exe --cclite-worker sphlite.inp --ipc-prefix CCLITE_CASE001 --solver-name SPH +femlite.exe --cclite-worker femlite.inp --ipc-prefix CCLITE_CASE001 --solver-name FEM +``` + +最小参数: + +| 参数 | 必填 | 含义 | +| --- | --- | --- | +| `--cclite-worker` | 是 | 进入 CCLite worker/service 模式 | +| input file | 是 | 求解器自己的 `.inp` 文件 | +| `--ipc-prefix` | 是 | CCLite 创建的共享对象前缀 | +| `--solver-name` | 是 | `SPH` 或 `FEM` | +| `--workdir` | 否 | worker 工作目录 | +| `--timeout-ms` | 否 | worker 默认等待超时 | + +## 3.2 worker 行为 + +worker 模式下,求解器不得自行完整运行到结束,而是等待 CCLite 命令。 + +worker 主循环: + +```text +attach command block +attach data blocks +signal READY + +loop: + wait command event + read command block + execute command + write status/error + signal done event + if command == STOP: + exit +``` + +## 3.3 worker 必须支持的操作 + +| 操作 | SPHLite | FEMLite | +| --- | --- | --- | +| attach IPC | 必须 | 必须 | +| read input | 必须 | 必须 | +| build model | 必须 | 必须 | +| export interface | 必须 | 必须 | +| import loads | 必须 | 必须 | +| advance explicit | 必须 | 必须 | +| write output | 必须 | 必须 | +| stop | 必须 | 必须 | + +隐式推进、restart 和高级输出不属于 0.1.x 必须项,可在后续版本追加。 + +--- + +# 4. CCLite `.inp` 关键词接口 + +## 4.1 关键词范围 + +0.1.x 必须支持: + +```text +*CCLITE CONTROL +*CCLITE SOLVER +*CCLITE IPC +*CCLITE TIME +*CCLITE INTERFACE +*CCLITE OUTPUT +``` + +0.2.x 必须支持: + +```text +*CCLITE SURFACE INTERACTION +*CCLITE CONTACT PAIR +``` + +后续版本追加 tied coupling、FSI、restart 和高级稳定性关键词。 + +## 4.2 `*CCLITE CONTROL` + +示例: + +```text +*CCLITE CONTROL, NAME=CASE001 +MODE=EXPLICIT_EXPLICIT_SYNC +``` + +参数: + +| 参数 | 必填 | 默认 | 含义 | +| --- | --- | --- | --- | +| `NAME` | 是 | 无 | 算例名称 | + +数据行: + +| 字段 | 必填 | 默认 | 允许值 | +| --- | --- | --- | --- | +| `MODE` | 是 | 无 | `EXPLICIT_EXPLICIT_SYNC` | + +后续允许值: + +```text +EXPLICIT_EXPLICIT_ASYNC +EXPLICIT_SPH_IMPLICIT_FEM_WEAK +EXPLICIT_SPH_IMPLICIT_FEM_STRONG +``` + +## 4.3 `*CCLITE SOLVER` + +示例: + +```text +*CCLITE SOLVER, NAME=SPH, TYPE=SPHLITE +EXECUTABLE=SPHLite/cpu_release/bin/sphlite.exe +INPUT=sphlite.inp +WORKDIR=work/sph +WORKER=YES +``` + +参数: + +| 参数 | 必填 | 允许值 | +| --- | --- | --- | +| `NAME` | 是 | `SPH`、`FEM` | +| `TYPE` | 是 | `SPHLITE`、`FEMLITE` | + +数据行字段: + +| 字段 | 必填 | 默认 | +| --- | --- | --- | +| `EXECUTABLE` | 是 | 无 | +| `INPUT` | 是 | 无 | +| `WORKDIR` | 否 | 当前目录下自动生成 | +| `WORKER` | 否 | `YES` | +| `TIMEOUT_MS` | 否 | 30000 | + +## 4.4 `*CCLITE IPC` + +示例: + +```text +*CCLITE IPC, TYPE=WINDOWS_SHMEM +PREFIX=CCLITE_CASE001 +CONTROL=NAMED_EVENT +COMMAND_BLOCK=YES +BUFFERING=DOUBLE +PAYLOAD_LAYOUT=AOR_V1 +TIMEOUT_MS=30000 +``` + +字段: + +| 字段 | 必填 | 默认 | 允许值 | +| --- | --- | --- | --- | +| `PREFIX` | 是 | 无 | 字母、数字、下划线 | +| `CONTROL` | 是 | `NAMED_EVENT` | `NAMED_EVENT` | +| `COMMAND_BLOCK` | 否 | `YES` | `YES` | +| `BUFFERING` | 否 | `DOUBLE` | `SINGLE`、`DOUBLE`、`TRIPLE` | +| `PAYLOAD_LAYOUT` | 否 | `AOR_V1` | `AOR_V1` | +| `TIMEOUT_MS` | 否 | 30000 | 正整数 | + +0.1.x 只允许 `TYPE=WINDOWS_SHMEM`。 + +## 4.5 `*CCLITE TIME` + +示例: + +```text +*CCLITE TIME +START=0.0, END=1.0E-3, DT=1.0E-7 +OUTPUT_FREQUENCY=10 +``` + +字段: + +| 字段 | 必填 | 默认 | +| --- | --- | --- | +| `START` | 是 | 无 | +| `END` | 是 | 无 | +| `DT` | 是 | 无 | +| `OUTPUT_FREQUENCY` | 否 | 1 | + +## 4.6 `*CCLITE INTERFACE` + +示例: + +```text +*CCLITE INTERFACE, NAME=HULL_IMPACT +SPH_REGION=WATER_CONTACT +FEM_SURFACE=HULL_OUTER +``` + +字段: + +| 字段 | 必填 | 含义 | +| --- | --- | --- | +| `SPH_REGION` | 是 | SPHLite coupling region 名称 | +| `FEM_SURFACE` | 是 | FEMLite surface/facet 集合名称 | + +## 4.7 `*CCLITE SURFACE INTERACTION` + +示例: + +```text +*CCLITE SURFACE INTERACTION, NAME=PENALTY_1 +NORMAL=PENALTY, KN=1.0E9, CN=1.0E4 +FRICTION=0.0 +``` + +字段: + +| 字段 | 必填 | 默认 | 含义 | +| --- | --- | --- | --- | +| `NORMAL` | 是 | 无 | 法向模型 | +| `KN` | 是 | 无 | penalty 刚度 | +| `CN` | 否 | 0 | 法向阻尼 | +| `FRICTION` | 否 | 0 | 摩擦系数,0.4.x 起启用 | + +0.2.x 必须支持 `NORMAL=PENALTY`。 + +## 4.8 `*CCLITE CONTACT PAIR` + +示例: + +```text +*CCLITE CONTACT PAIR, NAME=PAIR_1 +INTERFACE=HULL_IMPACT +INTERACTION=PENALTY_1 +TYPE=SPH_PARTICLE_TO_FEM_FACE +``` + +字段: + +| 字段 | 必填 | 允许值 | +| --- | --- | --- | +| `INTERFACE` | 是 | 已定义 interface | +| `INTERACTION` | 是 | 已定义 surface interaction | +| `TYPE` | 是 | `SPH_PARTICLE_TO_FEM_FACE`、`SPH_PARTICLE_TO_FEM_SHELL` | + +后续版本追加 SPH shell、facet proxy、tie 和 FSI 类型。 + +## 4.9 `*CCLITE OUTPUT` + +示例: + +```text +*CCLITE OUTPUT +DIRECTORY=work/cclite +FREQUENCY=10 +CONTACT=YES +IPC=YES +FORCE_BALANCE=YES +SNAPSHOT=NO +``` + +字段: + +| 字段 | 默认 | +| --- | --- | +| `DIRECTORY` | `work/cclite` | +| `FREQUENCY` | 1 | +| `CONTACT` | `YES` | +| `IPC` | `YES` | +| `FORCE_BALANCE` | `YES` | +| `SNAPSHOT` | `NO` | + +--- + +# 5. 控制 IPC 接口 + +## 5.1 控制 IPC 组成 + +每个 solver worker 有一组控制对象: + +```text +COMMAND_BLOCK_ +COMMAND_EVENT_ +DONE_EVENT_ +``` + +示例: + +```text +CCLITE_CASE001_COMMAND_BLOCK_SPH +CCLITE_CASE001_COMMAND_EVENT_SPH +CCLITE_CASE001_DONE_EVENT_SPH +``` + +## 5.2 command block 职责 + +command block 用于传递小命令和状态,不用于传递大数组。 + +内容包括: + +1. magic/version; +2. command id; +3. step id; +4. buffer id; +5. dt/time; +6. target block role; +7. command state; +8. error code; +9. message。 + +## 5.3 事件流程 + +```text +CCLite: + write command block + reset COMMAND_EVENT + reset DONE_EVENT + signal COMMAND_EVENT + wait DONE_EVENT + read command block status + +Solver: + wait COMMAND_EVENT + read command block + set state BUSY + execute command + set state DONE or FAILED + signal DONE_EVENT +``` + +0.1.x 约定使用 Windows manual-reset named event。CCLite 负责 reset `COMMAND_EVENT` 和 `DONE_EVENT`;worker 只执行 wait 和 signal,不负责 reset。这样可以减少求解器 worker 端状态复杂度。 + +## 5.4 超时 + +每个命令都有 `timeout_ms`。若超时: + +1. CCLite 将 solver 状态置为 `TIMEOUT`; +2. 写入 `ipc_report.csv`; +3. 0.1.x 默认终止当前 run; +4. 0.8.x 后可引入恢复策略。 + +--- + +# 6. Command Shared Block 布局 + +## 6.1 基本类型 + +| 名称 | 类型 | 说明 | +| --- | --- | --- | +| `int32` | 32 位有符号整数 | 枚举、数量、状态 | +| `int64` | 64 位有符号整数 | 字节数、全局 id | +| `real64` | IEEE 754 double | 浮点数据 | +| `char[N]` | 固定长度 ASCII/UTF-8 字节 | 短消息,不允许变长指针 | + +所有共享内存字段不得包含进程私有指针。 + +## 6.2 字节序与对齐 + +0.1.x 只支持 Windows/x86_64 little-endian。 +共享结构不依赖编译器默认派生类型布局,正式实现应使用显式 offset 常量或 `bind(C)` 镜像结构。 + +## 6.3 command block 字段顺序 + +AoR v1 command block 头部字段顺序: + +| 序号 | 字段 | 类型 | 含义 | +| --- | --- | --- | --- | +| 1 | `magic` | int32 | 固定 magic | +| 2 | `version_major` | int32 | 接口主版本 | +| 3 | `version_minor` | int32 | 接口次版本 | +| 4 | `layout_id` | int32 | command block layout | +| 5 | `solver_id` | int32 | SPH/FEM | +| 6 | `worker_state` | int32 | worker 生命周期状态 | +| 7 | `command_id` | int32 | 命令枚举 | +| 8 | `command_state` | int32 | 当前命令状态 | +| 9 | `command_seq` | int32 | CCLite 发出的命令序号 | +| 10 | `ack_seq` | int32 | worker 确认的命令序号 | +| 11 | `step_id` | int32 | 宏步编号 | +| 12 | `substep_id` | int32 | 子步编号,无子步时为 0 | +| 13 | `iteration_id` | int32 | 强耦合迭代号,无迭代时为 0 | +| 14 | `buffer_id` | int32 | buffer 编号 | +| 15 | `target_block_role` | int32 | 相关 data block | +| 16 | `command_flags` | int32 | 命令标志位 | +| 17 | `error_code` | int32 | 错误码 | +| 18 | `warning_count` | int32 | warning 数量 | +| 19 | `heartbeat_seq` | int32 | worker 心跳序号 | +| 20 | `timeout_ms` | int32 | 超时 | +| 21 | `message_length` | int32 | message 有效长度 | +| 22 | `reserved_i4` | int32[8] | 预留 | +| 23 | `time` | real64 | 当前时间 | +| 24 | `dt` | real64 | 当前步长 | +| 25 | `macro_dt` | real64 | 宏步步长,无子循环时等于 `dt` | +| 26 | `int_param` | int32[16] | 命令整数参数槽 | +| 27 | `real_param` | real64[16] | 命令浮点参数槽 | +| 28 | `message` | char[256] | 短消息 | + +`command_seq` 必须单调递增,用于检测重复命令和 stale command。 + +`ack_seq` 必须等于 worker 已处理完成的 `command_seq`。CCLite 等待 `DONE_EVENT` 后必须检查 `ack_seq == command_seq`。 + +`substep_id` 为显式异步子循环预留,`iteration_id` 为显隐强耦合和 Aitken 松弛预留。0.1.x/0.2.x 中二者均写 0。 + +`int_param` 和 `real_param` 是稳定扩展槽,用于 `ADVANCE`、`WRITE_OUTPUT`、`READ_RESTART`、`EXPORT_INTERFACE` 等命令传递少量参数,避免频繁修改 command block 主结构。 + +## 6.4 command flags + +`command_flags` 使用 bit mask: + +| bit | 名称 | 含义 | +| --- | --- | --- | +| 0 | `FLAG_FINAL_STEP` | 当前为最后一步 | +| 1 | `FLAG_WRITE_OUTPUT` | 本步要求输出 | +| 2 | `FLAG_STRICT_CHECK` | 严格校验 block/header | +| 3 | `FLAG_ALLOW_EMPTY_BLOCK` | 允许导出空 block | +| 4 | `FLAG_RESTART_POINT` | 本步为 restart 点 | +| 5 | `FLAG_SUBCYCLING` | 当前命令属于子循环 | +| 6 | `FLAG_COUPLING_ITERATION` | 当前命令属于强耦合迭代 | + +未定义 bit 必须写 0。 + +--- + +# 7. 共享内存 Data Block 通用 Header + +## 7.1 Data block header 字段 + +所有 data block 都以统一 header 开始。 + +| 序号 | 字段 | 类型 | 含义 | +| --- | --- | --- | --- | +| 1 | `magic` | int32 | block magic | +| 2 | `version_major` | int32 | block 主版本 | +| 3 | `version_minor` | int32 | block 次版本 | +| 4 | `layout_id` | int32 | `AOR_V1`、后续 `SOA_V2` | +| 5 | `block_role` | int32 | block role | +| 6 | `producer_id` | int32 | 写入者 | +| 7 | `consumer_id` | int32 | 读取者 | +| 8 | `step_id` | int32 | 耦合步 | +| 9 | `buffer_id` | int32 | buffer 编号 | +| 10 | `state` | int32 | buffer 状态 | +| 11 | `item_count` | int32 | 记录数量 | +| 12 | `item_stride` | int32 | 单条记录字节数 | +| 13 | `payload_bytes` | int64 | payload 总字节数 | +| 14 | `header_bytes` | int32 | header 字节数 | +| 15 | `max_item_count` | int32 | 最大记录数 | +| 16 | `error_code` | int32 | 错误码 | +| 17 | `reserved_i4` | int32[16] | 预留 | + +## 7.2 buffer 状态 + +| 状态 | 含义 | +| --- | --- | +| `EMPTY` | 可写 | +| `WRITING` | producer 正在写 | +| `READY` | producer 写完,可读 | +| `READING` | consumer 正在读 | +| `CONSUMED` | consumer 已读完 | +| `ERROR` | 数据无效 | + +状态转换: + +```text +EMPTY -> WRITING -> READY -> READING -> CONSUMED + \-> ERROR +``` + +## 7.3 header 校验 + +读取 data block 前必须检查: + +1. magic 正确; +2. major 版本兼容; +3. layout id 支持; +4. block role 与预期一致; +5. payload bytes 不超过映射大小; +6. item count 不超过 max item count; +7. state 为 `READY`; +8. step id 与 command block 匹配。 + +--- + +# 8. Block Role 与版本 + +## 8.1 block role 枚举 + +| role | 名称 | 首次版本 | 说明 | +| --- | --- | --- | --- | +| 101 | `SPH_TO_CCL_PARTICLE` | 0.1.x | SPH 粒子界面状态 | +| 102 | `SPH_TO_CCL_FACET` | 0.6.x | SPH facet proxy | +| 201 | `FEM_TO_CCL_FACET` | 0.1.x | FEM 边界 facet | +| 301 | `CCL_TO_SPH_FORCE` | 0.2.x | CCLite 写给 SPH 的力/接触状态 | +| 302 | `CCL_TO_FEM_LOAD` | 0.2.x | CCLite 写给 FEM 的节点力/facet 载荷 | +| 401 | `CCL_DIAGNOSTIC` | 0.1.x | 诊断摘要 | +| 901 | `CCL_COMMAND_SPH` | 0.1.x | SPH command block | +| 902 | `CCL_COMMAND_FEM` | 0.1.x | FEM command block | + +## 8.2 layout id + +| layout id | 名称 | 说明 | +| --- | --- | --- | +| 1 | `AOR_V1` | Array of Records,第一阶段默认 | +| 2 | `SOA_V2` | Structure of Arrays,0.8.x 性能优化预留 | + +0.1.x 到 0.7.x 以 `AOR_V1` 为主。 + +--- + +# 9. AoR v1 Payload 布局 + +## 9.1 通用要求 + +AoR v1 表示 payload 是连续 record 数组: + +```text +payload = record[0], record[1], ..., record[item_count-1] +``` + +每个 record: + +1. 字段顺序固定; +2. 不含指针; +3. 不含变长字符串; +4. 浮点为 real64; +5. 枚举和局部数量为 int32; +6. 全局 id 可用 int64。 + +## 9.2 SPH_TO_CCL_PARTICLE record + +| 序号 | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 1 | `external_id` | int64 | SPHLite 外部粒子 id | +| 2 | `internal_index` | int32 | SPHLite 导出 index | +| 3 | `phase` | int32 | 相/粒子类型 | +| 4 | `status` | int32 | active/failed/inactive | +| 5 | `material_id` | int32 | 材料 id | +| 6 | `section_id` | int32 | section id | +| 7 | `valid_flags` | int32 | 有效字段 bit mask | +| 8 | `reserved_i4` | int32[2] | 预留 | +| 9 | `mass` | real64 | 质量 | +| 10 | `volume` | real64 | 体积 | +| 11 | `density` | real64 | 密度 | +| 12 | `pressure` | real64 | 压力 | +| 13 | `internal_energy` | real64 | 内能 | +| 14 | `temperature` | real64 | 温度 | +| 15 | `h` | real64 | 光滑长度 | +| 16 | `smoothing_length` | real64 | 平滑长度别名,默认等于 `h` | +| 17 | `contact_radius` | real64 | 接触半径 | +| 18 | `sound_speed` | real64 | 声速,FSI/Riemann 使用 | +| 19 | `x` | real64[3] | 坐标 | +| 20 | `v` | real64[3] | 速度 | +| 21 | `a` | real64[3] | 加速度 | + +0.2.x 接触算法至少需要: + +```text +external_id, internal_index, status, contact_radius, x, v +``` + +`valid_flags` 定义: + +| bit | 字段 | +| --- | --- | +| 0 | `mass` | +| 1 | `volume` | +| 2 | `density` | +| 3 | `pressure` | +| 4 | `internal_energy` | +| 5 | `temperature` | +| 6 | `h/smoothing_length` | +| 7 | `contact_radius` | +| 8 | `sound_speed` | + +无效的 real64 字段建议填 0,并通过 `valid_flags` 判断,不使用 NaN 作为接口语义。 + +## 9.3 SPH_TO_CCL_FACET record + +0.6.x 起启用。0.1.x 到 0.5.x 可不创建或创建空 block。 + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `facet_id` | int64 | SPH facet proxy id | +| `particle_count` | int32 | 局部粒子数 | +| `particle_ids` | int64[8] | 粒子 id,最多 8 | +| `section_id` | int32 | section | +| `material_id` | int32 | material | +| `area` | real64 | 面积 | +| `normal` | real64[3] | 法向 | +| `x` | real64[8,3] | facet 粒子坐标 | +| `v` | real64[8,3] | facet 粒子速度 | + +## 9.4 FEM_TO_CCL_FACET record + +| 序号 | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 1 | `facet_id` | int64 | FEM facet id | +| 2 | `elem_id` | int64 | FEM element id | +| 3 | `face_id` | int32 | element face id | +| 4 | `node_count` | int32 | facet 节点数 | +| 5 | `element_type` | int32 | 元素类型枚举 | +| 6 | `surface_type` | int32 | solid/shell | +| 7 | `surface_id` | int64 | surface 名称 hash 或导出 id | +| 8 | `valid_flags` | int32 | 有效字段 bit mask | +| 9 | `reserved_i4` | int32[3] | 预留 | +| 10 | `node_ids` | int64[8] | 节点 id,最多 8 | +| 11 | `area` | real64 | 面积 | +| 12 | `thickness` | real64 | 壳厚度,实体为 0 | +| 13 | `shell_thickness` | real64 | 壳厚度别名,默认等于 `thickness` | +| 14 | `mass_per_area` | real64 | 面密度或等效质量/面积 | +| 15 | `normal` | real64[3] | facet 法向 | +| 16 | `x` | real64[8,3] | 节点坐标 | +| 17 | `v` | real64[8,3] | 节点速度 | + +0.2.x 接触算法至少需要: + +```text +facet_id, node_count, node_ids, surface_type, area, thickness, normal, x, v +``` + +`surface_id` 可以是 FEMLite 导出的 surface id,也可以是 CCLite 对 surface 名称计算的稳定 hash。若当前 FEMLite 只能按全边界导出,可填 0。 + +`valid_flags` 定义: + +| bit | 字段 | +| --- | --- | +| 0 | `area` | +| 1 | `thickness/shell_thickness` | +| 2 | `mass_per_area` | +| 3 | `normal` | +| 4 | `x` | +| 5 | `v` | + +## 9.5 CCL_TO_SPH_FORCE record + +| 序号 | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 1 | `external_id` | int64 | SPH 粒子 id | +| 2 | `internal_index` | int32 | SPH 导出 index | +| 3 | `load_mode` | int32 | particle force / motion / contact state | +| 4 | `contact_state` | int32 | 接触状态 | +| 5 | `coupling_step` | int32 | CCLite 耦合步 | +| 6 | `valid_flags` | int32 | 有效字段 bit mask | +| 7 | `source_pair_id` | int64 | CCLite contact pair id | +| 8 | `source_facet_id` | int64 | 关联 FEM facet id | +| 9 | `force` | real64[3] | 作用于 SPH 的力 | +| 10 | `moment` | real64[3] | 作用于 SPH 的力矩,第一阶段可为 0 | +| 11 | `normal` | real64[3] | 接触法向 | +| 12 | `gap` | real64 | 法向间隙 | +| 13 | `penetration` | real64 | 穿透量 | +| 14 | `pressure` | real64 | 接触压力或 FSI 压力 | +| 15 | `target_motion` | real64[3] | 运动边界目标,0.6.x 起使用 | + +同一 SPH 粒子可出现多条 record,SPHLite 负责累加或 CCLite 可在写入前合并。0.2.x 建议 CCLite 写入前按粒子合并。 + +## 9.6 CCL_TO_FEM_LOAD record + +| 序号 | 字段 | 类型 | 说明 | +| --- | --- | --- | --- | +| 1 | `facet_id` | int64 | FEM facet id | +| 2 | `source_pair_id` | int64 | CCLite contact pair id | +| 3 | `source_particle_id` | int64 | 关联 SPH 粒子 id | +| 4 | `node_count` | int32 | 节点数 | +| 5 | `load_type` | int32 | nodal force / pressure / traction | +| 6 | `distribution_mode` | int32 | 节点分配模式 | +| 7 | `contact_state` | int32 | 接触状态 | +| 8 | `valid_flags` | int32 | 有效字段 bit mask | +| 9 | `node_ids` | int64[8] | 节点 id | +| 10 | `node_forces` | real64[8,3] | 节点力 | +| 11 | `pressure` | real64 | facet 压力 | +| 12 | `traction` | real64[3] | facet 牵引 | +| 13 | `resultant` | real64[3] | facet 合力 | +| 14 | `normal` | real64[3] | 接触法向 | + +0.2.x 必须支持 `load_type=NODAL_FORCE`。 + +## 9.7 CCL_DIAGNOSTIC record + +诊断 record 可使用 key-value 风格的固定记录: + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `step_id` | int32 | 步号 | +| `source_id` | int32 | CCLite/SPH/FEM | +| `metric_id` | int32 | 指标枚举 | +| `count_value` | int64 | 计数值 | +| `real_value` | real64 | 浮点值 | +| `message` | char[128] | 可选短消息 | + +详细 CSV 输出由 CCLite 自身负责,不依赖该 block。 + +--- + +# 10. 命令与状态枚举 + +## 10.1 solver id + +| id | 名称 | +| --- | --- | +| 1 | `SOLVER_SPH` | +| 2 | `SOLVER_FEM` | +| 3 | `SOLVER_CCL` | + +## 10.2 command id + +| id | 命令 | 首次版本 | 含义 | +| --- | --- | --- | --- | +| 1 | `INIT` | 0.1.x | worker 初始化 IPC | +| 2 | `READ_INPUT` | 0.1.x | 读取求解器输入 | +| 3 | `BUILD_MODEL` | 0.1.x | 构建模型 | +| 4 | `EXPORT_INTERFACE` | 0.1.x | 导出界面状态 | +| 5 | `IMPORT_LOADS` | 0.2.x | 导入 CCLite 载荷 | +| 6 | `ADVANCE` | 0.1.x | 推进一步 | +| 7 | `WRITE_OUTPUT` | 0.1.x | 写输出 | +| 8 | `WRITE_RESTART` | 0.8.x | 写 restart | +| 9 | `READ_RESTART` | 0.8.x | 读 restart | +| 99 | `STOP` | 0.1.x | 停止 worker | + +## 10.3 command state + +| id | 状态 | +| --- | --- | +| 0 | `IDLE` | +| 1 | `READY` | +| 2 | `BUSY` | +| 3 | `DONE` | +| 4 | `FAILED` | +| 5 | `TIMEOUT` | +| 6 | `STOPPED` | + +## 10.4 worker state + +| id | 状态 | +| --- | --- | +| 0 | `WORKER_CREATED` | +| 1 | `WORKER_ATTACHED` | +| 2 | `WORKER_INPUT_READ` | +| 3 | `WORKER_MODEL_BUILT` | +| 4 | `WORKER_READY` | +| 5 | `WORKER_BUSY` | +| 6 | `WORKER_FAILED` | +| 7 | `WORKER_STOPPED` | + +`worker_state` 描述 worker 生命周期,`command_state` 描述当前命令执行状态。二者不得混用。 + +## 10.5 contact state + +| id | 状态 | +| --- | --- | +| 0 | `CONTACT_NONE` | +| 1 | `CONTACT_ACTIVE` | +| 2 | `CONTACT_EDGE` | +| 3 | `CONTACT_RELEASED` | +| 4 | `CONTACT_SKIPPED_DEGENERATE` | + +## 10.6 load type + +| id | 类型 | +| --- | --- | +| 1 | `NODAL_FORCE` | +| 2 | `FACET_PRESSURE` | +| 3 | `FACET_TRACTION` | +| 4 | `FACET_RESULTANT` | + +## 10.7 SPH load mode + +| id | 类型 | +| --- | --- | +| 1 | `PARTICLE_FORCE` | +| 2 | `PARTICLE_MOMENT` | +| 3 | `CONTACT_STATE` | +| 4 | `MOTION_BOUNDARY` | +| 5 | `FACET_LOAD` | + +0.2.x 必须支持 `PARTICLE_FORCE` 和 `CONTACT_STATE`。`MOTION_BOUNDARY` 和 `FACET_LOAD` 为 0.6.x 后续 FSI 能力预留。 + +## 10.8 distribution mode + +| id | 类型 | +| --- | --- | +| 1 | `DISTRIBUTION_SHAPE_FUNCTION` | +| 2 | `DISTRIBUTION_UNIFORM` | +| 3 | `DISTRIBUTION_AREA` | +| 4 | `DISTRIBUTION_MASS` | + +0.2.x 默认使用 `DISTRIBUTION_SHAPE_FUNCTION`。若无法获得可靠形函数权重,可降级为 `DISTRIBUTION_UNIFORM` 并输出 warning。 + +--- + +# 11. 错误码与异常处理 + +## 11.1 错误码范围 + +| 范围 | 类型 | +| --- | --- | +| 0 | `CCL_OK` | +| 1000-1999 | 输入错误 | +| 2000-2999 | IPC 错误 | +| 3000-3999 | worker/进程错误 | +| 4000-4999 | 数据 block 错误 | +| 5000-5999 | 接触/几何错误 | +| 6000-6999 | 非有限值/数值保护 | + +## 11.2 必须定义的错误 + +```text +CCL_OK = 0 + +CCL_ERROR_INPUT_MISSING_KEYWORD = 1001 +CCL_ERROR_INPUT_BAD_PARAM = 1002 + +CCL_ERROR_IPC_CREATE_FAILED = 2001 +CCL_ERROR_IPC_OPEN_FAILED = 2002 +CCL_ERROR_IPC_TIMEOUT = 2003 +CCL_ERROR_IPC_EVENT_FAILED = 2004 + +CCL_ERROR_WORKER_START_FAILED = 3001 +CCL_ERROR_WORKER_FAILED = 3002 +CCL_ERROR_WORKER_BAD_STATE = 3003 + +CCL_ERROR_BLOCK_BAD_MAGIC = 4001 +CCL_ERROR_BLOCK_BAD_VERSION = 4002 +CCL_ERROR_BLOCK_BAD_STATE = 4003 +CCL_ERROR_BLOCK_SIZE_OVERFLOW = 4004 +CCL_ERROR_BLOCK_STALE_STEP = 4005 + +CCL_ERROR_GEOMETRY_DEGENERATE = 5001 +CCL_ERROR_CONTACT_OVERFLOW = 5002 + +CCL_ERROR_NONFINITE_INPUT = 6001 +CCL_ERROR_NONFINITE_LOAD = 6002 +``` + +## 11.3 异常策略 + +0.1.x 到 0.2.x: + +1. IPC 失败:终止 run; +2. worker 失败:终止 run; +3. block 版本不兼容:终止 run; +4. 单个退化几何:跳过该 candidate 并诊断; +5. 非有限输入:跳过对应 record;超过阈值终止 step; +6. 非有限载荷:禁止写入 load block 并终止 step。 + +0.8.x 后可增加错误恢复和 restart 续算。 + +--- + +# 12. 接口版本兼容策略 + +## 12.1 版本字段 + +所有 command block 和 data block 必须包含: + +```text +version_major +version_minor +layout_id +``` + +## 12.2 兼容规则 + +| 变更 | major | minor | 说明 | +| --- | --- | --- | --- | +| 修改已有字段含义 | 增加 | 重置 | 不兼容 | +| 修改已有字段顺序 | 增加 | 重置 | 不兼容 | +| 删除字段 | 增加 | 重置 | 不兼容 | +| 追加字段到 record 尾部 | 不变 | 增加 | 条件兼容 | +| 追加新 block role | 不变 | 增加 | 兼容 | +| 追加新 command id | 不变 | 增加 | 兼容 | +| 新增 SoA layout | 不变或增加 | 增加 | 取决于是否保留 AoR | + +## 12.3 0.x 阶段策略 + +0.x 阶段允许快速迭代,但每次接口变化必须同步更新本文档。 + +0.10.x 前应冻结: + +1. worker 命令行; +2. command block v1; +3. AoR v1 基本 block; +4. 错误码范围; +5. 0.2.x 接触最小 payload; +6. 0.7.x 主要算法 block。 + +--- + +# 13. 版本接口演进路线 + +| 版本线 | 接口目标 | +| --- | --- | +| 0.1.x | worker 模式、command block、named event、基础 data block、空耦合 | +| 0.2.x | SPH 粒子、FEM facet、SPH force、FEM load、基础接触字段 | +| 0.3.x | 壳厚度、edge contact、contact persistence 字段 | +| 0.4.x | 摩擦、自动 penalty、接触历史字段 | +| 0.5.x | tie bond、release、tie-to-contact 字段 | +| 0.6.x | pressure projection、boundary/ghost、SPH facet proxy | +| 0.7.x | Riemann FSI、异步子循环、强耦合残差字段 | +| 0.8.x | restart、SoA v2、性能统计、错误恢复字段 | +| 0.9.x | 工程算例、参数推荐、验收矩阵接口稳定化 | +| 0.10.x | 接口冻结、文档冻结、回归体系和工程发布候选 | + +--- + +# 14. 与 03、04、06 号文档的关系 + +## 14.1 与 03 号详细设计 + +03 号文档描述 CCLite 内部模块和实现结构。本文档只描述外部接口契约。 + +## 14.2 与 04 号数学模型 + +04 号文档定义几何、接触、耦合、FSI 和时间耦合的数学模型。本文档将这些数学对象落实为可交换数据字段。 + +## 14.3 与 06 号测试计划 + +06 号文档应按本文档逐项建立接口测试,包括: + +1. worker 启动测试; +2. command block 测试; +3. named event 同步测试; +4. data block header 校验; +5. AoR payload pack/unpack; +6. SPH/FEM 最小接触数据交换; +7. 错误码和超时测试。 + +--- + +# 15. 第一阶段冻结项 + +0.1.x/0.2.x 必须冻结: + +1. worker/service 模式存在; +2. 控制 IPC 为 named event + command shared block; +3. 大数据使用 Windows shared memory; +4. payload 采用 AoR v1; +5. block header 包含 magic/version/layout/role/step/state/count/bytes/error; +6. 最小命令集为 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`IMPORT_LOADS`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; +7. `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_TO_SPH_FORCE`、`CCL_TO_FEM_LOAD` 四类核心 block 可用; +8. `.inp` 至少支持 `CONTROL`、`SOLVER`、`IPC`、`TIME`、`INTERFACE`、`SURFACE INTERACTION`、`CONTACT PAIR`、`OUTPUT`。 diff --git a/docs/06_test_and_verification_plan.md b/docs/06_test_and_verification_plan.md new file mode 100644 index 0000000..8842630 --- /dev/null +++ b/docs/06_test_and_verification_plan.md @@ -0,0 +1,2228 @@ +# CCLite 测试与验证计划 + +## Coupling & Contact Lite for SPHLite and FEMLite + +# 1. 文档定位 + +## 1.1 编写目的 + +本文档定义 CCLite 的测试、验证和验收计划,用于约束从 0.1.x 到 0.10.x 的持续开发过程。 + +CCLite 是基于 SPHLite 和 FEMLite 的 SPH-FEM 耦合、接触联合仿真软件。其第一阶段采用 Windows/gfortran/本机共享内存通信,算法核心采用 Fortran95,数据和通信层可采用 Fortran2018,必要时可使用 C/C++ 薄层封装系统 IPC。 + +本文档的目的不是替代 04 号数学模型文档,也不是替代 05 号接口控制文档,而是把数学模型、接口协议和工程实现转化为可执行、可复现、可验收的测试体系。 + +## 1.2 文档边界 + +本文档覆盖: + +1. 单元测试; +2. 接口测试; +3. 集成测试; +4. 验证算例; +5. 回归测试; +6. 性能与稳定性测试; +7. 版本验收矩阵; +8. 测试数据、输出文件和检查工具要求。 + +本文档不覆盖: + +1. SPHLite 和 FEMLite 各自独立求解器内部算法的完整验证; +2. 商业软件级别的标准认证; +3. Linux/MPI 分布式执行的第一阶段验收; +4. 未进入 04 号数学模型文档的扩展算法。 + +SPHLite 和 FEMLite 的内部求解准确性应由各自项目负责。CCLite 只验证三程序联合运行、接口数据一致性、耦合算法正确性和联合算例结果合理性。 + +## 1.3 与其他文档的关系 + +01 号需求规格说明书定义 CCLite 要做什么。 + +02 号概要设计说明书定义 CCLite 的总体结构和模块边界。 + +03 号详细设计说明书定义 CCLite 的实现结构、数据类型和运行流程。 + +04 号数学模型与算法说明书定义接触、耦合、FSI、时间同步和稳定性算法的理论基础。 + +05 号接口控制文档定义 CCLite、SPHLite worker、FEMLite worker 之间的外部接口协议。 + +本文档负责回答: + +1. 如何确认 04 号算法实现正确; +2. 如何确认 05 号接口实现兼容; +3. 如何确认三程序联合运行稳定; +4. 每个版本需要通过哪些验收项; +5. 测试失败时如何定位责任边界。 + +## 1.4 测试原则 + +CCLite 测试体系采用以下原则: + +1. 先接口闭环,后物理精度; +2. 先 mock solver,后真实 solver; +3. 先小算例可解释,后工程算例覆盖; +4. 先确定性验收,后性能优化; +5. 先守恒和一致性检查,后复杂现象拟合; +6. 每个版本只冻结已经实现并通过测试的能力; +7. 所有测试输入和测试输出都应可重复、可追踪、可自动检查。 + +# 2. 测试对象与范围 + +## 2.1 程序对象 + +CCLite 测试体系包含三个程序对象: + +| 对象 | 测试责任 | +| --- | --- | +| CCLite | 主控流程、`.inp` 解析、IPC 调度、共享内存管理、界面数据、接触与耦合算法、诊断输出 | +| SPHLite worker | CCLite worker/service 模式、SPH 界面数据导出、外力导入、命令响应 | +| FEMLite worker | CCLite worker/service 模式、FEM 界面数据导出、面载荷导入、命令响应 | + +此外,测试体系必须提供 mock solver: + +1. `mock_sph_worker`; +2. `mock_fem_worker`; +3. 必要时提供 `mock_combined_worker`,用于极简 IPC 和时序测试。 + +mock solver 不承担真实物理计算责任,只承担可控数据生成、命令响应、故障注入和结果校验责任。 + +## 2.2 功能范围 + +测试范围包括: + +1. `.inp` 关键词解析; +2. CCLite 主控状态机; +3. worker/service 启动与退出; +4. named event 控制同步; +5. command shared block; +6. data block header; +7. AoR v1 payload; +8. 接口版本检查; +9. SPH 粒子与 FEM facet 几何搜索; +10. point-triangle、point-quad、point-edge 最近点; +11. 壳厚度接触判定; +12. penalty 接触力; +13. 法向阻尼; +14. Coulomb 摩擦; +15. FEM 节点力分配; +16. tied coupling; +17. release; +18. pressure projection; +19. boundary/ghost particle; +20. Riemann FSI; +21. 显式同步; +22. 异步子循环; +23. 弱耦合和强耦合迭代; +24. 诊断输出; +25. 非有限值、超时和异常处理; +26. 回归与性能测试。 + +## 2.3 第一阶段平台范围 + +0.1.x 第一版验收平台为: + +1. Windows; +2. gfortran; +3. 本机运行; +4. named event; +5. Windows shared memory; +6. CCLite、SPHLite worker、FEMLite worker 三独立进程。 + +Linux、MPI、socket、跨机器通信只作为预留方向,不进入 0.1.x 验收。 + +## 2.4 测试通过定义 + +一个测试项通过必须同时满足: + +1. 程序正常退出,返回码符合预期; +2. 日志没有未解释的 `ERROR`; +3. 诊断 CSV 字段完整; +4. 数值结果满足该测试项容差; +5. 共享内存和事件资源被释放; +6. 失败路径测试能够给出预期错误码; +7. 测试结果可由自动检查脚本重复判定。 + +# 3. 测试分层 + +## 3.1 单元测试 + +单元测试面向单个模块、单个函数或单个数据结构,重点验证局部逻辑正确性。 + +单元测试不依赖真实 SPHLite 和 FEMLite 主程序,不依赖三进程调度。必要时可直接构造内存数据结构。 + +单元测试覆盖: + +1. `.inp` 解析器; +2. keyword 参数校验; +3. vector、AABB、hash grid; +4. 最近点算法; +5. 接触穿透量计算; +6. 接触力计算; +7. FEM 节点力分配; +8. 接触诊断量; +9. data block header 校验; +10. command block 字段编码; +11. 错误码映射; +12. 非有限值检查。 + +## 3.2 接口测试 + +接口测试面向 05 号文档定义的外部接口协议。 + +接口测试关注: + +1. worker 启动参数; +2. command block 字段; +3. named event wait/signal/reset 责任; +4. heartbeat 和 ack; +5. shared memory block 创建、打开、关闭; +6. data block header; +7. AoR v1 payload; +8. block role; +9. layout id; +10. 版本兼容; +11. 超时和异常处理。 + +接口测试必须优先使用 mock solver,因为 mock solver 能稳定构造正常路径和错误路径。 + +## 3.3 集成测试 + +集成测试面向 CCLite 与 worker 的联合运行。 + +集成测试分三类: + +1. CCLite + mock SPH worker + mock FEM worker; +2. CCLite + 真实 SPHLite worker + mock FEM worker,或反向组合; +3. CCLite + 真实 SPHLite worker + 真实 FEMLite worker。 + +0.1.x 必须完成第一类集成测试。 + +0.2.x 起逐步增加真实 worker 集成测试。 + +## 3.4 验证算例 + +验证算例面向数学模型和物理行为。 + +验证算例应优先选择: + +1. 有解析解的简单问题; +2. 可用手工计算复核的极小问题; +3. 可与独立脚本结果比较的问题; +4. 经典文献或工程常用 benchmark; +5. 可稳定重复的工程简化问题。 + +验证算例不追求一开始覆盖所有复杂现象,而应确保每个算法能力进入版本时有对应的最小可信证据。 + +## 3.5 回归测试 + +回归测试用于保证新版本没有破坏已有能力。 + +所有已经验收通过的用例应进入回归集合。若一个用例因为算法升级导致数值基线合理变化,必须记录: + +1. 变化原因; +2. 影响范围; +3. 新旧结果对比; +4. 是否需要调整容差; +5. 谁批准基线更新。 + +## 3.6 性能与稳定性测试 + +性能测试不作为 0.1.x 核心验收项,但必须从 0.2.x 开始保留基础指标。 + +性能与稳定性测试关注: + +1. 单步 IPC 延迟; +2. data block 读写耗时; +3. 几何搜索耗时; +4. 接触对数量; +5. 单步总耗时; +6. 内存占用; +7. 长时间运行稳定性; +8. 大接触面数量下的退化行为。 + +0.8.x 起,性能测试应覆盖 AoR v1 与 SoA v2 block 的对比。 + +# 4. 测试环境与工具 + +## 4.1 编译环境 + +第一阶段推荐测试环境: + +| 项目 | 要求 | +| --- | --- | +| 操作系统 | Windows | +| Fortran 编译器 | gfortran | +| C/C++ 编译器 | 仅 IPC 薄层必要时使用 | +| 构建方式 | 批处理、Makefile 或 CMake 均可,实际以仓库实现为准 | +| 字符编码 | UTF-8 without BOM | + +测试脚本和测试数据必须避免依赖开发者本机绝对路径。 + +## 4.2 运行模式 + +测试应覆盖三种运行模式: + +| 模式 | 说明 | +| --- | --- | +| check | 只检查输入、接口配置和资源可用性 | +| dry-run | 创建 IPC 资源、启动 worker、执行空耦合或有限步模拟,不做完整物理计算 | +| run | 执行真实联合仿真 | + +0.1.x 必须完成 check 和 dry-run 测试。 + +0.2.x 起 run 模式进入接触验证。 + +## 4.3 Python checker + +允许使用 Python 编写测试检查脚本,用于: + +1. 读取 CSV; +2. 检查误差; +3. 比较基线; +4. 生成简短测试报告; +5. 检查日志关键字; +6. 统计性能指标。 + +允许借助仓库中的 `.\Python\` 目录实现以下辅助能力: + +1. 生成小规模验证算例的 `.inp` 输入文件; +2. 生成 mock worker 使用的可控输入数据; +3. 计算解析解或独立参考解; +4. 检查 CCLite 输出 CSV; +5. 汇总 `verification_report.json` 或 `verification_report.txt`; +6. 对真实 SPHLite/FEMLite worker 输出进行调试性解析。 + +Python checker 不应替代 Fortran 核心算法实现。Python 只用于测试、验证、参考解、算例生成和自动化检查。 + +建议 `.\Python\` 后续按以下职责细分: + +```text +Python/ + checkers/ + references/ + casegen/ + runners/ +``` + +其中 `checkers` 负责输出检查,`references` 负责解析解或独立参考值,`casegen` 负责生成小算例输入,`runners` 负责封装外部程序运行。已有调试脚本可在不破坏其用途的前提下逐步迁入该结构。 + +## 4.4 推荐目录 + +建议测试目录采用: + +```text +tests/ + unit/ + interface/ + integration/ + verification/ + regression/ + performance/ + data/ + baselines/ + checkers/ +``` + +建议算例目录采用: + +```text +cases/ + v0_1_ipc_empty_coupling/ + v0_2_single_particle_wall/ + v0_3_shell_edge_contact/ + v0_4_friction_slide/ + v0_5_tied_release/ + v0_6_pressure_plate/ + v0_7_riemann_interface/ + v0_8_stability_suite/ + v0_9_engineering_cases/ +``` + +目录名称中的版本号表示该算例第一次进入验收的版本,不表示该算例只在该版本运行。 + +## 4.5 输出文件 + +每个测试算例至少应生成: + +1. `run.log`; +2. `ipc_report.csv`; +3. `contact_report.csv`,若该算例涉及接触; +4. `force_balance.csv`,若该算例涉及力交换; +5. `timestep_report.csv`,若该算例涉及时间步控制; +6. `verification_report.json` 或 `verification_report.txt`。 + +CSV 文件用于数值自动检查,日志用于人工定位。 + +## 4.6 容差约定 + +测试容差分为四类: + +| 类型 | 含义 | +| --- | --- | +| bitwise | 字段、枚举、layout、错误码必须完全一致 | +| absolute | 使用绝对误差检查 | +| relative | 使用相对误差检查 | +| statistical | 用于长时间或大规模算例的统计指标 | + +接口测试默认使用 bitwise 判定。 + +几何测试优先使用 absolute 判定。 + +物理验证测试根据变量量级同时使用 absolute 和 relative 判定。 + +初始建议: + +| 项目 | 默认容差 | +| --- | --- | +| 坐标最近点 | `1.0e-10` 到 `1.0e-8`,按精度实现调整 | +| 力平衡相对误差 | `1.0e-8` 到 `1.0e-5`,按算例规模调整 | +| 能量诊断误差 | `1.0e-6` 到 `1.0e-3`,按模型和时间步调整 | +| 接触穿透量 | 不超过用户设定接触尺度的指定比例 | +| IPC 字段 | 完全一致 | + +正式容差应在具体测试用例中写明,不应只依赖本文档默认值。 + +# 5. 测试数据与诊断输出 + +## 5.1 输入文件 + +CCLite 测试输入采用 Abaqus 风格 `.inp`。 + +每个联合测试至少包含: + +1. CCLite `.inp`; +2. SPHLite 输入文件,真实 worker 测试需要; +3. FEMLite 输入文件,真实 worker 测试需要; +4. 期望输出说明; +5. 自动检查配置。 + +mock solver 测试可只提供 CCLite `.inp` 和 mock 数据配置。 + +## 5.2 基线数据 + +基线数据用于回归比较。 + +基线数据应包含: + +1. 输入文件版本; +2. CCLite 版本; +3. SPHLite 和 FEMLite 版本; +4. 编译器信息; +5. 平台信息; +6. 关键输出 CSV; +7. 检查报告; +8. 容差配置。 + +基线更新必须有明确原因,不能因为测试失败而直接覆盖旧基线。 + +## 5.3 诊断量 + +接触和耦合测试至少检查以下诊断量: + +| 诊断量 | 说明 | +| --- | --- | +| `num_candidate_pairs` | 宽相候选对数量 | +| `num_active_contacts` | 活跃接触数量 | +| `max_penetration` | 最大穿透量 | +| `sum_force_sph` | CCLite 写给 SPH 的总力 | +| `sum_force_fem` | CCLite 写给 FEM 的总力 | +| `force_balance_error` | 作用反作用误差 | +| `moment_balance_error` | 力矩平衡误差 | +| `contact_work` | 接触功 | +| `ipc_latency` | IPC 同步耗时 | +| `step_status` | 步状态 | +| `error_code` | 错误码 | + +0.6.x 起,应增加 FSI 诊断量。 + +0.7.x 起,应增加 Riemann FSI 和子循环诊断量。 + +## 5.4 日志要求 + +日志必须记录: + +1. 程序版本; +2. 输入文件路径; +3. worker 启动命令; +4. shared memory block 名称; +5. named event 名称; +6. layout id; +7. command id; +8. step id; +9. substep id; +10. iteration id; +11. worker state; +12. 超时与错误码; +13. 资源释放结果。 + +日志中的错误信息应足以判断错误属于输入、接口、算法、worker 还是系统资源。 + +# 6. 单元测试计划 + +## 6.1 `.inp` 解析测试 + +`.inp` 解析测试覆盖: + +1. 正常关键词; +2. 参数顺序变化; +3. 大小写兼容; +4. 注释行; +5. 空行; +6. 重复关键词; +7. 缺失必需参数; +8. 未知关键词; +9. 非法枚举; +10. 非法数值范围; +11. 文件路径参数; +12. 多 solver 配置。 + +通过标准: + +1. 合法输入生成正确 case 对象; +2. 非法输入生成明确错误码; +3. 错误行号和关键词名可定位; +4. 不因空行、注释、大小写造成误判。 + +## 6.2 几何基础测试 + +几何基础测试覆盖: + +1. vector 点积、叉积、长度、归一化; +2. AABB 合并、扩展、相交; +3. hash grid cell index; +4. 点到线段最近点; +5. 点到三角形最近点; +6. 点到四边形最近点; +7. barycentric 坐标; +8. 边缘 fallback; +9. 退化三角形; +10. 退化四边形; +11. 壳厚度间隙; +12. 法向翻转。 + +通过标准: + +1. 最近点坐标满足容差; +2. 穿透量符号与 04 号文档一致; +3. 退化几何不产生未定义结果; +4. edge fallback 能识别边缘接触; +5. 法向方向可解释并可诊断。 + +## 6.3 搜索算法测试 + +搜索算法测试覆盖: + +1. 单粒子单 facet; +2. 多粒子单 facet; +3. 单粒子多 facet; +4. cell 边界上的粒子; +5. 搜索半径变化; +6. 空集合; +7. 大量非接触对象; +8. 候选对去重; +9. surface id 过滤; +10. 接触 pair id 稳定性。 + +通过标准: + +1. 候选对不漏检指定接触; +2. 候选对不出现重复记录; +3. 空输入返回空结果; +4. 搜索耗时随规模增长符合预期; +5. 候选对数量可诊断。 + +## 6.4 接触力测试 + +接触力单元测试覆盖: + +1. 零穿透; +2. 正穿透; +3. 负间隙; +4. 法向 penalty; +5. 法向阻尼; +6. 切向相对速度; +7. Coulomb 粘着区; +8. Coulomb 滑移区; +9. 力限幅; +10. 非有限值保护; +11. FEM 三角形节点分配; +12. FEM 四边形节点分配; +13. 力矩一致性。 + +通过标准: + +1. 接触开启和关闭条件正确; +2. 法向力方向正确; +3. 摩擦力不超过 Coulomb 上限; +4. 分配到 FEM 节点的合力等于接触反力; +5. 分配后总力矩误差满足容差; +6. 非有限输入被拒绝或安全处理。 + +## 6.5 Tied 与 Release 测试 + +Tied 与 release 单元测试覆盖: + +1. tie 初始绑定; +2. tie 位移约束; +3. penalty tie 力; +4. release 阈值; +5. release 后转入 contact; +6. 多点 tie; +7. tie 诊断输出; +8. 能量记录。 + +通过标准: + +1. tie 对象在未 release 前保持绑定关系; +2. release 条件满足时状态只转换一次; +3. release 后接触状态与普通 contact 一致; +4. 诊断量能追踪状态变化。 + +## 6.6 FSI 数学测试 + +FSI 单元测试覆盖: + +1. pressure projection; +2. 面法向压力转节点载荷; +3. FEM 运动边界速度导出; +4. boundary particle 数据构造; +5. ghost particle 数据构造; +6. 声阻抗 Riemann 近似; +7. 界面压力; +8. 界面速度; +9. 载荷方向; +10. 单位一致性。 + +通过标准: + +1. 均匀压力载荷积分正确; +2. 界面速度和压力符号与 04 号文档一致; +3. Riemann 简化解在退化输入下稳定; +4. 单位换算不引入隐藏比例因子。 + +## 6.7 时间耦合测试 + +时间耦合单元测试覆盖: + +1. 显式同步步进; +2. 异步子循环步进; +3. macro step; +4. substep id; +5. iteration id; +6. force relaxation; +7. 强耦合残差; +8. 时间步拒绝; +9. 时间步重试; +10. 最大迭代失败。 + +通过标准: + +1. 时间不倒退; +2. step id、substep id、iteration id 单调可解释; +3. 子循环结束时间与 macro step 对齐; +4. 失败路径给出可追踪错误码。 + +# 7. 接口测试计划 + +## 7.1 Worker/Service 启动测试 + +worker 启动测试覆盖: + +1. 正常启动; +2. 缺少 worker 参数; +3. 非法 solver id; +4. shared memory 名称错误; +5. event 名称错误; +6. worker 初始化超时; +7. worker 主动退出; +8. CCLite 请求退出; +9. 重复启动; +10. 资源清理。 + +通过标准: + +1. worker 能进入 `READY` 状态; +2. `heartbeat_seq` 能递增; +3. CCLite 能收到 `ack_seq`; +4. 异常启动返回明确错误码; +5. 退出后 IPC 资源被释放。 + +## 7.2 Command Shared Block 测试 + +command block 测试覆盖 05 号文档中的字段: + +1. `magic`; +2. `abi_version`; +3. `layout_id`; +4. `solver_id`; +5. `command_id`; +6. `command_seq`; +7. `ack_seq`; +8. `step_id`; +9. `substep_id`; +10. `iteration_id`; +11. `command_flags`; +12. `heartbeat_seq`; +13. `worker_state`; +14. `int_param[16]`; +15. `real_param[16]`; +16. `macro_dt`; +17. `error_code`。 + +通过标准: + +1. 所有字段按 05 号文档布局编码; +2. 字节数、偏移和对齐满足接口定义; +3. command seq 与 ack seq 配对正确; +4. worker state 转换合法; +5. 错误码不被覆盖; +6. 旧版本字段兼容策略符合预期。 + +## 7.3 Named Event 测试 + +named event 测试覆盖: + +1. `COMMAND_EVENT`; +2. `DONE_EVENT`; +3. CCLite reset command event; +4. CCLite reset done event; +5. worker wait command event; +6. worker signal done event; +7. 超时; +8. signal 丢失; +9. 重复 signal; +10. worker 异常退出。 + +通过标准: + +1. reset 责任符合 05 号文档; +2. 正常命令不丢失; +3. 超时能被 CCLite 识别; +4. worker 卡死时 CCLite 不永久等待; +5. 日志记录事件名和 command seq。 + +## 7.4 Data Block Header 测试 + +data block header 测试覆盖: + +1. block magic; +2. block role; +3. layout id; +4. header size; +5. record size; +6. record count; +7. capacity; +8. byte size; +9. data state; +10. producer id; +11. consumer id; +12. step id; +13. substep id; +14. checksum 或 header 校验; +15. 保留字段置零。 + +通过标准: + +1. CCLite 能拒绝非法 header; +2. 生产者和消费者 id 匹配; +3. record count 不超过 capacity; +4. record size 与 layout id 匹配; +5. buffer state 转换合法。 + +## 7.5 AoR v1 Payload 测试 + +AoR v1 payload 测试覆盖: + +1. `SPH_TO_CCL_PARTICLE`; +2. `SPH_TO_CCL_FACET`; +3. `FEM_TO_CCL_FACET`; +4. `CCL_TO_SPH_FORCE`; +5. `CCL_TO_FEM_LOAD`; +6. `CCL_DIAGNOSTIC`。 + +重点字段包括: + +1. id; +2. position; +3. velocity; +4. mass; +5. radius 或 smoothing length; +6. density; +7. pressure; +8. sound_speed; +9. node ids; +10. facet normal; +11. surface_id; +12. shell_thickness; +13. mass_per_area; +14. valid_flags; +15. source id; +16. load_mode; +17. distribution_mode。 + +通过标准: + +1. payload 字段与 05 号文档一致; +2. 空 payload 可被接受; +3. 最大 capacity payload 可被处理; +4. 无效 record 被跳过或报错,行为必须符合定义; +5. CCLite 不读取未初始化字段。 + +## 7.6 版本兼容测试 + +版本兼容测试覆盖: + +1. 相同 ABI 版本; +2. minor 版本差异; +3. 不支持的 layout id; +4. 不支持的 block role; +5. AoR v1; +6. SoA v2 预留; +7. 字段扩展; +8. worker 版本低于 CCLite; +9. worker 版本高于 CCLite; +10. 强制拒绝不兼容版本。 + +通过标准: + +1. 可兼容版本继续运行; +2. 不兼容版本在初始化阶段停止; +3. 错误信息写出双方版本; +4. 不发生 silent fallback。 + +## 7.7 故障注入接口测试 + +故障注入测试覆盖: + +1. worker 不启动; +2. worker 启动后不响应; +3. worker 写入错误 header; +4. worker 写入错误 layout id; +5. worker 写入 NaN; +6. worker record count 超限; +7. worker command seq 不匹配; +8. worker heartbeat 停止; +9. shared memory 打开失败; +10. named event 打开失败; +11. CCLite 中途请求终止; +12. worker 中途崩溃。 + +通过标准: + +1. CCLite 不崩溃; +2. 错误码符合定义; +3. 资源释放; +4. 日志可定位故障点; +5. 后续测试不受残留资源影响。 + +# 8. 集成测试计划 + +## 8.1 CCLite + mock workers + +0.1.x 必须完成 CCLite + mock SPH worker + mock FEM worker 的集成测试。 + +测试场景包括: + +1. 三进程正常启动; +2. worker ready; +3. 初始化 data block; +4. 执行空耦合 step; +5. 写入 mock SPH 粒子; +6. 写入 mock FEM facet; +7. CCLite 读取数据; +8. CCLite 写回空载荷; +9. worker ack; +10. CCLite 正常退出; +11. 多步循环; +12. 中途终止。 + +通过标准: + +1. 至少连续运行指定步数; +2. 每步 command seq 和 ack seq 匹配; +3. 所有 data block header 合法; +4. IPC 诊断完整; +5. 退出后没有残留 worker 进程。 + +## 8.2 CCLite + 单真实 worker + +单真实 worker 集成测试用于分阶段接入 SPHLite 和 FEMLite。 + +组合包括: + +1. CCLite + 真实 SPHLite worker + mock FEM worker; +2. CCLite + mock SPH worker + 真实 FEMLite worker。 + +通过标准: + +1. 真实 worker 能进入 CCLite worker/service 模式; +2. 真实 worker 能按 05 号接口写出 payload; +3. CCLite 能读取真实 worker 数据; +4. CCLite 写回载荷后真实 worker 能接受; +5. 单真实 worker 的异常不会破坏另一 mock worker。 + +## 8.3 CCLite + 双真实 workers + +双真实 worker 集成测试用于真实联合仿真。 + +测试阶段: + +1. 空耦合; +2. 单步接触; +3. 多步接触; +4. 简单 FSI; +5. tied/release; +6. 子循环; +7. 长时间运行。 + +通过标准: + +1. 三程序按主控顺序运行; +2. 两个 worker 不直接通信; +3. 所有数据交换都经过 CCLite; +4. 接口载荷方向正确; +5. 诊断量可解释; +6. 程序能够正常结束。 + +## 8.4 check / dry-run / run 集成测试 + +每个关键算例应尽量覆盖: + +| 模式 | 检查内容 | +| --- | --- | +| check | 输入、路径、关键词、接口配置 | +| dry-run | IPC 资源、worker 启动、空耦合循环 | +| run | 真实联合计算和结果验证 | + +check 和 dry-run 是定位问题的第一层防线,不能只依赖 run 模式。 + +# 9. 验证算例计划 + +## 9.1 总体约定 + +验证算例是算法和工程行为进入版本验收的最小可信证据。验证算例不同于演示算例:验证算例必须有明确输入、参考值、检查指标和通过判据;演示算例可以展示功能效果,但不能单独作为算法正确性证据。 + +每个验证算例必须包含: + +1. 算例编号; +2. 首次进入验收的版本; +3. 验证目标; +4. 使用的 CCLite `.inp`; +5. 使用 mock worker 还是真实 worker; +6. SPH 输入或 mock SPH 数据; +7. FEM 输入或 mock FEM 数据; +8. 参考值来源; +9. 输出文件清单; +10. Python checker; +11. 通过判据; +12. 失败分类建议。 + +凡是没有解析值、独立脚本参考值或可手算参考值的算例,只能作为演示、稳定性观察或工程趋势算例,不能作为核心算法正确性验收算例。 + +## 9.2 算例实现层级 + +验证算例按三层推进: + +| 层级 | 说明 | 适用版本 | +| --- | --- | --- | +| A 层:mock 算例 | 使用 mock worker 或直接构造接口数据,验证 CCLite 算法和接口 | 0.1.x 起 | +| B 层:单真实 worker 算例 | 一侧真实 SPHLite/FEMLite worker,另一侧 mock worker | 0.2.x 起 | +| C 层:双真实 worker 算例 | SPHLite 和 FEMLite 都以 worker/service 模式参与 | 0.2.x 后逐步增加 | + +所有核心物理算例应先完成 A 层,再进入 B 层和 C 层。这样可以先排除 CCLite 算法和接口错误,再讨论真实求解器内部误差。 + +## 9.3 Python 辅助算例约定 + +允许借助 `.\Python\` 实现验证算例辅助能力,但 Fortran 仍是 CCLite 算法核心。 + +建议 Python 脚本职责如下: + +| 目录 | 职责 | +| --- | --- | +| `Python/casegen/` | 生成小规模 `.inp`、mock 数据和固定参数表 | +| `Python/references/` | 计算解析解、半解析参考解或独立公式结果 | +| `Python/checkers/` | 读取 CSV、检查误差、生成验证报告 | +| `Python/runners/` | 封装 CCLite、SPHLite、FEMLite 或 mock worker 的运行 | + +Python checker 的输出建议统一为: + +```text +verification_report.json +``` + +报告至少包含: + +1. `case_id`; +2. `case_version`; +3. `status`; +4. `tolerance`; +5. `metrics`; +6. `failed_checks`; +7. `input_files`; +8. `output_files`; +9. `reference_source`。 + +Python 参考解必须独立于 CCLite Fortran 实现,不应直接复制 Fortran 源码逻辑。若参考解也是同一公式实现,应在报告中说明其参考公式来自 04 号文档的具体章节。 + +## 9.4 0.1.x 空耦合与 IPC 验证算例 + +算例编号:`V010_EMPTY_COUPLING` + +验证目标: + +1. CCLite 可独立启动; +2. SPHLite mock worker 和 FEMLite mock worker 可进入 worker/service 模式; +3. Windows shared memory 和 named event 可形成闭环; +4. command block、data block header 和 AoR v1 payload 可完成最小读写; +5. 空耦合循环可重复执行。 + +输入模型: + +1. CCLite `.inp` 指定两个 worker、共享内存名称、event 名称、总步数和输出目录; +2. mock SPH worker 每步写入 0 个或少量固定粒子; +3. mock FEM worker 每步写入 0 个或少量固定 facet; +4. CCLite 不产生真实接触力,只写回空载荷或零载荷。 + +参考值: + +1. `command_seq` 与 `ack_seq` 应逐步配对; +2. `step_id` 应从 1 到指定步数连续递增; +3. `num_active_contacts = 0`; +4. `sum_force_sph = 0`; +5. `sum_force_fem = 0`。 + +输出文件: + +1. `run.log`; +2. `ipc_report.csv`; +3. `force_balance.csv`; +4. `verification_report.json`。 + +Python 检查: + +1. 检查 `ipc_report.csv` 中每步 seq/ack 配对; +2. 检查 worker state 合法; +3. 检查超时次数为 0; +4. 检查空耦合载荷为 0; +5. 检查进程正常退出。 + +通过判据: + +1. 连续运行不少于 100 个空耦合 step; +2. 无 IPC 超时; +3. 无未解释错误码; +4. 退出后没有残留 worker; +5. 资源释放日志完整。 + +## 9.5 几何验证算例 + +算例编号:`V020_GEOMETRY_PRIMITIVES` + +首次验收版本:0.2.x,0.3.x 扩展 shell、edge 和 quad。 + +验证目标: + +1. 验证 04 号第 4 章的几何 primitive; +2. 验证最近点、法向间隙和穿透量; +3. 验证退化几何处理; +4. 验证后续接触力计算的几何输入可靠。 + +输入模型: + +| 子算例 | 输入 | +| --- | --- | +| 点到三角形内部 | 一个粒子位于三角形法向上方,投影点在三角形内部 | +| 点到三角形边 | 一个粒子投影到三角形外部且最近点在线段上 | +| 点到三角形顶点 | 一个粒子最近点为三角形顶点 | +| 点到四边形内部 | 一个粒子投影到四边形内部 | +| 非平面四边形 | 四边形四点轻微非共面 | +| 壳中面接触 | 设置 shell thickness,粒子接近壳中面 | +| 退化 facet | 三角形面积为 0 或四边形两点重合 | + +参考值: + +1. 最近点坐标由 Python `references` 脚本按解析几何公式计算; +2. barycentric 坐标可手工复核; +3. 壳厚度穿透量按 04 号第 4.6 节公式计算; +4. 退化 facet 的期望行为为诊断并跳过。 + +输出文件: + +1. `contact_report.csv`; +2. `geometry_report.csv`,若实现提供; +3. `verification_report.json`。 + +Python 检查: + +1. 比较最近点坐标; +2. 比较法向间隙; +3. 比较穿透量; +4. 检查退化 facet 数量; +5. 检查 active contact 状态。 + +通过判据: + +1. 最近点误差满足几何容差; +2. 接触状态符合穿透量定义; +3. quad 与等价 triangle 组合结果一致; +4. 壳厚度改变接触开启位置; +5. 退化几何不产生接触力。 + +## 9.6 单粒子撞刚性面 + +算例编号:`V020_SINGLE_PARTICLE_WALL` + +首次验收版本:0.2.x。 + +验证目标: + +1. 作为 0.2.x 第一个真实物理验收算例; +2. 验证 SPH 粒子到 FEM facet 的 penalty 接触主链路; +3. 验证接触开启、法向力、冲量、力平衡和诊断输出; +4. 为真实 SPHLite/FEMLite worker 接入提供最小联合算例。 + +实现层级: + +1. A 层:mock SPH 粒子和 mock FEM facet,先验证 CCLite 接触算法; +2. B 层:真实 SPHLite worker + mock FEM worker,验证 SPH 外力写回; +3. B 层:mock SPH worker + 真实 FEMLite worker,验证 FEM 面载荷写回; +4. C 层:真实 SPHLite worker + 真实 FEMLite worker,验证完整联合运行。 + +输入模型: + +1. 一个 SPH 粒子; +2. 一个固定 FEM 三角形 facet; +3. 粒子初始位置在 facet 法向外侧; +4. 粒子速度指向 facet; +5. 首个验收版本不启用摩擦; +6. 阻尼可分为关闭和开启两个子算例。 + +参考值: + +1. 接触开启条件由粒子半径、facet 位置和法向间隙手算; +2. 法向 penalty 力由 04 号第 5.3 节公式计算; +3. 阻尼子算例由 04 号第 5.4 节公式计算; +4. 冲量参考值可由 Python 按离散时间积分计算; +5. 力平衡参考值为 SPH 力与 FEM 反力相加为 0。 + +输出文件: + +1. `contact_report.csv`; +2. `force_balance.csv`; +3. `timestep_report.csv`; +4. `verification_report.json`。 + +Python 检查: + +1. 检查接触开启步; +2. 检查最大穿透量; +3. 检查法向力方向; +4. 检查法向力幅值; +5. 检查冲量; +6. 检查 force balance; +7. 检查无阻尼和有阻尼能量趋势。 + +通过判据: + +1. 未接触前接触力为 0; +2. 穿透后法向力阻止继续穿透; +3. SPH 力与 FEM 反力满足平衡容差; +4. 无阻尼时能量误差满足容差; +5. 有阻尼时能量耗散方向正确; +6. 真实 worker 算例中载荷方向与 mock 算例一致。 + +## 9.7 多粒子压平面 + +算例编号:`V020_MULTI_PARTICLE_PLANE` + +首次验收版本:0.2.x。 + +验证目标: + +1. 验证多接触对搜索; +2. 验证接触力累加; +3. 验证 FEM 节点载荷分配; +4. 验证总力和总力矩平衡; +5. 验证接触对去重。 + +输入模型: + +1. 多个 SPH 粒子按规则阵列布置; +2. 一个或多个 FEM facet 构成平面; +3. 粒子垂直压向平面; +4. FEM 平面保持固定或做规定运动; +5. 初始可使用 mock 数据,随后接入真实 worker。 + +参考值: + +1. 每个粒子的穿透量可由几何关系手算; +2. 每个粒子的 penalty 力由 04 号第 5 章公式计算; +3. FEM 节点载荷由 barycentric 或面积权重计算; +4. 总力矩以选定参考点计算。 + +输出文件: + +1. `contact_report.csv`; +2. `force_balance.csv`; +3. `verification_report.json`。 + +Python 检查: + +1. 检查活跃接触数量; +2. 检查每个粒子接触力; +3. 检查 FEM 节点力之和; +4. 检查总力矩; +5. 检查重复 pair id。 + +通过判据: + +1. 总力等于各粒子接触力累加; +2. 节点力分配后总力和总力矩一致; +3. 无重复接触对; +4. 接触诊断 CSV 完整; +5. 接触 pair id 在连续步中可追踪。 + +## 9.8 边缘与壳厚度接触 + +算例编号:`V030_SHELL_EDGE_CONTACT` + +首次验收版本:0.3.x。 + +验证目标: + +1. 验证 shell thickness; +2. 验证 edge fallback; +3. 验证 triangle 和 quad facet; +4. 验证接触状态连续性; +5. 验证法向跳变诊断。 + +输入模型: + +1. 粒子靠近 FEM 壳边缘; +2. 设置非零 shell thickness; +3. 同时构造 triangle 和 quad 子算例; +4. 粒子轨迹经过面内部、边缘和角点; +5. quad 子算例应提供等价 triangle 拆分参考。 + +参考值: + +1. 壳厚度修正由 04 号第 4.6 节计算; +2. edge 最近点由点到线段公式计算; +3. quad 参考值由两个 triangle 子问题取一致结果; +4. 接触状态连续性由连续步 active contact 变化检查。 + +输出文件: + +1. `contact_report.csv`; +2. `geometry_report.csv`,若实现提供; +3. `verification_report.json`。 + +Python 检查: + +1. 检查边缘附近是否漏检; +2. 检查 shell thickness 对接触开启位置的影响; +3. 检查 quad 与 triangle 组合一致性; +4. 检查法向跳变幅度; +5. 检查异常几何诊断。 + +通过判据: + +1. 边缘附近不漏检; +2. 壳厚度改变接触开启位置; +3. quad 与等价 triangle 组合结果一致; +4. 接触力不出现非物理尖峰,或尖峰被诊断; +5. 退化 facet 不产生有效接触力。 + +## 9.9 摩擦滑移 + +算例编号:`V040_FRICTION_SLIDE` + +首次验收版本:0.4.x。 + +验证目标: + +1. 验证 Coulomb 摩擦; +2. 验证粘着和滑移状态; +3. 验证切向力方向; +4. 验证摩擦耗能; +5. 验证稳定时间步和阻尼对结果的影响。 + +输入模型: + +1. 一个粒子或粒子组与 FEM 平面接触; +2. 设置法向预压或重力等效载荷; +3. 设置切向相对速度; +4. 设置多个摩擦系数; +5. 分别运行粘着子算例和滑移子算例。 + +参考值: + +1. 摩擦上限为 `mu * normal_force`; +2. 滑移方向由相对切向速度确定; +3. 粘着区切向力由 penalty 切向模型或历史位移计算; +4. 摩擦功应为非正值,具体符号按 04 号文档约定。 + +输出文件: + +1. `contact_report.csv`; +2. `force_balance.csv`; +3. `timestep_report.csv`; +4. `verification_report.json`。 + +Python 检查: + +1. 检查切向力方向; +2. 检查摩擦力上限; +3. 检查粘着到滑移转换; +4. 检查接触功; +5. 检查能量耗散方向。 + +通过判据: + +1. 摩擦力反向于相对滑移趋势; +2. 摩擦力不超过 Coulomb 上限; +3. 能量不因摩擦非物理增加; +4. 诊断输出区分 normal 和 tangential 分量; +5. 关闭摩擦时结果退化到无摩擦算例。 + +## 9.10 Tied Coupling 与 Release + +算例编号:`V050_TIED_RELEASE` + +首次验收版本:0.5.x。 + +验证目标: + +1. 验证 tied coupling; +2. 验证 release 阈值; +3. 验证 release 后转入普通 contact; +4. 验证状态转换诊断; +5. 验证 tied/release 能量记录。 + +输入模型: + +1. SPH 粒子初始绑定到 FEM 面; +2. FEM 面发生规定运动或受载运动; +3. 设置 release 位移、力或能量阈值; +4. release 后粒子继续与 FEM 面接触; +5. 至少包含 release 和不 release 两个子算例。 + +参考值: + +1. tie 位移由初始局部坐标和 FEM 面运动计算; +2. tie 力由 04 号第 6 章 penalty tie 模型计算; +3. release 触发步由阈值条件计算; +4. release 后接触力参考普通 contact 公式。 + +输出文件: + +1. `contact_report.csv`; +2. `tie_release_report.csv`,若实现提供; +3. `force_balance.csv`; +4. `verification_report.json`。 + +Python 检查: + +1. 检查初始绑定关系; +2. 检查 release 前 tie 状态; +3. 检查 release 触发步; +4. 检查 release 只触发一次; +5. 检查 release 后不再施加 tie 约束; +6. 检查 release 后 contact 状态。 + +通过判据: + +1. release 前绑定对象稳定; +2. release 条件可复现; +3. release 后状态转换不可逆,除非输入显式允许重新绑定; +4. release 后接触力与普通 contact 一致; +5. 诊断能还原状态变化。 + +## 9.11 均匀压力作用于 FEM 面 + +算例编号:`V060_PRESSURE_TO_FEM` + +首次验收版本:0.6.x。 + +验证目标: + +1. 验证 pressure projection; +2. 验证 SPH 压力到 FEM 面载荷; +3. 验证节点载荷分配; +4. 验证载荷方向和单位; +5. 验证 FSI 基础诊断输出。 + +输入模型: + +1. SPH 侧提供均匀压力场; +2. FEM 侧提供一个或多个平面 facet; +3. CCLite 将压力转换为 FEM 面载荷; +4. FEM 可固定,只验证载荷积分; +5. 子算例可覆盖 triangle 和 quad。 + +参考值: + +1. 总载荷为 `pressure * area`; +2. 节点载荷由面积坐标或形函数权重分配; +3. 载荷方向由 FEM facet 法向和 04 号约定决定; +4. 力矩由节点位置和节点载荷计算。 + +输出文件: + +1. `force_balance.csv`; +2. `fsi_report.csv`,若实现提供; +3. `verification_report.json`。 + +Python 检查: + +1. 检查总载荷; +2. 检查节点载荷; +3. 检查力矩; +4. 检查载荷方向; +5. 检查单位换算。 + +通过判据: + +1. 总载荷等于压力乘面积; +2. 节点分配保持总力和总力矩; +3. 载荷方向与法向约定一致; +4. 单位不出现比例错误; +5. 压力为 0 时载荷为 0。 + +## 9.12 运动边界与 Boundary/Ghost Particle + +算例编号:`V060_MOVING_BOUNDARY` + +首次验收版本:0.6.x。 + +验证目标: + +1. 验证 FEM 运动边界到 SPH 的传递; +2. 验证 boundary particle 数据; +3. 验证 ghost particle 数据; +4. 验证边界速度和时间同步; +5. 验证数据生命周期。 + +输入模型: + +1. FEM 边界做规定速度运动; +2. CCLite 读取 FEM 边界位置和速度; +3. SPH worker 接收边界速度或 ghost/boundary 数据; +4. 使用小规模规则粒子分布; +5. 包含静止边界和运动边界两个子算例。 + +参考值: + +1. 边界速度由规定运动函数计算; +2. boundary/ghost 位置由 FEM facet 和法向偏移计算; +3. step 和 substep 对应关系由时间同步规则计算。 + +输出文件: + +1. `fsi_report.csv`; +2. `ipc_report.csv`; +3. `verification_report.json`。 + +Python 检查: + +1. 检查 SPH 接收的边界速度; +2. 检查 ghost/boundary 数据位置; +3. 检查 step 与 substep 对应; +4. 检查数据不跨步误用; +5. 检查数据数量。 + +通过判据: + +1. SPH 接收到的边界速度与 FEM 规定运动一致; +2. ghost/boundary 数据不越界; +3. step、substep 数据对应正确; +4. 边界静止时速度为 0; +5. 运动边界不破坏 IPC 同步。 + +## 9.13 一维声阻抗 Riemann 界面 + +算例编号:`V070_RIEMANN_INTERFACE_1D` + +首次验收版本:0.7.x。 + +验证目标: + +1. 验证 Riemann FSI 主算法; +2. 验证界面压力; +3. 验证界面速度; +4. 验证声阻抗极限状态; +5. 验证非物理输入保护。 + +输入模型: + +1. SPH 侧和 FEM 侧各给定一维等效状态; +2. 指定密度、声速、压力和法向速度; +3. CCLite 计算界面压力和界面速度; +4. 子算例覆盖左右状态相同、高阻抗差、低阻抗差和反向速度。 + +参考值: + +1. Python `references` 按 04 号第 8 章声阻抗近似公式计算; +2. 左右状态相同时界面状态应等于原状态; +3. 高阻抗侧速度响应应小于低阻抗侧; +4. 非物理密度或声速应触发错误或安全降级。 + +输出文件: + +1. `fsi_report.csv`; +2. `force_balance.csv`; +3. `verification_report.json`。 + +Python 检查: + +1. 检查界面压力; +2. 检查界面速度; +3. 检查载荷方向; +4. 检查声阻抗极限情况; +5. 检查异常输入处理。 + +通过判据: + +1. Riemann 输出与参考计算一致; +2. 左右状态相同时不产生虚假扰动; +3. 高阻抗极限趋势正确; +4. 非物理输入被拒绝或安全处理; +5. 诊断记录界面状态。 + +## 9.14 异步子循环 + +算例编号:`V070_ASYNC_SUBCYCLING` + +首次验收版本:0.7.x。 + +验证目标: + +1. 验证显式-显式异步子循环; +2. 验证 macro step、substep 和 iteration id; +3. 验证数据交换时刻; +4. 验证 force hold 或 interpolation 策略; +5. 验证失败定位到具体 substep。 + +输入模型: + +1. SPHLite 使用较小时间步; +2. FEMLite 使用较大时间步; +3. CCLite 以 macro step 调度; +4. 一个 solver 在 macro step 内执行多个 substep; +5. 初始可使用 mock worker 控制各自时间步。 + +参考值: + +1. macro step 结束时两个 solver 时间应一致; +2. substep id 应连续; +3. force hold 或 interpolation 结果由 Python 根据策略计算; +4. 数据交换次数由步长比决定。 + +输出文件: + +1. `ipc_report.csv`; +2. `timestep_report.csv`; +3. `force_balance.csv`; +4. `verification_report.json`。 + +Python 检查: + +1. 检查 substep 数量; +2. 检查每个 worker 的时间; +3. 检查数据交换时刻; +4. 检查 force hold 或 interpolation 值; +5. 检查失败定位信息。 + +通过判据: + +1. macro step 结束时两个 solver 时间一致; +2. substep id 连续; +3. 数据不会跨步误用; +4. 失败时能定位到具体 substep; +5. 真实 worker 接入后仍保持相同调度语义。 + +## 9.15 稳定性套件 + +算例编号:`V080_STABILITY_SUITE` + +首次验收版本:0.8.x。 + +验证目标: + +1. 验证 force relaxation; +2. 验证接触历史补强; +3. 验证异常输入保护; +4. 验证长时间运行稳定性; +5. 验证 AoR v1 与 SoA v2 性能对比。 + +套件组成: + +| 子算例 | 验证点 | +| --- | --- | +| 大 penalty 刚度 | 接触稳定时间步和非有限值保护 | +| 小时间步 | 长时间步进和诊断输出体量 | +| 大速度冲击 | 最大穿透量、力峰值和 relaxation | +| 多接触对 | 搜索性能和 pair 管理 | +| 接触反复开启关闭 | persistence 和历史状态 | +| 摩擦滑移 | 摩擦历史变量稳定性 | +| tied release 后接触 | 状态转换和历史清理 | +| FSI 压力波 | pressure projection 和时间同步 | +| worker 延迟 | timeout、heartbeat、ack | +| 非有限值故障注入 | NaN/Inf 捕获和错误码 | + +输出文件: + +1. `run.log`; +2. `ipc_report.csv`; +3. `contact_report.csv`; +4. `force_balance.csv`; +5. `timestep_report.csv`; +6. `performance_report.csv`; +7. `verification_report.json`。 + +Python 检查: + +1. 检查非有限值; +2. 检查错误码; +3. 检查最大穿透量; +4. 检查能量和冲量趋势; +5. 检查长时间运行步数; +6. 检查 AoR v1 与 SoA v2 性能差异; +7. 检查 worker 延迟场景的超时处理。 + +通过判据: + +1. 程序不崩溃; +2. 非有限值被捕获; +3. 诊断能指出不稳定来源; +4. force relaxation 生效; +5. 接触历史不发生错误串扰; +6. SoA v2 优化不改变物理验收结果。 + +## 9.16 工程简化算例 + +算例编号:`V090_ENGINEERING_CASES` + +首次验收版本:0.9.x。 + +验证目标: + +1. 验证工程趋势; +2. 建立参数推荐范围; +3. 建立性能基线; +4. 验证长时间运行稳定性; +5. 为 0.10.x 发布候选提供工程证据。 + +工程简化算例从 0.9.x 起作为硬验收,不提前作为 0.6.x 或 0.7.x 的基础正确性验收。 + +建议方向: + +1. 水下爆炸冲击简化模型; +2. 粒子流冲击薄板; +3. SPH 颗粒堆积与 FEM 壁面; +4. 流固压力作用下的弹性板; +5. 局部破坏或 release 后接触。 + +水下爆炸 FSI 在本路线中放入 0.9.x 工程简化算例。0.6.x 只验证 pressure projection、边界速度和 boundary/ghost 数据;0.7.x 只验证 Riemann FSI 与时间耦合的可拆解小问题。 + +参考值: + +1. 工程趋势可来自独立脚本、简化理论或既有试算结果; +2. 若没有严格解析解,应明确标记为趋势验证; +3. 参数推荐范围必须来自参数扫描结果; +4. 关键诊断量必须可复现。 + +输出文件: + +1. `run.log`; +2. `contact_report.csv`; +3. `fsi_report.csv`; +4. `force_balance.csv`; +5. `timestep_report.csv`; +6. `performance_report.csv`; +7. `verification_report.json`。 + +Python 检查: + +1. 检查关键趋势量; +2. 检查参数扫描结果; +3. 检查长时间运行稳定性; +4. 检查性能指标; +5. 检查回归基线。 + +通过判据: + +1. 结果趋势符合工程认知; +2. 关键诊断量稳定; +3. 参数推荐范围可复用; +4. 长时间运行无资源泄漏; +5. 回归基线稳定; +6. 算例说明足够让用户复现。 + +## 9.17 0.10.x 全量回归算例 + +算例编号:`V100_RELEASE_REGRESSION` + +首次验收版本:0.10.x。 + +验证目标: + +1. 冻结 0.x 开发线接口; +2. 冻结文档与测试基线; +3. 确认 0.1.x 到 0.9.x 的已验收能力未退化; +4. 在干净环境中重建并运行全量测试; +5. 形成工程发布候选证据。 + +输入模型: + +1. 0.1.x 到 0.9.x 所有已验收算例; +2. AoR v1 和 SoA v2 相关接口测试; +3. 真实 SPHLite/FEMLite worker 的代表算例; +4. 版本兼容和错误路径算例; +5. 文档一致性检查。 + +参考值: + +1. 已冻结回归基线; +2. 每个算例自己的解析值或参考解; +3. 接口布局和枚举来自 05 号文档; +4. 算法公式和判据来自 04 号文档。 + +输出文件: + +1. `release_test_report.json`; +2. `release_test_summary.txt`; +3. 全量 CSV 输出; +4. 性能基线; +5. 文档一致性检查结果。 + +Python 检查: + +1. 汇总全量测试结果; +2. 检查回归差异; +3. 检查接口兼容; +4. 检查文档章节追踪; +5. 生成发布候选测试摘要。 + +通过判据: + +1. 全量单元测试通过; +2. 全量接口测试通过; +3. 全量集成测试通过; +4. 全量验证算例通过; +5. 全量回归测试通过; +6. 性能指标不低于已批准基线; +7. 文档、接口和测试矩阵一致。 + +# 10. 验收判据 + +## 10.1 通用验收判据 + +所有版本通用验收判据: + +1. 文档与实现一致; +2. `.inp` 输入可复现; +3. 测试用例可一键或按说明运行; +4. 自动检查报告给出通过或失败; +5. 失败时错误码和日志可定位; +6. 已通过测试进入回归集合; +7. 不引入未说明的接口破坏。 + +## 10.2 接口验收判据 + +接口验收采用严格判定: + +1. magic、version、layout、role 完全一致; +2. record size 完全一致; +3. 枚举值完全一致; +4. 字节序和对齐符合 05 号文档; +5. command seq 与 ack seq 正确; +6. worker state 合法; +7. timeout 行为可复现; +8. 错误码可追踪。 + +接口测试失败时,不应继续执行物理验证算例。 + +## 10.3 几何验收判据 + +几何验收关注: + +1. 最近点; +2. 接触法向; +3. 穿透量; +4. 候选对; +5. edge fallback; +6. 壳厚度; +7. 退化处理。 + +几何错误会直接影响接触力方向和稳定性,因此几何验收是 0.2.x 之后所有接触版本的前置条件。 + +## 10.4 接触验收判据 + +接触验收关注: + +1. 接触开启和关闭; +2. 法向力方向; +3. 阻尼力方向; +4. 摩擦力上限; +5. 作用反作用; +6. 力矩一致性; +7. 接触功; +8. 最大穿透量; +9. 非有限值保护。 + +接触力可以根据不同算法参数改变幅值,但不得违反方向、守恒和约束激活逻辑。 + +## 10.5 FSI 验收判据 + +FSI 验收关注: + +1. 压力积分; +2. 速度边界; +3. ghost/boundary 数据; +4. Riemann 界面压力; +5. Riemann 界面速度; +6. 载荷方向; +7. 时间同步; +8. 稳定性。 + +FSI 算例应优先使用小规模、可解释模型,避免过早使用复杂工程场景作为唯一验收依据。 + +## 10.6 性能验收判据 + +性能验收分阶段执行。 + +0.1.x 只记录 IPC 和启动耗时,不设置严格性能门槛。 + +0.2.x 到 0.7.x 记录每步耗时、搜索耗时、接触对数量和数据传输耗时。 + +0.8.x 起必须比较 AoR v1 与 SoA v2 的性能差异。 + +0.9.x 起建立工程算例性能目标。 + +性能测试不能以牺牲接口兼容性和数值正确性为代价。 + +# 11. 版本测试与验证路线 + +## 11.1 0.1.x 主控与通信闭环 + +目标: + +1. CCLite 独立主控; +2. SPHLite worker/service 模式; +3. FEMLite worker/service 模式; +4. Windows shared memory; +5. named event; +6. command block; +7. AoR v1 data block; +8. 空耦合循环; +9. CSV 诊断。 + +必须通过: + +1. `.inp` check 测试; +2. worker 启动测试; +3. command block 测试; +4. event 同步测试; +5. data block header 测试; +6. mock workers 空耦合集成测试; +7. timeout 和错误码测试; +8. 资源释放测试。 + +0.1.x 不要求真实接触力验收。 + +## 11.2 0.2.x 基础 SPH-FEM Penalty 接触 + +目标: + +1. SPH 粒子到 FEM 三角形 facet; +2. 基础宽相搜索; +3. 点到三角形最近点; +4. 法向 penalty 接触; +5. FEM 节点力分配; +6. force balance 诊断。 + +必须通过: + +1. 几何基础单元测试; +2. 搜索算法单元测试; +3. 单粒子撞刚性面; +4. 多粒子压平面; +5. 力平衡测试; +6. CCLite + 至少一个真实 worker 集成测试。 + +## 11.3 0.3.x 壳、边缘与四边形接触 + +目标: + +1. shell thickness; +2. edge fallback; +3. quad facet; +4. 接触 persistence 初步; +5. 接触诊断增强。 + +必须通过: + +1. 点到四边形几何测试; +2. 边缘接触测试; +3. 壳厚度测试; +4. quad 与 triangle 组合一致性测试; +5. 接触状态连续性测试。 + +## 11.4 0.4.x 阻尼、摩擦与稳定时间步 + +目标: + +1. 法向阻尼; +2. Coulomb 摩擦; +3. penalty 参数估计; +4. 接触稳定时间步; +5. 接触能量诊断。 + +必须通过: + +1. 阻尼单元测试; +2. 摩擦滑移验证; +3. 能量耗散检查; +4. penalty 参数范围测试; +5. 稳定时间步诊断测试。 + +## 11.5 0.5.x Tied Coupling 与 Release + +目标: + +1. tied coupling; +2. release; +3. tie-to-contact; +4. 状态转换诊断; +5. 能量记录。 + +必须通过: + +1. tie 单元测试; +2. release 阈值测试; +3. tied/release 集成算例; +4. release 后接触验证; +5. 状态转换回归测试。 + +## 11.6 0.6.x Pressure Projection 与 Boundary/Ghost Particle + +目标: + +1. SPH 压力到 FEM 面载荷; +2. FEM 运动边界到 SPH; +3. boundary particle; +4. ghost particle; +5. FSI 基础诊断。 + +必须通过: + +1. 均匀压力作用于 FEM 面; +2. 运动边界传递测试; +3. boundary/ghost 数据测试; +4. FSI 载荷方向测试; +5. 单位一致性测试。 + +## 11.7 0.7.x Riemann FSI 与时间耦合 + +目标: + +1. Riemann FSI 主算法; +2. 异步子循环; +3. 显式-隐式弱耦合框架; +4. 强耦合迭代框架; +5. 算法主体完成。 + +必须通过: + +1. 一维声阻抗 Riemann 界面; +2. Riemann 极限状态测试; +3. 异步子循环测试; +4. 弱耦合流程测试; +5. 强耦合迭代状态机测试; +6. 算法章节到测试项的覆盖审查。 + +0.7.x 完成后,04 号文档中的主要算法应均有实现入口和基本验证。 + +## 11.8 0.8.x 稳定化、性能优化与 SoA v2 + +目标: + +1. force relaxation; +2. 接触历史补强; +3. 能量修正; +4. 异常处理补强; +5. AoR v1 与 SoA v2 性能对比; +6. 长时间运行稳定性。 + +必须通过: + +1. 稳定性套件; +2. 非有限值故障注入; +3. worker 延迟测试; +4. 长时间运行测试; +5. AoR v1 / SoA v2 对比测试; +6. 回归测试全量通过。 + +## 11.9 0.9.x 工程算例与参数推荐 + +目标: + +1. 工程简化算例集合; +2. 参数推荐范围; +3. 性能目标; +4. 工程验收矩阵; +5. 文档和测试闭环。 + +必须通过: + +1. 工程简化算例; +2. 参数敏感性测试; +3. 性能基线测试; +4. 长时间稳定性测试; +5. 回归测试全量通过; +6. 用户可复现实验说明。 + +## 11.10 0.10.x 接口冻结与工程发布候选 + +目标: + +1. 接口冻结; +2. 文档冻结; +3. 回归体系冻结; +4. 版本兼容策略冻结; +5. 工程发布候选。 + +必须通过: + +1. 全量单元测试; +2. 全量接口测试; +3. 全量集成测试; +4. 全量验证算例; +5. 全量回归测试; +6. 性能测试; +7. 文档一致性审查; +8. 干净环境重建测试。 + +0.10.x 不表示进入 1.0.x,而是 0.x 开发线的第十个工程版本阶段。 + +# 12. 追踪矩阵 + +## 12.1 数学模型到测试项 + +| 04 号章节 | 测试覆盖 | +| --- | --- | +| 第 3 章 界面数据抽象 | data block、payload、单位一致性测试 | +| 第 4 章 几何搜索与接触检测 | 几何单元测试、几何验证算例、边缘和壳测试 | +| 第 5 章 接触力与摩擦模型 | 接触力单元测试、单粒子撞面、多粒子压面、摩擦滑移 | +| 第 6 章 Tied Coupling 与 Release | tied/release 单元测试和验证算例 | +| 第 7 章 FSI 压力、速度与边界粒子 | 均匀压力、运动边界、boundary/ghost 测试 | +| 第 8 章 Riemann FSI | 一维声阻抗 Riemann 界面测试 | +| 第 9 章 时间耦合数学框架 | 显式同步、异步子循环、弱耦合、强耦合状态机测试 | +| 第 10 章 稳定性控制 | 稳定性套件、force relaxation、非有限值测试 | +| 第 11 章 守恒与诊断量 | force balance、moment balance、contact work、impulse 测试 | + +## 12.2 接口文档到测试项 + +| 05 号章节 | 测试覆盖 | +| --- | --- | +| Worker/Service 模式接口 | worker 启动、退出、心跳、异常测试 | +| `.inp` 关键词接口 | `.inp` 解析和 check 模式测试 | +| 控制 IPC 接口 | named event 测试 | +| Command Shared Block | command block 字段、版本、seq/ack 测试 | +| Data Block Header | header、role、state、capacity、checksum 测试 | +| AoR v1 Payload | 各 record 布局和字段测试 | +| 命令与状态枚举 | command id、worker state、load mode 测试 | +| 错误码与异常处理 | timeout、非法 header、worker 崩溃、NaN 测试 | +| 版本兼容策略 | ABI、layout、AoR/SoA 兼容测试 | + +## 12.3 版本到验收项 + +| 版本 | 验收重点 | +| --- | --- | +| 0.1.x | IPC、worker、mock solver、空耦合 | +| 0.2.x | 基础 penalty contact | +| 0.3.x | 壳、边缘、四边形、接触状态 | +| 0.4.x | 阻尼、摩擦、稳定时间步 | +| 0.5.x | tied、release、tie-to-contact | +| 0.6.x | pressure projection、boundary/ghost | +| 0.7.x | Riemann FSI、子循环、弱/强耦合框架 | +| 0.8.x | 稳定化、性能、SoA v2、异常处理 | +| 0.9.x | 工程算例、参数推荐、性能目标 | +| 0.10.x | 文档冻结、接口冻结、全量回归、发布候选 | + +# 13. 自动化与执行策略 + +## 13.1 测试执行层级 + +建议执行层级: + +1. `quick`:单元测试和基础接口测试; +2. `standard`:quick + mock 集成 + 小验证算例; +3. `full`:standard + 真实 worker + 回归测试; +4. `release`:full + 性能测试 + 工程算例 + 文档一致性检查。 + +日常开发至少运行 quick。 + +合并关键接口或算法变更前应运行 standard。 + +版本验收前应运行 release。 + +## 13.2 自动检查报告 + +自动检查报告至少包含: + +1. 测试名称; +2. 测试版本; +3. 运行时间; +4. 平台; +5. 编译器; +6. CCLite commit; +7. SPHLite commit 或版本; +8. FEMLite commit 或版本; +9. 通过数量; +10. 失败数量; +11. 跳过数量; +12. 失败原因摘要; +13. 输出路径。 + +## 13.3 测试命名 + +建议测试命名使用: + +```text +test___ +``` + +示例: + +```text +test_unit_closest_point_triangle_inside +test_interface_command_block_seq_ack +test_integration_mock_empty_coupling_100_steps +test_verification_single_particle_wall_no_damping +``` + +## 13.4 失败分类 + +测试失败分为: + +| 类型 | 说明 | +| --- | --- | +| INPUT | 输入文件或测试配置错误 | +| BUILD | 编译或链接错误 | +| IPC | shared memory、event、command block 错误 | +| INTERFACE | payload、layout、版本兼容错误 | +| ALGORITHM | 几何、接触、耦合算法错误 | +| NUMERICAL | 数值误差或稳定性错误 | +| WORKER | SPHLite/FEMLite worker 行为错误 | +| SYSTEM | 平台资源或系统调用错误 | +| TEST | 测试脚本或基线错误 | + +失败分类应写入测试报告,便于定位责任边界。 + +# 14. 风险与对策 + +## 14.1 Mock 测试通过但真实 worker 失败 + +风险: + +mock solver 可能过于理想,不能暴露真实 worker 的数据生命周期、时间步和异常行为。 + +对策: + +1. 0.2.x 起引入单真实 worker 集成测试; +2. 真实 worker 输出必须经过同一套接口检查; +3. mock solver 增加故障注入; +4. 用真实 worker 数据回放构造回归测试。 + +## 14.2 接口变化破坏回归 + +风险: + +共享内存 layout 一旦变化,旧测试和旧 worker 可能无法运行。 + +对策: + +1. 所有 layout 变化必须更新 05 号文档; +2. layout id 必须递增或明确兼容; +3. 版本兼容测试必须先于集成测试; +4. 0.10.x 前冻结接口。 + +## 14.3 数值结果依赖参数 + +风险: + +接触刚度、阻尼、时间步和摩擦参数会显著影响结果。 + +对策: + +1. 验证算例固定参数; +2. 参数写入输入文件; +3. 输出参数摘要; +4. 0.9.x 建立参数推荐范围; +5. 回归测试允许有记录的基线更新。 + +## 14.4 工程算例过早进入硬验收 + +风险: + +复杂工程算例问题来源多,难以判断失败属于接口、算法还是模型设置。 + +对策: + +1. 0.1.x 到 0.7.x 以小算例为主; +2. 0.9.x 再建立工程算例硬验收; +3. 工程算例必须拆分出可验证的子问题; +4. 不用复杂工程算例替代基础验证。 + +## 14.5 性能优化影响正确性 + +风险: + +SoA v2、并行搜索或缓存优化可能改变接触对顺序和浮点累加结果。 + +对策: + +1. 0.8.x 才引入 SoA v2 性能优化; +2. 保留 AoR v1 作为对照; +3. 对排序无关结果使用合力、力矩和误差判据; +4. 对顺序敏感诊断明确排序规则。 + +# 15. 第一阶段冻结项 + +0.1.x 第一阶段测试计划冻结以下内容: + +1. 测试分层采用单元测试、接口测试、集成测试、验证算例四层主结构; +2. 0.1.x 以 mock solver、IPC、worker、空耦合为主要验收目标; +3. 0.2.x 以单粒子和小规模 SPH-FEM penalty contact 为主要接触验收目标; +4. 允许使用 Python checker 检查 CSV 和数值结果; +5. 验收计划按 0.1.x 到 0.10.x 组织; +6. 第一阶段平台为 Windows/gfortran/本机共享内存; +7. Linux/MPI 只作为预留测试方向; +8. 接口测试必须严格追踪 05 号文档; +9. 算法验证必须严格追踪 04 号文档; +10. 0.2.x 第一个真实物理验收算例定为单粒子撞刚性面; +11. 核心物理算例应先用 mock 数据验证 CCLite 算法,再逐步接入真实 SPHLite/FEMLite worker; +12. 工程简化算例从 0.9.x 起作为硬验收; +13. 核心验证算例必须有解析值、独立脚本参考值或可手算参考值; +14. 水下爆炸 FSI 暂定为 0.9.x 工程简化算例; +15. 允许借助 `.\Python\` 实现算例生成、参考解、runner 和 checker; +16. 0.10.x 是 0.x 开发线的工程发布候选阶段,不自动跳转为 1.0.x。 + +# 16. 待细化事项 + +以下事项应在代码和测试框架建立后进一步细化: + +1. 具体测试目录是否与最终源码目录合并; +2. gfortran 单元测试框架选择; +3. Python checker 的最终报告 schema; +4. CSV 字段最终名称; +5. 每个验证算例的默认数值参数; +6. 每个版本的测试运行时间目标; +7. 工程算例数据是否纳入仓库; +8. 大文件测试数据的管理方式; +9. 0.8.x SoA v2 的性能基准; +10. 0.9.x 工程验收矩阵。 + +本文档后续应随 03、04、05 号文档和代码实现同步维护。 diff --git a/docs/v1.x_development_plan.md b/docs/v1.x_development_plan.md new file mode 100644 index 0000000..50cd856 --- /dev/null +++ b/docs/v1.x_development_plan.md @@ -0,0 +1,839 @@ +# CCLite 0.1.x 开发计划 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**文件名**:`v1.x_development_plan.md` +**适用版本**:CCLite 0.1.x +**文档依据**:`01_requirements.md` 到 `06_test_and_verification_plan.md` +**实现基线**:Fortran95 算法核心 + Fortran2018 IPC 包装 + C/C++ Windows IPC 薄层 +**第一阶段平台**:Windows / gfortran / 本机共享内存 +**输入格式**:Abaqus 风格 `.inp` +**编码要求**:中文,UTF-8 without BOM + +# 1. 文档目的 + +本文档定义 CCLite 0.1.x 的开发目标、工作分解、版本节奏、交付物、测试验收和风险控制。 + +0.1.x 的核心目标不是完成真实 SPH-FEM 接触算法,而是建立可靠的工程骨架: + +1. CCLite 独立主控程序; +2. SPHLite 和 FEMLite 的 CCLite worker/service 运行模式; +3. Windows/gfortran/本机共享内存通信闭环; +4. named event + command shared block 控制同步; +5. AoR v1 data block 基础布局; +6. `.inp` 主控输入; +7. mock worker 空耦合测试; +8. CSV 诊断和 Python checker; +9. 可复现的 0.1.x 验收流程。 + +0.1.x 完成后,应能证明 CCLite 的三进程主控、IPC、worker 调度、数据块版本化和测试体系已经可用,为 0.2.x 的基础 penalty contact 接触算法开发提供稳定地基。 + +# 2. 版本边界 + +## 2.1 0.1.x 必须完成 + +0.1.x 必须完成以下能力: + +1. `cclite.exe` 可作为独立主控程序启动; +2. 支持 `check`、`dry-run` 和最小 `run` 模式; +3. 支持 CCLite `.inp` 关键词子集; +4. 可创建和销毁 Windows shared memory; +5. 可创建和销毁 Windows manual-reset named event; +6. 可读写 command shared block; +7. 可读写 data block header; +8. 支持 AoR v1 基础 payload 布局; +9. 支持 `mock_sph_worker` 和 `mock_fem_worker`; +10. 支持 SPHLite/FEMLite worker/service 最小命令序列; +11. 可执行空耦合多步同步推进; +12. 输出 `run.log`、`ipc_report.csv`、`force_balance.csv` 和验证报告; +13. 通过 `V010_EMPTY_COUPLING` 验证算例; +14. Linux/MPI 只保留配置、枚举和错误提示。 + +## 2.2 0.1.x 不完成 + +0.1.x 不完成以下能力: + +1. 真实 SPH-FEM 接触力计算; +2. 单粒子撞刚性面物理验收; +3. 多粒子接触; +4. 壳厚度、边缘 fallback、四边形高级接触验收; +5. 摩擦、tied/release、FSI、Riemann FSI; +6. 异步子循环; +7. SoA v2 data block; +8. Linux/MPI 生产实现; +9. 工程算例验收; +10. 性能优化硬指标。 + +0.1.x 可以保留接触、FSI、SoA v2、Linux/MPI 的接口枚举和预留字段,但不得把这些预留项写成已经可用的交付能力。 + +## 2.3 0.1.x 与 0.2.x 的分界 + +0.1.x 结束标准是通信和空耦合闭环通过。 + +0.2.x 开始标准是 0.1.x 的 IPC、worker、payload、诊断和 mock 测试均稳定,随后才进入基础 penalty contact: + +1. `V020_GEOMETRY_PRIMITIVES`; +2. `V020_SINGLE_PARTICLE_WALL`; +3. `V020_MULTI_PARTICLE_PLANE`。 + +# 3. 总体开发策略 + +0.1.x 采用“先 mock,后真实;先接口,后物理;先 check/dry-run,后 run”的策略。 + +开发顺序为: + +1. 建立可编译工程骨架; +2. 建立 CCLite 主控入口和 `.inp` case model; +3. 建立 Windows IPC 薄层; +4. 建立 Fortran2018 IPC wrapper; +5. 建立 command block 和 data block header; +6. 建立 mock worker; +7. 建立 controller 状态机; +8. 跑通空耦合; +9. 增加 CSV 诊断; +10. 增加 Python checker; +11. 接入 SPHLite/FEMLite worker/service 最小模式; +12. 固化 0.1.x 验收测试。 + +每一步都应有可运行的小闭环,不等待所有模块完成后再集成。 + +# 4. 推荐 patch 版本节奏 + +0.1.x 内部 patch 版本可按以下节奏推进。实际开发时允许合并相邻 patch,但不得跳过验收目标。 + +| 版本 | 主题 | 主要交付 | +| --- | --- | --- | +| 0.1.0 | 工程骨架 | 目录结构、构建脚本、`cclite.exe` 空入口、版本输出 | +| 0.1.1 | `.inp` 与 case model | CCLite 关键词解析、check 模式、输入错误码 | +| 0.1.2 | IPC 基础 | Windows shared memory、named event、Fortran wrapper | +| 0.1.3 | command block 与 worker 协议 | command block、seq/ack、worker state、mock worker 启动 | +| 0.1.4 | data block 与 AoR v1 | data block header、block role、基础 payload、空载荷写回 | +| 0.1.5 | Controller 空耦合 | 三进程调度、100 step dry-run、正常退出和资源释放 | +| 0.1.6 | 诊断与 Python checker | CSV 输出、`V010_EMPTY_COUPLING` 自动检查 | +| 0.1.7 | 真实 worker 最小接入 | SPHLite/FEMLite worker/service handshake,真实 worker 可空耦合 | +| 0.1.8 | 0.1.x 发布候选 | 全量 0.1.x 回归、文档一致性、干净环境重建 | + +若 SPHLite/FEMLite 当前包短期内不便修改,0.1.7 可先定义为 worker/service 接口样例和接入指南;但 0.1.x 发布候选前至少应有可执行的 mock worker 完整闭环。 + +# 5. 交付物 + +## 5.1 程序交付物 + +0.1.x 应交付以下可执行程序或构建目标: + +1. `cclite.exe`; +2. `mock_sph_worker.exe`; +3. `mock_fem_worker.exe`; +4. SPHLite worker/service 最小入口,若 SPHLite 源码可修改; +5. FEMLite worker/service 最小入口,若 FEMLite 源码可修改。 + +## 5.2 源码交付物 + +0.1.x 源码至少包含: + +1. App 层; +2. `.inp` parser; +3. case/config 数据结构; +4. controller 状态机; +5. process launcher; +6. Windows IPC C/C++ 薄层; +7. Fortran2018 IPC wrapper; +8. command block pack/unpack; +9. data block header pack/unpack; +10. AoR v1 payload 基础类型; +11. diagnostics writer; +12. mock worker; +13. Python checker。 + +## 5.3 文档交付物 + +0.1.x 结束时应更新: + +1. `README.md`; +2. `docs/01_requirements.md`,如有需求变更; +3. `docs/02_architectural_design_specification.md`,如有架构变更; +4. `docs/03_detailed_design.md`,如有实现变更; +5. `docs/05_interface_control_document.md`,如有接口字段变更; +6. `docs/06_test_and_verification_plan.md`,如有测试变更; +7. 本开发计划。 + +04 号数学模型文档在 0.1.x 不应大改,因为 0.1.x 不实现真实接触算法;若发现后续算法边界影响接口,应记录到待讨论项。 + +## 5.4 测试交付物 + +0.1.x 测试交付物包括: + +1. `.inp` parser 单元测试; +2. command block 单元测试; +3. data block header 单元测试; +4. named event 接口测试; +5. shared memory 接口测试; +6. worker 启动和退出测试; +7. mock workers 空耦合集成测试; +8. `V010_EMPTY_COUPLING` 验证算例; +9. Python checker; +10. 测试报告样例。 + +# 6. 推荐目录结构 + +0.1.x 可按以下目录组织。若现有仓库已有结构,应优先兼容现有结构。 + +```text +src/ + app/ + case/ + controller/ + ipc/ + process/ + interface_data/ + diagnostics/ + mock_workers/ + +include/ + cclite_ipc.h + +tests/ + unit/ + interface/ + integration/ + verification/ + data/ + baselines/ + +cases/ + v0_1_ipc_empty_coupling/ + +Python/ + checkers/ + references/ + casegen/ + runners/ +``` + +目录职责: + +| 目录 | 0.1.x 职责 | +| --- | --- | +| `src/app/` | 主程序入口、命令行、版本输出 | +| `src/case/` | `.inp` 解析、case model、参数校验 | +| `src/controller/` | 主控状态机、step 调度、worker 命令 | +| `src/ipc/` | Windows IPC 薄层和 Fortran wrapper | +| `src/process/` | worker 启动、监控、停止 | +| `src/interface_data/` | block header、AoR v1 record、buffer view | +| `src/diagnostics/` | log 和 CSV 输出 | +| `src/mock_workers/` | mock SPH/FEM worker | +| `Python/checkers/` | CSV 与验证报告检查 | +| `cases/v0_1_ipc_empty_coupling/` | 0.1.x 验收算例 | + +# 7. 工作包分解 + +## 7.1 WP01:工程骨架与构建 + +目标: + +1. 建立 Windows/gfortran 可编译工程; +2. 形成 CCLite 主程序入口; +3. 形成 mock worker 构建目标; +4. 输出版本号、构建信息和平台信息。 + +任务: + +1. 确定构建方式; +2. 建立源码目录; +3. 建立公共精度和错误码模块; +4. 建立 `cclite --version`; +5. 建立 `cclite --help`; +6. 建立最小日志输出; +7. 建立 CI 或本地测试脚本预留。 + +完成标准: + +1. 干净仓库可构建; +2. `cclite --version` 输出版本; +3. mock worker 可构建或至少有独立入口; +4. 构建产物不依赖开发者个人绝对路径。 + +## 7.2 WP02:`.inp` 解析与 case model + +目标: + +支持 0.1.x 所需 CCLite `.inp` 关键词子集。 + +0.1.x 必须识别: + +1. `*CCLITE CONTROL`; +2. `*CCLITE SOLVER`; +3. `*CCLITE IPC`; +4. `*CCLITE TIME`; +5. `*CCLITE INTERFACE`; +6. `*CCLITE OUTPUT`。 + +可识别但不启用真实物理计算: + +1. `*CCLITE SURFACE INTERACTION`; +2. `*CCLITE CONTACT PAIR`。 + +任务: + +1. 实现关键词行解析; +2. 实现参数键值解析; +3. 实现大小写兼容; +4. 实现注释和空行处理; +5. 实现路径参数解析; +6. 实现必需字段校验; +7. 实现 `IPC TYPE=WINDOWS_SHMEM` 限制; +8. 实现 Linux/MPI 配置项的明确拒绝或预留提示; +9. 实现 check 模式输出。 + +完成标准: + +1. 合法 `.inp` 生成 case model; +2. 非法 `.inp` 给出行号、关键词和错误码; +3. `CONTACT=YES` 等真实接触能力在 0.1.x 中不误报为已支持; +4. check 模式不创建真实 IPC 资源。 + +## 7.3 WP03:Windows IPC 薄层 + +目标: + +完成 Windows shared memory 和 named event 的最小可用封装。 + +任务: + +1. 封装 shared memory create/open/map/unmap/close; +2. 封装 named event create/open/wait/signal/reset/close; +3. 支持 manual-reset named event; +4. 统一错误码; +5. 隐藏 Windows API 细节; +6. 提供 Fortran2018 `iso_c_binding` wrapper; +7. 提供资源释放函数; +8. 提供 timeout 支持。 + +完成标准: + +1. Fortran 侧可创建和映射共享内存; +2. Fortran 侧可等待和触发 named event; +3. CCLite 负责 reset `COMMAND_EVENT` 和 `DONE_EVENT`; +4. worker 只 wait/signal,不 reset; +5. 资源释放后可重复运行测试。 + +## 7.4 WP04:Command Shared Block + +目标: + +实现 05 号接口文档定义的 command shared block。 + +0.1.x 需要支持字段: + +1. `magic`; +2. `abi_version`; +3. `layout_id`; +4. `solver_id`; +5. `command_id`; +6. `command_seq`; +7. `ack_seq`; +8. `step_id`; +9. `substep_id`,0.1.x 写 0; +10. `iteration_id`,0.1.x 写 0; +11. `command_flags`; +12. `heartbeat_seq`; +13. `worker_state`; +14. `int_param[16]`; +15. `real_param[16]`; +16. `macro_dt`; +17. `error_code`。 + +任务: + +1. 定义 command block 逻辑类型; +2. 定义二进制布局; +3. 实现 pack/unpack 或 `bind(C)` 镜像类型; +4. 实现 magic 和 version 检查; +5. 实现 seq/ack 配对; +6. 实现 worker state 转换; +7. 实现 timeout 错误处理; +8. 实现 command block 单元测试。 + +完成标准: + +1. 字节数、字段顺序和对齐符合 05 号文档; +2. seq/ack 不错配; +3. worker state 非法转换被拒绝; +4. 不兼容 layout 在初始化阶段停止。 + +## 7.5 WP05:Data Block Header 与 AoR v1 + +目标: + +实现基础 data block header 和 AoR v1 record 布局。 + +0.1.x 必须支持 block role: + +1. `SPH_TO_CCL_PARTICLE`; +2. `FEM_TO_CCL_FACET`; +3. `CCL_DIAGNOSTIC`; +4. `CCL_COMMAND_SPH`; +5. `CCL_COMMAND_FEM`。 + +0.1.x 可创建但保持空内容: + +1. `CCL_TO_SPH_FORCE`; +2. `CCL_TO_FEM_LOAD`; +3. `SPH_TO_CCL_FACET`。 + +任务: + +1. 定义 data block header; +2. 定义 block role 枚举; +3. 定义 buffer state; +4. 定义 record size 和 capacity 检查; +5. 定义 AoR v1 粒子 record; +6. 定义 AoR v1 facet record; +7. 定义空载荷 record; +8. 实现 header 校验; +9. 实现空 payload 处理; +10. 实现最大 capacity 边界测试。 + +完成标准: + +1. CCLite 可拒绝非法 header; +2. record count 不超过 capacity; +3. record size 与 layout id 匹配; +4. 空 payload 合法; +5. 0.1.x 空耦合不读取未初始化字段。 + +## 7.6 WP06:Mock Worker + +目标: + +提供稳定可控的 mock SPH worker 和 mock FEM worker,用于 0.1.x 的主要集成测试。 + +任务: + +1. mock worker 支持 worker/service 启动参数; +2. 支持打开 CCLite 创建的 shared memory; +3. 支持打开 named event; +4. 支持命令:`INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; +5. 支持 heartbeat; +6. 支持 ack; +7. 支持写入 0 个 record; +8. 支持写入少量固定 record; +9. 支持故障注入预留; +10. 支持正常退出和异常退出测试。 + +完成标准: + +1. mock worker 可被 CCLite 启动; +2. mock worker 可进入 `READY`; +3. mock worker 可完成 100 step 空耦合; +4. mock worker 可响应 `STOP`; +5. worker 崩溃或超时时 CCLite 可给出错误码。 + +## 7.7 WP07:SPHLite/FEMLite Worker 最小接入 + +目标: + +在不破坏 SPHLite/FEMLite 独立主控程序身份的前提下,增加 CCLite worker/service 模式的最小入口。 + +任务: + +1. 定义 worker 启动参数; +2. 保持 SPHLite/FEMLite 原独立运行入口; +3. 增加 CCLite worker/service 分支; +4. worker 模式只通过 05 号外部接口和 CCLite 通信; +5. 0.1.x 支持最小命令序列; +6. 0.1.x 可导出空接口数据或少量固定接口数据; +7. 0.1.x 可接收空载荷; +8. 不要求真实求解推进结果参与物理验收。 + +完成标准: + +1. SPHLite/FEMLite 仍可独立运行; +2. worker 模式可启动并进入 `READY`; +3. worker 模式可响应 `STOP`; +4. worker 模式不直接依赖 CCLite 内部 Fortran API; +5. 若真实 worker 暂不能完成,mock worker 必须完整通过验收,并记录真实 worker 接入缺口。 + +## 7.8 WP08:Controller 状态机 + +目标: + +实现 CCLite 三进程主控流程。 + +0.1.x controller 状态包括: + +1. parse input; +2. create IPC; +3. launch workers; +4. wait workers ready; +5. send init/read/build/export; +6. step loop; +7. read interface data; +8. write empty loads; +9. collect diagnostics; +10. send stop; +11. release resources。 + +任务: + +1. 实现 `check` 流程; +2. 实现 `dry-run` 流程; +3. 实现最小 `run` 流程; +4. 实现 command dispatch; +5. 实现 timeout; +6. 实现 worker exit 监控; +7. 实现异常清理; +8. 实现 step id 单调递增; +9. 0.1.x 中 `substep_id=0`; +10. 0.1.x 中 `iteration_id=0`。 + +完成标准: + +1. 两个 mock worker 可同步推进; +2. 每步 seq/ack 匹配; +3. 每步 step id 正确; +4. timeout 不造成永久等待; +5. 所有 IPC 资源最终释放。 + +## 7.9 WP09:诊断输出 + +目标: + +提供 0.1.x 验收所需的日志和 CSV。 + +0.1.x 输出: + +1. `run.log`; +2. `ipc_report.csv`; +3. `force_balance.csv`; +4. `verification_report.json`,由 Python checker 生成。 + +`ipc_report.csv` 建议字段: + +1. `step_id`; +2. `solver_id`; +3. `command_id`; +4. `command_seq`; +5. `ack_seq`; +6. `worker_state`; +7. `heartbeat_seq`; +8. `elapsed_ms`; +9. `error_code`。 + +`force_balance.csv` 在 0.1.x 中可输出: + +1. `step_id`; +2. `sum_force_sph_x`; +3. `sum_force_sph_y`; +4. `sum_force_sph_z`; +5. `sum_force_fem_x`; +6. `sum_force_fem_y`; +7. `sum_force_fem_z`; +8. `force_balance_error`。 + +0.1.x 空耦合中所有力应为 0。 + +完成标准: + +1. CSV 表头稳定; +2. 每步都有记录; +3. 异常路径写错误码; +4. Python checker 可读取并判定通过或失败。 + +## 7.10 WP10:Python Checker + +目标: + +使用 `.\Python\` 支持 0.1.x 自动验收。 + +任务: + +1. 建立 `Python/checkers/`; +2. 建立 CSV 读取工具; +3. 建立 `V010_EMPTY_COUPLING` checker; +4. 检查 seq/ack; +5. 检查 worker state; +6. 检查 timeout; +7. 检查空载荷; +8. 生成 `verification_report.json`; +9. 返回明确退出码。 + +完成标准: + +1. checker 可在本机直接运行; +2. 失败报告指出字段和步号; +3. 报告包含 case id、status、metrics 和 failed checks; +4. Python 不参与 CCLite 核心算法实现。 + +# 8. `.inp` 最小样例 + +0.1.x 验收算例建议使用以下风格输入。具体字段名以后以 05 号接口文档和代码实现为准。 + +```text +*CCLITE CONTROL, NAME=V010_EMPTY_COUPLING, MODE=DRY_RUN +VERSION=0.1 + +*CCLITE SOLVER, ID=SPH, KIND=SPHLITE +EXECUTABLE=mock_sph_worker.exe +INPUT=mock_sph.inp + +*CCLITE SOLVER, ID=FEM, KIND=FEMLITE +EXECUTABLE=mock_fem_worker.exe +INPUT=mock_fem.inp + +*CCLITE IPC, TYPE=WINDOWS_SHMEM +NAME_PREFIX=CCLITE_V010 +BUFFER=DOUBLE +TIMEOUT_MS=5000 + +*CCLITE TIME +START=0.0 +END=1.0e-4 +DT=1.0e-6 + +*CCLITE INTERFACE, NAME=IFACE_1 +SPH_REGION=MOCK_SPH_REGION +FEM_SURFACE=MOCK_FEM_SURFACE + +*CCLITE OUTPUT +DIRECTORY=output/v010_empty_coupling +CSV=YES +LOG=YES +``` + +0.1.x 中该算例不要求产生真实接触力;若输入显式请求真实 contact,程序应给出明确错误或仅允许空耦合模式,不能静默伪装成真实接触已完成。 + +# 9. 0.1.x 命令流程 + +0.1.x 主流程: + +```text +CCLite parse .inp +CCLite check case +CCLite create command blocks +CCLite create data blocks +CCLite create named events +CCLite launch SPH worker +CCLite launch FEM worker +CCLite wait READY + +for each step: + CCLite send EXPORT_INTERFACE + SPH/FEM write interface data + CCLite read headers and payload + CCLite write zero loads + CCLite send ADVANCE + SPH/FEM advance or mock advance + CCLite write diagnostics + +CCLite send WRITE_OUTPUT +CCLite send STOP +CCLite release IPC +CCLite exit +``` + +0.1.x 支持的 worker 命令: + +| command | 0.1.x 行为 | +| --- | --- | +| `INIT` | worker 打开 IPC 并初始化 | +| `READ_INPUT` | worker 读取输入或 mock 配置 | +| `BUILD_MODEL` | worker 构建模型或 mock 数据 | +| `EXPORT_INTERFACE` | worker 写出接口数据,可为空 | +| `ADVANCE` | worker 推进一步或 mock step | +| `WRITE_OUTPUT` | worker 写自身输出,可为空 | +| `STOP` | worker 正常退出 | + +# 10. 测试计划 + +## 10.1 单元测试 + +0.1.x 单元测试: + +1. `.inp` 正常解析; +2. `.inp` 缺失必需字段; +3. `.inp` 非法 IPC 类型; +4. keyword 大小写; +5. command block pack/unpack; +6. data block header pack/unpack; +7. block role 枚举; +8. buffer state 转换; +9. 错误码映射; +10. CSV writer。 + +## 10.2 接口测试 + +0.1.x 接口测试: + +1. shared memory create/open/map/close; +2. named event create/open/wait/signal/reset/close; +3. command seq/ack; +4. heartbeat; +5. timeout; +6. worker state; +7. data block header 校验; +8. record count 超限; +9. bad magic; +10. bad layout id。 + +## 10.3 集成测试 + +0.1.x 集成测试: + +1. CCLite + mock SPH worker; +2. CCLite + mock FEM worker; +3. CCLite + 双 mock workers; +4. 双 mock workers 空耦合 1 step; +5. 双 mock workers 空耦合 100 steps; +6. worker 启动失败; +7. worker 中途超时; +8. CCLite 正常 STOP; +9. CCLite 异常清理。 + +## 10.4 验证算例 + +0.1.x 唯一硬验证算例: + +```text +V010_EMPTY_COUPLING +``` + +通过指标: + +1. 连续运行不少于 100 个空耦合 step; +2. `command_seq` 与 `ack_seq` 全部配对; +3. `step_id` 连续递增; +4. `num_active_contacts = 0`; +5. `sum_force_sph = 0`; +6. `sum_force_fem = 0`; +7. 无 IPC 超时; +8. 无未解释错误码; +9. worker 正常退出; +10. 资源释放完整。 + +# 11. 验收清单 + +0.1.x 发布候选必须满足: + +1. 构建通过; +2. `cclite --version` 可用; +3. `cclite --help` 可用; +4. check 模式通过合法 `.inp`; +5. check 模式拒绝非法 `.inp`; +6. dry-run 模式可创建并释放 IPC; +7. mock workers 可由 CCLite 启动; +8. command block 字段检查通过; +9. named event 同步检查通过; +10. data block header 检查通过; +11. `V010_EMPTY_COUPLING` 通过; +12. Python checker 生成通过报告; +13. 日志和 CSV 输出完整; +14. Linux/MPI 配置给出预留或不支持提示; +15. 0.1.x 文档与实现一致; +16. 不要求真实接触力验收。 + +# 12. 质量门禁 + +每个 0.1.x patch 合入前应满足: + +1. 代码可编译; +2. 新增模块有最小测试; +3. 不破坏已有 mock 测试; +4. 不引入非 UTF-8 文档; +5. 不改变已冻结接口字段,除非同步更新 05 号文档; +6. 不把 Windows API 暴露到算法层; +7. 不让 SPHLite/FEMLite 直接链接 CCLite 算法核心; +8. 不把 Python checker 写成核心算法依赖。 + +0.1.x 发布前应执行: + +1. quick 测试; +2. standard 测试中的 mock 集成部分; +3. `V010_EMPTY_COUPLING`; +4. 文档一致性检查; +5. UTF-8 without BOM 检查。 + +# 13. 风险与对策 + +## 13.1 Windows IPC 细节复杂 + +风险: + +Windows shared memory、named event、句柄生命周期和错误码容易泄漏到 Fortran 算法层。 + +对策: + +1. IPC 细节只放在 C/C++ 薄层和 Fortran2018 wrapper; +2. Fortran95 核心只看到逻辑数据结构; +3. 所有 IPC 资源创建和释放都集中管理; +4. 增加重复运行测试。 + +## 13.2 C/Fortran 二进制布局不一致 + +风险: + +command block 和 data block header 如果直接跨语言映射,可能出现对齐和字节数差异。 + +对策: + +1. 优先使用明确 pack/unpack; +2. 若使用 `bind(C)`,必须写字段偏移测试; +3. 所有 block 有 `magic`、`abi_version` 和 `layout_id`; +4. Python checker 不直接假设未文档化字段。 + +## 13.3 真实 worker 接入拖慢 0.1.x + +风险: + +SPHLite/FEMLite 原有主程序改造可能影响 0.1.x 通信闭环进度。 + +对策: + +1. 先用 mock worker 完成硬验收; +2. 真实 worker 接入按最小 handshake 推进; +3. 保持 SPHLite/FEMLite 独立主控入口; +4. 若真实 worker 未完全接入,应记录缺口,不影响 mock 闭环验收。 + +## 13.4 0.1.x 范围膨胀 + +风险: + +过早加入接触力、摩擦、FSI 或性能优化,会破坏 0.1.x 建立通信地基的目标。 + +对策: + +1. 0.1.x 不做真实物理接触验收; +2. 接触算法入口可预留但默认关闭; +3. 单粒子撞面放入 0.2.x; +4. 工程算例放入 0.9.x; +5. 所有超范围需求进入 backlog。 + +# 14. Backlog + +以下事项不进入 0.1.x 硬验收,但应记录为后续版本准备: + +1. `V020_SINGLE_PARTICLE_WALL` 输入模板; +2. 几何最近点单元测试框架; +3. 基础 hash grid 数据结构; +4. penalty 接触力模块空接口; +5. SPH/FEM 真实界面数据导出细节; +6. SoA v2 layout 设计草案; +7. Linux shared memory 后端草案; +8. MPI 后端草案; +9. worker 故障注入扩展; +10. 长时间运行性能指标。 + +# 15. 完成定义 + +CCLite 0.1.x 完成的定义: + +1. 文档、源码、测试和样例均以 Fortran/IPC/.inp 方案为基线; +2. CCLite、mock SPH worker、mock FEM worker 可形成三进程闭环; +3. Windows shared memory 和 named event 可稳定创建、使用和释放; +4. command block 和 data block header 与 05 号文档一致; +5. `V010_EMPTY_COUPLING` 通过自动检查; +6. 日志和 CSV 可定位输入、IPC、worker 和资源释放问题; +7. 0.1.x 不宣称真实 SPH-FEM 接触力已经完成; +8. 0.2.x 可以在此基础上开始基础 penalty contact 开发。 + +0.1.x 的成功标准是一条干净、可重复、可诊断的通信和主控链路。只要这条链路稳定,后续 0.2.x 到 0.7.x 的算法实现才能可靠落地。 diff --git a/femlite_suggests.md b/femlite_suggests.md new file mode 100644 index 0000000..76950f7 --- /dev/null +++ b/femlite_suggests.md @@ -0,0 +1,513 @@ +# FEMLite 配合 CCLite 的改造建议 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**对象**:FEMLite +**目的**:使 FEMLite 能作为 CCLite 的独立 worker/service,参与 SPH-FEM 耦合、接触和后续 FSI 联合仿真。 +**依据**:CCLite `01` 到 `06` 号文档、`v1.x_development_plan.md`、FEMLite 当前接口文档与能力说明。 +**编码要求**:中文,UTF-8 without BOM。 + +# 1. 总体建议 + +FEMLite 不需要被改造成 CCLite 的内部库,也不应把 CCLite 接触算法写入 FEMLite 内部。建议 FEMLite 保持独立主控程序身份,只新增一层面向 CCLite 的 worker/service 模式。 + +FEMLite 对 CCLite 的核心责任是: + +1. 在 worker 模式下接受 CCLite 的命令; +2. 按 CCLite 要求导出 FEM 边界 surface/facet 状态; +3. 接收 CCLite 写回的节点力、facet 载荷或后续压力载荷; +4. 将外部载荷安全叠加到 FEM 显式或隐式求解流程; +5. 输出可检查的接口诊断; +6. 保持原 FEMLite 独立运行、Fortran API 和 C ABI 不被破坏。 + +建议把本改造定位为: + +```text +FEMLite 原有求解器 + + +FEMLite CCLite worker/service adapter + + +FEM surface/load public interface +``` + +其中 adapter 只负责通信、命令和数据映射,不负责 CCLite 算法。 + +# 2. 必须保持的边界 + +## 2.1 FEMLite 继续负责 + +FEMLite 继续负责: + +1. FEM 节点、单元、材料、section、边界条件解析; +2. 实体/壳单元内力、质量、刚度和本构更新; +3. 显式动力学、静力、非线性、隐式 Newmark 等自身求解流程; +4. FEM 内部接触、cohesive、mortar/AL 等已有能力; +5. restart、CSV/VTK 输出和自身 release gate; +6. FEM 内部错误码和诊断。 + +## 2.2 CCLite 负责 + +CCLite 负责: + +1. 启动和调度 FEMLite worker; +2. 创建和销毁 Windows shared memory 与 named event; +3. 解析 CCLite `.inp`; +4. 读取 FEMLite 导出的 boundary facet; +5. 读取 SPHLite 导出的粒子状态; +6. 计算 SPH-FEM 接触、耦合和 FSI 界面载荷; +7. 把结果写回 FEMLite 和 SPHLite; +8. 输出联合诊断。 + +## 2.3 FEMLite 不应做 + +FEMLite 不应: + +1. 直接调度 SPHLite; +2. 直接读取 SPHLite 私有数据结构; +3. 直接链接 CCLite Fortran95 算法核心; +4. 在自身内部复制 CCLite 的 SPH-FEM 接触搜索算法; +5. 修改 CCLite 创建的 event reset 责任; +6. 把 CCLite 0.1.x 预留能力宣称为已完成物理算法。 + +# 3. 0.1.x 必要改造 + +0.1.x 的目标是让 FEMLite 能参与 CCLite 空耦合和接口闭环,不要求真实 SPH-FEM 接触力验收。 + +FEMLite 侧建议完成: + +1. 增加 `--cclite-worker` 命令行模式; +2. worker 模式能打开 CCLite 创建的 command block; +3. worker 模式能打开 CCLite 创建的 data block; +4. worker 模式能等待 `COMMAND_EVENT`; +5. worker 模式能触发 `DONE_EVENT`; +6. worker 只 wait/signal,不 reset event; +7. 支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; +8. `substep_id=0`、`iteration_id=0`; +9. 可导出 0 个或少量固定 FEM facet; +10. 可接收空载荷; +11. 可写出 worker 日志和接口诊断。 + +0.1.x 完成标准: + +1. FEMLite 原独立运行入口不受影响; +2. CCLite 能启动 FEMLite worker; +3. FEMLite worker 能进入 `READY`; +4. FEMLite worker 可完成 100 step 空耦合; +5. FEMLite worker 可响应 `STOP`; +6. 异常时能写 `error_code`; +7. 资源由 CCLite 释放后,FEMLite worker 正常退出。 + +# 4. Worker/Service 模式建议 + +## 4.1 启动方式 + +建议 FEMLite 支持: + +```text +femlite.exe --cclite-worker --solver-id FEM --case femlite.inp --ipc-name +``` + +可选参数: + +```text +--command-block +--data-prefix +--log +--timeout-ms +--worker-id +``` + +若未指定 `--cclite-worker`,FEMLite 仍按原 CLI 行为运行。 + +## 4.2 Worker 主循环 + +建议 worker 主循环为: + +```text +initialize worker +open command block +open data blocks +signal READY + +while true: + wait COMMAND_EVENT + read command block + + case INIT: + initialize ipc-side state + + case READ_INPUT: + read femlite.inp + + case BUILD_MODEL: + build FEM model and surface database + + case EXPORT_INTERFACE: + write FEM_TO_CCL_FACET + + case IMPORT_LOADS: + read CCL_TO_FEM_LOAD + + case ADVANCE: + advance one CCLite macro step or worker-controlled step + + case WRITE_OUTPUT: + write FEMLite output + + case STOP: + signal DONE and exit + + write ack_seq + update worker_state + signal DONE_EVENT +``` + +0.1.x 可暂不启用 `IMPORT_LOADS`,但应保留命令枚举。0.2.x 必须支持载荷导入。 + +# 5. FEM Surface/Facet 导出建议 + +## 5.1 导出对象 + +FEMLite 应面向 CCLite 导出 boundary surface/facet,而不是导出完整单元内部状态。 + +0.2.x 接触至少需要: + +1. facet id; +2. surface id; +3. element id; +4. node count; +5. node ids; +6. 当前节点坐标; +7. 当前节点速度; +8. facet normal; +9. facet area; +10. shell thickness; +11. mass per area; +12. material id; +13. section id; +14. body id; +15. valid flags。 + +## 5.2 实体面 + +实体单元边界面建议导出: + +```text +face_id +elem_id +surface_id +node_count = 3 or 4 +node_ids[] +x_node[3,node] +v_node[3,node] +normal[3] +area +material_id +body_id +valid_flags +``` + +实体面 `shell_thickness` 可写 0。 + +## 5.3 壳面 + +壳单元面建议导出: + +```text +face_id +elem_id +surface_id +node_count = 3 or 4 +node_ids[] +x_node[3,node] +v_node[3,node] +normal[3] +area +shell_thickness +mass_per_area +section_id +material_id +body_id +valid_flags +``` + +壳厚度必须来自 FEMLite section 或壳单元属性,不能由 CCLite 猜测。CCLite 只把 `shell_thickness` 用于接触距离、载荷分配和诊断。 + +## 5.4 法向约定 + +FEMLite 应导出稳定、可复现的 facet normal。 + +建议: + +1. normal 使用当前构型; +2. normal 长度为 1; +3. 退化 facet 设置 invalid flag; +4. 四边形 facet 的 normal 与 FEMLite 自身壳/面定义一致; +5. CCLite 可在单个接触对内部翻转局部法向,但不得修改 FEMLite 原始法向。 + +## 5.5 Surface id + +FEMLite 输入文件应允许用户定义可被 CCLite 引用的 surface 名称。 + +建议: + +```text +*SURFACE, NAME=CCL_SURF_1 +... +``` + +FEMLite worker 导出时应提供稳定 `surface_id`。若短期内只能导出全边界,可填 0,但必须输出 warning,便于 0.2.x 后定位接触范围。 + +# 6. 载荷导入建议 + +## 6.1 0.2.x 必须支持 + +0.2.x 起 FEMLite 应支持 `CCL_TO_FEM_LOAD`。 + +基本载荷类型: + +1. `NODAL_FORCE`; +2. 后续预留 `FACET_PRESSURE`; +3. 后续预留 `MOMENT`; +4. 后续预留 `KINEMATIC_BOUNDARY`。 + +基础接触建议先只做节点力: + +```text +node_id +force[3] +source_id +load_mode +distribution_mode +valid_flags +``` + +## 6.2 外部载荷缓存 + +FEMLite 内部建议增加独立外部耦合载荷缓存: + +```text +fem_cclite_external_load + node_id + force[3] + moment[3] + source_id + step_id + active +``` + +该缓存应在每个 CCLite step 开始前清零,导入后叠加到当前求解步的外力项或 RHS。 + +不要让 CCLite 直接写 FEMLite 内部全局力数组。 + +## 6.3 力和力矩守恒 + +FEMLite 应输出或允许查询: + +1. 本步接收的 CCLite 总力; +2. 本步接收的 CCLite 总力矩; +3. 每个 surface 的总载荷; +4. 被拒绝的 load record 数量; +5. 非有限载荷数量; +6. 节点 id 未匹配数量。 + +这些量用于 CCLite 的 `force_balance.csv` 和 06 号验证计划。 + +# 7. 输入文件建议 + +FEMLite 自身输入仍由 FEMLite 解析。为配合 CCLite,建议新增或明确以下关键词能力。 + +## 7.1 Surface 定义 + +建议支持: + +```text +*SURFACE, NAME=CCL_SURF_PLATE, TYPE=ELEMENT +... +``` + +对于壳: + +```text +*SHELL SECTION, ELSET=PLATE, THICKNESS=... +``` + +FEMLite worker 应能根据 `FEM_SURFACE` 名称导出对应 facet。 + +## 7.2 CCLite 输出开关 + +可选支持: + +```text +*FEMLITE CCLITE +WORKER=YES +EXPORT_SURFACE=CCL_SURF_PLATE +EXPORT_VELOCITY=YES +EXPORT_THICKNESS=YES +ACCEPT_EXTERNAL_LOAD=YES +``` + +该关键词只是 FEMLite 侧辅助开关,不替代 CCLite `.inp`。 + +# 8. API/ABI 建议 + +FEMLite 已有 Fortran API 和 C ABI。建议在不破坏现有接口的前提下增加中立命名接口,不要出现 SPHLite 私有结构。 + +建议 C ABI: + +```c +int femlite_get_coupling_surface_count(const char *surface_name, + int *num_facets, + int *max_nodes_per_facet); + +int femlite_get_coupling_surface_facets(const char *surface_name, + int max_facets, + int max_nodes_per_facet, + long long *facet_id, + long long *elem_id, + int *surface_id, + int *node_count, + long long *node_ids, + double *x, + double *v, + double *normal, + double *area, + double *shell_thickness, + double *mass_per_area, + int *material_id, + int *section_id, + int *body_id, + int *valid_flags, + int *num_facets); + +int femlite_apply_coupling_nodal_forces(int num_loads, + const long long *node_ids, + const double *forces, + const long long *source_ids, + const int *load_mode, + const int *valid_flags); +``` + +数组展开建议沿用 FEMLite 现有 C ABI 风格: + +```text +x[dim + 3 * (local_node + max_nodes_per_facet * facet)] +v[dim + 3 * (local_node + max_nodes_per_facet * facet)] +normal[dim + 3 * facet] +forces[dim + 3 * load] +``` + +# 9. 与 CCLite 版本路线的配合 + +| CCLite 版本 | FEMLite 配合目标 | +| --- | --- | +| 0.1.x | worker/service、command block、named event、空 facet/固定 facet 导出、空载荷接收 | +| 0.2.x | surface/facet 完整导出、节点力导入、单粒子撞面和多粒子压面验证 | +| 0.3.x | 壳厚度、边缘、四边形 facet、surface id 稳定化 | +| 0.4.x | 阻尼/摩擦接触所需切向速度、接触诊断和载荷能量统计 | +| 0.5.x | tied/release 所需绑定 surface、release 状态和 tie-to-contact 诊断 | +| 0.6.x | pressure projection、FEM 运动边界、boundary/ghost 数据支持 | +| 0.7.x | 弱耦合/强耦合需要的 step rollback 或预测状态接口预留 | +| 0.8.x | SoA v2 性能测试、长时间稳定性和异常处理补强 | +| 0.9.x | 工程简化算例、水下爆炸 FSI、参数推荐和性能基线 | + +# 10. 测试建议 + +## 10.1 0.1.x 测试 + +FEMLite 侧建议新增: + +1. worker 启动测试; +2. worker `READY` 状态测试; +3. command seq/ack 测试; +4. named event wait/signal 测试; +5. 空 facet 导出测试; +6. 固定 facet 导出测试; +7. 空载荷导入测试; +8. `STOP` 正常退出测试; +9. 超时和错误码测试。 + +## 10.2 0.2.x 测试 + +建议新增: + +1. 单三角形 facet 导出; +2. 单四边形 facet 导出; +3. 壳 facet 厚度导出; +4. 节点速度导出; +5. 节点力导入; +6. 节点 id 未匹配错误; +7. 非有限载荷拒绝; +8. 与 CCLite 的 `V020_SINGLE_PARTICLE_WALL` 联合测试。 + +## 10.3 工程测试 + +建议保留以下 FEMLite 原有或新增算例作为后续联合验证基础: + +1. 刚性平面/壳板接触小算例; +2. clamped square plate pressure pulse; +3. rigid sphere impact plate; +4. shell rigid plane contact; +5. shell/solid surface 导出 smoke。 + +# 11. 诊断建议 + +FEMLite worker 应至少输出: + +1. worker 启动参数; +2. CCLite command block 名称; +3. data block 名称; +4. 当前 command id; +5. step id; +6. ack seq; +7. worker state; +8. 导出 facet 数量; +9. 接收 load 数量; +10. 接收总力; +11. 接收总力矩; +12. 错误码和错误消息。 + +建议输出文件: + +```text +femlite_cclite_worker.log +femlite_cclite_surface_report.csv +femlite_cclite_load_report.csv +``` + +# 12. 优先级建议 + +最高优先级: + +1. worker/service 模式; +2. command block 与 named event; +3. surface/facet 导出; +4. 空载荷和节点力导入; +5. 诊断输出; +6. 与 CCLite mock/空耦合联调。 + +次优先级: + +1. shell thickness 和 mass_per_area 精确导出; +2. surface id 稳定化; +3. pressure/facet load; +4. tie/release 支持; +5. rollback/强耦合预留。 + +# 13. 总结 + +FEMLite 配合 CCLite 的关键不是重写 FEMLite 接触算法,而是提供稳定的外部边界数据和外部载荷通道。 + +建议 FEMLite 的改造口径为: + +```text +保持独立主控程序 +增加 CCLite worker/service 模式 +导出 surface/facet 状态 +接收 CCLite 节点力/面载荷 +提供诊断和错误码 +不依赖 SPHLite 内部结构 +不嵌入 CCLite 算法核心 +``` + +这样 FEMLite 能在 0.1.x 参与通信闭环,在 0.2.x 支撑基础 SPH-FEM penalty contact,在后续版本支撑壳厚度、tied/release、FSI 和工程算例。 diff --git a/include/README.md b/include/README.md new file mode 100644 index 0000000..73c57e7 --- /dev/null +++ b/include/README.md @@ -0,0 +1,5 @@ +# include + +Public C/C++ headers for CCLite IPC and worker-facing binary layouts will be placed here. + +0.1.0 only creates the directory and reserves `cclite_ipc.h` for the IPC layer. diff --git a/sphlite_suggests.md b/sphlite_suggests.md new file mode 100644 index 0000000..49a8c67 --- /dev/null +++ b/sphlite_suggests.md @@ -0,0 +1,548 @@ +# SPHLite 配合 CCLite 的改造建议 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**对象**:SPHLite +**目的**:使 SPHLite 能作为 CCLite 的独立 worker/service,参与 SPH-FEM 耦合、接触和后续 FSI 联合仿真。 +**依据**:CCLite `01` 到 `06` 号文档、`v1.x_development_plan.md`、SPHLite 当前接口文档与能力说明。 +**编码要求**:中文,UTF-8 without BOM。 + +# 1. 总体建议 + +SPHLite 不需要被改造成 CCLite 的内部库,也不应把 FEMLite 或 CCLite 的内部结构写入 SPHLite 核心物理模块。建议 SPHLite 保持独立主控程序身份,只新增一层面向 CCLite 的 worker/service 模式和 CouplingInterface。 + +SPHLite 对 CCLite 的核心责任是: + +1. 在 worker 模式下接受 CCLite 的命令; +2. 按 coupling region 导出 SPH 粒子状态; +3. 可选导出 SPH 侧 facet、壳粒子或边界近似; +4. 接收 CCLite 写回的粒子力、接触状态、边界状态或后续 FSI 状态; +5. 将外部耦合载荷安全叠加到 SPH 显式求解; +6. 输出可检查的耦合诊断; +7. 保持 SPHLite 原独立运行、Fortran API、C ABI 和 Python 调试入口不被破坏。 + +建议把本改造定位为: + +```text +SPHLite 原有求解器 + + +SPHLite CCLite worker/service adapter + + +SPH CouplingInterface +``` + +其中 adapter 只负责通信、命令和数据映射,不负责 CCLite 接触算法。 + +# 2. 必须保持的边界 + +## 2.1 SPHLite 继续负责 + +SPHLite 继续负责: + +1. SPH 粒子、材料、section、phase、EOS 和时间控制; +2. 水、气、炸药、solid、shell 等 SPH 内部物理; +3. SPH 邻域搜索、密度、压力、内力、人工粘性和稳定时间步; +4. SPH 内部结构/壳粒子的状态更新; +5. 显式动力学推进; +6. SPH 自身输出、restart 和诊断; +7. SPHLite 错误码和 release gate。 + +## 2.2 CCLite 负责 + +CCLite 负责: + +1. 启动和调度 SPHLite worker; +2. 创建和销毁 Windows shared memory 与 named event; +3. 读取 SPHLite coupling region; +4. 读取 FEMLite surface/facet; +5. 计算 SPH-FEM 接触、耦合和 FSI 界面载荷; +6. 把结果写回 SPHLite 和 FEMLite; +7. 输出联合诊断。 + +## 2.3 SPHLite 不应做 + +SPHLite 不应: + +1. 直接调度 FEMLite; +2. 直接读取 FEMLite 私有数据结构; +3. 在公开 ABI 中出现 FEMLite 内部类型; +4. 直接链接 CCLite Fortran95 算法核心; +5. 在自身内部复制 CCLite 的 SPH-FEM 接触搜索算法; +6. 修改 CCLite 创建的 event reset 责任; +7. 把 0.1.x 的通信闭环宣称为真实接触算法完成。 + +# 3. 0.1.x 必要改造 + +0.1.x 的目标是让 SPHLite 能参与 CCLite 空耦合和接口闭环,不要求真实 SPH-FEM 接触力验收。 + +SPHLite 侧建议完成: + +1. 增加 `--cclite-worker` 命令行模式; +2. worker 模式能打开 CCLite 创建的 command block; +3. worker 模式能打开 CCLite 创建的 data block; +4. worker 模式能等待 `COMMAND_EVENT`; +5. worker 模式能触发 `DONE_EVENT`; +6. worker 只 wait/signal,不 reset event; +7. 支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`; +8. `substep_id=0`、`iteration_id=0`; +9. 可导出 0 个或少量固定 SPH 粒子; +10. 可接收空粒子力; +11. 可写出 worker 日志和接口诊断。 + +0.1.x 完成标准: + +1. SPHLite 原独立运行入口不受影响; +2. CCLite 能启动 SPHLite worker; +3. SPHLite worker 能进入 `READY`; +4. SPHLite worker 可完成 100 step 空耦合; +5. SPHLite worker 可响应 `STOP`; +6. 异常时能写 `error_code`; +7. 资源由 CCLite 释放后,SPHLite worker 正常退出。 + +# 4. Worker/Service 模式建议 + +## 4.1 启动方式 + +建议 SPHLite 支持: + +```text +sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name +``` + +可选参数: + +```text +--command-block +--data-prefix +--log +--timeout-ms +--worker-id +``` + +若未指定 `--cclite-worker`,SPHLite 仍按原 CLI 行为运行。 + +## 4.2 Worker 主循环 + +建议 worker 主循环为: + +```text +initialize worker +open command block +open data blocks +signal READY + +while true: + wait COMMAND_EVENT + read command block + + case INIT: + initialize ipc-side state + + case READ_INPUT: + read sphlite.inp + + case BUILD_MODEL: + build SPH model and coupling regions + + case EXPORT_INTERFACE: + write SPH_TO_CCL_PARTICLE + + case IMPORT_LOADS: + read CCL_TO_SPH_FORCE + + case ADVANCE: + advance one explicit step or worker-controlled step + + case WRITE_OUTPUT: + write SPHLite output + + case STOP: + signal DONE and exit + + write ack_seq + update worker_state + signal DONE_EVENT +``` + +0.1.x 可暂不启用 `IMPORT_LOADS`,但应保留命令枚举。0.2.x 必须支持粒子力导入。 + +# 5. Coupling Region 导出建议 + +## 5.1 导出对象 + +SPHLite 应按 coupling region 导出粒子状态,而不是导出全部内部数组。 + +0.2.x 接触至少需要: + +1. external particle id; +2. internal index; +3. phase; +4. status; +5. material id; +6. section id; +7. body id; +8. position; +9. velocity; +10. mass; +11. density; +12. volume; +13. smoothing length; +14. contact radius; +15. pressure; +16. sound speed; +17. valid flags。 + +## 5.2 接触半径 + +CCLite 04 号文档允许: + +1. SPHLite 直接导出 `radius`; +2. 或 CCLite 根据 `h` 和输入参数估计 `radius = alpha_r h`。 + +建议 SPHLite 优先显式导出接触半径。该半径只用于跨域接触,不改变 SPHLite 内部核函数和邻域计算。 + +## 5.3 Pressure 与 sound speed + +为后续 FSI 和 Riemann FSI,建议从 0.2.x 起 SPHLite 粒子导出中保留: + +1. pressure; +2. density; +3. sound speed; +4. internal energy,可选; +5. phase; +6. EOS/material id。 + +0.6.x pressure projection 和 0.7.x Riemann FSI 会使用这些字段。 + +## 5.4 SPH facet 或壳粒子 + +若 SPHLite 已有壳粒子或粒子构成的表面 facet,建议保留 `SPH_TO_CCL_FACET` 的导出能力。 + +0.1.x 到 0.5.x 可为空 block。 + +0.6.x 以后用于: + +1. SPH 边界近似; +2. SPH shell 与 FEM surface 耦合; +3. boundary/ghost particle 诊断; +4. FSI 接口状态。 + +# 6. 外部载荷导入建议 + +## 6.1 0.2.x 必须支持 + +0.2.x 起 SPHLite 应支持 `CCL_TO_SPH_FORCE`。 + +基础 record: + +```text +particle_id +force[3] +moment[3] +source_id +load_mode +contact_state +valid_flags +``` + +其中: + +1. `force` 是 CCLite 计算的跨域接触或耦合力; +2. `moment` 第一阶段可为 0,壳粒子后续启用; +3. `source_id` 用于追踪 contact pair 或 FEM facet; +4. `contact_state` 用于诊断和后续 persistence; +5. `load_mode` 区分粒子力、接触状态、运动边界和后续 FSI 状态。 + +## 6.2 外部载荷缓存 + +SPHLite 内部建议增加独立外部耦合载荷缓存: + +```text +sph_cclite_external_load + particle_id_ext + internal_index + force[3] + moment[3] + source_id + contact_state + step_id + active +``` + +该缓存应在每个 CCLite step 开始前清零,导入后叠加到 SPH 动量方程或显式外力项。 + +不要让 CCLite 直接写 SPHLite 内部加速度、速度或力数组。 + +## 6.3 力和冲量诊断 + +SPHLite 应输出或允许查询: + +1. 本步接收的 CCLite 总力; +2. 本步接收的 CCLite 总力矩; +3. 每个 coupling region 的总力; +4. 被拒绝的 force record 数量; +5. 非有限载荷数量; +6. particle id 未匹配数量。 + +这些量用于 CCLite 的 `force_balance.csv` 和 06 号验证计划。 + +# 7. 接触状态导入建议 + +CCLite 会计算跨域接触状态。SPHLite 不需要重复计算 FEM 接触搜索,但可以接收接触状态,用于诊断、输出或后续物理处理。 + +建议支持: + +```text +contact_state = inactive / candidate / active / released / tied +penetration +normal[3] +source_facet_id +pair_id +``` + +0.2.x 可只导入 `contact_state` 和 `pair_id`。 + +0.3.x 起可导入 `penetration` 和 `normal` 供输出。 + +0.5.x tied/release 后可导入 `released` 状态。 + +# 8. Boundary/Ghost 与 FSI 预留 + +0.6.x 起 CCLite 需要向 SPHLite 传递 FEM 运动边界、boundary particle 或 ghost particle 状态。 + +建议 SPHLite 预留: + +1. 外部 boundary particle buffer; +2. 外部 ghost state buffer; +3. moving wall velocity; +4. wall normal; +5. boundary pressure; +6. boundary density; +7. interface pressure; +8. interface velocity。 + +SPHLite 如何把这些状态纳入内部 SPH 邻域求和,不由 CCLite 决定,应由 SPHLite 内部边界模型实现。 + +建议后续接口: + +```c +int sphlite_apply_coupling_boundary_states(int num_states, + const long long *state_id, + const double *x, + const double *v, + const double *normal, + const double *pressure, + const double *density, + const double *sound_speed, + const int *state_mode, + const int *valid_flags); +``` + +# 9. 输入文件建议 + +SPHLite 自身输入仍由 SPHLite 解析。为配合 CCLite,建议新增或明确以下关键词能力。 + +## 9.1 Coupling region + +建议支持类似: + +```text +*SPHLITE COUPLING REGION, NAME=CCL_SPH_REGION +PHASE=SOLID,WATER,SHELL +SET=... +EXPORT_PARTICLES=YES +EXPORT_PRESSURE=YES +EXPORT_SOUND_SPEED=YES +ACCEPT_EXTERNAL_FORCE=YES +``` + +CCLite `.inp` 中的 `SPH_REGION` 应引用该名称。 + +## 9.2 CCLite 辅助开关 + +可选支持: + +```text +*SPHLITE CCLITE +WORKER=YES +REGION=CCL_SPH_REGION +EXPORT_RADIUS=YES +EXPORT_PRESSURE=YES +EXPORT_SOUND_SPEED=YES +ACCEPT_CONTACT_STATE=YES +ACCEPT_BOUNDARY_STATE=NO +``` + +该关键词只是 SPHLite 侧辅助开关,不替代 CCLite `.inp`。 + +# 10. API/ABI 建议 + +SPHLite 当前 05 号接口文档已经建议了 CouplingInterface。为贴合 CCLite 05 号文档,建议补强字段并保持中立命名,不出现 FEMLite 私有结构。 + +建议 C ABI: + +```c +int sphlite_get_coupling_particle_count(const char *region, + int *count); + +int sphlite_get_coupling_particles_v2(const char *region, + int max_particles, + long long *particle_id_ext, + int *internal_index, + int *phase, + int *status, + int *material_id, + int *section_id, + int *body_id, + double *x, + double *v, + double *mass, + double *density, + double *volume, + double *h, + double *radius, + double *pressure, + double *sound_speed, + int *valid_flags, + int *count); + +int sphlite_apply_coupling_particle_forces_v2(int num_particles, + const long long *particle_id_ext, + const double *forces, + const double *moments, + const long long *source_ids, + const int *load_mode, + const int *contact_state, + const int *valid_flags); +``` + +数组展开建议沿用 SPHLite 现有 C ABI 风格: + +```text +x[dim + 3 * particle] +v[dim + 3 * particle] +forces[dim + 3 * particle] +moments[dim + 3 * particle] +``` + +若需要保持旧 ABI,可把新增字段放入 `_v2` 接口,旧接口继续保留。 + +# 11. 与 CCLite 版本路线的配合 + +| CCLite 版本 | SPHLite 配合目标 | +| --- | --- | +| 0.1.x | worker/service、command block、named event、空粒子/固定粒子导出、空载荷接收 | +| 0.2.x | coupling region 粒子完整导出、粒子力导入、单粒子撞面和多粒子压面验证 | +| 0.3.x | 壳粒子、接触半径、接触状态、pair id 和 persistence 诊断 | +| 0.4.x | 阻尼/摩擦所需切向速度、接触功和摩擦耗能诊断 | +| 0.5.x | tied/release 所需绑定粒子、damage/release 状态和 tie-to-contact 诊断 | +| 0.6.x | pressure projection、boundary/ghost particle 和 FEM 运动边界支持 | +| 0.7.x | Riemann FSI 所需 pressure、density、sound speed、EOS/material id | +| 0.8.x | 稳定化、长时间运行、异常输入和 AoR/SoA 性能对比 | +| 0.9.x | 水下爆炸 FSI、工程简化算例、参数推荐和性能基线 | + +# 12. 测试建议 + +## 12.1 0.1.x 测试 + +SPHLite 侧建议新增: + +1. worker 启动测试; +2. worker `READY` 状态测试; +3. command seq/ack 测试; +4. named event wait/signal 测试; +5. 空粒子导出测试; +6. 固定粒子导出测试; +7. 空载荷导入测试; +8. `STOP` 正常退出测试; +9. 超时和错误码测试。 + +## 12.2 0.2.x 测试 + +建议新增: + +1. 单粒子 coupling region 导出; +2. 多粒子 coupling region 导出; +3. pressure 和 sound speed 导出; +4. radius 与 h 字段一致性检查; +5. 粒子力导入; +6. particle id 未匹配错误; +7. 非有限载荷拒绝; +8. 与 CCLite 的 `V020_SINGLE_PARTICLE_WALL` 联合测试。 + +## 12.3 FSI 测试 + +建议保留或新增: + +1. 均匀压力场导出; +2. 水相 pressure projection 小算例; +3. boundary/ghost 状态导入 smoke; +4. 一维声阻抗 Riemann 状态导出; +5. 水下爆炸工程简化算例预留。 + +# 13. 诊断建议 + +SPHLite worker 应至少输出: + +1. worker 启动参数; +2. CCLite command block 名称; +3. data block 名称; +4. 当前 command id; +5. step id; +6. ack seq; +7. worker state; +8. 导出粒子数量; +9. 接收 force 数量; +10. 接收总力; +11. 接收总力矩; +12. coupling region 名称; +13. 非有限粒子状态数量; +14. 错误码和错误消息。 + +建议输出文件: + +```text +sphlite_cclite_worker.log +sphlite_cclite_particle_report.csv +sphlite_cclite_force_report.csv +``` + +# 14. 优先级建议 + +最高优先级: + +1. worker/service 模式; +2. command block 与 named event; +3. coupling region 粒子导出; +4. 空载荷和粒子力导入; +5. pressure、density、sound speed 字段预留; +6. 诊断输出; +7. 与 CCLite mock/空耦合联调。 + +次优先级: + +1. 接触状态导入; +2. SPH facet 或壳粒子导出; +3. boundary/ghost 状态; +4. tied/release 状态; +5. Riemann FSI EOS 信息; +6. rollback/强耦合预留。 + +# 15. 总结 + +SPHLite 配合 CCLite 的关键不是让 SPHLite 直接处理 FEM 接触,而是提供稳定的粒子/region 数据和外部载荷通道。 + +建议 SPHLite 的改造口径为: + +```text +保持独立主控程序 +增加 CCLite worker/service 模式 +按 coupling region 导出粒子状态 +接收 CCLite 粒子力/接触状态/边界状态 +提供 pressure、density、sound speed 等 FSI 字段 +提供诊断和错误码 +不依赖 FEMLite 内部结构 +不嵌入 CCLite 算法核心 +``` + +这样 SPHLite 能在 0.1.x 参与通信闭环,在 0.2.x 支撑基础 SPH-FEM penalty contact,在后续版本支撑壳粒子、tied/release、boundary/ghost、Riemann FSI 和水下爆炸工程算例。 diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..972c516 --- /dev/null +++ b/src/README.md @@ -0,0 +1,9 @@ +# src + +CCLite source tree. + +0.1.x keeps the executable programs independent: + +- `app`: CCLite controller entry point. +- `common`: shared version, error and logging utilities. +- `mock_workers`: mock SPH/FEM workers used before real SPHLite/FEMLite worker integration. diff --git a/src/app/cclite_main.f90 b/src/app/cclite_main.f90 new file mode 100644 index 0000000..89b8d1b --- /dev/null +++ b/src/app/cclite_main.f90 @@ -0,0 +1,70 @@ +program cclite_main + use ccl_errors, only: CCL_SUCCESS, CCL_ERROR_INPUT_MISSING_ARGUMENT + use ccl_log, only: ccl_log_info, ccl_log_error + use ccl_version, only: ccl_print_version + implicit none + + integer :: argc + integer :: exit_code + character(len=128) :: command + + argc = command_argument_count() + exit_code = CCL_SUCCESS + + if (argc == 0) then + call print_help() + call exit(CCL_SUCCESS) + end if + + call get_command_argument(1, command) + command = adjustl(command) + + select case (trim(command)) + case ("--help", "-h", "help") + call print_help() + case ("--version", "-v", "version") + call ccl_print_version() + case ("check") + exit_code = handle_mode("check", argc) + case ("dry-run") + exit_code = handle_mode("dry-run", argc) + case ("run") + exit_code = handle_mode("run", argc) + case default + call ccl_log_error("app", "unknown command: " // trim(command)) + call print_help() + exit_code = CCL_ERROR_INPUT_MISSING_ARGUMENT + end select + + call exit(exit_code) + +contains + + integer function handle_mode(mode, argc_value) result(ierr) + character(len=*), intent(in) :: mode + integer, intent(in) :: argc_value + character(len=512) :: input_file + + if (argc_value < 2) then + call ccl_log_error("app", trim(mode) // " requires a CCLite .inp file") + ierr = CCL_ERROR_INPUT_MISSING_ARGUMENT + return + end if + + call get_command_argument(2, input_file) + call ccl_log_info("app", trim(mode) // " mode accepted input: " // trim(input_file)) + call ccl_log_info("app", "0.1.0 only provides the command skeleton") + ierr = CCL_SUCCESS + end function handle_mode + + subroutine print_help() + print '(a)', "CCLite 0.1.x" + print '(a)', "Usage:" + print '(a)', " cclite --help" + print '(a)', " cclite --version" + print '(a)', " cclite check " + print '(a)', " cclite dry-run " + print '(a)', " cclite run " + end subroutine print_help + +end program cclite_main diff --git a/src/case/README.md b/src/case/README.md new file mode 100644 index 0000000..f8a161c --- /dev/null +++ b/src/case/README.md @@ -0,0 +1,3 @@ +# src/case + +CCLite `.inp` parsing, case model and input validation. diff --git a/src/common/ccl_errors.f90 b/src/common/ccl_errors.f90 new file mode 100644 index 0000000..aea36dd --- /dev/null +++ b/src/common/ccl_errors.f90 @@ -0,0 +1,27 @@ +module ccl_errors + implicit none + + integer, parameter :: CCL_SUCCESS = 0 + + integer, parameter :: CCL_ERROR_INPUT_BASE = 1000 + integer, parameter :: CCL_ERROR_INPUT_MISSING_ARGUMENT = CCL_ERROR_INPUT_BASE + 1 + integer, parameter :: CCL_ERROR_INPUT_PARSE_FAILED = CCL_ERROR_INPUT_BASE + 2 + integer, parameter :: CCL_ERROR_INPUT_INVALID_VALUE = CCL_ERROR_INPUT_BASE + 3 + + integer, parameter :: CCL_ERROR_IPC_BASE = 2000 + integer, parameter :: CCL_ERROR_IPC_CREATE_FAILED = CCL_ERROR_IPC_BASE + 1 + integer, parameter :: CCL_ERROR_IPC_OPEN_FAILED = CCL_ERROR_IPC_BASE + 2 + integer, parameter :: CCL_ERROR_IPC_MAP_FAILED = CCL_ERROR_IPC_BASE + 3 + integer, parameter :: CCL_ERROR_IPC_TIMEOUT = CCL_ERROR_IPC_BASE + 4 + integer, parameter :: CCL_ERROR_IPC_BAD_HEADER = CCL_ERROR_IPC_BASE + 5 + + integer, parameter :: CCL_ERROR_WORKER_BASE = 3000 + integer, parameter :: CCL_ERROR_WORKER_START_FAILED = CCL_ERROR_WORKER_BASE + 1 + integer, parameter :: CCL_ERROR_WORKER_STOP_FAILED = CCL_ERROR_WORKER_BASE + 2 + integer, parameter :: CCL_ERROR_WORKER_BAD_STATE = CCL_ERROR_WORKER_BASE + 3 + + integer, parameter :: CCL_ERROR_SYSTEM_BASE = 9000 + integer, parameter :: CCL_ERROR_SYSTEM_UNSUPPORTED = CCL_ERROR_SYSTEM_BASE + 1 + integer, parameter :: CCL_ERROR_SYSTEM_INTERNAL = CCL_ERROR_SYSTEM_BASE + 2 + +end module ccl_errors diff --git a/src/common/ccl_log.f90 b/src/common/ccl_log.f90 new file mode 100644 index 0000000..055e9a5 --- /dev/null +++ b/src/common/ccl_log.f90 @@ -0,0 +1,20 @@ +module ccl_log + implicit none + +contains + + subroutine ccl_log_info(module_name, message) + character(len=*), intent(in) :: module_name + character(len=*), intent(in) :: message + + print '(a)', "[INFO] [" // trim(module_name) // "] " // trim(message) + end subroutine ccl_log_info + + subroutine ccl_log_error(module_name, message) + character(len=*), intent(in) :: module_name + character(len=*), intent(in) :: message + + print '(a)', "[ERROR] [" // trim(module_name) // "] " // trim(message) + end subroutine ccl_log_error + +end module ccl_log diff --git a/src/common/ccl_version.f90 b/src/common/ccl_version.f90 new file mode 100644 index 0000000..66ed2ed --- /dev/null +++ b/src/common/ccl_version.f90 @@ -0,0 +1,16 @@ +module ccl_version + implicit none + + integer, parameter :: CCL_VERSION_MAJOR = 0 + integer, parameter :: CCL_VERSION_MINOR = 1 + integer, parameter :: CCL_VERSION_PATCH = 0 + character(len=*), parameter :: CCL_VERSION_LABEL = "0.1.0" + +contains + + subroutine ccl_print_version() + print '(a)', "CCLite " // CCL_VERSION_LABEL + print '(a)', "Target platform: Windows / gfortran / local shared memory" + end subroutine ccl_print_version + +end module ccl_version diff --git a/src/controller/README.md b/src/controller/README.md new file mode 100644 index 0000000..62ffa90 --- /dev/null +++ b/src/controller/README.md @@ -0,0 +1,3 @@ +# src/controller + +CCLite controller state machine and step dispatch. diff --git a/src/diagnostics/README.md b/src/diagnostics/README.md new file mode 100644 index 0000000..520d269 --- /dev/null +++ b/src/diagnostics/README.md @@ -0,0 +1,3 @@ +# src/diagnostics + +Runtime logs, CSV reports and verification-facing diagnostics. diff --git a/src/interface_data/README.md b/src/interface_data/README.md new file mode 100644 index 0000000..7c67ae1 --- /dev/null +++ b/src/interface_data/README.md @@ -0,0 +1,3 @@ +# src/interface_data + +Command blocks, data block headers and AoR payload records. diff --git a/src/ipc/README.md b/src/ipc/README.md new file mode 100644 index 0000000..adae94a --- /dev/null +++ b/src/ipc/README.md @@ -0,0 +1,3 @@ +# src/ipc + +Windows shared memory and named event wrappers. diff --git a/src/mock_workers/ccl_mock_worker.f90 b/src/mock_workers/ccl_mock_worker.f90 new file mode 100644 index 0000000..0eb2968 --- /dev/null +++ b/src/mock_workers/ccl_mock_worker.f90 @@ -0,0 +1,47 @@ +module ccl_mock_worker + use ccl_errors, only: CCL_SUCCESS + use ccl_log, only: ccl_log_info + use ccl_version, only: CCL_VERSION_LABEL + implicit none + +contains + + integer function run_mock_worker(worker_name, solver_id) result(ierr) + character(len=*), intent(in) :: worker_name + character(len=*), intent(in) :: solver_id + integer :: argc + character(len=128) :: arg + + argc = command_argument_count() + if (argc >= 1) then + call get_command_argument(1, arg) + arg = adjustl(arg) + select case (trim(arg)) + case ("--help", "-h", "help") + call print_worker_help(worker_name) + ierr = CCL_SUCCESS + return + case ("--version", "-v", "version") + print '(a)', trim(worker_name) // " " // CCL_VERSION_LABEL + ierr = CCL_SUCCESS + return + end select + end if + + call ccl_log_info(worker_name, "mock worker started") + call ccl_log_info(worker_name, "solver_id=" // trim(solver_id)) + call ccl_log_info(worker_name, "0.1.0 skeleton exits without IPC attach") + ierr = CCL_SUCCESS + end function run_mock_worker + + subroutine print_worker_help(worker_name) + character(len=*), intent(in) :: worker_name + + print '(a)', trim(worker_name) // " 0.1.x" + print '(a)', "Usage:" + print '(a)', " " // trim(worker_name) // " --help" + print '(a)', " " // trim(worker_name) // " --version" + print '(a)', " " // trim(worker_name) // " --cclite-worker --solver-id " + end subroutine print_worker_help + +end module ccl_mock_worker diff --git a/src/mock_workers/mock_fem_worker_main.f90 b/src/mock_workers/mock_fem_worker_main.f90 new file mode 100644 index 0000000..7da81e1 --- /dev/null +++ b/src/mock_workers/mock_fem_worker_main.f90 @@ -0,0 +1,9 @@ +program mock_fem_worker_main + use ccl_mock_worker, only: run_mock_worker + implicit none + + integer :: ierr + + ierr = run_mock_worker("mock_fem_worker", "FEM") + call exit(ierr) +end program mock_fem_worker_main diff --git a/src/mock_workers/mock_sph_worker_main.f90 b/src/mock_workers/mock_sph_worker_main.f90 new file mode 100644 index 0000000..fd60cbf --- /dev/null +++ b/src/mock_workers/mock_sph_worker_main.f90 @@ -0,0 +1,9 @@ +program mock_sph_worker_main + use ccl_mock_worker, only: run_mock_worker + implicit none + + integer :: ierr + + ierr = run_mock_worker("mock_sph_worker", "SPH") + call exit(ierr) +end program mock_sph_worker_main diff --git a/src/process/README.md b/src/process/README.md new file mode 100644 index 0000000..868d4cf --- /dev/null +++ b/src/process/README.md @@ -0,0 +1,3 @@ +# src/process + +Worker process launch, monitoring and shutdown helpers. diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..7c300a9 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,5 @@ +# tests + +CCLite test tree. + +0.1.x starts with smoke, input, IPC, worker and empty-coupling tests. diff --git a/tests/baselines/README.md b/tests/baselines/README.md new file mode 100644 index 0000000..337f900 --- /dev/null +++ b/tests/baselines/README.md @@ -0,0 +1,3 @@ +# tests/baselines + +Approved regression baselines. diff --git a/tests/data/README.md b/tests/data/README.md new file mode 100644 index 0000000..d7aa528 --- /dev/null +++ b/tests/data/README.md @@ -0,0 +1,3 @@ +# tests/data + +Small test input data. diff --git a/tests/integration/README.md b/tests/integration/README.md new file mode 100644 index 0000000..fcce57b --- /dev/null +++ b/tests/integration/README.md @@ -0,0 +1,3 @@ +# tests/integration + +Integration tests for CCLite plus mock or real workers. diff --git a/tests/interface/README.md b/tests/interface/README.md new file mode 100644 index 0000000..b137c8c --- /dev/null +++ b/tests/interface/README.md @@ -0,0 +1,3 @@ +# tests/interface + +Interface tests for IPC resources, command blocks and payload layouts. diff --git a/tests/unit/README.md b/tests/unit/README.md new file mode 100644 index 0000000..ff1cdcd --- /dev/null +++ b/tests/unit/README.md @@ -0,0 +1,3 @@ +# tests/unit + +Unit tests for parser, block layouts, diagnostics and small utilities. diff --git a/tests/verification/README.md b/tests/verification/README.md new file mode 100644 index 0000000..c52e3b4 --- /dev/null +++ b/tests/verification/README.md @@ -0,0 +1,3 @@ +# tests/verification + +Verification tests, including `V010_EMPTY_COUPLING`. diff --git a/todo.md b/todo.md new file mode 100644 index 0000000..5eade6a --- /dev/null +++ b/todo.md @@ -0,0 +1,342 @@ +# CCLite 0.1.x 待办事项 + +## Coupling & Contact Lite for SPHLite and FEMLite + +**依据**:`docs/v1.x_development_plan.md` +**适用范围**:CCLite 0.1.x +**目标**:完成主控、通信、worker、mock、空耦合、诊断和自动验收闭环。 +**不包含**:真实 SPH-FEM 接触力、单粒子撞面物理验收、摩擦、FSI、Linux/MPI 生产实现、SoA v2。 + +# 1. 任务颗粒度约定 + +每个待办事项应满足: + +1. 可以由一个小 patch 独立完成; +2. 有明确输入、输出或可观察行为; +3. 有最小测试或检查方式; +4. 不跨越多个架构层大改; +5. 完成后能让项目更接近 `V010_EMPTY_COUPLING`。 + +状态标记: + +```text +[ ] 未开始 +[~] 进行中 +[x] 已完成 +[!] 阻塞 +``` + +# 2. 0.1.0 工程骨架 + +目标:建立可编译工程、程序入口和最小 smoke。 + +- [x] T0101 建立 `src/`、`include/`、`tests/`、`cases/`、`Python/` 基础目录。 + 完成判据:目录结构与开发计划一致,空目录有占位说明或后续构建可识别。 + +- [x] T0102 建立 Windows/gfortran 构建入口。 + 完成判据:可构建至少一个 `cclite` 空程序目标。 + +- [x] T0103 增加 CCLite 版本模块。 + 完成判据:程序能输出 `0.1.0` 版本号和构建平台信息。 + +- [x] T0104 增加主程序 CLI 骨架。 + 完成判据:支持 `--help`、`--version`、`check`、`dry-run`、`run` 命令入口。 + +- [x] T0105 增加基础错误码模块。 + 完成判据:输入错误、IPC 错误、worker 错误、系统错误有独立范围。 + +- [x] T0106 增加基础日志模块。 + 完成判据:能写 `run.log`,包含时间、级别、模块名和消息。 + +- [x] T0107 建立空 mock worker 构建目标。 + 完成判据:`mock_sph_worker` 和 `mock_fem_worker` 可启动并输出自身身份。 + +- [x] T0108 增加工程 smoke 测试。 + 完成判据:测试能检查 `cclite --version`、`cclite --help` 和两个 mock worker 启动。 + +# 3. 0.1.1 `.inp` 与 Case Model + +目标:支持 CCLite 主控输入和 check 模式。 + +- [ ] T0111 定义 `CCL_Case` 数据结构。 + 完成判据:可保存 control、solver、ipc、time、interface、output 配置。 + +- [ ] T0112 实现关键词行解析。 + 完成判据:支持 `*CCLITE ...` 关键词、大小写兼容、注释和空行。 + +- [ ] T0113 实现参数键值解析。 + 完成判据:支持 `KEY=VALUE`、字符串路径、数值和布尔值。 + +- [ ] T0114 解析 `*CCLITE CONTROL` 和运行模式。 + 完成判据:能识别 `check`、`dry-run`、`run`,非法模式报错。 + +- [ ] T0115 解析 `*CCLITE SOLVER`。 + 完成判据:能保存 SPH/FEM solver id、kind、executable 和 input 文件。 + +- [ ] T0116 解析 `*CCLITE IPC`。 + 完成判据:0.1.x 只接受 `TYPE=WINDOWS_SHMEM`,其他类型给出预留或不支持错误。 + +- [ ] T0117 解析 `*CCLITE TIME`、`*CCLITE INTERFACE` 和 `*CCLITE OUTPUT`。 + 完成判据:能保存时间范围、dt、region/surface 映射和输出目录。 + +- [ ] T0118 实现 case 校验。 + 完成判据:缺失 solver、缺失 IPC、非法时间步、缺失输出目录均能定位到关键词。 + +- [ ] T0119 实现 `cclite check`。 + 完成判据:合法输入输出检查摘要,非法输入返回非零错误码。 + +- [ ] T0120 增加 `.inp` parser 单元测试。 + 完成判据:覆盖合法输入、未知关键词、缺失字段、非法 IPC 和大小写兼容。 + +# 4. 0.1.2 IPC 基础 + +目标:完成 Windows shared memory 和 named event 最小可用层。 + +- [ ] T0121 定义 C IPC 薄层头文件。 + 完成判据:声明 shared memory、event、error 和 handle 基础接口。 + +- [ ] T0122 实现 shared memory create/open/map。 + 完成判据:可创建命名共享内存并取得 payload 指针。 + +- [ ] T0123 实现 shared memory unmap/close。 + 完成判据:资源释放后同名测试可重复运行。 + +- [ ] T0124 实现 named event create/open。 + 完成判据:可创建 Windows manual-reset named event。 + +- [ ] T0125 实现 named event wait/signal/reset/close。 + 完成判据:wait 支持 timeout,signal/reset 行为可测试。 + +- [ ] T0126 建立 Fortran2018 IPC wrapper。 + 完成判据:Fortran 侧可调用 C IPC 薄层并取得状态码。 + +- [ ] T0127 建立 IPC 资源命名规则。 + 完成判据:同一 case 的 command block、data block 和 event 名称可稳定生成。 + +- [ ] T0128 增加 IPC 错误映射。 + 完成判据:create/open/map/wait 失败能转换为 CCLite 错误码。 + +- [ ] T0129 增加 IPC 接口测试。 + 完成判据:覆盖 shared memory 生命周期、event wait/signal/reset、timeout 和重复释放。 + +# 5. 0.1.3 Command Block 与 Worker 协议 + +目标:实现命令共享块、seq/ack 和 worker 状态机基础。 + +- [ ] T0131 定义 command id 枚举。 + 完成判据:支持 `INIT`、`READ_INPUT`、`BUILD_MODEL`、`EXPORT_INTERFACE`、`ADVANCE`、`WRITE_OUTPUT`、`STOP`。 + +- [ ] T0132 定义 worker state 枚举。 + 完成判据:支持 `STARTING`、`READY`、`BUSY`、`DONE`、`ERROR`、`STOPPED`。 + +- [ ] T0133 定义 command block 逻辑类型。 + 完成判据:字段覆盖 05 号文档要求,`substep_id` 和 `iteration_id` 在 0.1.x 写 0。 + +- [ ] T0134 实现 command block pack/unpack。 + 完成判据:二进制布局可稳定写入共享内存并读回。 + +- [ ] T0135 实现 magic/version/layout 校验。 + 完成判据:非法 magic、ABI 或 layout id 能在初始化阶段拒绝。 + +- [ ] T0136 实现 command seq/ack 配对。 + 完成判据:每条命令都有递增 seq,worker 回写对应 ack。 + +- [ ] T0137 实现 heartbeat 更新。 + 完成判据:worker 空闲或执行命令时能更新 `heartbeat_seq`。 + +- [ ] T0138 实现 command timeout 检测。 + 完成判据:worker 不响应时 CCLite 返回超时错误,不永久等待。 + +- [ ] T0139 增加 command block 单元测试。 + 完成判据:覆盖字段读写、seq/ack、版本校验、非法状态和 timeout。 + +# 6. 0.1.4 Data Block 与 AoR v1 + +目标:实现 data block header、block role 和基础 AoR v1 payload。 + +- [ ] T0141 定义 data block header。 + 完成判据:包含 magic、version、role、layout、record size、count、capacity、state 和 step id。 + +- [ ] T0142 定义 block role 枚举。 + 完成判据:支持 `SPH_TO_CCL_PARTICLE`、`FEM_TO_CCL_FACET`、`CCL_DIAGNOSTIC`、`CCL_COMMAND_SPH`、`CCL_COMMAND_FEM`。 + +- [ ] T0143 定义 buffer state。 + 完成判据:支持 empty、writing、ready、reading、error 状态转换。 + +- [ ] T0144 实现 header pack/unpack。 + 完成判据:共享内存中 header 可由 CCLite 和 worker 双向读写。 + +- [ ] T0145 实现 header 校验。 + 完成判据:非法 role、record size、count 超限和 payload bytes 超限可被拒绝。 + +- [ ] T0146 定义 SPH particle AoR v1 record。 + 完成判据:字段覆盖 id、index、position、velocity、mass、density、h、radius、pressure、sound speed 和 flags。 + +- [ ] T0147 定义 FEM facet AoR v1 record。 + 完成判据:字段覆盖 facet id、surface id、node ids、coords、velocity、normal、area、thickness、mass per area 和 flags。 + +- [ ] T0148 定义空载荷 record 预留。 + 完成判据:0.1.x 可创建 `CCL_TO_SPH_FORCE` 和 `CCL_TO_FEM_LOAD` 空 block。 + +- [ ] T0149 增加 data block 单元测试。 + 完成判据:覆盖空 payload、固定 record、最大 capacity、bad header 和 bad count。 + +# 7. 0.1.5 Controller 空耦合 + +目标:跑通 CCLite + 双 mock worker 的三进程空耦合。 + +- [ ] T0151 实现 worker 进程描述结构。 + 完成判据:可保存 executable、input、solver id、ipc 名称、状态和进程句柄。 + +- [ ] T0152 实现 worker 启动器。 + 完成判据:CCLite 可启动 mock SPH/FEM worker,并记录启动命令。 + +- [ ] T0153 实现 worker 停止和退出监控。 + 完成判据:正常 STOP 和异常退出都能被 CCLite 识别。 + +- [ ] T0154 实现 mock worker IPC attach。 + 完成判据:mock worker 可打开 command block、data block 和 named event。 + +- [ ] T0155 实现 mock worker 命令循环。 + 完成判据:mock worker 可响应 0.1.x 必需命令并回写 ack。 + +- [ ] T0156 实现 mock SPH 固定粒子导出。 + 完成判据:可按配置导出 0 个或少量固定 SPH record。 + +- [ ] T0157 实现 mock FEM 固定 facet 导出。 + 完成判据:可按配置导出 0 个或少量固定 FEM facet record。 + +- [ ] T0158 实现 CCLite dry-run step loop。 + 完成判据:CCLite 可执行 export、读 header、写空载荷、advance、diagnostics。 + +- [ ] T0159 实现 1 step 空耦合集成测试。 + 完成判据:双 mock worker 完成 1 step 并正常退出。 + +- [ ] T0160 实现 100 step 空耦合集成测试。 + 完成判据:双 mock worker 完成 100 step,无 timeout,无残留进程。 + +# 8. 0.1.6 诊断与 Python Checker + +目标:形成可自动判定的 `V010_EMPTY_COUPLING` 验证闭环。 + +- [ ] T0161 实现 `run.log` 标准输出。 + 完成判据:记录版本、输入、worker 命令、IPC 名称、错误码和资源释放。 + +- [ ] T0162 实现 `ipc_report.csv`。 + 完成判据:每步输出 solver id、command id、seq、ack、worker state、heartbeat、elapsed 和 error。 + +- [ ] T0163 实现 `force_balance.csv`。 + 完成判据:0.1.x 空耦合每步输出 SPH/FEM 总力为 0。 + +- [ ] T0164 建立 `Python/checkers/`。 + 完成判据:目录中有 checker 入口和公共 CSV 读取工具。 + +- [ ] T0165 定义 `verification_report.json` schema。 + 完成判据:包含 case id、status、metrics、failed checks、输入和输出文件。 + +- [ ] T0166 实现 `V010_EMPTY_COUPLING` checker。 + 完成判据:检查 seq/ack、step id、timeout、worker state、空载荷和退出状态。 + +- [ ] T0167 建立 `cases/v0_1_ipc_empty_coupling/`。 + 完成判据:包含 CCLite `.inp`、mock 输入说明和预期输出说明。 + +- [ ] T0168 集成 checker 到本地测试命令。 + 完成判据:运行测试后自动生成 `verification_report.json`。 + +- [ ] T0169 增加诊断回归测试。 + 完成判据:CSV 表头变化或关键字段缺失会导致测试失败。 + +# 9. 0.1.7 真实 Worker 最小接入 + +目标:在不破坏 SPHLite/FEMLite 独立运行的前提下,定义或实现最小 worker/service handshake。 + +- [ ] T0171 确认 SPHLite worker 接入方式。 + 完成判据:明确是修改 SPHLite 入口、增加包装程序,还是暂以接入缺口记录。 + +- [ ] T0172 确认 FEMLite worker 接入方式。 + 完成判据:明确是修改 FEMLite 入口、增加包装程序,还是暂以接入缺口记录。 + +- [ ] T0173 固化 worker 启动参数。 + 完成判据:SPHLite/FEMLite 采用一致的 `--cclite-worker` 参数约定。 + +- [ ] T0174 实现或记录 SPHLite handshake。 + 完成判据:SPHLite worker 能进入 `READY`,或形成明确缺口说明。 + +- [ ] T0175 实现或记录 FEMLite handshake。 + 完成判据:FEMLite worker 能进入 `READY`,或形成明确缺口说明。 + +- [ ] T0176 验证 SPHLite 空接口导出。 + 完成判据:真实或包装 worker 可导出空 particle block。 + +- [ ] T0177 验证 FEMLite 空接口导出。 + 完成判据:真实或包装 worker 可导出空 facet block。 + +- [ ] T0178 验证真实 worker 空载荷接收。 + 完成判据:worker 能接受空 force/load block,不报物理算法错误。 + +- [ ] T0179 执行单真实 worker 集成 smoke。 + 完成判据:CCLite + 一个真实 worker + 一个 mock worker 可完成最小 dry-run,或输出受控缺口报告。 + +# 10. 0.1.8 发布候选 + +目标:冻结 0.1.x 通信闭环,准备进入 0.2.x 接触算法开发。 + +- [ ] T0181 执行全量 0.1.x 单元测试。 + 完成判据:`.inp`、command block、data block、错误码和 CSV writer 测试通过。 + +- [ ] T0182 执行全量 0.1.x 接口测试。 + 完成判据:shared memory、named event、timeout、bad header 和 bad layout 测试通过。 + +- [ ] T0183 执行全量 0.1.x 集成测试。 + 完成判据:双 mock workers 1 step 和 100 step 空耦合通过。 + +- [ ] T0184 执行 `V010_EMPTY_COUPLING` 验证算例。 + 完成判据:Python checker 生成通过报告。 + +- [ ] T0185 执行干净环境重建。 + 完成判据:从干净目录构建、运行 smoke 和 V010 均通过。 + +- [ ] T0186 检查 UTF-8 without BOM。 + 完成判据:新增文档和 `.inp` 样例均无 BOM。 + +- [ ] T0187 检查文档一致性。 + 完成判据:README、03、05、06 和开发计划与实现字段、命令、输出一致。 + +- [ ] T0188 冻结 0.1.x 接口常量。 + 完成判据:command id、worker state、block role、layout id、CSV 表头有记录。 + +- [ ] T0189 整理 0.1.x release notes。 + 完成判据:列出已完成能力、未完成能力、真实 worker 接入状态和 0.2.x 入口条件。 + +# 11. 0.1.x 总体验收清单 + +- [ ] A001 `cclite.exe` 可作为独立主控程序启动。 +- [ ] A002 `mock_sph_worker` 和 `mock_fem_worker` 可由 CCLite 启动。 +- [ ] A003 CCLite 可创建和释放 Windows shared memory。 +- [ ] A004 CCLite 可创建和释放 Windows manual-reset named event。 +- [ ] A005 Command block seq/ack 在 100 step 中全部匹配。 +- [ ] A006 Data block header 校验覆盖正常和异常路径。 +- [ ] A007 AoR v1 空 payload 和固定 payload 均可处理。 +- [ ] A008 `cclite check` 可检查合法和非法 `.inp`。 +- [ ] A009 `cclite dry-run` 可完成双 mock 空耦合。 +- [ ] A010 `run.log`、`ipc_report.csv`、`force_balance.csv` 均生成。 +- [ ] A011 Python checker 可生成 `verification_report.json`。 +- [ ] A012 `V010_EMPTY_COUPLING` 自动检查通过。 +- [ ] A013 Linux/MPI 配置只给出预留或不支持提示。 +- [ ] A014 0.1.x 不宣称真实 SPH-FEM 接触力已完成。 +- [ ] A015 0.2.x 可在该基础上进入基础 penalty contact 开发。 + +# 12. 暂不进入 0.1.x 的事项 + +以下事项进入 backlog,不作为 0.1.x 待办: + +- [ ] B001 单粒子撞刚性面物理验收。 +- [ ] B002 点到三角形和点到四边形几何验证。 +- [ ] B003 基础 penalty contact 力计算。 +- [ ] B004 壳厚度、边缘 fallback 和接触 persistence。 +- [ ] B005 Coulomb 摩擦和接触能量耗散。 +- [ ] B006 tied coupling 和 release。 +- [ ] B007 pressure projection 和 boundary/ghost particle。 +- [ ] B008 Riemann FSI。 +- [ ] B009 SoA v2 性能优化。 +- [ ] B010 Linux/MPI 生产后端。