Files
MDHelper/docs/installation.md
T
2026-05-25 17:12:00 +08:00

3.4 KiB

安装与编译

基本依赖

推荐环境:

  • CMake 3.20 或更高。
  • C++20 编译器。
  • Windows 下推荐 Visual Studio 2022。
  • 可选:CUDA Toolkit,用于 CUDA 构建路径。
  • 可选:OpenMP,用于 CPU 多线程。
  • 可选:MPI,用于分布式计算与 halo 同步。

CUDA 构建

项目目前常用 CUDA 13.0 构建目录:

cmake -S . -B cmake-build-cuda13
cmake --build cmake-build-cuda13 --config Release --target M3Frame

如果已经生成过构建目录,只需要重新编译:

cmake --build cmake-build-cuda13 --config Release --target M3Frame

主程序输出位置:

cmake-build-cuda13/Release/M3Frame.exe

如果 CUDA 编译失败,优先检查:

  • CUDA Toolkit 是否安装。
  • Visual Studio 版本是否被 CUDA 支持。
  • CMake 是否找到正确的 nvcc。
  • 是否启用了不支持的 GPU 架构。

Debug 构建

cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug --config Debug

Debug 构建便于定位 XML 解析、网格质量、接触和材料本构问题。

Examples 构建

案例 benchmark 通常在独立 examples 构建目录中:

cmake -S examples -B cmake-build-examples-migrated
cmake --build cmake-build-examples-migrated --config Debug

也可以只构建一个目标:

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 运行时可以通过环境变量设置线程数:

$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 运行案例验证程序。

运行检查

编译后可执行:

.\cmake-build-cuda13\Release\M3Frame.exe

如果没有给出配置文件,程序应打印帮助信息或提示需要输入文件。之后用一个轻量案例检查完整流程:

.\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。