first

pc-1
2026-03-11 21:32:58 +08:00
commit 8c8ad9fe07
29 changed files with 4005 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,312 @@
+# 三体问题求解器 - 纯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数值积分器
+  - 提供多种初始条件配置
+  - 完整的可视化功能
+  - 包含测试和示例