Files

T

admin 5de80d4f7e modified: CMakeLists.txt

modified:   INSTALL.md
	modified:   README.md
	modified:   build_release_zip.py
	modified:   compute.py
	new file:   doc/index.html
	modified:   dynamics.py
	modified:   engines/c/main.c
	modified:   engines/cpp/main.cpp
	modified:   engines/fortran/main.f90
	modified:   examples/case01/input/coord.txt
	renamed:    examples/case01/input/parameters.yaml -> examples/case01/input/input.txt
	modified:   examples/case01/run_dynamics.py
	new file:   examples/case02/input/bond.txt
	new file:   examples/case02/input/connection.txt
	new file:   examples/case02/input/coord.txt
	new file:   examples/case02/input/input.txt
	new file:   examples/case02/run_dynamics.py

2026-05-20 16:03:59 +08:00

14 KiB

Raw Blame History

安装指南

快速安装（5 分钟）

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 运行案例验证
cd Dynamics
py -3 examples/case01/run_dynamics.py --no-plot

或手动逐个安装：

pip install numpy pyyaml tqdm matplotlib

看到 [run] 完成！输出目录: ... 即安装成功。

详细步骤

1. 安装 Python

要求：Python 3.9 或更高版本。

系统	安装方式
Windows	从 python.org 下载安装包，安装时勾选 "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`

验证：

py -3 --version    # Windows
# 或
python3 --version  # Linux/macOS

2. 安装 Python 依赖

# 一键安装所有必需 + 推荐依赖
pip install -r requirements.txt

# 或手动逐个安装
pip install numpy pyyaml tqdm

# 绘图（可选，用于生成轨迹图）
pip install matplotlib

# 根据你的 pip 命令，可能是 pip3：
pip3 install numpy pyyaml tqdm matplotlib

如果遇到网络慢，使用国内镜像：
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，点击页面上的 "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

运行下载的安装包：

一路点 "Next"（下一步）
安装路径保持默认：C:\msys64
勾选 "Run MSYS2 now"（立即运行），点 Finish

步骤 3：安装 MinGW64 编译器

安装完成后会弹出 MSYS2 UCRT64 终端（黑窗口）。在终端中执行：

pacman -Syu

这步会更新 MSYS2 自身。更新完毕后终端可能自动关闭，请从开始菜单重新打开 "MSYS2 UCRT64"。

然后安装编译器：

pacman -S mingw-w64-ucrt-x86_64-gcc

安装 g++（可选，编译 C++ 引擎时需要）：

pacman -S mingw-w64-ucrt-x86_64-gcc

安装 gfortran（可选，编译 Fortran 引擎时需要）：

pacman -S mingw-w64-ucrt-x86_64-gcc-fortran

安装 make（可选，直接用 Makefile 编译时需要）：

pacman -S make

如果安装时提示选择软件包版本，直接回车选默认即可。

步骤 4：添加环境变量

MSYS2 安装完成后，需要把编译器所在目录添加到系统的 PATH 环境变量中，这样在 CMD 或 PowerShell 中直接输入 gcc 就能调用。

操作步骤：

打开 系统属性 → 高级 → 环境变量
- 快捷键：Win + R，输入 sysdm.cpl，回车 → 高级 → 环境变量
- 或：右键"此电脑" → 属性 → 高级系统设置 → 环境变量
在 "系统变量" 列表中找到 Path，选中后点 "编辑"
点 "新建"，添加以下路径：
```
C:\msys64\ucrt64\bin
```
如果安装时修改了路径，请替换为实际安装路径。
点 "确定" 关闭所有对话框

步骤 5：验证安装

打开一个新的 CMD 或 PowerShell 窗口（不是 MSYS2 终端），运行：

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 引擎

cd Dynamics\engines\c
gcc -O3 -march=native -o build\dynamics_c.exe main.c -lm

如果 MSYS2 安装在非默认路径，编译时可能需要指定完整路径：
C:\msys64\ucrt64\bin\gcc -O3 -o build\dynamics_c.exe main.c -lm

完整安装 MSYS2 + 编译器一键脚本

将以下内容保存为 install_msys2.bat，以管理员身份运行：

@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

# 安装 Xcode Command Line Tools（包含 clang）
xcode-select --install

# 或通过 Homebrew 安装 gcc
brew install gcc

