企业官网建设流程全解析

HTRI二次开发教程（11）：板式换热器自动化——Xphe 案例模型与模块间数据传递

版本与事实声明

• 版本锚点：当前Xchanger Suite 9.4；官方 Xchanger Suite Educational 版含 Xace/Xist/Xphe 三模块。
• 官方 Xphe 描述：“Rate, simulate, and design plate-and-frame exchangers usinguser-defined plate types or plates selected from an internal manufacturers’ databank. Xphe contains aport maldistribution modelthat calculates the flow through each plate channel.”
• 示例代码中所有标识符为占位符；数值均为示例性建模，不代表任何标准规定，不对应任何真实装置。

一句话结论：Xphe 与 Xist 的数据模型差异集中在三点——板型来源（用户自定义 vs 内部厂商库）、端口分布模型（计算每个板通道流量）、通道几何（板片波纹与板对数）；把管壳式的扫描脚本迁到板式，关键不是改模块名，而是按板式的变量层级裁剪扫描维度，并利用官方的"模块间数据传递"能力在 Xist/Xace/Xphe 间复用案例数据。

〇、本篇要解决的认知问题

• Q1：Xphe 与 Xist 的数据模型差在哪里，为什么脚本不能"改个模块名就复用"？
• Q2：Xphe 的板型从哪来？"内部厂商库"与"用户自定义"对自动化意味着什么？
• Q3：端口分布模型（port maldistribution model）在案例里是什么，取数时要不要取？
• Q4：官方的"模块间数据传递"是什么能力，怎么用于跨模块工作流？
• Q5：板式扫描的变量该怎么裁剪，避免维度爆炸？

一、机制解析

1.1 Xphe 与 Xist 的数据模型差异

官方组件页对两者的定位不同：

• Xist：管壳式，“supports all standard TEMA exchanger types”，几何维度是壳径/管径/管长/管间距/折流板/管程数/壳型等；
• Xphe：板式，“using user-defined plate types or plates selected from an internal manufacturers’ databank”，几何维度是板型、板片数、通道排列、端口尺寸等。

为什么脚本不能"改个模块名就复用"：两者的字段树结构不同——geometry.exchanger.shell_id在板式案例里不存在（没有"壳"），而板式特有的"板对数（number of plates）""板片波纹角"在管壳式里也不存在。模块名的更换必须伴随数据模型的重建（回到第 04 篇的数据字典方法）。

1.2 板型来源：厂商库 vs 用户自定义

官方明确 Xphe 可用"用户自定义板型"或"从内部厂商板型库中选择板片"。这对自动化的含义：

• 厂商库：板型是"预置对象"，你需要先枚举可用板型（第 06 篇的测绘能力在此复用——枚举库节点），再选择；
• 用户自定义：板型是"输入参数集合"（波纹几何、板片尺寸、材料等），需要逐字段写入。

经验法则：优先用厂商库（数据可靠、参数齐），只在自家专有板型时才用自定义。自动化脚本应对两种来源都留路径：一个"选择器"（按名/按属性选库中板型）、一个"构造器"（写自定义板型参数）。

1.3 端口分布模型

官方：“Xphe contains a port maldistribution model that calculates the flow through each plate channel.” 这意味着 Xphe 的结果里有一类**“每个板通道的流量分布”**——它不属于 summary 标量，而属于 detailed 剖面类。

取数含义：端口分布是多值分布（每个通道一个值），适合存成section="port_distribution", parameter="channel_flow", position=序号, value=...的长表。它常被忽略，但对板式换热器的流量分配均匀性判断很关键。

1.4 模块间数据传递

官方 Xist 页：“As a module in Xchanger Suite,Xist lets you quickly transfer applicable case data to other components like Xvib or Xace.”；Xace 页：“Xace lets you quickly transfer applicable case data to other components like Xist or Xhpe.”；Xphe 页：“Xphe lets you quickly transfer applicable case data to other components like Xist or Xace.”

能力解读：官方描述的是一种"在模块间传递适用案例数据"的工作流——同一股流体/工况可以在不同模块间复用，不必重复录入。对自动化：

• 正面价值：跨模块方案比选（同一工况用管壳式/板式/空冷分别评估）可以共享输入；
• 边界：传递的是"适用数据"（applicable case data），并非"整个案例"——不可适用字段不会传递，因此跨模块脚本必须做字段级核对，不能假定"传了就全有"。

反直觉点：很多人以为"数据传递 = 案例复制"。实际是"适用子集的传递"。跨模块工作流里，核对传递后哪些字段为空是必须的一步（见代码 11-2）。

