# 低温液氮储箱仿真模块使用说明

本目录实现了一个低温液氮储箱模型，用于模拟液氮储箱在氦气增压、液氮进出口流量、环境漏热和气液两区换热作用下的温度、液位、压力、氦气用量等随时间变化。

模型入口文件是 `main.py`，主要参数集中在 `config.py`。运行后会把数据和图像写入 `results/cryo_tank/`。

## 运行方法

在项目根目录运行：

```bash
python3 src/cryo_tank/main.py
```

如果使用本地虚拟环境，先安装依赖：

```bash
.venv/bin/python -m pip install numpy scipy matplotlib pillow CoolProp pytest python-docx
```

然后运行：

```bash
.venv/bin/python src/cryo_tank/main.py
```

建议从项目根目录运行，而不是进入 `src/cryo_tank/` 后运行。这样输出路径会稳定写到：

```text
results/cryo_tank/
```

## 输出文件

默认输出目录由 `config.py` 中的 `OUTPUT_DIR` 控制：

```python
OUTPUT_DIR = "results/cryo_tank"
```

运行完成后会生成：

- `cryo_tank_history.npz`：压缩后的完整时序数据，适合用 Python 后处理。
- `cryo_tank_history.csv`：CSV 表格数据，适合用 Excel、Origin 或其他工具查看。
- `cryo_tank_temperatures.png`：液相温度和气枕区温度曲线。
- `cryo_tank_level.png`：液位和充满率曲线。
- `cryo_tank_he_flow.png`：氦气质量和氦气流量曲线。
- `cryo_tank_heat.png`：漏热和气液换热曲线。
- `cryo_tank_pressure.png`：总压和氦气气枕压力曲线。

如果没有看到 CSV 文件，先确认本地代码里是否有：

```bash
grep -n "save_history_csv" src/cryo_tank/main.py src/cryo_tank/output.py
```

然后确认实际输出位置：

```bash
find results/cryo_tank -maxdepth 1 -type f -print
```

## 代码文件功能

### `main.py`

仿真入口。主要流程是：

1. 从 `config.py` 读取几何、工况、初始条件和求解参数。
2. 创建漏热模型 `MLIHeatLeak`。
3. 创建储箱模型 `CryoTank`。
4. 调用 `solver.run()` 进行 ODE 求解。
5. 调用 `output.py` 保存 `.npz`、`.csv` 和图像。

如果只是运行已有工况，一般只需要执行这个文件，不需要改动它。

### `config.py`

集中存放默认参数。常用调参基本都在这个文件里完成，包括：

- 储箱几何尺寸
- 工作压力
- 初始温度和初始气枕率
- 液氮入口、出口流量
- 氦气入口温度
- 气液换热系数
- 环境温度
- 仿真结束时间
- 求解器误差容限
- 输出目录

### `tank_model.py`

核心物理模型，定义 `CryoTank` 类。

状态量为：

```text
y = [m_liq, U_liq, T_ull]
```

含义分别是：

- `m_liq`：液氮质量
- `U_liq`：液相内能
- `T_ull`：气枕区温度

`derive(y)` 会根据状态量计算温度、体积、液位、充满率、氦气质量、气枕区总内能和氦气气枕压力等派生量。当前模型按恒压纯氦气枕处理，`m_He = rho_He(T_ull, P_work) * V_ull`，所以氦气质量是派生量，不是独立 ODE 状态。

`rhs(t, y)` 是 ODE 右端函数，由 `scipy.integrate.solve_ivp` 调用。

### `solver.py`

ODE 求解器封装。主要函数是：

```python
run(tank, t_end, rtol=1e-8, atol=1e-10, max_step=10.0)
```

它会：

- 调用 `tank.initial_state()` 获取初始状态。
- 使用 `solve_ivp` 求解。
- 在液氮质量降到 0 时终止计算。
- 对每个输出时刻计算温度、压力、液位、漏热、换热等时序数据。
- 返回 `history` 字典。

### `properties.py`

物性计算模块。

主要功能：

- 液氮密度、焓、内能计算。
- 根据液氮比内能和压力反推液相温度。
- 氦气密度、焓、内能、比热计算。
- 根据氦气压力和密度反推气枕温度。
- 计算氦气恒压密度温度导数 `(partial rho / partial T)_P`。
- 计算氦气恒压内能温度导数 `(partial u / partial T)_P`。

该模块依赖 `CoolProp`。

### `heat_leak.py`

漏热模型模块。

当前包含：

- `HeatLeakModel`：漏热模型基类。
- `MLIHeatLeak`：真空多层绝热模型，按固定热流密度 `q_mli` 计算。
- `FoamHeatLeak`：泡沫或包覆绝热模型，按一维稳态导热计算。

默认在 `main.py` 中使用：

```python
heat_leak = MLIHeatLeak(A_total=A_TOTAL, q_mli=1.0)
```

### `output.py`

输出模块。

负责保存：

- 压缩时序数据 `.npz`
- 表格数据 `.csv`
- 温度、液位、氦气流量、热流和压力图像

