three-body-problem/INSTALL.md

# 三体问题求解器 - 安装和使用指南

## 项目简介

这是一个纯Python实现的三体问题求解器，使用四阶龙格-库塔法（RK4）数值求解牛顿引力下的三体运动。项目提供了完整的模拟、可视化和分析功能。

## 安装步骤

### 1. 克隆或下载项目
```bash
# 克隆仓库
git clone <repository-url>
cd three_body_problem

# 或直接下载zip文件并解压
```

### 2. 安装依赖
```bash
# 使用pip安装
pip install numpy matplotlib

# 或使用requirements.txt
pip install -r requirements.txt
```

### 3. 验证安装
```bash
# 运行简单测试
python simple_test.py

# 或运行完整测试
python three_body_problem/tests/test_solver.py
```

## 快速开始

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

# 创建三个质点
particles = [
    Particle(mass=1.0, position=[1.0, 0.0, 0.0], velocity=[0.0, 0.5, 0.0], name="Star A"),
    Particle(mass=1.0, position=[-1.0, 0.0, 0.0], velocity=[0.0, -0.5, 0.0], name="Star B"),
    Particle(mass=0.1, position=[0.0, 1.0, 0.0], velocity=[-0.3, 0.0, 0.0], name="Star C")
]

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

# 模拟5年
solver.simulate(total_time=5.0)

# 可视化
visualizer = ThreeBodyVisualizer()
visualizer.plot_trajectories(solver, title="三体系统运动轨迹")
visualizer.show()
```

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

# 拉格朗日点L4
particles = ThreeBodyConfig.create_lagrange_point_config(lagrange_point=4)

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

## 运行示例

### 1. 运行简单示例
```bash
python three_body_problem/run_example.py
```

### 2. 运行8字形轨道示例
```bash
python three_body_problem/examples/figure8.py
```

### 3. 运行拉格朗日点示例
```bash
python three_body_problem/examples/lagrange.py
```

### 4. 运行随机系统示例
```bash
python three_body_problem/examples/random.py
```

### 5. 运行演示脚本
```bash
python three_body_problem/demo.py
```

## 项目结构

```
three_body_problem/
├── __init__.py              # 包初始化
├── particle.py              # 质点类
├── integrator.py            # 数值积分器（RK4）
├── solver.py                # 三体问题求解器
├── visualizer.py            # 可视化工具
├── config.py                # 配置管理
├── README.md                # 详细文档
├── SUMMARY.md               # 项目总结
├── demo.py                  # 演示脚本
├── run_example.py           # 快速示例
├── requirements.txt         # 依赖列表
├── setup.py                 # 安装配置
├── examples/                # 示例
│   ├── figure8.py           # 8字形轨道
│   ├── lagrange.py          # 拉格朗日点
│   └── random.py            # 随机系统
└── tests/                   # 测试
    └── test_solver.py       # 单元测试
```

## 主要功能

### 1. 物理模拟
- **牛顿引力计算**：精确计算三个质点间的万有引力
- **数值积分**：四阶龙格-库塔法（RK4）
- **守恒定律**：动量、角动量、能量守恒验证

### 2. 初始条件
- **8字形轨道**：著名的稳定周期解
- **拉格朗日点**：L4和L5点稳定性测试
- **随机系统**：随机初始条件生成
- **自定义配置**：灵活的用户定义

### 3. 可视化
- **3D轨迹图**：完整的三维运动轨迹
- **2D投影**：XY、XZ、YZ平面投影
- **相空间图**：位置-速度关系
- **能量分析**：守恒定律验证

### 4. 分析工具
- **质心计算**：系统质心位置和轨迹
- **距离分析**：质点间距离变化
- **稳定性分析**：轨道稳定性评估
- **误差分析**：数值积分精度评估

## 配置参数

### 时间步长选择
```python
# 高精度模拟（推荐）
solver = ThreeBodySolver(particles, dt=0.001)

# 快速模拟
solver = ThreeBodySolver(particles, dt=0.01)

# 超高精度模拟
solver = ThreeBodySolver(particles, dt=0.0001)
```

### 模拟时间
```python
# 短期模拟（几到几十年）
solver.simulate(total_time=10.0)      # 10年

# 长期模拟（几百年）
solver.simulate(total_time=100.0)     # 100年

# 超长期模拟（几千年）
solver.simulate(total_time=1000.0)    # 1000年
```

## 常见问题

### 1. 导入错误
**问题**：`ModuleNotFoundError: No module named 'numpy'`
**解决**：安装依赖 `pip install numpy matplotlib`

### 2. 模拟速度慢
**问题**：模拟时间太长或时间步长太小
**解决**：
- 减少模拟时间 `total_time`
- 增大时间步长 `dt`
- 减少进度打印频率 `progress_interval`

### 3. 数值不稳定
**问题**：质点间距离过小导致计算溢出
**解决**：
- 增大时间步长 `dt`
- 调整初始条件避免近距离接近
- 使用更小的质量差异

### 4. 内存不足
**问题**：长时间模拟产生大量轨迹数据
**解决**：
- 减少模拟时间
- 增大时间步长
- 修改代码只保存关键时间点

## 性能优化

### 1. 减少输出
```python
# 减少进度打印频率
solver.simulate(total_time=100.0, progress_interval=10000)
```

### 2. 调整精度
```python
# 平衡精度和速度
dt = 0.001      # 标准精度
dt = 0.01       # 较低精度，更快
dt = 0.0001     # 高精度，较慢
```

### 3. 内存管理
```python
# 定期清理历史记录
solver.reset()  # 清除所有历史记录
```

## 扩展开发

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

class MyConfig(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. **经典文献**：Poincaré, H. (1890). "Sur le problème des trois corps"
2. **现代研究**：Chenciner, A., & Montgomery, R. (2000). "A remarkable periodic solution"
3. **教科书**：Murray, C. D., & Dermott, S. F. (1999). "Solar System Dynamics"

### 数值方法
1. **数值分析**：Hairer, E., et al. (1993). "Solving Ordinary Differential Equations I"
2. **科学计算**：Press, W. H., et al. (2007). "Numerical Recipes"

### Python科学计算
1. **NumPy教程**：https://numpy.org/doc/stable/user/quickstart.html
2. **Matplotlib教程**：https://matplotlib.org/stable/tutorials/index.html
3. **SciPy教程**：https://docs.scipy.org/doc/scipy/tutorial/index.html

## 贡献指南

1. Fork项目仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

## 许可证

MIT License - 详见LICENSE文件

## 支持

如有问题或建议，请：
1. 查看文档和示例
2. 提交Issue
3. 联系作者

## 版本历史

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

---

**开始探索三体问题的奇妙世界吧！** 🚀