# Fluid-CFD Coupler

**Repository Path**: cnt-code/fluid-cfd-coupler

## Basic Information

- **Project Name**: Fluid-CFD Coupler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fluid-CFD Coupler — 1D 管网–3D 场多速率双向耦合求解器

**AI+工业软件赛道 · 中国商飞命题：流体 CFD 方向——三维耦合求解时间步长协调和边界耦合**

把粗时间步的 **1D 管网/喷管网络**与细时间步的 **3D 不可压 Navier–Stokes 场求解器**通过**多速率子循环**在交换窗口处双向耦合：1D 出口流量/温度实时传递到 3D 入口，3D 出流面背压实时回灌 1D 喷管下游边界。配套毫秒级阀门控制逻辑、守恒性审计与精度-效率权衡曲线。核心为纯 NumPy，无闭源组件，无网络调用，不做稠密矩阵构造。

## 提交物索引（对照赛题交付要求）

| 赛题交付要求 | 本仓库对应 |
| --- | --- |
| a. 方案说明文档 | `docs/10-流体双向耦合求解器.pdf`（`.md` 同源）+ `SOLUTION.md` |
| b. 可运行原型 | `python/`（CLI 入口）；容器化见 `docker/cfd.Dockerfile` |
| c. 算例报告 | `docs/10-流体双向耦合求解器.pdf` + `bench/fluid-cfd-results.json`（4 算例实测） |
| d. 可复现材料 | `python/` + `python/requirements.txt` + 下方复现步骤 |
| e. 演示视频 | B 站：【流体双向耦合求解器｜1D 管网 × 3D CFD 毫秒级协同仿真】`https://www.bilibili.com/video/BV1vQhy6NEkY/`（含毫秒级阀门介入的完整双向耦合响应） |

## 演示与可视化

![3D 场体素：Case A 壅塞流在方形场域内沿 +x 发展](docs/assets/screenshots/plugins/fluid-cfd-coupler/field-voxels-case-a.png)

![耦合时间序列（Case A 定常活塞）](docs/assets/screenshots/plugins/fluid-cfd-coupler/timeseries-case-a.png)

![验证视图：Case A 精度—效率权衡曲线](docs/assets/screenshots/plugins/fluid-cfd-coupler/tradeoff-case-a.png)

演示视频（B 站）：[【流体双向耦合求解器｜1D 管网 × 3D CFD 毫秒级协同仿真】](https://www.bilibili.com/video/BV1vQhy6NEkY/)

## 关键验证结果

来源：`bench/fluid-cfd-results.json`（2026-09-25 实测，numpy 纯内核）。

| 算例 | 场景 | 关键指标 |
| --- | --- | --- |
| Case A 定常壅塞 | 喷管全开、临界壅塞 | 流量相对误差 **0.0%**（解析临界流量）；放气压力误差 1.68%（归因于等熵幂律与常温刚性罐模型假设差异，已逐项归因） |
| Case B 毫秒级阀门控制 | 40 ms 阶跃关闭至 20%、90 ms 重开 | 节流比 **0.803**（关闭后流量下降 80.3%）；控制同步误差 **0.0 ms**（事件与 1D 网格严格对齐） |
| Case C 能量通道 | 高压高扩散场、加压环境 | 反向耦合背压抬升 **18.15 kPa**，反向支路真实参与 |
| Case D 亚临界非壅塞流 | 压比落在临界压比与 1 之间 | 流量对照文献等熵亚临界关系，相对误差 **0.107%** |
| 最小可行交换周期 | 交换频率扫描（0.25–4.0 ms） | **1.0 ms**（守恒达标，等于 1D 步长这一紧耦合极限） |
| 精度-效率权衡曲线 | 交换周期 0.5–5.0 ms 五档 | 延迟 vs 界面误差 vs 综合评分，见文档第六节与 bench JSON |

## 快速复现（纯 Python，无需浏览器）

```bash
pip install -r python/requirements.txt

cd python                                 # 内核包在 python/ 下，以下命令均从该目录运行
python run_tests.py                       # 26 项断言（无需 pytest）
python -m fluid_cfd.driver verify         # 完整验证套件 → JSON 到 stdout
python -m fluid_cfd.driver solve '{"case":"a"}'   # 单算例耦合（自定义 payload 见 config.example.json）
```

容器化复现：

```bash
docker build -f docker/cfd.Dockerfile -t cfd-verify .
docker run --rm cfd-verify                          # 默认跑完整验证套件
docker run --rm cfd-verify python -m fluid_cfd.driver verify
```

## 核心机制（摘要）

- **多速率时间协调**：1D 以 `dt1d` 粗步推进，3D 在每交换窗口内走 `dt1d/dt3d` 个子步（默认 8）；`normalized()` 硬校验步长与周期不变量，交换边界必然落在 1D 网格线上
- **正向耦合**：1D 出口质量流量、温度 → 3D 入口动量与焓注入（x0 面中心补丁）
- **反向耦合**：3D 出流面物理导出的平均背压（滞止动压 + 热膨胀 + 投影压力场三项）→ 1D 喷管下游边界，壅塞判据依赖实时反馈
- **守恒审计**：逐窗口 `iface_error = |p_back_used − p_back_3d| / p_ref`；`metrics` 汇总均值/最差
- **单位契约**：接口量全部 SI 基本单位，`units.consistent` 做无量纲一致性检验
- **统一误差口径**：每个量附相对误差公式 + 基准 + 认证断言（`rel_error + basis + certification`）

## 独立参赛声明

本项目为独立参赛作品（中国商飞流体 CFD 命题）。本仓库与 `SOLUTION.md`、`docs/10-流体双向耦合求解器.pdf`（`.md` 同源）共同构成方案交付物；`python/` 目录下的求解内核**自包含**（仅依赖 numpy），可直接独立运行与复现，并提供浏览器内执行的 Web 求解入口（同一内核经 Pyodide 运行），浏览器结果与 CLI 结果逐字节一致。本仓库与其他赛题提交无重复投递关系。

- 仓库：`https://gitee.com/cnt-code/fluid-cfd-coupler`

## 目录结构

```
├── SOLUTION.md                 # 插件方案说明
├── docs/                       # 提交用方案文档（PDF + md 同源）
│   └── 10-流体双向耦合求解器.pdf / .md
├── bench/                      # 实测结果归档
│   └── fluid-cfd-results.json
├── docker/
│   └── cfd.Dockerfile          # CLI 复现容器
└── python/                     # 自包含求解内核
    ├── fluid_cfd/              # 包：units / analytic / network_1d / domain_3d / coupler / verify / driver
    ├── tests/test_coupling.py  # 26 项断言
    ├── benchmarks/bench_coupling.py
    ├── run_tests.py
    ├── config.example.json
    └── requirements.txt        # 仅 numpy
```

## 许可

MIT。详见根目录 `LICENSE`。