1.5 板式扫描的变量裁剪

板式几何维度多（板型 + 板对数 + 通道数 + 端口），全因子极易爆炸。裁剪策略：

1. 先固定板型（选定厂商库中一款），只扫工况与板对数；
2. 板对数取"离散档位"（如 20/30/40 片），不做连续扫描；
3. 端口尺寸作为约束而非变量（先满足可制造性）；
4. 报告只需overall_u / 两侧压降 / 端口分布均匀性三类目标。

1.6 板式自动化的三条纪律

纪律一：模块即模型，换模块要重建字段树。管壳式的"壳径/管长/折流板"在板式里根本不存在，板式的"板型/板对数/板片波纹"在管壳式里也不存在。"改个模块名复用脚本"是板式自动化里最常见、代价最高的错误——第 04 篇的数据字典方法在这里必须重走一遍。

纪律二：厂商库板型"先枚举、后选择"，不许自造名字。官方明确板型可来自"内部厂商板型库"。库里的板型是预置对象，必须先枚举再按名选择；自造一个板型名不会帮你"创建板型"，只会让你拿到错误结果或直接失败。这条与铁律 1（探测优先）同源。

纪律三：端口分布要取、要存、要能算均匀性。端口分布模型算"每个板通道的流量"，是板式流量分配均匀性的直接证据。只取 summary 标量、不取端口分布的板式自动化，是不完整的——均匀性差往往是板式性能不达标的主因之一。

一条经验法则：板式的"变量裁剪"比"变量扫描"更重要。板片几何细碎（波纹角、板片厚度、端口尺寸、通道排列），若不做裁剪，组合数会以不可思议的速度膨胀。先固定板型与端口尺寸（可制造性约束），只扫工况与板对数，是工程上最务实的一条路。

二、完整代码与逐行剖析

代码 11-1：Xphe 案例契约与变量裁剪

# -*- coding: utf-8 -*-""" xphe_contract.py —— Xphe 板式案例契约（板型来源 + 变量裁剪） 用法：python xphe_contract.py 输出：xphe_contract.json 说明：示例性建模，不代表任何标准规定，不对应任何真实装置。 """importjsondefmake_contract(plate_source,selected_plate=None,custom_params=None):"""plate_source: 'vendor_db' 用厂商库；'custom' 用用户自定义板型。"""ifplate_source=="vendor_db":plate={"source":"vendor_db","selected_plate_name":selected_plate,# 先做枚举再填"enum_field":"<板型枚举节点（探测所得）>"}elifplate_source=="custom":plate={"source":"custom","params":custom_paramsor{}}else:raiseValueError("plate_source 必须是 vendor_db 或 custom")return{"meta":{"module":"Xphe","mode":"rating","template":"xphe_template.htri","disclaimer":"示例性建模，不代表任何标准规定，不对应任何真实装置",},"plate":plate,# 变量裁剪：板对数用离散档位，不做连续扫描"variables":{"geometry.plates.number_of_plates":[20,30,40],# 离散档位"process.shell_side_flow":[8.0,10.0,12.0],# kg/s},"fixed":{"geometry.connections.port_size":"<端口尺寸: 先满足可制造性>",},"targets":{"outputs.summary.overall_u":{"unit":"W/(m2·K)"},"outputs.summary.dp_hot":{"unit":"kPa"},"outputs.summary.dp_cold":{"unit":"kPa"},# 端口分布作为剖面类目标，单独标记"outputs.port_distribution.channel_flow":{"unit":"kg/s","kind":"profile"},},}defcheck(contract):probs=[]ifcontract["plate"]["source"]=="vendor_db"and\notcontract["plate"].get("selected_plate_name"):probs.append("选用厂商库板型时，selected_plate_name 不能为空（须先枚举）")forpath,valsincontract["variables"].items():iflen(vals)>5:probs.append(f"{path}取值档位过多（{len(vals)}），易致维度爆炸")returnprobsif__name__=="__main__":c=make_contract("vendor_db",selected_plate="<枚举后填板型名>")probs=check(c)withopen("xphe_contract.json","w",encoding="utf-8")asf:json.dump(c,f,ensure_ascii=False,indent=2)print("已写出 xphe_contract.json")ifprobs:print("[校验问题]")forpinprobs:print(" - "+p)else:print("[OK] 契约通过校验。")

逐行剖析：

