From b52579fcab9b57e9c2ae5e77c1d375106f83ec06 Mon Sep 17 00:00:00 2001 From: shenw Date: Mon, 22 Jun 2026 13:56:08 +0800 Subject: [PATCH] Establish FEM design documentation baselines --- .gitignore | 7 + docs/01_requirements_specification.md | 409 +++++++-- docs/02_software_architecture_design.md | 473 +++++++++-- docs/03_detailed_design.md | 846 ++++++++++++++++--- docs/04_mathematical_model_and_algorithms.md | 769 ++++++++++++++--- docs/05_interface_control_document.md | 569 +++++++++++-- docs/06_test_and_verification_plan.md | 598 +++++++++++-- 7 files changed, 3093 insertions(+), 578 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dc61912 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +# Local Python test environment +Python/.venv/ +Python/venv/ + +# Python cache files +__pycache__/ +*.pyc diff --git a/docs/01_requirements_specification.md b/docs/01_requirements_specification.md index a9c2c0a..ab41708 100644 --- a/docs/01_requirements_specification.md +++ b/docs/01_requirements_specification.md @@ -1,18 +1,19 @@ # FEM Software Requirements Specification -文档状态:草稿 +文档状态:需求基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档用于定义 FEM 软件模块的功能需求、非功能需求、输入输出要求、约束条件和第一阶段开发范围。 +本文档用于定义 FEM 软件模块的功能需求、非功能需求、输入输出要求、约束条件、阶段开发范围和第一版验收标准。 -待补充: +本文档将需求划分为四类: -- 需求来源与适用项目 -- 需求优先级规则 -- 验收准则 +- MUST:第一版必须实现,作为第一阶段验收依据 +- SHOULD:第二版或后续版本应实现,第一版架构需预留扩展能力 +- COULD:可选增强功能,不作为近期验收条件 +- OUT OF SCOPE:当前阶段明确不实现 ## 2. 项目目标 @@ -20,120 +21,344 @@ 目标包括: -- 提供可被外部程序调用的 Fortran95 FEM 核心库 -- 提供基于 Abaqus inp 文件的小型 FEM 分析程序 -- 暴露与 SPH 方法进行边界耦合的接口 -- 支持后续扩展接触、壳单元、实体单元和非线性求解能力 +- MUST:提供可被外部程序调用的 Fortran95 FEM 核心库 +- MUST:提供基于 Abaqus inp 文件的小型 FEM 分析程序 +- MUST:暴露与 SPH 方法进行边界耦合的力学接口 +- MUST:第一版支持显式瞬态动力学分析 +- MUST:第一版支持实体单元 C3D4、C3D8 和基础壳单元 S4 +- SHOULD:第二版支持更完整的壳单元、接触和隐式非线性求解 +- SHOULD:第二版支持 VTK 输出和 restart 能力 ## 3. 应用场景 -待补充: +软件主要服务于以下场景: -- 船体局部板架受爆炸冲击 -- 船体结构与 SPH 流体/爆炸载荷耦合 -- 壳-实体混合模型瞬态响应 -- 弹塑性变形与接触冲击分析 +- MUST:船体局部板架受爆炸冲击载荷作用下的瞬态响应分析 +- MUST:船体结构与 SPH 流体/爆炸载荷程序之间的边界力交换 +- MUST:实体结构模型的线弹性和弹塑性动力响应分析 +- MUST:基础 S4 壳单元参与的板结构动力响应分析 +- SHOULD:壳-实体混合模型瞬态响应分析 +- SHOULD:接触冲击和复杂边界约束分析 +- SHOULD:隐式非线性增量迭代分析 -## 4. 功能需求 +## 4. 阶段范围 -### 4.1 物理模型 +### 4.1 第一版范围 -待补充: +第一版必须完成: -- 线弹性 -- 弹塑性 -- 瞬态动力学 -- 非线性增量迭代 +- 显式瞬态动力学求解 +- C3D4、C3D8、S4 单元 +- 线弹性材料 +- J2 von Mises 弹塑性材料 +- Abaqus inp 文件读取 +- Dirichlet 边界、节点力、面压力 +- SPH 外力接口 +- 日志输出、CSV 历史量输出、基本场变量输出 +- 第一版验收算例 -### 4.2 空间维度 +### 4.2 第二版范围 -软件应支持三维结构有限元分析。 +第二版应完成: -### 4.3 单元类型 - -待补充: - -- 三角形壳单元 -- 四边形壳单元 -- 四面体实体单元 -- 六面体实体单元 -- 线性单元 -- 二次单元 - -### 4.4 材料模型 - -待补充: - -- 各向同性线弹性材料 -- 各向同性 J2 弹塑性材料 -- 密度、弹性参数、屈服参数和硬化参数定义 - -### 4.5 边界条件与载荷 - -待补充: - -- Dirichlet 边界 -- Neumann 边界 +- C3D10、C3D20、S3、S6、S8 单元 - Robin 边界 -- 接触边界 -- 约束方程 -- SPH 边界耦合载荷 +- MPC 约束方程 +- 接触算法 +- 隐式 Newmark + Newton 非线性求解 +- CSR 全局矩阵格式 +- VTK 结果输出 +- restart 能力 -### 4.6 求解类型 +## 5. 功能需求 -待补充: +### 5.1 物理模型 -- 默认显式瞬态动力学 -- 可选隐式瞬态动力学 -- 非线性增量迭代 +软件应支持: -### 4.7 输入输出 +- MUST:三维结构动力学 +- MUST:线弹性 +- MUST:弹塑性 +- MUST:大变形分析框架 +- MUST:小应变 J2 弹塑性作为可选材料更新方式 +- MUST:大应变 J2 弹塑性作为可选材料更新方式 +- MUST:材料失效与单元删除 +- MUST:Johnson-Cook 应变率效应 +- MUST:温度效应 +- SHOULD:隐式非线性增量迭代 -待补充: +说明: -- Abaqus inp 输入子集 -- 日志输出 -- 结果输出 -- 重启动文件 -- 错误诊断信息 +- 第一版默认求解器为显式瞬态动力学。 +- 弹塑性材料应允许用户选择小应变或大应变 J2 形式。 +- 材料失效、单元删除、应变率效应和温度效应属于船舶接触爆炸问题的核心需求,应在第一版需求中保留。 -## 5. 非功能需求 +### 5.2 空间维度 -待补充: +- MUST:支持三维结构有限元分析。 -- Fortran95 兼容性 -- Windows/Linux 平台 -- 编译器兼容性 -- 计算规模目标 -- 内存使用目标 -- 数值稳定性要求 -- 鲁棒性要求 +### 5.3 单元类型 -## 6. 约束与假设 +第一版必须支持: -待补充: +- MUST:C3D4,四节点线性四面体实体单元 +- MUST:C3D8,八节点线性六面体实体单元 +- MUST:S4,四节点线性四边形壳单元 -- 非面向对象 Fortran95 编程 -- 第一阶段不追求完整 Abaqus 兼容 -- 默认采用一致单位制,由用户输入保证 -- 第一阶段优先支持显式动力学 +第二版应支持: -## 7. 开发阶段划分 +- SHOULD:C3D10,十节点二次四面体实体单元 +- SHOULD:C3D20,二十节点二次六面体实体单元 +- SHOULD:S3,三节点线性三角形壳单元 +- SHOULD:S6,六节点二次三角形壳单元 +- SHOULD:S8,八节点二次四边形壳单元 -待补充: +### 5.4 材料模型 -- 原型阶段 -- 核心算法阶段 -- INP 驱动程序阶段 -- SPH 耦合阶段 -- 验证与发布阶段 +第一版必须支持: -## 8. 验收标准 +- MUST:各向同性材料 +- MUST:各向同性线弹性 +- MUST:J2 von Mises 弹塑性 +- MUST:理想弹塑性硬化模型 +- MUST:线性硬化模型 +- MUST:多段塑性曲线硬化模型 +- MUST:Johnson-Cook 流动应力 +- MUST:等效塑性应变阈值失效 +- MUST:Johnson-Cook 损伤失效 +- MUST:材料密度作为必填参数 -待补充: +第二版或后续版本可扩展: -- 支持的输入样例 -- 必须通过的基准算例 -- 接口调用测试 -- 回归测试要求 +- SHOULD:热-力相关材料参数 +- COULD:各向异性材料 +### 5.5 求解器与矩阵格式 + +第一版求解要求: + +- MUST:显式瞬态动力学作为默认求解器 +- MUST:显式求解采用集中质量矩阵 +- MUST:第一版暂不装配全局刚度矩阵 +- MUST:第一版通过单元内力累计形成全局内力向量 +- MUST:dense 矩阵仅用于单元局部矩阵和调试 + +第二版求解要求: + +- SHOULD:隐式 Newmark + Newton 非线性求解 +- SHOULD:CSR 作为隐式求解的主稀疏矩阵格式 +- COULD:skyline 格式作为低优先级调试或小规模验证格式 +- COULD:外部稀疏线性求解器接口 + +### 5.6 边界条件与载荷 + +第一版必须支持: + +- MUST:Dirichlet 边界条件 +- MUST:节点力 +- MUST:面压力 +- MUST:SPH 外力接口 + +第二版应支持: + +- SHOULD:Robin 弹簧/阻尼边界 +- SHOULD:MPC 约束方程 +- SHOULD:接触边界 + +### 5.7 SPH-FEM 耦合接口 + +SPH-FEM 耦合必须满足: + +- MUST:SPH 可向 FEM 传递压力 +- MUST:SPH 可向 FEM 传递剪切力 +- MUST:SPH 可向 FEM 传递等效节点力 +- MUST:FEM 可导出边界 facet +- MUST:边界 facet 可来自实体单元外表面 +- MUST:边界 facet 可来自壳单元表面 +- MUST:边界 facet 可来自指定 elset +- MUST:固体外法向定义为 facet 正法向 +- MUST:压力正方向定义为受压为正 +- MUST:正应力正方向定义为受拉为正 +- MUST:时间步由 SPH 或外部耦合驱动器控制 +- MUST:每个时间步进行 FEM 与 SPH 的双向信息交换 + +一次耦合步的基本流程为: + +```text +FEM 导出边界 facet 坐标、速度、法向和面积 +SPH 根据 FEM 边界状态计算压力、剪切力或节点力 +FEM 接收 SPH 外力并形成外力向量 +FEM 在给定时间步长内显式推进 +FEM 更新边界状态并进入下一耦合步 +``` + +### 5.8 Abaqus INP 输入兼容 + +第一版必须支持以下 Abaqus inp keyword: + +- MUST:*NODE +- MUST:*ELEMENT +- MUST:*NSET +- MUST:*ELSET +- MUST:*MATERIAL +- MUST:*DENSITY +- MUST:*ELASTIC +- MUST:*PLASTIC +- MUST:*SOLID SECTION +- MUST:*SHELL SECTION +- MUST:*BOUNDARY +- MUST:*CLOAD +- MUST:*DLOAD +- MUST:*AMPLITUDE +- MUST:*STEP +- MUST:*DYNAMIC + +集合生成要求: + +- MUST:支持 *NSET, GENERATE +- MUST:支持 *ELSET, GENERATE + +错误处理要求: + +- MUST:不支持的 keyword 默认 warning 后跳过 +- MUST:关键数据缺失时返回 error 并终止当前分析 +- MUST:输入解析日志应记录已识别 keyword、不支持 keyword 和错误位置 + +### 5.9 输出需求 + +第一版必须支持: + +- MUST:日志输出 +- MUST:CSV 历史量输出 +- MUST:节点位移输出 +- MUST:节点速度输出 +- MUST:节点加速度输出 +- MUST:单元应力输出 +- MUST:单元应变输出 +- MUST:单元塑性应变输出 +- MUST:能量历史输出 + +第二版应支持: + +- SHOULD:VTK 结果文件输出 +- SHOULD:restart 文件输出与读取 + +### 5.10 错误诊断 + +软件应诊断并报告: + +- MUST:输入文件不存在或不可读 +- MUST:不支持的单元类型 +- MUST:缺失材料定义 +- MUST:缺失密度 +- MUST:非法材料参数 +- MUST:退化单元或负 Jacobian +- MUST:非法边界自由度 +- MUST:时间步非法 +- MUST:SPH 耦合接口参数非法 + +## 6. 非功能需求 + +### 6.1 语言与编译 + +- MUST:采用 Fortran95 +- MUST:采用非面向对象过程式编程风格 +- MUST:默认支持 gfortran +- MUST:兼容 Intel Fortran +- MUST:采用 CMake 构建系统 + +### 6.2 平台 + +- MUST:支持 Windows +- MUST:支持 Linux + +### 6.3 性能目标 + +第一版性能目标: + +- MUST:目标节点数 10000 +- MUST:目标单元数 10000 +- MUST:目标时间步数 10000 +- MUST:第一版不要求并行 +- MUST:第一版不要求 OpenMP + +后续性能扩展: + +- COULD:OpenMP 并行 +- COULD:更大规模模型 +- COULD:外部高性能稀疏求解器 + +### 6.4 鲁棒性 + +- MUST:不支持 keyword 不应导致程序异常崩溃 +- MUST:关键数据错误应给出明确错误信息 +- MUST:显式时间积分应检查时间步合法性 +- MUST:单元删除后求解流程应保持数组和状态变量一致 + +## 7. 约束与假设 + +- MUST:软件不内置单位转换,输入文件、材料参数和 SPH 耦合数据必须采用一致单位制 +- MUST:第一版不追求完整 Abaqus 兼容,仅支持本文列出的 keyword 子集 +- MUST:第一版以显式动力学为默认分析流程 +- MUST:第一版不装配全局刚度矩阵 +- MUST:所有外部接口以 Fortran95 可表达的数组和标量参数为主 +- SHOULD:后续如需 C/C++/Python 调用,可增加薄包装层 + +## 8. 开发阶段划分 + +### 8.1 第一阶段 + +第一阶段目标是形成可运行的显式动力学 FEM 原型: + +- INP 读取与模型数据库 +- C3D4、C3D8、S4 单元 +- 线弹性与 J2 弹塑性 +- 大变形分析框架 +- 集中质量显式动力学 +- Dirichlet、节点力、面压力 +- SPH 外力接口 +- CSV 与日志输出 +- 第一版验收算例 + +### 8.2 第二阶段 + +第二阶段目标是扩展工程分析能力: + +- 二次实体单元 +- 更多壳单元 +- 接触 +- Robin 和 MPC +- 隐式非线性求解 +- CSR 稀疏矩阵 +- VTK 输出 +- restart + +### 8.3 后续阶段 + +后续可考虑: + +- 并行计算 +- 外部求解器 +- 更丰富材料模型 +- 更完整 Abaqus inp 兼容 +- 后处理工具链 + +## 9. 第一版验收标准 + +第一版必须通过以下验收项: + +- MUST:单元 patch test +- MUST:单轴拉伸 +- MUST:弹塑性加载卸载 +- MUST:弹性波传播 +- MUST:板受压力脉冲 +- MUST:简化 SPH-FEM 边界力传递接口 + +每个验收算例应至少包含: + +- 输入文件 +- 运行命令 +- 参考结果 +- 允许误差 +- 日志检查项 +- 回归测试判据 diff --git a/docs/02_software_architecture_design.md b/docs/02_software_architecture_design.md index 0f62779..24eb7b5 100644 --- a/docs/02_software_architecture_design.md +++ b/docs/02_software_architecture_design.md @@ -1,130 +1,439 @@ # FEM Software Architecture Design -文档状态:草稿 +文档状态:架构基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档描述 FEM 软件的整体架构、模块划分、数据流、控制流、外部接口和扩展策略。 +本文档描述 FEM 软件的整体架构、交付形态、目录组织、模块划分、数据流、控制流、外部接口、错误处理和扩展策略。 + +本文档中的架构决策用于约束后续详细设计、算法设计、接口设计和代码实现。 ## 2. 架构目标 -待补充: +软件架构应满足: -- 核心库与小型主程序分离 -- 显式动力学优先 -- 保留隐式非线性扩展路径 -- 支持 Abaqus inp 输入 -- 支持 SPH-FEM 边界耦合 -- 采用 Fortran95 过程式模块组织 +- 核心库与命令行程序分离 +- 第一版优先支持显式瞬态动力学 +- 第一版支持独立 FEM 程序运行和外部 SPH 驱动两种模式 +- 第一版支持 Abaqus inp 输入 +- 第一版支持 SPH-FEM 边界力交换接口 +- Fortran95 过程式模块组织,不采用面向对象类型绑定 +- 集中式数据库管理网格、材料、状态变量和全局向量 +- 单元、材料、求解器、耦合和输出模块保持职责分离 +- 第二版预留壳单元扩展、接触、隐式非线性和 CSR 稀疏矩阵能力 -## 3. 总体分层 +## 3. 交付形态 -建议分层: +第一版交付: -- 输入层:Abaqus inp 读取与模型构造 -- 核心 FEM 层:网格、材料、单元、边界、接触、耦合 -- 求解层:显式动力学、隐式非线性、稀疏矩阵与外部求解器接口 -- 输出层:日志、结果文件、诊断信息、重启动数据 +- 静态库:libFemLite +- 命令行程序:femlite +- 测试程序:单元测试、模块测试和集成测试可执行文件 +- 示例算例:examples 目录中的 Abaqus inp 输入文件和参考输出 +- 文档:docs 目录中的需求、架构、详细设计、算法、接口和测试文档 -待讨论: +第二版或后续版本可扩展: -- 是否需要独立 preprocessing 层 -- 是否需要独立 restart 层 -- 输出格式优先级 +- 动态库 +- C/C++/Python 包装层 +- 更完整后处理工具链 +- 外部求解器适配层 -## 4. 模块划分 +## 4. 目录结构 -初步模块: +建议目录结构: -- fem_precision.f90 -- fem_control.f90 -- fem_database.f90 -- fem_inp_reader.f90 -- fem_shape_solid.f90 -- fem_shape_shell.f90 -- fem_quadrature.f90 -- fem_material_iso.f90 -- fem_element_solid.f90 -- fem_element_shell.f90 -- fem_assembly.f90 -- fem_boundary.f90 -- fem_constraint.f90 -- fem_contact.f90 -- fem_sph_coupling.f90 -- fem_solver_explicit.f90 -- fem_solver_implicit.f90 -- fem_sparse_csr.f90 -- fem_program.f90 +```text +src/base 基础类型、常量、日志、错误码、控制参数 +src/input Abaqus inp 读取与输入数据预处理 +src/mesh 网格、集合、facet、自由度编号 +src/material 材料模型与状态变量更新 +src/element 实体单元、壳单元、形函数、积分规则 +src/solver 显式求解器、隐式求解器预留、稀疏矩阵预留 +src/boundary 边界条件、载荷、约束、接触预留 +src/coupling FEM 外部耦合接口和 SPH 力映射 +src/output 日志、CSV、VTK 预留、restart 预留 +src/app femlite 命令行程序 +tests 测试程序与测试数据 +examples 示例 inp 文件与参考结果 +docs 工程文档 +``` -待补充: +目录职责边界: -- 每个模块的职责边界 -- 模块依赖关系 -- 禁止出现的循环依赖 +- input 层只负责解析输入,不直接执行求解。 +- material 层只负责本构更新,不直接访问全局网格。 +- element 层负责单元级质量、内力、应力更新和稳定步长估计。 +- solver 层负责时间推进和全局向量更新,不直接依赖 SPH 实现。 +- coupling 层只负责数据交换和力映射,FEM 核心不依赖 SPH 程序。 +- output 层统一处理日志、历史量和结果输出。 -## 5. 核心数据流 +## 5. 总体分层 -待补充: +软件采用以下分层: + +```text +Application Layer + femlite command line program + test programs + examples + +Public API Layer + fem_initialize + fem_read_inp + fem_build_model + fem_advance_explicit + fem_get_boundary_facets + fem_apply_sph_forces + fem_finalize + +Core FEM Layer + mesh database + dof numbering + material update + element routines + boundary and load routines + coupling force mapping + +Solver Layer + explicit central difference solver + implicit solver placeholder + CSR matrix placeholder + +Input/Output Layer + Abaqus inp reader + log writer + CSV writer + VTK placeholder + restart placeholder +``` + +## 6. 数据库架构 + +软件采用集中式 fem_database 模块。 + +架构约定: + +- 网格、材料、截面、集合、自由度、状态变量和全局向量由 fem_database 统一保存。 +- 允许模块共享 fem_database 中的全局 allocatable 数组。 +- 各模块通过明确的初始化、查询和更新子程序访问数据库。 +- 不使用面向对象类型绑定。 +- 材料例程不直接访问全局数据库。 +- 单元例程可读取单元连接、坐标、材料编号和状态变量索引。 +- 求解器例程负责全局向量清零、累计、边界条件施加和时间推进。 + +核心数据库类别: + +- 节点坐标 +- 单元连接关系 +- 单元类型 +- 节点集和单元集 +- 材料参数 +- 截面参数 +- 自由度编号 +- 位移、速度、加速度 +- 集中质量 +- 内力、外力、接触力、SPH 力 +- 高斯点应力、应变、塑性应变和历史变量 +- 单元删除标志 + +## 7. 自由度架构 + +每个节点预留 6 个自由度: + +```text +1 UX +2 UY +3 UZ +4 RX +5 RY +6 RZ +``` + +自由度规则: + +- 实体单元只激活 UX、UY、UZ。 +- 壳单元激活 UX、UY、UZ、RX、RY、RZ。 +- 未激活自由度编号为 0。 +- 全局自由度编号由 mesh/dof 模块统一生成。 +- Dirichlet 边界、节点力、输出和 SPH 接口均使用同一自由度约定。 +- 后续 MPC、接触和壳-实体连接沿用同一自由度体系。 + +## 8. 大变形架构 + +第一版默认采用 Updated Lagrangian 架构。 + +基本约定: + +- 当前构形用于计算单元几何、Jacobian、体积、面积和法向。 +- 单元内力基于当前构形上的应力状态累计。 +- 小应变 J2 和大应变 J2 通过材料更新选项切换。 +- 大变形相关运动学量由单元模块计算并传递给材料模块。 +- 材料模块只接收材料更新所需的局部变量和旧状态,返回新应力、状态变量和可选切线。 +- 壳单元第一版可采用有限转动能力受限的 S4 实现,第二版再扩展更完整壳大变形框架。 + +## 9. 材料与状态变量架构 + +状态变量存储按 element + integration point 组织。 + +职责划分: + +- fem_database 保存所有高斯点状态变量。 +- element 模块负责从数据库取出旧状态并调用材料模块。 +- material 模块负责应力更新和状态变量更新。 +- element 模块负责把新状态写回数据库。 +- solver 模块负责控制何时提交或回滚状态变量。 + +材料例程接口原则: + +- 输入应包含材料编号、应变增量或变形度量、应变率、温度、时间步长和旧状态。 +- 输出应包含新应力、新状态变量、失效标志和可选算法切线。 +- 材料例程不得依赖全局节点、单元或求解器状态。 + +## 10. 单元调度架构 + +Fortran95 下直接使用 Abaqus 单元类型字符串作为内部主标识。 + +支持的单元类型字符串: + +```text +C3D4 +C3D8 +S4 +C3D10 +C3D20 +S3 +S6 +S8 +``` + +调度原则: + +- elem_type 使用固定长度字符串保存,例如 character(len=16)。 +- INP 读取时将单元类型转换为大写并去除多余空格。 +- element_driver 根据 elem_type 字符串调用具体单元例程。 +- 具体单元例程只处理本单元的质量、内力、应力更新、稳定时间步和面载荷。 +- 新增单元时扩展 elem_type 字符串识别和对应单元例程。 +- 第一版必须实现 C3D4、C3D8、S4。 +- 第二版应实现 C3D10、C3D20、S3、S6、S8。 +- 后续如需性能优化,可增加内部缓存编码,但 Abaqus 字符串仍作为数据库主字段。 + +## 11. 核心数据流 + +独立程序模式数据流: ```text Abaqus inp -> inp reader -> mesh/material/section/boundary database -> dof numbering + -> facet construction -> mass initialization - -> time integration loop + -> explicit time integration loop -> element stress/internal force update - -> boundary/contact/SPH force update - -> result output + -> boundary and load update + -> output ``` -## 6. 求解控制流 +外部 SPH 驱动模式数据流: -待补充: +```text +external driver + -> fem_initialize + -> fem_read_inp / fem_build_model + -> fem_get_boundary_facets + -> external SPH force calculation + -> fem_apply_sph_forces + -> fem_advance_explicit(dt) + -> fem_get_boundary_facets + -> repeat +``` -- 显式中心差分控制流 -- 隐式 Newmark + Newton 控制流 -- 非线性状态变量更新时机 -- 输出与重启动时机 +## 12. 求解控制流 -## 7. SPH-FEM 耦合架构 +第一版显式中心差分控制流: -待补充: +```text +initialize model +compute lumped mass +initialize displacement, velocity and acceleration +for each time step: + clear force vectors + apply prescribed loads + receive SPH forces when running in coupling mode + compute element stress and internal force + apply boundary conditions + compute acceleration from lumped mass + update velocity + update displacement + update current configuration + delete failed elements when required + write output when required +end for +``` -- FEM 边界 facet 导出 -- 边界坐标、速度、法向、面积交换 -- SPH 压力/剪切/节点力导入 -- 时间步同步策略 -- 错误码和耦合状态管理 +第二版隐式控制流预留: -## 8. 错误处理与日志 +```text +initialize model +build CSR sparsity +for each increment: + predict displacement and velocity + Newton iteration: + assemble residual + assemble tangent matrix + apply boundary and constraint equations + solve correction + update trial state + check convergence + commit state + write output +end for +``` -待补充: +求解控制权: -- 错误级别 -- 错误码范围 -- 日志格式 -- 不支持 keyword 的处理策略 +- 独立程序模式由 femlite 控制时间循环。 +- 外部 SPH 驱动模式由外部驱动器控制时间步长和调用顺序。 +- SPH 耦合时,solver 只接收 fsph 全局力向量。 +- solver 不直接调用 SPH 程序或依赖 SPH 数据结构。 -## 9. 扩展策略 +## 13. SPH-FEM 耦合架构 -待补充: +coupling 层职责: -- 添加新单元 -- 添加新材料 -- 添加新边界条件 -- 添加新输入 keyword -- 接入外部线性求解器 +- 构造和维护 FEM 边界 facet 列表。 +- 导出 facet 坐标、速度、法向和面积。 +- 接收压力、剪切力或等效节点力。 +- 将外部耦合载荷映射为 FEM 全局 fsph 向量。 +- 检查 coupling 接口参数合法性。 -## 10. 构建与部署架构 +边界 facet 来源: -待补充: +- 实体单元外表面 +- 壳单元表面 +- 指定 elset -- 静态库 +耦合约束: + +- FEM 核心不依赖具体 SPH 程序。 +- coupling 层不执行 SPH 粒子计算。 +- element 层不直接依赖 SPH。 +- solver 层只使用已经映射好的 fsph。 +- 每个时间步可执行一次双向交换。 +- 时间步由 SPH 或外部耦合驱动器控制。 + +## 14. 输出架构 + +第一版输出: + +- 日志文件:运行信息、warning、error、关键统计量 +- CSV 历史量:时间、能量、最大位移、最大速度、外力功等 +- CSV 场变量:节点位移、速度、加速度,单元应力、应变、塑性应变 + +第二版输出: + +- VTK 结果文件 +- restart 文件 + +输出控制: + +- 输出频率由 fem_control 统一管理。 +- 输出模块不参与求解状态更新。 +- 第一版不建立复杂后处理数据库。 + +## 15. 错误处理与日志 + +错误处理原则: + +- 所有核心接口返回 ierr。 +- 日志模块记录 warning、error 和 fatal 信息。 +- 不支持的 Abaqus keyword 作为 warning 后跳过。 +- 关键数据缺失、非法材料参数、退化单元等错误应终止当前分析。 +- 外部接口不得通过未捕获异常或直接停止进程隐藏错误来源。 + +错误码分组: + +```text +0 success +1000 input errors +2000 mesh and dof errors +3000 material and state errors +4000 solver errors +5000 coupling errors +6000 output errors +9000 internal errors +``` + +日志至少记录: + +- 输入文件名 +- 识别和跳过的 keyword +- 节点数、单元数、自由度数 +- 材料和截面数量 +- 时间步设置 +- 输出设置 +- warning 和 error 位置 +- 分析开始和结束状态 + +## 16. 扩展策略 + +添加新单元: + +- 增加 elem_type 字符串识别 +- 增加形函数和积分规则 +- 增加质量、内力、应力更新和面载荷例程 +- 增加单元测试和 patch test + +添加新材料: + +- 增加材料类型编码 +- 增加材料参数解析 +- 增加材料更新例程 +- 增加单轴或多轴材料测试 + +添加新边界条件: + +- 增加输入解析 +- 增加数据库存储 +- 增加载荷或约束施加例程 +- 增加验证算例 + +添加新输入 keyword: + +- 增加 keyword 识别 +- 增加参数解析 +- 增加错误诊断 +- 增加输入回归测试 + +接入外部线性求解器: + +- 通过 CSR 层提供矩阵和向量接口 +- 隐式求解器不得直接绑定具体第三方库 +- 外部库适配应单独放在 solver 或 external 子层 + +## 17. 构建与部署架构 + +构建系统: + +- 使用 CMake。 +- 默认编译器为 gfortran。 +- 兼容 Intel Fortran。 +- 支持 Windows 和 Linux。 + +构建目标: + +- FemLite 静态库 +- femlite 命令行程序 +- 单元测试程序 +- 模块测试程序 +- 集成测试程序 + +第一版不要求: + +- OpenMP +- MPI - 动态库 -- 小型命令行程序 -- 测试程序 -- 示例算例目录 - +- 外部求解器强依赖 diff --git a/docs/03_detailed_design.md b/docs/03_detailed_design.md index 9326a62..3a0ba2e 100644 --- a/docs/03_detailed_design.md +++ b/docs/03_detailed_design.md @@ -1,88 +1,467 @@ # FEM Detailed Design -文档状态:草稿 +文档状态:详细设计基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档给出各 Fortran95 模块的数据结构、子程序接口、调用顺序和实现细节,用于直接指导编码。 +本文档给出各 Fortran95 模块的数据结构、数组维度、子程序接口、调用顺序和实现约定,用于直接指导编码。 + +本文档承接需求规格说明书和软件架构设计说明书。 ## 2. 设计原则 -待补充: +代码实现应遵循: -- 过程式 Fortran95 -- 模块化组织 -- 全局数据库集中管理 -- 单元例程局部化 -- 求解器与单元实现解耦 -- 输入解析与计算核心解耦 +- 采用 Fortran95 过程式模块设计。 +- 模块名与文件名保持一致。 +- 使用集中式 fem_database 管理全局数据。 +- 允许模块共享 fem_database 中的全局 allocatable 数组。 +- 分量维度放在数组第一维,实体数量放在第二维。 +- 所有核心子程序通过 ierr 返回状态。 +- 核心库子程序不直接 stop,主程序根据 ierr 决定是否退出。 +- 输入解析、数据库构建、单元计算、材料更新、求解器、耦合和输出保持解耦。 -## 3. 全局精度与常量模块 +## 3. 文件与模块组织 + +第一版建议文件结构: + +```text +src/base/fem_precision.f90 +src/base/fem_error.f90 +src/base/fem_log.f90 +src/base/fem_control.f90 +src/mesh/fem_database.f90 +src/input/fem_inp_reader.f90 +src/input/fem_inp_keywords.f90 +src/material/fem_material_iso.f90 +src/material/fem_material_j2.f90 +src/element/fem_quadrature.f90 +src/element/fem_shape_solid.f90 +src/element/fem_shape_shell.f90 +src/element/fem_element_solid.f90 +src/element/fem_element_shell.f90 +src/element/fem_element_driver.f90 +src/boundary/fem_boundary.f90 +src/coupling/fem_sph_coupling.f90 +src/solver/fem_solver_explicit.f90 +src/solver/fem_sparse_csr.f90 +src/output/fem_output_csv.f90 +src/app/fem_program.f90 +``` + +第二版可增加: + +```text +src/boundary/fem_constraint.f90 +src/boundary/fem_contact.f90 +src/solver/fem_solver_implicit.f90 +src/output/fem_output_vtk.f90 +src/output/fem_restart.f90 +``` + +## 4. 全局精度与常量模块 模块:fem_precision.f90 -待补充: +职责: -- real kind 定义 -- integer kind 定义 -- 常用常量 -- 容差参数 +- 定义实数精度。 +- 定义常用整数常量。 +- 定义数组固定维度常量。 -## 4. 控制参数模块 +建议常量: + +```fortran +integer, parameter :: rk = selected_real_kind(12, 100) +integer, parameter :: ik = selected_int_kind(9) + +integer, parameter :: NDIM = 3 +integer, parameter :: NDOF_NODE = 6 +integer, parameter :: NSTRESS = 6 +integer, parameter :: MAX_NEN = 20 +integer, parameter :: MAX_FACE_NODES = 8 +integer, parameter :: NAME_LEN = 80 +integer, parameter :: ELEM_TYPE_LEN = 16 +integer, parameter :: MAT_MODEL_LEN = 32 +integer, parameter :: NSTATEV_MAX = 32 +``` + +应力、应变分量顺序: + +```text +1 XX / 11 +2 YY / 22 +3 ZZ / 33 +4 XY / 12 +5 XZ / 13 +6 YZ / 23 +``` + +剪切约定: + +- 应变数组中第 4、5、6 分量采用工程剪切应变 gamma12、gamma13、gamma23。 +- 应力数组中第 4、5、6 分量采用真实剪切应力 tau12、tau13、tau23。 +- 材料模块内部如需张量剪切应变,应在材料例程内部显式转换。 + +## 5. 错误与日志模块 + +模块: + +- fem_error.f90 +- fem_log.f90 + +错误码分组: + +```text +0 success +1000 input errors +2000 mesh and dof errors +3000 material and state errors +4000 solver errors +5000 coupling errors +6000 output errors +9000 internal errors +``` + +核心接口约定: + +```fortran +subroutine some_core_routine(..., ierr) + integer, intent(out) :: ierr +end subroutine +``` + +日志模块至少提供: + +```fortran +subroutine log_info(message) +subroutine log_warning(message) +subroutine log_error(message) +``` + +## 6. 控制参数模块 模块:fem_control.f90 -待补充: +职责: -- 时间步控制 -- 求解器类型 -- 输出控制 -- 非线性迭代控制 -- 接触控制 -- SPH 耦合控制 +- 保存分析控制参数。 +- 保存输出控制参数。 +- 保存材料和求解器选项。 +- 保存 SPH 耦合运行模式。 -## 5. 数据库模块 +第一版关键变量: + +```fortran +real(rk) :: time_start +real(rk) :: time_end +real(rk) :: dt_user +real(rk) :: dt_stable +integer :: nstep_max +integer :: output_interval +logical :: use_sph_coupling +logical :: use_user_dt +logical :: large_deformation +``` + +显式求解默认: + +- large_deformation = .true. +- use_user_dt 由输入文件或外部驱动器决定。 +- SPH 耦合模式下 dt 由外部驱动器传入。 + +## 7. 数据库模块 模块:fem_database.f90 -待补充: +职责: -- 节点数组 -- 单元数组 -- 自由度编号 -- 材料表 -- 截面表 -- 边界条件表 -- 状态变量表 -- 全局向量 +- 统一保存网格、材料、截面、集合、自由度、状态变量和全局向量。 +- 提供 allocate/deallocate/init 子程序。 +- 不承担具体单元、材料和求解算法。 -初步自由度约定: +### 7.1 网格数组 -```text -1 UX -2 UY -3 UZ -4 RX -5 RY -6 RZ +数组维度采用 Fortran 列主序友好形式: + +```fortran +integer :: nnode +integer :: nelem +integer :: ndof +integer :: ngauss_total + +real(rk), allocatable :: coord0(:,:) ! coord0(3,nnode) +real(rk), allocatable :: coord(:,:) ! coord(3,nnode) +integer, allocatable :: elem_conn(:,:) ! elem_conn(MAX_NEN,nelem) +integer, allocatable :: elem_nnode(:) ! elem_nnode(nelem) +character(len=ELEM_TYPE_LEN), allocatable :: elem_type(:) +integer, allocatable :: elem_mat(:) ! elem_mat(nelem) +integer, allocatable :: elem_sec(:) ! elem_sec(nelem) +integer, allocatable :: elem_status(:) ! elem_status(nelem) ``` -## 6. INP 读取模块 +单元类型直接使用 Abaqus 字符串: -模块:fem_inp_reader.f90 +```text +C3D4 +C3D8 +C3D10 +C3D20 +S3 +S4 +S6 +S8 +``` -待补充: +实现约定: -- 支持 keyword -- 不支持 keyword 处理 -- 集合解析 -- 材料解析 -- step 解析 -- 错误恢复策略 +- INP 读取时将单元类型转换为大写并去除多余空格。 +- 内部不使用整数单元类型编码作为主标识。 +- 单元调度通过字符串比较或统一的字符串选择例程完成。 +- 后续如需性能优化,可增加内部缓存编码,但 Abaqus 字符串仍作为数据库主字段。 -## 7. 形函数与积分模块 +单元状态建议: + +```text +0 active +1 deleted +2 inactive by input +``` + +### 7.2 自由度数组 + +每节点预留 6 个自由度: + +```fortran +integer, allocatable :: dof_id(:,:) ! dof_id(6,nnode) +``` + +规则: + +- dof_id(1:3,node) 对应 UX、UY、UZ。 +- dof_id(4:6,node) 对应 RX、RY、RZ。 +- 实体单元只激活 1:3。 +- 壳单元激活 1:6。 +- 未激活自由度编号为 0。 + +### 7.3 全局向量 + +显式动力学第一版使用: + +```fortran +real(rk), allocatable :: u(:) ! u(ndof) +real(rk), allocatable :: v(:) ! v(ndof), output velocity +real(rk), allocatable :: a(:) ! a(ndof) +real(rk), allocatable :: vhalf(:) ! vhalf(ndof) +real(rk), allocatable :: mass_diag(:) ! mass_diag(ndof) + +real(rk), allocatable :: fint(:) ! fint(ndof) +real(rk), allocatable :: fext(:) ! fext(ndof) +real(rk), allocatable :: fsph(:) ! fsph(ndof) +real(rk), allocatable :: fcontact(:) ! fcontact(ndof), second version +``` + +速度约定: + +- 显式求解内部保存半步速度 vhalf。 +- 输出速度 v 可由相邻半步速度重建。 +- v 数组保存用于输出和外部接口的整步速度估计。 + +### 7.4 高斯点与状态变量 + +```fortran +integer, allocatable :: elem_gp_start(:) ! elem_gp_start(nelem) +integer, allocatable :: elem_ngp(:) ! elem_ngp(nelem) + +real(rk), allocatable :: stress(:,:) ! stress(6,ngauss_total) +real(rk), allocatable :: strain(:,:) ! strain(6,ngauss_total) +real(rk), allocatable :: statev(:,:) ! statev(NSTATEV_MAX,ngauss_total) +``` + +固定 statev 布局: + +```text +1 eqps, equivalent plastic strain +2 damage +3 temperature +4 fail_flag, 0 active material point, 1 failed material point +5 plastic strain XX +6 plastic strain YY +7 plastic strain ZZ +8 plastic strain XY, engineering shear component +9 plastic strain XZ, engineering shear component +10 plastic strain YZ, engineering shear component +11 Fp11 +12 Fp12 +13 Fp13 +14 Fp21 +15 Fp22 +16 Fp23 +17 Fp31 +18 Fp32 +19 Fp33 +20 eqps_rate +21 current_yield_stress +22 plastic_multiplier +23 internal_energy_density +24 reserved for temperature history +25-32 reserved +``` + +约定: + +- 小应变 J2 使用 1、2、3、4、5:10、20、21、22。 +- 大应变 J2 使用 1、2、3、4、11:19、20、21、22。 +- 未使用槽位置零。 +- 材料失效后设置 statev(4,gp)=1。 +- 单元删除由 elem_status 标记,不通过释放内存实现。 + +## 8. INP 读取模块 + +模块: + +- fem_inp_reader.f90 +- fem_inp_keywords.f90 + +职责: + +- 读取 Abaqus inp 文件。 +- 解析第一版支持的 keyword。 +- 构造数据库所需的原始数据。 +- 对不支持 keyword 记录 warning。 +- 对关键数据缺失返回 error。 + +第一版 keyword: + +```text +*NODE +*ELEMENT +*NSET +*ELSET +*MATERIAL +*DENSITY +*ELASTIC +*PLASTIC +*SOLID SECTION +*SHELL SECTION +*BOUNDARY +*CLOAD +*DLOAD +*AMPLITUDE +*STEP +*DYNAMIC +``` + +集合要求: + +- 支持 *NSET, GENERATE。 +- 支持 *ELSET, GENERATE。 +- 集合名统一转大写保存。 + +建议接口: + +```fortran +subroutine inp_read_file(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr +end subroutine +``` + +## 9. 集合数据结构 + +节点集和单元集采用压缩连续存储。 + +```fortran +integer :: n_nset +integer :: n_elset + +character(len=NAME_LEN), allocatable :: nset_name(:) +integer, allocatable :: nset_start(:) +integer, allocatable :: nset_count(:) +integer, allocatable :: nset_items(:) + +character(len=NAME_LEN), allocatable :: elset_name(:) +integer, allocatable :: elset_start(:) +integer, allocatable :: elset_count(:) +integer, allocatable :: elset_items(:) +``` + +规则: + +- set_start 指向 set_items 中的起始位置。 +- set_count 表示集合元素数。 +- 集合项保持输入编号,数据库构建时再映射为内部编号。 + +## 10. 材料模块 + +模块: + +- fem_material_iso.f90 +- fem_material_j2.f90 + +材料控制建议采用分解模型选项: + +```fortran +character(len=MAT_MODEL_LEN), allocatable :: mat_elastic_model(:) +character(len=MAT_MODEL_LEN), allocatable :: mat_plastic_model(:) +character(len=MAT_MODEL_LEN), allocatable :: mat_rate_model(:) +character(len=MAT_MODEL_LEN), allocatable :: mat_temp_model(:) +character(len=MAT_MODEL_LEN), allocatable :: mat_failure_model(:) +``` + +第一版材料选项: + +```text +elastic model: ISO_LINEAR +plastic model: NONE / J2_SMALL / J2_FINITE +hardening: IDEAL / LINEAR / TABULAR +rate model: NONE / JOHNSON_COOK +temperature model: NONE / JOHNSON_COOK +failure model: NONE / EQPS_LIMIT / JOHNSON_COOK +``` + +材料参数至少包含: + +```fortran +real(rk), allocatable :: mat_density(:) +real(rk), allocatable :: mat_e(:) +real(rk), allocatable :: mat_nu(:) +real(rk), allocatable :: mat_yield0(:) +real(rk), allocatable :: mat_hardening_modulus(:) +``` + +材料更新接口建议: + +```fortran +subroutine material_update_3d(mat_id, dt, strain_inc, defgrad, & + strain_rate, temperature, state_old, & + stress_old, stress_new, state_new, & + failed, ierr) + integer, intent(in) :: mat_id + real(rk), intent(in) :: dt + real(rk), intent(in) :: strain_inc(6) + real(rk), intent(in) :: defgrad(3,3) + real(rk), intent(in) :: strain_rate + real(rk), intent(in) :: temperature + real(rk), intent(in) :: state_old(NSTATEV_MAX) + real(rk), intent(in) :: stress_old(6) + real(rk), intent(out) :: stress_new(6) + real(rk), intent(out) :: state_new(NSTATEV_MAX) + logical, intent(out) :: failed + integer, intent(out) :: ierr +end subroutine +``` + +材料模块约束: + +- 不直接访问全局节点和单元数组。 +- 不执行单元删除,只返回 failed 标志。 +- 不施加边界条件。 +- 不写输出文件。 + +## 11. 形函数与积分模块 模块: @@ -90,119 +469,332 @@ - fem_shape_shell.f90 - fem_quadrature.f90 -待补充: +接口建议: -- 单元自然坐标 -- 形函数接口 -- 导数接口 -- Jacobian 计算 -- 积分点与权重 +```fortran +subroutine shape_solid(elem_type, xi, nnode, n, dndxi, ierr) + character(len=*), intent(in) :: elem_type + real(rk), intent(in) :: xi(3) + integer, intent(out) :: nnode + real(rk), intent(out) :: n(MAX_NEN) + real(rk), intent(out) :: dndxi(3,MAX_NEN) + integer, intent(out) :: ierr +end subroutine +``` -## 8. 材料模块 +```fortran +subroutine quadrature_rule(elem_type, ngauss, xi, weight, ierr) + character(len=*), intent(in) :: elem_type + integer, intent(out) :: ngauss + real(rk), intent(out) :: xi(3,*) + real(rk), intent(out) :: weight(*) + integer, intent(out) :: ierr +end subroutine +``` -模块:fem_material_iso.f90 +第一版支持: -待补充: +- C3D4 +- C3D8 +- S4 -- 线弹性更新 -- J2 弹塑性返回映射 -- 状态变量定义 -- 一致切线或算法切线 -- 波速估计 - -## 9. 实体单元模块 +## 12. 实体单元模块 模块:fem_element_solid.f90 -待补充: +职责: -- 单元质量 -- 单元内力 -- 单元刚度 -- 应力更新 -- 稳定时间步估计 -- C3D4/C3D10/C3D8/C3D20 支持计划 +- 计算 C3D4、C3D8 集中质量。 +- 计算单元内力。 +- 更新高斯点应力和状态变量。 +- 估算稳定时间步。 +- 处理材料点失效并向单元删除逻辑报告。 -## 10. 壳单元模块 +接口建议: + +```fortran +subroutine solid_lumped_mass(elem, ierr) + integer, intent(in) :: elem + integer, intent(out) :: ierr +end subroutine + +subroutine solid_internal_force(elem, dt, ierr) + integer, intent(in) :: elem + real(rk), intent(in) :: dt + integer, intent(out) :: ierr +end subroutine + +subroutine solid_stable_dt(elem, dtcrit, ierr) + integer, intent(in) :: elem + real(rk), intent(out) :: dtcrit + integer, intent(out) :: ierr +end subroutine +``` + +单元删除策略: + +- 删除后的单元在内存中保留且可访问。 +- 删除通过 elem_status(elem)=1 标记。 +- 删除单元不再贡献内力。 +- 删除单元不再接受面压力和 SPH facet 外载。 +- 删除单元的质量不从全局 mass_diag 中移除。 +- 删除单元不触发自由度重编号。 +- 输出中应保留删除状态。 + +## 13. 壳单元模块 模块:fem_element_shell.f90 -待补充: +第一版支持 S4。 -- 壳截面 -- 膜应变 -- 弯曲应变 -- 横向剪切 -- 厚度积分 -- 剪切锁死处理 -- hourglass 控制 +职责: -## 11. 边界、约束与接触模块 +- 计算 S4 集中质量。 +- 计算 S4 内力。 +- 支持 S4 面压力。 +- 支持 S4 输出应力、应变和塑性应变。 -模块: +第一版约束: -- fem_boundary.f90 -- fem_constraint.f90 -- fem_contact.f90 +- S4 作为可计算单元纳入第一版。 +- 壳大变形和有限转动能力在第一版中保持受限实现。 +- 更完整壳理论、hourglass 控制和二次壳单元在第二版完善。 -待补充: +## 14. 边界与载荷模块 -- Dirichlet 处理 -- Neumann 处理 -- Robin 处理 -- MPC 处理 -- penalty 接触 -- 接触搜索接口 +模块:fem_boundary.f90 -## 12. SPH 耦合模块 +第一版数据结构: + +```fortran +integer :: nbc +integer, allocatable :: bc_node(:) +integer, allocatable :: bc_dof(:) +real(rk), allocatable :: bc_value(:) +integer, allocatable :: bc_amp(:) + +integer :: ncload +integer, allocatable :: cload_node(:) +integer, allocatable :: cload_dof(:) +real(rk), allocatable :: cload_value(:) +integer, allocatable :: cload_amp(:) + +integer :: ndload +integer, allocatable :: dload_elem(:) +integer, allocatable :: dload_face(:) +real(rk), allocatable :: dload_value(:) +integer, allocatable :: dload_amp(:) +``` + +接口建议: + +```fortran +subroutine boundary_apply_dirichlet(time, ierr) +subroutine boundary_apply_cload(time, ierr) +subroutine boundary_apply_dload(time, ierr) +``` + +约定: + +- Dirichlet 支持位移约束。 +- 节点力写入 fext。 +- 面压力转换为等效节点力后写入 fext。 +- amplitude 编号为 0 时表示常值。 + +## 15. SPH 耦合模块 模块:fem_sph_coupling.f90 -待补充: +facet 数据结构: -- 边界 facet 数据结构 -- FEM 状态导出接口 -- SPH 载荷导入接口 -- 节点力映射 -- 时间同步约定 +```fortran +integer :: nfacet +integer, allocatable :: facet_elem(:) +integer, allocatable :: facet_face(:) +integer, allocatable :: facet_nnode(:) +integer, allocatable :: facet_conn(:,:) ! facet_conn(MAX_FACE_NODES,nfacet) +real(rk), allocatable :: facet_center(:,:) ! facet_center(3,nfacet) +real(rk), allocatable :: facet_area(:) +real(rk), allocatable :: facet_normal(:,:) ! facet_normal(3,nfacet) +``` -## 13. 求解器模块 +导出数据应包含: -模块: +- facet 编号 +- facet 所属单元和面号 +- facet 节点连接 +- facet 中心坐标 +- facet 节点坐标 +- facet 节点速度 +- facet 外法向 +- facet 面积 + +接口建议: + +```fortran +subroutine coupling_build_facets(ierr) +subroutine fem_get_boundary_facets(nfacet_out, conn, x, vnod, normal, area, ierr) +subroutine fem_apply_sph_nodal_forces(nnode_in, node_id, force, ierr) +subroutine fem_apply_sph_facet_tractions(nfacet_in, facet_id, pressure, shear, ierr) +``` + +约定: + +- coupling 层只做数据交换和力映射。 +- FEM 不依赖 SPH 程序。 +- solver 只接收已经映射完成的 fsph。 +- 删除单元不再作为有效 SPH facet 来源。 + +## 16. 求解器模块 + +模块:fem_solver_explicit.f90 + +核心接口: + +```fortran +subroutine fem_initialize(ierr) +subroutine fem_read_inp(filename, ierr) +subroutine fem_build_model(ierr) +subroutine fem_compute_lumped_mass(ierr) +subroutine fem_estimate_stable_dt(dtcrit, ierr) +subroutine fem_advance_explicit(dt, ierr) +subroutine fem_write_output(step, time, ierr) +subroutine fem_finalize(ierr) +``` + +显式单步流程: + +```text +clear fint, fext, fsph if required +apply prescribed loads +receive or keep SPH forces depending on coupling mode +loop over active elements and compute internal force +apply Dirichlet constraints +compute acceleration from lumped mass +update vhalf +update displacement u +reconstruct output velocity v +update current coordinates coord = coord0 + displacement +mark failed elements as deleted +write output if requested +``` + +第二版模块: -- fem_solver_explicit.f90 - fem_solver_implicit.f90 +- fem_sparse_csr.f90 -待补充: +第一版只保留接口占位,不要求装配全局刚度矩阵。 -- 显式初始化 -- 显式单步推进 -- 稳定时间步估计 -- 隐式残差组装 -- Newton 迭代 -- 收敛准则 - -## 14. 稀疏矩阵模块 +## 17. 稀疏矩阵模块 模块:fem_sparse_csr.f90 -待补充: +第二版主用 CSR。 -- CSR 存储 -- 稀疏结构构造 -- 装配接口 -- 矩阵向量乘 -- 外部求解器接口 +第一版状态: -## 15. 主程序模块 +- 可提供空接口或最小数据结构。 +- dense 仅用于单元局部矩阵和调试。 +- skyline 非第一优先级。 + +## 18. 输出模块 + +模块:fem_output_csv.f90 + +第一版 CSV 文件组织: + +```text +history.csv +nodes_step_xxxxx.csv +elements_step_xxxxx.csv +``` + +history.csv 至少包含: + +- step +- time +- kinetic_energy +- internal_energy +- external_work +- max_displacement +- max_velocity +- deleted_element_count + +nodes_step_xxxxx.csv 至少包含: + +- node_id +- x +- y +- z +- ux +- uy +- uz +- vx +- vy +- vz +- ax +- ay +- az + +elements_step_xxxxx.csv 至少包含: + +- elem_id +- elem_type +- elem_status +- stress components +- strain components +- plastic strain components +- eqps +- damage + +第二版增加: + +- VTK 输出 +- restart 输出与读取 + +## 19. 主程序模块 模块:fem_program.f90 -待补充: +命令行程序 femlite 第一版流程: -- 命令行参数 -- inp 文件读取 -- 求解流程 -- 输出流程 -- 返回码 +```text +parse command line +fem_initialize +fem_read_inp +fem_build_model +fem_compute_lumped_mass +time loop: + fem_estimate_stable_dt if needed + fem_advance_explicit + fem_write_output +fem_finalize +return exit code +``` + +命令行建议: + +```text +femlite input.inp +femlite input.inp --dt 1.0e-8 --time 1.0e-4 --output-interval 10 +``` + +## 20. 内存分配与释放 + +内存策略: + +- 读取 inp 后确定模型规模。 +- 根据节点数、单元数、集合大小、边界条件数量和高斯点总数 allocate。 +- 所有 allocate 失败必须返回 ierr。 +- fem_finalize 统一 deallocate。 +- 单元删除不释放单元、状态变量或自由度内存。 + +核心接口: + +```fortran +subroutine database_allocate(ierr) +subroutine database_initialize(ierr) +subroutine database_finalize(ierr) +``` diff --git a/docs/04_mathematical_model_and_algorithms.md b/docs/04_mathematical_model_and_algorithms.md index 4e2c1de..b02a8dd 100644 --- a/docs/04_mathematical_model_and_algorithms.md +++ b/docs/04_mathematical_model_and_algorithms.md @@ -1,160 +1,711 @@ # FEM Mathematical Model and Algorithms -文档状态:草稿 +文档状态:算法基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档说明软件采用的控制方程、有限元离散、材料算法、时间积分、接触算法和 SPH-FEM 耦合算法。 +本文档说明软件采用的控制方程、空间离散、时间积分、材料算法、失效删除、载荷映射、SPH-FEM 耦合和数值稳定性算法。 -## 2. 控制方程 +本文档用于约束后续 Fortran95 实现和验证算例设计。 -待补充: +## 2. 算法范围 -- 动量守恒方程 -- 初始条件 -- 位移边界 -- 力边界 -- 接触边界 -- SPH 耦合边界 +第一版必须支持: -离散后基本方程: +- 显式瞬态动力学。 +- Updated Lagrangian 大变形框架。 +- C3D4、C3D8、S4 单元。 +- Cauchy 应力。 +- Jaumann 客观应力率。 +- 小应变 J2 弹塑性。 +- 大变形 hypoelastic-plastic J2 弹塑性。 +- Johnson-Cook 流动应力。 +- 等效塑性应变阈值失效。 +- Johnson-Cook 损伤失效。 +- 单元删除。 +- 初始温度和绝热塑性温升。 +- 可选线性和二次 bulk viscosity。 +- SPH 压力、剪切力和节点力映射。 + +第二版应补充: + +- 基于 F = Fe Fp 的有限应变塑性。 +- Rayleigh 阻尼。 +- 接触算法。 +- 隐式 Newmark + Newton 非线性算法。 +- C3D10、C3D20、S3、S6、S8。 +- 更完整的壳 hourglass 控制。 + +## 3. 符号与约定 + +节点自由度: ```text -M a + C v + F_int(u, state) = F_ext + F_contact + F_sph +1 UX +2 UY +3 UZ +4 RX +5 RY +6 RZ ``` -## 3. 弱式形式 +应力、应变分量顺序: -待补充: +```text +1 XX / 11 +2 YY / 22 +3 ZZ / 33 +4 XY / 12 +5 XZ / 13 +6 YZ / 23 +``` -- 虚功原理 -- 内力项 -- 外力项 -- 惯性项 -- 阻尼项 -- 接触和耦合边界贡献 +剪切约定: -## 4. 空间离散 +- 应变向量采用工程剪切应变 gamma12、gamma13、gamma23。 +- 应力向量采用真实剪切应力 tau12、tau13、tau23。 +- 材料内部如需张量剪切应变,应显式执行 gamma_ij / 2 转换。 -待补充: +压力符号: -- 位移插值 -- 应变-位移矩阵 -- 实体单元离散 -- 壳单元离散 -- 节点自由度定义 +```text +t = -p n +``` -## 5. 质量矩阵与阻尼 +其中 n 为固体外法向,p > 0 表示受压,t 为作用在 FEM 边界上的面力向量。正应力仍采用受拉为正。 -待补充: +## 4. 控制方程 -- 一致质量矩阵 -- 集中质量矩阵 -- Rayleigh 阻尼 -- 边界阻尼 -- 显式动力学质量处理 +连续体动量方程: -## 6. 显式中心差分算法 +```text +div(sigma) + b = rho a +``` -待补充: +边界分解: -- 速度半步更新 -- 位移整步更新 -- 加速度计算 -- 边界条件施加 -- 稳定时间步限制 +```text +u = ubar on Gamma_u +t = tbar on Gamma_t +t = -p n + tau_s on Gamma_sph +``` -## 7. 隐式 Newmark 算法 +半离散有限元方程: -待补充: +```text +M a + C v + F_int(u, state) = F_ext + F_sph + F_contact +``` -- Newmark 参数 -- 有效刚度 -- 有效残差 -- Newton-Raphson 迭代 -- 收敛准则 +第一版不实现接触,故实际显式残差为: -## 8. 实体单元算法 +```text +F_res = F_ext + F_sph - F_int - F_damp +``` -待补充: +## 5. 弱式形式 -- C3D4 -- C3D10 -- C3D8 -- C3D20 -- 形函数 -- 数值积分 -- Jacobian -- 内力和刚度 +虚功形式: -## 9. 壳单元算法 +```text +Integral_Omega delta_epsilon : sigma dV ++ Integral_Omega rho delta_u . a dV += Integral_Omega delta_u . b dV ++ Integral_Gamma_t delta_u . tbar dA ++ Integral_Gamma_sph delta_u . t_sph dA +``` -待补充: +有限元离散后: -- Reissner-Mindlin 壳理论 -- 三角形壳 -- 四边形壳 -- 膜应变 -- 弯曲应变 -- 横向剪切 -- 厚度积分 -- 锁死控制 +```text +F_int = Integral_Omega B^T sigma dV +F_ext = Integral_Omega N^T b dV + Integral_Gamma_t N^T tbar dA +F_sph = Integral_Gamma_sph N^T t_sph dA +``` -## 10. 材料算法 +Updated Lagrangian 第一版约定: -待补充: +- 当前构形用于计算体积、面积、法向和几何导数。 +- 内力在当前构形中使用 Cauchy 应力积分。 +- 单元节点坐标由 coord = coord0 + u 更新。 +- 单元删除后不再贡献内力和边界面力。 -- 各向同性线弹性 -- J2 屈服函数 -- 关联流动法则 -- 各向同性硬化 -- 径向返回映射 -- 状态变量更新 -- 算法切线 +## 6. 空间离散 -## 11. 接触算法 +位移插值: -待补充: +```text +u(x,t) = Sum_i N_i(x) u_i(t) +``` -- penalty 接触 -- 接触法向 -- 穿透量计算 -- 接触力计算 -- 接触阻尼 -- 时间步限制 +实体单元应变率离散: -## 12. SPH-FEM 耦合算法 +```text +D = sym(grad(v)) +``` -待补充: +小应变模式中使用增量工程应变: -- 边界 facet 构造 -- FEM 边界运动学量导出 -- SPH 压力映射 -- 剪切力映射 -- 节点等效力积分 -- 显式时间同步 +```text +Delta_epsilon = B Delta_u +``` -## 13. 稳定性与误差控制 +大变形模式中使用当前构形速度梯度: -待补充: +```text +L = grad_current(v) +D = 0.5 * (L + L^T) +W = 0.5 * (L - L^T) +``` -- 临界时间步 -- 材料波速 -- 单元特征长度 -- 退化单元检测 -- 能量平衡检查 +第一版实体单元: -## 14. 数值验证算例 +- C3D4:四节点线性四面体,一点积分。 +- C3D8:八节点线性六面体,2x2x2 全积分。 +- 第一版暂不支持 C3D8R 减缩积分。 -待补充: +第一版壳单元: -- patch test -- 单轴拉伸 -- 悬臂梁 -- 自由振动 -- 弹性波传播 -- 板受冲击 -- SPH-FEM 耦合压力传递 +- S4:四节点 Mindlin-Reissner 壳。 +- 膜/弯曲项采用 2x2 面内积分。 +- 横向剪切项采用选择性减缩积分。 +- 剪切修正系数采用 5/6。 +- 第一版 S4 大转动和 hourglass 控制能力有限,第二版完善。 + +## 7. 质量矩阵与阻尼 + +第一版采用集中质量矩阵。 + +实体单元质量: + +```text +m_e = rho V_e +``` + +C3D4 和 C3D8 平动质量按节点均分: + +```text +m_i += m_e / nnode +``` + +S4 壳单元质量: + +```text +m_e = rho A_e h +``` + +S4 平动质量按节点均分。转动惯量第一版采用简化对角近似: + +```text +I_i += rho A_e h^3 / (12 nnode) +``` + +阻尼策略: + +- 第一版默认无 Rayleigh 阻尼。 +- 第一版支持可选线性和二次 bulk viscosity。 +- 第二版实现 Rayleigh 阻尼。 + +bulk viscosity 可写为等效附加压力: + +```text +q = rho (c1 c Lc div(v) + c2 Lc^2 div(v)^2) +``` + +仅在压缩状态 div(v) < 0 时启用。 + +## 8. 显式中心差分算法 + +第一版默认使用中心差分: + +```text +a_n = M^-1 F_res_n +v_(n+1/2) = v_(n-1/2) + dt a_n +u_(n+1) = u_n + dt v_(n+1/2) +``` + +整步速度用于输出和外部接口: + +```text +v_n = 0.5 * (v_(n-1/2) + v_(n+1/2)) +``` + +单步流程: + +```text +clear force vectors +apply CLOAD and DLOAD +receive or keep SPH forces +compute element stress update and internal force +apply optional bulk viscosity +apply Dirichlet constraints +compute acceleration +update half-step velocity +update displacement +reconstruct output velocity +update current coordinates +evaluate material failure and element deletion +write output when requested +``` + +Dirichlet 约束处理: + +- 对约束自由度直接覆盖 u、v、vhalf 和 a。 +- 对固定自由度,速度和加速度置零。 +- 对给定位移历史,按 amplitude 更新约束值。 + +## 9. 稳定时间步 + +显式稳定步长采用单元临界步长估计: + +```text +dt_e = Lc / cd +dt = safety * min(dt_e) +``` + +默认安全系数: + +```text +safety = 0.8 +``` + +弹性波速: + +```text +cd = sqrt((lambda + 2 mu) / rho) +``` + +其中: + +```text +mu = E / (2(1 + nu)) +lambda = E nu / ((1 + nu)(1 - 2 nu)) +``` + +第一版约定: + +- 弹塑性、应变率和温度影响下仍使用弹性波速进行保守估计。 +- 删除单元不参与后续稳定步长估计。 +- 若用户指定 dt,仍应检查 dt > 0 并在日志中报告 dt / dtcrit。 + +## 10. 实体单元算法 + +### 10.1 C3D4 + +C3D4 使用一点积分: + +```text +F_int_e = V B^T sigma +``` + +特征长度可由体积和最大面面积估计: + +```text +Lc = 3 V / Amax +``` + +失效删除默认规则: + +```text +ANY_FAILED_GP +``` + +即任一积分点失效则删除单元。 + +### 10.2 C3D8 + +C3D8 使用 2x2x2 全积分: + +```text +F_int_e = Sum_gp B_gp^T sigma_gp detJ_gp w_gp +``` + +第一版不支持 C3D8R。 + +失效删除默认规则: + +```text +FRACTION_FAILED_GP, fraction = 0.5 +``` + +即失效积分点比例达到 0.5 时删除单元。 + +## 11. 壳单元算法 + +第一版 S4 采用 Mindlin-Reissner 壳。 + +壳应变包括: + +```text +epsilon_membrane +kappa_bending +gamma_transverse_shear +``` + +壳厚度方向应变近似: + +```text +epsilon(z) = epsilon_membrane + z kappa_bending +``` + +横向剪切能: + +```text +U_shear = Integral kappa_s G h gamma_s^T gamma_s dA +``` + +其中剪切修正系数: + +```text +kappa_s = 5 / 6 +``` + +积分策略: + +- 膜项:2x2。 +- 弯曲项:2x2。 +- 横向剪切项:选择性减缩积分。 + +第一版限制: + +- S4 可用于板受压力脉冲等基础动力响应。 +- S4 大转动能力有限。 +- hourglass 控制第二版完善。 +- S3、S6、S8 第二版实现。 + +S4 删除默认规则: + +```text +FRACTION_FAILED_GP, fraction = 0.5 +``` + +## 12. 材料算法 + +### 12.1 各向同性线弹性 + +小应变弹性: + +```text +sigma = C epsilon +``` + +弹性矩阵由 E 和 nu 定义。 + +大变形 hypoelastic 模式中采用应力率形式: + +```text +objective_rate(sigma) = C : D +``` + +第一版客观率采用 Jaumann rate: + +```text +sigma_dot_J = sigma_dot - W sigma + sigma W +``` + +### 12.2 小应变 J2 弹塑性 + +小应变 J2 采用: + +- von Mises 屈服函数。 +- 关联流动法则。 +- 径向返回映射。 +- 各向同性硬化。 + +屈服函数: + +```text +f = sigma_eq - sigma_y(eqps, epdot, T) +``` + +等效应力: + +```text +sigma_eq = sqrt(3/2 s:s) +``` + +试应力: + +```text +sigma_trial = sigma_n + C Delta_epsilon +``` + +若 f_trial <= 0,执行弹性更新。若 f_trial > 0,执行径向返回并更新: + +```text +Delta_gamma +eqps_(n+1) = eqps_n + Delta_eqps +plastic_strain_(n+1) +sigma_(n+1) +``` + +硬化模型: + +- 理想弹塑性。 +- 线性硬化。 +- 多段塑性曲线。 + +### 12.3 大变形 J2 弹塑性 + +第一版大变形 J2 采用: + +```text +hypoelastic-plastic J2 + Jaumann objective rate +``` + +算法变量: + +```text +L = grad_current(v) +D = sym(L) +W = skew(L) +``` + +应力更新采用 Cauchy 应力和 Jaumann 客观率。塑性修正仍采用 J2 偏应力返回思想。 + +第二版应补充: + +```text +F = Fe Fp +``` + +形式的有限应变塑性,并使用塑性变形梯度 Fp 作为状态变量。 + +### 12.4 Johnson-Cook 流动应力 + +第一版支持 Johnson-Cook 流动应力: + +```text +sigma_y = (A + B eqps^n) + * (1 + C ln(epdot / epdot0)) + * (1 - Tstar^m) +``` + +温度归一化: + +```text +Tstar = (T - Troom) / (Tmelt - Troom) +``` + +约定: + +- epdot <= epdot0 时应对对数项做下限保护。 +- Tstar 限制在 [0, 1]。 +- 温度达到熔点附近时材料强度可降至零或触发失效,具体由材料参数控制。 + +### 12.5 温度效应 + +第一版支持: + +- 初始温度。 +- 绝热塑性温升。 +- 外部温度接口预留。 + +第一版不做热传导。 + +绝热塑性温升: + +```text +Delta_T = chi sigma_eq Delta_eqps / (rho cp) +``` + +其中 chi 为 Taylor-Quinney 系数,cp 为比热。 + +### 12.6 材料失效 + +第一版支持两类失效: + +等效塑性应变阈值失效: + +```text +failed if eqps >= eqps_fail +``` + +Johnson-Cook 损伤失效: + +```text +D_damage = Sum(Delta_eqps / eps_f) +failed if D_damage >= 1 +``` + +断裂应变: + +```text +eps_f = (D1 + D2 exp(D3 sigma_star)) + * (1 + D4 ln(epdot / epdot0)) + * (1 + D5 Tstar) +``` + +其中 sigma_star 为应力三轴度相关变量。 + +## 13. 单元删除算法 + +材料点失效后设置对应高斯点 fail_flag。 + +单元删除规则: + +```text +delete_rule = ANY_FAILED_GP +delete_rule = FRACTION_FAILED_GP +``` + +默认规则: + +- C3D4:ANY_FAILED_GP。 +- C3D8:FRACTION_FAILED_GP,fraction = 0.5。 +- S4:FRACTION_FAILED_GP,fraction = 0.5。 + +删除单元处理: + +- 单元在内存中保留且可访问。 +- elem_status 标记为 deleted。 +- 删除单元不再贡献内力。 +- 删除单元不再接受面压力或 SPH facet 外载。 +- 删除单元质量保留在 mass_diag 中。 +- 删除单元不触发自由度重编号。 +- 输出中必须记录删除状态。 + +## 14. 压力、面力与 SPH 映射 + +压力面力: + +```text +t = -p n +``` + +等效节点力: + +```text +f_i += Integral_face N_i t dA +``` + +SPH facet 牵引: + +```text +t_sph = -p n + tau_s +``` + +其中 tau_s 为 SPH 传入的剪切牵引向量。 + +SPH 节点力输入: + +```text +f_sph(dof(node,1:3)) += force(1:3,node) +``` + +耦合步骤: + +```text +FEM exports boundary facet coordinates, velocities, normals and areas +SPH computes pressure, shear traction or nodal force +FEM maps received loads to fsph +FEM advances one explicit step +FEM updates current boundary state +``` + +## 15. 能量计算 + +第一版输出能量历史: + +- kinetic energy +- internal energy +- external work +- SPH work +- deleted element count + +第二版预留: + +- hourglass energy +- contact work +- damping energy + +动能: + +```text +E_kin = 0.5 Sum_i m_i v_i^2 +``` + +内能增量: + +```text +Delta_E_int = Sum_gp sigma : Delta_epsilon volume_gp +``` + +外力功可用梯形近似: + +```text +Delta_W_ext = 0.5 (F_ext_n + F_ext_(n+1)) . Delta_u +``` + +SPH 功按 fsph 单独累计。 + +## 16. 隐式算法预留 + +第二版隐式算法采用 Newmark + Newton。 + +预留方程: + +```text +R(u) = F_ext - F_int(u,state) - M a - C v +K_eff Delta_u = R +``` + +第一版不装配全局刚度矩阵,不要求算法切线用于求解。 + +## 17. 接触算法预留 + +第二版实现接触。 + +预留方向: + +- penalty 接触。 +- 接触搜索。 +- 接触法向与穿透量。 +- 接触阻尼。 +- 接触功输出。 + +第一版不实现接触,只保留 fcontact 向量和接口位置。 + +## 18. 稳定性与误差控制 + +第一版必须检查: + +- dt > 0。 +- dt / dtcrit。 +- 负 Jacobian。 +- 退化单元。 +- 非法材料参数。 +- 缺失密度。 +- 删除单元比例。 +- 能量历史异常增长。 + +建议日志输出: + +- 最小稳定时间步。 +- 控制时间步的单元编号。 +- 最大位移。 +- 最大速度。 +- 最大等效塑性应变。 +- 删除单元数量。 + +## 19. 数值验证算例 + +第一版验收算例: + +- 单元 patch test。 +- 单轴拉伸。 +- 弹塑性加载卸载。 +- 弹性波传播。 +- 板受压力脉冲。 +- 简化 SPH-FEM 边界力传递接口。 + +算法专项验证: + +- 小应变 J2 单点返回映射。 +- 大变形 Jaumann 客观率刚体转动测试。 +- Johnson-Cook 应变率敏感单点测试。 +- 绝热温升单点测试。 +- 单元删除规则测试。 +- 压力符号测试。 diff --git a/docs/05_interface_control_document.md b/docs/05_interface_control_document.md index 218d588..adc7225 100644 --- a/docs/05_interface_control_document.md +++ b/docs/05_interface_control_document.md @@ -1,144 +1,561 @@ # FEM Interface Control Document -文档状态:草稿 +文档状态:接口基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档定义 FEM 核心库对外暴露的调用接口、数据交换约定、错误码、单位制和 SPH-FEM 耦合接口。 +本文档定义 FEM 核心库对外暴露的调用接口、数组维度、编号规则、内存所有权、错误码、单位制和 SPH-FEM 耦合接口。 -## 2. 接口设计原则 +本文档是外部程序,特别是 SPH 程序,与 FemLite 进行联调时的接口合同。 -待补充: +## 2. 接口范围 -- Fortran95 数组接口 -- 不依赖面向对象特性 -- 调用者不直接访问内部数据库 -- 通过错误码返回状态 -- 一致单位制由调用者保证 +第一版提供: -## 3. 库生命周期接口 +- Fortran95 原生接口。 +- 显式瞬态动力学推进接口。 +- Abaqus inp 模型读取接口。 +- 外部 SPH 驱动接口。 +- 节点力、facet 压力、facet 压力加剪切力接口。 +- 节点运动学和单元平均结果查询接口。 +- CSV 输出控制接口。 -待补充: +第二版提供: + +- C ABI 包装层。 +- Python 调试接口。 +- 高斯点结果查询接口。 +- VTK 和 restart 相关接口。 + +## 3. 接口设计原则 + +接口设计遵循: + +- 第一版只承诺 Fortran95 原生接口。 +- 不依赖 Fortran 2003 `iso_c_binding`。 +- 不依赖面向对象类型绑定。 +- 调用者不直接访问 FEM 内部数据库。 +- 外部数组采用调用者分配。 +- 查询类接口采用两步查询模式。 +- 所有核心接口通过 ierr 返回错误状态。 +- warning 只写入日志,不作为 ierr 返回。 +- FEM 不做单位转换,调用者必须保证单位一致。 + +## 4. 编号与维度约定 + +### 4.1 编号约定 + +外部接口默认使用 Abaqus 原始编号: + +- node_id 为 Abaqus 输入文件中的节点编号。 +- elem_id 为 Abaqus 输入文件中的单元编号。 +- facet_id 为 FEM 构造并导出的稳定 facet 编号。 + +内部可维护连续编号,并提供原始编号和内部编号之间的查询接口。 + +建议接口: + +```fortran +subroutine fem_get_internal_node_id(node_id_ext, node_id_int, ierr) +subroutine fem_get_internal_elem_id(elem_id_ext, elem_id_int, ierr) +subroutine fem_get_external_node_id(node_id_int, node_id_ext, ierr) +subroutine fem_get_external_elem_id(elem_id_int, elem_id_ext, ierr) +``` + +### 4.2 自由度约定 + +自由度编号: + +```text +1 UX +2 UY +3 UZ +4 RX +5 RY +6 RZ +``` + +节点力接口: + +- `force(3,nnode)` 只作用于平动自由度 UX、UY、UZ。 +- 通用自由度接口使用 `node_id + dof + value`。 + +### 4.3 数组维度约定 + +接口数组采用 Fortran 列主序友好的维度: + +```fortran +coord(3,nnode) +velocity(3,nnode) +acceleration(3,nnode) +normal(3,nfacet) +force(3,nnode) +shear(3,nfacet) +conn(max_face_nodes,nfacet) +x(3,max_face_nodes,nfacet) +vnod(3,max_face_nodes,nfacet) +``` + +所有数组下标从 1 开始。 + +## 5. 字符串约定 + +文件名: + +```fortran +character(len=*), intent(in) :: filename +``` + +内部固定长度: + +```text +NAME_LEN = 80 +ELEM_TYPE_LEN = 16 +``` + +对外返回名称时,由调用者提供固定长度字符数组。 + +## 6. 内存所有权 + +第一版采用调用者分配数组的模式。 + +查询类接口采用两步流程: + +```text +1. 调用 fem_get_xxx_size 查询数量和最大维度 +2. 调用者 allocate 所需数组 +3. 调用 fem_get_xxx_data 填充数组 +``` + +FEM 内部不返回由库内 allocate 的外部数组指针。 + +## 7. 库生命周期接口 + +标准生命周期: ```fortran subroutine fem_initialize(ierr) + integer, intent(out) :: ierr +end subroutine + subroutine fem_finalize(ierr) + integer, intent(out) :: ierr +end subroutine ``` -## 4. 模型输入接口 +调用规则: -待补充: +- `fem_initialize` 必须在其他接口之前调用。 +- `fem_finalize` 负责释放 FEM 内部内存。 +- 多次重复初始化和释放应返回明确错误或在日志中记录状态。 + +## 8. 模型输入与构建接口 ```fortran subroutine fem_read_inp(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr +end subroutine + subroutine fem_build_model(ierr) + integer, intent(out) :: ierr +end subroutine + +subroutine fem_compute_lumped_mass(ierr) + integer, intent(out) :: ierr +end subroutine ``` -待讨论: +推荐调用顺序: -- filename 字符串长度约定 -- 多 step inp 文件处理方式 -- 不支持 keyword 的返回策略 +```text +fem_initialize +fem_read_inp +fem_build_model +fem_compute_lumped_mass +``` -## 5. 求解控制接口 +说明: -待补充: +- `fem_read_inp` 只负责读取和解析输入。 +- `fem_build_model` 负责内部编号、自由度、facet 和状态变量数据库构建。 +- `fem_compute_lumped_mass` 负责形成显式动力学所需集中质量。 + +## 9. 求解控制接口 ```fortran -subroutine fem_set_time_step(dt, ierr) subroutine fem_estimate_stable_dt(dtcrit, ierr) + real(rk), intent(out) :: dtcrit + integer, intent(out) :: ierr +end subroutine + subroutine fem_advance_explicit(dt, ierr) -subroutine fem_solve_current_step(ierr) + real(rk), intent(in) :: dt + integer, intent(out) :: ierr +end subroutine + +subroutine fem_get_current_time(time, step, ierr) + real(rk), intent(out) :: time + integer, intent(out) :: step + integer, intent(out) :: ierr +end subroutine ``` -## 6. 结果查询接口 +独立程序模式: -待补充: +- `femlite` 读取 inp 后控制时间循环。 +- 输出由 `femlite` 按控制参数调用。 + +外部 SPH 驱动模式: + +```text +fem_get_boundary_facets +external SPH calculation +fem_clear_sph_forces +fem_apply_sph_xxx +fem_advance_explicit(dt) +``` + +在 SPH 驱动模式下,时间步长由外部程序传入。 + +## 10. 载荷接口 + +### 10.1 外力清零 ```fortran -subroutine fem_get_nodal_displacement(nnode, node_id, disp, ierr) -subroutine fem_get_nodal_velocity(nnode, node_id, vel, ierr) -subroutine fem_get_nodal_acceleration(nnode, node_id, acc, ierr) -subroutine fem_get_element_stress(nelem, elem_id, stress, ierr) +subroutine fem_clear_external_forces(ierr) + integer, intent(out) :: ierr +end subroutine + +subroutine fem_clear_sph_forces(ierr) + integer, intent(out) :: ierr +end subroutine ``` -## 7. 载荷施加接口 +SPH 耦合规则: -待补充: +- 外部程序每个时间步显式调用 `fem_clear_sph_forces`。 +- 然后调用 SPH 载荷施加接口。 +- 最后调用 `fem_advance_explicit(dt)`。 +- `fem_advance_explicit` 不应自动清除刚传入的 `fsph`。 + +### 10.2 节点力 ```fortran -subroutine fem_clear_external_force(ierr) -subroutine fem_apply_nodal_force(nnode, node_id, force, ierr) -subroutine fem_apply_pressure(nface, face_id, pressure, ierr) +subroutine fem_apply_nodal_force(nnode_in, node_id, force, ierr) + integer, intent(in) :: nnode_in + integer, intent(in) :: node_id(nnode_in) + real(rk), intent(in) :: force(3,nnode_in) + integer, intent(out) :: ierr +end subroutine ``` -## 8. SPH-FEM 耦合接口 +说明: -待补充: +- `node_id` 使用 Abaqus 原始节点编号。 +- `force` 使用全局坐标。 +- 只作用于平动自由度。 + +### 10.3 通用自由度载荷 ```fortran -subroutine fem_get_boundary_facets(nfacet, conn, x, v, normal, area, ierr) -subroutine fem_apply_sph_nodal_forces(nnode, node_id, force, ierr) -subroutine fem_apply_sph_facet_tractions(nfacet, facet_id, pressure, shear, ierr) +subroutine fem_apply_dof_force(nitem, node_id, dof, value, ierr) + integer, intent(in) :: nitem + integer, intent(in) :: node_id(nitem) + integer, intent(in) :: dof(nitem) + real(rk), intent(in) :: value(nitem) + integer, intent(out) :: ierr +end subroutine ``` -待讨论: +说明: -- facet 编号稳定性 -- 法向方向约定 -- 压力正负号约定 -- 剪切力坐标系约定 -- FEM 与 SPH 时间步同步方式 +- `dof` 采用 1 到 6 的自由度编号。 +- 非激活自由度应返回错误。 -## 9. 边界条件接口 +## 11. SPH-FEM 耦合接口 -待补充: +### 11.1 facet 数量查询 ```fortran -subroutine fem_apply_prescribed_displacement(nnode, node_id, dof, value, ierr) -subroutine fem_apply_prescribed_velocity(nnode, node_id, dof, value, ierr) -subroutine fem_apply_robin_boundary(nnode, node_id, dof, stiffness, damping, ierr) +subroutine fem_get_boundary_facet_count(nfacet, max_face_nodes, ierr) + integer, intent(out) :: nfacet + integer, intent(out) :: max_face_nodes + integer, intent(out) :: ierr +end subroutine ``` -## 10. 错误码定义 +### 11.2 facet 数据查询 -待补充: +```fortran +subroutine fem_get_boundary_facets(nfacet_in, max_face_nodes_in, & + facet_id, elem_id, face_id, facet_nnode, & + facet_conn, x, vnod, normal, area, ierr) + integer, intent(in) :: nfacet_in + integer, intent(in) :: max_face_nodes_in + integer, intent(out) :: facet_id(nfacet_in) + integer, intent(out) :: elem_id(nfacet_in) + integer, intent(out) :: face_id(nfacet_in) + integer, intent(out) :: facet_nnode(nfacet_in) + integer, intent(out) :: facet_conn(max_face_nodes_in,nfacet_in) + real(rk), intent(out) :: x(3,max_face_nodes_in,nfacet_in) + real(rk), intent(out) :: vnod(3,max_face_nodes_in,nfacet_in) + real(rk), intent(out) :: normal(3,nfacet_in) + real(rk), intent(out) :: area(nfacet_in) + integer, intent(out) :: ierr +end subroutine +``` -- 成功 -- 输入文件错误 -- 不支持功能 -- 内存分配失败 -- 非法参数 -- 网格质量错误 -- 求解失败 -- 耦合接口错误 +说明: -## 11. 内存与数组约定 +- `elem_id` 使用 Abaqus 原始单元编号。 +- `facet_conn` 使用 Abaqus 原始节点编号。 +- `normal` 为固体外法向。 +- 删除单元对应 facet 不应作为有效 facet 导出。 +- 外部程序接受 `x(3,max_face_nodes,nfacet)` 和 `vnod(3,max_face_nodes,nfacet)` 三维数组。 -待补充: +### 11.3 SPH 节点力输入 -- 数组维度顺序 -- 调用方分配还是库内分配 -- 字符串长度 -- 下标从 1 开始 -- 节点、单元和 facet 编号约定 +```fortran +subroutine fem_apply_sph_nodal_forces(nnode_in, node_id, force, ierr) + integer, intent(in) :: nnode_in + integer, intent(in) :: node_id(nnode_in) + real(rk), intent(in) :: force(3,nnode_in) + integer, intent(out) :: ierr +end subroutine +``` -## 12. 单位制约定 +### 11.4 SPH facet 压力输入 -待补充: +```fortran +subroutine fem_apply_sph_facet_pressure(nfacet_in, facet_id, pressure, ierr) + integer, intent(in) :: nfacet_in + integer, intent(in) :: facet_id(nfacet_in) + real(rk), intent(in) :: pressure(nfacet_in) + integer, intent(out) :: ierr +end subroutine +``` -- 软件不内置单位转换 -- inp 文件和外部耦合程序必须采用一致单位制 -- 日志中记录建议单位说明 +压力约定: -## 13. C/C++/Python 包装层规划 +```text +p > 0 means compression +t = -p n +``` -待补充: +### 11.5 SPH facet 压力与剪切输入 -- Fortran95 原生接口 -- C ABI 包装层 -- Python 调研接口 -- 与外部 SPH 程序耦合方式 +```fortran +subroutine fem_apply_sph_facet_tractions(nfacet_in, facet_id, pressure, shear, ierr) + integer, intent(in) :: nfacet_in + integer, intent(in) :: facet_id(nfacet_in) + real(rk), intent(in) :: pressure(nfacet_in) + real(rk), intent(in) :: shear(3,nfacet_in) + integer, intent(out) :: ierr +end subroutine +``` + +剪切约定: + +- `shear(3,nfacet)` 为全局坐标下的剪切牵引向量。 +- FEM 将 `-p n + shear` 映射为 facet 等效节点力。 + +## 12. 结果查询接口 + +### 12.1 节点运动学 + +```fortran +subroutine fem_get_nodal_kinematics(nnode_in, node_id, uout, vout, aout, ierr) + integer, intent(in) :: nnode_in + integer, intent(in) :: node_id(nnode_in) + real(rk), intent(out) :: uout(3,nnode_in) + real(rk), intent(out) :: vout(3,nnode_in) + real(rk), intent(out) :: aout(3,nnode_in) + integer, intent(out) :: ierr +end subroutine +``` + +说明: + +- 第一版只返回平动位移、速度、加速度。 +- 壳节点转角查询可在第二版扩展。 + +### 12.2 单元状态 + +```fortran +subroutine fem_get_element_status(nelem_in, elem_id, status, ierr) + integer, intent(in) :: nelem_in + integer, intent(in) :: elem_id(nelem_in) + integer, intent(out) :: status(nelem_in) + integer, intent(out) :: ierr +end subroutine +``` + +状态约定: + +```text +0 active +1 deleted +2 inactive by input +``` + +### 12.3 单元平均结果 + +```fortran +subroutine fem_get_element_average_state(nelem_in, elem_id, stress, strain, & + plastic_strain, eqps, damage, ierr) + integer, intent(in) :: nelem_in + integer, intent(in) :: elem_id(nelem_in) + real(rk), intent(out) :: stress(6,nelem_in) + real(rk), intent(out) :: strain(6,nelem_in) + real(rk), intent(out) :: plastic_strain(6,nelem_in) + real(rk), intent(out) :: eqps(nelem_in) + real(rk), intent(out) :: damage(nelem_in) + integer, intent(out) :: ierr +end subroutine +``` + +说明: + +- 第一版返回单元平均值。 +- 高斯点查询作为第二版高级接口实现。 + +## 13. 输出控制接口 + +```fortran +subroutine fem_set_output_directory(path, ierr) + character(len=*), intent(in) :: path + integer, intent(out) :: ierr +end subroutine + +subroutine fem_set_output_interval(interval, ierr) + integer, intent(in) :: interval + integer, intent(out) :: ierr +end subroutine + +subroutine fem_write_output(step, time, ierr) + integer, intent(in) :: step + real(rk), intent(in) :: time + integer, intent(out) :: ierr +end subroutine +``` + +说明: + +- 第一版输出 CSV 和日志。 +- 第二版扩展 VTK 和 restart。 +- 外部程序可关闭自动输出并显式调用 `fem_write_output`。 + +## 14. 版本与错误查询接口 + +### 14.1 版本查询 + +```fortran +subroutine fem_get_version(major, minor, patch, ierr) + integer, intent(out) :: major + integer, intent(out) :: minor + integer, intent(out) :: patch + integer, intent(out) :: ierr +end subroutine +``` + +### 14.2 错误查询 + +```fortran +subroutine fem_get_last_error(code, message, ierr) + integer, intent(out) :: code + character(len=*), intent(out) :: message + integer, intent(out) :: ierr +end subroutine +``` + +错误返回规则: + +- `ierr = 0` 表示成功。 +- `ierr > 0` 表示错误。 +- warning 只写日志,不作为 ierr 返回。 +- 发生错误后,`fem_get_last_error` 可返回最近一次错误码和错误信息。 + +错误码分组: + +```text +0 success +1000 input errors +2000 mesh and dof errors +3000 material and state errors +4000 solver errors +5000 coupling errors +6000 output errors +9000 internal errors +``` + +## 15. 单位制约定 + +FemLite 不进行单位转换。 + +调用者必须保证以下数据采用一致单位制: + +- Abaqus inp 几何尺寸 +- 材料密度 +- 弹性和塑性参数 +- 时间步长 +- 节点力 +- 压力 +- 剪切牵引 +- SPH 传入数据 +- 输出解释 + +日志中应记录单位制不检查的提示。 + +## 16. 第一版典型调用流程 + +### 16.1 独立 FEM 程序流程 + +```text +fem_initialize +fem_read_inp +fem_build_model +fem_compute_lumped_mass +loop: + fem_estimate_stable_dt + fem_advance_explicit + fem_write_output +fem_finalize +``` + +### 16.2 SPH 驱动流程 + +```text +fem_initialize +fem_read_inp +fem_build_model +fem_compute_lumped_mass +loop: + fem_get_boundary_facet_count + allocate external arrays if needed + fem_get_boundary_facets + SPH computes pressure, shear or nodal force + fem_clear_sph_forces + fem_apply_sph_facet_pressure / fem_apply_sph_facet_tractions / fem_apply_sph_nodal_forces + fem_advance_explicit(dt) + fem_get_nodal_kinematics if needed +fem_finalize +``` + +## 17. C/C++/Python 包装层规划 + +第二版提供: + +- C ABI 包装层。 +- Python 调试接口。 +- 面向 C/C++ 的扁平化数组接口。 + +包装层原则: + +- 不改变 Fortran95 原生接口的物理含义。 +- 不改变压力、剪切、编号和单位制约定。 +- 对三维数组接口提供扁平化视图。 +- 包装层单独测试,不污染 FEM 核心。 diff --git a/docs/06_test_and_verification_plan.md b/docs/06_test_and_verification_plan.md index 590cc1e..ed648c2 100644 --- a/docs/06_test_and_verification_plan.md +++ b/docs/06_test_and_verification_plan.md @@ -1,134 +1,548 @@ # FEM Test and Verification Plan -文档状态:草稿 +文档状态:测试验证基线草稿 适用对象:船舶接触爆炸船体结构 FEM 核心库与小型分析程序 ## 1. 文档目的 -本文档定义 FEM 软件的测试层级、验证算例、确认算例、回归测试、性能测试和验收策略。 +本文档定义 FemLite 第一版的测试层级、测试工具、验证算例、确认算例、回归测试、性能测试、误差容限和发布阻断条件。 + +本文档用于判断第一版是否达到可开发、可联调、可回归和可验收状态。 ## 2. 测试目标 -待补充: +第一版测试目标: -- 验证有限元公式实现正确 -- 验证材料更新算法正确 -- 验证显式动力学稳定可靠 -- 验证 Abaqus inp 子集解析正确 -- 验证 SPH-FEM 边界接口可用 -- 建立回归测试基准 +- 验证有限元形函数、积分和单元公式实现正确。 +- 验证材料更新算法正确,包括线弹性、J2、Johnson-Cook、温升和失效。 +- 验证显式动力学时间推进稳定可靠。 +- 验证 Abaqus inp 子集解析正确。 +- 验证 SPH-FEM 边界接口可用。 +- 验证单元删除后内存、质量、状态和外载处理符合设计。 +- 建立可重复运行的回归测试基准。 +- 建立第一版验收算例集合。 -## 3. 测试层级 +## 3. 测试工具与环境 -待补充: +第一版测试工具: -- 单元测试 -- 模块测试 -- 集成测试 -- 系统测试 -- 回归测试 -- 性能测试 -- 鲁棒性测试 +- Fortran 独立测试程序。 +- CMake/CTest 统一管理测试。 +- Python 辅助 CSV 对比和报告生成,可选执行。 -## 4. 单元测试计划 +Python 环境约定: -待补充: +- 在 `.\Python\` 中建立本软件专用 Python 虚拟环境。 +- 建议虚拟环境路径为 `.\Python\.venv`。 +- 虚拟环境只用于测试辅助脚本、CSV 对比和报告生成。 +- 虚拟环境本体不应提交到 git。 +- 只提交必要的脚本、依赖说明和测试数据。 -- 形函数 Kronecker delta 性质 -- 形函数 partition of unity -- Jacobian 计算 -- 高斯积分规则 -- 线弹性应力更新 -- J2 弹塑性返回映射 -- CSR 索引构造 -- INP keyword 解析 +第二版扩展: -## 5. 模块测试计划 +- 接入 CI。 +- Python 调试接口测试。 +- C ABI 包装层接口测试。 -待补充: +## 4. 测试目录结构 -- 实体单元质量矩阵 -- 实体单元内力 -- 壳单元膜响应 -- 壳单元弯曲响应 -- 边界载荷等效节点力 -- Dirichlet 约束施加 -- SPH facet 导出与载荷导入 +建议目录结构: -## 6. 集成测试计划 +```text +tests/unit +tests/module +tests/integration +tests/verification +tests/coupling +tests/performance +tests/data +tests/reference +tests/scripts +``` -待补充: +目录说明: -- inp 读取到数据库构建 -- 数据库到自由度编号 -- 显式初始化 -- 单步推进 -- 多步输出 -- 错误日志检查 +- `tests/unit`:形函数、材料点、数学工具等小粒度测试。 +- `tests/module`:单元、边界、输出、输入解析等模块测试。 +- `tests/integration`:完整 inp 读取、建模、求解、输出流程测试。 +- `tests/verification`:解析解、手算解、Abaqus 可选参考和冻结基准算例。 +- `tests/coupling`:SPH-FEM 接口测试。 +- `tests/performance`:规模和耗时测试。 +- `tests/data`:测试输入文件。 +- `tests/reference`:小型参考结果和抽样基准。 +- `tests/scripts`:Python 辅助脚本。 -## 7. 验证算例 +## 5. 测试优先级 -待补充: +测试分为三类: -- 实体单元 patch test -- 壳单元 patch test -- 单轴拉伸 -- 悬臂梁静力 -- 自由振动频率 -- 弹性波传播 -- 薄板弯曲 -- 弹塑性单轴加载卸载 +```text +P0 每次提交前必须运行并通过 +P1 阶段性运行,发布前必须通过 +P2 长算例、性能测试或专项测试,发布前或专项评审时运行 +``` -## 8. 确认算例 +P0 包括: -待补充: +- 编译测试。 +- 核心单元测试。 +- 材料单点测试。 +- 小型 INP 解析测试。 +- 小型显式单步/多步测试。 +- SPH 总力映射测试。 -- Taylor impact -- 板受冲击压力载荷 -- 简化船体板架爆炸响应 -- 接触冲击算例 -- SPH-FEM 耦合压力传递算例 +P1 包括: -## 9. 回归测试 +- 第一版验收验证算例。 +- 中等规模动力学回归测试。 +- 阶段性能测试。 +- 跨平台编译检查。 -待补充: +P2 包括: -- 基准结果存储格式 -- 允许误差 -- 浮点误差处理 -- 自动测试脚本 -- 每次提交必须运行的测试集合 +- 性能长跑。 +- 长时间动力学稳定测试。 +- Abaqus/Explicit 可选对比。 +- 复杂耦合流程测试。 -## 10. 性能测试 +## 6. 误差容限 -待补充: +默认误差容限: -- 节点规模 -- 单元规模 -- 时间步规模 -- 内存占用 -- 显式单步耗时 -- INP 读取耗时 +```text +单元级解析测试 relative tolerance 1.0e-10 to 1.0e-8 +材料单点测试 relative tolerance 1.0e-8 +输入解析测试 exact match unless floating data are involved +SPH总力映射测试 relative tolerance 1.0e-10 to 1.0e-8 +动力学回归测试 key history relative tolerance 1.0e-5 +工程验证算例 displacement/energy relative tolerance 1.0e-3 to 1.0e-2 +``` -## 11. 鲁棒性测试 +说明: -待补充: +- 解析测试应使用更严格阈值。 +- 动力学测试允许不同编译器和平台导致的小幅历史量漂移。 +- 工程验证算例应同时检查趋势、数量级和能量合理性。 -- 缺失材料 -- 退化单元 -- 非法边界自由度 -- 不支持 keyword -- 空集合 -- 非法塑性曲线 -- 时间步过大 +## 7. 参考结果来源 -## 12. 验收准则 +允许的参考结果来源: -待补充: +- 解析解。 +- 手算结果。 +- Abaqus/Explicit 可选参考。 +- 内部冻结基准 CSV。 +- 网格收敛趋势。 -- 第一阶段验收算例 -- 数值误差阈值 -- 日志和错误码要求 -- 文档完整性要求 +优先级: + +```text +解析解/手算结果 > Abaqus/Explicit 可选参考 > 冻结基准 CSV > 收敛趋势 +``` + +说明: + +- Abaqus/Explicit 结果作为可选参考,不作为开发环境强依赖。 +- 冻结基准 CSV 应尽量小,只保存关键历史量和抽样结果。 + +## 8. 单元测试计划 + +形函数测试: + +- C3D4 形函数 Kronecker delta 性质。 +- C3D8 形函数 Kronecker delta 性质。 +- S4 形函数 Kronecker delta 性质。 +- partition of unity。 +- 自然坐标导数正确性。 + +积分与几何测试: + +- C3D4 体积。 +- C3D8 2x2x2 积分。 +- S4 面积和厚度。 +- Jacobian 正负检查。 +- 退化单元检测。 + +质量测试: + +- C3D4 集中质量守恒。 +- C3D8 集中质量守恒。 +- S4 平动质量守恒。 +- S4 简化对角转动惯量非负。 + +压力等效节点力测试: + +- 均布压力总力正确。 +- 压力符号符合 `t = -p n`。 +- 等效节点力矩平衡在简单面片上合理。 + +## 9. 材料算法测试 + +第一版材料测试必须包含: + +- 线弹性单轴拉伸。 +- 线弹性纯剪切。 +- 小应变 J2 弹性步。 +- 小应变 J2 塑性步。 +- 小应变 J2 加载卸载。 +- 大变形 J2 加载卸载。 +- Jaumann 客观率刚体转动测试。 +- Johnson-Cook 应变率敏感测试。 +- Johnson-Cook 温度软化测试。 +- 绝热塑性温升测试。 +- 等效塑性应变阈值失效测试。 +- Johnson-Cook 损伤失效测试。 + +材料测试要求: + +- 单点材料测试优先使用解析或半解析参考。 +- 每个材料测试应检查应力、等效塑性应变、温度、损伤和失效标志。 +- 失效测试应检查 fail_flag 是否正确设置。 + +## 10. 模块测试计划 + +实体单元测试: + +- C3D4 单元质量。 +- C3D4 单元内力。 +- C3D4 patch test。 +- C3D8 单元质量。 +- C3D8 单元内力。 +- C3D8 patch test。 +- C3D8 全积分路径。 +- 第一版不支持 C3D8R,应返回明确错误或不支持信息。 + +壳单元测试: + +- S4 单元质量。 +- S4 膜响应。 +- S4 弯曲响应。 +- S4 横向剪切响应。 +- S4 选择性减缩积分路径。 +- S4 patch test。 + +边界与载荷测试: + +- Dirichlet 位移约束。 +- 节点力施加。 +- 面压力等效节点力。 +- amplitude 常值和表格插值。 + +输出测试: + +- `history.csv` 字段存在。 +- `nodes_step_xxxxx.csv` 字段存在。 +- `elements_step_xxxxx.csv` 字段存在。 +- 删除单元状态可输出。 + +## 11. 输入解析测试 + +第一版支持 keyword 均应有最小 inp 测试: + +- *NODE +- *ELEMENT +- *NSET +- *ELSET +- *MATERIAL +- *DENSITY +- *ELASTIC +- *PLASTIC +- *SOLID SECTION +- *SHELL SECTION +- *BOUNDARY +- *CLOAD +- *DLOAD +- *AMPLITUDE +- *STEP +- *DYNAMIC + +集合测试: + +- *NSET, GENERATE。 +- *ELSET, GENERATE。 +- 普通显式集合。 +- 空集合错误处理。 + +错误处理测试: + +- 不支持 keyword warning 后跳过。 +- 关键数据缺失返回 error。 +- 缺失材料返回 error。 +- 缺失密度返回 error。 +- 非法单元类型返回 error。 +- 原始编号到内部编号映射正确。 + +## 12. SPH-FEM 接口测试 + +SPH 接口第一版必须测试三类输入: + +- facet 压力。 +- facet 压力加剪切。 +- 节点力。 + +facet 导出测试: + +- facet 数量正确。 +- facet 编号稳定。 +- facet 节点连接使用 Abaqus 原始节点编号。 +- facet 所属单元使用 Abaqus 原始单元编号。 +- facet 外法向方向正确。 +- facet 面积正确。 +- facet 节点坐标和速度维度正确。 + +力映射测试: + +- 压力映射总力正确。 +- 压力符号符合受压为正。 +- 剪切映射总力正确。 +- 节点力直接累加正确。 +- 删除单元不会导出有效 facet。 +- 删除单元不再接受 SPH facet 外载。 + +## 13. 单元删除与失效测试 + +必须测试: + +- C3D4 使用 ANY_FAILED_GP 删除。 +- C3D8 使用 FRACTION_FAILED_GP,fraction = 0.5 删除。 +- S4 使用 FRACTION_FAILED_GP,fraction = 0.5 删除。 +- 删除后单元仍在内存中且可查询。 +- 删除后单元不贡献内力。 +- 删除后单元不接受面压力。 +- 删除后单元不接受 SPH facet 外载。 +- 删除后质量保留。 +- 删除后不触发自由度重编号。 +- 输出中记录 deleted 状态。 + +## 14. 集成测试计划 + +集成测试覆盖: + +- inp 读取到数据库构建。 +- 数据库到自由度编号。 +- facet 构造。 +- 集中质量初始化。 +- 显式单步推进。 +- 显式多步推进。 +- CSV 输出。 +- 错误日志检查。 +- 独立 femlite 程序运行。 +- 外部 SPH 驱动式调用流程。 + +典型流程测试: + +```text +fem_initialize +fem_read_inp +fem_build_model +fem_compute_lumped_mass +fem_estimate_stable_dt +fem_advance_explicit +fem_write_output +fem_finalize +``` + +SPH 驱动流程测试: + +```text +fem_get_boundary_facet_count +fem_get_boundary_facets +fem_clear_sph_forces +fem_apply_sph_facet_pressure / fem_apply_sph_facet_tractions / fem_apply_sph_nodal_forces +fem_advance_explicit +fem_get_nodal_kinematics +``` + +## 15. 第一版验证算例 + +第一版验收算例: + +- 单元 patch test。 +- 单轴拉伸。 +- 弹塑性加载卸载。 +- 弹性波传播。 +- 板受压力脉冲。 +- 简化 SPH-FEM 边界力传递接口。 + +覆盖要求: + +- patch test 覆盖 C3D4、C3D8、S4。 +- 单轴拉伸覆盖线弹性和 J2 弹塑性。 +- 弹塑性加载卸载覆盖小应变 J2 和大变形 J2。 +- 弹性波传播覆盖 C3D8 和 C3D4。 +- 板受压力脉冲覆盖第一版所有板壳单元。 +- SPH 接口覆盖压力、剪切力和节点力三类载荷。 + +每个验证算例应包含: + +- 输入文件。 +- 运行命令。 +- 参考结果来源。 +- 允许误差。 +- 关键输出字段。 +- 日志检查项。 +- 回归判据。 + +## 16. 确认算例 + +第一版可选确认算例: + +- 板受冲击压力载荷。 +- 简化船体板架爆炸响应。 +- 简化 SPH-FEM 压力传递。 + +第二版或后续确认算例: + +- Taylor impact。 +- 接触冲击算例。 +- 壳-实体混合模型响应。 +- Abaqus/Explicit 对比算例。 + +## 17. 回归测试 + +基准结果目录: + +```text +tests/reference +``` + +允许存储: + +- 小型 `history.csv`。 +- 抽样节点结果。 +- 抽样单元结果。 +- 日志关键模式。 +- 小型参考输入文件。 + +不应提交: + +- 每一步全场大 CSV。 +- 大型二进制结果。 +- Python 虚拟环境本体。 +- 临时构建目录。 + +回归比较: + +- P0 回归比较关键标量和少量抽样场变量。 +- P1 回归比较完整历史量和更多抽样节点/单元。 +- P2 回归重点检查性能、稳定性和长期漂移。 + +## 18. 性能测试 + +第一版性能目标: + +```text +目标节点数 10000 +目标单元数 10000 +目标时间步数 10000 +``` + +阶段性能测试 P1: + +```text +10000 节点 +10000 单元 +100 步 +``` + +性能长跑 P2: + +```text +10000 节点 +10000 单元 +10000 步 +``` + +性能指标: + +- INP 读取耗时。 +- 数据库构建耗时。 +- 集中质量计算耗时。 +- 显式单步平均耗时。 +- 总耗时。 +- 峰值内存。 +- 删除单元数量。 +- 最小稳定时间步。 + +第一版不要求: + +- OpenMP。 +- MPI。 +- GPU。 +- 外部求解器加速。 + +## 19. 鲁棒性测试 + +必须覆盖: + +- 输入文件不存在。 +- 缺失材料。 +- 缺失密度。 +- 非法材料参数。 +- 非法塑性曲线。 +- 非法 Johnson-Cook 参数。 +- 非法温度参数。 +- 退化单元。 +- 负 Jacobian。 +- 非法边界自由度。 +- 不支持 keyword。 +- 空集合。 +- 时间步小于等于零。 +- SPH facet_id 非法。 +- SPH node_id 非法。 +- 输出目录不可写。 + +鲁棒性判据: + +- 错误必须通过 ierr 返回。 +- 关键错误必须写入日志。 +- warning 不应导致程序异常终止。 +- 不支持 keyword 应 warning 后跳过。 +- 关键数据缺失应 error 并终止当前分析。 + +## 20. 本地测试与 CI 策略 + +第一版: + +- 使用本地 CTest。 +- P0 作为每次提交前必须通过的测试集合。 +- P1 作为阶段评审和发布前测试集合。 +- P2 作为专项长跑和发布候选验证。 + +第二版: + +- 接入 CI。 +- 增加 Windows/Linux 自动编译。 +- 增加 C ABI 和 Python 接口测试。 +- 增加 VTK/restart 回归测试。 + +## 21. 发布阻断条件 + +以下任一情况应阻断第一版发布: + +- P0 测试失败。 +- 输入解析关键测试失败。 +- 材料单点测试失败。 +- 显式动力学稳定测试失败。 +- SPH 接口总力映射失败。 +- 单元删除关键测试失败。 +- 跨平台编译失败。 +- 输出结果字段缺失。 +- 核心接口未通过 ierr 返回错误。 +- 文档与实现明显不一致。 + +## 22. 第一版验收准则 + +第一版完成条件: + +- P0 全部通过。 +- P1 验证算例全部通过。 +- P2 性能长跑完成并形成报告。 +- Windows 和 Linux 均可编译。 +- gfortran 默认可用。 +- Intel Fortran 兼容性检查通过或记录明确限制。 +- SPH 三类接口均通过测试。 +- CSV 输出符合接口文档。 +- 所有第一版文档更新到与实现一致。