企业官网建设流程全解析

• 科学计算

导读：CoolProp 是一个以 C++ 为核心的开源热物理性质（thermophysical properties）数据库，覆盖纯流体、伪纯流体、混合物、不可压缩流体/盐水、湿空气与天然气等多种工质的物性计算。本文基于仓库官方文档（Web/index.rst）及其关联子文档，系统梳理 CoolProp 的能力清单、支持环境、PropsSI高阶用法（相位强制、偏导数、参考状态）、低层AbstractState接口，以及 SVDSBTL / TTSE / BICUBIC 表格加速后端与 IF97、湿空气模块的实现细节。读完本文，你将掌握 CoolProp 从"一行代码查密度"到"亚微秒级批量物性查询"的完整技术路径，并能直接对照仓库源码理解其底层原理。

一、CoolProp 是什么

CoolProp 是一个开源的 C++ 物性计算库，以"Thermophysical properties for the masses"为定位，实现了对纯流体与伪纯流体的高精度亥姆霍兹（Helmholtz）状态方程与输运性质计算。根据官方门户文档 Web/index.rst，其核心能力包括：

• 纯流体与伪纯流体状态方程与输运性质：覆盖 137 种流体的完整 JSON 数据（见 dev/fluids 目录下的 137 个*.json文件），详细列表见 纯流体与伪纯流体物性；
• 混合物性质：基于高精度亥姆霍兹能公式（Kunz 与 Lemmon 系列工作），见 混合物；
• 不可压缩流体与盐水的物性关联式：见 不可压缩流体；
• 计算高效的表格插值：SVD+SBTL（SVDSBTL 后端）或 bicubic/TTSE（表格插值）；
• 最高精度的湿空气（psychrometric）例程：见 湿空气物性；
• 对 NIST REFPROP 全功能的友好封装：见 REFPROP；
• 快速的 IAPWS-IF97 工业公式水/蒸汽计算：见 IF97；
• 立方型状态方程（SRK、PR）：见 立方型状态方程后端；
• PC-SAFT 状态方程：见 PC-SAFT 后端；
• 严格的 GERG-2004 / GERG-2008 天然气状态方程：见 GERG 后端。

从源码结构看，这些能力被组织为多个独立后端目录（src/Backends），包括Helmholtz（HEOS，纯流体与混合物）、IF97、Cubics、PCSAFT、GERG、Incompressible、REFPROP、SVDSBTL、Tabular等，每个后端都通过实现统一的AbstractState协议接入库框架，这一点在低层接口部分详述。

许可与使用方式

CoolProp 采用灵活的许可条款，商业项目与学术工作均可免费使用，具体以仓库根目录的 LICENSE 为准。Python 用户可通过pip install CoolProp安装官方发布版；源码构建方式参见 CMake 构建说明 与 开发文档。

二、支持的环境

CoolProp 的核心是 C++ 库，因此几乎任何能编译 C++ 的平台都可以运行。

编程语言（完全功能封装）：

• Python（2.x 与 3.x，基于 Cython）：Python 封装文档；
• C++：静态库（说明）与共享库/DLL（说明）；
• Modelica（通过 ExternalMedia 库）、Octave、C#、VB.NET、MathCAD、Java、Android、MATLAB（多数基于 SWIG 生成）。

高层接口封装（仅使用PropsSI/HAPropsSI等函数）：LabVIEW、EES、Microsoft Excel、LibreOffice、JavaScript、PHP、FORTRAN、Maple、Mathematica、Scilab、Delphi & Lazarus、Julia。

架构与操作系统：

• 32 位 / 64 位；
• Windows、Linux、macOS（OSX）、树莓派（Raspberry Pi）、VxWorks CompactRIO 等——如文档所述："如果你能在它上面编译 C++，CoolProp 就能运行"。

完整的封装清单、各目标平台的操作系统支持与备注见 封装列表。无论哪种封装，所有PropsSI调用最终都会落到 C++ 层的同一实现上（见 CoolPropLib.h，该头文件以 C 风格字符串与double*数组定义了 DLL 导出接口，供 Excel、FORTRAN、Julia 等无法直接实例化 C++ 类的语言调用）。

三、快速上手：High-Level 接口与 PropsSI

3.1 一行代码查密度

绝大多数用户需要的只是一个PropsSI调用。以氮气为例，计算 298 K、101325 Pa 下的密度D：

