# case04 — 日地月三体系统 稳定轨道版本

太阳、地球、月球三体系统，采用真实比例的质量和万有引力模拟，地球和月球维持稳定椭圆轨道。

Python 引擎 万有引力 3 粒子 | leapfrog 算法 | 稳定轨道

## 一、物理系统概览

本案例模拟真实的日-地-月三体系统：

- 太阳：位于原点，质量为 $M_\odot$，固定不动（fix_x=fix_y=fix_z=1）
- 地球：绕太阳公转，质量为 $M_\oplus$，近日点出发
- 月球：绕地球公转（同时跟随地球绕太阳），质量为 $M_\text{moon}$

原子间万有引力由 `gravity_strength` 缩放控制，$F = G \dfrac{m_1 m_2}{r^2}$。

## 二、天体真实参数

### 2.1 质量

天体 | 质量 / kg | 模拟质量（月球=1）
--- | --- | ---
太阳 | $1.989 \times 10^{30}$ | $27\,000$
地球 | $5.972 \times 10^{24}$ | $81$
月球 | $7.35 \times 10^{22}$ | $1$

质量比：$M_\odot : M_\oplus : M_\text{moon} \approx 27\,100\,000 : 81.3 : 1$
模拟中采用缩放比例 $27\,000 : 81 : 1$（太阳质量缩至 $1/1000$ 以保持数值稳定）。

### 2.2 轨道参数

轨道 | 半长轴 $a$ | 偏心率 $e$ | 半短轴 $b$ | 周期
--- | --- | --- | --- | ---
地球绕太阳 | $1.4960 \times 10^8$ km (1 AU) | $0.0167$ | $1.4958 \times 10^8$ km | 365.25 天
月球绕地球 | $3.844 \times 10^5$ km | $0.0549$ | $3.838 \times 10^5$ km | 27.32 天

比例：$R_{\text{日地}} : R_{\text{地月}} \approx 389 : 1$
地月距离约为日地距离的 $1/389$。

## 三、轨道力学

### 3.1 交互式轨道示意图

拖动下方滑块改变偏心率 $e$，观察轨道形状的变化和参数标注：

偏心率 e = 0.0170（地球真实值 0.0167）

### 3.2 月球绕地球轨道

拖动下方滑块改变月球轨道偏心率 $e_\text{moon}$（真实值 0.0549）：

偏心率 e = 0.0549（月球真实值 0.0549）

### 3.3 偏心率定义

偏心率 $e$ 描述椭圆轨道偏离正圆的程度：

$$e = \frac{c}{a}$$

其中 $c = ea$ 为偏心距（焦点到椭圆中心的距离），$a$ 为半长轴。

$e$ 值 | 轨道形状 | 说明
--- | --- | ---
$e = 0$ | 正圆形 | 速度恒定，距离恒定
$0 < e < 1$ | 椭圆 | 近日点/近地点速度最大，远日点/远地点速度最小
$e = 1$ | 抛物线 | 逃逸轨道，速度恰好达到逃逸速度
$e > 1$ | 双曲线 | 飞越轨道，速度超过逃逸速度

### 3.4 半长轴与半短轴的关系

$$b = a\sqrt{1 - e^2}$$

当 $e \ll 1$ 时，$b \approx a\left(1 - \dfrac{e^2}{2}\right)$，椭圆度非常微小。

### 3.5 近日点与远日点

近日点（距太阳最近）和远日点（距太阳最远）的距离分别为：

$$r_{\text{peri}} = a(1 - e), \qquad r_{\text{ap}} = a(1 + e)$$

在近日点轨道速度最大，在远日点轨道速度最小：

$$v_{\text{peri}} = \sqrt{\frac{GM(1+e)}{a(1-e)}}, \qquad v_{\text{ap}} = \sqrt{\frac{GM(1-e)}{a(1+e)}}$$

### 3.6 开普勒三大定律

1. 椭圆定律：行星轨道是椭圆，太阳位于椭圆的一个焦点上。
2. 面积定律：行星与太阳的连线在相等时间内扫过相等的面积。
3. 周期定律：公转周期的平方与半长轴的立方成正比：$T^2 \propto a^3$。

验证：在本模拟中，你可以通过轨迹图观察面积定律是否成立——地球在近日点移动更快，远日点移动更慢。

## 四、模拟参数

### 4.1 缩放说明

真实尺度无法直接用于模拟（日地距离 1.5 亿 km），因此采用缩放参数。当前 case04 的配置为教学演示而简化：

参数 | 值 | 说明
--- | --- | ---
`gravity_strength` | 100.0 | 万有引力强度
`box_a` | 30.0 | 盒子半边长
`method` | leapfrog | 蛙跳法（辛积分器，能量守恒）
`T_total` | 10.0 s | 总模拟时间
`NSTEP` | 2 | 抽帧间隔（密采帧）

### 4.2 初始构型

天体 | 质量 | 位置 $(x,y,z)$ | 速度 $(v_x,v_y,v_z)$ | 固定约束
--- | --- | --- | --- | ---
太阳 | $27\,000$ | $(0,0,0)$ | $(0,0,0)$ | 全部固定
地球 | $81$ | $(10,0,0)$ | $(0,0,520)$ | 无
月球 | $1$ | $(10.5,0,0)$ | $(0,0,647)$ | 无

地球在 $z$ 方向获得初速度 $v=520$，产生绕太阳的轨道运动（接近圆轨道）；月球在地球基础上附加 $v\approx127$ 的绕地速度，形成绕地球的轨道。速度由圆形轨道公式 $v = \sqrt{G_{\text{eff}} M / r}$ 计算，其中 $G_{\text{eff}} = \text{gravity\_strength} = 100$。

验证：地球速度 $v_\oplus = \sqrt{100 \times 27\,000 / 10} \approx 519.6$，设 520 正确。月球相对速度 $v_{\text{rel}} = \sqrt{100 \times 81 / 0.5} \approx 127.3$，设 127 正确。地月距离 0.5 在地球希尔半径 $r_H \approx 10 \times (81 / 81\,000)^{1/3} \approx 1.0$ 之内，可确保轨道稳定。

## 五、使用方法

`# 进入 case04 目录并运行
cd examples/case04
python run_dynamics.py
# 仅输出轨迹图，跳过动画
python run_dynamics.py --no-plot`

配置文件：`input/input.txt`（物理参数）、`input/coord.txt`（初始位置/速度）。

## 六、与 case03 的对比

| case03（失败案例） | case04（成功案例）
--- | --- | ---
轨道状态 | 轨道发散或碰撞 | 稳定椭圆轨道
关键差异 | 初始速度或质量比不恰当 | 合理的初值和参数
教学意义 | 展示参数选择的重要性 | 展示正确的三体运动

教学建议：先运行 case03 观察失稳，再运行 case04 对比稳定轨道，理解初始条件对数值模拟的关键影响。

## 七、已知局限

- 太阳真实质量为月球 $27\,100\,000$ 倍，模拟中缩至 $27\,000$ 倍以保持数值稳定（$1/1000$）
- 轨道半径未按真实比例缩放（真实日地距是地月距的 389 倍，模拟中约为 20 倍，受希尔半径约束，月球已尽可能放远）
- 未考虑月球轨道倾角（真实地月轨道有约 5° 的倾角）
- leapfrog 算法为能量守恒的辛积分器，长期稳定，但步长过大时仍可能偏离真实轨道
- 太阳固定不动可作为教学简化，但严格三体模拟中应让所有天体在质心系中自由运动