Metadata-Version: 2.4
Name: e2m2e
Version: 5.3.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: tqdm>=4.66
Requires-Dist: spiceypy>=8.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyerfa>=2.0.1.5
Requires-Dist: sympy>=1.12 ; extra == 'normal-form'
Requires-Dist: joblib>=1.3 ; extra == 'normal-form'
Provides-Extra: normal-form
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS.md
Summary: Earth to Moon, Moon to Earth — 地月空间转移轨道设计库
Keywords: astrodynamics,orbital mechanics,CR3BP,three-body problem,transfer orbit,earth-moon,cislunar,trajectory design
Author-email: ouyangjiahong <ouyangjiahong22@nudt.edu.cn>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/cislunarspace/e2m2e
Project-URL: Issues, https://github.com/cislunarspace/e2m2e/issues
Project-URL: Repository, https://github.com/cislunarspace/e2m2e

# e2m2e — Earth to Moon, Moon to Earth

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/e2m2e)](https://pypi.org/project/e2m2e/)
[![CI](https://github.com/cislunarspace/e2m2e/actions/workflows/ci.yml/badge.svg)](https://github.com/cislunarspace/e2m2e/actions/workflows/ci.yml)

e2m2e 是面向地月空间任务规划的**算法工具集基础设施**。在“LLM+Agent”式自主任务规划系统中，大模型负责理解任务意图、分解与编排子任务，e2m2e 负责提供精确可靠的轨道计算工具：建立地月空间的动力学模型，生成周期轨道族，设计轨道之间的转移路径，并把结果画出来检查。

## 安装

### uv（推荐）

[uv](https://docs.astral.sh/uv/) 是本项目推荐的包管理器，速度快、依赖解析可靠。

```bash
uv pip install e2m2e
```

在自己的项目中使用：

```bash
uv init my-project && cd my-project
uv add e2m2e
```

从源码开发（需要 [Rust 工具链](https://www.rust-lang.org/tools/install)，用于构建积分器内核）：

```bash
git clone https://github.com/cislunarspace/e2m2e.git
cd e2m2e
uv sync
```

### conda

e2m2e 没有 conda-forge 包，conda 用来创建和管理 Python 环境，环境内仍用 pip 安装：

```bash
conda create -n e2m2e python=3.12
conda activate e2m2e
pip install e2m2e
```

### pip

```bash
pip install e2m2e
```

可选依赖（Hamiltonian 正规化流水线）：

```bash
pip install e2m2e[normal-form]
```

### SPICE 内核

星历动力学需要 NASA SPICE 内核文件，放置在 `kernels/` 目录或 `$SPICE_KERNEL_DIR` 指定的路径。

国内用户推荐从项目的 [GitHub Release](https://github.com/cislunarspace/e2m2e/releases) 下载：`kernels-v1` 中打包了全部必需内核（行星星历、地球自转、月球姿态、闰秒与行星常数），下载后放入 `kernels/` 目录即可。官方来源（网络可达时）：[NASA NAIF](https://naif.jpl.nasa.gov/naif/data.html)。

## 快速开始

创建地月 CR3BP 系统，生成一个 DRO 轨道族：

```python
from e2m2e.core import CR3BP_System, Orbit, CR3BP_Dynamics
from e2m2e.algorithms import DifferentialCorrection, Continuation

system = CR3BP_System(mu=0.01215, primary="earth", secondary="moon")
dynamics = CR3BP_Dynamics(system=system)

# 种子轨道
initial_state = [0.79188556619742, 0.0, 0.0, 0.0, 0.53682, 0.0]
seed_orbit = Orbit(states=[initial_state], times=[0])

# 微分修正收敛到周期轨道
corrector = DifferentialCorrection(dynamic=dynamics)
corrector.setup_2D_symmetric_x_fixed_x0(x0=initial_state[0])
seed_dro = corrector.iterate_correction(initial_guess=seed_orbit)

# 延拓生成轨道族
continuation = Continuation(corrector=corrector)
family = continuation.natural_continuation(
    seed_orbit=seed_dro,
    param_range=(0.14, 0.9),
    step_size=0.005,
)
```

更多示例（星历动力学、多重打靶、转移设计、可视化）见[在线文档](https://cislunarspace.github.io/e2m2e/)和 [`examples/`](examples/) 目录。

## 使命与进度

航天任务规划正从“人在回路”走向自主规划。传统模式依赖地面人员逐级分解任务、调配资源，决策链条冗长，单次在轨服务任务的地面支持普遍在十余个小时。李胤慷等在[《基于“LLM+Agent”的在轨服务自主任务规划技术》](https://doi.org/10.19328/j.cnki.2096-8655.2026.01.016)（上海航天，2026）中提出了新架构：大模型负责语义理解、任务分解与编排，专业算法工具负责精确计算，两者通过 MCP 协议协同，分钟级生成全流程任务规划方案。

![“LLM+Agent”协同推理决策架构（李胤慷等，2026）](docs/_static/paper/llm-agent-architecture.jpg)

这套架构能否落地，关键在算法工具集。大模型是概率生成模型，自身做不了精确轨道计算，它输出的方案是否可信，取决于所调用工具的精度与可靠性。没有标准化、经过验证、可被调用的算法工具集，自主规划就是空中楼阁。

这里有一个容易产生的误解需要说清。用户把任务需求和相关信息输入大模型，大模型调用工具求解问题，最终呈现的结果并非大模型自身生成，而是工具计算得出的。大模型做的只是把工具的输出整理成便于人阅读和理解的形式。看起来像是模型直接根据输入生成了答案，实际上这些结果既不是大模型算出来的，也不是它推理出来的，而是工具的运算输出。因此，工具集的质量决定了整个系统的质量，这正是 e2m2e 要守住的地方。

![算法工具集整体架构（李胤慷等，2026）](docs/_static/paper/algorithm-toolkit-architecture.jpg)

地月空间是这套范式最重要的应用场景之一，空间站、导航与通信星座、月面往返都从这里起步。e2m2e 的使命是建设地月空间方向的算法工具集基础设施，把轨道建模、轨道生成、转移设计等算法做成精确、标准化、可被上层规划系统调用的开源工具库。上图中算法封装层与接口协议层的能力，正是 e2m2e 已经建成和正在补齐的部分。

**已经建成：**

- 两套动力学模型：简化三体模型（CR3BP，用于快速设计）和高精度星历模型（基于 SPICE，用于精确外推），以及两者之间的转换
- 周期轨道族生成：DRO、Halo、Lyapunov、Lissajous、Butterfly、Dragonfly、共振轨道（RO）等，配微分修正、多重打靶、延拓等数值算法
- 高精度力模型：点质量与第三体引力、球谐重力场（含固体潮）、大气阻力、太阳光压、连续推力，传播精度已与 GMAT、DFH 对齐到亚百米级
- 转移轨道设计：网格搜索 + 非线性规划的两步法
- 坐标系转换（J2000/ITRF 等，与 GMAT 兼容）和 2D/3D 可视化

**正在进行和计划中的：**

- 更多轨道族：DPO、三角平动点附近的 SPO/LPO、Horseshoe 等
- 小推力转移与 LEO/GEO 端点条件
- Hamiltonian 正规化流水线的进一步完善（把平动点附近轨道化简为少数表征参数）
- 面向上层规划系统的服务化封装。下一步把 e2m2e 封装为 MCP 服务器，接入下图所示的异构模型交互框架，让大模型可以像调用 Lambert、C-W 工具一样调用地月轨道算法

![基于 MCP 的异构模型交互框架（李胤慷等，2026）](docs/_static/paper/mcp-interaction-framework.jpg)

详细的能力清单与 API 文档见[在线文档](https://cislunarspace.github.io/e2m2e/)；逐版本变更见 [CHANGELOG.md](CHANGELOG.md)。

## 文档

在线文档：<https://cislunarspace.github.io/e2m2e/>

本地构建：

```bash
uv sync --group docs
uv run sphinx-build -b html docs docs/_build/html
```

## 测试与代码规范

```bash
uv run pytest tests/
uv run ruff check .
```

## 贡献

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

## 引用

```bibtex
@software{e2m2e,
  title = {e2m2e: Earth to Moon, Moon to Earth Transfer Orbit Design Library},
  author = {ouyangjiahong},
  email = {ouyangjiahong22@nudt.edu.cn},
  url = {https://github.com/cislunarspace/e2m2e},
  version = {5.3.0},
  year = {2026},
}
```

使命叙述依据的文献：

> 李胤慷, 王浩, 袁容昊, 等. 基于“LLM+Agent”的在轨服务自主任务规划技术[J]. 上海航天（中英文）, 2026, 43(1): 169-179. DOI: [10.19328/j.cnki.2096-8655.2026.01.016](https://doi.org/10.19328/j.cnki.2096-8655.2026.01.016).

## License

[Apache 2.0](LICENSE)

