heatsink-forced-mlp 是 PINNeAPPle 模型库（Model Zoo）中的一款散热器物理代理模型（MLP Surrogate）：输入风速、鳍片几何、材料导热系数等 12 个参数，一秒内即可预测导热鳍片散热器的基座对空气热阻（r_base_k_w）与风道压降（pressure_drop_pa），并给出 95% 置信区间上界。它用 6000 次 HeatSink Sizer 物理引擎求解训练而成，平均误差仅 0.71%，让早期散热方案筛选从"等 CFD 跑几小时"变成"一次前向传播"。

什么是 heatsink-forced-mlp 散热器代理模型？

传统做法里，评估一块散热器（plate-fin heat sink）在 ducted forced convection（风道强制对流）下的散热性能，通常需要 CFD 仿真或反复调用物理引擎，单次评估耗时数分钟到数小时，做几百种几何扫描时几乎不可行。

heatsink-forced-mlp 的思路是：先把物理引擎跑 6000 次，训练一个小型神经网络（bench_mlp架构，4 层 × 128 神经元，SiLU 激活）去逼近引擎的输出。之后：

• 🚀推理极快：一次前向传播毫秒级完成，适合参数扫描和多方案比选；
• ⚖️物理打底：引擎基于 Teertstra/Yovanovich & Culham（2000）复合平行板 Nusselt 数、3-D 有限体积基座导热（扩散热阻）、发展流摩擦 + 进出口损失，模型继承这些物理规律；
• 📊误差透明：平均误差 < 1%（相对引擎），且带split-conformal 95% 置信上界，告诉你结果"最多可能差多少"。

模型卡与完整验证报告见 model_card.json，一个可运行的输入/输出示例见 example.json。

输入输出速览：12 个参数预测热阻与压降

输入：几何、材料与工况共 12 项

输出：3 个可直接用于决策的量

有了热阻和功耗，芯片结温估算一步到位：T_j ≈ T_ambient + power × R；压降则直接对应风扇选型。

精度验证：0.71% 平均误差的 900 项独立测试

模型在 900 个**留出（held-out）**设计上与物理引擎逐一对比，结果如下（完整指标见 model_card.json）：

更关键的是物理一致性检验：22/22 项 applicable 检查全部通过，信任报告结论为APPROVED（得分 1.00），包括：

• 📉 风速增大 → 热阻只降不升（单调性，违例率 0）；
• 📈 压降随风速增大而增大（单调性，违例率 0）；
• 🔩 导热系数更高的材料 → 热阻不会升高；
• ✅ 热源更大 → 热扩散更好、热阻更低；
• 🧮 热阻与压降恒为正（热力学第二定律）。

引擎本身也经过了独立方法交叉验证：Lee 扩散热阻（1–5%）、Stephan 发展流 Nusselt + e-NTU（0–5%）、完全发展流摩阻（2–4%）、有限体积网格收敛性（< 2%）。

有效范围与已知局限：预测前必读

代理模型只在训练过的参数域内可靠，heatsink-forced-mlp 的有效范围：

流动 regime 限定为ducted（风道内、无旁通）空气层流/发展流强制对流。超出范围时predict会主动发出警告。

三条已知局限，建议牢记：

1. 旁通气流会骗人：真实散热器若有 bypass（气流绕开鳍片），实际通过鳍片的气流会损失 20–50%，请先修正有效风速再预测；
2. ±15% 是关联式的固有精度：模型自身误差（平均 < 1%）是相对物理引擎而言的，对流关联式本身约有 ±15% 的精度，不要对结果期望"实测级"精度；
3. 它是筛选工具：用它在几百个方案里快速圈定候选，最终选型建议用物理引擎复核。

快速上手：3 行代码完成散热器热阻预测

安装 PINNeAPPle 后即可加载模型（权重文件会按 SHA-256 校验，确保你拿到的模型与发布版完全一致）：

pip install pinneapple

import pinneapple as pp model = pp.zoo.load("heatsink_forced_mlp") # 权重 SHA-256 校验通过 inputs = { "base_width_mm": 44.7278, "base_depth_mm": 138.196, "base_thickness_mm": 3.54108, "n_fins": 15.0, "fin_thickness_mm": 0.816, "fin_height_mm": 15.009, "k_w_mk": 183.817, "source_width_mm": 13.568, "source_depth_mm": 21.694, "t_ambient_c": 27.77, "air_velocity_m_s": 4.20, "power_w": 297.7, } out = model.predict(inputs) # 超出有效范围会警告 # r_base_k_w ≈ 0.883 K/W, pressure_drop_pa ≈ 66.2 Pa, r_base_upper95_k_w ≈ 0.901 K/W

上面示例的输入输出与信任判定完整保存在 example.json（模型输出与引擎参考值 0.8744 K/W、65.44 Pa 相差不足 1%）。

此外还提供了：

• ONNX 部署：model.onnx（opset 17）把预处理/归一化都编进了图内，输入(n, 12)的 12 个物理量，输出上述 3 个结果，与 PyTorch 路径最大差异 1.8e-06。注意 ONNX 图内不含有效范围与物理检查，调用方需自行检查；
• 逐查询信任检查：pp.zoo.query_checks(model, inputs)可对每次查询给出范围/物理判定；
• 一键复现指标：pp.zoo.evaluate("heatsink_forced_mlp")会在存留参考上重新计算模型卡的全部指标。

架构与归一化参数（4×128 SiLU，目标为log R与log dP，13 维特征）见 config.json。

仓库文件清单：权重、配置与模型卡一览

常见问题 FAQ

问：预测误差只有 0.71%，可以直接当实测值用吗？不能。0.71% 是相对 HeatSink Sizer 物理引擎的误差；引擎背后是对流关联式，本身约 ±15% 精度。把它当作快速、可复现、带不确定度上界的筛选工具。

问：我的散热器有旁通气流，能直接预测吗？不建议。旁通会让实际穿鳍风量损失 20–50%，先用风道修正估算有效风速，再代入预测。

问：输入超出有效范围会怎样？predict会返回警告（out-of-range），结果可信度下降。建议把设计拉回有效域内，或用物理引擎做外推评估。

问：它能替代 CFD 吗？对"几百个方案比谁热阻低、谁压降小"这类比选问题，它是极快的替代方案；对复杂非对称结构、自然对流、混合工况等超出 ducted 强制对流假设的场景，仍需 CFD 或实验。

总结：什么时候该用 heatsink-forced-mlp？

✅ 适合：风道强制对流下的导热鳍片散热器，几何扫描、多方案热阻/压降比选、芯片结温快速估算、给结果附上 95% 置信上界。 ❌ 不适合：旁通/自然对流等非 ducted 工况、超出有效范围的大外推、以及需要实测级精度的最终验收。

一句话工作流：用 heatsink-forced-mlp 一秒钟筛掉 90% 的坏设计，再对剩下 10% 跑引擎或 CFD 精算——这就是代理模型给散热设计带来的杠杆。