from CoolProp.CoolProp import PropsSI rho = PropsSI('D', 'T', 298.15, 'P', 101325, 'Nitrogen')

参数语义（参见 高层接口文档）：

• 第 1 个参数'D'是输出物性；
• 第 2、4 个参数'T'、'P'是指定状态的输入属性对；
• 第 3、5 个参数是这两个输入属性的数值；
• 第 6 个参数是工质名，全部为需要加引号的字符串。

再如水的常压饱和温度（Q=0表示饱和液态）：

T_sat = PropsSI('T', 'P', 101325, 'Q', 0, 'Water') # 约 373.124 K

仓库中提供了完整的 C++ 示例与运行输出，见 propssi.cxx 与 propssi.cxx.output（后者演示了Propane[0.5]&Ethane[0.5]在默认 HEOS、显式HEOS::与REFPROP::下得到一致结果 40.8269）。更多可运行的PropsSI示例参见 示例页。

3.2 输入属性的速度差异

状态方程以T和ρ为独立变量，因此：

• T, ρ永远是最快的输入；
• P, T稍慢（约 3–10 倍）；
• 既不含T也不含ρ的输入对（如P, H）要慢得多。

若对速度敏感，可改用 SVDSBTL SVD 压缩表格后端；若只关心水，可使用 IF97 工业公式后端。

3.3 气相、液相与饱和态

若输入对（如P, T）落在气相区，返回气相物性；落在液相区则返回液相物性。当输入对落在饱和压力附近 1E-4% 以内时，由于饱和曲线上液态和气态同时被定义，CoolProp 可能返回错误。

要显式获取饱和曲线上的气/液物性，请在输入对中给出饱和温度T（或压力p）与干度Q：Q=1取饱和气相，Q=0取饱和液相。例如 1 大气压下水的汽化潜热：

from CoolProp.CoolProp import PropsSI H_V = PropsSI('H', 'P', 101325, 'Q', 1, 'Water') # 饱和汽焓，J/kg H_L = PropsSI('H', 'P', 101325, 'Q', 0, 'Water') # 饱和液焓，J/kg latent = H_V - H_L # 汽化潜热

3.4 相位强制（Imposing the Phase）

每次PropsSI调用都需要根据输入对判定相态，并可能需要一次非平凡的闪蒸（flash）计算来生成求解器的初值。为提升效率，CoolProp 允许通过输入键字符串手动强制相态：在一个且仅一个输入键后追加"|"分隔符与相态字符串。

示例：

# 在 T=461.1 K、P=5.0e6 Pa 处强制液相求密度 PropsSI('D', 'T|liquid', 461.1, 'P', 5e6, 'Water') # 在 T=597.9 K、P=5.0e6 Pa 处强制气相求密度 PropsSI('D', 'T', 597.9, 'P|gas', 5e6, 'Water')

语法约束：每次调用都会重置为"not_imposed"，因此强制相态需要每次调用都显式写；以下情况会报错——分隔符不是"|"、相态字符串不在上表、或对多个输入键同时施加相态。为与低层接口保持一致，合法相态字符串还可加phase_或iphase_前缀（如phase_liquid）。

⚠️重要警告：强制相态时，输入对必须确实落在所指定的相区内。若相态指定错误，PropsSI可能抛出意外错误或返回错误结果。若不确定状态点相态，最好让 CoolProp 自动判定。

3.5 查看版本信息

import CoolProp CoolProp.__version__ # 当前版本 CoolProp.__gitrevision__ # 当前 git 修订号 # 或通过全局参数： CP.get_global_param_string("version") CP.get_global_param_string("gitrevision")

四、流体信息查询与平凡输入

4.1 get_fluid_param_string

用get_fluid_param_string获取流体的字符串编码信息（以 R125 为例）：

import CoolProp.CoolProp as CP for k in ['formula', 'CAS', 'aliases', 'ASHRAE34', 'REFPROP_name', 'pure', 'INCHI', 'INCHI_Key', 'CHEMSPIDER_ID']: print(k, '-->', CP.get_fluid_param_string("R125", k))

这些字段（分子式、CAS 号、别名、ASHRAE 34 编号、InChI 等）均来自 dev/fluids 下的流体 JSON 文件，是官方提供的可验证元数据。

4.2 平凡输入（Trivial Inputs）

不依赖热力学状态的物性（如临界温度）无需完整状态确定，可用Props1SI直接获取：

Props1SI("Tcrit", "Water")

Python 中PropsSI被重载为也接受两个参数，或用哑元占位：

