pipe-system-simulation-test/src/cryo_tank/README.md

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

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

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

运行方法

在项目根目录运行：

python3 src/cryo_tank/main.py

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

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

然后运行：

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

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

results/cryo_tank/

输出文件

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

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 文件，先确认本地代码里是否有：

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

然后确认实际输出位置：

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 类。

状态量为：

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 求解器封装。主要函数是：

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 中使用：

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

output.py

输出模块。

负责保存：

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

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

常用调参方法

修改仿真时间

在 config.py 中修改：

T_END = 3600.0

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

T_END = 600.0

修改储箱尺寸

在 config.py 中修改：

V_TOTAL = 420.1e-3
H_TANK = 0.5

其中：

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

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

修改工作压力

在 config.py 中修改：

P_WORKING = 0.17e6
P_MAX = 0.8e6

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

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

修改初始充液量

在 config.py 中修改：

ULLAGE_FRACTION = 0.30

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

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

取值必须在 0 到 1 之间。

修改液氮进出口流量

在 config.py 中修改：

MDOT_IN_LN2 = 1.144
MDOT_OUT_LN2 = 1.1895

单位是 kg/s。

当前液氮质量变化率为：

dm_liq/dt = MDOT_IN_LN2 - MDOT_OUT_LN2

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

修改入口温度

在 config.py 中修改：

T_IN_LN2 = 77.0
T_IN_HE = 100.0

单位是 K。

修改环境漏热

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

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

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

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

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 中修改：

H_CONV_SURFACE = 50.0

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

修改求解精度

在 config.py 中修改：

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

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

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

max_step=10.0

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

后处理数据

读取 .npz 数据示例：

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 数据示例：

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

测试

运行低温储箱相关测试：

pytest -q tests/cryo_tank

运行全项目测试：

pytest -q

注意事项

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