Linux (Ubuntu/Debian)

sudo apt install gcc g++ gfortran

Linux (Fedora)

sudo dnf install gcc gcc-c++ gcc-gfortran

4. 安装 CMake（可选）

仅当你想用 CMake 方式编译引擎 时才需要。如果只用 gcc 直接编译可跳过。

下载安装

系统	安装方式
Windows	① 从 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`

验证安装

打开新的终端，运行：

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/ 目录中，不会污染源码目录。

# 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）

# 确保 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 编译器：

# 在 "Developer Command Prompt for VS" 中运行
cmake -B build
cmake --build build --config Release

也可在 CMake GUI 中操作：

打开 cmake-gui

源码目录：D:/.../Dynamics

构建目录：D:/.../Dynamics/build

点 Configure → 选择 VC 或 MinGW → 点 Generate

点 Open Project 在 VS 中打开，或直接点 Build

CMake 交叉编译

从任意平台编译到其他平台（需安装对应交叉编译器）：

# 编译到 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 直接编译（最快）

cd engines/c
gcc -O3 -march=native -o build/dynamics_c.exe main.c -lm

方式二：用 CMake（跨平台推荐）

# 配置
cmake -B build

# 只编译 C 引擎
cmake --build build --target dynamics_c

# 或编译全部引擎
cmake --build build

方式三：用 Python 脚本

py -3 build_engines.py --target dynamics_c

验证 C 引擎

# 确认可执行文件已生成
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 动画 时才需要。

pip install vispy PyQt5

验证：

py -3 -c "from vispy import app; print('VisPy 安装成功')"

验证安装

基础验证（Python 引擎）

cd Dynamics
py -3 examples/case01/run_dynamics.py --no-plot

预期输出末尾：

[run] 完成！输出目录: .../examples/case01/output
[run] 运行 python draw.py 查看动画。

完整验证（包括绘图）

py -3 examples/case01/run_dynamics.py

会在 examples/case01/output/ 下生成：

trajectory.txt — 完整轨迹
display.txt — 动画数据
trajectory_plots.png — 轨迹图
dynamics.log — 计算日志

C 引擎验证

# 修改 input.txt 中 engine: python → engine: c
# 或用命令行指定
py -3 examples/case01/run_dynamics.py

预期输出中出现 [C-engine] 字样。

动画验证

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 的包管理命令：

# 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：

pip install vispy PyQt5

如果仍闪退，直接运行查看错误信息：

py -3 draw.py examples/case01/output

Q: 网络慢，pip 安装失败？

使用国内镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy pyyaml tqdm matplotlib vispy PyQt5

Q: 如何使用 C 引擎？

# 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：

# Ubuntu
sudo apt install python3 python3-pip

# 然后用 python3 和 pip3 代替 python 和 pip
python3 examples/case01/run_dynamics.py

14 KiB Raw Blame History Unescape Escape

安装指南

目录

快速安装（5 分钟）

详细步骤

1. 安装 Python

2. 安装 Python 依赖

3. 安装 C 编译器（可选）

Windows — 下载安装 MSYS2 + MinGW64

步骤 1：下载 MSYS2

步骤 2：安装 MSYS2

步骤 3：安装 MinGW64 编译器

步骤 4：添加环境变量

步骤 5：验证安装

步骤 6：编译 C 引擎

完整安装 MSYS2 + 编译器一键脚本

macOS

Linux (Ubuntu/Debian)

Linux (Fedora)

4. 安装 CMake（可选）

下载安装

验证安装

CMake 基本用法

CMake 在 Windows 上的注意事项

CMake 交叉编译

5. 编译 C 引擎

方式一：用 gcc 直接编译（最快）

方式二：用 CMake（跨平台推荐）

方式三：用 Python 脚本

验证 C 引擎

6. 安装 VisPy（可选）

验证安装

基础验证（Python 引擎）

完整验证（包括绘图）

C 引擎验证

动画验证

平台对照表

常见问题

Q: pip 命令找不到？

Q: gcc 命令找不到？

Q: 运行 draw.py 闪退？

Q: 网络慢，pip 安装失败？

Q: 如何使用 C 引擎？

Q: 如何安装旧版 Python？

14 KiB

Raw Blame History

Q: `pip` 命令找不到？

Q: `gcc` 命令找不到？

Q: 运行 `draw.py` 闪退？