From ad31c2d5cc400c1e02f54d742b74da58176ad8c7 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 2 Jul 2026 18:47:38 +0800 Subject: [PATCH] Release SPHLite 0.1.0 framework --- .gitattributes | 4 + .gitignore | 17 + CMakeLists.txt | 131 ++++++ Python/sphlite_debug.py | 66 +++ README.md | 73 ++++ docs/01_requirements_specification.md | 91 ++++ docs/02_software_architecture_design.md | 151 +++++++ docs/03_detailed_design.md | 245 +++++++++++ docs/04_mathematical_model_and_algorithms.md | 202 +++++++++ docs/05_interface_control_document.md | 274 ++++++++++++ docs/06_test_and_verification_plan.md | 162 +++++++ docs/07_user_manual.md | 49 +++ docs/08_developer_manual.md | 55 +++ docs/09_release_history.md | 64 +++ docs/10_development_roadmap.md | 76 ++++ docs/11_benchmark_matrix.md | 83 ++++ docs/README.md | 27 ++ docs/v1.0_development_plan.md | 398 ++++++++++++++++++ include/sphlite.hpp | 80 ++++ include/sphlite_c_api.h | 47 +++ src/app/sph_main.c | 105 +++++ src/app/sph_program.f90 | 37 ++ src/core/sph_control.f90 | 48 +++ src/core/sph_error.f90 | 41 ++ src/core/sph_log.f90 | 51 +++ src/core/sph_precision.f90 | 11 + .../sph_coupling_interface.f90 | 97 +++++ src/database/sph_database.f90 | 144 +++++++ src/explosive/sph_explosive.f90 | 15 + src/gas/sph_gas.f90 | 15 + src/input/sph_inp_defs.f90 | 18 + src/input/sph_inp_helpers.f90 | 91 ++++ src/input/sph_input_reader.f90 | 258 ++++++++++++ src/interface/sph_api.f90 | 398 ++++++++++++++++++ src/interface/sph_api_state.f90 | 20 + src/interface/sph_c_api.c | 189 +++++++++ src/material/sph_material.f90 | 15 + src/output/sph_output_csv.f90 | 61 +++ src/output/sph_restart.f90 | 98 +++++ src/particle/sph_particle.f90 | 15 + src/shell/sph_shell.f90 | 15 + src/solid/sph_solid.f90 | 15 + src/solver/sph_solver_explicit.f90 | 60 +++ src/water/sph_water.f90 | 15 + tests/data/minimal_particles.inp | 8 + tests/data/missing_required.inp | 4 + tests/data/unknown_keyword.inp | 10 + tests/interface/test_c_api.c | 55 +++ tests/module/test_input.f90 | 60 +++ tests/source_size_exceptions.txt | 4 + tests/unit/test_smoke.f90 | 56 +++ todo.md | 224 ++++++++++ tools/testing/check_source_size.py | 128 ++++++ tools/testing/test_python_debug.py | 34 ++ 54 files changed, 4710 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 CMakeLists.txt create mode 100644 Python/sphlite_debug.py create mode 100644 README.md create mode 100644 docs/01_requirements_specification.md create mode 100644 docs/02_software_architecture_design.md create mode 100644 docs/03_detailed_design.md create mode 100644 docs/04_mathematical_model_and_algorithms.md create mode 100644 docs/05_interface_control_document.md create mode 100644 docs/06_test_and_verification_plan.md create mode 100644 docs/07_user_manual.md create mode 100644 docs/08_developer_manual.md create mode 100644 docs/09_release_history.md create mode 100644 docs/10_development_roadmap.md create mode 100644 docs/11_benchmark_matrix.md create mode 100644 docs/README.md create mode 100644 docs/v1.0_development_plan.md create mode 100644 include/sphlite.hpp create mode 100644 include/sphlite_c_api.h create mode 100644 src/app/sph_main.c create mode 100644 src/app/sph_program.f90 create mode 100644 src/core/sph_control.f90 create mode 100644 src/core/sph_error.f90 create mode 100644 src/core/sph_log.f90 create mode 100644 src/core/sph_precision.f90 create mode 100644 src/coupling_interface/sph_coupling_interface.f90 create mode 100644 src/database/sph_database.f90 create mode 100644 src/explosive/sph_explosive.f90 create mode 100644 src/gas/sph_gas.f90 create mode 100644 src/input/sph_inp_defs.f90 create mode 100644 src/input/sph_inp_helpers.f90 create mode 100644 src/input/sph_input_reader.f90 create mode 100644 src/interface/sph_api.f90 create mode 100644 src/interface/sph_api_state.f90 create mode 100644 src/interface/sph_c_api.c create mode 100644 src/material/sph_material.f90 create mode 100644 src/output/sph_output_csv.f90 create mode 100644 src/output/sph_restart.f90 create mode 100644 src/particle/sph_particle.f90 create mode 100644 src/shell/sph_shell.f90 create mode 100644 src/solid/sph_solid.f90 create mode 100644 src/solver/sph_solver_explicit.f90 create mode 100644 src/water/sph_water.f90 create mode 100644 tests/data/minimal_particles.inp create mode 100644 tests/data/missing_required.inp create mode 100644 tests/data/unknown_keyword.inp create mode 100644 tests/interface/test_c_api.c create mode 100644 tests/module/test_input.f90 create mode 100644 tests/source_size_exceptions.txt create mode 100644 tests/unit/test_smoke.f90 create mode 100644 todo.md create mode 100644 tools/testing/check_source_size.py create mode 100644 tools/testing/test_python_debug.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..a2237bc --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +* text=auto eol=lf + +*.bat text eol=crlf +*.cmd text eol=crlf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d046d55 --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +build*/ +*.mod +*.smod +*.o +*.obj +*.exe +*.dll +*.a +*.lib +*.csv +*.vtk +*.vtu +*.restart +*.rst +/output/ +__pycache__/ +*.pyc diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..aeb3d78 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,131 @@ +cmake_minimum_required(VERSION 3.20) + +project(SPHLite VERSION 0.1.0 LANGUAGES C Fortran) + +set(CMAKE_C_STANDARD 99) +set(CMAKE_C_STANDARD_REQUIRED ON) +set(CMAKE_C_EXTENSIONS OFF) + +set(CMAKE_Fortran_STANDARD 95) +set(CMAKE_Fortran_STANDARD_REQUIRED ON) +set(CMAKE_Fortran_EXTENSIONS OFF) + +set(SPHLITE_MODULE_DIR "${CMAKE_BINARY_DIR}/modules") +set(SPHLITE_GENERATED_DIR "${CMAKE_BINARY_DIR}/generated") +file(MAKE_DIRECTORY "${SPHLITE_MODULE_DIR}" "${SPHLITE_GENERATED_DIR}") + +include(FortranCInterface) +FortranCInterface_HEADER( + "${SPHLITE_GENERATED_DIR}/sphlite_fortran_mangle.h" + MACRO_NAMESPACE "SPHLITE_" +) +if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU") + file(APPEND "${SPHLITE_GENERATED_DIR}/sphlite_fortran_mangle.h" +" +#ifndef SPHLITE_FC_sphft_initialize +#define SPHLITE_FC_sphft_initialize sphft_initialize_ +#define SPHLITE_FC_sphft_finalize sphft_finalize_ +#define SPHLITE_FC_sphft_get_version sphft_get_version_ +#define SPHLITE_FC_sphft_get_last_error_chars sphft_get_last_error_chars_ +#define SPHLITE_FC_sphft_read_inp_chars sphft_read_inp_chars_ +#define SPHLITE_FC_sphft_build_model sphft_build_model_ +#define SPHLITE_FC_sphft_estimate_stable_dt sphft_estimate_stable_dt_ +#define SPHLITE_FC_sphft_advance_explicit sphft_advance_explicit_ +#define SPHLITE_FC_sphft_run_explicit sphft_run_explicit_ +#define SPHLITE_FC_sphft_get_current_time sphft_get_current_time_ +#define SPHLITE_FC_sphft_get_particle_count sphft_get_particle_count_ +#define SPHLITE_FC_sphft_write_csv_chars sphft_write_csv_chars_ +#define SPHLITE_FC_sphft_write_restart_chars sphft_write_restart_chars_ +#define SPHLITE_FC_sphft_read_restart_chars sphft_read_restart_chars_ +#endif +") +endif() + +set(SPHLITE_CORE_SOURCES + src/core/sph_precision.f90 + src/core/sph_error.f90 + src/core/sph_log.f90 + src/core/sph_control.f90 + src/database/sph_database.f90 + src/input/sph_inp_defs.f90 + src/input/sph_inp_helpers.f90 + src/input/sph_input_reader.f90 + src/solver/sph_solver_explicit.f90 + src/output/sph_output_csv.f90 + src/output/sph_restart.f90 + src/coupling_interface/sph_coupling_interface.f90 + src/particle/sph_particle.f90 + src/material/sph_material.f90 + src/water/sph_water.f90 + src/gas/sph_gas.f90 + src/explosive/sph_explosive.f90 + src/solid/sph_solid.f90 + src/shell/sph_shell.f90 + src/interface/sph_api_state.f90 + src/interface/sph_api.f90 +) + +add_library(sphlite_core STATIC ${SPHLITE_CORE_SOURCES}) +target_include_directories(sphlite_core PUBLIC "${SPHLITE_GENERATED_DIR}") +set_target_properties(sphlite_core PROPERTIES + Fortran_MODULE_DIRECTORY "${SPHLITE_MODULE_DIR}" + POSITION_INDEPENDENT_CODE ON +) + +add_library(sphlite_c STATIC src/interface/sph_c_api.c) +target_include_directories(sphlite_c PUBLIC include "${SPHLITE_GENERATED_DIR}") +target_link_libraries(sphlite_c PUBLIC sphlite_core) +set_target_properties(sphlite_c PROPERTIES POSITION_INDEPENDENT_CODE ON) + +add_library(sphlite_c_shared SHARED src/interface/sph_c_api.c) +target_include_directories(sphlite_c_shared PUBLIC include "${SPHLITE_GENERATED_DIR}") +target_compile_definitions(sphlite_c_shared PRIVATE SPHLITE_BUILD_SHARED) +target_link_libraries(sphlite_c_shared PRIVATE sphlite_core) +set_target_properties(sphlite_c_shared PROPERTIES OUTPUT_NAME sphlite_c) + +add_executable(sphlite src/app/sph_main.c src/app/sph_program.f90) +target_include_directories(sphlite PRIVATE include) +target_link_libraries(sphlite PRIVATE sphlite_c) +set_target_properties(sphlite PROPERTIES Fortran_MODULE_DIRECTORY "${SPHLITE_MODULE_DIR}") + +enable_testing() + +add_executable(test_smoke tests/unit/test_smoke.f90) +target_link_libraries(test_smoke PRIVATE sphlite_core) +set_target_properties(test_smoke PROPERTIES Fortran_MODULE_DIRECTORY "${SPHLITE_MODULE_DIR}") +add_test(NAME smoke COMMAND test_smoke) +set_tests_properties(smoke PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + +add_executable(test_input tests/module/test_input.f90) +target_link_libraries(test_input PRIVATE sphlite_core) +set_target_properties(test_input PROPERTIES Fortran_MODULE_DIRECTORY "${SPHLITE_MODULE_DIR}") +add_test(NAME input COMMAND test_input) +set_tests_properties(input PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + +add_executable(test_c_api tests/interface/test_c_api.c) +target_include_directories(test_c_api PRIVATE include) +target_compile_definitions(test_c_api PRIVATE + SPHLITE_TEST_DATA_DIR="${CMAKE_CURRENT_SOURCE_DIR}/tests/data" +) +target_link_libraries(test_c_api PRIVATE sphlite_c) +add_test(NAME c_api COMMAND test_c_api) +set_tests_properties(c_api PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + +find_package(Python3 REQUIRED COMPONENTS Interpreter) +add_test( + NAME python_debug + COMMAND "${Python3_EXECUTABLE}" + "${CMAKE_CURRENT_SOURCE_DIR}/tools/testing/test_python_debug.py" + --library "$" + --input "${CMAKE_CURRENT_SOURCE_DIR}/tests/data/minimal_particles.inp" +) +set_tests_properties(python_debug PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + +add_test( + NAME source_size + COMMAND "${Python3_EXECUTABLE}" + "${CMAKE_CURRENT_SOURCE_DIR}/tools/testing/check_source_size.py" + --root "${CMAKE_CURRENT_SOURCE_DIR}" + --exceptions "${CMAKE_CURRENT_SOURCE_DIR}/tests/source_size_exceptions.txt" +) +set_tests_properties(source_size PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") diff --git a/Python/sphlite_debug.py b/Python/sphlite_debug.py new file mode 100644 index 0000000..f962dfd --- /dev/null +++ b/Python/sphlite_debug.py @@ -0,0 +1,66 @@ +from __future__ import annotations + +import ctypes +from pathlib import Path + + +class SPHLiteError(RuntimeError): + pass + + +class SPHLite: + def __init__(self, library: str | Path): + self.library_path = Path(library) + self.lib = ctypes.CDLL(str(self.library_path)) + self._configure() + + def _configure(self) -> None: + self.lib.sphlite_initialize.restype = ctypes.c_int + self.lib.sphlite_finalize.restype = ctypes.c_int + + self.lib.sphlite_read_inp.argtypes = [ctypes.c_char_p] + self.lib.sphlite_read_inp.restype = ctypes.c_int + + self.lib.sphlite_build_model.restype = ctypes.c_int + self.lib.sphlite_run_explicit.restype = ctypes.c_int + + self.lib.sphlite_get_particle_count.argtypes = [ctypes.POINTER(ctypes.c_int)] + self.lib.sphlite_get_particle_count.restype = ctypes.c_int + + self.lib.sphlite_get_last_error.argtypes = [ + ctypes.POINTER(ctypes.c_int), + ctypes.c_char_p, + ctypes.c_int, + ] + self.lib.sphlite_get_last_error.restype = ctypes.c_int + + def _check(self, ierr: int) -> None: + if ierr == 0: + return + code = ctypes.c_int(0) + buffer = ctypes.create_string_buffer(256) + rc = self.lib.sphlite_get_last_error(ctypes.byref(code), buffer, len(buffer)) + if rc == 0: + raise SPHLiteError(buffer.value.decode("utf-8", errors="replace")) + raise SPHLiteError(f"SPHLite error {ierr}") + + def initialize(self) -> None: + self._check(self.lib.sphlite_initialize()) + + def finalize(self) -> None: + self._check(self.lib.sphlite_finalize()) + + def read_inp(self, filename: str | Path) -> None: + encoded = str(Path(filename)).encode("utf-8") + self._check(self.lib.sphlite_read_inp(encoded)) + + def build_model(self) -> None: + self._check(self.lib.sphlite_build_model()) + + def particle_count(self) -> int: + count = ctypes.c_int(0) + self._check(self.lib.sphlite_get_particle_count(ctypes.byref(count))) + return int(count.value) + + def run_explicit(self) -> None: + self._check(self.lib.sphlite_run_explicit()) diff --git a/README.md b/README.md new file mode 100644 index 0000000..d4234fd --- /dev/null +++ b/README.md @@ -0,0 +1,73 @@ +# SPHLite + +SPHLite 是一个面向船舶水下接触爆炸的轻量级 SPH 多物理仿真软件。项目目标是支持水、爆炸产物气体、实体结构粒子、板壳结构粒子、破裂损伤,以及通过外部耦合模块与 FEMLite 进行接触和连续体耦合。 + +当前目标版本:0.1.0。该版本定位为工程骨架版,只建立可编译、可测试、可扩展的 Fortran 95 求解器框架,不交付生产级水下爆炸、气泡脉动、结构破裂或 FEM-SPH 联合计算能力。 + +代码仓库地址: + +- http://123.57.213.67:3062/shen/SPHLite.git + +## 目标能力 + +- 3D 流体 SPH 粒子仿真水体运动、冲击波传播和自由界面演化。 +- `Gas` 表示气体相,包括爆轰产物、舱内空气、空泡和混合气体。 +- `Explosive` 描述炸药点火、爆轰传播、反应进度和向气体相的质量/能量注入。 +- 3D 实体结构 SPH 粒子仿真船体大变形、塑性、损伤和破裂。 +- 板壳 SPH 粒子仿真船体板壳结构变形、屈曲、撕裂和穿孔。 +- 船舱局部破坏、气体膨胀、气泡产生与脉动等水下爆炸现象。 +- SPH 3D 实体结构与 FEMLite 3D 实体单元的接触和连续体耦合。 +- SPH 板壳粒子与 FEMLite 板壳单元的接触和连续体耦合。 + +## 模块设想 + +| 模块 | 职责 | +|---|---| +| `Core` | 精度、错误码、生命周期、日志、全局控制 | +| `Particle` | 粒子状态、邻域搜索、核函数和基础数据结构 | +| `Water` | 水体、冲击波和流固界面载荷 | +| `Gas` | 气体 EOS、气体团簇、气泡/气腔统计和界面演化 | +| `Explosive` | 点火、爆轰传播、反应进度和能量释放 | +| `Solid` | 3D 结构粒子、应力更新、损伤和断裂 | +| `Shell` | 板壳粒子、厚度、转角/法向、膜弯剪响应和撕裂 | +| `CouplingInterface` | 中立耦合数据导出、外部载荷导入和耦合诊断占位 | +| `Output` | CSV、VTK、restart 和诊断输出 | +| `Interface` | C ABI、C++ 接口和 Python 调试入口 | + +## 构建原则 + +SPHLite 的编译和测试要求应与 FEMLite 保持一致风格: + +- CMake 作为主构建系统。 +- CTest 作为测试入口。 +- Fortran 95 用于核心求解器实现。 +- C ABI 作为长期稳定的跨语言边界。 +- C++ 作为 C ABI 之上的薄包装接口。 +- Python 用于调试脚本、轻量后处理和验收检查。 +- 只在本仓库目录内维护 SPHLite 文件;FEMLite 仅作为参考和外部耦合对象。 + +## 文档 + +- [文档索引](docs/README.md) +- [01 需求规格说明](docs/01_requirements_specification.md) +- [02 软件架构设计](docs/02_software_architecture_design.md) +- [03 详细设计](docs/03_detailed_design.md) +- [04 数学模型与算法](docs/04_mathematical_model_and_algorithms.md) +- [05 接口控制文档](docs/05_interface_control_document.md) +- [06 测试与验证计划](docs/06_test_and_verification_plan.md) +- [07 用户手册](docs/07_user_manual.md) +- [08 开发者手册](docs/08_developer_manual.md) +- [09 版本历史与验收记录](docs/09_release_history.md) +- [10 后续开发路线图](docs/10_development_roadmap.md) +- [11 Benchmark 与验收矩阵](docs/11_benchmark_matrix.md) + +## 当前状态 + +0.1.0 当前实现重点包括: + +- CMake/CTest 工程骨架。 +- Fortran 95 核心库、C ABI、C++ 头文件薄包装和 Python `ctypes` 调试入口。 +- Abaqus `.inp` 明确子集的最小解析框架。 +- Velocity-Verlet 显式推进骨架。 +- Water、Gas、Explosive、Solid、Shell 和 CouplingInterface 的占位模块。 +- 0.1.0 release gate 与 source size 门禁。 diff --git a/docs/01_requirements_specification.md b/docs/01_requirements_specification.md new file mode 100644 index 0000000..cfda28e --- /dev/null +++ b/docs/01_requirements_specification.md @@ -0,0 +1,91 @@ +# 01 需求规格说明 + +文档状态:规划确认稿 + +## 1. 软件定位 + +SPHLite 是一个面向船舶水下接触爆炸的轻量级 SPH 多物理仿真软件。软件应能描述水下爆炸载荷、水体运动、爆轰产物气体、气泡产生与脉动、船体结构大变形和破裂,并能与 FEMLite 进行接触耦合和连续体耦合。 + +SPHLite 不定位为通用 SPH 框架,也不只是颗粒接触工具。其通用数值能力应服务于船舶水下接触爆炸目标,并按“水-气-爆炸-结构-耦合”的多物理平台规划。 + +SPHLite 的求解维度面向 3D。1D、2D 或轴对称模型可作为验证、简化算例或后处理概念使用,但不作为正式求解维度规划。 + +## 2. 长期目标能力 + +长期目标能力包括: + +- 3D 实体 SPH 粒子仿真水体运动、冲击波传播和自由界面演化。 +- 3D 实体 SPH 粒子仿真船体结构的大变形、塑性、损伤和破裂。 +- 板壳 SPH 粒子仿真船体板壳结构的变形、屈曲、撕裂和穿孔。 +- 炸药粒子的点火、爆轰传播和能量释放,采用解析点火/爆轰传播路线,而不是固定球面载荷模型。 +- `Gas` 统一表示爆轰产物气体、舱内空气、空泡和混合气体。 +- 爆炸气体在水中形成气泡,支持气泡膨胀、回缩、脉动和迁移统计。 +- 船舱局部破坏和水气结构相互作用。 +- `Solid` 与 FEMLite 3D 实体单元之间的接触耦合和连续体耦合。 +- `Shell` 与 FEMLite 壳单元之间的接触耦合和连续体耦合。 + +FEMLite 侧术语使用“实体单元”和“壳单元”;SPHLite 侧术语使用“实体粒子”和“板壳粒子”,避免将 FEM 单元误称为粒子。 + +## 3. 各版本交付范围 + +各版本交付范围是规划边界,实际版本号可根据验证闭环调整。 + +| 版本线 | 交付范围 | +|---|---| +| 0.1 | CMake/CTest 工程骨架、3D 粒子状态、生命周期、错误码、C ABI 和最小 Python 调试入口 | +| 0.2 | 3D 水体 SPH 基础能力、核函数、邻域搜索、弱可压 SPH、Tait EOS 和小型压力传播测试 | +| 0.3 | `Gas`,最小 EOS 集合为 JWL 和理想气体;气体体积、中心、平均压力和等效气泡半径诊断 | +| 0.4 | `Explosive`,解析点火、爆轰到达时间、反应进度和向 `Gas` 的质量/能量注入 | +| 0.5 | `Solid` 3D 结构粒子,Johnson-Cook 材料模型和 Johnson-Cook 失效模型的最小闭环 | +| 0.6 | `Shell` 板壳粒子,板壳运动、厚度/法向、Johnson-Cook 路线下的板壳失效和撕裂初步能力 | +| 0.7 | 水-气-结构局部爆炸 smoke,覆盖气体膨胀、气泡诊断和结构响应 | +| 0.8 | SPH 与 FEMLite 的接触耦合,覆盖 SPH-FEM facet 载荷交换和运动边界 | +| 0.9 | SPH 与 FEMLite 的连续体耦合,覆盖 `Solid` 与 FEMLite 实体、`Shell` 与 FEMLite 壳的界面或重叠区耦合 | +| 1.0 | 船舱局部水下接触爆炸破坏综合 benchmark | + +## 4. 关键物理路线 + +水体模型长期需要支持水下爆炸近场所需的可压缩 SPH 或 Riemann-SPH。早期版本允许先使用弱可压 SPH 建立粒子、邻域、时间推进、输出和验证框架。 + +`Gas` 的第一批 EOS 为 JWL 和理想气体。JWL 用于爆轰产物气体,理想气体用于空气或低压气体。Stiffened gas、tabular EOS 和混合气体高级模型作为后续扩展。 + +`Explosive` 的主路线是解析点火、爆轰传播和炸药粒子反应。球面经验载荷模型不得作为主模型,只能作为校核、边界载荷或对比工具。 + +结构模型的初步目标是 Johnson-Cook 材料模型和 Johnson-Cook 失效模型。基础弹性响应可作为单元测试和算法调试所需的退化路径,但交付目标应面向率相关塑性、损伤和失效。 + +FEM-SPH 连续体耦合是核心需求,不应简化为接触问题。连续体耦合应支持同一结构连续体中一部分使用 FEMLite 计算、另一部分使用 SPHLite 计算。具体方法,如节点投影、重叠区耦合或界面约束,放入算法和接口文档继续讨论。 + +## 5. 工程接口需求 + +- 软件应提供 C ABI,作为 C++、Python 和 FEMLite 耦合的稳定边界。 +- C++ 接口可用于内部实现和高级调用。 +- Python 接口先用于调试、算例生成、后处理和验收检查,不要求第一阶段提供完整绑定。 +- 与 FEMLite 的耦合应通过明确的数据契约完成,不直接依赖 FEMLite 内部数据库。 +- 所有可失败接口必须返回错误码,并提供可查询的错误消息。 + +## 6. 当前不交付范围 + +以下能力不应放入初始版本默认交付: + +- 完整整船级水下爆炸长算例。 +- 工业级高精度爆轰化学反应模型。 +- 完整多材料断裂和焊缝失效库。 +- 大规模并行和 GPU 后端。 +- 生产级 FEM-SPH 强耦合非线性隐式算法。 +- 完整商业软件输入文件兼容。 + +## 7. 质量要求 + +- 每个新增物理能力必须有小型、可重复的测试或 checker。 +- 不支持的物理模型、材料模型或输入关键字必须明确报错,不得静默回退。 +- 默认验证算例应小而可控,长跑和研究算例不进入默认 release gate。 +- 输出文件、临时结果、大型 CSV/VTK/restart 不应提交到源码仓库。 +- 文档使用 UTF-8 without BOM 编码。 + +## 8. 待讨论问题 + +- 第一版输入格式采用自定义关键字、JSON/YAML,还是类 Abaqus 风格。 +- 可压缩 SPH/Riemann-SPH 的引入版本和验收算例。 +- Johnson-Cook 参数、单位系统和失效删除/软化策略。 +- `Shell` 的法向、转角或 director 表达方式。 +- FEM-SPH 连续体耦合第一版采用节点投影、重叠区还是界面约束。 diff --git a/docs/02_software_architecture_design.md b/docs/02_software_architecture_design.md new file mode 100644 index 0000000..b943fac --- /dev/null +++ b/docs/02_software_architecture_design.md @@ -0,0 +1,151 @@ +# 02 软件架构设计 + +文档状态:规划确认稿 + +## 1. 架构概览 + +SPHLite 采用与 FEMLite 一致的 Fortran 95 风格过程式模块架构。核心求解器使用 Fortran 编写并遵守 Fortran 95 规范;C API/ABI、C++ 薄包装和 Python API 作为接口层提供,不作为核心求解实现语言。 + +推荐的数据流: + +```text +输入层 -> 数据库 -> 粒子/材料/物理模块 -> 显式求解器 -> 输出/API +``` + +SPHLite 是求解器,不负责几何、网格或粒子生成。测试和示例可以使用 Python 脚本生成 Abaqus 风格 `.inp` 输入文件,但这些脚本属于测试/示例辅助工具,不作为求解器功能。 + +SPHLite 的支持环境、构建方式和工具链要求应与 FEMLite 保持一致。 + +## 2. 主要模块 + +| 模块 | 职责 | +|---|---| +| `Core` | 精度、错误、日志、生命周期、控制参数 | +| `Input` | Abaqus `.inp` 子集解析和 `*SPHLITE ...` 扩展关键词解析 | +| `Database` | 集中管理粒子、集合、材料、section、phase、时间状态和模块状态 | +| `Particle` | 粒子状态、粒子族、邻域搜索、核函数 | +| `Material` | 水、气体、炸药、金属、壳材料和损伤参数 | +| `Water` | 水体、压力、人工黏性、冲击波和自由界面 | +| `Gas` | 气体 EOS、气体粒子、气体团簇和气泡诊断 | +| `Explosive` | 起爆、爆轰到达时间、反应进度和能量释放 | +| `Solid` | 3D 固体结构、应力更新、塑性、损伤、断裂 | +| `Shell` | 板壳粒子、厚度、法向/转角、膜弯剪和撕裂 | +| `CouplingInterface` | 面向外部耦合模块的中立数据交换接口和耦合诊断 | +| `Solver` | Velocity-Verlet 显式时间推进、子循环、稳定时间步估计 | +| `Output` | CSV、VTK、restart、诊断和 benchmark 指标 | +| `Interface` | Fortran API、C ABI、C++ 薄包装、Python API、CLI | + +## 3. 模块边界 + +- `Explosive` 只负责炸药反应和能量释放,不直接实现气泡脉动。 +- `Gas` 负责气体相状态、EOS、气体界面和气泡诊断。 +- `Water` 负责水相运动和水中压力传播。 +- `Solid` 和 `Shell` 分别处理实体结构粒子和板壳结构粒子,不互相伪装。 +- `CouplingInterface` 只定义中立耦合数据、边界导出、载荷导入和诊断统计,不依赖 FEMLite,也不依赖外部耦合模块内部实现。 +- 外部耦合模块暂称 `CouplingModule`,后续可能命名为 `CoupleLite`、`CoupledLite` 或 `CouplingLite`。该模块不属于 SPHLite 内部依赖。 + +## 4. 输入与模型识别 + +SPHLite 应解析 Abaqus `.inp` 文件的明确子集,不追求完整 Abaqus 兼容。能复用 Abaqus 关键词时不新增关键词;Abaqus 无法表达的 SPHLite 专有能力统一使用 `*SPHLITE ...` 扩展关键词。 + +输入识别原则: + +- 水、气、炸药和实体结构均作为 3D 实体粒子处理。 +- 板壳结构为 2D 几何,通过 section 识别板壳属性。 +- 水、气、炸药、实体结构和板壳结构通过 material 识别物理类型和本构/EOS 参数。 +- set 只表示集合,可包含同种或不同种类的粒子,不能作为类型判断依据。 +- 不影响程序运行的未支持关键词应 warning 后跳过。 +- 关键词缺失或不支持导致程序无法运行时应报 error。 +- 单位系统与 FEMLite/Abaqus 风格一致,程序不做内置单位换算,用户负责保持单位一致。 + +## 5. 数据库与粒子状态 + +SPHLite 采用集中型数据库。所有粒子的通用状态由 `Database` 统一管理,包括 id、phase、material、section、位置、速度、加速度、质量、密度、压力、体积和时间状态。 + +水和气有本质区别,计算模块保持独立;但水粒子和气粒子共享同一套粒子通用数据结构。`Water` 和 `Gas` 只维护各自计算所需的派生状态、EOS 状态、诊断量和临时工作数组。 + +phase 允许在计算中改变,例如炸药粒子可逐步转化为气体 phase。`Explosive` 同时预留两种路线: + +- 同一粒子从 explosive phase 迁移到 gas phase。 +- 炸药粒子保留自身状态,并向 `Gas` 注入质量、动量和能量源项。 + +## 6. 时间推进 + +SPHLite 只支持显式动力学时间推进。求解器采用 Velocity-Verlet 作为唯一主时间积分格式。 + +架构中不保留隐式求解、静力求解、非线性静力求解或隐式-显式混合求解接口。后续如需引入子循环,也应服务于显式动力学主流程。 + +## 7. 外部耦合边界 + +SPHLite 不直接与 FEMLite 耦合,也不引用 FEMLite 模块作为依赖。SPHLite 只通过中立耦合数据契约与外部耦合模块交换数据。外部耦合模块再负责与 FEMLite 或其他求解器通信。 + +SPHLite 侧应提供: + +- 导出 SPH 侧耦合区域的粒子状态、边界面、法向、面积、速度和材料/phase 信息。 +- 导入外部耦合模块提供的节点力、面力、体力、位移/速度约束或连续体界面交换量。 +- 记录耦合功、动量交换、能量交换和错误诊断。 +- 区分接触耦合和连续体耦合,不将连续体耦合简化为接触。 + +SPHLite 输入文件只定义 SPHLite 侧 coupling region 和交换变量。外部求解器侧区域由外部耦合模块或其配置文件匹配。 + +## 8. Restart 和输出 + +restart 应按完整模块级别设计,能够恢复显式动力学继续计算所需的全部状态。第一版至少应在格式上预留: + +- 粒子通用状态。 +- 时间控制、步数、输出计数和 Velocity-Verlet 所需的当前/历史加速度或半步状态。 +- 水相状态和气体状态。 +- 炸药反应进度、爆轰到达状态和源项累计量。 +- `Solid` 应力、塑性、损伤和失效状态。 +- `Shell` 厚度、法向/转角、积分点、损伤和撕裂状态。 +- 耦合历史量、功、动量和能量诊断。 +- 邻域搜索重建所需控制参数。 + +## 9. 构建产物和接口层 + +SPHLite 建议采用与 FEMLite 类似的产物分层: + +- `sphlite_core`:Fortran 核心库。 +- `sphlite_c`:C ABI 薄包装库。 +- `sphlite`:命令行程序。 +- C++ wrapper:薄包装 C ABI。 +- Python API:优先使用 `ctypes` 包装 C ABI。 + +命令行程序作为一等入口,语法风格应与 FEMLite 保持一致,例如读取 `.inp` 文件并执行显式动力学分析。 + +## 10. 建议目录结构 + +```text +include/ + sphlite_c_api.h +src/ + core/ + input/ + database/ + particle/ + material/ + water/ + gas/ + explosive/ + solid/ + shell/ + coupling_interface/ + solver/ + output/ + interface/ +Python/ +tests/ +examples/ +tools/ +docs/ +``` + +不设置 `geometry/` 或 `mesh/` 目录。SPHLite 不承担几何建模、网格生成或粒子生成职责。 + +## 11. 待讨论问题 + +- Abaqus 子集的第一批关键词清单。 +- `*SPHLITE ...` 扩展关键词的详细语法。 +- Velocity-Verlet restart 中半步速度和加速度的保存约定。 +- Python inp 生成器的目录组织和示例规范。 +- 外部耦合模块最终命名和配置文件边界。 diff --git a/docs/03_detailed_design.md b/docs/03_detailed_design.md new file mode 100644 index 0000000..c48fafa --- /dev/null +++ b/docs/03_detailed_design.md @@ -0,0 +1,245 @@ +# 03 详细设计 + +文档状态:规划确认稿 + +## 1. 设计原则 + +SPHLite 核心使用 Fortran 95 实现,详细设计采用集中数组数据库和过程式模块协作方式。核心状态集中存放在 `sph_database` 一类模块中,物理模块围绕数据库读取通用状态、维护自身派生状态,并通过显式求解器推进。 + +SPHLite 不采用面向对象的粒子类设计。输入文件中的 `*NODE` id 作为 external id 读取,数据库内部统一按 particle 管理。 + +## 2. 数据库分层 + +SPHLite 采用集中型数据库,推荐分层如下: + +| 层级 | 职责 | +|---|---| +| 通用粒子状态 | id、phase、material、section、位置、速度、加速度、质量、密度、压力、体积 | +| 输入映射 | external node id、external element id、set、section、material 名称和内部 id 映射 | +| 物理状态 | 水相、气相、炸药、实体结构、板壳结构的模块状态 | +| 求解状态 | 当前时间、步数、dt、Velocity-Verlet 中间量和稳定时间步 | +| 诊断状态 | 质量、动量、能量、气泡指标、损伤统计、耦合交换量 | +| restart 状态 | 恢复继续计算所需的所有模块级状态 | + +set 来源于输入文件,只表示用户集合,可包含同种或不同种类粒子。region 是运行时区域,由 set、material、section、phase 或扩展关键词解析得到,用于输出、耦合或模块选择。 + +## 3. 通用粒子状态 + +第一阶段建议 `sph_database` 至少保存以下通用数组: + +```fortran +integer :: npart +integer, allocatable :: particle_id_ext(:) +integer, allocatable :: particle_phase(:) +integer, allocatable :: particle_status(:) +integer, allocatable :: material_id(:) +integer, allocatable :: section_id(:) +real(rk), allocatable :: x0(:,:) +real(rk), allocatable :: x(:,:) +real(rk), allocatable :: v(:,:) +real(rk), allocatable :: a(:,:) +real(rk), allocatable :: vhalf(:,:) +real(rk), allocatable :: mass(:) +real(rk), allocatable :: rho(:) +real(rk), allocatable :: volume(:) +real(rk), allocatable :: pressure(:) +real(rk), allocatable :: internal_energy(:) +real(rk), allocatable :: temperature(:) +real(rk), allocatable :: h(:) +``` + +数组形状约定: + +- `x0(3,npart)`:参考坐标。 +- `x(3,npart)`:当前坐标。 +- `v(3,npart)`:当前速度。 +- `a(3,npart)`:当前加速度。 +- `vhalf(3,npart)`:Velocity-Verlet 或等价显式推进所需的半步速度。 +- `h(npart)`:每粒子独立光滑长度。 + +Velocity-Verlet restart 应保存 `v`、`a` 和 `vhalf` 三类速度/加速度相关状态,保证继续计算路径可恢复。 + +## 4. Phase、Material 和 Section + +SPHLite 使用 `phase + material_id + section_id + set/region` 分层识别计算行为: + +- `phase` 决定粒子当前由哪个物理模块处理。 +- `material_id` 决定 EOS、本构和失效参数。 +- `section_id` 决定实体或板壳 section 属性。 +- `set` 保留输入集合语义,不参与类型判断。 +- `region` 表示运行时计算区域、输出区域或耦合区域。 + +建议 phase 枚举至少预留: + +- `PHASE_WATER` +- `PHASE_GAS` +- `PHASE_EXPLOSIVE` +- `PHASE_SOLID` +- `PHASE_SHELL` +- `PHASE_BOUNDARY` +- `PHASE_COUPLING` +- `PHASE_SOLID_FAILED` +- `PHASE_SHELL_FAILED` + +phase 改变是不可逆历史过程。爆炸反应、气体生成、结构失效和板壳撕裂均可通过 phase 和 status 的组合表达。 + +默认不删除粒子。失效、破裂或不再参与某些模块计算的粒子通过 `particle_status` 和 `particle_phase` 控制。 + +## 5. 邻域搜索和核函数 + +第一阶段邻域搜索采用 uniform cell/bin 方法,不引入复杂树结构。数据库或 `Particle` 模块应维护: + +- cell 尺寸和空间范围。 +- 每粒子所属 cell。 +- cell 链表或压缩索引。 +- 全局邻域表。 +- 搜索半径和每粒子 `h(i)`。 + +邻域表采用全局搜索,模块内部按 phase、material、section 或 region 过滤相互作用。这样可避免多张邻域表之间不同步。 + +核函数模块应提供: + +- 核函数值。 +- 核函数梯度。 +- 支持半径。 +- 与每粒子 `h(i)` 相关的归一化系数。 + +## 6. Water 状态 + +水相通用位置、速度、密度、压力等数据保存在数据库中。`Water` 维护水相计算所需的参数、派生量和临时工作数组。 + +第一阶段 `Water` 至少需要: + +- 水相 EOS 参数。 +- 人工黏性或后续 Riemann 通量参数。 +- 密度变化率或连续方程临时量。 +- 水相压力、加速度和能量贡献诊断。 +- 自由面或边界标记的运行时缓存。 + +水相计算只处理 phase 为水或与水存在相互作用的 region。水和气共享粒子数据库,但计算模块保持独立。 + +## 7. Gas 状态 + +`Gas` 负责气体相状态、气体 EOS、气体团簇和气泡诊断。第一批 EOS 为 JWL 和理想气体。 + +`Gas` 至少维护: + +- 气体 EOS 类型和参数。 +- 气体内能、温度或等效能量相关派生量。 +- 气体团簇 id 和团簇统计。 +- 气体总体积、中心、平均压力和最大压力。 +- 等效气泡半径、半径变化率、脉动周期和中心迁移指标。 +- 来自 `Explosive` 的质量、动量和能量源项累计量。 + +气泡不是一级模块,而是 `Gas` 在水介质中的现象和诊断分支。 + +## 8. Explosive 状态 + +`Explosive` 负责炸药点火、爆轰传播、反应进度和能量释放。第一阶段需要同时预留两条路线: + +- 同一粒子从 explosive phase 不可逆迁移到 gas phase。 +- 炸药粒子保留自身状态,并向 `Gas` 注入质量、动量和能量源项。 + +建议状态包括: + +```fortran +real(rk), allocatable :: detonation_time(:) +real(rk), allocatable :: reaction_progress(:) +real(rk), allocatable :: gas_mass_source(:) +real(rk), allocatable :: gas_energy_source(:) +real(rk), allocatable :: gas_momentum_source(:,:) +integer, allocatable :: ignition_status(:) +``` + +其中 `gas_momentum_source(3,npart)` 使用列主序形状。 + +restart 必须保存爆轰到达状态、反应进度和源项累计量。 + +## 9. Solid 状态 + +`Solid` 面向 3D 实体结构粒子,初步目标是 Johnson-Cook 材料模型和 Johnson-Cook 失效模型。基础弹性状态可作为调试和退化路径,但交付目标应面向率相关塑性、损伤和失效。 + +建议第一阶段保存: + +- 参考构型和当前构型。 +- 变形梯度或修正梯度相关状态。 +- Cauchy 应力或等价应力状态。 +- 等效塑性应变。 +- 等效塑性应变率。 +- 温度或等效温升。 +- Johnson-Cook 损伤变量。 +- 失效状态。 +- 内力和能量诊断。 + +失效后不删除粒子。结构失效粒子通过 `PHASE_SOLID_FAILED` 和 status 表达,后续可进入碎片、接触或自由面处理。 + +## 10. Shell 状态 + +`Shell` 面向板壳粒子,采用 Mindlin-Reissner 板壳理论路线。板壳是 2D 几何,通过 section 识别厚度、积分点和板壳属性。 + +建议第一阶段保存: + +```fortran +real(rk), allocatable :: shell_thickness(:) +real(rk), allocatable :: shell_director(:,:) +real(rk), allocatable :: shell_omega(:,:) +real(rk), allocatable :: shell_membrane_strain(:,:) +real(rk), allocatable :: shell_bending_strain(:,:) +real(rk), allocatable :: shell_shear_strain(:,:) +real(rk), allocatable :: shell_damage(:) +integer, allocatable :: shell_failure_status(:) +``` + +其中: + +- `shell_director(3,npart)` 表示板壳 director 或法向。 +- `shell_omega(3,npart)` 表示角速度或转动相关状态。 +- 厚度积分点材料状态应预留独立数组或压缩存储。 + +板壳失效后使用 `PHASE_SHELL_FAILED` 和 status 表达,后续可进入撕裂、穿孔、碎片或接触处理。 + +## 11. CouplingInterface 状态 + +SPHLite 内部不实现外部耦合模块,也不依赖 FEMLite。内部只提供 `CouplingInterface`,用于导出和导入中立耦合数据。 + +`CouplingInterface` 应维护或生成: + +- SPHLite 侧 coupling region。 +- 耦合粒子 id、坐标、速度、phase、material 和 section。 +- 耦合边界面或近似面片的几何、法向和面积。 +- 外部导入的节点力、面力、体力、位移/速度约束或连续体交换量。 +- 耦合功、动量交换、能量交换和错误诊断。 + +接触耦合和连续体耦合必须在状态和诊断中区分。外部耦合模块暂称 `CouplingModule`,后续可改名。 + +## 12. 壳-实体连接占位 + +壳粒子与实体粒子的连接不作为第一阶段交付能力。数据库和接口可以预留 connection 或 interface region 概念,后续用于: + +- 壳-实体结构连接。 +- 壳-实体连续体耦合。 +- 局部壳模型和实体模型过渡。 + +第一阶段不要求实现连接算法。 + +## 13. Diagnostics 和 Restart + +诊断状态至少包括: + +- 总质量、总动量、总能量。 +- 水相压力和冲量指标。 +- 气体体积、平均压力和等效气泡半径。 +- 炸药反应进度统计。 +- `Solid` 损伤和失效数量。 +- `Shell` 损伤、撕裂和失效数量。 +- 耦合功、动量交换和能量交换。 + +restart 应保存完整模块级状态。任何影响继续计算路径的状态都不能只作为临时量存在。 + +## 14. 待讨论问题 + +- phase 枚举的具体整数值。 +- 粒子 status 枚举。 +- 第一批 Abaqus `.inp` 粒子 element type 和 section 约定。 +- 厚度积分点数量和存储布局。 +- restart 文件格式和版本号。 diff --git a/docs/04_mathematical_model_and_algorithms.md b/docs/04_mathematical_model_and_algorithms.md new file mode 100644 index 0000000..fd445aa --- /dev/null +++ b/docs/04_mathematical_model_and_algorithms.md @@ -0,0 +1,202 @@ +# 04 数学模型与算法 + +文档状态:规划确认稿 + +## 1. 总体算法路线 + +SPHLite 第一阶段采用弱可压 SPH 作为主框架,显式动力学作为唯一时间推进方式。水体、气体、炸药、3D 实体结构和板壳结构共享统一粒子数据库,但各物理模块按 phase、material、section 和 region 独立选择计算路径。 + +总体路线: + +- 水相:弱可压 SPH + Tait EOS + Monaghan 人工黏性。 +- 气相:JWL、理想气体和 Stiffened gas EOS。 +- 爆炸:解析点火、爆轰到达时间和 programmed burn 反应进度。 +- 3D 结构:Total Lagrangian / corrected Lagrangian SPH + Johnson-Cook 材料与失效。 +- 板壳结构:Mindlin-Reissner 板壳理论 + 厚度积分。 +- 时间推进:Velocity-Verlet。 +- 耦合:SPHLite 仅提供中立交换算法,外部耦合模块负责跨求解器匹配和投影。 + +Riemann-SPH 或其他可压缩强冲击格式作为后续近场冲击升级方向,不进入第一阶段主算法。 + +## 2. SPH 核函数 + +第一阶段默认核函数为 Wendland C2。Wendland C4 作为可选核函数,cubic spline 保留为对比和回归测试用核函数。 + +核函数模块应提供: + +- 核函数值 `W(r,h)`。 +- 核函数梯度 `grad W(r,h)`。 +- 支持半径。 +- 与每粒子独立光滑长度 `h(i)` 对应的归一化系数。 + +每个粒子保存独立 `h(i)`。第一阶段不做随时间自动自适应更新,但允许不同粒子使用不同初始光滑长度。 + +## 3. 水相模型 + +水相采用弱可压 SPH。密度演化采用连续性方程,不保留 summation density 作为主流程或辅助校正工具。 + +第一阶段水体 EOS 为 Tait EOS。水相压力由密度和参考声速等参数计算。具体参数和单位由输入文件给定,SPHLite 不做内置单位换算。 + +水相动量方程包含: + +- 压力梯度项。 +- Monaghan 型人工黏性项。 +- 外部体力或边界/耦合载荷。 +- 与气体、结构或边界粒子相互作用产生的等效贡献。 + +诊断指标至少包括: + +- 水相总质量。 +- 水相动量。 +- 压力峰值。 +- 冲量。 +- 时间步稳定约束贡献。 + +## 4. 人工黏性和强冲击升级 + +第一阶段采用 Monaghan 型人工黏性。人工黏性参数,如 `alpha` 和 `beta`,应由输入控制,默认建议值放入用户手册或示例说明。 + +Riemann-SPH、Godunov-SPH 或其他强冲击格式作为后续升级方向,用于近场水下爆炸强冲击和更严格的波传播计算。第一阶段只在接口和文档中保留升级方向,不进入默认交付。 + +## 5. 气体模型 + +`Gas` 第一阶段支持三类 EOS: + +- JWL EOS:用于爆轰产物气体。 +- 理想气体 EOS:用于空气或低压气体。 +- Stiffened gas EOS:作为压缩气体备选模型。 + +`Gas` 负责气体压力、内能、温度或等效能量状态,并提供气体团簇和气泡诊断。 + +气泡不是独立一级模块,而是 `Gas` 在水介质中的现象和诊断分支。气泡诊断至少包括: + +- 气体总体积。 +- 气体中心。 +- 平均压力和最大压力。 +- 等效气泡半径。 +- 半径变化率。 +- 脉动周期估计。 +- 气泡中心迁移。 + +第一阶段水-气界面不做复杂界面重构,采用粒子相间基础压力/动量交换和气体团簇统计。 + +## 6. 爆炸模型 + +`Explosive` 采用解析点火和 programmed burn 路线。 + +算法状态包括: + +- 起爆点。 +- 起爆时间。 +- 爆速。 +- 每个炸药粒子的爆轰到达时间 `td(i)`。 +- 反应进度 `lambda(i)`,范围为 `0 <= lambda <= 1`。 +- 向 `Gas` 注入的质量、动量和能量源项。 + +爆轰到达后,炸药粒子按照反应时间窗口或输入控制参数更新 `lambda(i)`。反应进度增长产生的质量、动量和能量进入 `Gas`。 + +SPHLite 同时预留两种实现路线: + +- 炸药粒子从 explosive phase 不可逆迁移到 gas phase。 +- 炸药粒子保留 explosive phase 或反应后状态,并向 gas phase 注入源项。 + +球面经验载荷模型不作为主模型,只可作为校核、边界载荷或对比工具。 + +## 7. 3D Solid 结构模型 + +`Solid` 面向 3D 实体结构粒子,采用 Total Lagrangian / corrected Lagrangian SPH 路线。参考构型和当前构型分离,参考邻域可用于提高大变形结构计算稳定性。 + +`Solid` 主结构材料路线为 Johnson-Cook 材料模型和 Johnson-Cook 失效模型。弹性或简化 J2 路径可作为调试和回归测试的退化路径,但不作为长期主线。 + +`Solid` 算法应覆盖: + +- 变形梯度或修正梯度。 +- 应变率和应力更新。 +- Johnson-Cook 流动应力。 +- 温度或等效温升。 +- 应变率效应。 +- Johnson-Cook 损伤累积。 +- 失效后的渐进软化。 +- 内力、动能、内能和损伤能量诊断。 + +Johnson-Cook 热项应保留温度变量和温升/热软化接口。第一阶段允许等温退化测试,但 restart 和数据库中必须保存温度状态。 + +## 8. 结构失效和断裂处理 + +结构损伤达到失效阈值后,不删除粒子。SPHLite 通过不可逆 phase/status 改变表达结构失效: + +- 实体结构失效后可进入 `PHASE_SOLID_FAILED`。 +- 板壳结构失效后可进入 `PHASE_SHELL_FAILED`。 + +失效后采用渐进软化策略降低承载能力,而不是瞬时删除粒子。失效粒子后续可参与碎片、自由面或接触处理。 + +断裂、碎片和后续接触的完整算法可分阶段实现。第一阶段文档和状态中必须预留失效 phase、status、损伤变量和软化状态。 + +## 9. Shell 板壳模型 + +`Shell` 面向 2D 几何板壳粒子,采用 Mindlin-Reissner 板壳理论。板壳厚度、积分点和材料参数通过 section 识别。 + +`Shell` 算法应覆盖: + +- 中面平动。 +- director 或法向更新。 +- 角速度或转动相关状态。 +- 膜应变。 +- 弯曲应变。 +- 横向剪切应变。 +- 厚度积分点材料更新。 +- 板壳损伤、渐进软化、撕裂和穿孔状态。 + +厚度积分点数量由 section 选择。第一阶段支持 3 点和 5 点厚度积分,默认 3 点,5 点用于更高精度或强非线性板壳响应。 + +剪切修正系数和具体厚度积分权重由 section 或材料设置给出,默认值在用户手册中说明。 + +## 10. 时间推进 + +SPHLite 采用 Velocity-Verlet 作为唯一主时间积分格式。求解器不提供隐式求解、静力求解或非线性静力求解接口。 + +时间步估计取以下约束的最小值后乘安全系数: + +- CFL 声速约束。 +- 加速度约束。 +- 黏性约束。 +- `Solid` 结构波速约束。 +- `Shell` 平动和转动约束。 +- 外部耦合或边界交换约束。 + +安全系数由输入控制,不在算法文档中写死固定默认值。 + +Velocity-Verlet restart 必须保存继续计算所需的速度、加速度和半步速度状态。 + +## 11. 水-气-结构相互作用 + +第一阶段水、气和结构之间采用基于粒子邻域的基础相互作用: + +- 水-气之间交换压力和动量贡献。 +- 水-结构之间形成压力和接触/边界等效载荷。 +- 气-结构之间形成气体压力载荷。 +- 炸药反应通过 `Gas` 向水和结构传递爆炸产物压力和能量。 + +复杂界面重构、锐界面追踪、相变蒸发和高阶多相 Riemann 通量作为后续扩展。 + +## 12. CouplingInterface 算法边界 + +SPHLite 不在内部实现 FEM-SPH 匹配、投影或强/弱耦合控制策略。这些由外部耦合模块负责。 + +SPHLite 侧只提供中立交换算法: + +- 按 coupling region 导出粒子状态、phase、material、section、坐标、速度和诊断量。 +- 导出 SPH 侧边界近似面片、法向、面积和速度。 +- 接收外部模块给出的节点力、面力、体力、位移/速度约束或连续体交换量。 +- 在显式时间步中施加外部载荷或约束。 +- 记录外部耦合功、动量交换、能量交换和错误状态。 + +接触耦合和连续体耦合必须在输入、状态和诊断中区分。SPHLite 输入文件只定义 SPHLite 侧 coupling region 和交换变量。 + +## 13. 待讨论问题 + +- Tait、JWL、理想气体和 Stiffened gas 的输入参数命名。 +- Monaghan 人工黏性默认参数建议值。 +- Johnson-Cook 温升模型和热软化默认选项。 +- 渐进软化曲线的第一版形式。 +- `Shell` 剪切修正默认值和厚度积分权重。 diff --git a/docs/05_interface_control_document.md b/docs/05_interface_control_document.md new file mode 100644 index 0000000..1ef0e9d --- /dev/null +++ b/docs/05_interface_control_document.md @@ -0,0 +1,274 @@ +# 05 接口控制文档 + +文档状态:规划确认稿 + +## 1. 接口原则 + +SPHLite 核心使用 Fortran 95 实现。公共接口分层如下: + +- Fortran API:核心主接口,由 Fortran 模块提供。 +- C ABI:长期稳定公共接口,统一使用 `sphlite_` 前缀。 +- C++ API:薄包装 C ABI,不重新定义物理语义。 +- Python API:优先使用 `ctypes` 包装 C ABI。 +- CLI:命令行入口,语法风格与 FEMLite 保持一致。 + +所有可失败接口必须返回错误码。调用失败后应能查询最近错误码和错误消息。 + +C ABI 第一阶段只支持 host 内存指针,不设计 GPU 内存接口。多维数组按 Fortran 顺序展平到 C 缓冲区。 + +## 2. 错误和生命周期接口 + +生命周期接口沿用 FEMLite 风格: + +```c +int sphlite_initialize(void); +int sphlite_finalize(void); +int sphlite_get_version(int *major, int *minor, int *patch); +int sphlite_get_last_error(int *code, char *message, int message_capacity); +``` + +错误约定: + +- C 参数错误,如空指针、非正容量或非法数组尺寸,返回 `-1`。 +- 输入、物理模型、求解流程或数据库校验错误返回 SPHLite 错误码。 +- 错误消息由 `sphlite_get_last_error` 查询。 +- 不支持且影响继续计算的能力必须报 error。 +- 不影响程序运行的未支持输入项可 warning 后跳过。 + +## 3. 输入、构建和显式求解接口 + +SPHLite 只提供显式动力学接口,不提供 static、implicit 或 nonlinear static 接口。 + +建议 C ABI: + +```c +int sphlite_read_inp(const char *filename); +int sphlite_build_model(void); +int sphlite_estimate_stable_dt(double *dtcrit); +int sphlite_advance_explicit(double dt); +int sphlite_run_explicit(void); +int sphlite_get_current_time(double *time, int *step); +``` + +接口语义: + +- `sphlite_read_inp` 读取 Abaqus `.inp` 支持子集和 `*SPHLITE ...` 扩展关键词。 +- `sphlite_build_model` 校验数据库,构建运行时 region、邻域搜索参数、section/material 映射等派生数据。 +- `sphlite_estimate_stable_dt` 返回当前状态下的显式稳定时间步估计。 +- `sphlite_advance_explicit` 执行一个 Velocity-Verlet 显式步,供外部耦合模块逐步驱动。 +- `sphlite_run_explicit` 按输入文件时间控制连续运行。 + +## 4. 输出和 Restart 接口 + +建议 C ABI: + +```c +int sphlite_set_output_directory(const char *path); +int sphlite_set_output_interval(int interval); +int sphlite_write_output(int step, double time); +int sphlite_write_restart(const char *filename); +int sphlite_read_restart(const char *filename); +``` + +restart 应保存完整模块级状态,包括粒子通用状态、Velocity-Verlet 所需速度/加速度/半步速度、水相、气相、炸药、Solid、Shell、诊断和耦合历史状态。 + +输出接口只控制输出行为,不应改变求解物理状态。 + +## 5. Phase 和 Status 常量 + +C 头文件应暴露 phase/status 常量,便于 C++、Python、外部耦合模块和后处理工具解释粒子状态。 + +建议 phase 常量: + +```c +#define SPHLITE_PHASE_WATER 1 +#define SPHLITE_PHASE_GAS 2 +#define SPHLITE_PHASE_EXPLOSIVE 3 +#define SPHLITE_PHASE_SOLID 4 +#define SPHLITE_PHASE_SHELL 5 +#define SPHLITE_PHASE_BOUNDARY 6 +#define SPHLITE_PHASE_COUPLING 7 +#define SPHLITE_PHASE_SOLID_FAILED 8 +#define SPHLITE_PHASE_SHELL_FAILED 9 +``` + +具体整数值可在实现前最终锁定,但文档、C 头文件、Fortran 常量和 Python 包装必须保持一致。 + +## 6. 粒子查询接口 + +粒子查询采用 dimension query + caller-allocated buffer 风格。 + +建议 C ABI: + +```c +int sphlite_get_particle_count(int *count); + +int sphlite_get_particle_state(int max_particles, + int *particle_id_ext, + int *phase, + int *status, + int *material_id, + int *section_id, + double *x, + double *v, + double *a, + double *rho, + double *pressure, + double *internal_energy, + double *temperature, + double *h, + int *count); +``` + +数组展开顺序: + +- `x[dim + 3 * particle]` +- `v[dim + 3 * particle]` +- `a[dim + 3 * particle]` + +其中 `dim = 0,1,2`,`particle = 0 .. count-1`。该顺序对应 Fortran 数组 `x(3,npart)` 的列主序展开。 + +## 7. Gas 和爆炸诊断接口 + +Gas 诊断接口应体现气泡只是 Gas 在水介质中的现象和诊断分支。 + +建议 C ABI: + +```c +int sphlite_get_gas_summary(double *volume, + double *center, + double *mean_pressure, + double *max_pressure); + +int sphlite_get_gas_bubble_metrics(double *equivalent_radius, + double *radius_rate, + double *center); +``` + +`center` 使用三维向量缓冲区,展开为: + +- `center[dim]` + +Explosive 的主输入来自 `.inp`。为调试和测试可保留起爆点设置接口: + +```c +int sphlite_set_ignition_point(double x, double y, double z, double time); +``` + +该接口不替代 `.inp` 输入语义,主要用于单元测试、Python 调试和小型 smoke。 + +## 8. CouplingInterface 接口 + +SPHLite 不直接依赖 FEMLite,也不依赖外部 CouplingModule。C ABI 中不得出现 `fem` 命名或 FEMLite 内部数据结构。 + +CouplingInterface 使用中立命名,必须支持每步交换。 + +建议 C ABI: + +```c +int sphlite_get_coupling_particle_count(const char *region, + int *count); + +int sphlite_get_coupling_particles(const char *region, + int max_particles, + int *particle_id_ext, + int *phase, + int *material_id, + int *section_id, + double *x, + double *v, + double *pressure, + int *count); + +int sphlite_get_coupling_facet_count(const char *region, + int *num_facets, + int *max_face_particles); + +int sphlite_get_coupling_facets(const char *region, + int num_facets, + int max_face_particles, + int *facet_id, + int *facet_npart, + int *facet_particles, + double *x, + double *v, + double *normal, + double *area); + +int sphlite_apply_coupling_particle_forces(int num_particles, + const int *particle_id_ext, + const double *forces); + +int sphlite_apply_coupling_facet_loads(int num_facets, + int max_face_particles, + const int *facet_id, + const int *facet_npart, + const double *particle_forces); +``` + +数组展开顺序: + +- `x[dim + 3 * particle]` for particle arrays。 +- `forces[dim + 3 * particle]`。 +- `facet_particles[local + max_face_particles * facet]`。 +- `particle_forces[dim + 3 * (local + max_face_particles * facet)]`。 +- `normal[dim + 3 * facet]`。 + +接口语义: + +- `region` 为 SPHLite 侧 coupling region 名称。 +- 外部耦合模块负责 FEM-SPH 匹配、投影和强/弱耦合控制策略。 +- SPHLite 只导出状态和边界近似,导入外部载荷或约束。 +- 接触耦合和连续体耦合应在 region 或后续接口参数中区分。 + +## 9. Fortran API 和 C ABI 关系 + +Fortran API 是核心语义来源。C ABI 只做薄包装: + +- 不改变 Fortran API 的物理含义。 +- 不暴露 Fortran 内部 allocatable 数组指针。 +- 所有输出数组由调用方分配。 +- C wrapper 负责空指针、容量和字符串长度检查。 +- Fortran 侧负责物理校验、数据库校验和错误消息。 + +字符串从 C 传入 Fortran 时应按 FEMLite 风格传递字符缓冲区和长度,避免依赖编译器私有字符串 ABI。 + +## 10. C++ 和 Python 接口 + +C++ API 是 C ABI 的薄包装,主要提供 RAII 生命周期管理和类型更友好的调用封装,不维护独立物理语义。 + +Python API 第一阶段使用 `ctypes` 包装 C ABI,用于: + +- 调试。 +- 示例生成和运行。 +- smoke/checker。 +- 后处理和诊断读取。 + +Python API 不应成为唯一可用入口;CLI 和 C ABI 必须保持完整可用。 + +## 11. CLI 接口原则 + +命令行程序 `sphlite` 作为一等入口,语法风格与 FEMLite 保持一致。 + +建议最小用法: + +```powershell +sphlite model.inp --run +``` + +后续可扩展: + +- 输出目录参数。 +- restart 读写参数。 +- 只检查输入/模型的 inspect 模式。 +- 调试诊断开关。 + +CLI 内部应调用 Fortran API 或 C ABI 等稳定入口,不绕过公共生命周期和错误处理。 + +## 12. 待讨论问题 + +- 第一批 `*SPHLITE ...` 扩展关键词与 C API 字段的对应关系。 +- phase/status 具体整数值和头文件宏名是否在 0.1 锁定。 +- coupling region 的字符串命名规则。 +- facet 近似生成方式和 facet id 稳定性。 +- restart 文件格式和 C API 版本兼容策略。 diff --git a/docs/06_test_and_verification_plan.md b/docs/06_test_and_verification_plan.md new file mode 100644 index 0000000..e62d021 --- /dev/null +++ b/docs/06_test_and_verification_plan.md @@ -0,0 +1,162 @@ +# 06 测试与验证计划 + +文档状态:规划确认稿 + +## 1. 测试原则 + +SPHLite 测试体系仿照 FEMLite,采用 CMake + CTest + Python checker + release gate。核心求解器使用 Fortran 95,因此单元测试和模块测试以 Fortran 小程序为主。C ABI、C++ wrapper、Python API 和 CLI 作为接口层分别测试。 + +测试设计原则: + +- 新物理能力必须配套小型、可重复测试或 checker。 +- 默认 release gate 只包含快速、稳定、小规模测试。 +- 长跑、工程 benchmark 和研究项不进入默认 gate。 +- C ABI 是第一优先接口测试对象。 +- C++ wrapper 测试保留,但不作为 0.1 最小 gate 必选项。 +- Python 基础 smoke 纳入默认 gate。 +- 从第一版开始启用 source size 门禁。 + +## 2. 测试分层 + +| 层级 | 目标 | +|---|---| +| 单元测试 | 核函数、邻域搜索、EOS、Velocity-Verlet、Johnson-Cook 材料点、Mindlin-Reissner 局部量 | +| 输入测试 | Abaqus `.inp` 子集、`*SPHLITE ...` 扩展关键词、warning/error 路径 | +| 模块测试 | Water、Gas、Explosive、Solid、Shell、CouplingInterface | +| 接口测试 | Fortran API、C ABI、C++ wrapper、Python `ctypes`、CLI | +| 示例 smoke | 小型可运行模型,检查方向、量级和关键输出 | +| benchmark | 带 checker 的紧凑工程验收 | +| 外部集成测试 | 与外部 CouplingModule/FEMLite 的联合验证,不属于 SPHLite 默认 gate | +| release gate | 当前版本发布前必须通过的组合测试 | + +## 3. 第一批默认测试 + +第一批默认测试按长期能力逐步扩展。0.1.0 的默认 gate 只覆盖工程骨架、接口、最小输入、最小显式步进和 source size;下列物理项在对应版本实现后再进入默认 gate: + +- Wendland C2 核函数归一性和梯度反对称性。 +- Wendland C4 和 cubic spline 对比/回归测试。 +- uniform cell/bin 邻域搜索与朴素搜索一致性。 +- Tait EOS 压力计算。 +- JWL EOS 压力计算。 +- 理想气体 EOS 压力计算。 +- Stiffened gas EOS 压力计算。 +- Monaghan 人工黏性方向和量级。 +- Velocity-Verlet 自由运动、恒力或简化振动步进。 +- 水相连续性方程小算例。 +- 小型压力波 smoke。 +- 解析爆轰到达时间。 +- programmed burn 反应进度 `lambda`。 +- 气体团簇体积和等效气泡半径统计。 +- Johnson-Cook 材料点。 +- Johnson-Cook 失效与渐进软化材料点。 +- Mindlin-Reissner 板壳小变形 smoke。 +- C ABI 空指针、非正容量和小缓冲区错误。 +- Python `ctypes` 基础 smoke。 + +## 4. 输入解析测试 + +SPHLite 支持 Abaqus `.inp` 明确子集,不追求完整 Abaqus 兼容。输入测试必须覆盖: + +- `*NODE`。 +- `*ELEMENT`。 +- `*NSET`。 +- `*ELSET`。 +- `*MATERIAL`。 +- `*SECTION` 或等价 section 关键词。 +- `*SPHLITE ...` 扩展关键词。 +- 未支持但不影响运行的关键词 warning。 +- 缺失关键数据或无法继续运行的 error。 +- set 只表示集合,不作为类型判断依据。 +- material 和 section 对 phase/物理路径的识别。 + +输入解析测试应同时覆盖 CLI 路径和 API 路径。 + +## 5. 模块测试顺序 + +模块测试按开发路线递进: + +1. `Water`:核函数、邻域、Tait EOS、连续性方程、压力波 smoke。 +2. `Gas`:JWL、理想气体、Stiffened gas、气体团簇和气泡诊断。 +3. `Explosive`:爆轰到达时间、反应进度、质量/动量/能量源项。 +4. `Solid`:Johnson-Cook 材料点、失效和渐进软化。 +5. `Shell`:Mindlin-Reissner 小变形、厚度积分点选择。 +6. `CouplingInterface`:中立耦合状态导出、外力导入、耦合功和能量诊断。 + +## 6. CouplingInterface 测试边界 + +SPHLite 默认 gate 不包含真正 FEM-SPH 联合测试。外部 CouplingModule、FEMLite 或其他求解器的联合运行属于外部集成测试。 + +SPHLite 仓库内只测试中立接口: + +- coupling region 解析。 +- coupling particles 导出。 +- coupling facets 或近似面片导出。 +- 外部粒子力、面力或体力导入。 +- 显式步内载荷施加。 +- 耦合功、动量交换和能量交换统计。 +- 接触耦合和连续体耦合诊断字段区分。 + +## 7. 0.1 Release Gate 草案 + +0.1 release gate 建议包含: + +```powershell +cmake --build build-codex-gcc --parallel +ctest --test-dir build-codex-gcc -R "^(smoke|input|c_api|python_debug)$" --output-on-failure +ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure +git diff --check +``` + +其中: + +- `smoke` 覆盖 Fortran 生命周期、数据库、最小显式步。 +- `input` 覆盖 `.inp` 支持子集和 warning/error。 +- `c_api` 覆盖 C ABI 生命周期、查询和错误路径。 +- `python_debug` 覆盖 Python `ctypes` 基础调用。 +- `source_size` 控制单文件和单过程持续膨胀。 + +实际 build 目录和测试名称可在代码实现阶段按 CMake 配置调整。 + +## 8. Source Size 门禁 + +从第一版开始设置 source size 门禁。建议沿用 FEMLite 风格: + +- 普通过程设置 review target 和 hard limit。 +- 普通源文件设置 review target 和 hard limit。 +- 必要例外登记到例外清单。 +- stale exception 应被检查。 + +具体阈值可在实现阶段与 FEMLite 保持一致或按 SPHLite 文件结构微调。 + +## 9. 非默认长跑和研究项 + +以下内容不进入默认 release gate: + +- 自由场水下爆炸工程曲线。 +- 气泡多周期脉动。 +- 板壳穿孔、撕裂和碎片云。 +- 舱段局部水下接触爆炸破坏。 +- FEM-SPH 联合长算例。 +- 大规模粒子数性能测试。 +- 近场强冲击 Riemann-SPH 对比。 +- 多材料复杂断裂和焊缝失效。 + +这些内容应作为非默认 benchmark、研究项或外部集成测试维护,并配套独立 checker 和运行说明。 + +## 10. 文档与产物检查 + +发布前必须确认: + +- README 和 01-11 文档与当前版本能力一致。 +- 默认 gate 结果写入版本历史和 benchmark 矩阵。 +- 输出目录、CSV、VTK、restart 和大型临时结果不提交。 +- Python 生成器仅作为测试/示例辅助工具,不宣传为求解器几何或粒子生成功能。 +- 文档使用 UTF-8 without BOM。 + +## 11. 待讨论问题 + +- 0.1 source size 具体阈值。 +- 第一批 CTest 测试名称和 label。 +- Python checker 的目录组织。 +- 非默认 benchmark 的运行入口和命名。 +- 外部集成测试与 CouplingModule 仓库的边界。 diff --git a/docs/07_user_manual.md b/docs/07_user_manual.md new file mode 100644 index 0000000..7748932 --- /dev/null +++ b/docs/07_user_manual.md @@ -0,0 +1,49 @@ +# 07 用户手册 + +文档状态:规划初稿 + +## 1. 软件用途 + +SPHLite 用于船舶水下接触爆炸相关的 SPH 多物理仿真,包括水体运动、爆炸产物气体、气泡脉动、结构大变形、板壳破裂和 FEM-SPH 耦合。 + +## 2. 预期工作流 + +典型工作流: + +1. 准备水域、船体结构、炸药和边界输入。 +2. 设置材料、EOS、爆炸点火和时间控制。 +3. 运行 SPHLite 或通过 CouplingModule 与 FEMLite 联合运行。 +4. 输出压力、速度、结构变形、损伤、气体体积和气泡指标。 +5. 使用 Python checker 或后处理脚本检查验收指标。 + +## 3. 输入内容草案 + +未来用户输入应覆盖: + +- 粒子几何和初始状态。 +- 水、气体、炸药、实体结构和板壳材料。 +- EOS 参数,如 Tait、JWL、理想气体。 +- 起爆点、起爆时间和爆速。 +- 时间步、输出间隔和稳定性参数。 +- FEM-SPH 耦合区域和边界。 + +## 4. 输出内容草案 + +建议输出: + +- 粒子位置、速度、密度、压力。 +- 结构位移、速度、应力、塑性应变、损伤。 +- 壳粒子厚度、法向、膜/弯曲状态和失效。 +- 气体体积、中心、平均压力、等效气泡半径。 +- 耦合界面力、功、能量和动量残差。 +- CSV、VTK 和 restart。 + +## 5. 当前限制 + +当前项目还未实现求解器。本文档仅记录目标用户体验和后续输入/输出设计方向。 + +## 6. 待讨论问题 + +- 输入格式采用自定义文本、JSON/YAML,还是类 Abaqus 关键字。 +- 输出是否优先 VTK,还是先 CSV smoke。 +- 用户侧如何描述 FEM-SPH 连续体耦合区域。 diff --git a/docs/08_developer_manual.md b/docs/08_developer_manual.md new file mode 100644 index 0000000..e456d76 --- /dev/null +++ b/docs/08_developer_manual.md @@ -0,0 +1,55 @@ +# 08 开发者手册 + +文档状态:规划初稿 + +## 1. 基本原则 + +- 只修改 SPHLite 仓库内文件;FEMLite 只作为参考和外部耦合对象。 +- 默认采用小步、可测试、可闭环的开发方式。 +- 新物理模型必须配套最小测试或 checker。 +- 不支持的输入和物理能力必须明确报错。 +- 不提交 build、临时结果、大型 CSV/VTK/restart。 +- 文档使用 UTF-8 without BOM。 + +## 2. 构建建议 + +SPHLite 构建体系应仿照 FEMLite: + +- CMake 作为主构建系统。 +- CTest 作为测试入口。 +- C ABI 作为稳定接口。 +- Python3 用于测试脚本和调试入口。 +- 可选 OpenMP 用于邻域搜索或接触搜索加速。 + +## 3. 新增模块流程 + +新增模块建议遵循: + +1. 明确模块边界和数据所有权。 +2. 增加最小数据结构和生命周期。 +3. 增加单元测试。 +4. 增加 C ABI 或内部接口。 +5. 增加模块级 smoke。 +6. 更新相关文档和 benchmark 矩阵。 + +## 4. 新增 API 流程 + +- 优先使用 dimension query + value-fill query。 +- 写输出前验证 id、索引和缓冲区容量。 +- C ABI 空指针或非正容量返回 `-1`。 +- 多维数组展开顺序必须写入接口文档。 +- API 不应暴露内部容器指针。 + +## 5. 耦合开发规则 + +- 接触耦合和连续体耦合必须分开实现、分开测试。 +- FEMLite 适配层不得侵入 SPHLite 核心物理模块。 +- 耦合接口应记录质量、动量、能量或功的交换量。 +- 第一版不追求复杂强耦合,优先建立可验证的数据契约。 + +## 6. 待讨论问题 + +- C++ 标准版本。 +- 命名风格和目录风格。 +- 单文件和单函数大小限制。 +- 是否与 FEMLite 使用相同 release gate 命名。 diff --git a/docs/09_release_history.md b/docs/09_release_history.md new file mode 100644 index 0000000..50c01d3 --- /dev/null +++ b/docs/09_release_history.md @@ -0,0 +1,64 @@ +# 09 版本历史与验收记录 + +文档状态:0.1.0 开发中 + +## 1. 当前状态 + +SPHLite 当前正在搭建 0.1.0 工程骨架版本。该版本只交付可编译、可测试、可扩展的求解器框架,不交付生产级物理算法。 + +## 2. 规划版本线 + +| 版本线 | 目标 | +|---|---| +| 0.1.0 | 工程骨架、生命周期、错误码、C ABI、CLI、Python 调试入口和测试框架 | +| 0.2 | 粒子状态、核函数、邻域搜索和基础 `Water` | +| 0.3 | `Gas`、基础 EOS、气体统计和气泡诊断 | +| 0.4 | `Explosive`、解析点火、爆轰传播和产物气体注入 | +| 0.5 | 3D `Solid` 弹塑性、损伤和基础破裂 | +| 0.6 | `Shell` 板壳变形、损伤和撕裂 | +| 0.7 | 水-气-结构局部爆炸 smoke | +| 0.8 | SPH-FEM 接触耦合 | +| 0.9 | SPH-FEM 连续体耦合 | +| 1.0 | 船舱局部破坏综合 benchmark | + +## 3. 验收记录 + +### 0.1.0 本地验收记录 + +记录日期:2026-07-02 + +本地构建目录:`build-codex-unix` + +构建配置: + +```powershell +cmake -S . -B build-codex-unix -G "Unix Makefiles" -DCMAKE_C_COMPILER=C:/gcc-16.1.0-64/bin/gcc.exe -DCMAKE_Fortran_COMPILER=C:/gcc-16.1.0-64/bin/gfortran.exe -DCMAKE_MAKE_PROGRAM=C:/gcc-16.1.0-64/bin/make.exe +cmake --build build-codex-unix --parallel +``` + +验收结果: + +- `sphlite_core`、`sphlite_c` 和 `sphlite` 完整编译通过。 +- `ctest -R "^(smoke|input|c_api|python_debug)$"` 通过,4/4。 +- `ctest -R "^source_size$"` 通过,1/1。 +- `git diff --check` 通过。 +- CLI inspect 模式通过:`sphlite tests/data/minimal_particles.inp`。 +- CLI run 模式通过:`sphlite tests/data/minimal_particles.inp --run`。 +- 已通过 `.gitignore` 排除 build 目录、CSV/VTK/restart 临时结果和 Python 缓存。 +- 文档已明确 0.1.0 不交付生产级 Water、Gas、Explosive、Solid、Shell 物理算法。 + +说明:当前目录已初始化本地 git 仓库,并设置远端 `origin` 为 `http://123.57.213.67:3062/shen/SPHLite.git`,尚未执行提交或推送。 + +后续每个版本应记录: + +- 完成能力。 +- 明确不交付范围。 +- 本地构建命令。 +- CTest 结果。 +- benchmark/checker 结果。 +- 已知限制。 + +## 4. 待讨论问题 + +- 是否需要在 0.3 前完成最小可视化输出。 +- 0.8 和 0.9 是否拆分为独立大版本。 diff --git a/docs/10_development_roadmap.md b/docs/10_development_roadmap.md new file mode 100644 index 0000000..50802f7 --- /dev/null +++ b/docs/10_development_roadmap.md @@ -0,0 +1,76 @@ +# 10 后续开发路线图 + +文档状态:规划初稿 + +## 1. 路线图原则 + +- 每个版本只选择可闭环目标。 +- 研究长跑不进入默认 release gate。 +- 新物理能力必须先有小模型、接口边界和测试矩阵。 +- 接触耦合和连续体耦合分开规划。 +- `Gas` 作为气体相通用模块,气泡作为气体相在水中的现象和诊断。 + +## 2. 阶段 1:工程与粒子基础 + +建议目标: + +1. CMake/CTest 工程骨架。 +2. C ABI 生命周期和错误码。 +3. 粒子状态、核函数和邻域搜索。 +4. CSV/VTK 最小输出。 +5. Python smoke/checker。 + +## 3. 阶段 2:水、气和爆炸 + +建议目标: + +1. 弱可压水体 SPH。 +2. `Gas` 基础 EOS 和气体统计。 +3. 气泡等效半径和体积诊断。 +4. `Explosive` 解析点火和爆轰到达时间。 +5. 爆轰产物向 `Gas` 注入。 + +## 4. 阶段 3:结构粒子 + +建议目标: + +1. 3D `Solid` 弹性。 +2. J2 或 Johnson-Cook 塑性。 +3. 损伤和粒子失效。 +4. `Shell` 小变形基础。 +5. `Shell` 损伤、撕裂和穿孔。 + +## 5. 阶段 4:耦合 + +建议目标: + +1. SPH 对 FEM facet 的压力/节点力投影。 +2. FEM facet 运动驱动 SPH 边界。 +3. `Solid` 与 FEM solid 连续体耦合。 +4. `Shell` 与 FEM shell 连续体耦合。 +5. 耦合能量、动量和功诊断。 + +## 6. 阶段 5:应用 benchmark + +建议目标: + +1. 水下自由场爆炸。 +2. 气泡脉动。 +3. 水冲击弹塑性板。 +4. 舱段局部接触爆炸。 +5. SPH-FEM 混合船体局部破坏。 + +## 7. 延期能力 + +- GPU 后端。 +- 大规模并行。 +- 完整化学反应爆轰。 +- 完整整船长时程水下爆炸。 +- 生产级隐式强耦合。 +- 完整商业输入兼容。 + +## 8. 待讨论问题 + +- 0.1 到 0.3 是否应先完成输入格式。 +- 爆炸和气体是否放在同一大版本。 +- FEM-SPH 连续体耦合的第一批 benchmark 如何定义。 diff --git a/docs/11_benchmark_matrix.md b/docs/11_benchmark_matrix.md new file mode 100644 index 0000000..db4e17b --- /dev/null +++ b/docs/11_benchmark_matrix.md @@ -0,0 +1,83 @@ +# 11 Benchmark 与验收矩阵 + +文档状态:0.1.0 gate 草案 + +## 1. 当前状态 + +0.1.0 不交付工程 benchmark,只建立 release gate 和 source size 门禁。后续物理 benchmark 矩阵保留为长期规划。 + +## 2. 0.1.0 Release Gate + +| 测试名 | 类型 | 验收点 | +|---|---|---| +| `smoke` | Fortran smoke | 生命周期、版本号、数据库最小分配、显式步进 | +| `input` | Fortran input | 最小 `.inp`、unknown keyword warning、关键数据缺失 error | +| `c_api` | C ABI | 生命周期、空指针错误、输入、查询、显式步进 | +| `python_debug` | Python `ctypes` | 加载 C ABI、读取最小 `.inp`、查询粒子数、显式运行 | +| `source_size` | 工具门禁 | Fortran/C 文件大小、Fortran 过程大小、stale exception | + +0.1.0 不验收 Water、Gas、Explosive、Solid、Shell 的生产级物理结果,也不验收真实 FEM-SPH 联合运行。 + +本地验收记录: + +| 日期 | 构建目录 | 结果 | +|---|---|---| +| 2026-07-02 | `build-codex-unix` | `smoke`、`input`、`c_api`、`python_debug`、`source_size` 和 `git diff --check` 均通过 | + +## 3. 基础数值矩阵 + +| 领域 | 测试或 benchmark | 验收点 | +|---|---|---| +| 核函数 | kernel 单测 | 归一性、梯度方向、紧支撑 | +| 邻域搜索 | neighbor 单测 | 与朴素搜索一致 | +| 水体 EOS | Tait EOS 单测 | 压力量级和单调性 | +| 气体 EOS | JWL/理想气体单测 | 压力、能量和单位一致 | +| 爆轰传播 | ignition 单测 | 到达时间和反应进度 | +| 气体团簇 | gas summary 单测 | 体积、中心、等效半径 | + +## 4. 水下爆炸矩阵 + +| 领域 | 代表算例 | 验收点 | +|---|---|---| +| 压力波 | 1D 水中压力传播 | 波速、峰值、数值耗散 | +| 自由场爆炸 | 小装药水域 | 压力峰值和冲量 | +| 气泡脉动 | 单气泡膨胀回缩 | 最大半径、周期、中心迁移 | +| 流固载荷 | 水冲击刚性板 | 法向压力和冲量 | + +## 5. 结构矩阵 + +| 领域 | 代表算例 | 验收点 | +|---|---|---| +| `Solid` 弹性 | 单轴拉伸 | 应力应变曲线 | +| `Solid` 塑性 | 高速拉伸/压缩 | 屈服和塑性功 | +| `Solid` 断裂 | 缺口拉伸 | 损伤局部化和断裂路径 | +| `Shell` 变形 | 悬臂板/简支板 | 位移方向和量级 | +| `Shell` 破裂 | 薄板冲击 | 穿孔、撕裂和能量 | + +## 6. 耦合矩阵 + +| 领域 | 代表算例 | 验收点 | +|---|---|---| +| SPH-FEM 接触 | SPH 压力作用 FEM facet | 合力、方向、能量 | +| FEM 驱动边界 | 运动 FEM facet 驱动水体 | 边界速度和压力响应 | +| `Solid` 连续体耦合 | `Solid` - FEM 实体拉伸 | 位移连续、力平衡 | +| `Shell` 连续体耦合 | `Shell` - FEM 壳弯曲 | 转角/位移连续、力矩平衡 | +| 混合舱段 | 局部 FEM + 局部 SPH 舱段爆炸 | 破坏模式和耦合诊断 | + +## 7. 默认 gate 与非默认长跑 + +默认 gate 应只包含小型、快速、稳定的测试。 + +非默认长跑包括: + +- 大水域自由场爆炸。 +- 长时程气泡脉动。 +- 复杂舱段破坏。 +- SPH-FEM 混合整船局部模型。 +- 高分辨率断裂和碎片云。 + +## 8. 待讨论问题 + +- 第一版 benchmark 是否需要真实工程量纲。 +- 气泡脉动验收采用解析近似、实验曲线还是参考软件结果。 +- 结构破裂 checker 采用定量阈值还是形态分类。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..2e486f8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# SPHLite 文档索引 + +文档状态:规划初稿 + +SPHLite 文档结构仿照 FEMLite,采用 01-11 固定编号文件维护需求、架构、算法、接口、测试、路线图和验收矩阵。 + +| 文档 | 内容 | +|---|---| +| [01 需求规格说明](01_requirements_specification.md) | 软件定位、目标能力、非目标能力和质量要求 | +| [02 软件架构设计](02_software_architecture_design.md) | 模块划分、数据流、耦合架构和工程边界 | +| [03 详细设计](03_detailed_design.md) | 核心数据结构、模块内部职责和关键对象 | +| [04 数学模型与算法](04_mathematical_model_and_algorithms.md) | SPH、气体、爆炸、结构、断裂和耦合算法 | +| [05 接口控制文档](05_interface_control_document.md) | C/C++/Python 接口、FEMLite 耦合接口和数据布局 | +| [06 测试与验证计划](06_test_and_verification_plan.md) | 测试分层、验证路线、release gate 和检查器 | +| [07 用户手册](07_user_manual.md) | 用户侧输入、运行、输出和结果解释 | +| [08 开发者手册](08_developer_manual.md) | 开发约定、代码组织、接口规则和测试要求 | +| [09 版本历史与验收记录](09_release_history.md) | 版本目标、完成状态和验收证据 | +| [10 后续开发路线图](10_development_roadmap.md) | 阶段计划、优先级和延期能力 | +| [11 Benchmark 与验收矩阵](11_benchmark_matrix.md) | 代表算例、验收指标和默认/非默认 gate | + +## 当前讨论重点 + +- `Gas` 是否作为所有气体相的统一模块。 +- `Explosive` 如何向 `Gas` 注入爆轰产物。 +- 水、气、结构三类粒子的统一状态表示。 +- 3D 实体粒子和板壳粒子的不同结构模型。 +- SPH-FEM 接触耦合与连续体耦合的接口契约。 diff --git a/docs/v1.0_development_plan.md b/docs/v1.0_development_plan.md new file mode 100644 index 0000000..2563170 --- /dev/null +++ b/docs/v1.0_development_plan.md @@ -0,0 +1,398 @@ +# SPHLite v1.0 开发计划 + +文档状态:0.1.0 开发计划稿 + +目标软件版本:SPHLite 0.1.0 + +依据文档: + +- `01_requirements_specification.md` +- `02_software_architecture_design.md` +- `03_detailed_design.md` +- `04_mathematical_model_and_algorithms.md` +- `05_interface_control_document.md` +- `06_test_and_verification_plan.md` + +## 1. 版本定位 + +SPHLite 0.1.0 是工程骨架版本,目标是先把软件框架搭起来,为后续 Water、Gas、Explosive、Solid、Shell 和 CouplingInterface 的物理实现提供稳定基础。 + +0.1.0 不追求完整 SPH 物理能力,不交付水下爆炸、气泡脉动、结构断裂或外部 FEM-SPH 联合计算。该版本的核心价值是建立可编译、可测试、可扩展、接口边界清晰的 Fortran 95 求解器框架。 + +## 2. 版本目标 + +0.1.0 应完成: + +- 与 FEMLite 一致风格的 CMake/CTest 工程骨架。 +- Fortran 95 核心库 `sphlite_core`。 +- C ABI 薄包装库 `sphlite_c`。 +- 命令行程序 `sphlite`。 +- 最小 Python `ctypes` 调试入口。 +- Fortran API 生命周期、错误码、日志和版本接口。 +- 集中型数据库的最小粒子状态。 +- Abaqus `.inp` 子集解析框架。 +- `*SPHLITE ...` 扩展关键词解析框架。 +- Velocity-Verlet 显式推进的最小骨架。 +- 输出、restart、CouplingInterface 的占位接口。 +- 0.1 release gate 和 source size 门禁。 + +## 3. 明确不交付范围 + +0.1.0 不交付: + +- 完整 Water 弱可压 SPH。 +- Gas EOS 的生产计算路径。 +- Explosive programmed burn 真实能量释放。 +- Solid Johnson-Cook 应力更新和失效。 +- Shell Mindlin-Reissner 板壳计算。 +- 真实水-气-结构相互作用。 +- 外部 CouplingModule、CoupleLite、CoupledLite 或 CouplingLite。 +- 与 FEMLite 的联合运行。 +- 几何、网格或粒子生成能力。 +- 工程 benchmark 和长跑算例。 + +0.1.0 可保留模块占位、接口占位和小型 smoke,但不得将占位写成已实现物理能力。 + +## 4. 目录结构 + +0.1.0 建议建立以下目录: + +```text +include/ + sphlite_c_api.h +src/ + core/ + input/ + database/ + particle/ + material/ + water/ + gas/ + explosive/ + solid/ + shell/ + coupling_interface/ + solver/ + output/ + interface/ + app/ +Python/ +tests/ + unit/ + module/ + interface/ + data/ +tools/ + testing/ +examples/ +docs/ +``` + +不设置 `geometry/` 或 `mesh/` 目录。Python 输入生成脚本只允许作为 `tools/` 或 `examples/` 的辅助工具存在,不作为求解器功能。 + +## 5. 构建目标 + +0.1.0 建议 CMake 目标: + +| 目标 | 类型 | 内容 | +|---|---|---| +| `sphlite_core` | static library | Fortran 95 核心模块 | +| `sphlite_c` | static library | C ABI wrapper | +| `sphlite` | executable | 命令行程序 | +| `test_smoke` | executable | Fortran 生命周期和数据库 smoke | +| `test_input` | executable | `.inp` 解析 smoke | +| `test_c_api` | executable | C ABI smoke | + +构建要求: + +- 使用 CMake。 +- 使用 CTest。 +- Fortran 标准遵守 Fortran 95。 +- 支持环境和 FEMLite 保持一致。 +- C ABI wrapper 使用 C。 +- Python 测试使用系统 Python3。 + +## 6. Fortran 核心模块 + +0.1.0 最小 Fortran 模块: + +| 模块 | 初始职责 | +|---|---| +| `sph_precision` | 精度、版本号和基础常量 | +| `sph_error` | 错误码、最近错误消息、错误清理 | +| `sph_log` | 日志打开、关闭和基础消息 | +| `sph_control` | 时间控制、输出控制和默认参数 | +| `sph_database` | 集中粒子数据库和生命周期 | +| `sph_input_reader` | `.inp` 文件读取框架 | +| `sph_api_state` | 初始化状态 | +| `sph_api` | Fortran 公共 API | +| `sph_solver_explicit` | Velocity-Verlet 最小步进框架 | +| `sph_output_csv` | 最小 CSV 输出占位 | +| `sph_restart` | restart 读写占位 | +| `sph_coupling_interface` | 中立耦合接口占位 | + +物理模块 `Water`、`Gas`、`Explosive`、`Solid`、`Shell` 在 0.1.0 中可建立模块文件和空生命周期/诊断占位,但不实现生产物理算法。 + +## 7. 数据库最小状态 + +0.1.0 数据库至少支持: + +```fortran +integer :: npart +integer, allocatable :: particle_id_ext(:) +integer, allocatable :: particle_phase(:) +integer, allocatable :: particle_status(:) +integer, allocatable :: material_id(:) +integer, allocatable :: section_id(:) +real(rk), allocatable :: x0(:,:) +real(rk), allocatable :: x(:,:) +real(rk), allocatable :: v(:,:) +real(rk), allocatable :: a(:,:) +real(rk), allocatable :: vhalf(:,:) +real(rk), allocatable :: mass(:) +real(rk), allocatable :: rho(:) +real(rk), allocatable :: volume(:) +real(rk), allocatable :: pressure(:) +real(rk), allocatable :: internal_energy(:) +real(rk), allocatable :: temperature(:) +real(rk), allocatable :: h(:) +``` + +0.1.0 可先实现: + +- 分配和释放。 +- 默认初始化。 +- 粒子数量查询。 +- external id 保存。 +- phase/status/material/section 默认值。 +- `x0(3,npart)` 和 `x(3,npart)` 保存。 + +复杂物理状态可先预留字段,不要求完整填充。 + +## 8. 输入解析范围 + +0.1.0 支持 Abaqus `.inp` 子集解析框架。第一批建议解析: + +- `*NODE` +- `*ELEMENT` +- `*NSET` +- `*ELSET` +- `*MATERIAL` +- `*SECTION` 或当前约定的 section 关键词 +- `*SPHLITE ...` 扩展关键词框架 + +0.1.0 不要求完整 Abaqus 兼容。未支持但不影响运行的关键词 warning 后跳过;缺失关键数据或导致无法运行的输入 error。 + +最小可运行 `.inp` 应能定义一组 3D 粒子节点、基本材料、section 和显式时间控制。 + +## 9. Fortran API 范围 + +0.1.0 Fortran API 至少包括: + +```fortran +subroutine sph_initialize(ierr) +subroutine sph_finalize(ierr) +subroutine sph_get_version(major, minor, patch, ierr) +subroutine sph_get_last_error(code, message, ierr) +subroutine sph_read_inp(filename, ierr) +subroutine sph_build_model(ierr) +subroutine sph_estimate_stable_dt(dtcrit, ierr) +subroutine sph_advance_explicit(dt, ierr) +subroutine sph_run_explicit(ierr) +subroutine sph_get_current_time(time, step, ierr) +subroutine sph_get_particle_count(count, ierr) +``` + +0.1.0 可以让 `sph_advance_explicit` 执行最小 Velocity-Verlet 骨架:更新时间、步数和基础运动状态,但不要求完整 Water/Gas/Solid/Shell 力学。 + +## 10. C ABI 范围 + +0.1.0 C ABI 至少包括: + +```c +int sphlite_initialize(void); +int sphlite_finalize(void); +int sphlite_get_version(int *major, int *minor, int *patch); +int sphlite_get_last_error(int *code, char *message, int message_capacity); +int sphlite_read_inp(const char *filename); +int sphlite_build_model(void); +int sphlite_estimate_stable_dt(double *dtcrit); +int sphlite_advance_explicit(double dt); +int sphlite_run_explicit(void); +int sphlite_get_current_time(double *time, int *step); +int sphlite_get_particle_count(int *count); +``` + +C 头文件应定义 phase 常量: + +```c +#define SPHLITE_PHASE_WATER 1 +#define SPHLITE_PHASE_GAS 2 +#define SPHLITE_PHASE_EXPLOSIVE 3 +#define SPHLITE_PHASE_SOLID 4 +#define SPHLITE_PHASE_SHELL 5 +#define SPHLITE_PHASE_BOUNDARY 6 +#define SPHLITE_PHASE_COUPLING 7 +#define SPHLITE_PHASE_SOLID_FAILED 8 +#define SPHLITE_PHASE_SHELL_FAILED 9 +``` + +C 参数错误返回 `-1`。Fortran 物理、输入或数据库错误返回 SPHLite 错误码。 + +## 11. CLI 范围 + +0.1.0 命令行程序 `sphlite` 应支持最小用法: + +```powershell +sphlite model.inp --run +``` + +建议同时支持 inspect 模式: + +```powershell +sphlite model.inp +``` + +inspect 模式输出: + +- 版本号。 +- 粒子数量。 +- 当前时间和步数。 +- 输入是否成功。 +- 基础 warning/error 摘要。 + +CLI 语法风格应与 FEMLite 保持一致。 + +## 12. Python 范围 + +0.1.0 Python 只提供最小调试入口: + +- 使用 `ctypes` 加载 C ABI。 +- 调用生命周期接口。 +- 读取 `.inp`。 +- 查询粒子数量。 +- 运行一个最小 smoke。 + +Python 生成器可放在 `tools/` 或 `examples/`,用于生成测试 `.inp`,但不作为求解器几何或粒子生成功能宣传。 + +## 13. 测试计划 + +0.1.0 测试优先级: + +1. Fortran 生命周期 smoke。 +2. 数据库分配、释放和粒子数量查询。 +3. `.inp` 最小输入解析。 +4. unsupported keyword warning。 +5. 缺失关键数据 error。 +6. C ABI 生命周期和空指针错误。 +7. CLI inspect/run smoke。 +8. Python `ctypes` smoke。 +9. source size 门禁。 + +暂不进入 0.1.0 默认 gate: + +- Water 真实压力波 benchmark。 +- Gas EOS 生产路径。 +- Explosive 真实能量释放。 +- Solid/Shell 材料点。 +- CouplingInterface 联合外部模块测试。 + +## 14. 0.1.0 Release Gate + +建议 release gate: + +```powershell +cmake --build build-codex-gcc --parallel +ctest --test-dir build-codex-gcc -R "^(smoke|input|c_api|python_debug)$" --output-on-failure +ctest --test-dir build-codex-gcc -R "^source_size$" --output-on-failure +git diff --check +``` + +验收标准: + +- 完整编译通过。 +- `smoke` 通过。 +- `input` 通过。 +- `c_api` 通过。 +- `python_debug` 通过。 +- `source_size` 通过。 +- `git diff --check` 通过。 +- 文档状态与实际能力一致。 + +## 15. 开发阶段拆分 + +### 阶段 A:工程骨架 + +- 建立目录结构。 +- 建立 CMakeLists。 +- 建立 Fortran 核心库。 +- 建立空 CLI。 +- 建立最小 CTest。 + +### 阶段 B:Core 和 Database + +- 实现 `sph_precision`。 +- 实现 `sph_error`。 +- 实现 `sph_log`。 +- 实现 `sph_control`。 +- 实现 `sph_database` 分配、释放和最小查询。 + +### 阶段 C:Input 和 API + +- 实现 `.inp` 读取框架。 +- 支持 `*NODE` 最小解析。 +- 支持基础 material/section 占位。 +- 实现 Fortran API 生命周期和输入接口。 + +### 阶段 D:C ABI 和 CLI + +- 生成 Fortran-C 名字修饰头。 +- 实现 `include/sphlite_c_api.h`。 +- 实现 C wrapper。 +- 实现 `sphlite` CLI inspect/run。 + +### 阶段 E:Solver、Output、Restart 占位 + +- 实现 Velocity-Verlet 最小步进。 +- 实现稳定时间步占位。 +- 实现输出目录和输出间隔接口。 +- 实现 restart 占位接口。 + +### 阶段 F:测试和 Gate + +- 建立 Fortran smoke。 +- 建立 input smoke。 +- 建立 C ABI smoke。 +- 建立 Python debug smoke。 +- 建立 source size 检查。 +- 跑通 0.1.0 release gate。 + +## 16. 风险和控制 + +| 风险 | 控制 | +|---|---| +| 0.1.0 范围膨胀到物理算法 | 只实现框架和占位,物理能力推迟到后续版本 | +| INP 解析目标过大 | 只支持明确子集,不追求完整 Abaqus 兼容 | +| C ABI 与 Fortran API 分叉 | C ABI 只做薄包装,Fortran API 是语义来源 | +| CouplingInterface 过早绑定 FEMLite | 接口命名保持中立,不出现 `fem` 依赖 | +| restart 设计不足 | 0.1.0 先建立版本化占位和模块级状态清单 | +| 文件过大 | 从第一版启用 source size 门禁 | + +## 17. 后续版本衔接 + +0.1.0 完成后,后续版本按以下方向推进: + +- 0.2:Water 基础 SPH、核函数、邻域搜索、Tait EOS、连续性方程。 +- 0.3:Gas EOS、气体统计和气泡诊断。 +- 0.4:Explosive 解析点火、爆轰传播和产物气体注入。 +- 0.5:Solid Johnson-Cook 材料与失效。 +- 0.6:Shell Mindlin-Reissner 板壳和失效。 +- 0.7 以后:水-气-结构局部爆炸、外部耦合接口和综合 benchmark。 + +## 18. 待确认事项 + +- 0.1.0 第一批 `.inp` section 关键词名称。 +- CTest 具体测试名和 label。 +- source size 门禁阈值是否完全沿用 FEMLite。 +- restart 占位文件格式是否从 0.1.0 开始版本化。 +- `sphlite` CLI inspect 输出字段格式。 diff --git a/include/sphlite.hpp b/include/sphlite.hpp new file mode 100644 index 0000000..d28acec --- /dev/null +++ b/include/sphlite.hpp @@ -0,0 +1,80 @@ +#ifndef SPHLITE_HPP +#define SPHLITE_HPP + +#include "sphlite_c_api.h" + +#include +#include + +namespace sphlite { + +struct Version { + int major; + int minor; + int patch; +}; + +class Error : public std::runtime_error { +public: + explicit Error(const std::string &message) : std::runtime_error(message) {} +}; + +inline std::string last_error_message() +{ + int code = 0; + char message[256]; + if (sphlite_get_last_error(&code, message, static_cast(sizeof(message))) != 0) { + return "SPHLite C API parameter error"; + } + return std::string(message); +} + +inline void check(int ierr) +{ + if (ierr != 0) { + throw Error(last_error_message()); + } +} + +inline void initialize() +{ + check(sphlite_initialize()); +} + +inline void finalize() +{ + check(sphlite_finalize()); +} + +inline Version version() +{ + Version result = {0, 0, 0}; + check(sphlite_get_version(&result.major, &result.minor, &result.patch)); + return result; +} + +inline void read_inp(const std::string &filename) +{ + check(sphlite_read_inp(filename.c_str())); +} + +inline void build_model() +{ + check(sphlite_build_model()); +} + +inline int particle_count() +{ + int count = 0; + check(sphlite_get_particle_count(&count)); + return count; +} + +inline void run_explicit() +{ + check(sphlite_run_explicit()); +} + +} // namespace sphlite + +#endif diff --git a/include/sphlite_c_api.h b/include/sphlite_c_api.h new file mode 100644 index 0000000..28bbd3e --- /dev/null +++ b/include/sphlite_c_api.h @@ -0,0 +1,47 @@ +#ifndef SPHLITE_C_API_H +#define SPHLITE_C_API_H + +#ifdef _WIN32 +# ifdef SPHLITE_BUILD_SHARED +# define SPHLITE_API __declspec(dllexport) +# else +# define SPHLITE_API +# endif +#else +# define SPHLITE_API +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#define SPHLITE_PHASE_WATER 1 +#define SPHLITE_PHASE_GAS 2 +#define SPHLITE_PHASE_EXPLOSIVE 3 +#define SPHLITE_PHASE_SOLID 4 +#define SPHLITE_PHASE_SHELL 5 +#define SPHLITE_PHASE_BOUNDARY 6 +#define SPHLITE_PHASE_COUPLING 7 +#define SPHLITE_PHASE_SOLID_FAILED 8 +#define SPHLITE_PHASE_SHELL_FAILED 9 + +SPHLITE_API int sphlite_initialize(void); +SPHLITE_API int sphlite_finalize(void); +SPHLITE_API int sphlite_get_version(int *major, int *minor, int *patch); +SPHLITE_API int sphlite_get_last_error(int *code, char *message, int message_capacity); +SPHLITE_API int sphlite_read_inp(const char *filename); +SPHLITE_API int sphlite_build_model(void); +SPHLITE_API int sphlite_estimate_stable_dt(double *dtcrit); +SPHLITE_API int sphlite_advance_explicit(double dt); +SPHLITE_API int sphlite_run_explicit(void); +SPHLITE_API int sphlite_get_current_time(double *time, int *step); +SPHLITE_API int sphlite_get_particle_count(int *count); +SPHLITE_API int sphlite_write_csv(const char *filename); +SPHLITE_API int sphlite_write_restart(const char *filename); +SPHLITE_API int sphlite_read_restart(const char *filename); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/app/sph_main.c b/src/app/sph_main.c new file mode 100644 index 0000000..700e245 --- /dev/null +++ b/src/app/sph_main.c @@ -0,0 +1,105 @@ +#include "sphlite_c_api.h" + +#include +#include + +static void sphlite_print_error(void) +{ + int code = 0; + char message[256]; + if (sphlite_get_last_error(&code, message, (int)sizeof(message)) == 0) { + fprintf(stderr, "SPHLite error %d: %s\n", code, message); + } +} + +static void sphlite_print_usage(void) +{ + printf("usage: sphlite model.inp [--run]\n"); +} + +int main(int argc, char **argv) +{ + int ierr; + int major = 0; + int minor = 0; + int patch = 0; + int count = 0; + int step = 0; + double time = 0.0; + int run_mode = 0; + + if (argc < 2 || argc > 3) { + sphlite_print_usage(); + return 1; + } + if (argc == 3) { + if (strcmp(argv[2], "--run") != 0) { + sphlite_print_usage(); + return 1; + } + run_mode = 1; + } + + ierr = sphlite_initialize(); + if (ierr != 0) { + sphlite_print_error(); + return 1; + } + + ierr = sphlite_get_version(&major, &minor, &patch); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + + ierr = sphlite_read_inp(argv[1]); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + + ierr = sphlite_build_model(); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + + if (run_mode) { + ierr = sphlite_run_explicit(); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + } + + ierr = sphlite_get_particle_count(&count); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + ierr = sphlite_get_current_time(&time, &step); + if (ierr != 0) { + sphlite_print_error(); + (void)sphlite_finalize(); + return 1; + } + + printf("SPHLite %d.%d.%d\n", major, minor, patch); + printf("input: %s\n", argv[1]); + printf("mode: %s\n", run_mode ? "run" : "inspect"); + printf("particles: %d\n", count); + printf("time: %.16e\n", time); + printf("step: %d\n", step); + + ierr = sphlite_finalize(); + if (ierr != 0) { + sphlite_print_error(); + return 1; + } + return 0; +} diff --git a/src/app/sph_program.f90 b/src/app/sph_program.f90 new file mode 100644 index 0000000..6cf7719 --- /dev/null +++ b/src/app/sph_program.f90 @@ -0,0 +1,37 @@ +module sph_program + use sph_error, only: SPH_SUCCESS + use sph_api, only: sph_initialize, sph_finalize, sph_read_inp, sph_build_model, & + sph_run_explicit, sph_get_particle_count, sph_get_current_time + use sph_precision, only: rk + implicit none + +contains + + subroutine sph_program_run_file(filename, run_mode, count, time, step, ierr) + character(len=*), intent(in) :: filename + logical, intent(in) :: run_mode + integer, intent(out) :: count + real(rk), intent(out) :: time + integer, intent(out) :: step + integer, intent(out) :: ierr + + count = 0 + time = 0.0_rk + step = 0 + call sph_initialize(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_read_inp(filename, ierr) + if (ierr /= SPH_SUCCESS) return + call sph_build_model(ierr) + if (ierr /= SPH_SUCCESS) return + if (run_mode) then + call sph_run_explicit(ierr) + if (ierr /= SPH_SUCCESS) return + end if + call sph_get_particle_count(count, ierr) + if (ierr /= SPH_SUCCESS) return + call sph_get_current_time(time, step, ierr) + call sph_finalize(ierr) + end subroutine sph_program_run_file + +end module sph_program diff --git a/src/core/sph_control.f90 b/src/core/sph_control.f90 new file mode 100644 index 0000000..ea7610e --- /dev/null +++ b/src/core/sph_control.f90 @@ -0,0 +1,48 @@ +module sph_control + use sph_precision, only: rk + implicit none + + real(rk), parameter :: SPH_DEFAULT_DT = 1.0e-6_rk + real(rk), parameter :: SPH_DEFAULT_END_TIME = 1.0e-6_rk + integer, parameter :: SPH_DEFAULT_MAX_STEPS = 1 + integer, parameter :: SPH_DEFAULT_OUTPUT_INTERVAL = 1 + + real(rk) :: current_time = 0.0_rk + integer :: current_step = 0 + real(rk) :: dt_default = SPH_DEFAULT_DT + real(rk) :: end_time = SPH_DEFAULT_END_TIME + integer :: max_steps = SPH_DEFAULT_MAX_STEPS + integer :: output_interval = SPH_DEFAULT_OUTPUT_INTERVAL + character(len=256) :: output_directory = 'output' + +contains + + subroutine sph_control_reset() + current_time = 0.0_rk + current_step = 0 + dt_default = SPH_DEFAULT_DT + end_time = SPH_DEFAULT_END_TIME + max_steps = SPH_DEFAULT_MAX_STEPS + output_interval = SPH_DEFAULT_OUTPUT_INTERVAL + output_directory = 'output' + end subroutine sph_control_reset + + subroutine sph_control_set_time(dt, total_time, steps) + real(rk), intent(in) :: dt + real(rk), intent(in) :: total_time + integer, intent(in) :: steps + + if (dt > 0.0_rk) dt_default = dt + if (total_time > 0.0_rk) end_time = total_time + if (steps > 0) max_steps = steps + end subroutine sph_control_set_time + + subroutine sph_control_get_time(time, step) + real(rk), intent(out) :: time + integer, intent(out) :: step + + time = current_time + step = current_step + end subroutine sph_control_get_time + +end module sph_control diff --git a/src/core/sph_error.f90 b/src/core/sph_error.f90 new file mode 100644 index 0000000..edef625 --- /dev/null +++ b/src/core/sph_error.f90 @@ -0,0 +1,41 @@ +module sph_error + use sph_precision, only: SPH_ERROR_MESSAGE_LEN + implicit none + + integer, parameter :: SPH_SUCCESS = 0 + integer, parameter :: SPH_ERROR_ARGUMENT = 1 + integer, parameter :: SPH_ERROR_STATE = 2 + integer, parameter :: SPH_ERROR_IO = 3 + integer, parameter :: SPH_ERROR_INPUT = 4 + integer, parameter :: SPH_ERROR_DATABASE = 5 + integer, parameter :: SPH_ERROR_NOT_IMPLEMENTED = 6 + + integer :: last_error_code = SPH_SUCCESS + character(len=SPH_ERROR_MESSAGE_LEN) :: last_error_message = 'OK' + +contains + + subroutine sph_error_clear() + last_error_code = SPH_SUCCESS + last_error_message = 'OK' + end subroutine sph_error_clear + + subroutine sph_error_set(code, message) + integer, intent(in) :: code + character(len=*), intent(in) :: message + + last_error_code = code + last_error_message = ' ' + last_error_message = message + end subroutine sph_error_set + + subroutine sph_error_get(code, message) + integer, intent(out) :: code + character(len=*), intent(out) :: message + + code = last_error_code + message = ' ' + message = last_error_message + end subroutine sph_error_get + +end module sph_error diff --git a/src/core/sph_log.f90 b/src/core/sph_log.f90 new file mode 100644 index 0000000..e041f60 --- /dev/null +++ b/src/core/sph_log.f90 @@ -0,0 +1,51 @@ +module sph_log + use sph_error, only: SPH_SUCCESS, SPH_ERROR_IO, sph_error_set + implicit none + + integer, parameter :: SPH_LOG_UNIT = 97 + logical :: sph_log_is_open = .false. + +contains + + subroutine sph_log_open(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + integer :: ios + + ierr = SPH_SUCCESS + if (sph_log_is_open) call sph_log_close(ierr) + open(unit=SPH_LOG_UNIT, file=trim(filename), status='unknown', & + action='write', position='append', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to open log file') + ierr = SPH_ERROR_IO + sph_log_is_open = .false. + return + end if + sph_log_is_open = .true. + end subroutine sph_log_open + + subroutine sph_log_close(ierr) + integer, intent(out) :: ierr + integer :: ios + + ierr = SPH_SUCCESS + if (sph_log_is_open) then + close(unit=SPH_LOG_UNIT, iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to close log file') + ierr = SPH_ERROR_IO + end if + end if + sph_log_is_open = .false. + end subroutine sph_log_close + + subroutine sph_log_info(message) + character(len=*), intent(in) :: message + + if (sph_log_is_open) then + write(SPH_LOG_UNIT, '(A)') trim(message) + end if + end subroutine sph_log_info + +end module sph_log diff --git a/src/core/sph_precision.f90 b/src/core/sph_precision.f90 new file mode 100644 index 0000000..a349586 --- /dev/null +++ b/src/core/sph_precision.f90 @@ -0,0 +1,11 @@ +module sph_precision + implicit none + + integer, parameter :: rk = selected_real_kind(12, 100) + integer, parameter :: SPH_VERSION_MAJOR = 0 + integer, parameter :: SPH_VERSION_MINOR = 1 + integer, parameter :: SPH_VERSION_PATCH = 0 + integer, parameter :: SPH_NDIM = 3 + integer, parameter :: SPH_ERROR_MESSAGE_LEN = 256 + integer, parameter :: SPH_PATH_LEN = 1024 +end module sph_precision diff --git a/src/coupling_interface/sph_coupling_interface.f90 b/src/coupling_interface/sph_coupling_interface.f90 new file mode 100644 index 0000000..ac98e72 --- /dev/null +++ b/src/coupling_interface/sph_coupling_interface.f90 @@ -0,0 +1,97 @@ +module sph_coupling_interface + use sph_precision, only: rk, SPH_NDIM + use sph_error, only: SPH_SUCCESS, SPH_ERROR_ARGUMENT, sph_error_set + use sph_database, only: npart, particle_id_ext, x, v + implicit none + + integer :: coupling_region_count = 0 + real(rk) :: coupling_work = 0.0_rk + real(rk) :: coupling_energy = 0.0_rk + +contains + + subroutine sph_coupling_reset() + coupling_region_count = 0 + coupling_work = 0.0_rk + coupling_energy = 0.0_rk + end subroutine sph_coupling_reset + + subroutine sph_coupling_get_particle_count(count, ierr) + integer, intent(out) :: count + integer, intent(out) :: ierr + + count = npart + ierr = SPH_SUCCESS + end subroutine sph_coupling_get_particle_count + + subroutine sph_coupling_export_particle(index, ext_id, position, velocity, ierr) + integer, intent(in) :: index + integer, intent(out) :: ext_id + real(rk), intent(out) :: position(SPH_NDIM) + real(rk), intent(out) :: velocity(SPH_NDIM) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + ext_id = 0 + position = 0.0_rk + velocity = 0.0_rk + if (index < 1 .or. index > npart) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'coupling particle index is out of range') + ierr = SPH_ERROR_ARGUMENT + return + end if + ext_id = particle_id_ext(index) + position(:) = x(:,index) + velocity(:) = v(:,index) + end subroutine sph_coupling_export_particle + + subroutine sph_coupling_get_facet_count(count, ierr) + integer, intent(out) :: count + integer, intent(out) :: ierr + + count = 0 + ierr = SPH_SUCCESS + end subroutine sph_coupling_get_facet_count + + subroutine sph_coupling_export_facet(index, node_ids, ierr) + integer, intent(in) :: index + integer, intent(out) :: node_ids(3) + integer, intent(out) :: ierr + + node_ids = 0 + ierr = SPH_SUCCESS + if (index /= 1) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'no coupling facets are available in 0.1.0') + ierr = SPH_ERROR_ARGUMENT + end if + end subroutine sph_coupling_export_facet + + subroutine sph_coupling_import_particle_force(index, force, ierr) + integer, intent(in) :: index + real(rk), intent(in) :: force(SPH_NDIM) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (index < 1 .or. index > npart) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'coupling force particle index is out of range') + ierr = SPH_ERROR_ARGUMENT + return + end if + coupling_work = coupling_work + sum(force) + end subroutine sph_coupling_import_particle_force + + subroutine sph_coupling_import_facet_load(index, load, ierr) + integer, intent(in) :: index + real(rk), intent(in) :: load(SPH_NDIM) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (index < 1) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'coupling facet index must be positive') + ierr = SPH_ERROR_ARGUMENT + return + end if + coupling_energy = coupling_energy + sum(load) + end subroutine sph_coupling_import_facet_load + +end module sph_coupling_interface diff --git a/src/database/sph_database.f90 b/src/database/sph_database.f90 new file mode 100644 index 0000000..2808508 --- /dev/null +++ b/src/database/sph_database.f90 @@ -0,0 +1,144 @@ +module sph_database + use sph_precision, only: rk, SPH_NDIM + use sph_error, only: SPH_SUCCESS, SPH_ERROR_ARGUMENT, SPH_ERROR_DATABASE, sph_error_set + implicit none + + integer, parameter :: SPH_PHASE_WATER = 1 + integer, parameter :: SPH_PHASE_GAS = 2 + integer, parameter :: SPH_PHASE_EXPLOSIVE = 3 + integer, parameter :: SPH_PHASE_SOLID = 4 + integer, parameter :: SPH_PHASE_SHELL = 5 + integer, parameter :: SPH_PHASE_BOUNDARY = 6 + integer, parameter :: SPH_PHASE_COUPLING = 7 + integer, parameter :: SPH_PHASE_SOLID_FAILED = 8 + integer, parameter :: SPH_PHASE_SHELL_FAILED = 9 + + integer, parameter :: SPH_STATUS_ACTIVE = 0 + integer, parameter :: SPH_STATUS_INACTIVE = 1 + integer, parameter :: SPH_STATUS_FAILED = 2 + + integer :: npart = 0 + integer, allocatable :: particle_id_ext(:) + integer, allocatable :: particle_phase(:) + integer, allocatable :: particle_status(:) + integer, allocatable :: material_id(:) + integer, allocatable :: section_id(:) + real(rk), allocatable :: x0(:,:) + real(rk), allocatable :: x(:,:) + real(rk), allocatable :: v(:,:) + real(rk), allocatable :: a(:,:) + real(rk), allocatable :: vhalf(:,:) + real(rk), allocatable :: mass(:) + real(rk), allocatable :: rho(:) + real(rk), allocatable :: volume(:) + real(rk), allocatable :: pressure(:) + real(rk), allocatable :: internal_energy(:) + real(rk), allocatable :: temperature(:) + real(rk), allocatable :: h(:) + +contains + + subroutine sph_db_allocate(count, ierr) + integer, intent(in) :: count + integer, intent(out) :: ierr + integer :: stat + + ierr = SPH_SUCCESS + if (count < 0) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'particle count must be non-negative') + ierr = SPH_ERROR_ARGUMENT + return + end if + + call sph_db_free() + npart = count + if (count == 0) return + + allocate(particle_id_ext(count), particle_phase(count), particle_status(count), & + material_id(count), section_id(count), x0(SPH_NDIM,count), & + x(SPH_NDIM,count), v(SPH_NDIM,count), a(SPH_NDIM,count), & + vhalf(SPH_NDIM,count), mass(count), rho(count), volume(count), & + pressure(count), internal_energy(count), temperature(count), & + h(count), stat=stat) + if (stat /= 0) then + call sph_db_free() + call sph_error_set(SPH_ERROR_DATABASE, 'failed to allocate particle database') + ierr = SPH_ERROR_DATABASE + return + end if + + call sph_db_initialize_defaults() + end subroutine sph_db_allocate + + subroutine sph_db_initialize_defaults() + integer :: i + + if (npart <= 0) return + do i = 1, npart + particle_id_ext(i) = i + particle_phase(i) = SPH_PHASE_SOLID + particle_status(i) = SPH_STATUS_ACTIVE + material_id(i) = 1 + section_id(i) = 1 + x0(:,i) = 0.0_rk + x(:,i) = 0.0_rk + v(:,i) = 0.0_rk + a(:,i) = 0.0_rk + vhalf(:,i) = 0.0_rk + mass(i) = 1.0_rk + rho(i) = 1000.0_rk + volume(i) = 1.0_rk + pressure(i) = 0.0_rk + internal_energy(i) = 0.0_rk + temperature(i) = 293.15_rk + h(i) = 1.0_rk + end do + end subroutine sph_db_initialize_defaults + + subroutine sph_db_free() + if (allocated(particle_id_ext)) deallocate(particle_id_ext) + if (allocated(particle_phase)) deallocate(particle_phase) + if (allocated(particle_status)) deallocate(particle_status) + if (allocated(material_id)) deallocate(material_id) + if (allocated(section_id)) deallocate(section_id) + if (allocated(x0)) deallocate(x0) + if (allocated(x)) deallocate(x) + if (allocated(v)) deallocate(v) + if (allocated(a)) deallocate(a) + if (allocated(vhalf)) deallocate(vhalf) + if (allocated(mass)) deallocate(mass) + if (allocated(rho)) deallocate(rho) + if (allocated(volume)) deallocate(volume) + if (allocated(pressure)) deallocate(pressure) + if (allocated(internal_energy)) deallocate(internal_energy) + if (allocated(temperature)) deallocate(temperature) + if (allocated(h)) deallocate(h) + npart = 0 + end subroutine sph_db_free + + subroutine sph_db_get_particle_count(count, ierr) + integer, intent(out) :: count + integer, intent(out) :: ierr + + count = npart + ierr = SPH_SUCCESS + end subroutine sph_db_get_particle_count + + subroutine sph_db_set_node(index, ext_id, coords, ierr) + integer, intent(in) :: index + integer, intent(in) :: ext_id + real(rk), intent(in) :: coords(SPH_NDIM) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (index < 1 .or. index > npart) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'particle index is out of range') + ierr = SPH_ERROR_ARGUMENT + return + end if + particle_id_ext(index) = ext_id + x0(:,index) = coords(:) + x(:,index) = coords(:) + end subroutine sph_db_set_node + +end module sph_database diff --git a/src/explosive/sph_explosive.f90 b/src/explosive/sph_explosive.f90 new file mode 100644 index 0000000..b12d7ab --- /dev/null +++ b/src/explosive/sph_explosive.f90 @@ -0,0 +1,15 @@ +module sph_explosive + implicit none + logical :: explosive_module_initialized = .false. + +contains + + subroutine sph_explosive_initialize() + explosive_module_initialized = .true. + end subroutine sph_explosive_initialize + + subroutine sph_explosive_reset() + explosive_module_initialized = .false. + end subroutine sph_explosive_reset + +end module sph_explosive diff --git a/src/gas/sph_gas.f90 b/src/gas/sph_gas.f90 new file mode 100644 index 0000000..4c1ad2e --- /dev/null +++ b/src/gas/sph_gas.f90 @@ -0,0 +1,15 @@ +module sph_gas + implicit none + logical :: gas_module_initialized = .false. + +contains + + subroutine sph_gas_initialize() + gas_module_initialized = .true. + end subroutine sph_gas_initialize + + subroutine sph_gas_reset() + gas_module_initialized = .false. + end subroutine sph_gas_reset + +end module sph_gas diff --git a/src/input/sph_inp_defs.f90 b/src/input/sph_inp_defs.f90 new file mode 100644 index 0000000..5266c25 --- /dev/null +++ b/src/input/sph_inp_defs.f90 @@ -0,0 +1,18 @@ +module sph_inp_defs + implicit none + + integer, parameter :: SPH_INPUT_LINE_LEN = 1024 + integer, parameter :: SPH_INPUT_FIELD_LEN = 256 + integer, parameter :: SPH_INPUT_MAX_FIELDS = 64 + + integer, parameter :: SPH_KEY_NONE = 0 + integer, parameter :: SPH_KEY_NODE = 1 + integer, parameter :: SPH_KEY_ELEMENT = 2 + integer, parameter :: SPH_KEY_NSET = 3 + integer, parameter :: SPH_KEY_ELSET = 4 + integer, parameter :: SPH_KEY_MATERIAL = 5 + integer, parameter :: SPH_KEY_SECTION = 6 + integer, parameter :: SPH_KEY_SPHLITE = 7 + integer, parameter :: SPH_KEY_UNKNOWN = 99 + +end module sph_inp_defs diff --git a/src/input/sph_inp_helpers.f90 b/src/input/sph_inp_helpers.f90 new file mode 100644 index 0000000..b868ed1 --- /dev/null +++ b/src/input/sph_inp_helpers.f90 @@ -0,0 +1,91 @@ +module sph_inp_helpers + use sph_inp_defs, only: SPH_INPUT_LINE_LEN, SPH_KEY_NODE, SPH_KEY_ELEMENT, & + SPH_KEY_NSET, SPH_KEY_ELSET, SPH_KEY_MATERIAL, SPH_KEY_SECTION, & + SPH_KEY_SPHLITE, SPH_KEY_UNKNOWN + implicit none + +contains + + function sph_inp_upper(line) result(out) + character(len=*), intent(in) :: line + character(len=len(line)) :: out + integer :: i + integer :: code + + out = line + do i = 1, len(out) + code = ichar(out(i:i)) + if (code >= ichar('a') .and. code <= ichar('z')) then + out(i:i) = char(code - ichar('a') + ichar('A')) + end if + end do + end function sph_inp_upper + + function sph_inp_clean_line(line) result(clean) + character(len=*), intent(in) :: line + character(len=SPH_INPUT_LINE_LEN) :: clean + + clean = ' ' + if (len_trim(line) == 0) return + if (line(1:1) == '!') return + if (len_trim(line) >= 2) then + if (line(1:2) == '**') return + end if + clean = adjustl(line) + end function sph_inp_clean_line + + subroutine sph_inp_split_csv(line, fields, nfields) + character(len=*), intent(in) :: line + character(len=*), intent(out) :: fields(:) + integer, intent(out) :: nfields + integer :: i + integer :: start_pos + integer :: n + + fields = ' ' + nfields = 0 + n = len_trim(line) + if (n <= 0) return + + start_pos = 1 + do i = 1, n + if (line(i:i) == ',') then + if (nfields < size(fields)) then + nfields = nfields + 1 + fields(nfields) = adjustl(line(start_pos:i-1)) + end if + start_pos = i + 1 + end if + end do + + if (nfields < size(fields)) then + nfields = nfields + 1 + fields(nfields) = adjustl(line(start_pos:n)) + end if + end subroutine sph_inp_split_csv + + function sph_inp_keyword_id(line) result(key_id) + character(len=*), intent(in) :: line + integer :: key_id + character(len=len(line)) :: upper + + upper = sph_inp_upper(adjustl(line)) + key_id = SPH_KEY_UNKNOWN + if (index(upper, '*NODE') == 1) then + key_id = SPH_KEY_NODE + else if (index(upper, '*ELEMENT') == 1) then + key_id = SPH_KEY_ELEMENT + else if (index(upper, '*NSET') == 1) then + key_id = SPH_KEY_NSET + else if (index(upper, '*ELSET') == 1) then + key_id = SPH_KEY_ELSET + else if (index(upper, '*MATERIAL') == 1) then + key_id = SPH_KEY_MATERIAL + else if (index(upper, '*SPHLITE') == 1) then + key_id = SPH_KEY_SPHLITE + else if (index(upper, 'SECTION') > 0 .and. upper(1:1) == '*') then + key_id = SPH_KEY_SECTION + end if + end function sph_inp_keyword_id + +end module sph_inp_helpers diff --git a/src/input/sph_input_reader.f90 b/src/input/sph_input_reader.f90 new file mode 100644 index 0000000..77ea7e4 --- /dev/null +++ b/src/input/sph_input_reader.f90 @@ -0,0 +1,258 @@ +module sph_input_reader + use sph_precision, only: rk, SPH_NDIM + use sph_error, only: SPH_SUCCESS, SPH_ERROR_IO, SPH_ERROR_INPUT, sph_error_set + use sph_control, only: sph_control_set_time + use sph_database, only: npart, sph_db_allocate, sph_db_free, sph_db_set_node + use sph_inp_defs, only: SPH_INPUT_LINE_LEN, SPH_INPUT_FIELD_LEN, & + SPH_INPUT_MAX_FIELDS, SPH_KEY_NODE, SPH_KEY_ELEMENT, SPH_KEY_NSET, & + SPH_KEY_ELSET, SPH_KEY_MATERIAL, SPH_KEY_SECTION, SPH_KEY_SPHLITE, & + SPH_KEY_UNKNOWN + use sph_inp_helpers, only: sph_inp_clean_line, sph_inp_split_csv, & + sph_inp_keyword_id, sph_inp_upper + implicit none + + integer, parameter :: SPH_INPUT_UNIT = 31 + integer :: input_warning_count = 0 + logical :: input_has_material = .false. + logical :: input_has_section = .false. + logical :: input_has_time_control = .false. + +contains + + subroutine sph_input_reset() + input_warning_count = 0 + input_has_material = .false. + input_has_section = .false. + input_has_time_control = .false. + end subroutine sph_input_reset + + subroutine sph_input_get_warning_count(count) + integer, intent(out) :: count + + count = input_warning_count + end subroutine sph_input_get_warning_count + + subroutine sph_input_read(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + integer :: node_count + + call sph_input_reset() + call sph_input_scan(filename, node_count, ierr) + if (ierr /= SPH_SUCCESS) return + call sph_db_allocate(node_count, ierr) + if (ierr /= SPH_SUCCESS) return + call sph_input_fill_nodes(filename, node_count, ierr) + end subroutine sph_input_read + + subroutine sph_input_build_model(ierr) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (npart <= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'input is missing *NODE particle data') + ierr = SPH_ERROR_INPUT + return + end if + if (.not. input_has_material) then + call sph_error_set(SPH_ERROR_INPUT, 'input is missing *MATERIAL data') + ierr = SPH_ERROR_INPUT + return + end if + if (.not. input_has_section) then + call sph_error_set(SPH_ERROR_INPUT, 'input is missing *SECTION data') + ierr = SPH_ERROR_INPUT + return + end if + if (.not. input_has_time_control) then + call sph_error_set(SPH_ERROR_INPUT, 'input is missing *SPHLITE time control data') + ierr = SPH_ERROR_INPUT + return + end if + end subroutine sph_input_build_model + + subroutine sph_input_scan(filename, node_count, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: node_count + integer, intent(out) :: ierr + character(len=SPH_INPUT_LINE_LEN) :: raw_line + character(len=SPH_INPUT_LINE_LEN) :: line + integer :: ios + integer :: active_key + integer :: key_id + + ierr = SPH_SUCCESS + node_count = 0 + active_key = SPH_KEY_UNKNOWN + + open(unit=SPH_INPUT_UNIT, file=trim(filename), status='old', action='read', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to open input file') + ierr = SPH_ERROR_IO + return + end if + + do + read(SPH_INPUT_UNIT, '(A)', iostat=ios) raw_line + if (ios /= 0) exit + line = sph_inp_clean_line(raw_line) + if (len_trim(line) == 0) cycle + + if (line(1:1) == '*') then + key_id = sph_inp_keyword_id(line) + active_key = key_id + call sph_input_record_keyword(key_id, line) + else if (active_key == SPH_KEY_NODE) then + node_count = node_count + 1 + end if + end do + + close(unit=SPH_INPUT_UNIT) + end subroutine sph_input_scan + + subroutine sph_input_fill_nodes(filename, expected_nodes, ierr) + character(len=*), intent(in) :: filename + integer, intent(in) :: expected_nodes + integer, intent(out) :: ierr + character(len=SPH_INPUT_LINE_LEN) :: raw_line + character(len=SPH_INPUT_LINE_LEN) :: line + integer :: ios + integer :: active_key + integer :: key_id + integer :: node_index + + ierr = SPH_SUCCESS + active_key = SPH_KEY_UNKNOWN + node_index = 0 + + if (expected_nodes == 0) then + call sph_db_free() + return + end if + + open(unit=SPH_INPUT_UNIT, file=trim(filename), status='old', action='read', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to reopen input file') + ierr = SPH_ERROR_IO + return + end if + + do + read(SPH_INPUT_UNIT, '(A)', iostat=ios) raw_line + if (ios /= 0) exit + line = sph_inp_clean_line(raw_line) + if (len_trim(line) == 0) cycle + + if (line(1:1) == '*') then + key_id = sph_inp_keyword_id(line) + active_key = key_id + else if (active_key == SPH_KEY_NODE) then + node_index = node_index + 1 + call sph_input_parse_node(line, node_index, ierr) + if (ierr /= SPH_SUCCESS) then + close(unit=SPH_INPUT_UNIT) + return + end if + end if + end do + + close(unit=SPH_INPUT_UNIT) + end subroutine sph_input_fill_nodes + + subroutine sph_input_record_keyword(key_id, line) + integer, intent(in) :: key_id + character(len=*), intent(in) :: line + + if (key_id == SPH_KEY_MATERIAL) then + input_has_material = .true. + else if (key_id == SPH_KEY_SECTION) then + input_has_section = .true. + else if (key_id == SPH_KEY_SPHLITE) then + input_has_time_control = .true. + call sph_input_parse_time_control(line) + else if (key_id == SPH_KEY_UNKNOWN) then + input_warning_count = input_warning_count + 1 + end if + end subroutine sph_input_record_keyword + + subroutine sph_input_parse_time_control(line) + character(len=*), intent(in) :: line + character(len=SPH_INPUT_FIELD_LEN) :: fields(SPH_INPUT_MAX_FIELDS) + character(len=SPH_INPUT_FIELD_LEN) :: item + character(len=SPH_INPUT_FIELD_LEN) :: key + character(len=SPH_INPUT_FIELD_LEN) :: value + integer :: nfields + integer :: i + integer :: eq_pos + integer :: ios + real(rk) :: dt + real(rk) :: total_time + integer :: steps + + dt = -1.0_rk + total_time = -1.0_rk + steps = -1 + call sph_inp_split_csv(line, fields, nfields) + do i = 1, nfields + item = adjustl(fields(i)) + eq_pos = index(item, '=') + if (eq_pos <= 0) cycle + key = sph_inp_upper(adjustl(item(1:eq_pos-1))) + value = adjustl(item(eq_pos+1:len_trim(item))) + if (index(key, 'DT') == 1) then + read(value, *, iostat=ios) dt + else if (index(key, 'TIME') == 1 .or. index(key, 'END TIME') == 1) then + read(value, *, iostat=ios) total_time + else if (index(key, 'STEPS') == 1 .or. index(key, 'MAX STEPS') == 1) then + read(value, *, iostat=ios) steps + end if + end do + call sph_control_set_time(dt, total_time, steps) + end subroutine sph_input_parse_time_control + + subroutine sph_input_parse_node(line, node_index, ierr) + character(len=*), intent(in) :: line + integer, intent(in) :: node_index + integer, intent(out) :: ierr + character(len=SPH_INPUT_FIELD_LEN) :: fields(SPH_INPUT_MAX_FIELDS) + integer :: nfields + integer :: ext_id + integer :: ios + real(rk) :: coords(SPH_NDIM) + + ierr = SPH_SUCCESS + call sph_inp_split_csv(line, fields, nfields) + if (nfields < 4) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid *NODE record') + ierr = SPH_ERROR_INPUT + return + end if + read(fields(1), *, iostat=ios) ext_id + if (ios /= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid node id') + ierr = SPH_ERROR_INPUT + return + end if + read(fields(2), *, iostat=ios) coords(1) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid node x coordinate') + ierr = SPH_ERROR_INPUT + return + end if + read(fields(3), *, iostat=ios) coords(2) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid node y coordinate') + ierr = SPH_ERROR_INPUT + return + end if + read(fields(4), *, iostat=ios) coords(3) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid node z coordinate') + ierr = SPH_ERROR_INPUT + return + end if + + call sph_db_set_node(node_index, ext_id, coords, ierr) + end subroutine sph_input_parse_node + +end module sph_input_reader diff --git a/src/interface/sph_api.f90 b/src/interface/sph_api.f90 new file mode 100644 index 0000000..019df9b --- /dev/null +++ b/src/interface/sph_api.f90 @@ -0,0 +1,398 @@ +module sph_api + use sph_precision, only: rk, SPH_VERSION_MAJOR, SPH_VERSION_MINOR, & + SPH_VERSION_PATCH + use sph_error, only: SPH_SUCCESS, SPH_ERROR_STATE, sph_error_clear, & + sph_error_set, sph_error_get + use sph_log, only: sph_log_close + use sph_control, only: sph_control_reset, sph_control_get_time + use sph_database, only: sph_db_free, sph_db_get_particle_count + use sph_input_reader, only: sph_input_read, sph_input_build_model + use sph_solver_explicit, only: sph_solver_estimate_stable_dt, & + sph_solver_advance_explicit, sph_solver_run_explicit + use sph_output_csv, only: sph_output_write_csv, sph_output_set_directory, & + sph_output_set_interval + use sph_restart, only: sph_restart_write, sph_restart_read + use sph_coupling_interface, only: sph_coupling_reset + use sph_particle, only: sph_particle_initialize, sph_particle_reset + use sph_material, only: sph_material_initialize, sph_material_reset + use sph_water, only: sph_water_initialize, sph_water_reset + use sph_gas, only: sph_gas_initialize, sph_gas_reset + use sph_explosive, only: sph_explosive_initialize, sph_explosive_reset + use sph_solid, only: sph_solid_initialize, sph_solid_reset + use sph_shell, only: sph_shell_initialize, sph_shell_reset + use sph_api_state, only: sph_api_initialized, sph_api_state_set_initialized + implicit none + +contains + + subroutine sph_initialize(ierr) + integer, intent(out) :: ierr + + call sph_error_clear() + call sph_control_reset() + call sph_db_free() + call sph_coupling_reset() + call sph_particle_initialize() + call sph_material_initialize() + call sph_water_initialize() + call sph_gas_initialize() + call sph_explosive_initialize() + call sph_solid_initialize() + call sph_shell_initialize() + call sph_api_state_set_initialized(.true.) + ierr = SPH_SUCCESS + end subroutine sph_initialize + + subroutine sph_finalize(ierr) + integer, intent(out) :: ierr + integer :: local_ierr + + call sph_db_free() + call sph_coupling_reset() + call sph_particle_reset() + call sph_material_reset() + call sph_water_reset() + call sph_gas_reset() + call sph_explosive_reset() + call sph_solid_reset() + call sph_shell_reset() + call sph_log_close(local_ierr) + call sph_api_state_set_initialized(.false.) + call sph_error_clear() + ierr = SPH_SUCCESS + end subroutine sph_finalize + + subroutine sph_get_version(major, minor, patch, ierr) + integer, intent(out) :: major + integer, intent(out) :: minor + integer, intent(out) :: patch + integer, intent(out) :: ierr + + major = SPH_VERSION_MAJOR + minor = SPH_VERSION_MINOR + patch = SPH_VERSION_PATCH + ierr = SPH_SUCCESS + end subroutine sph_get_version + + subroutine sph_get_last_error(code, message, ierr) + integer, intent(out) :: code + character(len=*), intent(out) :: message + integer, intent(out) :: ierr + + call sph_error_get(code, message) + ierr = SPH_SUCCESS + end subroutine sph_get_last_error + + subroutine sph_read_inp(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_input_read(filename, ierr) + end subroutine sph_read_inp + + subroutine sph_build_model(ierr) + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_input_build_model(ierr) + end subroutine sph_build_model + + subroutine sph_estimate_stable_dt(dtcrit, ierr) + real(rk), intent(out) :: dtcrit + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) then + dtcrit = 0.0_rk + return + end if + call sph_solver_estimate_stable_dt(dtcrit, ierr) + end subroutine sph_estimate_stable_dt + + subroutine sph_advance_explicit(dt, ierr) + real(rk), intent(in) :: dt + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_solver_advance_explicit(dt, ierr) + end subroutine sph_advance_explicit + + subroutine sph_run_explicit(ierr) + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_solver_run_explicit(ierr) + end subroutine sph_run_explicit + + subroutine sph_get_current_time(time, step, ierr) + real(rk), intent(out) :: time + integer, intent(out) :: step + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) then + time = 0.0_rk + step = 0 + return + end if + call sph_control_get_time(time, step) + ierr = SPH_SUCCESS + end subroutine sph_get_current_time + + subroutine sph_get_particle_count(count, ierr) + integer, intent(out) :: count + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) then + count = 0 + return + end if + call sph_db_get_particle_count(count, ierr) + end subroutine sph_get_particle_count + + subroutine sph_write_csv(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_output_write_csv(filename, ierr) + end subroutine sph_write_csv + + subroutine sph_set_output_directory(directory, ierr) + character(len=*), intent(in) :: directory + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_output_set_directory(directory, ierr) + end subroutine sph_set_output_directory + + subroutine sph_set_output_interval(interval, ierr) + integer, intent(in) :: interval + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_output_set_interval(interval, ierr) + end subroutine sph_set_output_interval + + subroutine sph_write_restart(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_restart_write(filename, ierr) + end subroutine sph_write_restart + + subroutine sph_read_restart(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + + call sph_api_require_initialized(ierr) + if (ierr /= SPH_SUCCESS) return + call sph_restart_read(filename, ierr) + end subroutine sph_read_restart + + subroutine sph_api_require_initialized(ierr) + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (.not. sph_api_initialized) then + call sph_error_set(SPH_ERROR_STATE, 'SPHLite API is not initialized') + ierr = SPH_ERROR_STATE + end if + end subroutine sph_api_require_initialized + +end module sph_api + +subroutine sphft_initialize(ierr) + use sph_api, only: sph_initialize + implicit none + integer, intent(out) :: ierr + + call sph_initialize(ierr) +end subroutine sphft_initialize + +subroutine sphft_finalize(ierr) + use sph_api, only: sph_finalize + implicit none + integer, intent(out) :: ierr + + call sph_finalize(ierr) +end subroutine sphft_finalize + +subroutine sphft_get_version(major, minor, patch, ierr) + use sph_api, only: sph_get_version + implicit none + integer, intent(out) :: major + integer, intent(out) :: minor + integer, intent(out) :: patch + integer, intent(out) :: ierr + + call sph_get_version(major, minor, patch, ierr) +end subroutine sphft_get_version + +subroutine sphft_get_last_error_chars(code, chars, capacity, actual, ierr) + use sph_api, only: sph_get_last_error + use sph_error, only: SPH_SUCCESS + implicit none + integer, intent(out) :: code + integer, intent(out) :: chars(*) + integer, intent(in) :: capacity + integer, intent(out) :: actual + integer, intent(out) :: ierr + character(len=256) :: message + integer :: i + integer :: n + + call sph_get_last_error(code, message, ierr) + if (capacity <= 0) return + n = len_trim(message) + if (n > capacity - 1) n = capacity - 1 + actual = n + do i = 1, n + chars(i) = ichar(message(i:i)) + end do + if (capacity > n) chars(n+1) = 0 + ierr = SPH_SUCCESS +end subroutine sphft_get_last_error_chars + +subroutine sphft_read_inp_chars(chars, count, ierr) + use sph_api, only: sph_read_inp + implicit none + integer, intent(in) :: chars(*) + integer, intent(in) :: count + integer, intent(out) :: ierr + character(len=1024) :: filename + integer :: i + integer :: n + + filename = ' ' + n = count + if (n > len(filename)) n = len(filename) + do i = 1, n + filename(i:i) = char(chars(i)) + end do + call sph_read_inp(filename(1:n), ierr) +end subroutine sphft_read_inp_chars + +subroutine sphft_build_model(ierr) + use sph_api, only: sph_build_model + implicit none + integer, intent(out) :: ierr + + call sph_build_model(ierr) +end subroutine sphft_build_model + +subroutine sphft_estimate_stable_dt(dtcrit, ierr) + use sph_api, only: sph_estimate_stable_dt + use sph_precision, only: rk + implicit none + real(rk), intent(out) :: dtcrit + integer, intent(out) :: ierr + + call sph_estimate_stable_dt(dtcrit, ierr) +end subroutine sphft_estimate_stable_dt + +subroutine sphft_advance_explicit(dt, ierr) + use sph_api, only: sph_advance_explicit + use sph_precision, only: rk + implicit none + real(rk), intent(in) :: dt + integer, intent(out) :: ierr + + call sph_advance_explicit(dt, ierr) +end subroutine sphft_advance_explicit + +subroutine sphft_run_explicit(ierr) + use sph_api, only: sph_run_explicit + implicit none + integer, intent(out) :: ierr + + call sph_run_explicit(ierr) +end subroutine sphft_run_explicit + +subroutine sphft_get_current_time(time, step, ierr) + use sph_api, only: sph_get_current_time + use sph_precision, only: rk + implicit none + real(rk), intent(out) :: time + integer, intent(out) :: step + integer, intent(out) :: ierr + + call sph_get_current_time(time, step, ierr) +end subroutine sphft_get_current_time + +subroutine sphft_get_particle_count(count, ierr) + use sph_api, only: sph_get_particle_count + implicit none + integer, intent(out) :: count + integer, intent(out) :: ierr + + call sph_get_particle_count(count, ierr) +end subroutine sphft_get_particle_count + +subroutine sphft_write_csv_chars(chars, count, ierr) + use sph_api, only: sph_write_csv + implicit none + integer, intent(in) :: chars(*) + integer, intent(in) :: count + integer, intent(out) :: ierr + character(len=1024) :: filename + integer :: i + integer :: n + + filename = ' ' + n = count + if (n > len(filename)) n = len(filename) + do i = 1, n + filename(i:i) = char(chars(i)) + end do + call sph_write_csv(filename(1:n), ierr) +end subroutine sphft_write_csv_chars + +subroutine sphft_write_restart_chars(chars, count, ierr) + use sph_api, only: sph_write_restart + implicit none + integer, intent(in) :: chars(*) + integer, intent(in) :: count + integer, intent(out) :: ierr + character(len=1024) :: filename + integer :: i + integer :: n + + filename = ' ' + n = count + if (n > len(filename)) n = len(filename) + do i = 1, n + filename(i:i) = char(chars(i)) + end do + call sph_write_restart(filename(1:n), ierr) +end subroutine sphft_write_restart_chars + +subroutine sphft_read_restart_chars(chars, count, ierr) + use sph_api, only: sph_read_restart + implicit none + integer, intent(in) :: chars(*) + integer, intent(in) :: count + integer, intent(out) :: ierr + character(len=1024) :: filename + integer :: i + integer :: n + + filename = ' ' + n = count + if (n > len(filename)) n = len(filename) + do i = 1, n + filename(i:i) = char(chars(i)) + end do + call sph_read_restart(filename(1:n), ierr) +end subroutine sphft_read_restart_chars diff --git a/src/interface/sph_api_state.f90 b/src/interface/sph_api_state.f90 new file mode 100644 index 0000000..46755e3 --- /dev/null +++ b/src/interface/sph_api_state.f90 @@ -0,0 +1,20 @@ +module sph_api_state + implicit none + + logical :: sph_api_initialized = .false. + +contains + + subroutine sph_api_state_set_initialized(value) + logical, intent(in) :: value + + sph_api_initialized = value + end subroutine sph_api_state_set_initialized + + subroutine sph_api_state_get_initialized(value) + logical, intent(out) :: value + + value = sph_api_initialized + end subroutine sph_api_state_get_initialized + +end module sph_api_state diff --git a/src/interface/sph_c_api.c b/src/interface/sph_c_api.c new file mode 100644 index 0000000..01837ef --- /dev/null +++ b/src/interface/sph_c_api.c @@ -0,0 +1,189 @@ +#include "sphlite_c_api.h" +#include "sphlite_fortran_mangle.h" + +#include +#include +#include + +extern void SPHLITE_FC_sphft_initialize(int *ierr); +extern void SPHLITE_FC_sphft_finalize(int *ierr); +extern void SPHLITE_FC_sphft_get_version( + int *major, int *minor, int *patch, int *ierr); +extern void SPHLITE_FC_sphft_get_last_error_chars( + int *code, int *chars, const int *capacity, int *actual, int *ierr); +extern void SPHLITE_FC_sphft_read_inp_chars( + const int *chars, const int *count, int *ierr); +extern void SPHLITE_FC_sphft_build_model(int *ierr); +extern void SPHLITE_FC_sphft_estimate_stable_dt( + double *dtcrit, int *ierr); +extern void SPHLITE_FC_sphft_advance_explicit( + const double *dt, int *ierr); +extern void SPHLITE_FC_sphft_run_explicit(int *ierr); +extern void SPHLITE_FC_sphft_get_current_time( + double *time, int *step, int *ierr); +extern void SPHLITE_FC_sphft_get_particle_count( + int *count, int *ierr); +extern void SPHLITE_FC_sphft_write_csv_chars( + const int *chars, const int *count, int *ierr); +extern void SPHLITE_FC_sphft_write_restart_chars( + const int *chars, const int *count, int *ierr); +extern void SPHLITE_FC_sphft_read_restart_chars( + const int *chars, const int *count, int *ierr); + +static int sphlite_call_path( + const char *path, + void (*fortran_call)(const int *chars, const int *count, int *ierr)) +{ + size_t i; + size_t length; + int count; + int ierr; + int *chars; + + if (path == NULL) { + return -1; + } + length = strlen(path); + if (length == 0 || length > 1024) { + return -1; + } + + chars = (int *)malloc(length * sizeof(int)); + if (chars == NULL) { + return -1; + } + for (i = 0; i < length; ++i) { + chars[i] = (unsigned char)path[i]; + } + count = (int)length; + ierr = 0; + fortran_call(chars, &count, &ierr); + free(chars); + return ierr; +} + +int sphlite_initialize(void) +{ + int ierr = 0; + SPHLITE_FC_sphft_initialize(&ierr); + return ierr; +} + +int sphlite_finalize(void) +{ + int ierr = 0; + SPHLITE_FC_sphft_finalize(&ierr); + return ierr; +} + +int sphlite_get_version(int *major, int *minor, int *patch) +{ + int ierr = 0; + if (major == NULL || minor == NULL || patch == NULL) { + return -1; + } + SPHLITE_FC_sphft_get_version(major, minor, patch, &ierr); + return ierr; +} + +int sphlite_get_last_error(int *code, char *message, int message_capacity) +{ + int ierr = 0; + int actual = 0; + int *chars; + int i; + + if (code == NULL || message == NULL || message_capacity <= 0) { + return -1; + } + chars = (int *)malloc((size_t)message_capacity * sizeof(int)); + if (chars == NULL) { + return -1; + } + SPHLITE_FC_sphft_get_last_error_chars(code, chars, &message_capacity, &actual, &ierr); + for (i = 0; i < message_capacity; ++i) { + if (chars[i] == 0) { + message[i] = '\0'; + break; + } + message[i] = (char)chars[i]; + } + message[message_capacity - 1] = '\0'; + free(chars); + return ierr; +} + +int sphlite_read_inp(const char *filename) +{ + return sphlite_call_path( + filename, SPHLITE_FC_sphft_read_inp_chars); +} + +int sphlite_build_model(void) +{ + int ierr = 0; + SPHLITE_FC_sphft_build_model(&ierr); + return ierr; +} + +int sphlite_estimate_stable_dt(double *dtcrit) +{ + int ierr = 0; + if (dtcrit == NULL) { + return -1; + } + SPHLITE_FC_sphft_estimate_stable_dt(dtcrit, &ierr); + return ierr; +} + +int sphlite_advance_explicit(double dt) +{ + int ierr = 0; + SPHLITE_FC_sphft_advance_explicit(&dt, &ierr); + return ierr; +} + +int sphlite_run_explicit(void) +{ + int ierr = 0; + SPHLITE_FC_sphft_run_explicit(&ierr); + return ierr; +} + +int sphlite_get_current_time(double *time, int *step) +{ + int ierr = 0; + if (time == NULL || step == NULL) { + return -1; + } + SPHLITE_FC_sphft_get_current_time(time, step, &ierr); + return ierr; +} + +int sphlite_get_particle_count(int *count) +{ + int ierr = 0; + if (count == NULL) { + return -1; + } + SPHLITE_FC_sphft_get_particle_count(count, &ierr); + return ierr; +} + +int sphlite_write_csv(const char *filename) +{ + return sphlite_call_path( + filename, SPHLITE_FC_sphft_write_csv_chars); +} + +int sphlite_write_restart(const char *filename) +{ + return sphlite_call_path( + filename, SPHLITE_FC_sphft_write_restart_chars); +} + +int sphlite_read_restart(const char *filename) +{ + return sphlite_call_path( + filename, SPHLITE_FC_sphft_read_restart_chars); +} diff --git a/src/material/sph_material.f90 b/src/material/sph_material.f90 new file mode 100644 index 0000000..7be885d --- /dev/null +++ b/src/material/sph_material.f90 @@ -0,0 +1,15 @@ +module sph_material + implicit none + logical :: material_module_initialized = .false. + +contains + + subroutine sph_material_initialize() + material_module_initialized = .true. + end subroutine sph_material_initialize + + subroutine sph_material_reset() + material_module_initialized = .false. + end subroutine sph_material_reset + +end module sph_material diff --git a/src/output/sph_output_csv.f90 b/src/output/sph_output_csv.f90 new file mode 100644 index 0000000..24307dd --- /dev/null +++ b/src/output/sph_output_csv.f90 @@ -0,0 +1,61 @@ +module sph_output_csv + use sph_precision, only: rk + use sph_error, only: SPH_SUCCESS, SPH_ERROR_ARGUMENT, SPH_ERROR_IO, sph_error_set + use sph_control, only: output_directory, output_interval + use sph_database, only: npart, particle_id_ext, x, v + implicit none + + integer, parameter :: SPH_OUTPUT_UNIT = 41 + +contains + + subroutine sph_output_set_directory(directory, ierr) + character(len=*), intent(in) :: directory + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (len_trim(directory) <= 0) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'output directory must not be empty') + ierr = SPH_ERROR_ARGUMENT + return + end if + output_directory = directory + end subroutine sph_output_set_directory + + subroutine sph_output_set_interval(interval, ierr) + integer, intent(in) :: interval + integer, intent(out) :: ierr + + ierr = SPH_SUCCESS + if (interval <= 0) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'output interval must be positive') + ierr = SPH_ERROR_ARGUMENT + return + end if + output_interval = interval + end subroutine sph_output_set_interval + + subroutine sph_output_write_csv(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + integer :: ios + integer :: i + + ierr = SPH_SUCCESS + open(unit=SPH_OUTPUT_UNIT, file=trim(filename), status='unknown', & + action='write', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to open CSV output file') + ierr = SPH_ERROR_IO + return + end if + + write(SPH_OUTPUT_UNIT, '(A)') 'id,x,y,z,vx,vy,vz' + do i = 1, npart + write(SPH_OUTPUT_UNIT, '(I0,6(",",ES24.16))') particle_id_ext(i), & + x(1,i), x(2,i), x(3,i), v(1,i), v(2,i), v(3,i) + end do + close(unit=SPH_OUTPUT_UNIT) + end subroutine sph_output_write_csv + +end module sph_output_csv diff --git a/src/output/sph_restart.f90 b/src/output/sph_restart.f90 new file mode 100644 index 0000000..2a36225 --- /dev/null +++ b/src/output/sph_restart.f90 @@ -0,0 +1,98 @@ +module sph_restart + use sph_precision, only: rk + use sph_error, only: SPH_SUCCESS, SPH_ERROR_IO, SPH_ERROR_INPUT, sph_error_set + use sph_control, only: current_time, current_step + use sph_database, only: npart, sph_db_allocate, particle_id_ext, particle_phase, & + particle_status, material_id, section_id, x0, x, v, a, vhalf, mass, rho, & + volume, pressure, internal_energy, temperature, h + implicit none + + integer, parameter :: SPH_RESTART_UNIT = 43 + +contains + + subroutine sph_restart_write(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + integer :: ios + integer :: i + + ierr = SPH_SUCCESS + open(unit=SPH_RESTART_UNIT, file=trim(filename), status='unknown', & + action='write', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to open restart file for writing') + ierr = SPH_ERROR_IO + return + end if + + write(SPH_RESTART_UNIT, '(A)') 'SPHLITE_RESTART 0.1.0' + write(SPH_RESTART_UNIT, *) current_time, current_step, npart + do i = 1, npart + write(SPH_RESTART_UNIT, *) particle_id_ext(i), particle_phase(i), & + particle_status(i), material_id(i), section_id(i) + write(SPH_RESTART_UNIT, *) x0(:,i), x(:,i), v(:,i), a(:,i), vhalf(:,i) + write(SPH_RESTART_UNIT, *) mass(i), rho(i), volume(i), pressure(i), & + internal_energy(i), temperature(i), h(i) + end do + close(unit=SPH_RESTART_UNIT) + end subroutine sph_restart_write + + subroutine sph_restart_read(filename, ierr) + character(len=*), intent(in) :: filename + integer, intent(out) :: ierr + character(len=64) :: tag + character(len=32) :: version + integer :: ios + integer :: count + integer :: i + + ierr = SPH_SUCCESS + open(unit=SPH_RESTART_UNIT, file=trim(filename), status='old', & + action='read', iostat=ios) + if (ios /= 0) then + call sph_error_set(SPH_ERROR_IO, 'failed to open restart file for reading') + ierr = SPH_ERROR_IO + return + end if + + read(SPH_RESTART_UNIT, *, iostat=ios) tag, version + if (ios /= 0 .or. trim(tag) /= 'SPHLITE_RESTART') then + call sph_error_set(SPH_ERROR_INPUT, 'invalid restart header') + ierr = SPH_ERROR_INPUT + close(unit=SPH_RESTART_UNIT) + return + end if + + read(SPH_RESTART_UNIT, *, iostat=ios) current_time, current_step, count + if (ios /= 0 .or. count < 0) then + call sph_error_set(SPH_ERROR_INPUT, 'invalid restart state') + ierr = SPH_ERROR_INPUT + close(unit=SPH_RESTART_UNIT) + return + end if + call sph_db_allocate(count, ierr) + if (ierr /= SPH_SUCCESS) then + close(unit=SPH_RESTART_UNIT) + return + end if + + do i = 1, npart + read(SPH_RESTART_UNIT, *, iostat=ios) particle_id_ext(i), particle_phase(i), & + particle_status(i), material_id(i), section_id(i) + if (ios /= 0) exit + read(SPH_RESTART_UNIT, *, iostat=ios) x0(:,i), x(:,i), v(:,i), a(:,i), vhalf(:,i) + if (ios /= 0) exit + read(SPH_RESTART_UNIT, *, iostat=ios) mass(i), rho(i), volume(i), pressure(i), & + internal_energy(i), temperature(i), h(i) + if (ios /= 0) exit + end do + + if (ios /= 0) then + call sph_error_set(SPH_ERROR_INPUT, 'restart file ended unexpectedly') + ierr = SPH_ERROR_INPUT + end if + close(unit=SPH_RESTART_UNIT) + end subroutine sph_restart_read + +end module sph_restart diff --git a/src/particle/sph_particle.f90 b/src/particle/sph_particle.f90 new file mode 100644 index 0000000..0416461 --- /dev/null +++ b/src/particle/sph_particle.f90 @@ -0,0 +1,15 @@ +module sph_particle + implicit none + logical :: particle_module_initialized = .false. + +contains + + subroutine sph_particle_initialize() + particle_module_initialized = .true. + end subroutine sph_particle_initialize + + subroutine sph_particle_reset() + particle_module_initialized = .false. + end subroutine sph_particle_reset + +end module sph_particle diff --git a/src/shell/sph_shell.f90 b/src/shell/sph_shell.f90 new file mode 100644 index 0000000..5c0d694 --- /dev/null +++ b/src/shell/sph_shell.f90 @@ -0,0 +1,15 @@ +module sph_shell + implicit none + logical :: shell_module_initialized = .false. + +contains + + subroutine sph_shell_initialize() + shell_module_initialized = .true. + end subroutine sph_shell_initialize + + subroutine sph_shell_reset() + shell_module_initialized = .false. + end subroutine sph_shell_reset + +end module sph_shell diff --git a/src/solid/sph_solid.f90 b/src/solid/sph_solid.f90 new file mode 100644 index 0000000..da4acc6 --- /dev/null +++ b/src/solid/sph_solid.f90 @@ -0,0 +1,15 @@ +module sph_solid + implicit none + logical :: solid_module_initialized = .false. + +contains + + subroutine sph_solid_initialize() + solid_module_initialized = .true. + end subroutine sph_solid_initialize + + subroutine sph_solid_reset() + solid_module_initialized = .false. + end subroutine sph_solid_reset + +end module sph_solid diff --git a/src/solver/sph_solver_explicit.f90 b/src/solver/sph_solver_explicit.f90 new file mode 100644 index 0000000..e8aadfb --- /dev/null +++ b/src/solver/sph_solver_explicit.f90 @@ -0,0 +1,60 @@ +module sph_solver_explicit + use sph_precision, only: rk + use sph_error, only: SPH_SUCCESS, SPH_ERROR_ARGUMENT, sph_error_set + use sph_control, only: current_time, current_step, dt_default, end_time, max_steps + use sph_database, only: npart, x, v, a, vhalf + implicit none + +contains + + subroutine sph_solver_estimate_stable_dt(dtcrit, ierr) + real(rk), intent(out) :: dtcrit + integer, intent(out) :: ierr + + dtcrit = dt_default + ierr = SPH_SUCCESS + end subroutine sph_solver_estimate_stable_dt + + subroutine sph_solver_advance_explicit(dt, ierr) + real(rk), intent(in) :: dt + integer, intent(out) :: ierr + integer :: i + + ierr = SPH_SUCCESS + if (dt <= 0.0_rk) then + call sph_error_set(SPH_ERROR_ARGUMENT, 'time step must be positive') + ierr = SPH_ERROR_ARGUMENT + return + end if + + if (npart > 0) then + do i = 1, npart + vhalf(:,i) = v(:,i) + 0.5_rk * dt * a(:,i) + x(:,i) = x(:,i) + dt * vhalf(:,i) + v(:,i) = vhalf(:,i) + 0.5_rk * dt * a(:,i) + end do + end if + + current_time = current_time + dt + current_step = current_step + 1 + end subroutine sph_solver_advance_explicit + + subroutine sph_solver_run_explicit(ierr) + integer, intent(out) :: ierr + integer :: local_step + real(rk) :: dt + + ierr = SPH_SUCCESS + local_step = 0 + do while (current_time < end_time .and. local_step < max_steps) + call sph_solver_estimate_stable_dt(dt, ierr) + if (ierr /= SPH_SUCCESS) return + if (current_time + dt > end_time) dt = end_time - current_time + if (dt <= 0.0_rk) exit + call sph_solver_advance_explicit(dt, ierr) + if (ierr /= SPH_SUCCESS) return + local_step = local_step + 1 + end do + end subroutine sph_solver_run_explicit + +end module sph_solver_explicit diff --git a/src/water/sph_water.f90 b/src/water/sph_water.f90 new file mode 100644 index 0000000..0ebd81a --- /dev/null +++ b/src/water/sph_water.f90 @@ -0,0 +1,15 @@ +module sph_water + implicit none + logical :: water_module_initialized = .false. + +contains + + subroutine sph_water_initialize() + water_module_initialized = .true. + end subroutine sph_water_initialize + + subroutine sph_water_reset() + water_module_initialized = .false. + end subroutine sph_water_reset + +end module sph_water diff --git a/tests/data/minimal_particles.inp b/tests/data/minimal_particles.inp new file mode 100644 index 0000000..c60bee3 --- /dev/null +++ b/tests/data/minimal_particles.inp @@ -0,0 +1,8 @@ +*NODE +1, 0.0, 0.0, 0.0 +2, 1.0, 0.0, 0.0 +3, 0.0, 1.0, 0.0 +4, 0.0, 0.0, 1.0 +*MATERIAL, NAME=WATER_PLACEHOLDER +*SOLID SECTION, ELSET=ALL, MATERIAL=WATER_PLACEHOLDER +*SPHLITE TIME CONTROL, DT=1.0E-6, TIME=1.0E-6, STEPS=1 diff --git a/tests/data/missing_required.inp b/tests/data/missing_required.inp new file mode 100644 index 0000000..289d0c5 --- /dev/null +++ b/tests/data/missing_required.inp @@ -0,0 +1,4 @@ +*NODE +1, 0.0, 0.0, 0.0 +2, 1.0, 0.0, 0.0 +*SPHLITE TIME CONTROL, DT=1.0E-6, TIME=1.0E-6, STEPS=1 diff --git a/tests/data/unknown_keyword.inp b/tests/data/unknown_keyword.inp new file mode 100644 index 0000000..7b61b59 --- /dev/null +++ b/tests/data/unknown_keyword.inp @@ -0,0 +1,10 @@ +*NODE +1, 0.0, 0.0, 0.0 +2, 1.0, 0.0, 0.0 +3, 0.0, 1.0, 0.0 +4, 0.0, 0.0, 1.0 +*UNSUPPORTED KEYWORD +1, 2, 3 +*MATERIAL, NAME=WATER_PLACEHOLDER +*SOLID SECTION, ELSET=ALL, MATERIAL=WATER_PLACEHOLDER +*SPHLITE TIME CONTROL, DT=1.0E-6, TIME=1.0E-6, STEPS=1 diff --git a/tests/interface/test_c_api.c b/tests/interface/test_c_api.c new file mode 100644 index 0000000..62afba2 --- /dev/null +++ b/tests/interface/test_c_api.c @@ -0,0 +1,55 @@ +#include "sphlite_c_api.h" + +#include +#include + +static int fail(const char *message) +{ + fprintf(stderr, "%s\n", message); + return 1; +} + +int main(void) +{ + char path[1024]; + int ierr; + int major = 0; + int minor = 0; + int patch = 0; + int count = 0; + int step = 0; + double time = 0.0; + + if (sphlite_get_particle_count(NULL) != -1) { + return fail("null particle count pointer did not return -1"); + } + if (sphlite_get_last_error(NULL, path, (int)sizeof(path)) != -1) { + return fail("null last-error code pointer did not return -1"); + } + + ierr = sphlite_initialize(); + if (ierr != 0) return fail("initialize failed"); + + ierr = sphlite_get_version(&major, &minor, &patch); + if (ierr != 0) return fail("get_version failed"); + if (major != 0 || minor != 1 || patch != 0) return fail("unexpected version"); + + snprintf(path, sizeof(path), "%s/minimal_particles.inp", SPHLITE_TEST_DATA_DIR); + ierr = sphlite_read_inp(path); + if (ierr != 0) return fail("read_inp failed"); + + ierr = sphlite_build_model(); + if (ierr != 0) return fail("build_model failed"); + + ierr = sphlite_get_particle_count(&count); + if (ierr != 0 || count != 4) return fail("particle count mismatch"); + + ierr = sphlite_advance_explicit(1.0e-6); + if (ierr != 0) return fail("advance explicit failed"); + ierr = sphlite_get_current_time(&time, &step); + if (ierr != 0 || step != 1 || time <= 0.0) return fail("time query failed"); + + ierr = sphlite_finalize(); + if (ierr != 0) return fail("finalize failed"); + return 0; +} diff --git a/tests/module/test_input.f90 b/tests/module/test_input.f90 new file mode 100644 index 0000000..2252635 --- /dev/null +++ b/tests/module/test_input.f90 @@ -0,0 +1,60 @@ +program test_input + use sph_error, only: SPH_SUCCESS + use sph_api, only: sph_initialize, sph_finalize, sph_read_inp, & + sph_build_model, sph_get_particle_count + use sph_input_reader, only: sph_input_get_warning_count + implicit none + + integer :: ierr + integer :: count + integer :: warnings + + call sph_initialize(ierr) + call assert_ok(ierr, 'initialize failed for minimal input') + call sph_read_inp('tests/data/minimal_particles.inp', ierr) + call assert_ok(ierr, 'minimal input read failed') + call sph_build_model(ierr) + call assert_ok(ierr, 'minimal model build failed') + call sph_get_particle_count(count, ierr) + call assert_ok(ierr, 'minimal particle count failed') + if (count /= 4) call fail('minimal input particle count mismatch') + call sph_finalize(ierr) + call assert_ok(ierr, 'finalize failed after minimal input') + + call sph_initialize(ierr) + call assert_ok(ierr, 'initialize failed for unknown keyword input') + call sph_read_inp('tests/data/unknown_keyword.inp', ierr) + call assert_ok(ierr, 'unknown keyword input read failed') + call sph_input_get_warning_count(warnings) + if (warnings <= 0) call fail('unknown keyword warning was not recorded') + call sph_build_model(ierr) + call assert_ok(ierr, 'unknown keyword input build failed') + call sph_finalize(ierr) + call assert_ok(ierr, 'finalize failed after unknown keyword input') + + call sph_initialize(ierr) + call assert_ok(ierr, 'initialize failed for missing required input') + call sph_read_inp('tests/data/missing_required.inp', ierr) + call assert_ok(ierr, 'missing required input read failed') + call sph_build_model(ierr) + if (ierr == SPH_SUCCESS) call fail('missing required input did not fail') + call sph_finalize(ierr) + call assert_ok(ierr, 'finalize failed after missing required input') + +contains + + subroutine assert_ok(ierr_value, message) + integer, intent(in) :: ierr_value + character(len=*), intent(in) :: message + + if (ierr_value /= SPH_SUCCESS) call fail(message) + end subroutine assert_ok + + subroutine fail(message) + character(len=*), intent(in) :: message + + write(*, '(A)') trim(message) + stop 1 + end subroutine fail + +end program test_input diff --git a/tests/source_size_exceptions.txt b/tests/source_size_exceptions.txt new file mode 100644 index 0000000..7211eb7 --- /dev/null +++ b/tests/source_size_exceptions.txt @@ -0,0 +1,4 @@ +# Source size exceptions. +# Format: +# path/to/file.ext +# path/to/file.f90:procedure_name diff --git a/tests/unit/test_smoke.f90 b/tests/unit/test_smoke.f90 new file mode 100644 index 0000000..6635d67 --- /dev/null +++ b/tests/unit/test_smoke.f90 @@ -0,0 +1,56 @@ +program test_smoke + use sph_precision, only: rk + use sph_error, only: SPH_SUCCESS + use sph_api, only: sph_initialize, sph_finalize, sph_get_version, & + sph_get_particle_count, sph_get_current_time, sph_advance_explicit + use sph_database, only: sph_db_allocate + implicit none + + integer :: ierr + integer :: major + integer :: minor + integer :: patch + integer :: count + integer :: step + real(rk) :: time + + call sph_initialize(ierr) + call assert_ok(ierr, 'initialize failed') + + call sph_get_version(major, minor, patch, ierr) + call assert_ok(ierr, 'version failed') + if (major /= 0 .or. minor /= 1 .or. patch /= 0) call fail('unexpected version') + + call sph_db_allocate(2, ierr) + call assert_ok(ierr, 'database allocation failed') + call sph_get_particle_count(count, ierr) + call assert_ok(ierr, 'particle count failed') + if (count /= 2) call fail('unexpected particle count') + + call sph_advance_explicit(1.0e-6_rk, ierr) + call assert_ok(ierr, 'explicit advance failed') + call sph_get_current_time(time, step, ierr) + call assert_ok(ierr, 'current time failed') + if (step /= 1) call fail('unexpected step after advance') + if (abs(time - 1.0e-6_rk) > 1.0e-12_rk) call fail('unexpected time after advance') + + call sph_finalize(ierr) + call assert_ok(ierr, 'finalize failed') + +contains + + subroutine assert_ok(ierr_value, message) + integer, intent(in) :: ierr_value + character(len=*), intent(in) :: message + + if (ierr_value /= SPH_SUCCESS) call fail(message) + end subroutine assert_ok + + subroutine fail(message) + character(len=*), intent(in) :: message + + write(*, '(A)') trim(message) + stop 1 + end subroutine fail + +end program test_smoke diff --git a/todo.md b/todo.md new file mode 100644 index 0000000..7ca81b9 --- /dev/null +++ b/todo.md @@ -0,0 +1,224 @@ +# SPHLite TODO + +当前目标版本:0.1.0 + +本文档依据 `docs/v1.0_development_plan.md` 拆分。0.1.0 只搭建软件框架,不实现生产级 Water、Gas、Explosive、Solid、Shell 物理算法。 + +## 阶段 A:工程骨架 + +- [x] 创建 0.1.0 规划目录结构。 +- [x] 创建根目录 `CMakeLists.txt`。 +- [x] 配置 CMake 项目版本为 `0.1.0`。 +- [x] 配置项目语言为 C 和 Fortran。 +- [x] 配置 Fortran 95 编译标准。 +- [x] 配置 Fortran module 输出目录。 +- [x] 配置 `FortranCInterface` 名字修饰头生成。 +- [x] 创建 `sphlite_core` 静态库目标。 +- [x] 创建 `sphlite_c` 静态库目标。 +- [x] 创建 `sphlite` 命令行程序目标。 +- [x] 启用 CTest。 +- [x] 添加最小 `test_smoke` 测试目标占位。 + +## 阶段 B:Core 基础模块 + +- [x] 实现 `src/core/sph_precision.f90`。 +- [x] 在 `sph_precision` 中定义 `rk` 精度。 +- [x] 在 `sph_precision` 中定义版本号 `0.1.0`。 +- [x] 在 `sph_precision` 中定义 3D 维度常量。 +- [x] 实现 `src/core/sph_error.f90`。 +- [x] 定义 SPHLite 基础错误码。 +- [x] 实现最近错误码保存。 +- [x] 实现最近错误消息保存。 +- [x] 实现错误清理接口。 +- [x] 实现 `src/core/sph_log.f90`。 +- [x] 实现日志打开接口。 +- [x] 实现日志关闭接口。 +- [x] 实现基础 info 日志接口。 +- [x] 实现 `src/core/sph_control.f90`。 +- [x] 定义默认时间控制参数。 +- [x] 定义默认输出控制参数。 +- [x] 实现控制参数默认初始化。 + +## 阶段 C:Database 最小状态 + +- [x] 实现 `src/database/sph_database.f90`。 +- [x] 定义 `npart` 粒子数量。 +- [x] 定义粒子 external id 数组。 +- [x] 定义 phase/status/material/section 数组。 +- [x] 定义 `x0(3,npart)` 和 `x(3,npart)`。 +- [x] 定义 `v(3,npart)`、`a(3,npart)` 和 `vhalf(3,npart)`。 +- [x] 定义 `mass/rho/volume/pressure/internal_energy/temperature/h` 数组。 +- [x] 实现数据库分配接口。 +- [x] 实现数据库默认初始化接口。 +- [x] 实现数据库释放接口。 +- [x] 实现粒子数量查询接口。 +- [x] 定义 phase 常量。 +- [x] 定义 status 常量占位。 + +## 阶段 D:API 状态和 Fortran API + +- [x] 实现 `src/interface/sph_api_state.f90`。 +- [x] 保存 API 初始化状态。 +- [x] 实现 `src/interface/sph_api.f90`。 +- [x] 实现 `sph_initialize`。 +- [x] 实现 `sph_finalize`。 +- [x] 实现 `sph_get_version`。 +- [x] 实现 `sph_get_last_error`。 +- [x] 实现 `sph_get_particle_count`。 +- [x] 实现 `sph_get_current_time`。 +- [x] 为未实现 API 返回明确错误或占位成功码。 + +## 阶段 E:Input 解析框架 + +- [x] 实现 `src/input/sph_inp_defs.f90`。 +- [x] 定义输入关键词识别常量。 +- [x] 实现 `src/input/sph_inp_helpers.f90`。 +- [x] 实现行清理和大小写规范化工具。 +- [x] 实现逗号分隔字段解析工具。 +- [x] 实现 `src/input/sph_input_reader.f90`。 +- [x] 实现 `.inp` 文件打开和逐行读取。 +- [x] 实现 `*NODE` 最小解析。 +- [x] 实现 `*ELEMENT` 占位解析。 +- [x] 实现 `*NSET` 占位解析。 +- [x] 实现 `*ELSET` 占位解析。 +- [x] 实现 `*MATERIAL` 占位解析。 +- [x] 实现 `*SECTION` 占位解析。 +- [x] 实现 `*SPHLITE ...` 扩展关键词入口。 +- [x] 对不影响运行的未知关键词发出 warning。 +- [x] 对缺失关键数据返回 error。 +- [x] 在 Fortran API 中接入 `sph_read_inp`。 +- [x] 在 Fortran API 中接入 `sph_build_model`。 + +## 阶段 F:Solver、Output 和 Restart 占位 + +- [x] 实现 `src/solver/sph_solver_explicit.f90`。 +- [x] 实现稳定时间步估计占位。 +- [x] 实现 Velocity-Verlet 最小步进。 +- [x] 在步进中更新时间和步数。 +- [x] 在 Fortran API 中接入 `sph_estimate_stable_dt`。 +- [x] 在 Fortran API 中接入 `sph_advance_explicit`。 +- [x] 在 Fortran API 中接入 `sph_run_explicit`。 +- [x] 实现 `src/output/sph_output_csv.f90`。 +- [x] 实现输出目录设置占位。 +- [x] 实现输出间隔设置占位。 +- [x] 实现最小 CSV 输出占位。 +- [x] 实现 `src/output/sph_restart.f90`。 +- [x] 实现 restart 写入占位。 +- [x] 实现 restart 读取占位。 + +## 阶段 G:物理模块占位 + +- [x] 创建 `src/water/sph_water.f90` 占位模块。 +- [x] 创建 `src/gas/sph_gas.f90` 占位模块。 +- [x] 创建 `src/explosive/sph_explosive.f90` 占位模块。 +- [x] 创建 `src/solid/sph_solid.f90` 占位模块。 +- [x] 创建 `src/shell/sph_shell.f90` 占位模块。 +- [x] 创建 `src/particle/sph_particle.f90` 占位模块。 +- [x] 创建 `src/material/sph_material.f90` 占位模块。 +- [x] 每个占位模块提供 reset 或 initialize 入口。 +- [x] 确保占位模块不声明生产级物理能力。 + +## 阶段 H:CouplingInterface 占位 + +- [x] 实现 `src/coupling_interface/sph_coupling_interface.f90`。 +- [x] 定义 coupling region 占位数据。 +- [x] 实现 coupling particle count 占位接口。 +- [x] 实现 coupling particle 导出占位接口。 +- [x] 实现 coupling facet count 占位接口。 +- [x] 实现 coupling facet 导出占位接口。 +- [x] 实现 coupling particle force 导入占位接口。 +- [x] 实现 coupling facet load 导入占位接口。 +- [x] 添加耦合功和能量诊断占位字段。 +- [x] 保持接口命名中立,不出现 FEMLite 依赖。 + +## 阶段 I:C ABI + +- [x] 创建 `include/sphlite_c_api.h`。 +- [x] 在 C 头文件中定义 phase 常量。 +- [x] 声明生命周期 C API。 +- [x] 声明输入和显式求解 C API。 +- [x] 声明粒子数量查询 C API。 +- [x] 声明输出和 restart C API 占位。 +- [x] 实现 `src/interface/sph_c_api.c`。 +- [x] 接入 Fortran-C 名字修饰头。 +- [x] 实现 C 字符串到 Fortran 字符串桥接。 +- [x] 实现 C 空指针参数检查。 +- [x] 实现 C 非正容量参数检查。 +- [x] 将 C 参数错误返回 `-1`。 +- [x] 将 Fortran 错误码原样返回 C 调用方。 +- [x] 创建 `tests/interface/test_c_api.c`。 + +## 阶段 J:CLI + +- [x] 实现 `src/app/sph_program.f90`。 +- [x] 支持 `sphlite model.inp` inspect 模式。 +- [x] 支持 `sphlite model.inp --run` 运行模式。 +- [x] CLI 调用公共生命周期 API。 +- [x] CLI 打印版本号。 +- [x] CLI 打印粒子数量。 +- [x] CLI 打印当前时间和步数。 +- [x] CLI 在错误时打印最近错误消息。 +- [x] CLI 语法风格与 FEMLite 保持一致。 + +## 阶段 K:Python 调试入口 + +- [x] 创建 `Python/sphlite_debug.py`。 +- [x] 使用 `ctypes` 加载 C ABI。 +- [x] 包装生命周期接口。 +- [x] 包装 `read_inp`。 +- [x] 包装粒子数量查询。 +- [x] 包装显式运行入口。 +- [x] 创建 `tools/testing/test_python_debug.py`。 +- [x] Python smoke 读取最小 `.inp`。 +- [x] Python smoke 查询粒子数量。 + +## 阶段 L:测试数据和测试目标 + +- [x] 创建 `tests/data/minimal_particles.inp`。 +- [x] 在最小输入中包含 `*NODE`。 +- [x] 在最小输入中包含基础 material。 +- [x] 在最小输入中包含基础 section。 +- [x] 在最小输入中包含 `*SPHLITE ...` 时间控制占位。 +- [x] 创建 `tests/unit/test_smoke.f90`。 +- [x] `test_smoke` 覆盖 initialize/finalize。 +- [x] `test_smoke` 覆盖数据库最小分配。 +- [x] `test_smoke` 覆盖最小显式步。 +- [x] 创建 `tests/module/test_input.f90`。 +- [x] `test_input` 覆盖最小 `.inp` 解析。 +- [x] `test_input` 覆盖 unknown keyword warning。 +- [x] `test_input` 覆盖关键数据缺失 error。 +- [x] 添加 CTest `smoke`。 +- [x] 添加 CTest `input`。 +- [x] 添加 CTest `c_api`。 +- [x] 添加 CTest `python_debug`。 + +## 阶段 M:Source Size 和工具 + +- [x] 创建 `tools/testing/check_source_size.py`。 +- [x] 创建 `tests/source_size_exceptions.txt`。 +- [x] 设置 Fortran 过程大小检查。 +- [x] 设置 Fortran 源文件大小检查。 +- [x] 设置 C 源文件大小检查。 +- [x] 设置 stale exception 检查。 +- [x] 添加 CTest `source_size`。 + +## 阶段 N:文档同步 + +- [x] 更新 README 的当前版本为 0.1.0。 +- [x] 更新 `docs/09_release_history.md` 的 0.1.0 计划项。 +- [x] 更新 `docs/11_benchmark_matrix.md` 的 0.1.0 gate。 +- [x] 确认 01-06 文档不声明 0.1.0 已实现物理算法。 +- [x] 记录 0.1.0 不交付范围。 + +## 阶段 O:0.1.0 验收 + +- [x] 完整配置 CMake。 +- [x] 完整编译 `sphlite_core`。 +- [x] 完整编译 `sphlite_c`。 +- [x] 完整编译 `sphlite`。 +- [x] 运行 `ctest -R "^(smoke|input|c_api|python_debug)$"`。 +- [x] 运行 `ctest -R "^source_size$"`。 +- [x] 运行 `git diff --check`。 +- [x] 确认没有提交 build 目录。 +- [x] 确认没有提交 CSV/VTK/restart 临时结果。 +- [x] 记录 0.1.0 release gate 结果。 diff --git a/tools/testing/check_source_size.py b/tools/testing/check_source_size.py new file mode 100644 index 0000000..88b4d12 --- /dev/null +++ b/tools/testing/check_source_size.py @@ -0,0 +1,128 @@ +from __future__ import annotations + +import argparse +import re +from pathlib import Path + + +FORTRAN_FILE_MAX_LINES = 700 +C_FILE_MAX_LINES = 500 +FORTRAN_PROCEDURE_MAX_LINES = 140 + + +def read_exceptions(path: Path) -> set[str]: + exceptions: set[str] = set() + if not path.exists(): + raise SystemExit(f"exception file does not exist: {path}") + for raw in path.read_text(encoding="utf-8").splitlines(): + line = raw.strip() + if not line or line.startswith("#"): + continue + exceptions.add(line.split()[0].replace("\\", "/")) + return exceptions + + +def source_files(root: Path) -> list[Path]: + skip_dirs = {".git", ".agents", ".codex"} + result: list[Path] = [] + for path in root.rglob("*"): + if not path.is_file(): + continue + rel_path = path.relative_to(root) + rel_parts = set(rel_path.parts) + if rel_parts & skip_dirs: + continue + if rel_path.parts and rel_path.parts[0].startswith("build"): + continue + if path.suffix.lower() in {".f90", ".c", ".h", ".hpp"}: + result.append(path) + return sorted(result) + + +def rel_key(root: Path, path: Path) -> str: + return path.relative_to(root).as_posix() + + +def check_file_lines(root: Path, path: Path, exceptions: set[str], errors: list[str]) -> None: + rel = rel_key(root, path) + lines = path.read_text(encoding="utf-8").splitlines() + suffix = path.suffix.lower() + if suffix in {".f90"}: + limit = FORTRAN_FILE_MAX_LINES + elif suffix in {".c", ".h", ".hpp"}: + limit = C_FILE_MAX_LINES + else: + return + if len(lines) > limit and rel not in exceptions: + errors.append(f"{rel}: {len(lines)} lines exceeds limit {limit}") + + +def check_fortran_procedures(root: Path, path: Path, exceptions: set[str], errors: list[str]) -> None: + rel = rel_key(root, path) + lines = path.read_text(encoding="utf-8").splitlines() + start_re = re.compile(r"^\s*(subroutine|function|program)\s+([a-zA-Z_][a-zA-Z0-9_]*)", re.I) + end_re = re.compile(r"^\s*end\s+(subroutine|function|program)\b", re.I) + active_name: str | None = None + active_start = 0 + + for index, line in enumerate(lines, start=1): + if active_name is None: + match = start_re.match(line) + if match: + active_name = match.group(2) + active_start = index + continue + if end_re.match(line): + size = index - active_start + 1 + key = f"{rel}:{active_name}" + if size > FORTRAN_PROCEDURE_MAX_LINES and key not in exceptions: + errors.append( + f"{key}: {size} lines exceeds procedure limit " + f"{FORTRAN_PROCEDURE_MAX_LINES}" + ) + active_name = None + + +def check_stale_exceptions(root: Path, exceptions: set[str], files: list[Path], errors: list[str]) -> None: + file_keys = {rel_key(root, path) for path in files} + possible_keys = set(file_keys) + for path in files: + if path.suffix.lower() == ".f90": + text = path.read_text(encoding="utf-8") + for match in re.finditer( + r"^\s*(subroutine|function|program)\s+([a-zA-Z_][a-zA-Z0-9_]*)", + text, + re.I | re.M, + ): + possible_keys.add(f"{rel_key(root, path)}:{match.group(2)}") + for item in exceptions: + if item not in possible_keys: + errors.append(f"stale source size exception: {item}") + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--root", required=True) + parser.add_argument("--exceptions", required=True) + args = parser.parse_args() + + root = Path(args.root).resolve() + exceptions = read_exceptions(Path(args.exceptions).resolve()) + files = source_files(root) + errors: list[str] = [] + + for path in files: + check_file_lines(root, path, exceptions, errors) + if path.suffix.lower() == ".f90": + check_fortran_procedures(root, path, exceptions, errors) + check_stale_exceptions(root, exceptions, files, errors) + + if errors: + for error in errors: + print(error) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/testing/test_python_debug.py b/tools/testing/test_python_debug.py new file mode 100644 index 0000000..7e11f47 --- /dev/null +++ b/tools/testing/test_python_debug.py @@ -0,0 +1,34 @@ +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--library", required=True) + parser.add_argument("--input", required=True) + args = parser.parse_args() + + root = Path(__file__).resolve().parents[2] + sys.path.insert(0, str(root / "Python")) + + from sphlite_debug import SPHLite + + solver = SPHLite(args.library) + solver.initialize() + try: + solver.read_inp(args.input) + solver.build_model() + count = solver.particle_count() + if count != 4: + raise AssertionError(f"expected 4 particles, got {count}") + solver.run_explicit() + finally: + solver.finalize() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())