docs: 添加 examples/Readme.md 总览（6个案例介绍）

2026-06-11 13:32:23 +08:00
parent 20bfdf2f18
commit 8261017879
1 changed files with 106 additions and 0 deletions
@@ -0,0 +1,106 @@
+# Dynamics 示例案例
+
+本目录包含 6 个从简单到复杂的物理模拟案例，均基于 `../dynamics.py` 框架运行。
+
+---
+
+## 案例一览
+
+| 案例 | 标题 | 简介 | 原子数 | 力类型 |
+|---|---|---|---|---|
+| [case01](./case01/) | **双粒子弹簧系统** | 两个原子由弹簧连接，在重力场中运动 | 2 | 重力 + 弹簧 |
+| [case02](./case02/) | **行星运动** | 地球绕太阳椭圆公转（万有引力） | 2 | 万有引力 |
+| [case03](./case03/) | **日地月系统（失败）** | 地球绕太阳、月球绕地球，参数不当导致失稳 | 3 | 万有引力 |
+| [case04](./case04/) | **日地月系统（成功）** | 地球绕太阳、月球绕地球，稳定轨道 | 3 | 万有引力 |
+| [case05](./case05/) | **一维原子链纵波** | 驱动原子 1 沿 x 轴振动，产生纵波传播 | 60 | 弹簧 + 驱动力 |
+| [case06](./case06/) | **一维原子链横波** | 驱动原子 1 沿 z 轴振动，产生横波传播 | 60 | 弹簧 + 驱动力 |
+
+---
+
+## 各案例详细说明
+
+### case01 — 双粒子弹簧系统
+
+两个原子通过弹簧连接，在均匀重力场中自由运动。原子 1 位于 x=-1，原子 2 位于 x=1（初始 z=1），展示了在重力作用下的耦合振动与落体运动的复合。
+
+- **力开关**：重力场开，弹簧键力开
+- **算法**：leapfrog（蛙跳法）
+- **物理**：重力 m·g + 弹簧胡克力
+
+### case02 — 行星运动
+
+模拟地球绕太阳的椭圆轨道运动（一个固定大质量中心体 + 一个绕行小质量体）。采用万有引力相互作用。
+
+- **力开关**：万有引力开（含强度参数）
+- **算法**：leapfrog（蛙跳法）
+- **物理**：牛顿万有引力 F = G·m₁·m₂/r²
+
+### case03 — 日地月系统（失败案例）
+
+三体系统：太阳（中心）、地球、月球。由于初始条件或参数设置不当，轨道不稳定，展示了数值模拟中参数选择的重要性。
+
+- **力开关**：万有引力开
+- **算法**：leapfrog（蛙跳法）
+- **状态**：轨道发散或碰撞
+
+### case04 — 日地月系统（成功案例）
+
+与 case03 相同的三体系统，但采用了恰当的初始条件和参数，地球和月球都能维持稳定的轨道运动。
+
+- **力开关**：万有引力开
+- **算法**：leapfrog（蛙跳法）
+- **状态**：稳定椭圆轨道
+
+### case05 — 一维原子链纵波
+
+60 个原子沿 x 轴等间距排列（间距 1），相邻原子用弹簧（k=1.0, L₀=1.0）连接。原子 1 受 x 方向驱动力 `x(t)=0.5·cos(2π·t)`，产生沿链传播的**纵波**（压缩波/疏密波）。原子 x 方向自由（fix_x=0），y/z 锁定。
+
+- **力开关**：弹簧键力开，驱动力开
+- **算法**：leapfrog（蛙跳法）
+- **波速**：快（x 方向弹簧力为线性）
+- **渲染**：Marker 模式（GPU 实例化，60 原子）
+
+### case06 — 一维原子链横波
+
+与 case05 相同的原子链，但驱动力沿 z 方向 `z(t)=0.5·cos(2π·0.1·t+90°)`，原子 z 方向自由（fix_z=0），x/y 锁定。振动在横向传播，形成**横波**。
+
+- **力开关**：弹簧键力开，驱动力开
+- **算法**：leapfrog（蛙跳法）
+- **波速**：慢（z 方向弹簧力呈几何非线性，类似 FPU 系统）
+- **渲染**：Marker 模式（GPU 实例化，60 原子）
+
+---
+
+## 通用使用方法
+
+```bash
+# 进入任意案例目录
+cd examples/case05
+
+# 完整运行（模拟 + 采样 + 3D 动画）
+python run_dynamics.py
+
+# 仅运行模拟，跳过 3D 动画
+python run_dynamics.py --no-plot
+
+# 手动查看 3D 动画
+python ../../draw.py output/
+```
+
+每个案例的 `input/input.txt` 中可配置所有物理参数、力开关、算法、渲染方式等。
+
+## 框架结构
+
+```
+dynamics/
+├── dynamics.py          # 统一运行入口
+├── compute.py           # Python 物理引擎
+├── draw.py              # VisPy 3D 动画
+├── plot_wave.py         # 波形能量图（需 matplotlib）
+├── engines/             # C / C++ / Fortran 引擎
+├── examples/            # 案例（本目录）
+│   ├── case01/
+│   ├── ...
+│   └── case06/
+└── output/              # 默认输出目录
+```