Files
CCLite/docs/03_detailed_design.md
T
2026-07-04 21:52:49 +08:00

1107 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CCLite 详细设计说明书
## Coupling & Contact Lite for SPHLite and FEMLite
**文档版本**:V1.1
**软件名称**:CCLite
**实现基线**:Fortran95 算法核心 + Fortran2018 IPC 包装 + C/C++ Windows IPC 薄层
**输入基线**:Abaqus 风格 `.inp`
**第一阶段平台**:Windows / gfortran / 本机共享内存
---
# 1. 文档说明
## 1.1 编写目的
本文档细化 CCLite 的目录结构、模块职责、核心数据结构、共享内存布局、控制状态机、输入关键词、显式同步流程、接触算法、诊断输出、错误码和版本实现路径。
## 1.2 设计范围
本文档覆盖:
1. Fortran 源码目录结构;
2. CCLite 主控上下文;
3. `.inp` 解析器;
4. Controller 状态机;
5. Windows 本机共享内存和控制 IPC;
6. Fortran2018 `iso_c_binding` 包装;
7. SPH/FEM interface view;
8. 几何、搜索和接触检测;
9. penalty damping 接触力;
10. SPH/FEM 力传递;
11. 诊断输出;
12. 第一阶段测试和验收。
## 1.3 设计边界
CCLite 负责 SPHLite 与 FEMLite 之间的数据交换、接触/耦合算法和同步调度;不负责 SPH/FEM 内部求解。
第一版只实现 Windows/gfortran/本机共享内存。Linux 共享内存、MPI 和分布式 socket 后端只保留枚举、配置项和错误提示。
---
# 2. 推荐目录结构
## 2.1 源码目录
```text
CCLite/
├── Makefile
├── CMakeLists.txt 可选构建入口
├── include/
│ └── cclite/
│ └── cclite_ipc.h C IPC 薄层头文件
├── src/
│ ├── app/
│ │ └── cclite_main.f90
│ ├── base/
│ │ ├── ccl_precision.f90
│ │ ├── ccl_error.f90
│ │ ├── ccl_constants.f90
│ │ └── ccl_string.f90
│ ├── case/
│ │ ├── ccl_case_types.f90
│ │ ├── ccl_inp_reader.f90
│ │ ├── ccl_keyword_parser.f90
│ │ └── ccl_case_validate.f90
│ ├── controller/
│ │ ├── ccl_context.f90
│ │ ├── ccl_controller.f90
│ │ ├── ccl_solver_process.f90
│ │ └── ccl_state_machine.f90
│ ├── ipc/
│ │ ├── ccl_ipc_types.f90
│ │ ├── ccl_ipc_f2018.f90
│ │ ├── ccl_shared_block.f90
│ │ ├── ccl_buffer_state.f90
│ │ └── ccl_win_ipc.c
│ ├── interface/
│ │ ├── ccl_interface_types.f90
│ │ ├── ccl_sph_view.f90
│ │ ├── ccl_fem_view.f90
│ │ └── ccl_interface_manager.f90
│ ├── geometry/
│ │ ├── ccl_vec3.f90
│ │ ├── ccl_aabb.f90
│ │ ├── ccl_closest_point.f90
│ │ └── ccl_shell_geometry.f90
│ ├── search/
│ │ ├── ccl_hash_grid.f90
│ │ └── ccl_candidate_builder.f90
│ ├── contact/
│ │ ├── ccl_contact_types.f90
│ │ ├── ccl_contact_detector.f90
│ │ ├── ccl_penalty_contact.f90
│ │ └── ccl_contact_manager.f90
│ ├── transfer/
│ │ ├── ccl_force_buffer.f90
│ │ ├── ccl_force_transfer.f90
│ │ └── ccl_force_balance.f90
│ ├── diagnostics/
│ │ ├── ccl_diag_types.f90
│ │ ├── ccl_contact_report.f90
│ │ ├── ccl_ipc_report.f90
│ │ └── ccl_timestep_report.f90
│ └── output/
│ ├── ccl_log.f90
│ ├── ccl_csv_writer.f90
│ └── ccl_snapshot_writer.f90
├── tests/
│ ├── unit/
│ ├── integration/
│ └── regression/
├── examples/
└── docs/
```
## 2.2 命名约定
```text
ccl_ Fortran procedure/module 前缀
ccl_*_mod Fortran module 后缀
CCL_ 公共枚举和常量前缀
CCLITE_ 共享内存 magic、环境变量和命令行前缀
```
示例:
```fortran
module ccl_contact_manager_mod
subroutine ccl_contact_manager_compute(ctx, ierr)
integer, parameter :: CCL_CMD_EXPORT_INTERFACE = 20
```
---
# 3. 核心数据类型
## 3.1 精度模块
```fortran
module ccl_precision_mod
implicit none
integer, parameter :: ccl_i4 = selected_int_kind(9)
integer, parameter :: ccl_i8 = selected_int_kind(18)
integer, parameter :: ccl_r8 = selected_real_kind(15, 300)
end module
```
算法核心使用上述 kind,避免在 Fortran95 核心中依赖平台类型。
## 3.2 CCL_Case
```fortran
type CCL_SolverConfig
character(len=32) :: name
character(len=32) :: solver_type
character(len=260) :: executable
character(len=260) :: input_file
character(len=260) :: work_dir
end type
type CCL_IpcConfig
character(len=32) :: ipc_type
character(len=64) :: prefix
character(len=32) :: control
character(len=32) :: buffering
integer :: timeout_ms
end type
type CCL_TimeConfig
real(ccl_r8) :: start_time
real(ccl_r8) :: end_time
real(ccl_r8) :: dt
integer :: output_frequency
end type
type CCL_InterfaceConfig
character(len=64) :: name
character(len=64) :: sph_region
character(len=64) :: fem_surface
end type
type CCL_ContactConfig
character(len=64) :: name
character(len=64) :: interface_name
character(len=64) :: interaction_name
character(len=64) :: contact_type
end type
```
## 3.3 CCL_Context
`CCL_Context` 是 CCLite 顶层运行上下文。
```fortran
type CCL_Context
type(CCL_Case) :: case_data
type(CCL_RunState) :: run_state
type(CCL_IpcManager) :: ipc
type(CCL_InterfaceManager) :: interfaces
type(CCL_SearchState) :: search
type(CCL_ContactState) :: contact
type(CCL_TransferState) :: transfer
type(CCL_Diagnostics) :: diagnostics
end type
```
上下文保存 CCLite 自身状态,不保存 SPHLite/FEMLite 私有求解状态。
## 3.4 Run State
```fortran
type CCL_RunState
integer :: mode
integer :: controller_state
integer :: current_step
real(ccl_r8) :: current_time
integer :: last_error_code
character(len=256) :: last_error_message
end type
```
---
# 4. `.inp` 解析详细设计
## 4.1 解析范围
第一版解析器支持 CCLite 关键词子集:
```text
*CCLITE CONTROL
*CCLITE SOLVER
*CCLITE IPC
*CCLITE TIME
*CCLITE INTERFACE
*CCLITE SURFACE INTERACTION
*CCLITE CONTACT PAIR
*CCLITE OUTPUT
*END STEP
```
不承诺完整 Abaqus 语法兼容。
## 4.2 关键词行
关键词行格式:
```text
*KEYWORD, PARAM1=VALUE1, PARAM2=VALUE2
```
解析步骤:
1. 去除首尾空白;
2. 跳过空行和 `**` 注释;
3. 若首字符为 `*`,识别新关键词;
4. 逗号分割参数;
5. 将参数名转换为大写;
6. 保存到当前 keyword record;
7. 后续非关键词行作为数据行归属当前关键词。
## 4.3 参数校验
必须检查:
1. 是否存在一个 `*CCLITE CONTROL`;
2. 是否存在 SPH 和 FEM 两个 `*CCLITE SOLVER`;
3. 是否存在 `*CCLITE IPC`;
4. 是否存在 `*CCLITE TIME`;
5. `CONTACT PAIR` 引用的 interface 和 interaction 是否存在;
6. 第一版 `IPC TYPE` 是否为 `WINDOWS_SHMEM`;
7. 路径字段是否非空。
## 4.4 错误策略
解析错误必须包含:
```text
file
line_number
keyword
parameter
message
```
示例:
```text
CCL_ERROR_INPUT_MISSING_PARAM:
line 18, *CCLITE SOLVER missing INPUT
```
---
# 5. IPC 详细设计
## 5.1 C IPC 薄层
C/C++ 薄层只负责 OS 资源,不包含接触算法。
建议导出接口:
```c
void* ccl_ipc_create_block(const char* name, long long bytes);
void* ccl_ipc_open_block(const char* name, long long bytes);
void* ccl_ipc_map_block(void* handle);
int ccl_ipc_unmap_block(void* ptr);
int ccl_ipc_close_block(void* handle);
void* ccl_ipc_create_event(const char* name);
void* ccl_ipc_open_event(const char* name);
int ccl_ipc_wait_event(void* handle, int timeout_ms);
int ccl_ipc_signal_event(void* handle);
int ccl_ipc_reset_event(void* handle);
```
Windows 实现可使用 file mapping object 和 named event。Linux 实现只预留。
## 5.2 Fortran2018 Wrapper
Fortran2018 wrapper 使用 `iso_c_binding`:
```fortran
module ccl_ipc_f2018_mod
use iso_c_binding
implicit none
type CCL_IpcHandle
type(c_ptr) :: raw = c_null_ptr
type(c_ptr) :: mapped = c_null_ptr
integer(c_size_t) :: bytes = 0
end type
contains
subroutine ccl_ipc_map_real64_1d(handle, offset_bytes, n, values)
type(CCL_IpcHandle), intent(in) :: handle
integer(c_size_t), intent(in) :: offset_bytes
integer, intent(in) :: n
real(c_double), pointer, intent(out) :: values(:)
end subroutine
end module
```
Fortran95 算法核心不得直接依赖 `c_ptr`。
## 5.3 Shared Block Header
Header 使用固定字段:
```fortran
type CCL_SharedHeader
integer(ccl_i4) :: magic
integer(ccl_i4) :: version_major
integer(ccl_i4) :: version_minor
integer(ccl_i4) :: block_role
integer(ccl_i4) :: producer_id
integer(ccl_i4) :: consumer_id
integer(ccl_i4) :: step_id
integer(ccl_i4) :: buffer_id
integer(ccl_i4) :: state
integer(ccl_i4) :: item_count
integer(ccl_i4) :: item_stride
integer(ccl_i8) :: payload_bytes
integer(ccl_i4) :: error_code
integer(ccl_i4) :: reserved(16)
end type
```
注意:实际跨 C/Fortran 二进制布局实现时,应由 IPC 层提供 pack/unpack 或使用 `bind(C)` 镜像类型;算法层只读写逻辑字段。
## 5.4 Buffer 状态转换
```text
EMPTY -> WRITING -> READY -> READING -> CONSUMED
\-> ERROR
```
规则:
1. producer 只能写 `EMPTY` 或 `CONSUMED` buffer;
2. consumer 只能读 `READY` buffer;
3. step_id 必须单调递增;
4. 任何一方发现版本、大小、状态非法,应置 `ERROR` 并上报 Controller。
## 5.5 Block Role
第一版 role:
```fortran
integer, parameter :: CCL_BLOCK_SPH_PARTICLE = 101
integer, parameter :: CCL_BLOCK_SPH_FACET = 102
integer, parameter :: CCL_BLOCK_FEM_FACET = 201
integer, parameter :: CCL_BLOCK_TO_SPH_FORCE = 301
integer, parameter :: CCL_BLOCK_TO_FEM_LOAD = 302
integer, parameter :: CCL_BLOCK_DIAGNOSTIC = 900
```
---
# 6. 共享数据布局
## 6.1 SPH Particle Payload
每个 SPH 粒子记录推荐字段:
```text
int external_id
int internal_index
int phase
int status
int material_id
int section_id
real mass
real volume
real density
real pressure
real h
real x(3)
real v(3)
real a(3)
real contact_radius
```
payload 可按 structure-of-arrays 或 array-of-records 实现。第一版推荐 array-of-records,便于调试;后续性能优化可改为 structure-of-arrays,但共享内存 version 必须升级。
## 6.2 FEM Facet Payload
每个 FEM facet 记录推荐字段:
```text
int facet_id
int elem_id
int face_id
int node_count
int node_ids(max_face_nodes)
real x(max_face_nodes,3)
real v(max_face_nodes,3)
real normal(3)
real area
real thickness
```
`max_face_nodes` 第一版可取 4 或 8,必须在 header 或配置中明确。
## 6.3 CCL to SPH Force Payload
```text
int external_id
int export_index
real force(3)
real moment(3)
int contact_state
real normal(3)
real gap
real penetration
```
## 6.4 CCL to FEM Load Payload
```text
int facet_id
int node_count
int node_ids(max_face_nodes)
real node_forces(max_face_nodes,3)
real pressure
real traction(3)
real resultant(3)
```
---
# 7. Controller 状态机
## 7.1 Controller State
```text
CCL_CTRL_CREATED
CCL_CTRL_CASE_LOADED
CCL_CTRL_IPC_READY
CCL_CTRL_SOLVERS_STARTED
CCL_CTRL_SOLVERS_READY
CCL_CTRL_RUNNING
CCL_CTRL_FINALIZING
CCL_CTRL_DONE
CCL_CTRL_FAILED
```
## 7.2 Solver State
```text
SOLVER_CREATED
SOLVER_INITIALIZING
SOLVER_READY
SOLVER_EXPORTING
SOLVER_WAITING_IMPORT
SOLVER_ADVANCING
SOLVER_DONE
SOLVER_FAILED
SOLVER_STOPPED
```
## 7.3 Command Enum
```fortran
integer, parameter :: CCL_CMD_INIT = 1
integer, parameter :: CCL_CMD_READ_INPUT = 2
integer, parameter :: CCL_CMD_BUILD_MODEL = 3
integer, parameter :: CCL_CMD_EXPORT_INTERFACE = 4
integer, parameter :: CCL_CMD_IMPORT_LOADS = 5
integer, parameter :: CCL_CMD_ADVANCE = 6
integer, parameter :: CCL_CMD_WRITE_OUTPUT = 7
integer, parameter :: CCL_CMD_STOP = 99
```
## 7.4 显式同步 Stepper
伪代码:
```fortran
do step = 1, nstep
time = time0 + step * dt
call ccl_controller_command(ctx, SOLVER_SPH, CCL_CMD_EXPORT_INTERFACE, step, ierr)
call ccl_controller_command(ctx, SOLVER_FEM, CCL_CMD_EXPORT_INTERFACE, step, ierr)
call ccl_controller_wait_both(ctx, step, ierr)
call ccl_interface_update_views(ctx, step, ierr)
call ccl_search_build_candidates(ctx, ierr)
call ccl_contact_detect(ctx, ierr)
call ccl_contact_compute_forces(ctx, ierr)
call ccl_transfer_write_buffers(ctx, step, ierr)
call ccl_controller_command(ctx, SOLVER_SPH, CCL_CMD_IMPORT_LOADS, step, ierr)
call ccl_controller_command(ctx, SOLVER_FEM, CCL_CMD_IMPORT_LOADS, step, ierr)
call ccl_controller_wait_both(ctx, step, ierr)
call ccl_controller_advance(ctx, SOLVER_SPH, dt, step, ierr)
call ccl_controller_advance(ctx, SOLVER_FEM, dt, step, ierr)
call ccl_controller_wait_both(ctx, step, ierr)
call ccl_diagnostics_write_step(ctx, step, time, ierr)
end do
```
---
# 8. Interface View 设计
## 8.1 SPHParticleView
```fortran
type CCL_SPHParticleView
integer :: count
integer, pointer :: external_id(:)
integer, pointer :: export_index(:)
integer, pointer :: phase(:)
integer, pointer :: status(:)
real(ccl_r8), pointer :: mass(:)
real(ccl_r8), pointer :: x(:,:)
real(ccl_r8), pointer :: v(:,:)
real(ccl_r8), pointer :: radius(:)
end type
```
维度约定:
```text
x(3, count)
v(3, count)
```
## 8.2 FEMFacetView
```fortran
type CCL_FEMFacetView
integer :: count
integer :: max_face_nodes
integer, pointer :: facet_id(:)
integer, pointer :: node_count(:)
integer, pointer :: node_ids(:,:)
real(ccl_r8), pointer :: x(:,:,:)
real(ccl_r8), pointer :: v(:,:,:)
real(ccl_r8), pointer :: normal(:,:)
real(ccl_r8), pointer :: area(:)
real(ccl_r8), pointer :: thickness(:)
end type
```
维度约定:
```text
node_ids(max_face_nodes, count)
x(3, max_face_nodes, count)
normal(3, count)
```
## 8.3 Force Buffers
SPH force buffer:
```fortran
type CCL_SPHForceBuffer
integer :: count
integer, allocatable :: external_id(:)
integer, allocatable :: export_index(:)
real(ccl_r8), allocatable :: force(:,:)
real(ccl_r8), allocatable :: normal(:,:)
real(ccl_r8), allocatable :: gap(:)
real(ccl_r8), allocatable :: penetration(:)
end type
```
FEM load buffer:
```fortran
type CCL_FEMLoadBuffer
integer :: count
integer :: max_face_nodes
integer, allocatable :: facet_id(:)
integer, allocatable :: node_count(:)
integer, allocatable :: node_ids(:,:)
real(ccl_r8), allocatable :: node_force(:,:,:)
end type
```
---
# 9. 几何与搜索详细设计
## 9.1 Vec3
基础向量过程:
```fortran
ccl_vec3_dot(a, b)
ccl_vec3_cross(a, b, c)
ccl_vec3_norm(a)
ccl_vec3_normalize(a, ierr)
```
## 9.2 AABB
```fortran
type CCL_AABB
real(ccl_r8) :: xmin(3)
real(ccl_r8) :: xmax(3)
end type
```
SPH 粒子 AABB:
```text
x - radius <= point <= x + radius
```
FEM facet AABB:
```text
min/max(facet node coords) expanded by search_distance + shell_thickness/2
```
## 9.3 Hash Grid
第一版使用均匀 hash grid:
1. cell size 取最大搜索距离;
2. FEM facet 插入 grid;
3. 每个 SPH 粒子查询邻近 cell;
4. 生成候选 pair。
## 9.4 最近点计算
必须实现:
1. point-triangle closest point;
2. point-quad closest point,可拆成两个 triangle;
3. point-edge closest point;
4. barycentric 或 shape weight 输出。
## 9.5 Candidate Pair
```fortran
type CCL_ContactCandidate
integer :: sph_index
integer :: fem_facet_index
integer :: candidate_type
end type
```
---
# 10. 接触检测详细设计
## 10.1 ContactPair
```fortran
type CCL_ContactPair
integer :: pair_id
integer :: sph_index
integer :: fem_facet_index
integer :: contact_type
real(ccl_r8) :: closest_point(3)
real(ccl_r8) :: normal(3)
real(ccl_r8) :: gap
real(ccl_r8) :: penetration
real(ccl_r8) :: relative_velocity_normal
real(ccl_r8) :: shape_weight(8)
integer :: node_count
end type
```
## 10.2 SPH 粒子到 FEM 面
流程:
1. 读取 SPH 粒子位置 `xp`、速度 `vp`、半径 `rp`;
2. 读取 FEM facet 节点坐标和速度;
3. 计算 facet 最近点 `xc`;
4. 计算面法向 `n`;
5. 计算 `gap = dot(xp - xc, n)`;
6. 若 FEM 是壳,接触距离 `rc = rp + 0.5 * thickness`;
7. 若 FEM 是实体面,接触距离 `rc = rp`;
8. 若 `gap < rc`,生成接触;
9. `penetration = rc - gap`。
## 10.3 边缘 fallback
当 point-face 最近点落在 facet 外或接近边界时,执行 point-edge 检测:
1. 遍历 facet 边;
2. 计算点到边最近点;
3. 若距离小于接触距离,生成 edge contact;
4. 法向从 edge closest point 指向 SPH 粒子。
## 10.4 壳厚度处理
FEM 壳不得简单视为零厚度面。第一版规则:
```text
effective_distance = sph_radius + 0.5 * shell_thickness
```
壳法向由 FEMLite facet normal 提供,CCLite 不重构复杂壳法向。
---
# 11. 接触力详细设计
## 11.1 法向 penalty force
```text
fn = kn * penetration
```
若 `penetration <= 0`,法向接触力为 0。
## 11.2 阻尼力
```text
fd = cn * max(0, -vn)
```
其中 `vn` 为法向相对速度:
```text
vn = dot(v_sph - v_fem_closest, normal)
```
## 11.3 合力
```text
f_normal = (fn + fd) * normal
```
作用在 SPH 上的力为 `+f_normal` 或 `-f_normal` 取决于法向定义。设计要求:最终输出必须通过 force balance 检查验证作用-反作用。
## 11.4 FEM 节点分配
FEM 侧反力:
```text
f_fem = -f_sph
```
节点力:
```text
f_node_i = N_i * f_fem
```
其中 `N_i` 为最近点处形函数或由三角形 barycentric 权重得到的权重。
## 11.5 Force Balance
每步计算:
```text
sum_f_sph
sum_f_fem
force_error = norm(sum_f_sph + sum_f_fem)
sum_m_sph
sum_m_fem
moment_error = norm(sum_m_sph + sum_m_fem)
```
输出到 `force_balance.csv`。
---
# 12. 传递写回设计
## 12.1 写入 SPH
CCLite 将 SPH 粒子力写入 `CCL_TO_SPH`:
```text
external_id
export_index
force(3)
normal(3)
gap
penetration
contact_state
```
SPHLite 根据 export index 或 external id 将载荷映射回内部粒子。
## 12.2 写入 FEM
CCLite 将 FEM 节点力写入 `CCL_TO_FEM`:
```text
facet_id
node_count
node_ids
node_forces
```
FEMLite 根据 facet/node id 将载荷加入外部 SPH 力缓存。
## 12.3 非有限保护
写回前必须检查:
1. force 是否有限;
2. node force 是否有限;
3. penetration 是否非负;
4. node_count 是否在范围内;
5. facet_id/node_id 是否有效。
发现错误时应停止当前步并上报。
---
# 13. 诊断详细设计
## 13.1 contact_report.csv
字段:
```text
step,time,active_pairs,max_penetration,max_force,
mean_penetration,edge_pair_count,failed_candidate_count
```
## 13.2 force_balance.csv
字段:
```text
step,time,
sph_fx,sph_fy,sph_fz,
fem_fx,fem_fy,fem_fz,
force_error,
sph_mx,sph_my,sph_mz,
fem_mx,fem_my,fem_mz,
moment_error
```
## 13.3 ipc_report.csv
字段:
```text
step,solver,command,state,elapsed_ms,block_role,
buffer_id,payload_bytes,error_code
```
## 13.4 timestep_report.csv
字段:
```text
step,time,dt,sph_state,fem_state,contact_pairs,controller_state
```
## 13.5 日志
`cclite.log` 记录:
1. 输入文件路径;
2. 进程启动参数;
3. IPC 名称;
4. 每个阶段开始/结束;
5. warning 和 error;
6. 最终统计。
---
# 14. 错误码设计
```fortran
integer, parameter :: CCL_OK = 0
integer, parameter :: CCL_ERROR_INPUT_BASE = 1000
integer, parameter :: CCL_ERROR_INPUT_UNKNOWN_KEYWORD = 1001
integer, parameter :: CCL_ERROR_INPUT_MISSING_PARAM = 1002
integer, parameter :: CCL_ERROR_INPUT_BAD_VALUE = 1003
integer, parameter :: CCL_ERROR_IPC_BASE = 2000
integer, parameter :: CCL_ERROR_IPC_CREATE_FAILED = 2001
integer, parameter :: CCL_ERROR_IPC_MAP_FAILED = 2002
integer, parameter :: CCL_ERROR_IPC_TIMEOUT = 2003
integer, parameter :: CCL_ERROR_IPC_BAD_HEADER = 2004
integer, parameter :: CCL_ERROR_IPC_BAD_STATE = 2005
integer, parameter :: CCL_ERROR_SOLVER_BASE = 3000
integer, parameter :: CCL_ERROR_SOLVER_START_FAILED = 3001
integer, parameter :: CCL_ERROR_SOLVER_FAILED = 3002
integer, parameter :: CCL_ERROR_SOLVER_BAD_STEP = 3003
integer, parameter :: CCL_ERROR_CONTACT_BASE = 4000
integer, parameter :: CCL_ERROR_CONTACT_NONFINITE = 4001
integer, parameter :: CCL_ERROR_CONTACT_BAD_GEOM = 4002
integer, parameter :: CCL_ERROR_CONTACT_OVERFLOW = 4003
```
所有错误应写入 `cclite.log`,并在命令行返回非零退出码。
---
# 15. 版本实现路径
## 15.1 CCLite 0.1.x
目标:主控程序、`.inp`、IPC 和空耦合闭环。
任务:
1. Fortran 项目骨架;
2. `cclite_main.f90`;
3. `cclite.inp` 解析器;
4. CCLite Controller 状态机;
5. Windows IPC 薄层;
6. Fortran2018 IPC wrapper;
7. mock solver 测试;
8. SPHLite/FEMLite 进程启动;
9. 空耦合同步推进;
10. `ipc_report.csv`。
验收:
1. `cclite check` 可检查输入;
2. `cclite dry-run` 可启动并停止两个求解器;
3. `cclite run` 可完成空耦合;
4. 通信错误可诊断。
## 15.2 CCLite 0.2.x
目标:显式同步 SPH-FEM 接触。
任务:
1. SPH particle view;
2. FEM facet view;
3. hash grid;
4. point-face/point-edge;
5. penalty damping;
6. SPH/FEM load buffer;
7. force balance;
8. 单粒子撞面验收算例。
## 15.3 CCLite 0.3.x
目标:显式异步子循环。
任务:
1. 子循环 stepper;
2. 宏步/子步映射;
3. 冲量累计;
4. 平均力传递;
5. 子循环诊断。
## 15.4 CCLite 0.4.x
目标:SPH-FEM tied coupling。
任务:
1. InterfaceBond;
2. penalty tie;
3. bond damage;
4. release 后转 contact;
5. tie 诊断。
## 15.5 CCLite 0.5.x
目标:基础 FSI。
任务:
1. SPH pressure projection;
2. FEM motion boundary;
3. boundary/ghost particle;
4. 水下爆炸 FSI 小算例。
## 15.6 CCLite 0.6+
预留:
1. SPH 显式 + FEM 隐式弱耦合;
2. rollback;
3. 强耦合迭代;
4. Aitken 松弛;
5. Riemann FSI;
6. Linux/MPI 后端。
---
# 16. 测试详细设计
## 16.1 单元测试
```text
inp_keyword_parse
inp_case_validate
ipc_header_pack
buffer_state_transition
vec3_ops
closest_point_triangle
closest_point_quad
closest_point_edge
hash_grid_candidates
penalty_contact_force
force_balance
```
## 16.2 集成测试
```text
mock_solver_ipc
controller_two_mock_solvers
empty_coupling_sph_fem
sph_particle_fem_plane_contact
sph_particle_fem_shell_contact
ipc_timeout_error
nonfinite_force_error
```
## 16.3 验收输出检查
每个接触验收算例应检查:
1. `contact_report.csv` 存在且 active pair 数合理;
2. 最大穿透非负且在预期范围;
3. 最大接触力非负且有限;
4. `force_balance.csv` 中 force_error 可接受;
5. `ipc_report.csv` 无 timeout/error;
6. 求解器进程正常停止。
---
# 17. 关键实现注意事项
## 17.1 不把 CCLite 写成 SPH/FEM 内部库
CCLite 第一版是独立主控程序。不得要求 SPHLite 或 FEMLite 直接链接 CCLite 算法核心。
## 17.2 不把 CCLite 写成通用接触库
第一版只处理 SPH-FEM 跨域接触,不处理 FEM 内部接触、SPH 内部接触或任意多体接触。
## 17.3 IPC 层必须薄
Windows API、句柄、事件、共享内存映射只在 IPC 层出现。接触算法只面对 Fortran 数组和 view。
## 17.4 `.inp` 第一版保持小而稳
只实现 `*CCLITE` 关键词子集。后续增加关键词时必须保持旧算例可读。
## 17.5 共享内存必须版本化
任何 payload 布局变化都必须升级 version,并在 check/dry-run 阶段发现不兼容。
---
# 18. 总结
CCLite 详细设计以三独立进程和本机共享内存为核心:CCLite 负责主控与接触算法,SPHLite/FEMLite 负责各自求解。Fortran95 保持算法核心简洁稳定,Fortran2018 与 C/C++ 薄层承担共享内存和 IPC。第一版交付重点是 `.inp` 主控、Windows/gfortran 通信闭环、显式同步 SPH-FEM penalty 接触和完整诊断。