CP.PropsSI("Tcrit", "Water") CP.PropsSI("Tcrit", "REFPROP::WATER") CP.PropsSI("Tcrit", "", 0, "", 0, "Water") # 所有语言通用写法

PropsSI的完整输入/输出参数表见高层接口文档的参数表章节。

五、相态查询：PhaseSI

想知道某个状态点的相态，可用高层函数PhaseSI：

import CoolProp.CoolProp as CP CP.PhaseSI('P', 101325, 'Q', 0, 'Water')

也可通过PropsSI('Phase', ...)获得浮点型相态索引，并用get_phase_index查询整型索引对应的相态标志：

CP.PropsSI('Phase', 'P', 101325, 'Q', 0, 'Water') CP.get_phase_index('phase_twophase') # 例如返回 5 CP.get_phase_index('phase_liquid')

在 T-p 坐标下绘制给定流体的相区分布（液相、气相、超临界、超临界液相/气相、熔化线、饱和线）的完整 Python 绘图脚本见 高层接口文档（该文档使用AbstractState+keyed_output与melting_line绘制熔化曲线与饱和曲线，可作为相图绘制的可直接运行模板）。

六、偏导数计算

6.1 一阶偏导（单相态）

CoolProp 实现了通用一阶偏导数，编码格式为d(OF)/d(WRT)|CONSTANT，即数学上的 $\left.\partial OF/\partial WRT\right|_{CONSTANT}$。底层调用 AbstractState::first_partial_deriv（见 CoolProp.h 高层函数声明）。

⚠️ 该导数公式目前仅对均相（单相）状态有效；两相导数未定义，且对许多组合无意义。

定压比热 $c_p=\left.\partial h/\partial T\right|_p$ 的两种求法：

import CoolProp.CoolProp as CP CP.PropsSI('C', 'P', 101325, 'T', 300, 'Water') # 直接查 C CP.PropsSI('d(Hmass)/d(T)|P', 'P', 101325, 'T', 300, 'Water') # 用导数串

6.2 二阶偏导（单相态）

同理可求二阶导数，例如 $c_p$ 对定压焓的导数d(d(Hmass)/d(T)|P)/d(Hmass)|P，其中内层d(Hmass)/d(T)|P即 $c_p$ 的定义：

CP.PropsSI('d(d(Hmass)/d(T)|P)/d(Hmass)|P', 'P', 101325, 'T', 300, 'Water')

6.3 饱和曲线导数

沿饱和曲线的导数同样可用字符串编码，例如饱和汽曲线上的焓导数（|sigma表示沿饱和线）：

CoolProp.CoolProp.PropsSI('d(Hmolar)/d(T)|sigma', 'P', 101325, 'Q', 1, 'Water')

⚠️ 该公式仅对干度为 0 或 1 的饱和态有效。

对于性能敏感场景，应改用低层接口的first_partial_deriv/second_partial_deriv，避免字符串解析开销（见下一节）。

七、低层接口：AbstractState

7.1 为什么需要低层接口

高层PropsSI内部会调用低层接口，但低层接口只使用枚举整数与浮点数、不使用字符串，省去了昂贵的字符串比较与解析，因此快得多。在 C++ 层，代码基于AbstractState抽象基类（include/CoolProp/AbstractState.h），它定义了各物性后端必须实现的协议，因此扩展一个全新物性库（如 REFPROP）只需让它的接口适配AbstractState结构即可无缝接入。

关键使用原则（详见 低层接口文档）：

• 每种流体（或混合物）只实例化一个后端实例，然后反复调用其方法——构造函数有计算开销；
• 使用表格后端（TTSE、BICUBIC、SVDSBTL）时，必须尽量少创建AbstractState实例：SVDSBTL 每次构造有约 80–140 ms 的表加载开销（进程内的内存缓存可缓解，见下文）；
• 在 C++ 中，AbstractState::factory返回裸指针，强烈建议用shared_ptr包裹以便自动析构。

7.2 最小示例（Python）

import CoolProp HEOS = CoolProp.AbstractState("HEOS", "Water") HEOS.update(CoolProp.DmolarT_INPUTS, 1e-6, 300) # (ρ, T) 输入，极低密度态 print(HEOS.p()) print([HEOS.keyed_output(k) for k in [CoolProp.iP, CoolProp.iHmass, CoolProp.iHmolar]])

