# 星历转换：从 CR3BP 到真实星历

## 为什么要转换

CR3BP 假设地球月球做匀速圆运动、忽略太阳引力等摄动，因此算出的周期轨道
是理想化的。真实星历模型包含月球轨道偏心率、太阳引力、光压等摄动，轨道
不再是严格周期。任务设计最终需要在真实星历模型里有一条**标称轨道**（可
传播、可做轨道保持基准），这就需要把 CR3BP 初猜修正到星历模型。

轨道设计工具的工作流：

```
CR3BP 初猜（形状参数 → 微分修正收敛到周期轨道）
   → 星历修正（多重打靶，把初猜拟合到真实动力学）
   → 标称星历（跨整个传播时长，画布中为虚线）
```

## 修正方法

星历修正用**多重打靶**（multiple shooting）：把整条轨道按**拼接点**
（patch points）分段，逐段在真实力模型中外推，再迭代修正各段初值使段间
位置、速度连续。软件支持的修正方法：

| 方法 | 说明 |
|------|------|
| `standard` | Rust 多重打靶的稳定轨道路径别名（与 `two_level` 等价，保留给 API 兼容，不在界面暴露） |
| `two_level` | Rust 多重打靶（稳定轨道默认路径）。e2m2e 5.8.0 起旧的 Python 两级修正实现已删除，`standard` 与它指向同一条实现；界面只保留这个对外名称，避免把同一算法显示成两个选项 |
| `segmented` | 分段打靶拼接：**不稳定轨道专用**，由算法对 Halo/NRHO/DPO 自动选用 |

## 为什么不稳定轨道（Halo/NRHO/DPO）必须走 segmented

`two_level` 的流程是修正 1 圈加自由外推。这里的 `two_level` 是稳定轨道路径的对外名称，不再表示已删除的旧 Python 两级实现。对稳定轨道（DRO 等）这没有
问题；但对不稳定轨道，每圈 STM（状态转移矩阵）可达 1e7 量级，1 圈外的
外推必然发散，自由外推几圈后轨迹就不知去向。

`segmented` 全程分段打靶：每一段都约束在真实动力学上，段间只要求连续性，
不依赖外推 1 圈仍贴轨道的假设，因此对不稳定轨道收敛。e2m2e 5.6.5 起
`design_orbit` 对 Halo/NRHO **自动重定向 segmented**，5.8.1 起 DPO 同属此列，用户不需要手选，
面板上的 `correction_method` 只决定稳定轨道路径。

## 修正质量

修正完成后，工具返回两组诊断：

- **收敛残差**：多重打靶牛顿迭代的解范数残差，反映迭代是否收敛；
- **连续性误差**：修正完成后逐段重新传播，比较传播终点与目标拼接点的
  物理位置偏差，反映修正后轨迹在真实动力学中的连续性。

轨道设计结果 JSON 中的 `correction_converged` / `correction_iterations`
即收敛状态与迭代次数；位置连续性容差默认对齐 e2m2e 的
`CORRECTION_TOL_KM`（2e-2 km）。

## 已知的模型限制

- **参考历元**：转换必须由用户显式提供起始历元（`epoch`）。相同输入在
  不同历元下可能得到不同星历结果（月球位置不同）。
- **大幅 DRO 的长期漂移**：e2m2e 5.6.x 修复了大幅 DRO 星历发散问题
  （速度残差加权），但大幅 DRO 在真实星历中仍有数万 km 量级的准周期
  漂移，这是真实动力学特性，不是 bug，由轨道保持处理。
- **Lissajous**：CR3BP 初猜经中心流形约化生成多点有界参考轨迹，修正到
  星历后保持有界。
- **NRHO**：e2m2e 5.7.3 起与 Halo 解耦采样策略，默认等时间拼接点 +
  1 圈/段（上游 #473），GUI 默认量级（L2 南、近月高 5000 km、约 1 个月）
  segmented 约数十秒收敛；删近月点采样保留为对照工具。产物含标称星历，
  可作轨道保持输入。圈间漂移仍是星历下固有准周期特征，由轨道保持处理。