# IAPWS95

**Repository Path**: thermalogic/iapws95

## Basic Information

- **Project Name**: IAPWS95
- **Description**: IAPWS95
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IAPWS-95 热力学性质计算库

本项目实现了 **IAPWS-95** (International Association for the Properties of Water and Steam Formulation 1995, Revised 2018) 标准，用于精确计算水和蒸汽的热力学性质。项目包含 C 和 Rust 两种语言的高性能实现。

## 目录

- [功能特性](#功能特性)
- [技术规格](#技术规格)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
  - [C 语言版本](#c-语言版本)
  - [Rust 语言版本](#rust-语言版本)
- [IAPWS-95 公式说明](#iapws-95-公式说明)
- [性能优化](#性能优化)
- [测试验证](#测试验证)
- [引用文献](#引用文献)

---

## 功能特性

### 通用功能

- **全面的性质计算**: 温度、压力、密度、焓、熵、内能、比热容 (Cp, Cv)、声速、焦耳-汤姆逊系数、等温压缩率
- **多种输入模式**: 支持温度-密度 (TD) 和温度-压力 (TP) 输入规格
- **饱和状态计算**: 计算饱和液体/蒸汽性质
- **标准符合性**: 严格按照 IAPWS-95 标准实现

### C 语言版本特性

- **极致性能优化**: 针对 CFD 求解器和实时过程模拟优化的实现
- **零运行时依赖**: 仅使用 C 标准库，跨平台兼容性好
- **多种编译器支持**: GCC、Clang、MSVC
- **预估性能提升**: 相比朴素实现减少 **40-60%** 的计算开销

### Rust 语言版本特性

- **内存安全保证**: 利用 Rust 所有权系统确保无数据竞争和缓冲区溢出
- **零成本抽象**: 编译期优化，运行时零额外开销
- **现代构建系统**: Cargo 包管理器，依赖管理简单
- **无外部依赖**: 仅使用标准库，最小化安全风险

---

## 技术规格

| 参数 | 范围 |
|------|------|
| **温度 (T)** | 273.16 K 至 1273 K (0°C 至 1000°C) |
| **压力 (p)** | 最高 1000 MPa (扩展可用范围: 100 GPa) |
| **临界温度 (Tc)** | 647.096 K |
| **临界密度 (ρc)** | 322 kg/m³ |
| **比气体常数 (R)** | 0.46151805 kJ/(kg·K) |

### 计算性质列表

| 性质 | 符号 | 单位 |
|------|------|------|
| 温度 | T | K |
| 密度 | ρ | kg/m³ |
| 压力 | p | MPa |
| 内能 | u | kJ/kg |
| 焓 | h | kJ/kg |
| 熵 | s | kJ/(kg·K) |
| 定容比热容 | cv | kJ/(kg·K) |
| 定压比热容 | cp | kJ/(kg·K) |
| 声速 | w | m/s |
| 焦耳-汤姆逊系数 | μ | K/MPa |
| 等温压缩率 | κ | 1/MPa |

---

## 项目结构

```
iapws95/
├── README.md                    # 总说明文档 (本文件)
├── doc/                         # 文档和参考资料
│   ├── IAPWS95-2018.pdf        # IAPWS-95 官方规范文档
│   └── iapws95.py              # Python 参考实现
├── c/                           # C 语言版本
│   ├── include/
│   │   └── iapws95.h           # 公共 API 头文件
│   ├── src/
│   │   ├── README.md           # C 版本详细说明文档
│   │   ├── Makefile            # GCC 构建配置
│   │   ├── build.bat           # MSVC 构建脚本
│   │   ├── iapws95.c           # 主 API 和工具函数
│   │   ├── iapws95_ideal.c     # Helmholtz 自由能理想气体部分
│   │   ├── iapws95_residual.c  # Helmholtz 自由能剩余部分
│   │   ├── main.c              # 测试驱动和示例程序
│   │   └── test_iapws95_table7.c  # Table 7 测试用例
├── rust/                        # Rust 语言版本
│   ├── Cargo.toml              # Cargo 项目配置
│   ├── Cargo.lock              # 依赖锁定文件
│   ├── README.md               # Rust 版本详细说明文档
│   ├── main.rs                 # 命令行入口程序
│   ├── src/
│   │   ├── lib.rs              # 库入口，导出所有公共模块
│   │   ├── iapws95.rs          # 主模块：参考常数、数据结构、API 函数
│   │   ├── iapws95_ideal.rs    # Helmholtz 自由能理想气体部分
│   │   └── iapws95_residual.rs # Helmholtz 自由能剩余部分
│   └── tests/
│       └── table7_tests.rs     # Table 7 测试用例
└── .gitignore                   # Git 忽略规则
```

---

## 快速开始

### C 语言版本

#### 环境要求

- C99 或更高标准编译器 (GCC 4.8+, Clang 3.3+, MSVC 2015+)
- Make (Linux/macOS/MinGW)

#### 构建和运行

**使用 GCC (Linux/macOS/MinGW):**

```bash
cd c/src

# 编译项目
make

# 运行测试
make test

# 清理构建文件
make clean
```

**使用 MSVC (Windows):**

```cmd
cd c\src
build.bat
```

#### 使用示例

```c
#include "iapws95.h"

int main() {
    iapws95_TD_state_t input = {
        .T = 500.0,      /* Temperature: 500 K */
        .rho = 838.025   /* Density: 838.025 kg/m³ */
    };
    
    iapws95_state_t output;
    
    int result = iapws95_from_TD(&input, &output);
    
    if (result == 0) {
        printf("Pressure: %.6f MPa\n", output.p);
        printf("Enthalpy: %.3f kJ/kg\n", output.h);
        printf("Entropy: %.6f kJ/(kg·K)\n", output.s);
    }
    
    return 0;
}
```

#### 编译示例程序

```bash
cd c/src
gcc -o iapws95 main.c iapws95.c iapws95_ideal.c iapws95_residual.c -O2 -lm
./iapws95
```

---

### Rust 语言版本

#### 环境要求

- Rust 工具链 (edition 2021)
- Cargo 构建系统

安装 Rust: https://www.rust-lang.org/tools/install

#### 构建和运行

```bash
cd rust

# 构建项目
cargo build

# 运行测试
cargo test

# 生成文档并打开
cargo doc --open

# 清理构建文件
cargo clean
```

#### 使用示例

```rust
use iapws95::iapws95::*;

fn main() {
    // 创建状态 (温度 + 密度)
    let state = TDState {
        T: 500.0,      // Temperature in Kelvin
        rho: 838.025,  // Density in kg/m³
    };

    // 计算所有热力学性质
    match iapws95_from_TD(&state) {
        Ok(result) => {
            println!("Pressure: {:.6} MPa", result.p);
            println!("Enthalpy: {:.4} kJ/kg", result.h);
            println!("Entropy:  {:.6} kJ/(kg·K)", result.s);
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

#### 命令行使用

```bash
# 运行内置测试
cargo run -- -t

# 计算指定状态的热力学性质
cargo run -- 500 838.025

# 查看帮助信息
cargo run -- --help
```

---

## IAPWS-95 公式说明

IAPWS-95 的核心是**无量纲 Helmholtz 自由能** φ(δ, τ)，它被分解为两部分：

```
φ(δ, τ) = φ°(δ, τ) + φʳ(δ, τ)
```

其中：
- **φ°(δ, τ)**: 理想气体部分，仅依赖于温度
- **φʳ(δ, τ)**: 剩余部分，考虑分子间相互作用

### 约化变量

```
δ = ρ/ρc    (约化密度)
τ = Tc/T    (逆约化温度)
```

### 理想气体部分 φ°(δ, τ)

基于 IAPWS-95 公式 5 和表 1、表 4：

```
φ°(δ, τ) = ln(δ) + n₁ + n₂τ + n₃ln(τ) + Σᵢ₌₄⁸ nᵢln[1 - exp(-γᵢτ)]
```

包含 8 个系数 (n₁-n₈) 和 5 个指数系数 (γ₄-γ₈)。

### 剩余部分 φʳ(δ, τ)

基于 IAPWS-95 表 5，由四部分组成：

```
φʳ(δ, τ) = Σᵢ nᵢδ^dᵢτ^tᵢ                                    [多项式项，i=1-7]
         + Σᵢ nᵢδ^dᵢτ^tᵢexp(-δ^cᵢ)                          [指数项，i=8-51]
         + Σᵢ nᵢδ^dᵢτ^tᵢexp[-αᵢ(δ-εᵢ)²-βᵢ(τ-γᵢ)²]          [高斯项，i=52-54]
         + Σᵢ nᵢΔ^bᵢδF(δ, τ)                               [非解析项，i=55-56]
```

**项分类统计**:

| 项类型 | 索引范围 | c 值 | 数量 |
|--------|----------|------|------|
| 多项式项 (Polynomial) | i=1-7 | - | 7 |
| 指数项 (c=1) | i=8-22 | 1 | 15 |
| 指数项 (c=2) | i=23-42 | 2 | 20 |
| 指数项 (c=3,4,6) | i=43-51 | 3,4,6 | 9 |
| 高斯项 (Gaussian) | i=52-54 | - | 3 |
| 非解析项 (Non-analytic) | i=55-56 | - | 2 |
| **总计** | - | - | **56** |

### 性质计算公式

所有热力学性质都通过 Helmholtz 自由能及其导数计算得到（基于 IAPWS-95 Table 3）：

| 性质 | 公式 |
|------|------|
| 压力 p | RT·δ·(1 + δ·∂φʳ/∂δ) |
| 内能 u | RT·τ·(φ° + φʳ + τ·∂φ/∂τ) |
| 熵 s | R·(φ° + φʳ - τ·∂φ/∂τ) |
| 焓 h | u + p/ρ × 1000 |
| 定容比热容 cv | R·(-τ²·∂²φ/∂τ²) |
| 定压比热容 cp | cv + R·(∂p/∂T)²ᵣₒₕₑ / (∂p/∂ρ)ₜ |
| 声速 w | √(cp/cv · RT × 1000) |

---

## 性能优化

### C 语言版本优化技术

C 版本针对计算密集型应用（CFD、实时过程模拟）进行了深度优化，相比朴素实现减少 **40-60%** 的计算开销。主要优化技术包括：

#### 1. 快速整数幂 (`ipow`) — 平方求算法

**问题**: IAPWS-95 公式包含数十个具有整数指数的项（如 δ^15、τ^23）。使用标准库 `pow(double, double)` 计算整数幂效率低下，因为 `pow()` 必须处理任意实数指数，涉及对数和指数函数调用。

**解决方案**: 使用**平方求算法**实现自定义 `ipow(double x, int n)` 函数：

```c
double ipow(double x, int n) {
    if (n == 0) return 1.0;
    double result = 1.0;
    double base = x;
    while (n > 0) {
        if (n & 1) result *= base;   // 当位为 1 时乘
        base *= base;                 // 平方底数
        n >>= 1;                      // 右移一位
    }
    return result;
}
```

**性能**: O(log n) 次乘法运算。例如，计算 δ^15 仅需 **4 次乘法**（15 = 1111₂），相比完整的 `log() + exp()` 函数调用快 10-50 倍。

#### 2. 预计算公共幂值 — 避免重复计算

**问题**: 多个项共享相同的 δ 幂次，如 δ²、δ³、δ⁴、δ⁶。独立计算每个会浪费 CPU 周期。

**解决方案**: 一次性计算共享幂次并在所有需要它们的项中重用：

```c
double delta_2 = delta * delta;       /* δ² 只计算一次 */
double delta_3 = delta_2 * delta;     /* δ³ = δ² × δ */
double delta_4 = delta_3 * delta;     /* δ⁴ = δ³ × δ */
double delta_6 = delta_3 * delta_3;   /* δ⁶ = δ³ × δ³ */

/* 所有 20 个 c=2 的项共享 exp(-δ²): */
for (i = 0; i < 20; i++) {
    sum += coeff[i] * ipow(delta, d[i]) * ipow(tau, t[i]) * exp(-delta_2);
}
```

**影响**: `exp(-δ²)` 只需计算 **1 次**而非 20 次。类似地，`exp(-δ³)`、`exp(-δ⁴)`、`exp(-δ⁶)` 也各减少多次调用，每次评估最多消除 **25 次冗余 exp() 调用**。

#### 3. 直接乘法求平方 — 消除函数开销

**问题**: 通过 `pow(x, 2.0)` 计算 x² 仍然会调用完整的 `pow()` 函数机制。

**解决方案**: 将所有 `pow(x, 2.0)` 替换为直接乘法：

```c
/* 优化前 (慢): */
double exp_arg = -a * pow(delta - e, 2.0) - b * pow(tau - g, 2.0);

/* 优化后 (快): */
double d_e = delta - e;
double t_g = tau - g;
double exp_arg = -a * d_e * d_e - b * t_g * t_g;
```

**影响**: 每个 `pow(x, 2.0)` → `x*x` 替换节省一次函数调用及其内部分支逻辑。在高斯项中消除了 **6 次冗余 pow() 调用**。

#### 4. 系数分组 — 缓存友好的数据布局

**解决方案**: 根据共享指数模式将系数分组到单独的静态常量结构中：

| 组 | 项范围 | 共享特性 | 数组名称 |
|----|--------|----------|----------|
| 多项式 | i=1–7 | δ 有整数 d，τ 有分数 t | `res_poly_d1[]` |
| c=1 指数 | i=8–22 | 都使用 `exp(-δ)` | `res_exp_d2_c1[]` |
| c=2 指数 | i=23–42 | 都使用 `exp(-δ²)` | `res_exp_d2_c2[]` |
| c=3/4/6 指数 | i=43–51 | 共享 δ 幂次 (δ³, δ⁴, δ⁶) | `res_exp_d2_cn[]` |
| 高斯 | i=52–54 | 相同函数形式 | `res_gauss[]` |
| 非解析 | i=55–56 | 特殊形式 | `res_non_anal[]` |

**优势**:
- **缓存局部性**: 每个循环访问连续数组，提高 CPU 缓存命中率
- **编译器优化**: 编译器能更好地分析和优化每个同质组
- **可维护性**: 系数按 IAPWS-95 规范表格组织

#### 5. 中间值缓存 — 消除重复减法

**解决方案**: 将复杂表达式存储在局部变量中：

```c
double d_e = delta - res_gauss[i].e;   /* 只计算一次，使用 3+ 次 */
double t_g = tau - res_gauss[i].g;     /* 只计算一次，使用 2+ 次 */
```

**影响**: 减少浮点减法次数并提高寄存器利用率。

#### C 版本性能总结

| 优化技术 | 每次调用节省的操作数 | 影响 |
|---------|---------------------|------|
| `ipow` vs `pow()` (整数指数) | ~60+ 超越函数调用 | **高** — 每个 `log()+exp()` 对比乘法慢 10-50 倍 |
| 预计算公共幂次 (δ², δ³, δ⁴, δ⁶) | ~25 次 `exp()` 调用 | **中高** — `exp()` 比乘加慢 5-10 倍 |
| 直接平方 (`x*x` vs `pow(x,2.0)`) | ~6+ 次函数调用 | **中低** — 消除不必要的开销 |
| 中间值缓存 | ~30+ 冗余浮点运算 | **中** — 改善寄存器压力和指令级并行性 |

---

### Rust 语言版本优化策略

Rust 版本利用现代编译器和语言特性进行优化：

#### 1. `#[inline]` 属性

对频繁调用的内联函数（如约化变量计算）添加内联提示：

```rust
#[inline]
pub fn reduced_density(rho: f64) -> f64 {
    rho / IAPWS95_RHOCRIT
}
```

#### 2. 零成本抽象

利用 Rust 的类型系统和所有权模型，在编译期消除运行时检查开销：

```rust
#[derive(Debug, Clone, Copy)]
pub struct TDState {
    pub T: f64,   // 值类型，无堆分配
    pub rho: f64,
}
```

#### 3. 模式匹配和 Result 处理

利用 Rust 的错误处理机制确保安全性而不牺牲性能：

```rust
match iapws95_from_TD(&state) {
    Ok(result) => println!("Pressure: {:.6} MPa", result.p),
    Err(e) => eprintln!("Error: {}", e),
}
```

#### 4. Cargo 构建优化

使用 Release 模式获得最佳性能：

```bash
cargo build --release
```

---

## 测试验证

### C 语言版本测试

```bash
cd c/src
make test
```

测试套件验证 Helmholtz 自由能的理想气体部分和剩余部分的计算结果，与 IAPWS-95 官方参考值进行对比。

**运行详细输出**:

```bash
./iapws95 -t
```

### Rust 语言版本测试

```bash
cd rust
cargo test              # 运行所有测试
cargo test -- --nocapture  # 显示测试输出
cargo test table7_tests    # 运行特定模块的测试
```

**测试覆盖情况**:

| 测试类别 | 数量 | 说明 |
|----------|------|------|
| 温度范围测试 | 10 | 覆盖 273.16 K 至 1273 K |
| 一致性验证 | 3 | 验证便捷函数与主函数的结果一致 |
| 边界条件 | 4 | 临界点、最小/最大温度、无效输入 |
| 物理合理性 | 5 | 单调性检查、理想气体 vs 剩余部分贡献 |

### 数值精度

根据 IAPWS-95 官方文档，该公式在以下范围内提供：
- **单相区**: 不确定度 < 0.01% (压力), < 0.02% (焓)
- **饱和线**: 不确定度 < 0.05% (饱和压力), < 0.1% (饱和密度)

---

## 语言版本对比

| 特性 | C 语言版本 | Rust 语言版本 |
|------|-----------|--------------|
| **内存管理** | 手动管理 | 编译期所有权检查 |
| **安全性** | 需开发者保证 | 编译器强制保证 |
| **构建系统** | Make / MSBuild | Cargo |
| **运行时依赖** | C 标准库 | Rust 标准库 |
| **性能优化** | 深度手工优化 (40-60% 提升) | 编译器自动优化 + 内联提示 |
| **错误处理** | 返回值码 | Result<T, E> |
| **跨平台性** | 极好 (C99 标准) | 极好 (Rust 跨平台支持) |
| **适用场景** | CFD、嵌入式系统、实时控制 | 现代应用、Web 服务、安全关键系统 |

---

## 开发指南

### 代码规范

**C 语言版本**:
- 遵循 C99 标准
- K&R 缩进风格
- 所有函数添加注释说明
- 使用 `static const` 存储系数数组

**Rust 语言版本**:
- 遵循 Rust 社区编码规范 (`rustfmt`)
- 公共 API 添加文档注释 (`///`)
- 利用 Rust 类型系统确保安全性
- 使用 `#[inline]` 优化频繁调用的函数

### 待实现功能

以下功能在两个版本中都标记为待实现：

| 功能 | 说明 | 优先级 |
|------|------|--------|
| **TP 输入模式** | 从温度和压力计算性质（需要迭代密度求解器） | 高 |
| **饱和状态计算** | 计算给定温度下的饱和液体/蒸汽性质 | 高 |
| **完整二阶导数** | ∂²φʳ/∂δ² 的完整实现 | 中 |
| **焦耳-汤姆逊系数** | 完整的 μ 系数计算 | 中 |

### 贡献指南

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

**贡献要求**:
- C 版本: 保持与现有代码风格一致，添加必要的测试
- Rust 版本: 运行 `cargo fmt` 和 `cargo clippy`，确保测试通过
- 所有新增功能必须包含文档注释
- 保持向后兼容性

---

## 引用文献

1. **IAPWS-95 官方规范**: Wagner, W., & Pruß, A. (2002). "The IAPWS Formulation 1995 for the Thermodynamic Properties of Ordinary Water Substance for General and Scientific Use." *Journal of Physical and Chemical Reference Data*, 31(2), 387-535.

2. **IAPWS 2018 修订版**: "Revised Release on the IAPWS Formulation 1995 for the Thermodynamic Properties of Ordinary Water Substance", IAPWS, September 2018. [IAPWS R6-95(2018)](https://iapws.org/readme/iapws-r1/)

3. **官方文档**: 详见 `doc/IAPWS95-2018.pdf`

---

## 许可证

本项目仅供教育和研究用途。商业用途请参考 [IAPWS 官方网站](https://iapws.org/) 获取最新的许可要求。

---

## 联系方式

如有问题、建议或贡献，请通过以下方式联系：
- 提交 Issue
- 创建 Pull Request

---

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 0.1.0 | 2024 | 初始版本 - C 和 Rust 双语言实现，Helmholtz 自由能基本功能 |