• 输入对可用generate_update_pair(iT, 300, iDmolar, 1e-6)由"已知两个变量与值但不知顺序"的情况生成，返回如CoolProp.DmolarT_INPUTS；
• keyed_output(k)与访问器函数（如rhomolar()）等价，但便于按键迭代。

7.3 低层独有功能

以下功能仅存在于低层接口（源码文档）：

• 相位指定加速：HEOS.specify_phase(CoolProp.iphase_gas)可跳过饱和边界检查、直接求值状态方程，视输入对可提速约 10%；

取消指定可用HEOS.specify_phase(CoolProp.iphase_not_imposed)或HEOS.unspecify_phase()；相位指定应在调用update()之前进行。

• 混合物露点计算与饱和相组成：

HEOS = CoolProp.AbstractState("HEOS", "Methane&Ethane") HEOS.set_mole_fractions([0.2, 0.8]) HEOS.update(CoolProp.PQ_INPUTS, 101325, 1) # 露点 HEOS.saturated_liquid_keyed_output(CoolProp.iDmolar) HEOS.saturated_vapor_keyed_output(CoolProp.iDmolar) HEOS.mole_fractions_liquid() HEOS.mole_fractions_vapor() # 应为整体组成

• 低层偏导数（比高层导数串快得多）：

HEOS.update(CoolProp.PT_INPUTS, 101325, 300) HEOS.first_partial_deriv(CoolProp.iHmass, CoolProp.iT, CoolProp.iP) # ≈ cpmass HEOS.second_partial_deriv(CoolProp.iSmass, CoolProp.iT, CoolProp.iDmass, CoolProp.iDmass, CoolProp.iT)

• 两相与饱和导数：两相导数（Thorade 公式）在first_two_phase_deriv，饱和曲线导数在first_saturation_deriv/second_saturation_deriv。其中干度导数 $d(Q)/d(Hmolar)|P$ 与 $d(Q)/d(P)|Hmolar$ 由杠杆法则 $Q=(h-h')/(h''-h')$ 直接导出，仅限纯流体（混合物有温度滑移、伪纯流体泡露线压力不同，杠杆法则不成立），且在临界点发散。注意：表格后端（BICUBIC、TTSE）不实现这两个导数，应请求 HEOS 或 REFPROP 后端。

• 多重饱和根的消歧：少数饱和闪蒸输入对（如气相侧的HmolarQ_INPUTS/HmassQ_INPUTS，水的液相侧DmolarQ_INPUTS）在同一输入值下存在两个温度解（水的饱和汽焓约在 540 K 达峰、饱和液密度约在 4 °C 达峰）。CoolProp 现在对处于多根区域的普通update调用抛出MultipleSolutionsError而非静默选一个；要选择特定根，用update_with_guesses并通过GuessesStructure.T提供温度提示（内部利用切比雪夫超辅助曲线的单调子区间与 TOMS748 求根）。首次懒构建量热超辅助曲线约需 10–50 ms，之后每次调用约微秒级。

7.4 参考状态

焓与熵是相对量，应始终比较差值而非绝对值。需要时可用set_reference_state（Python）或set_reference_stateS（其他语言）设置标准参考状态：

• IIR：0 °C 饱和液处 h = 200 kJ/kg，s = 1 kJ/kg/K；
• ASHRAE：-40 °C 饱和液处 h = 0，s = 0；
• NBP：1 大气压饱和液处 h = 0，s = 0；
• DEF：恢复流体默认参考状态。

示例（n-Propane）：

import CoolProp.CoolProp as CP CP.set_reference_state('n-Propane', 'ASHRAE') CP.PropsSI('H', 'T', 233.15, 'Q', 0, 'n-Propane') # 应接近 0 CP.set_reference_state('n-Propane', 'DEF') # 恢复 CP.PropsSI('H', 'T', 233.15, 'Q', 0, 'n-Propane') # 不再为 0

也支持自定义参考状态（给定温度与摩尔密度处的 h、s 值）：

Dmolar = CP.PropsSI("Dmolar", "T", 298.15, "P", 101325, "NH3") CP.set_reference_state('NH3', 298.15, Dmolar, -60000.12, 314.159) # 流体, T, D(mol/m³), h(J/mol), s(J/mol/K)

⚠️ 参考状态的更改应作为程序初始化的一部分，不要在计算过程中反复修改；低层AbstractState实例在工厂创建后不会感知后续参考状态变更（这是有意设计），需在创建实例前设置。

八、混合物：预定义与自定义

