# 三体问题求解器 - 纯Python方案

一个用于模拟和可视化三体问题的Python库。使用四阶龙格-库塔法数值求解牛顿引力下的三体运动。

## 功能特性

- **纯Python实现**：无需外部依赖（除可视化外）
- **高精度数值积分**：使用四阶龙格-库塔法（RK4）
- **多种初始条件**：预置8字形轨道、拉格朗日点等经典配置
- **完整可视化**：3D轨迹、2D投影、相空间图、能量分析
- **物理守恒验证**：动量、角动量、能量守恒检查
- **模块化设计**：易于扩展和自定义

## 安装要求

### 必需依赖
- Python 3.7+
- NumPy
- Matplotlib

### 安装方法
```bash
# 克隆仓库
git clone <repository-url>
cd three_body_problem

# 安装依赖
pip install numpy matplotlib
```

## 快速开始

### 基本使用
```python
import numpy as np
from three_body_problem import ThreeBodySolver, Particle, ThreeBodyConfig, ThreeBodyVisualizer

# 创建8字形轨道配置
particles = ThreeBodyConfig.create_figure8_config()

# 创建求解器
solver = ThreeBodySolver(particles, dt=0.001)

# 模拟10年
solver.simulate(total_time=10.0)

# 可视化
visualizer = ThreeBodyVisualizer()
visualizer.plot_trajectories(solver, title="8字形三体轨道")
visualizer.show()
```

### 运行示例
```python
# 运行8字形轨道示例
from three_body_problem.examples import figure8
solver = figure8.run_figure8_example()

# 运行拉格朗日点示例
from three_body_problem.examples import lagrange
solver_l4 = lagrange.run_lagrange_example(lagrange_point=4, total_time=50.0)

# 运行随机系统示例
from three_body_problem.examples import random
solver_random = random.run_random_example(seed=42, total_time=15.0)
```

## 核心组件

### 1. Particle（质点类）
表示三体问题中的一个天体。

```python
# 创建质点
particle = Particle(
    mass=1.0,                    # 质量（太阳质量）
    position=[1.0, 0.0, 0.0],    # 位置向量 [AU]
    velocity=[0.0, 6.28, 0.0],   # 速度向量 [AU/年]
    name="Earth",                # 名称
    color="blue"                 # 可视化颜色
)
```

### 2. ThreeBodySolver（求解器类）
主求解器，使用RK4方法积分运动方程。

```python
# 创建求解器
solver = ThreeBodySolver(particles, dt=0.001)

# 模拟一段时间
solver.simulate(total_time=10.0, progress_interval=1000)

# 获取轨迹
trajectories = solver.get_trajectories()

# 计算质心
center_of_mass = solver.get_center_of_mass()

# 检查守恒定律
momentum_error, angular_momentum_error, energy_error = solver.get_conservation_errors()
```

### 3. ThreeBodyConfig（配置管理）
提供多种预置初始条件。

```python
# 8字形轨道（著名的稳定解）
particles = ThreeBodyConfig.create_figure8_config()

# 拉格朗日点配置（L4或L5）
particles_l4 = ThreeBodyConfig.create_lagrange_point_config(lagrange_point=4)
particles_l5 = ThreeBodyConfig.create_lagrange_point_config(lagrange_point=5)

# 随机配置
particles_random = ThreeBodyConfig.create_random_config(
    masses=None,           # 随机质量
    position_range=2.0,    # 位置范围 ±2 AU
    velocity_scale=1.0     # 速度缩放因子
)

# 自定义配置
config_dict = {
    'particle_1': {'mass': 1.0, 'position': [1,0,0], 'velocity': [0,1,0], 'name': 'Star A'},
    'particle_2': {'mass': 1.0, 'position': [-1,0,0], 'velocity': [0,-1,0], 'name': 'Star B'},
    'particle_3': {'mass': 0.1, 'position': [0,1,0], 'velocity': [-1,0,0], 'name': 'Star C'}
}
particles_custom = ThreeBodyConfig.create_custom_config(config_dict)
```

### 4. ThreeBodyVisualizer（可视化类）
提供多种可视化选项。

```python
visualizer = ThreeBodyVisualizer(figsize=(12, 10))

# 3D轨迹图
visualizer.plot_trajectories(solver, show_current_positions=True, show_com=True)

# 2D投影
fig, ax = visualizer.plot_2d_projection(solver, projection='xy')

# 相空间图
fig, ax = visualizer.plot_phase_space(solver, particle_index=0, dimension='x')

# 显示图形
visualizer.show()

# 保存图形
visualizer.save_figure("trajectory.png", dpi=300)
```

