# Dynamics

多语言动力学数值积分与轨迹可视化框架。

支持 Python、C、C++、Fortran 多种语言实现同一套物理引擎，共享同一套可视化管线
（抽帧、绘图、3D 动画），直接在 `input.txt` 中切换引擎即可对比性能。

## 快速开始

```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/
│       │   ├── input.txt         ← 唯一配置文件（YAML 格式）
│       │   ├── coord.txt
│       │   ├── connection.txt
│       │   └── bond.txt
│       └── output/
│           ├── trajectory.txt   ← 完整轨迹
│           ├── display.txt      ← 抽帧数据（动画用）
│           ├── trajectory_plots.png
│           └── dynamics.log     ← 计算日志
│
└── .workbuddy/memory/        ← 工作记忆（AI 辅助开发用）
```

## 配置文件 (`input.txt` — 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
# input.txt 中改一行
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
```

## 工作原理

```
input.txt
      │
      ▼
 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 参考实现结果一致
- **可视化**：一套代码搞定所有语言的轨迹展示