8.1 预定义混合物

CoolProp 内置一批预定义混合物，用get_global_param_string("predefined_mixtures")获取逗号分隔列表；用.mix后缀按名调用：

import CoolProp.CoolProp as CP CP.get_global_param_string('predefined_mixtures').split(',')[0:6] CP.PropsSI('D', 'P', 101325, 'T', 300, 'Air.mix')

完整预定义混合物清单（含组分、摩尔分数与不可用备注）见 混合物文档。

8.2 用户自定义混合物

用&连接组分、[...]括起摩尔分数：

# R410A 组分编码 CP.PropsSI('D', 'T', 300, 'P', 101325, 'HEOS::R32[0.697615]&R125[0.302385]') # 三元及以上混合物同理，依次追加

8.3 混合物 PT 闪蒸与二元交互参数

混合物的热力学建模比纯流体复杂得多，CoolProp 采用经典的两阶段 Michelsen 方法（稳定性分析 + 相分裂计算）实现等温等压（PT）闪蒸，算法选择由配置键MIXTURE_STABILITY_ALGORITHM控制（1为 v8.0 起的默认 Michelsen 算法，0为 v7.x 及更早的 Gernert 遗产算法），详细的两阶段流程、TPD 稳定性判据、Wilson K 因子初始化、Rachford-Rice 方程与 GDEM 加速描述见 混合物文档。其流程结构可参见仓库中的 PT 闪蒸流程图 pt-flash-flowchart.png：

交互参数估计：对缺少交互参数的二元对，可用两种估计方案（应谨慎使用、只适用于性质相近的流体）：

• linear：$T_r$、$v_r$ 为两纯流体值随摩尔组成的线性函数；
• Lorentz-Berthelot：所有交互参数取 1.0。

CP.apply_simple_mixing_rule('Helium', 'Xenon', 'linear') CP.PropsSI('Dmass', 'T', 300, 'P', 101325, 'Helium[0.5]&Xenon[0.5]')

自定义交互参数：先设置配置布尔量OVERWRITE_BINARY_INTERACTION = true（默认 false，禁止覆盖已有参数），再用set_mixture_binary_pair_data（按 CAS 号）设置betaT、gammaT、betaV、gammaV等；低层接口可用AS.set_binary_interaction_double(0, 1, 'betaT', 0.987)仅对单个实例生效。仓库中所有已发布二元对的参数保存在 dev/mixtures/mixture_binary_pairs.json；同一二元对存在多个已发布模型时，最后一条记录生效（较新的关联式以追加方式排在旧记录之后，例如 H2+{CH4, N2, CO, CO2} 先列 GERG-2008 参数、后列 Beckmüller 2021 参数）。

还原参数与超额亥姆霍兹能：混合物建模基于还原密度/温度函数（Lemmon 的 $1/\rho_r=\sum x_i/\rho_{c_i}+\sum\sum x_ix_j\zeta_{ij}$ 形式，或 GERG-2008 的 $\beta_{T,ij}\gamma_{T,ij}$ 形式）与超额亥姆霍兹能 $\alpha^E$，具体公式与从 Lemmon 形式到 GERG-2008 形式的转换推导见 混合物文档。

九、高速表格后端：SVDSBTL、TTSE 与 BICUBIC

对压力-焓这类工程常用输入，直接求值完整状态方程太慢。CoolProp 提供三个表格后端（详见 表格插值文档）：BICUBIC、TTSE与SVDSBTL。

9.1 TTSE 与 BICUBIC

TTSE（Tabular Taylor Series Extrapolation）在规则网格上缓存函数值及其导数，用区间二分定位后按泰勒展开插值：

$$z=z_{i,j}+\Delta x\left(\frac{\partial z}{\partial x}\right){y}+\Delta y\left(\frac{\partial z}{\partial y}\right){x}+\frac{1}{2}\Delta x^2\left(\frac{\partial^2 z}{\partial x^2}\right){y}+\frac{1}{2}\Delta y^2\left(\frac{\partial^2 z}{\partial y^2}\right){y}+\Delta x\Delta y\left(\frac{\partial^2 z}{\partial y\partial x}\right)$$

