Metadata-Version: 2.4
Name: lagrange-poisson
Version: 0.4.1
Summary: 拉格朗日-泊松问题数值求解器 / Lagrange-Poisson Problem Numerical Solver
Author-email: Your Name <your.email@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/lagrange-poison
Project-URL: Documentation, https://github.com/yourusername/lagrange-poison/blob/main/README.md
Project-URL: Repository, https://github.com/yourusername/lagrange-poison
Project-URL: Issues, https://github.com/yourusername/lagrange-poison/issues
Keywords: lagrange,poisson,rigid body,dynamics,numerical methods
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# 拉格朗日-泊松问题求解器

一个用于求解刚体绕定点在重力场中运动的Python数值计算工具包，提供图形界面、3D动画和多种数值方法。

## 功能特点

### 数值方法
- 三种经典数值方法：
  - 显式欧拉法 (一阶精度)
  - 改进欧拉法/Heun法 (二阶精度)
  - 四阶Runge-Kutta法 (四阶精度)

### 用户界面
- **标准版GUI** (`lagrange-poisson`)
  - 泊松变量输入模式
  - 基于 Tkinter 的直观界面
  - 实时参数调整
  - 结果可视化展示
  - 数据导出功能

- **增强版GUI** (`lagrange-poisson-pro`) 🆕
  - **欧拉角输入模式**（更直观）
  - **泊松变量输入模式**（专业）
  - 一键切换输入/输出模式
  - **3D陀螺运动动画**
  - 实时欧拉角显示

### 数据转换
- **欧拉角 ↔ 泊松变量双向转换**
  - 输入：欧拉角（直观）
  - 计算：泊松变量（高效）
  - 输出：欧拉角（直观）
- 自动转换公式：
  - γ₁ = sin(θ)·sin(ψ)
  - γ₂ = sin(θ)·cos(ψ)
  - γ₃ = cos(θ)

### 科学可视化
- 基于 Matplotlib 的高质量绘图
- 角速度和欧拉角的时间演化曲线
- **3D刚体姿态动画**
- 方向余弦/欧拉角切换显示

### 物理模型
- 欧拉动力学方程
- 泊松运动学方程
- 支持任意主转动惯量配置
- 支持任意质心位置

## 安装

```bash
pip install lagrange-poisson
```

或从源码安装：

```bash
git clone https://github.com/yourusername/lagrange-poisson.git
cd lagrange-poisson
pip install -e .
```

## 快速开始

### 安装

```bash
pip install lagrange-poisson
```

### 启动GUI

#### 标准版（泊松变量输入）
```bash
lagrange-poisson
```

#### 增强版（欧拉角输入 + 3D动画）推荐
```bash
lagrange-poisson-pro
```

### 在Python代码中使用

```python
import numpy as np
from lagrange_poisson import LagrangePoissonSolver, RK4Method

# 创建求解器
solver = LagrangePoissonSolver(
    A=1.0,   # 主转动惯量
    B=2.0,
    C=3.0,
    x0=0.1,  # 质心坐标
    y0=0.0,
    z0=0.0,
    m=1.0,   # 质量
    g=9.81   # 重力加速度
)

# 【新方法】使用欧拉角设置初始条件（更直观）
phi0 = np.radians(10)    # 进动角 10度
theta0 = np.radians(30)  # 章动角 30度
psi0 = np.radians(45)    # 自转角 45度

# 将欧拉角转换为泊松变量
gamma = solver.euler_angles_to_poisson(phi0, theta0, psi0)

# 设置初始条件 [p0, q0, r0, γ1, γ2, γ3]
initial_conditions = np.array([0.5, 0.1, 0.05, gamma[0], gamma[1], gamma[2]])

# 求解
method = RK4Method()
t, y = solver.solve(
    initial_conditions=initial_conditions,
    t_span=(0, 20),
    dt=0.01,
    method=method
)

# 绘制结果
import matplotlib.pyplot as plt

fig, axes = plt.subplots(2, 3, figsize=(12, 8))
labels = ['p', 'q', 'r', 'γ₁', 'γ₂', 'γ₃']
titles = ['角速度 p', '角速度 q', '角速度 r',
          '方向余弦 γ₁', '方向余弦 γ₂', '方向余弦 γ₃']

for i, ax in enumerate(axes.flat):
    ax.plot(t, y[:, i])
    ax.set_title(titles[i])
    ax.set_xlabel('时间 (s)')
    ax.set_ylabel(labels[i])
    ax.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()
```

### 泊松变量与欧拉角转换