• make_contract用plate_source分支把"厂商库/自定义"两条路显式建模：不假设板型从哪来，而是让契约声明来源，脚本据此走枚举或构造。
• 厂商库路径强制要求selected_plate_name非空：先枚举、后选择——把"库板型必须来自枚举结果"做成校验规则（铁律 1 的又一次落地）。
• variables用离散档位（20/30/40 片）：反直觉但关键——板对数连续扫描意义不大（实际制造是整数板片），离散档位既符合工程又不爆炸。
• targets里给端口分布加了"kind": "profile"：把"标量目标"与"剖面目标"分开标记，指导第 09 篇的取数分流（标量入宽表、剖面入长表）。
• check检查"档位数 > 5"：把 1.5 节的裁剪经验做成可执行护栏。
• 端口尺寸放进fixed而非variables：先满足可制造性再谈优化，这是板式设计的经验法则。

代码 11-2：跨模块数据传递后的字段核对

# -*- coding: utf-8 -*-""" xfer_check.py —— 模块间数据传递后的字段级核对 用法：python xfer_check.py 【重要】标识符须替换为探测所得真实值。 要点：官方描述的是"传递适用案例数据（applicable case data）"， 不是整案例复制，因此必须逐字段核对哪些没传过来。 """fromdrive_caseimportsession PROGID="<HTRIAutomationServer.ProgID（本机枚举所得）>"OP_LOAD="<打开案例的方法（探测所得）>"OP_XFER="<模块间数据传递的方法（探测所得）>"# 期望"传递后应有"的字段（规范路径 -> 真实标识符占位）EXPECT={"process.shell_side_inlet_T":"<真实标识符>","process.shell_side_flow":"<真实标识符>","process.duty":"<真实标识符>","geometry.plates.number_of_plates":"<真实标识符>",# 板式特有，通常不来自 Xist}defprobe_present(case,ident):try:node=caseforpartinident.split("."):node=getattr(node,part)returnTrueexceptException:# noqa: BLE001returnFalsedefmain():src="<源案例路径（如 Xist 案例）>"dst="<目标案例路径（如 Xphe 案例）>"withsession(PROGID,300)as(app,_start):src_case=getattr(app,OP_LOAD)(src)dst_case=getattr(app,OP_LOAD)(dst)getattr(src_case,OP_XFER)(dst_case)# 触发传递（形式以探测为准）missing=[]fornorm,identinEXPECT.items():if"<"inident:missing.append((norm,"标识符未探测确认"))continueifnotprobe_present(dst_case,ident):missing.append((norm,"传递后缺失"))print("跨模块传递核对结果：")ifmissing:fornorm,whyinmissing:print(f" [缺]{norm}:{why}")print("提示：'适用数据'才会传递，板式特有字段通常需在目标案例单独设置。")else:print(" [OK] 全部期望字段均存在。")if__name__=="__main__":main()

逐行剖析：

• EXPECT里特意放了一个板式特有字段（板对数）：预期它"传递后缺失"，用来演示"适用数据 ≠ 全部字段"这一官方边界。
• probe_present用 try/except 判断字段是否存在：跨模块传递后，"字段在不在"是首要问题，比"值对不对"更基础。
• 未探测确认的标识符记为"标识符未探测确认"而非静默跳过：核对脚本里，未知本身就是要报出来的结果。
• 打印提示明确"板式特有字段通常需单独设置"：把 1.4 节的边界结论写进脚本输出。
• 传递动作OP_XFER是占位符：官方告诉我们"可以传"，具体方法名要探测。

三、常见报错与排查

报错 3-1：把 Xist 的扫描脚本直接换模块名跑板式，报字段不存在。
现象：getattr抛属性不存在的错误。根因：Xphe 数据模型与 Xist 不同（没有"壳"，有"板对数/板型"）。解法：重建数据字典（第 04 篇方法），按板式字段树重写字段路径；模块名更换必须伴随数据模型重建。

报错 3-2：用厂商库板型但selected_plate_name为空。
现象：契约校验报错或运行失败。根因：没先枚举库中板型就填了名字（或没填）。解法：先按第 06 篇方法枚举板型库节点，取真实板型名再填；绝不自造板型名。

报错 3-3：跨模块传递后目标案例某些字段为空。
现象：传递"成功"但结果缺东西。根因：官方传递的是"applicable case data"（适用数据），板式特有字段不会从管壳式传过来。解法：用xfer_check.py逐字段核对；对缺失的模块特有字段在目标案例单独设置。