BICUBIC则以单位方格四个角点的函数值与导数拟合双三次曲面（与 Wikipedia 所述标准方法一致）。表格默认存放在$HOME/.CoolProp/Tables/（可用CP.get_global_param_string("HOME")查询，或用配置项ALTERNATIVE_TABLES_DIRECTORY换目录），默认网格 200×200，可用配置项TABULAR_NX/TABULAR_NY或工厂串选项?{"grid":{"Nx":400,"Ny":400}}调高分辨率（临界区网格较粗，是误差的主要来源）。每次流体生成表格约产生 20 MB 数据，表格目录默认超过 1 GB 会警告、1.5 GB 会报错（可用配置键MAXIMUM_TABLE_DIRECTORY_SIZE_IN_GB调整）。

9.2 SVDSBTL：SVD 压缩表格查找后端

SVDSBTL是面向新代码推荐的高吞吐表格后端（SVDSBTL 文档），由三层构成：

1. 区域图谱（Region atlas）：把 $(p,h)$ 或 $(p,T)$ 包络划分为 3–7 个不相交区域（LIQUID/VAPOR/SUPER，IF97 源另有 R1/R3、R2/R3 边界分裂），每个区域用两条解析边界曲线归一化到 $[0,1]$；
2. 逐区域 SVD：每个属性（ρ, h, s, u, w, η, λ）表示为稠密 $N_h\times N_p$ 采样网格（默认 200×800、秩 r=20）的秩-r SVD，密度与输运性质用对数变换以适配 SVD 的光滑性假设；
3. 临界区补丁回退：临界点附近的 $\partial\rho/\partial p|_h$ 尖点无法用有限秩表达，SVDSBTL 自动标定一个小矩形补丁（默认水为 $[0.95,1.05]T_c\times[0.75,1.15]p_c$，按流体自动收缩并缓存到 sidecar 文件），落在补丁内的查询直接转发给源后端。

import CoolProp.CoolProp as CP AS = CP.AbstractState("SVDSBTL&IF97", "Water") # IAPWS G13-15 一致 AS = CP.AbstractState("SVDSBTL&HEOS", "Methane") # 多流体 HEOS AS = CP.AbstractState("SVDSBTL&REFPROP", "Water") # REFPROP 真值

支持的源后端为HEOS、REFPROP、IF97（仅水）；不能单独写SVDSBTL（无默认真值源）。已表格化的输入对：HmassP_INPUTS（工业主导）、PT_INPUTS、PSmass_INPUTS、DmassT_INPUTS；摩尔基输入从质量基表乘除摩尔质量得到；两相PQ/QT沿饱和线用 SuperAncillary/代理快速路径或源闪蒸解析。

三种性能模式（源码文档中给出了 Apple Silicon 上的实测数据）：

1. 复用实例 +update：表加载摊薄到整个工作负载，单相区原生 C++ 约 200 ns/次，两相/饱和线约 1–1.5 µs/次；
2. fast_evaluate批量路径：无实例变更、无逐点封装编组，共享定位与 Hermite 基计算，4 输出查询约 300–330 ns/探针（超临界区），每个附加输出边际约 35 ns——CFD 规模（每时间步 ≥10 万探针）的唯一合理选择；
3. PropsSI高层包装（默认关闭）：每次调用都会构造后端、首次需加载 7–14 MB 表（约 80–140 ms），因此默认通过配置键ALLOW_SVDSBTL_IN_PROPSSI关闭，仅适合交互式/脚本用途。

进程级线程安全 LRU 内存缓存（SVDSBTL_SURFACE_CACHE_MAX_ENTRIES默认 16、SVDSBTL_SURFACE_CACHE_MAX_SIZE_MB默认 512）可让同一进程内相同(流体, 源, 输入对, 选项)的二次构造退化为一次哈希查找。表构建可用SVDSBTL_SAMPLING_THREADS并行（默认 1，4 线程约 2.25× 加速；REFPROP 源因线程安全自动回退串行）。

配置键速查：ALLOW_SVDSBTL_IN_PROPSSI（默认 false）、ALTERNATIVE_SVDTABLES_DIRECTORY（默认空，重定向.svd.bin.z与.critpatch.bin缓存目录）、SVDSBTL_SURFACE_CACHE_MAX_ENTRIES、SVDSBTL_SURFACE_CACHE_MAX_SIZE_MB、SVDSBTL_SAMPLING_THREADS。工厂串选项如{"grid":{"NT":200,"NR":800,"rank":20}}、{"prebuild":true}（预构建全部输入对表面，不改变表内容、不进入 OptHash）与critical_patch覆盖项见 后端选项文档。