本软件支持将泊松变量 $(\gamma_1, \gamma_2, \gamma_3)$ 转换为欧拉角 $(\phi, \theta, \psi)$：

```python
# 转换为欧拉角
euler = solver.poisson_to_euler_angles(t, y, phi0=0.0)

phi = euler[:, 0]   # 进动角
theta = euler[:, 1] # 章动角
psi = euler[:, 2]   # 自转角

# 绘制欧拉角
fig, axes = plt.subplots(2, 3, figsize=(12, 8))
labels = ['φ (rad)', 'θ (rad)', 'ψ (rad)', 'φ (°)', 'θ (°)', 'ψ (°)']
titles = ['进动角', '章动角', '自转角'] * 2

for i in range(3):
    # 弧度
    axes[0, i].plot(t, euler[:, i])
    axes[0, i].set_title(titles[i])
    axes[0, i].set_ylabel(labels[i])

    # 角度
    axes[1, i].plot(t, np.degrees(euler[:, i]))
    axes[1, i].set_title(titles[i])
    axes[1, i].set_ylabel(labels[i + 3])
    axes[1, i].set_xlabel('时间 (s)')

plt.tight_layout()
plt.show()
```

**转换公式：**
- 章动角: $\theta = \arccos(\gamma_3)$
- 自转角: $\psi = \operatorname{atan2}(\gamma_1, \gamma_2)$
- 进动角: $\phi_{n+1} = \phi_n + h\frac{p_n\gamma_{1,n} + q_n\gamma_{2,n}}{\gamma_{1,n}^2 + \gamma_{2,n}^2}$

**注意：** 欧拉角表示在 $\sin\theta \approx 0$ 时存在奇异点，这是欧拉角表示法的固有特性。

## 物理背景

本软件求解的是**拉格朗日-泊松问题**，即刚体绕定点在重力场中的运动。

### 数学方程

**欧拉动力学方程：**
```
Aṗ + (C-B)qr = M₁
Bq̇ + (A-C)rp = M₂
Cṙ + (B-A)pq = M₃
```

**泊松运动学方程：**
```
γ̇₁ = rγ₂ - qγ₃
γ̇₂ = pγ₃ - rγ₁
γ̇₃ = qγ₁ - pγ₂
```

其中：
- p, q, r 是角速度在体轴系中的分量
- γ₁, γ₂, γ₃ 是重力方向在体轴系中的方向余弦
- A, B, C 是主转动惯量
- M₁, M₂, M₃ 是重力矩分量

## 参数说明

| 参数 | 说明 | 单位 |
|------|------|------|
| A, B, C | 主转动惯量 | kg·m² |
| x₀, y₀, z₀ | 质心在体坐标系中的位置 | m |
| m | 刚体质量 | kg |
| g | 重力加速度 | m/s² |
| p₀, q₀, r₀ | 初始角速度 | rad/s |
| γ₁₀, γ₂₀, γ₃₀ | 初始方向余弦 | 无量纲 |

## 数值方法

### 1. 显式欧拉法
最简单的数值方法，一阶精度：
```
y_{n+1} = y_n + h·f(y_n)
```

### 2. 改进欧拉法 (Heun方法)
二阶精度的预测-校正方法：
```
k₁ = f(y_n)
k₂ = f(y_n + h·k₁)
y_{n+1} = y_n + (h/2)(k₁ + k₂)
```

### 3. 四阶Runge-Kutta法 (RK4)
最常用的四阶精度方法：
```
k₁ = f(y_n)
k₂ = f(y_n + h·k₁/2)
k₃ = f(y_n + h·k₂/2)
k₄ = f(y_n + h·k₃)
y_{n+1} = y_n + (h/6)(k₁ + 2k₂ + 2k₃ + k₄)
```

## 依赖项

- Python >= 3.8
- NumPy >= 1.20.0
- Matplotlib >= 3.3.0

## 开发

### 运行测试

```bash
pip install -e ".[dev]"
pytest
```

### 构建和发布

```bash
# 构建
python -m build

# 发布到PyPI (需要配置 API token)
python -m twine upload dist/*
```

## 许可证

MIT License

## 作者

Your Name <your.email@example.com>

## 参考文献

1. Arnold, V. I. (1989). *Mathematical Methods of Classical Mechanics*
2. Landau, L. D., & Lifshitz, E. M. (1976). *Mechanics*
3. Goldstein, H. (1980). *Classical Mechanics*

## 贡献

欢迎提交 Issue 和 Pull Request！
