Initial MDHelper implementation

This commit is contained in:
shenw
2026-05-25 17:12:00 +08:00
commit 50b15b02c7
45 changed files with 11654 additions and 0 deletions
+127
View File
@@ -0,0 +1,127 @@
# 安装与编译
## 基本依赖
推荐环境:
- CMake 3.20 或更高。
- C++20 编译器。
- Windows 下推荐 Visual Studio 2022。
- 可选:CUDA Toolkit,用于 CUDA 构建路径。
- 可选:OpenMP,用于 CPU 多线程。
- 可选:MPI,用于分布式计算与 halo 同步。
## CUDA 构建
项目目前常用 CUDA 13.0 构建目录:
```powershell
cmake -S . -B cmake-build-cuda13
cmake --build cmake-build-cuda13 --config Release --target M3Frame
```
如果已经生成过构建目录,只需要重新编译:
```powershell
cmake --build cmake-build-cuda13 --config Release --target M3Frame
```
主程序输出位置:
```text
cmake-build-cuda13/Release/M3Frame.exe
```
如果 CUDA 编译失败,优先检查:
- CUDA Toolkit 是否安装。
- Visual Studio 版本是否被 CUDA 支持。
- CMake 是否找到正确的 `nvcc`。
- 是否启用了不支持的 GPU 架构。
## Debug 构建
```powershell
cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug --config Debug
```
Debug 构建便于定位 XML 解析、网格质量、接触和材料本构问题。
## Examples 构建
案例 benchmark 通常在独立 examples 构建目录中:
```powershell
cmake -S examples -B cmake-build-examples-migrated
cmake --build cmake-build-examples-migrated --config Debug
```
也可以只构建一个目标:
```powershell
cmake --build cmake-build-examples-migrated --config Debug --target benchmark_sph_oscillating_droplet
```
注意:benchmark 程序一般只读取结果并计算误差。运行 benchmark 前,应先用 `M3Frame.exe pipeline.xml` 生成结果。
## OpenMP
OpenMP 主要用于:
- 粒子划分。
- 网格采样。
- 邻域搜索。
- FEM/SPH 部分循环。
是否启用由 CMake 配置和编译器能力决定。案例 XML 中通常通过 `backend="openmp"` 或并行参数控制。
Windows 运行时可以通过环境变量设置线程数:
```powershell
$env:OMP_NUM_THREADS=4
.\cmake-build-cuda13\Release\M3Frame.exe examples\...\pipeline.xml
```
## MPI
MPI 当前用于:
- SPH halo 同步。
- 并行邻域搜索框架。
- 部分粒子和网格生成任务。
Windows 下通常依赖 Microsoft MPI。若未安装 MPI,应关闭相关选项或使用非 MPI 构建。
## 推荐构建矩阵
| 用途 | 构建目录 | 配置 | 说明 |
|---|---|---|---|
| 日常运行 | `cmake-build-cuda13` | `Release` | 主程序和较快算例。 |
| 调试 | `cmake-build-debug` | `Debug` | 检查崩溃、断言和 XML 解析。 |
| benchmark | `cmake-build-examples-migrated` | `Debug` | 运行案例验证程序。 |
## 运行检查
编译后可执行:
```powershell
.\cmake-build-cuda13\Release\M3Frame.exe
```
如果没有给出配置文件,程序应打印帮助信息或提示需要输入文件。之后用一个轻量案例检查完整流程:
```powershell
.\cmake-build-cuda13\Release\M3Frame.exe examples\sph\benchmarks\oscillating_droplet\pipeline.xml
```
## 常见编译问题
| 问题 | 建议 |
|---|---|
| 找不到 CUDA | 检查 `CUDA_PATH` 和 CMake CUDA 编译器。 |
| MSBuild 访问 SDK 被拒绝 | 用普通终端或管理员权限重新构建。 |
| CUDA 与 MSVC 不兼容 | 调整 Visual Studio 工具集或 CUDA 版本。 |
| 链接库冲突 | 检查 Release/Debug 运行库设置。 |
| 头文件找不到 | 确认从项目根目录配置 CMake。 |
| benchmark 找不到结果 | 先运行对应 `pipeline.xml`。 |