# 安装指南
## 目录
- [快速安装（5 分钟）](#快速安装5-分钟)
- [详细步骤](#详细步骤)
- [1. 安装 Python](#1-安装-python)
- [2. 安装 Python 依赖](#2-安装-python-依赖)
- [3. 安装 C 编译器（可选）](#3-安装-c-编译器可选)
- [4. 安装 CMake（可选）](#4-安装-cmake可选)
- [5. 编译 C 引擎](#5-编译-c-引擎)
- [6. 安装 VisPy（可选）](#6-安装-vispy可选)
- [验证安装](#验证安装)
- [平台对照表](#平台对照表)
- [常见问题](#常见问题)
---
## 快速安装（5 分钟）
```bash
# 1. 安装 Python 依赖
pip install -r requirements.txt
# 2. 运行案例验证
cd Dynamics
py -3 examples/case01/run_dynamics.py --no-plot
```
或手动逐个安装：
```bash
pip install numpy pyyaml tqdm matplotlib
```
看到 `[run] 完成！输出目录: ...` 即安装成功。
---
## 详细步骤
### 1. 安装 Python
**要求：Python 3.9 或更高版本。**
| 系统 | 安装方式 |
|------|---------|
| **Windows** | 从 [python.org](https://www.python.org/downloads/) 下载安装包，安装时勾选 **"Add Python to PATH"** |
| **macOS** | `brew install python` 或从 python.org 下载 |
| **Linux (Ubuntu/Debian)** | `sudo apt install python3 python3-pip` |
| **Linux (Fedora)** | `sudo dnf install python3 python3-pip` |
| **Linux (Arch)** | `sudo pacman -S python python-pip` |
验证：
```bash
py -3 --version # Windows
# 或
python3 --version # Linux/macOS
```
### 2. 安装 Python 依赖
```bash
# 一键安装所有必需 + 推荐依赖
pip install -r requirements.txt
# 或手动逐个安装
pip install numpy pyyaml tqdm
# 绘图（可选，用于生成轨迹图）
pip install matplotlib
# 根据你的 pip 命令，可能是 pip3：
pip3 install numpy pyyaml tqdm matplotlib
```
> 如果遇到网络慢，使用国内镜像：
> ```bash
> pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pyyaml tqdm matplotlib
> ```
### 3. 安装 C 编译器（可选）
> 仅当你想**编译 C/C++ 引擎**时才需要。如果只用默认的 Python 引擎可以跳过。
#### Windows — 下载安装 MSYS2 + MinGW64
MSYS2 是一个在 Windows 上提供 Linux 风格开发环境的软件包集合，
内含 MinGW64 编译器（gcc、g++、gfortran 等）。
##### 步骤 1：下载 MSYS2
访问 [msys2.org](https://www.msys2.org/)，点击页面上的 **"msys2-x86_64-…….exe"** 下载安装包。
> 国内用户如果下载慢，可尝试镜像：
> - 清华大学: https://mirrors.tuna.tsinghua.edu.cn/msys2/distrib/msys2-x86_64-latest.exe
> - 中科大: https://mirrors.ustc.edu.cn/msys2/distrib/msys2-x86_64-latest.exe
##### 步骤 2：安装 MSYS2
运行下载的安装包：
1. 一路点 **"Next"**（下一步）
2. 安装路径保持默认：`C:\msys64`
3. 勾选 **"Run MSYS2 now"**（立即运行），点 Finish
##### 步骤 3：安装 MinGW64 编译器
安装完成后会弹出 **MSYS2 UCRT64 终端**（黑窗口）。在终端中执行：
```bash
pacman -Syu
```
> 这步会更新 MSYS2 自身。更新完毕后终端可能自动关闭，请从开始菜单重新打开 **"MSYS2 UCRT64"**。
然后安装编译器：
```bash
pacman -S mingw-w64-ucrt-x86_64-gcc
```
安装 g++（可选，编译 C++ 引擎时需要）：
```bash
pacman -S mingw-w64-ucrt-x86_64-gcc
```
安装 gfortran（可选，编译 Fortran 引擎时需要）：
```bash
pacman -S mingw-w64-ucrt-x86_64-gcc-fortran
```
安装 make（可选，直接用 Makefile 编译时需要）：
```bash
pacman -S make
```
> 如果安装时提示选择软件包版本，直接回车选默认即可。
##### 步骤 4：添加环境变量
MSYS2 安装完成后，需要把编译器所在目录添加到系统的 **PATH** 环境变量中，这样在 CMD 或 PowerShell 中直接输入 `gcc` 就能调用。
**操作步骤：**
1. 打开 **系统属性** → **高级** → **环境变量**
- 快捷键：Win + R，输入 `sysdm.cpl`，回车 → 高级 → 环境变量
- 或：右键"此电脑" → 属性 → 高级系统设置 → 环境变量
2. 在 **"系统变量"** 列表中找到 `Path`，选中后点 **"编辑"**
3. 点 **"新建"**，添加以下路径：
```
C:\msys64\ucrt64\bin
```
> 如果安装时修改了路径，请替换为实际安装路径。
4. 点 **"确定"** 关闭所有对话框
##### 步骤 5：验证安装
打开一个新的 **CMD** 或 **PowerShell** 窗口（不是 MSYS2 终端），运行：
```bash
gcc --version
```
如果显示类似以下信息，说明安装成功：
```
gcc.exe (Rev13, Built by MSYS2 project) 15.2.0
Copyright (C) 2025 Free Software Foundation, Inc.
```
如果提示 `'gcc' 不是内部或外部命令`，说明环境变量未生效：
- 检查是否添加了正确的路径（`C:\msys64\ucrt64\bin`）
- 检查是否打开了**新的**命令行窗口（旧的窗口不识别新的环境变量）
- 重启电脑使环境变量生效
##### 步骤 6：编译 C 引擎
```bash
cd Dynamics\engines\c
gcc -O3 -march=native -o build\dynamics_c.exe main.c -lm
```
> 如果 MSYS2 安装在非默认路径，编译时可能需要指定完整路径：
> ```bash
> C:\msys64\ucrt64\bin\gcc -O3 -o build\dynamics_c.exe main.c -lm
> ```
##### 完整安装 MSYS2 + 编译器一键脚本
将以下内容保存为 `install_msys2.bat`，以管理员身份运行：
```batch
@echo off
echo 本脚本将安装 MSYS2 和 MinGW64 编译器
echo 请确保已下载 MSYS2 安装包: https://www.msys2.org/
echo.
REM 检查是否已安装
if exist "C:\msys64\ucrt64\bin\gcc.exe" (
echo 检测到 gcc 已安装，跳过编译安装步骤
goto check_path
)
echo 请手动运行 MSYS2 UCRT64 终端，执行以下命令：
echo.
echo pacman -Syu
echo pacman -S mingw-w64-ucrt-x86_64-gcc
echo.
echo 安装完成后重新运行此脚本。
pause
exit /b
:check_path
echo 检查环境变量...
echo %PATH% | findstr /C:"C:\msys64\ucrt64\bin" >nul
if %errorlevel% equ 0 (
echo 环境变量已设置
) else (
echo 警告: C:\msys64\ucrt64\bin 不在 PATH 中
echo 请手动添加：系统属性 → 高级 → 环境变量 → Path → 新建
)
echo.
gcc --version
echo.
echo 安装验证完成!
pause
```
#### macOS
```bash
# 安装 Xcode Command Line Tools（包含 clang）
xcode-select --install
# 或通过 Homebrew 安装 gcc
brew install gcc
```
#### Linux (Ubuntu/Debian)
```bash
sudo apt install gcc g++ gfortran
```
#### Linux (Fedora)
```bash
sudo dnf install gcc gcc-c++ gcc-gfortran
```
### 4. 安装 CMake（可选）
> 仅当你想用 **CMake 方式编译引擎** 时才需要。如果只用 gcc 直接编译可跳过。
#### 下载安装
| 系统 | 安装方式 |
|------|---------|
| **Windows** | ① 从 [cmake.org/download](https://cmake.org/download/) 下载 `.msi` 安装包 → 安装时勾选 **"Add CMake to system PATH"**
② 或使用 winget：`winget install Kitware.CMake` |
| **macOS** | `brew install cmake`
或从 cmake.org 下载 `.dmg` 安装包 |
| **Linux (Ubuntu/Debian)** | `sudo apt install cmake` |
| **Linux (Fedora)** | `sudo dnf install cmake` |
| **Linux (Arch)** | `sudo pacman -S cmake` |
#### 验证安装
打开新的终端，运行：
```bash
cmake --version
```
预期输出：
```
cmake version 3.29.0
CMake suite maintained and supported by Kitware (kitware.com/cmake).
```
> 如果提示 `'cmake' 不是内部或外部命令`，说明未添加到 PATH：
> - **Windows**：重新运行安装包，选择 **"Add CMake to the system PATH for all users"**
> - 或手动将 CMake 安装目录（如 `C:\Program Files\CMake\bin`）添加到环境变量
#### CMake 基本用法
CMake 采用 **源码外构建**（out-of-source build），所有编译中间文件生成在 `build/` 目录中，
不会污染源码目录。
```bash
# 1. 在项目根目录下配置（只需执行一次）
cd Dynamics
cmake -B build
# 2. 编译（--build 会自动调用 make / nmake / MSBuild）
cmake --build build
# 3. 只编译特定引擎
cmake --build build --target dynamics_c # C 引擎
cmake --build build --target dynamics_cpp # C++ 引擎
cmake --build build --target dynamics_f90 # Fortran 引擎
cmake --build build --target all-engines # 全部（默认）
# 4. 指定编译配置
cmake -B build -DCMAKE_BUILD_TYPE=Debug # Debug 模式（含符号表）
cmake -B build -DCMAKE_BUILD_TYPE=Release # Release 模式（-O3 优化）
# 5. 清理后重新编译
rm -rf build # Windows: rmdir /s /q build
cmake -B build
cmake --build build
```
#### CMake 在 Windows 上的注意事项
**情况 A：使用 MinGW（MSYS2）**
```bash
# 确保 gcc 在 PATH 中
gcc --version
# 配置时指定 MinGW Makefiles 生成器
cmake -B build -G "MinGW Makefiles"
# 编译
cmake --build build
# 或者用 ninja（如果安装了 ninja）
cmake -B build -G "Ninja"
cmake --build build
```
**情况 B：使用 Visual Studio**
如果安装了 Visual Studio，CMake 会自动检测并使用 MSVC 编译器：
```bash
# 在 "Developer Command Prompt for VS" 中运行
cmake -B build
cmake --build build --config Release
```
> 也可在 CMake GUI 中操作：
> 1. 打开 `cmake-gui`
> 2. 源码目录：`D:/.../Dynamics`
> 3. 构建目录：`D:/.../Dynamics/build`
> 4. 点 **Configure** → 选择 VC 或 MinGW → 点 **Generate**
> 5. 点 **Open Project** 在 VS 中打开，或直接点 **Build**
#### CMake 交叉编译
从任意平台编译到其他平台（需安装对应交叉编译器）：
```bash
# 编译到 Windows（需 mingw-w64）
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-mingw.cmake
cmake --build build
# 编译到 Linux（需 Linux 交叉编译器）
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-linux.cmake
cmake --build build
# 编译到 macOS（需 osxcross）
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-macos.cmake
cmake --build build
```
### 5. 编译 C 引擎
#### 方式一：用 gcc 直接编译（最快）
```bash
cd engines/c
gcc -O3 -march=native -o build/dynamics_c.exe main.c -lm
```
#### 方式二：用 CMake（跨平台推荐）
```bash
# 配置
cmake -B build
# 只编译 C 引擎
cmake --build build --target dynamics_c
# 或编译全部引擎
cmake --build build
```
#### 方式三：用 Python 脚本
```bash
py -3 build_engines.py --target dynamics_c
```
#### 验证 C 引擎
```bash
# 确认可执行文件已生成
ls engines/c/build/dynamics_c.exe
# 直接运行测试
engines/c/build/dynamics_c.exe examples/case01/input examples/case01/output engines/c/param.json
```
> `ls` 在 Windows 上可用 `dir` 替代。
### 6. 安装 VisPy（可选）
> 仅当你想观看 **3D 动画** 时才需要。
```bash
pip install vispy PyQt5
```
验证：
```bash
py -3 -c "from vispy import app; print('VisPy 安装成功')"
```
---
## 验证安装
### 基础验证（Python 引擎）
```bash
cd Dynamics
py -3 examples/case01/run_dynamics.py --no-plot
```
预期输出末尾：
```
[run] 完成！输出目录: .../examples/case01/output
[run] 运行 python draw.py 查看动画。
```
### 完整验证（包括绘图）
```bash
py -3 examples/case01/run_dynamics.py
```
会在 `examples/case01/output/` 下生成：
- `trajectory.txt` — 完整轨迹
- `display.txt` — 动画数据
- `trajectory_plots.png` — 轨迹图
- `dynamics.log` — 计算日志
### C 引擎验证
```bash
# 修改 parameters.yaml 中 engine: python → engine: c
# 或用命令行指定
py -3 examples/case01/run_dynamics.py
```
预期输出中出现 `[C-engine]` 字样。
### 动画验证
```bash
py -3 draw.py examples/case01/output
```
会弹出一个 3D 窗口，显示原子运动。
---
## 平台对照表
| 组件 | Windows | macOS | Linux |
|------|---------|-------|-------|
| **Python** (必需) | python.org 安装包 | `brew install python` | `apt install python3` |
| **numpy** (必需) | `pip install numpy` | 同上 | 同上 |
| **PyYAML** (必需) | `pip install pyyaml` | 同上 | 同上 |
| **tqdm** (推荐) | `pip install tqdm` | 同上 | 同上 |
| **matplotlib** (可选) | `pip install matplotlib` | 同上 | 同上 |
| **C 编译器** (可选) | MSYS2 MinGW | Xcode CLT / brew gcc | `apt install gcc` |
| **CMake** (可选) | cmake.org / winget | `brew install cmake` | `apt install cmake` |
| **VisPy** (可选) | `pip install vispy PyQt5` | `pip install vispy PyQt5` | `pip install vispy` |
| **交叉编译→Windows** | — | `brew install mingw-w64` | `apt install mingw-w64` |
| **交叉编译→Linux** | MSYS2 中 `pacman -S mingw-w64-x86_64-linux-gnu` | `brew install x86_64-elf-gcc` | — |
| **交叉编译→macOS** | 需 osxcross | — | 需 osxcross |
---
## 常见问题
### Q: `pip` 命令找不到？
Python 3 的包管理命令：
```bash
# Windows
py -3 -m pip install numpy
# Linux/macOS
python3 -m pip install numpy
```
### Q: `gcc` 命令找不到？
| 系统 | 解决 |
|------|------|
| **Windows (MSYS2)** | 将 `C:\msys64\ucrt64\bin` 添加到 PATH |
| **macOS** | 运行 `xcode-select --install` |
| **Linux** | `sudo apt install gcc` |
### Q: 运行 `draw.py` 闪退？
确保已安装 VisPy 和 PyQt5：
```bash
pip install vispy PyQt5
```
如果仍闪退，直接运行查看错误信息：
```bash
py -3 draw.py examples/case01/output
```
### Q: 网络慢，pip 安装失败？
使用国内镜像：
```bash
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pyyaml tqdm matplotlib vispy PyQt5
```
### Q: 如何使用 C 引擎？
```yaml
# 1. 修改 examples/case01/input/parameters.yaml
engine: c
# 2. 先编译
cd engines/c
gcc -O3 -march=native -o build/dynamics_c.exe main.c -lm
# 3. 运行
cd ../..
py -3 examples/case01/run_dynamics.py
```
### Q: 如何安装旧版 Python？
项目要求 Python 3.9+。如果系统自带 Python 2（某些旧版 Linux），请单独安装 Python 3：
```bash
# Ubuntu
sudo apt install python3 python3-pip
# 然后用 python3 和 pip3 代替 python 和 pip
python3 examples/case01/run_dynamics.py
```