diff --git a/docs/07_v2_development_plan.md b/docs/07_v2_development_plan.md new file mode 100644 index 0000000..fc2dcdc --- /dev/null +++ b/docs/07_v2_development_plan.md @@ -0,0 +1,272 @@ +# FemLite 0.2.0 第二版开发计划 + +文档状态:第二版开发基线草稿 + +日期:2026-06-22 + +适用对象:FemLite 0.2.0 开发、评审、测试与阶段验收 + +## 1. 文档目的 + +本文档定义 FemLite 第二版的开发目标、阶段划分、技术路线、验收准则和风险控制。 + +第二版开发应以 0.1.0 第一版验收基线为起点,在不破坏第一版显式瞬态、实体单元、材料、INP 读取和 SPH 力接口能力的前提下,逐步扩展壳单元、二次实体、接触、隐式求解、CSR 稀疏矩阵、VTK、restart 和外部接口能力。 + +## 2. 版本定位 + +0.2.0 的定位: + +- 保持 0.1.0 已验收能力稳定可回归。 +- 完成第二版需求中的关键框架能力。 +- 优先建立可扩展基础设施,再逐项加入复杂算法。 +- 每个阶段都必须能编译、能测试、能回退定位。 + +0.2.0 不应一次性大改所有核心模块。涉及求解器、单元、状态变量和输出格式的变更应通过小步提交完成。 + +## 3. 第二版主要目标 + +第二版计划实现或完善: + +- CSR 稀疏矩阵基础设施。 +- 隐式线弹性小变形框架。 +- 非线性增量迭代框架预留。 +- C3D10、C3D20 二次实体单元。 +- S3、S6、S8 壳单元。 +- S4 壳单元能力完善。 +- Robin 边界条件。 +- MPC 约束方程。 +- 接触基础框架。 +- C ABI 包装层。 +- Python 调试接口。 +- VTK 结果输出。 +- restart 基础能力。 +- CI 或准 CI 本地脚本。 + +## 4. 开发分支与版本策略 + +推荐策略: + +- `main` 保持已验收稳定版本。 +- `v0.1.0` 标签固定第一版验收基线。 +- `dev/v0.2` 作为第二版主开发分支。 +- 每个阶段完成后形成阶段提交。 +- 发布 0.2.0 前从 `dev/v0.2` 合并回 `main`。 + +版本号约定: + +- 开发中版本可保持 `0.2.0-dev` 或在文档中标记为第二版开发版。 +- 正式第二版验收后将代码常量更新为 `0.2.0`。 +- 若需要中间可用版本,可使用 `0.2.0-alpha.1`、`0.2.0-alpha.2` 等标签。 + +## 5. 阶段划分 + +第二版分为 6 个阶段。 + +| 阶段 | 名称 | 目标 | 阶段结果 | +|---|---|---|---| +| V2.1 | 基础设施整理 | 单元拓扑、积分规则、状态变量和测试结构升级 | 为二次单元、壳单元和隐式求解打基础 | +| V2.2 | CSR 与隐式线弹性 | CSR 矩阵、装配接口、线性求解接口、隐式小变形线弹性 | 可运行小型静力或准静力线弹性算例 | +| V2.3 | 二次实体单元 | C3D10、C3D20 形函数、积分、质量、内力、patch test | 二次实体单元通过基础验证 | +| V2.4 | 壳单元扩展 | S4 完善,新增 S3、S6、S8 | 壳单元压力、膜、弯曲和 patch test 通过 | +| V2.5 | 约束与接触 | Robin、MPC、基础接触搜索和接触力 | 简化接触冲击与约束测试通过 | +| V2.6 | 外部接口与输出 | C ABI、Python 调试接口、VTK、restart、CI | 第二版交付形态完整 | + +## 6. V2.1 基础设施整理 + +目标: + +- 建立统一单元拓扑查询接口。 +- 建立统一积分点与权重接口。 +- 将单元状态变量维度和高斯点数量从固定逻辑中解耦。 +- 梳理显式、隐式共用的单元级数据接口。 +- 扩展测试目录,区分第一版回归和第二版新增测试。 + +建议新增或整理模块: + +- `src/element/fem_element_topology.f90` +- `src/element/fem_quadrature.f90` +- `src/element/fem_shape_functions.f90` +- `src/solver/fem_sparse_csr.f90` 占位或骨架 +- `tests/module` 中新增单元拓扑和积分规则测试 + +验收条件: + +- 0.1.0 全部 CTest 继续通过。 +- C3D4、C3D8、S4 原有路径不回退。 +- 单元类型、节点数、面数、面节点、积分点数量可通过统一接口查询。 +- 为 C3D10、C3D20、S3、S6、S8 预留清晰入口。 + +## 7. V2.2 CSR 与隐式线弹性 + +目标: + +- 实现 CSR 矩阵存储和基础操作。 +- 建立稀疏装配接口。 +- 建立隐式求解器骨架。 +- 第一阶段只实现小变形线弹性隐式路径。 +- 外部线性求解器先不作为强依赖,可先实现内部简单 CG 或直接调试求解器。 + +建议实现内容: + +- CSR pattern 构建。 +- CSR 数值清零、累加、矩阵向量乘。 +- Dirichlet 条件在 CSR 系统中的施加。 +- 单元刚度矩阵装配接口。 +- 隐式求解控制参数读取。 +- 小型 C3D4/C3D8 线弹性静力或准静力验证算例。 + +验收条件: + +- dense 仍只用于单元局部矩阵和调试。 +- CSR 成为隐式主格式。 +- 第一版显式求解路径不受影响。 +- 至少一个小型线弹性隐式算例通过解析或手算验证。 + +## 8. V2.3 二次实体单元 + +目标: + +- 实现 C3D10 和 C3D20。 +- 支持质量、内力、应力更新、稳定步长估计和基础输出。 +- 显式路径优先,隐式刚度可随后接入。 + +建议顺序: + +1. C3D10 形函数、导数、体积和 patch test。 +2. C3D10 集中质量和显式内力。 +3. C3D20 形函数、导数、积分和 patch test。 +4. C3D20 集中质量和显式内力。 +5. 二次单元 INP 读取和输出检查。 + +验收条件: + +- C3D10、C3D20 通过形函数 Kronecker delta、partition of unity 和导数测试。 +- C3D10、C3D20 通过基础 patch test。 +- 单元质量守恒。 +- 删除单元和 SPH facet 导出逻辑不被二次单元破坏。 + +## 9. V2.4 壳单元扩展 + +目标: + +- 完善 S4 第一版有限能力实现。 +- 新增 S3、S6、S8。 +- 明确壳厚度、法向、转动自由度、剪切修正和积分规则。 + +建议顺序: + +1. 固化壳单元公共数据接口。 +2. 完善 S4 状态输出、压力载荷和基础塑性路径。 +3. 实现 S3 线性三角壳。 +4. 实现 S6 二次三角壳。 +5. 实现 S8 二次四边壳。 +6. 增加壳单元压力脉冲和 patch test 覆盖。 + +验收条件: + +- S4 第一版测试继续通过。 +- S3、S6、S8 至少覆盖膜、弯曲、横向剪切、压力载荷基础测试。 +- 壳单元质量和转动惯量非负。 +- 壳面 facet 可被 SPH 耦合层正确导出。 + +## 10. V2.5 约束与接触 + +目标: + +- 实现 Robin 边界条件。 +- 实现 MPC 约束方程基础能力。 +- 实现接触基础框架。 + +接触第一阶段建议采用: + +- 节点到面接触。 +- penalty 法作为默认接触力方法。 +- 显式接触优先。 +- 接触搜索先使用简单网格或朴素搜索,后续再优化。 +- 接触接口与 SPH 耦合层保持分离。 + +验收条件: + +- Robin 边界在小型算例中通过手算验证。 +- MPC 可约束节点自由度线性关系。 +- 简化节点-刚性面或节点-壳面接触算例稳定运行。 +- 接触力、接触能量或关键接触统计量可输出。 + +## 11. V2.6 外部接口与输出 + +目标: + +- 增加 C ABI 包装层。 +- 增加 Python 调试接口。 +- 增加 VTK 输出。 +- 增加 restart 基础能力。 +- 增加 CI 或本地准 CI 脚本。 + +建议内容: + +- C ABI 优先覆盖初始化、读入、建模、推进、取边界 facet、施加 SPH 力、取节点运动量和释放资源。 +- Python 接口先用于调试和测试,不作为第一阶段高性能接口。 +- VTK 优先输出节点位移、速度、加速度、单元应力、应变、塑性应变和删除状态。 +- restart 优先支持显式求解从某一步继续。 +- CI 第二版至少覆盖 Linux gfortran 构建和 CTest。 + +验收条件: + +- C ABI 测试程序可独立调用核心流程。 +- Python 调试脚本可运行一个小型算例并读取关键结果。 +- VTK 文件可被 ParaView 打开并显示基础场量。 +- restart 可从保存步继续并与连续计算关键历史量一致。 + +## 12. 第二版测试策略 + +第二版测试必须保留第一版回归。 + +每个阶段新增测试: + +- V2.1:拓扑、积分、形函数、状态维度测试。 +- V2.2:CSR 操作、装配、Dirichlet、隐式线弹性测试。 +- V2.3:C3D10、C3D20 单元级和小型显式算例。 +- V2.4:S3、S6、S8 壳单元测试和压力脉冲算例。 +- V2.5:Robin、MPC、接触测试。 +- V2.6:C ABI、Python、VTK、restart 测试。 + +第二版发布前必须通过: + +- 第一版全部验收测试。 +- 第二版新增 P0/P1 测试。 +- Windows 和 Linux 至少完成构建检查。 +- gfortran 为默认通过编译器。 +- Intel Fortran 兼容性问题如未完全解决,必须形成限制说明。 + +## 13. 风险与控制 + +主要风险: + +- 隐式求解和显式求解共享数据库时引入状态提交混乱。 +- 二次单元增加高斯点数量后破坏旧状态数组假设。 +- 壳单元转动自由度和实体单元平动自由度耦合不清。 +- 接触算法可能影响显式稳定时间步。 +- C ABI 和 Python 接口可能暴露内部编号与 Abaqus 原始编号不一致的问题。 +- VTK/restart 输出可能引入较大文件或跨平台二进制兼容问题。 + +控制策略: + +- 每个阶段先写最小测试,再接入完整流程。 +- 保持第一版测试作为回归底线。 +- CSR、接触、VTK、restart 均先实现最小可用版本。 +- 新增全局数组必须明确初始化、释放和重置路径。 +- 外部接口继续默认使用 Abaqus 原始编号。 +- 大型输出和长算例结果不提交 git,只提交小型参考和抽样结果。 + +## 14. 第二版完成准则 + +FemLite 0.2.0 完成条件: + +- 0.1.0 验收能力无回退。 +- C3D10、C3D20、S3、S6、S8 基础能力通过测试。 +- S4 能力比第一版明确增强,并有对应测试证明。 +- CSR 隐式线弹性最小流程可运行。 +- Robin、MPC、接触基础能力可运行并通过小型验证。 +- C ABI、Python 调试接口、VTK 和 restart 至少具备最小可用能力。 +- 文档、测试计划和接口说明更新到与实现一致。 +- 形成 `v0.2.0` 验收报告或发布说明。