报错 3-4：板式扫描案例数爆炸。
现象：矩阵巨大跑不完。根因：板型 × 板对数 × 工况做全因子。解法：先固定板型，板对数取离散档位（≤5 档），端口尺寸作约束；只对少数关键变量做组合。

报错 3-5：端口分布结果取不出来或取成单个标量。
现象：想取"每个通道流量"却只拿到一个数。根因：端口分布是剖面类结果（每通道一个值），被当作标量读取。解法：按kind="profile"走剖面取数（第 09 篇 detailed 处理法），存成section="port_distribution"的长表。

四、动手练习

• 练习 1（板式契约）：用代码 11-1 生成一份 Xphe 契约。判定：xphe_contract.json存在；plate.source为vendor_db或custom；variables中每个变量档位数 ≤5。
• 练习 2（板型枚举）：对 Xphe 案例用第 06 篇的测绘方法枚举板型库节点。判定：得到至少 1 个候选板型名；把它填进契约的selected_plate_name后check通过。
• 练习 3（跨模块核对）：从 Xist 案例向 Xphe 案例做一次数据传递，运行代码 11-2。判定：输出中至少一项被标[缺]（板式特有字段），且你能解释"为什么它是适用的边界"。
• 练习 4（端口分布取数）：取一个案例的端口分布结果，存成长表。判定：长表section="port_distribution"、position覆盖所有板通道；通道流量之和与总流量相对偏差 < 2%。

五、小结与下一篇预告

本篇把自动化从管壳式拓展到板式：Xphe 的数据模型差异（板型来源、端口分布、通道几何）要求重建字段树而非复用管壳式脚本；厂商库板型必须"先枚举后选择"；端口分布是剖面类结果需专门取数；官方"模块间数据传递"传的是适用数据子集，跨模块工作流必须做字段级核对。变量裁剪上，板对数用离散档位、端口尺寸作约束。

第 12 篇《空冷器与振动：Xace 与 Xvib》：我们处理另外两个关键模块——空冷器 Xace（厂商风机选型、流量/温度分布不均、冗余风扇 TT-27）与严格振动分析 Xvib（有限元、fluidelastic instability 与 vortex shedding、rho-V² 判据），并给出"空冷批量校核 + 振动联合取数"的自动化骨架。

本篇认知问题回显（FAQ）

Q1：Xphe 与 Xist 的数据模型差在哪里，脚本能直接复用吗？
A：Xist 是管壳式、几何维度为壳径/管径/管长/管间距/折流板/管程/壳型（支持所有标准 TEMA 壳型）；Xphe 是板式、几何维度为板型/板对数/通道排列/端口尺寸，且含端口分布模型。两者字段树不同，geometry.exchanger.shell_id在板式里不存在。因此不能改个模块名就复用，必须按第 04 篇方法重建数据字典与字段路径。

Q2：Xphe 的板型从哪来，对自动化意味着什么？
A：官方称 Xphe 使用"user-defined plate types or plates selected from an internal manufacturers’ databank"，即用户自定义板型或从内部厂商板型库选择。对自动化：厂商库板型需先枚举库节点再选择（“先枚举后选择”），用户自定义则逐字段写入参数；经验法则是优先用厂商库，仅专有板型才自定义。脚本应对两种来源都留路径。

Q3：端口分布模型是什么，取数时要不要取？
A：官方称 Xphe 含 port maldistribution model，计算流经每个板通道的流量。它是剖面类结果（每通道一个值）而非 summary 标量，取数时应按section="port_distribution", parameter="channel_flow", position=通道序号, value=...存成长表，并可用"通道流量之和与总流量的偏差"衡量分配均匀性。

Q4：官方的"模块间数据传递"是什么，怎么用？
A：官方称 Xist/Xace/Xphe 各自可把"applicable case data"（适用案例数据）传递给其它组件（如 Xist→Xvib/Xace、Xace→Xist/Xhpe）。它适合跨模块方案比选（同工况用管壳式/板式/空冷分别评估）时共享输入。但传的是"适用子集"而非整案例，因此跨模块脚本必须做字段级核对，模块特有字段（如板式的板对数）通常不会传过来，需在目标案例单独设置。

Q5：板式扫描的变量该怎么裁剪？
A：四条策略：先固定板型（选定厂商库一款），只扫工况与板对数；板对数取离散档位（如 20/30/40 片，不做连续扫描）；端口尺寸作为可制造性约束而非优化变量；目标只取整体传热系数、两侧压降与端口分布均匀性三类。同时校验"每个变量档位数 ≤5"，避免维度爆炸。