# Dynamics 项目优化建议

> 分析日期：2026-06-12
> 版本：main (43 commits)

---

## 1. 架构优化

### 1.1 compute.py 拆分（高优先级）

**现状**：`compute.py` 1618 行，混合了以下职责：
- 物理引擎（数值积分方法 ~10 个函数）
- 文件 I/O（JSON/text 读写）
- 外部引擎管理（subprocess 调用）
- 参数加载与解析
- 主入口 main()

**建议**：按职责拆分为独立模块

```
compute/
├── __init__.py          # 导出公共 API
├── core.py              # 物理引擎: 数值积分方法, 力的计算 (~200 行)
├── io.py                # 文件 I/O: save/load display/trajectory (~300 行)
├── params.py            # 参数加载: load_coord_file, load_bond 等 (~150 行)
├── runner.py            # 运行管理: run_simulation, run_engine, run_from_config (~200 行)
├── engine_helper.py     # 外部引擎: 校准, subprocess, 进度监控 (~150 行)
└── main.py              # 主入口: main(), if __name__ == "__main__" (~30 行)
```

**收益**：可单独测试物理算法、文件读写、引擎调用

### 1.2 外部引擎代码重构（中优先级）

**现状**：C/C++/Fortran 引擎各自实现了一套：
- JSON 读取/写入（3 套独立实现）
- 物理算法（复制粘贴）
- display.txt / trajectory.txt 输出

**建议**：
- C 和 C++ 引擎共用头文件/函数库
- 物理算法提取为公共库（`engines/common/`）
- Fortran 更新支持 `save_trajectory` 兼容

---

## 2. 性能优化

### 2.1 外部引擎校准耗时（高）

**现状**：`run_engine()` 每次执行前先跑 1000 步校准测速（`_calib_nt = min(1000, max(100, total_steps // 10))`），对短时运行（~1000 步）校准占比高达 50%。

**建议**：
- 缓存校准结果：按 `(engine, NT, DT, NSTEP, n_atoms)` 哈希缓存
- 或对短运行 (<5000 步) 跳过校准
- 或只在校准目录为空时执行

```python
# 建议改动
_calib_cache = os.path.join(script_dir, "engines", engine, "_calib_cache.json")
if os.path.exists(_calib_cache):
    with open(_calib_cache) as f:
        _calib_data = json.load(f)
    if _calib_data.get("key") == _calib_key:
        _step_time = _calib_data["step_time"]
        _overhead = _calib_data["overhead"]
        skip_calibration()
```

### 2.2 display.txt 读取加速（已完成）

**现状**：已从逐行 `split()+float()` 改为 `np.genfromtxt()` 批量解析，200帧×120原子 加载仅 0.087s（测试已通过）。

### 2.3 Python 引擎性能（低）

**现状**：Python 引擎比 C 引擎慢约 6-8 倍（43s vs 7s for 10 万步）。对 50 万步以上的长时间模拟不适用。

**建议**：
- 使用 Numba JIT 加速力的计算
- 或使用 `numpy.vectorize` 替代 Python 循环（力的计算中已部分使用 numpy 数组操作）
- 文档中注明 Python 引擎仅适用于小规模测试

### 2.4 校准数据的进度条（已修复）

校准后进度条使用实时帧号更新，不再使用时间估算，避免了 `0% → 100%` 跳变。但注意校准本身不显示进度。

---

## 3. 代码质量

### 3.1 消除全局变量（高优先级）

**现状**：`compute.py` 定义了 40+ 个模块级全局变量：

```python
box_a = None
alpha = None
ATOM_IDS = None
...
```

所有算法函数直接依赖这些全局变量，导致：
- 无法并发运行两个模拟
- 无法单元测试单个函数
- 函数签名无法自文档化

**建议**：将全局状态封装为 `SimulationState` 类：

```python
@dataclass
class SimulationState:
    box_a: float = 10.0
    atom_ids: np.ndarray = None
    atom_masses: np.ndarray = None
    ...

def leapfrog(state: SimulationState, ...):
    ...
```

### 3.2 draw.py 全局变量（中优先级）

**现状**：类似的问题，`draw.py` 用了 ~30 个模块级变量：

```python
DISPLAY_X = ...
DISP_ALL_X = ...
N_FRAMES = ...
frame_idx = 0
```

**建议**：封装为 `AnimationData` 和 `CameraState` 类

### 3.3 废弃文件清理（低优先级）

以下文件可能已废弃或重复：

| 文件 | 行数 | 判断 |
|------|------|------|
| `sample.py` | 184 | 已不再被调用（抽帧已移至引擎内部） |
| `build_release_zip.py` | - | 打包脚本，非核心功能 |
| `export_web_data.py` | - | 导出脚本，非核心功能 |
| `migrate_npz_outputs.py` | - | 迁移脚本，一次性使用 |
| `tools/NumericalMethods.py` | - | 可能已过时 |
| `build/` (CMake 相关) | - | 与独立引擎编译无关 |

---

## 4. 配置管理

### 4.1 input.txt 格式统一（高优先级）

**现状**：6 个案例的 `input.txt` 格式不统一：

