569 lines
14 KiB
Markdown
569 lines
14 KiB
Markdown
# 安装指南
|
||
|
||
## 目录
|
||
|
||
- [快速安装（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
|
||
# 修改 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
|
||
```
|