# Dynamics 示例案例 v2.1

10 个从简单到复杂的物理模拟案例，展示分子动力学模拟框架的多种应用场景

## 📋 案例总览

01

### 双粒子弹簧系统

两个原子由弹簧连接，在重力场中运动

Python 弹簧 重力
02

### 行星运动

地球绕太阳椭圆公转（万有引力）

Python 万有引力
03

### 日地月系统（失稳）

三体系统参数不当导致轨道发散

Python 万有引力 失败案例
04

### 日地月系统（稳定）

三体系统稳定轨道，经希尔半径检验

Python 万有引力
05

### 一维原子链纵波

驱动原子 1 沿 x 振动，产生纵波传播

Python 弹簧 驱动力
06

### 一维原子链横波

带阻尼的横波传播（FPU 非线性）

C 引擎 弹簧 驱动力
07

### 一维链横波·双端驱动

原子 1 + 原子 120 同时驱动，波相遇干涉

C 引擎 弹簧 驱动力
08

### 双原子弹簧·C 引擎测试

2 原子快速验证 C 引擎正确性

C 引擎 弹簧
09

### 一维链纵波·Fortran 引擎

Fortran 引擎驱动的纵波，GPU 实例化渲染

Fortran 弹簧 驱动力
10

### 一维链纵波·能量分析

纵波传播 + 轨迹/能量图绘制

C 引擎 弹簧 驱动力

## 📖 各案例详情

### case01 — 双粒子弹簧系统

- Python 引擎
- 弹簧键力
- 重力场

两个原子通过弹簧连接，在均匀重力场（G=[0,0,-9.8]）中自由运动。展示重力作用下的耦合振动与落体运动的复合。

🔬 教学案例：算法 leapfrog，渲染 Sphere 模式，建议作为入门第一个案例

### case02 — 行星运动

- Python 引擎
- 万有引力

模拟地球绕太阳的椭圆轨道运动。大质量中心体固定，小质量体绕行。

🌍 万有引力强度 gravity_strength=100.0，leapfrog 算法确保能量守恒

### case03 — 日地月系统（失败案例）

- Python 引擎
- 万有引力
- 失稳

三体系统（太阳-地球-月球）。初始条件或参数设置不当，轨道不稳定。展示数值模拟中参数选择的重要性。

### case04 — 日地月系统（成功案例）

- Python 引擎
- 万有引力

与 case03 相同的三体系统，但采用恰当的初始条件：地球置于近日点（$r=10$），$v_z=520$ 接近圆轨道；月球缩至希尔半径（$r_H\approx1.0$）以内的 $r=0.5$，相对速度 $v_{\text{rel}}\approx127$，确保月球被地球稳定束缚。

✅ 与 case03 对比学习：初始条件对数值稳定性的影响。地月距 0.5 在地球希尔半径以内，满足稳定性条件

### case05 — 一维原子链纵波

- Python 引擎
- 弹簧键力
- 驱动力

60 原子沿 x 轴排列。原子 1 受 x 方向驱动力，产生沿链传播的纵波（压缩波）。原子 x 自由，y/z 锁定。

📈 纵波波速快（x 方向弹簧力线性），T_total=10, NSTEP=50

### case06 — 一维原子链横波（带阻尼）

- C 引擎
- 弹簧键力
- 驱动力

120 原子沿 x 轴排列，带横向阻尼。驱动沿 z 方向，原子 z 自由，x/y 锁定。横波传播具有 FPU 型非线性。

⚡ C 引擎高性能计算，T_total=1000, NSTEP=500，支持运动相机

### case07 — 一维链横波·双端驱动

- C 引擎
- 弹簧键力
- 驱动力

120 原子，原子 1 和原子 120 同时受 z 方向驱动（同频率、相位差 90°），两端向中间传播的横波相遇。

🌊 波干涉演示，视觉放大 display_amp=[1,1,10] 便于观察小幅度振动

### case08 — 双原子弹簧（C 引擎快速测试）

- C 引擎
- 弹簧键力

2 原子弹簧系统，T_total=100 的短时模拟。用于快速验证 C 引擎的正确性和性能。

🧪 引擎快速验证用例，无动画输出

### case09 — 一维链纵波·Fortran 引擎

- Fortran 引擎
- 弹簧键力
- 驱动力

40 原子沿 x 轴排列，Fortran 引擎驱动的纵波传播测试。使用 `use_marker: 1`（GPU 实例化 Marker 模式）加速渲染，验证 Fortran 引擎与其他引擎的输出兼容性。

🔧 Fortran 引擎兼容性验证，T_total=200, NSTEP=100。Marker 模式下 40 原子以 GPU 点精灵渲染，帧率高

### case10 — 一维链纵波·能量分析

- C 引擎
- 弹簧键力
- 驱动力

40 原子纵波传播，支持轨迹/能量图绘制（step_plot=1）。原子 x/y/z 全部自由。

📊 能量分析演示，T_total=10, NSTEP=20

## 🚀 使用方法

### 命令行

`# 进入案例目录并运行
cd examples/case05
python run_dynamics.py
# 仅运行模拟，跳过动画
python run_dynamics.py --no-plot
# 手动启动 3D 动画
python ../../draw.py output/`

### 案例选择指南

目标 | 推荐案例
--- | ---
快速上手框架 | case01
天体力学/万有引力 | case02 / case04
波动物理（纵波） | case05
波动物理（横波/非线性/阻尼） | case06
双端驱动/波干涉 | case07
引擎性能对比 | case08 (C) / case09 (Fortran)
能量分析 | case10

### 配置

每个案例的 `input/input.txt` 可配置物理参数、力开关、算法、引擎、渲染方式等。

### 引擎架构

外部引擎（C / C++ / Fortran）以 DLL 方式 运行，主程序通过 ctypes 在进程内直接调用，不启动子进程。DLL 预编译在 `engines/release/` 中，源码位于 `engines/src/{c,cpp,fortran}/`。重新编译： `cd engines/src/c && make dll`

## 📁 框架结构

    dynamics/
    ├── dynamics.py          # 统一运行入口
    ├── compute.py           # 物理引擎 + 显示数据生成
    ├── draw.py              # VisPy 3D 动画
    ├── plot_wave.py         # 波形能量图
    ├── .gitattributes       # DLL/二进制文件保护
    ├── engines/
    │   ├── engine_dll.py    # DLL 加载器（ctypes）
    │   ├── python/          # Python 引擎（dynamics_lib.py）
    │   ├── release/         # 预编译 DLL（C / C++ / Fortran）
    │   └── src/             # 引擎源码
    │       ├── c/           # C 源码 + Makefile → dynamics_c.dll
    │       ├── cpp/         # C++ 源码 + Makefile → dynamics_cpp.dll
    │       └── fortran/     # Fortran 源码 + Makefile → dynamics_f90.dll
    ├── examples/            # 案例目录
    │   ├── case01/  ~  case10/
    └── output/              # 默认输出目录