first

pc-1
2026-03-11 21:32:58 +08:00
commit 8c8ad9fe07
29 changed files with 4005 additions and 0 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -0,0 +1,309 @@
+# 三体问题求解器 - 安装和使用指南
+
+## 项目简介
+
+这是一个纯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数值积分器
+- 提供多种初始条件配置
+- 完整的可视化功能
+- 包含测试和示例
+
+---
+
+**开始探索三体问题的奇妙世界吧！** 🚀