精度包络（据官方文档）：SVDSBTL&IF97::Water的 $T(p,h)$ 在 R1/R2/R5 符合 IAPWS G13-15 预算（最大 2.79/8.52/1.81 mK 对 25/10/10 mK 预算）；SVDSBTL&HEOS在亚临界包络上 ρ、h、s 相对误差约 $10^{-3}$，极端区域角点峰值约 1%；SVDSBTL&REFPROP在测试探针上匹配 REFPROP 真值到其数值噪声底。

9.3 表格数据格式

BICUBIC/TTSE的表格以 zlib 压缩的 msgpack 格式存盘（single_phase_logph.bin.z、single_phase_logpT.bin.z、phase_envelope.bin.z），文档给出了用 Pythonmsgpack+zlib解包查看 T/h/p/ρ 矩阵的完整脚本（表格插值文档）。

十、IF97 水/蒸汽后端

IAPWS-IF97 工业公式是压力基（而非密度基）的水/蒸汽快速公式，比 IAPWS-95 亥姆霍兹公式快但精度略低（除临界点附近外，所有性质不确定度在 1% 内，多数区域在 0.1% 内）。IF97 后端最初是为湿空气后端开发的快速水性质计算，现已成熟为覆盖绝大多数正反向公式的独立后端（详见 IF97 文档）。

分区结构（IF97 按构造分段）：Region 1 压缩液（T ≤ 623.15 K，逆向 Gibbs $g_1(T,p)$）；Region 2 过热蒸汽与高温气体（至 1073.15 K，$g_2(T,p)$）；Region 3 稠密超临界/近临界（T ≥ 623.15 K、p ≥ p_B23(T)，是唯一用 $\rho,T$ 参数化的区域，$f_3(\rho,T)$）；Region 4 饱和曲线（仅 $p_\mathrm{sat}(T)$）；Region 5 高温扩展（1073.15–2273.15 K，至 50 MPa，$g_5(T,p)$）。区域边界为解析曲线：R2/R3 边界 $p_{B23}(T)=1.0193\times10^{-3}(T-572.545)^2+13.919$ MPa（T ∈ [623.15, 863.15] K），R1/R3 边界为等温线 T = 623.15 K。由于各区域基本方程不同，$c_p, s, w$ 在边界处有结构性扭结（值连续、导数不连续），下游插值器必须沿边界切分区域（这正是 SVDSBTL 图谱沿 $p_{B23}$ 分裂的原因）。

使用方式：仅支持IF97::Water（别名IF97::H2O，大小写不敏感）。输出键包括T, P, D, C, Cvmass, U, H, S, A, V, L, I, Prandtl及平凡量M, Tmin, Tmax, Pmin, Pmax, Ttriple, Tcrit, ptriple, pcrit。五个已知限制：不支持通用偏导数；不支持混合物；设置参考状态无效（参考状态固定为三相点饱和液的 U、S 恒为零）；不支持固态；熔点-升华线不使用，T_min 统一限制为 273.15 K。

from CoolProp.CoolProp import PropsSI PropsSI('C', 'T', 500, 'P', 101325, 'IF97::Water') # 500 K、1 atm 比热 PropsSI('D', 'T', 500, 'P', 101325, 'IF97::Water') # 密度 PropsSI('P', 'T', 500, 'Q', 0, 'IF97::Water') # 500 K 饱和压力

十一、湿空气：HAPropsSI

湿空气模块（湿空气物性文档）基于 Hermann 等的论文（ASHRAE 研究项目 RP-1485 成果，与 ASHRAE Handbook 2009 参考饱和表同源），适用压力 0.01 kPa–10 MPa、温度 -143.15–350 °C、湿度比 0–10 kg 水/kg 干空气。湿空气被建模为干空气（伪纯气体）与水蒸气（真实气体）的混合物，由干球温度 T、总压 p 与水摩尔分数 $\psi_w$ 三个变量固定状态；湿度比 W、相对湿度 φ 与露点温度是获取 $\psi_w$ 的三种非迭代途径。摩尔体积用截断维里方程 $p=\bar R T/\bar v(1+B_m/\bar v+C_m/\bar v^2)$，增强因子 f 描述空气对水饱和蒸气压的影响。

from CoolProp.HumidAirProp import HAPropsSI # 25 °C、1 atm、相对湿度 50% 的焓（J/kg 干空气） h = HAPropsSI('H', 'T', 298.15, 'P', 101325, 'R', 0.5) # 用该焓反求饱和空气温度——输入顺序无关 T = HAPropsSI('T', 'P', 101325, 'H', h, 'R', 1.0)