| 字段 | case01 | case06 |
|------|--------|--------|
| `save_trajectory` | ❌ 缺失 | ✅ 有 |
| `camera_distance/elevation/azimuth` | ❌ 缺失 | ✅ 有 |
| `move_camera` | ❌ 缺失 | ✅ 有 |
| `step_sample` | 仍然写 1 | 已改为 0 |
| `step_plot`配置 | 旧注释格式 | 新注释格式 |

**建议**：

```yaml
# 统一模板
flow:
  step_simulate: 1
  step_sample: 0           # 引擎已内置抽帧
  step_animation: 1
  save_trajectory: 0       # 默认不保留

physics:
  box_a: 10.0
  G: [0, 0, -9.8]
  method: leapfrog
  T_total: 10.0
  NSTEP: 100
  DT: 0.001

render:
  use_marker: 0
  alpha: [0.0]*6
  ball_color: [0.9, 0.2, 0.2]
  box_color: [0.8, 0.8, 0.85]
  camera:
    distance: 40.0
    elevation: 0
    azimuth: 0
    move: false
```

### 4.2 YAML 结构优化（中优先级）

**现状**：`ball_color_r/g/b` 三个独立的键，YAML 列表更自然：

```yaml
# 当前
ball_color_r: 0.90
ball_color_g: 0.20
ball_color_b: 0.20

# 建议
ball_color: [0.90, 0.20, 0.20]
```

---

## 5. 测试与质量

### 5.1 缺少测试（高优先级）

**现状**：无单元测试、无集成测试。每次修改只能手动跑案例。

**建议**：
- 为 `compute.py` 的物理算法（Leapfrog、Euler 等）添加 pytest 测试
- 为文件 I/O（`save_display_txt` / `load_display_txt` 读写一致性）添加测试
- 添加一个 `examples/case00` 最小验证案例（2 个原子，10 步）
- CI：`pytest` + 简单的集成测试脚本

### 5.2 缺少类型标注（中优先级）

```python
# 现状
def leapfrog(x, y, z, vx, vy, vz, dt, m, g, b):

# 建议
def leapfrog(
    x: np.ndarray, y: np.ndarray, z: np.ndarray,
    vx: np.ndarray, vy: np.ndarray, vz: np.ndarray,
    dt: float, m: np.ndarray, g: np.ndarray, b: np.ndarray
) -> tuple[np.ndarray, np.ndarray, np.ndarray,
           np.ndarray, np.ndarray, np.ndarray]:
```

---

## 6. 引擎一致性

### 6.1 Fortran 引擎更新（高）

**现状**：Fortran 引擎**不支持** `save_trajectory=0` 模式，总是写 JSON 格式的 `trajectory.txt`。需要：

1. 读取 `save_trajectory` 参数
2. 计算时按 NSTEP 采样
3. 写 display.txt 新格式
4. 按条件跳过 trajectory.txt 输出

参考 C 引擎的 `write_display_txt` 实现（约 40 行代码）。

### 6.2 参数默认值一致性（中）

各引擎的 `SimParams` 默认值不一致：

| 参数 | C | C++ | Fortran |
|------|---|---|---------|
| `box_a` | 无默认 | 10.0 | 10.0 (代码中) |
| `method` | leapfrog | leapfrog | leapfrog |
| `save_trajectory` | 0 | 1 | 不支持 |

---

## 7. 用户体验

### 7.1 进度条改进（低）

- 外部引擎校准阶段不显示进度（建议加 "校准中…" 文本）
- Fortran 引擎支持时，增加进度消息

### 7.2 缓存一致性（已修复）

已修复：`display.txt` 在 `save_trajectory=0` 时不再保留 `trajectory.txt`，外部引擎路径总是从 `trajectory.txt` 重新抽帧。

### 7.3 move_camera.txt 实时生效（已修复）

`draw.py` 直接读取 `move_camera.txt`，修改后重启动画即可生效，无需重新跑模拟。

---

## 8. 实施优先级

| 优先级 | 内容 | 预估工作量 |
|--------|------|-----------|
| P0 | Fortran 引擎支持 save_trajectory=0 | 2-3h |
| P0 | 全局变量封装为 SimulationState | 3-4h |
| P1 | compute.py 模块拆分 | 4-6h |
| P1 | 添加单元测试 (pytest) | 3-5h |
| P1 | input.txt 格式统一 (6个案例) | 1-2h |
| P2 | 校准缓存加速 | 1-2h |
| P2 | 废弃文件清理 | 0.5h |
| P3 | draw.py 封装 AnimationData | 2-3h |
| P3 | 类型标注 | 2-3h |

---

## 9. 快速 wins（半小时内可完成）

1. ✅ 更新 Fortran 引擎（参考 C 的 `write_display_txt` 迁移）
2. ✅ 删除 `sample.py`（已废弃）
3. ✅ 统一 6 个案例的 `input.txt` 格式
4. ✅ 添加 `save_trajectory` 到 case01-05 的 default 配置
5. ✅ 统一 `ball_color_r/g/b` 为 `ball_color` 列表