# 安装指南

## 目录

- [快速安装（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. 打开 **系统属性** → **高级** → **环境变量**
   - 快捷键：<kbd>Win</kbd> + <kbd>R</kbd>，输入 `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"** <br> ② 或使用 winget：`winget install Kitware.CMake` |
| **macOS** | `brew install cmake` <br> 或从 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
# 修改 input.txt 中 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/input.txt
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
```