HAPropsSI的输入/输出参数表（湿球温度B/Twb/T_wb、露点D/Tdp/DewPoint、焓H/Hda/Enthalpy、湿度比W/Omega/HumRat、相对湿度R/RH/RelHum、水摩尔分数psi_w/Y、比热C/CV/Cha/CVha、熵S/Sha、体积V/Vda/Vha、黏度M/Visc/mu、导热K/k/Conductivity、压缩因子Z等，含单位与输入/输出标志）完整列于 湿空气文档。注意：湿球温度在水的三相点（273.16 K）处因灯芯由液态水切换为冰而发生不连续跳变，位于不可达带的湿球温度输入（如HAPropsSI("Tdb","Twb",273.15,"RelHum",0.01,"P",89000)）无物理解，CoolProp 会抛出指明三相点的ValueError而非返回误导值。

十二、调用 REFPROP

安装了 REFPROP 库时，可用REFPROP::前缀以与调用 CoolProp 完全相同的方式调用 REFPROP：

import CoolProp.CoolProp as CP CP.PropsSI('D', 'T', 300, 'P', 101325, 'HEOS::R32[0.697615]&R125[0.302385]') # CoolProp 计算 CP.PropsSI('D', 'T', 300, 'P', 101325, 'REFPROP::R32[0.697615]&R125[0.302385]') # REFPROP 计算

低层同样支持CoolProp.AbstractState("REFPROP", "WATER")。REFPROP 封装的详细说明见 REFPROP 文档。

十三、添加流体

所有流体以 JSON 格式编译进库，源数据保存在 dev/fluids。可运行时读取并回填：

import CoolProp.CoolProp as CP jj = CP.get_fluid_param_string("Water", "JSON") # 获取水的 JSON 结构 CP.add_fluids_as_JSON("HEOS", jj) # 已存在会报错 CP.set_config_bool(CP.OVERWRITE_FLUIDS, True) # 允许覆盖 CP.add_fluids_as_JSON("HEOS", jj) # 成功 CP.set_config_bool(CP.OVERWRITE_FLUIDS, False) # 恢复

十四、后端选项字符串与配置机制

CoolProp 的每个实例级后端配置通过工厂字符串的 JSON 后缀传递（后端选项文档）：

SVDSBTL&HEOS::Water # 无选项，全部使用 schema 默认 SVDSBTL&HEOS::Water?{"critical_patch":"off"} # 内联 JSON SVDSBTL&HEOS::Water?@/path/to/cfg.json # 文件间接引用 HEOS::Water?{} # 空选项（无操作）

解析器在第一个?处分割，其后全部视为单个 JSON 值（或以@开头的文件路径）；选项可挂在后端半区或流体半区，但两半区同时携带选项会抛ValueError。每个支持选项的后端都内置 JSON Schema（Draft 2020-12，源码位于 include/CoolProp/schemas），未知键、类型不匹配、缺必填键、枚举越界都会在构造时立即抛出。build_options_json()返回实例构造所用的规范化 JSON（递归排序键），便于字节级复现；缓存后端的文件名包含规范化字节的 FNV-1a 64 十六进制前缀。该机制之所以选 JSON 后缀而非 setter/全局配置/构建器 API，是因为它能保证缓存键不变性、实例级隔离、零封装代码改动，具体决策轨迹见 设计文档。现有 Configuration 全局键（如BICUBIC_GRID_NT/NR、TTSE_GRID_NT/NR、ALTERNATIVE_REFPROP_*）将逐步迁移为选项键（grid.NT/NR、library_path/hmx_path/root_path），迁移期间全局键继续可用至少一个发布周期。

十五、帮助、支持与社区

按官方门户文档 Web/index.rst 的建议：一般性讨论请发布到官方 Discussions；Bug 与功能请求请提交到 issue 跟踪器；请不要直接给开发者发邮件（以便讨论可被检索）；支持项目可参阅 赞助页。在出版物中引用 CoolProp 时，请参照 引用信息页。

十六、总结：如何选择调用路径

结合本文的源码路径指引（src/Backends 各后端实现、include/CoolProp/AbstractState.h 抽象协议、dev/fluids 流体数据、include/CoolProp/CoolPropLib.h DLL 接口），读者可以沿"高层函数 → 底层协议 → 后端实现 → 数据文件"的链路深入理解并复用 CoolProp 的完整技术栈。

• 科学计算