## 物理模型

### 运动方程
对于三个质点 $i=1,2,3$，每个质点的加速度为：

$$
\vec{a}_i = G \sum_{j \neq i} \frac{m_j}{|\vec{r}_{ij}|^3} \vec{r}_{ij}
$$

其中：
- $G = 4\pi^2$ （天文单位制）
- $\vec{r}_{ij} = \vec{r}_j - \vec{r}_i$
- $m_j$ 是质点 $j$ 的质量

### 单位系统
- **距离**：天文单位（AU）
- **质量**：太阳质量（$M_\odot$）
- **时间**：年（yr）
- **速度**：AU/yr
- **引力常数**：$G = 4\pi^2$ AU³/(M⊙·yr²)

### 数值方法
使用四阶龙格-库塔法（RK4）积分运动方程：
- 时间步长：`dt`（默认0.001年）
- 状态向量：18维（3个质点 × 6个自由度）

## 示例

### 示例1：8字形轨道
```python
from three_body_problem.examples import figure8

# 运行8字形轨道示例
solver = figure8.run_figure8_example()

# 分析稳定性
figure8.analyze_figure8_stability()
```

### 示例2：拉格朗日点
```python
from three_body_problem.examples import lagrange

# 运行L4点示例
solver_l4 = lagrange.run_lagrange_example(lagrange_point=4, total_time=100.0)

# 运行L5点示例  
solver_l5 = lagrange.run_lagrange_example(lagrange_point=5, total_time=100.0)

# 比较L4和L5稳定性
lagrange.compare_lagrange_points()
```

### 示例3：随机系统
```python
from three_body_problem.examples import random

# 运行单个随机系统
solver = random.run_random_example(seed=42, total_time=20.0)

# 运行多个随机系统比较
results = random.run_multiple_random_simulations(n_simulations=5, total_time=10.0)
```

## 运行测试

```bash
# 运行所有测试
cd three_body_problem
python -m pytest tests/ -v

# 或直接运行测试脚本
python tests/test_solver.py
```

## 性能优化建议

1. **时间步长选择**：
   - 对于稳定轨道：`dt = 0.001`（默认）
   - 对于快速运动系统：`dt = 0.0001`
   - 对于长期模拟：`dt = 0.01`

2. **内存管理**：
   - 长时间模拟时考虑定期清理轨迹历史
   - 使用`reset()`方法清除历史记录

3. **精度控制**：
   - 检查能量守恒误差：应小于1e-5
   - 检查动量守恒误差：应小于1e-10

## 扩展开发

### 添加新的初始条件
```python
from three_body_problem.config import ThreeBodyConfig

class MyCustomConfig(ThreeBodyConfig):
    @staticmethod
    def create_my_config():
        # 实现自定义配置
        particles = [...]
        return particles
```

### 自定义可视化
```python
from three_body_problem.visualizer import ThreeBodyVisualizer

class MyVisualizer(ThreeBodyVisualizer):
    def plot_custom_view(self, solver):
        # 实现自定义可视化
        pass
```

### 实现新的积分器
```python
from three_body_problem.integrator import RK4Integrator

class MyIntegrator(RK4Integrator):
    def step(self, particles, acceleration_func):
        # 实现新的积分方法
        pass
```

## 已知问题与限制

1. **数值稳定性**：
   - 近距离接近可能导致数值不稳定
   - 建议使用较小时间步长`dt`

2. **能量漂移**：
   - 长期模拟可能出现能量漂移
   - 使用辛积分器可改善（未来版本）

3. **性能**：
   - 纯Python实现，性能有限
   - 对于大规模模拟考虑使用Numba或Cython加速

## 参考文献

1. Chenciner, A., & Montgomery, R. (2000). A remarkable periodic solution of the three-body problem in the case of equal masses.
2. Murray, C. D., & Dermott, S. F. (1999). Solar System Dynamics.
3. Hairer, E., Nørsett, S. P., & Wanner, G. (1993). Solving Ordinary Differential Equations I.

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！


## 版本历史

- v1.0.0 (2024) - 初始版本
  - 实现RK4数值积分器
  - 提供多种初始条件配置
  - 完整的可视化功能
  - 包含测试和示例