218 lines
6.6 KiB
Markdown
218 lines
6.6 KiB
Markdown
# Dynamics
|
||
|
||
多语言动力学数值积分与轨迹可视化框架。
|
||
|
||
支持 Python、C、C++、Fortran 多种语言实现同一套物理引擎，共享同一套可视化管线
|
||
（抽帧、绘图、3D 动画），直接在 `parameters.yaml` 中切换引擎即可对比性能。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
pip install numpy pyyaml matplotlib tqdm
|
||
|
||
# 2. 运行案例（计算 + 抽帧 + 绘图 + 动画）
|
||
py -3 examples/case01/run_dynamics.py
|
||
|
||
# 3. 仅计算（跳过绘图，最小依赖）
|
||
py -3 examples/case01/run_dynamics.py --no-plot
|
||
|
||
# 4. 仅播放动画（需先安装 VisPy）
|
||
pip install vispy PyQt5
|
||
py -3 draw.py examples/case01/output
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
Dynamics/
|
||
├── dynamics.py ← 统一入口：调度引擎、抽帧、绘图、动画
|
||
├── compute.py ← Python 参考引擎 + 外部引擎调度
|
||
├── draw.py ← VisPy 3D 动画（所有引擎共用）
|
||
├── plot_trajectory.py ← Matplotlib 静态绘图
|
||
├── sample.py ← 抽帧生成显示数据
|
||
├── export_web_data.py ← 导出 Web 可视化数据
|
||
│
|
||
├── engines/ ← 多语言计算引擎
|
||
│ ├── c/ ← C 语言 (完整实现，已编译)
|
||
│ │ ├── main.c
|
||
│ │ ├── Makefile
|
||
│ │ └── build/dynamics_c.exe
|
||
│ ├── cpp/ ← C++ (模板)
|
||
│ │ └── main.cpp
|
||
│ └── fortran/ ← Fortran (模板)
|
||
│ └── main.f90
|
||
│
|
||
├── examples/
|
||
│ └── case01/
|
||
│ ├── input/
|
||
│ │ ├── parameters.yaml ← 唯一配置文件
|
||
│ │ ├── coord.txt
|
||
│ │ ├── connection.txt
|
||
│ │ └── bond.txt
|
||
│ └── output/
|
||
│ ├── trajectory.txt ← 完整轨迹
|
||
│ ├── display.txt ← 抽帧数据（动画用）
|
||
│ ├── trajectory_plots.png
|
||
│ └── dynamics.log ← 计算日志
|
||
│
|
||
└── .workbuddy/memory/ ← 工作记忆（AI 辅助开发用）
|
||
```
|
||
|
||
## 配置文件 (`parameters.yaml`)
|
||
|
||
所有控制集中在一个文件里：
|
||
|
||
```yaml
|
||
# ── 计算引擎 ──────────────────────────────────
|
||
engine: python # python | c | cpp | fortran
|
||
|
||
# ── 流程控制（每步独立开关） ─────────────────
|
||
step_simulate: 1 # 运行物理模拟
|
||
step_sample: 1 # 抽帧
|
||
step_plot: 1 # 绘图
|
||
step_animation: 0 # VisPy 3D 动画
|
||
|
||
# ── 物理参数 ──────────────────────────────────
|
||
G: [0.0, 0.0, -9.8] # 重力
|
||
B: [0.0, 0.0, 0.0] # 阻尼
|
||
method: leapfrog # explicit_euler | implicit_euler | midpoint | leapfrog
|
||
NT: 100000
|
||
DT: 0.0001
|
||
NSTEP: 1000
|
||
|
||
# ── 显示参数 ──────────────────────────────────
|
||
# 六个面的透明度，按 [-x,+x,-y,+y,-z,+z] 顺序
|
||
alpha: [0.0, 0.0, 0.2, 0.2, 0.0, 0.0]
|
||
```
|
||
|
||
## 多语言引擎
|
||
|
||
### 一键切换
|
||
|
||
```yaml
|
||
# parameters.yaml 中改一行
|
||
engine: c # 切换到 C 引擎
|
||
engine: python # 切回 Python
|
||
```
|
||
|
||
### 编译 C 引擎
|
||
|
||
**方式一：CMake（推荐，跨平台）**
|
||
|
||
```bash
|
||
# 安装 CMake (https://cmake.org/download/)
|
||
# 然后：
|
||
cmake -B build # 配置
|
||
cmake --build build # 编译全部
|
||
cmake --build build --target dynamics_c # 只编译 C 引擎
|
||
|
||
# 编译完成后：
|
||
py -3 examples/case01/run_dynamics.py # 配合 Python 调度器使用
|
||
```
|
||
|
||
**方式二：直接 gcc（最快）**
|
||
|
||
```bash
|
||
cd engines/c
|
||
gcc -O3 -march=native -o build/dynamics_c.exe main.c -lm
|
||
```
|
||
|
||
### 交叉编译
|
||
|
||
从任意平台编译到其他平台：
|
||
|
||
```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
|
||
```
|
||
|
||
或用 Python 一键脚本（自动调用 CMake）：
|
||
|
||
```bash
|
||
py -3 build_engines.py # 本地编译全部
|
||
py -3 build_engines.py --target dynamics_c # 只编译 C 引擎
|
||
py -3 build_engines.py --clean # 清理后重新编译
|
||
```
|
||
|
||
所有平台统一输出到 `engines/*/build/dynamics_c.exe`，Python 自动识别调用。
|
||
|
||
### 性能对比 (case01, 10000步)
|
||
|
||
| 引擎 | 耗时 | 相对速度 |
|
||
|------|------|----------|
|
||
| Python | ~1.3 s | 1× |
|
||
| C | ~0.05 s | 26× |
|
||
|
||
## 3D 动画功能
|
||
|
||
运行 `py -3 draw.py examples/case01/output` 后：
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 鼠标拖拽 | 旋转视角 |
|
||
| 滚轮 | 缩放 |
|
||
| 点击 **`reset`** | 复位相机 + 从头播放 |
|
||
| 点击 **`info`** | 显示/隐藏信息面板 |
|
||
| 点击 **`axes`** | 显示/隐藏坐标轴 |
|
||
| `Q` / `E` 键 | 绕屏幕法线旋转 90° |
|
||
|
||
所有原子用 tab10 调色板着色，成键用灰色线段连接。
|
||
|
||
## 依赖
|
||
|
||
| 用途 | 包 | 是否必需 |
|
||
|------|----|---------|
|
||
| 数值计算 | `numpy` | 是 |
|
||
| 配置解析 | `PyYAML` | 是 |
|
||
| 进度条 | `tqdm` | 推荐 |
|
||
| 静态绘图 | `matplotlib` | 可选 |
|
||
| 3D 动画 | `vispy` + `PyQt5` | 可选 |
|
||
| C/C++/Fortran 编译 | `cmake` (>= 3.15) | 可选（编译引擎时） |
|
||
| C 快速编译 | `gcc` (MSYS2/MinGW) | 可选 |
|
||
|
||
```bash
|
||
pip install numpy pyyaml tqdm matplotlib vispy PyQt5
|
||
```
|
||
|
||
## 工作原理
|
||
|
||
```
|
||
parameters.yaml
|
||
│
|
||
▼
|
||
dynamics.py ──→ run_from_config() 加载全局参数
|
||
│
|
||
├── engine=python? → compute.py → run_simulation()
|
||
│ (Leapfrog / Euler)
|
||
└── engine=c? → subprocess → engines/c/dynamics_c.exe
|
||
(Leapfrog in C)
|
||
│
|
||
▼
|
||
trajectory.txt (JSON, 统一格式)
|
||
│
|
||
▼
|
||
sample.py → display.txt (抽帧数据)
|
||
│
|
||
├── plot_trajectory.py → trajectory_plots.png
|
||
└── draw.py → VisPy 3D 窗口
|
||
```
|
||
|
||
所有引擎的输出都是相同格式的 `trajectory.txt`（JSON 嵌套数组），
|
||
后续的抽帧、绘图、动画完全复用，每个引擎只需实现纯计算逻辑。
|
||
|
||
## 项目初衷
|
||
|
||
- **教学**：对比不同语言的数值计算性能
|
||
- **验证**：确保 C/C++/Fortran 实现与 Python 参考实现结果一致
|
||
- **可视化**：一套代码搞定所有语言的轨迹展示
|