绘图使用 `matplotlib` 的 `Agg` 后端，因此不需要图形界面。

## 常用调参方法

### 修改仿真时间

在 `config.py` 中修改：

```python
T_END = 3600.0
```

单位是秒。比如仿真 10 分钟：

```python
T_END = 600.0
```

### 修改储箱尺寸

在 `config.py` 中修改：

```python
V_TOTAL = 420.1e-3
H_TANK = 0.5
```

其中：

- `V_TOTAL` 是储箱总体积，单位 `m^3`。
- `H_TANK` 是圆柱储箱高度，单位 `m`。

横截面积、直径、侧面积和总面积会自动由这两个参数计算。

### 修改工作压力

在 `config.py` 中修改：

```python
P_WORKING = 0.17e6
P_MAX = 0.8e6
```

单位是 Pa，代码中使用绝对压力。

`P_WORKING` 是模型维持的工作压力，`P_MAX` 是最大承压限制，用于参数合法性检查。

### 修改初始充液量

在 `config.py` 中修改：

```python
ULLAGE_FRACTION = 0.30
```

该参数表示初始气枕体积分数。比如：

- `0.30` 表示气枕区占 30%，液氮占 70%。
- `0.20` 表示气枕区占 20%，液氮占 80%。

取值必须在 0 到 1 之间。

### 修改液氮进出口流量

在 `config.py` 中修改：

```python
MDOT_IN_LN2 = 1.144
MDOT_OUT_LN2 = 1.1895
```

单位是 `kg/s`。

当前液氮质量变化率为：

```text
dm_liq/dt = MDOT_IN_LN2 - MDOT_OUT_LN2
```

如果出口流量大于入口流量，液位会逐渐下降。

### 修改入口温度

在 `config.py` 中修改：

```python
T_IN_LN2 = 77.0
T_IN_HE = 100.0
```

单位是 K。

### 修改环境漏热

默认漏热模型在 `main.py` 中设置：

```python
heat_leak = MLIHeatLeak(A_total=A_TOTAL, q_mli=1.0)
```

其中 `q_mli` 是单位面积漏热，单位 `W/m^2`。增大 `q_mli` 会增加外界进入储箱的热量。

如果需要改用泡沫绝热模型，可以在 `main.py` 中引入并替换为：

```python
from cryo_tank.heat_leak import FoamHeatLeak

heat_leak = FoamHeatLeak(A_total=A_TOTAL, k_eff=0.03, delta=0.05)
```

其中：

- `k_eff` 是等效导热系数，单位 `W/(m*K)`。
- `delta` 是绝热层厚度，单位 `m`。

### 修改气液换热

在 `config.py` 中修改：

```python
H_CONV_SURFACE = 50.0
```

单位是 `W/(m^2*K)`。该参数控制液相和气枕区之间的换热强度。

### 修改求解精度

在 `config.py` 中修改：

```python
RTOL = 1e-8
ATOL = 1e-10
```

如果计算较慢，可以适当放宽；如果需要更高精度，可以适当收紧。收紧误差容限通常会增加计算时间。

`solver.run()` 还有一个默认参数：

```python
max_step=10.0
```

表示最大时间步长，单位秒。如果需要更密集的输出点，可以在调用 `run()` 时减小它。

## 后处理数据

读取 `.npz` 数据示例：

```python
import numpy as np

data = np.load("results/cryo_tank/cryo_tank_history.npz")
print(data.files)
print(data["t"])
print(data["T_liq"])
```

读取 CSV 数据示例：

```python
import numpy as np

data = np.loadtxt(
    "results/cryo_tank/cryo_tank_history.csv",
    delimiter=",",
    skiprows=1,
)
print(data.shape)
```

CSV 第一行是列名，列名来自 `history` 字典，包括：

- `t`
- `m_liq`
- `U_liq`
- `U_ull`
- `T_liq`
- `T_ull`
- `m_He`
- `mdot_He`
- `V_liq`
- `V_ull`
- `liquid_level`
- `fill_fraction`
- `P_He`
- `P_total`
- `Q_leak`
- `Q_leak_liq`
- `Q_leak_ull`
- `Q_liq_to_ull`

## 测试

运行低温储箱相关测试：

```bash
pytest -q tests/cryo_tank
```

运行全项目测试：

```bash
pytest -q
```

## 注意事项

- 本模型当前将储箱分为液相区和气枕区两个区域，不是完整 CFD 模型。
- 气枕区按纯氦气处理，物性由 CoolProp 计算。
- 气枕温度 `T_ull` 是 ODE 状态量；氦气质量 `m_He` 和补气流量 `mdot_He` 是恒压条件下的派生结果。
- 液氮物性依赖 `CoolProp`，缺少该包会导致程序无法启动。
- `results/` 目录默认被 `.gitignore` 忽略，仿真输出不会自动上传到 Git。
- 建议每次修改参数后保存对应工况说明，避免不同仿真结果混在同一个输出目录中。