添加气瓶计算过程文档

src/cylinder/Index.md

@@ -0,0 +1,338 @@
+## 1. 模型定位
+
+`gas_cylinder.py` 实现的是高压气瓶的 0D 集总参数模型 `HighPressureGasCylinder`。模型只描述气瓶内部平均热力状态，不解析气瓶内的轴向、径向或局部流场分布。
+
+主要假设：
+
+- 气瓶有效容积 `V` 固定。
+- 气瓶内工质均匀，使用单一平均密度和单一平均比内能描述。
+- 独立守恒状态只有总质量 `mass` 和总内能 `U`。
+- 压力、温度和比焓通过 CoolProp 由当前守恒状态恢复。
+- 模型不自行计算边界流量；外部模型给出质量流率和能量流率后，气瓶只更新守恒量。
+
+对应代码：`src/cylinder/gas_cylinder.py:20-142`
+
+## 2. 参数与状态
+
+默认参数定义在 `src/cylinder/gas_cylinder.py:14-17`：
+
+| 参数 | 默认值 | 含义 |
+| --- | ---: | --- |
+| `DEFAULT_FLUID` | `Helium` | CoolProp 工质名称 |
+| `DEFAULT_P_INIT` | `18.031e6 Pa` | 初始绝对压力 |
+| `DEFAULT_VOLUME` | `20e-3 m^3` | 气瓶容积，20 L |
+| `DEFAULT_T_INIT` | `78.0 K` | 初始温度 |
+
+构造函数输入为：
+
+$$
+\left(\mathrm{fluid},\ P_0,\ V,\ T_0,\ \mathrm{backend}\right)
+$$
+
+其中 `backend` 默认是 `HEOS`。构造函数会检查：
+
+$$
+\mathrm{fluid}\ne\varnothing,\quad P_0>0,\quad V>0,\quad T_0>0
+$$
+
+气瓶模型的独立状态向量为：
+
+$$
+\mathbf{y}_{\mathrm{cyl}}=\left[m_{\mathrm{cyl}},\ U_{\mathrm{cyl}}\right]
+$$
+
+其中：
+
+- `mass` 对应 $m_{\mathrm{cyl}}$，单位 kg。
+- `U` 对应 $U_{\mathrm{cyl}}$，单位 J。
+- 压力 `P`、温度 `T`、密度 `rho`、比内能 `specific_internal_energy` 和比焓 `h` 都是由这两个守恒量派生出来的量。
+
+## 3. 初始状态计算
+
+初始化发生在 `src/cylinder/gas_cylinder.py:51-56`。计算流程如下。
+
+第一步，建立 CoolProp 状态对象：
+
+```python
+self._state = AbstractState(backend, fluid)
+```
+
+第二步，用初始压力和初始温度更新热力状态：
+
+```python
+self._state.update(CP.PT_INPUTS, P_init, T_init)
+```
+
+对应数学表达为：
+
+$$
+\mathrm{state}_0=\mathrm{CoolProp}\left(P_0,T_0,\mathrm{fluid},\mathrm{backend}\right)
+$$
+
+第三步，从 CoolProp 读取初始密度：
+
+$$
+\rho_0=\rho\left(P_0,T_0\right)
+$$
+
+代码中对应：
+
+```python
+rho = self._state.rhomass()
+```
+
+第四步，由固定容积计算气瓶初始总质量：
+
+$$
+m_{\mathrm{cyl},0}=\rho_0 V
+$$
+
+代码中对应：
+
+```python
+self.mass = rho * V
+```
+
+第五步，从 CoolProp 读取初始比内能，并计算总内能：
+
+$$
+U_{\mathrm{cyl},0}=m_{\mathrm{cyl},0}u_0
+$$
+
+其中：
+
+$$
+u_0=u\left(P_0,T_0\right)
+$$
+
+代码中对应：
+
+```python
+self.U = self.mass * self._state.umass()
+```
+
+因此，模型初始化后不再单独保存初始压力和初始温度；后续压力和温度都通过当前 `mass`、`U` 和 `V` 重新计算。
+
+## 4. 状态恢复计算
+
+运行过程中，模型每次需要热力性质时都会调用 `_update_state()`，代码位置为 `src/cylinder/gas_cylinder.py:58-62`。
+
+### 4.1 密度
+
+气瓶体积固定，因此当前平均密度为：
+
+$$
+\rho_{\mathrm{cyl}}=\frac{m_{\mathrm{cyl}}}{V}
+$$
+
+代码位置：`src/cylinder/gas_cylinder.py:64-67`
+
+### 4.2 比内能
+
+当前比内能由总内能除以总质量得到：
+
+$$
+u_{\mathrm{cyl}}=\frac{U_{\mathrm{cyl}}}{m_{\mathrm{cyl}}}
+$$
+
+代码位置：`src/cylinder/gas_cylinder.py:69-72`
+
+这一步要求 `mass > 0`。`apply_flux()` 在每次通量更新后会检查质量不能为非正值。
+
+### 4.3 CoolProp 输入对
+
+模型用质量密度和质量比内能作为 CoolProp 输入对：
+
+```python
+self._state.update(CP.DmassUmass_INPUTS, rho, u)
+```
+
+对应数学表达为：
+
+$$
+\mathrm{state}=\mathrm{CoolProp}\left(\rho_{\mathrm{cyl}},u_{\mathrm{cyl}}\right)
+$$
+
+这里的关键点是：`P` 和 `T` 不是独立积分变量，而是 CoolProp 根据 $(\rho,u)$ 反算出来的热力结果。
+
+### 4.4 压力、温度和比焓
+
+状态恢复后，模型提供三个主要派生量：
+
+$$
+\begin{aligned}
+P_{\mathrm{cyl}} &= P\left(\rho_{\mathrm{cyl}},u_{\mathrm{cyl}}\right) \\
+T_{\mathrm{cyl}} &= T\left(\rho_{\mathrm{cyl}},u_{\mathrm{cyl}}\right) \\
+h_{\mathrm{cyl}} &= h\left(\rho_{\mathrm{cyl}},u_{\mathrm{cyl}}\right)
+\end{aligned}
+$$
+
+对应代码：
+
+- `P`：`src/cylinder/gas_cylinder.py:74-77`
+- `T`：`src/cylinder/gas_cylinder.py:79-82`
+- `h`：`src/cylinder/gas_cylinder.py:84-87`
+
+当前模型只保留上述三个热力派生量，不再保留额外的热物性辅助输出。
+
+## 5. 边界 ghost state 计算
+
+`ghost_state()` 用于给一维守恒流动模型提供气瓶侧边界状态，代码位置为 `src/cylinder/gas_cylinder.py:89-97`。
+
+返回向量为：
+
+$$
+\mathbf{q}_{\mathrm{ghost}}=
+\left[
+\rho_{\mathrm{cyl}},\
+0,\
+\rho_{\mathrm{cyl}}u_{\mathrm{cyl}}
+\right]^T
+$$
+
+三个分量分别是：
+
+| 分量 | 代码表达 | 物理意义 |
+| --- | --- | --- |
+| $q_1$ | `self.rho` | 质量密度 |
+| $q_2$ | `0.0` | 动量密度 |
+| $q_3$ | `self.rho * self.specific_internal_energy` | 总能量密度 |
+
+由于气瓶是 0D 静止控制体，边界 ghost state 的速度取 0，所以动量密度为 0。总能量密度中也没有宏观动能项：
+
+$$
+\rho E = \rho u + \frac{1}{2}\rho v^2 = \rho u \quad \left(v=0\right)
+$$
+
+注意：这个 ghost state 使用的是真实流体内能。如果下游管路求解器使用理想气体状态方程，耦合前需要确认状态方程和能量定义是否一致。
+
+## 6. 边界通量更新计算
+
+`apply_flux(mdot, edot, dt, sign)` 根据外部边界通量更新气瓶守恒量，代码位置为 `src/cylinder/gas_cylinder.py:99-128`。
+
+输入量含义：
+
+| 参数 | 单位 | 含义 |
+| --- | --- | --- |
+| `mdot` | kg/s | 边界质量流率 |
+| `edot` | W | 边界能量流率 |
+| `dt` | s | 时间步长 |
+| `sign` | - | 通量方向符号 |
+
+方向符号定义为：
+
+$$
+s=
+\begin{cases}
+-1, & \text{气体从气瓶流出} \\
++1, & \text{气体流入气瓶}
+\end{cases}
+$$
+
+离散更新方程为：
+
+$$
+\begin{aligned}
+m_{\mathrm{cyl}}^{n+1} &= m_{\mathrm{cyl}}^{n}+s\dot{m}\Delta t \\
+U_{\mathrm{cyl}}^{n+1} &= U_{\mathrm{cyl}}^{n}+s\dot{E}\Delta t
+\end{aligned}
+$$
+
+代码中对应：
+
+```python
+self.mass += sign * mdot * dt
+self.U += sign * edot * dt
+```
+
+连续形式为：
+
+$$
+\begin{aligned}
+\frac{dm_{\mathrm{cyl}}}{dt} &= s\dot{m} \\
+\frac{dU_{\mathrm{cyl}}}{dt} &= s\dot{E}
+\end{aligned}
+$$
+
+如果外部模型使用边界比焓计算能量流率，常见形式为：
+
+$$
+\dot{E}=\dot{m}h_{\mathrm{boundary}}
+$$
+
+但气瓶模型本身不强制 `edot = mdot * h`，只接收外部传入的能量流率。这使它可以用于不同边界模型，但也要求调用方保证质量通量和能量通量的物理一致性。
+
+### 6.1 数值保护
+
+通量更新前后包含三类保护：
+
+$$
+\Delta t\ge0,\quad s\in\{-1,+1\},\quad m_{\mathrm{cyl}}^{n+1}>0
+$$
+
+对应行为：
+
+- `dt < 0` 时抛出 `ValueError`。
+- `sign` 不是 `-1` 或 `+1` 时抛出 `ValueError`。
+- 更新后 `mass <= 0` 时抛出 `RuntimeError`。
+- 更新完成后立即调用 `_update_state()`，让 CoolProp 立刻检查新的 $(\rho,u)$ 是否处于有效热力状态。
+
+## 7. 状态汇总
+
+`state_summary()` 返回当前气瓶状态字典，代码位置为 `src/cylinder/gas_cylinder.py:130-142`。
+
+返回字段为：
+
+| 字段 | 含义 |
+| --- | --- |
+| `fluid` | 工质名称 |
+| `V` | 气瓶固定容积 |
+| `mass` | 当前总质量 |
+| `rho` | 当前平均密度 |
+| `P` | 当前绝对压力 |
+| `T` | 当前温度 |
+| `U` | 当前总内能 |
+| `u` | 当前比内能 |
+| `h` | 当前比焓 |
+
+该函数主要用于后处理、日志输出或快速检查模型状态。
+
+## 8. 耦合使用简述
+
+在低温贮箱和气瓶耦合示例中，气瓶状态通常作为整体 ODE 状态向量的一部分：
+
+$$
+\mathbf{y}=\left[m_{\mathrm{liq}},\ U_{\mathrm{liq}},\ T_{\mathrm{ull}},\ m_{\mathrm{cyl}},\ U_{\mathrm{cyl}}\right]
+$$
+
+气瓶向贮箱供气时，可写为：
+
+$$
+\frac{dm_{\mathrm{cyl}}}{dt}=-\dot{m}_{\mathrm{to\ tank}},\quad
+\frac{dU_{\mathrm{cyl}}}{dt}=-\dot{E}_{\mathrm{to\ tank}}
+$$
+
+并可用气瓶压力相对贮箱工作压力的差值作为终止条件：
+
+$$
+g(t,\mathbf{y})=P_{\mathrm{cyl}}-P_{\mathrm{work}}
+$$
+
+示例代码位置：`examples/cryo_tank_cylinder_system.py`
+
+## 9. 运行和测试
+
+气瓶模型可直接导入使用：
+
+```python
+from cylinder import HighPressureGasCylinder
+
+cylinder = HighPressureGasCylinder()
+summary = cylinder.state_summary()
+```
+
+相关测试覆盖默认状态、可配置输入、状态汇总字段、ghost state、出流通量更新和非法输入校验。测试命令：
+
+```bash
+pytest -q tests/test_gas_cylinder.py
+```