HTRI二次开发教程04案例数据模型心智模型——case、panel 与 input/output 的层级版本与事实声明版本锚点当前Xchanger Suite 9.4官方 Power Users 教程标注含 9.0。其余以官方发布说明为准。本文讨论的底层数据模型underlying data models是官方在 Parametric Study Tool 说明中使用的措辞具体对象树的类名/字段名无公开文档底账 U2本文只建立心智模型与命名规范不给出任何未经探测的标识符。文中所有数值均为示例性建模不代表任何标准规定不对应任何真实装置。一句话结论Xchanger Suite 的一个*.htri案例本质是一棵案例(case) → 面板(panel) → 输入/输出字段(field)“的树官方 Parametric Study Tool 明确要求使用者熟悉底层数据模型”正是因为自动化的寻址就是在这棵树上按路径走——先有案例再定位面板最后读写字段。〇、本篇要解决的认知问题Q1官方说的underlying data models到底指什么为什么它是批量自动化的前提Q2一个*.htri案例里到底装了什么为什么输入、输出、图形能共存于一个文件Q3界面上的面板和对象树上的节点是什么关系Q4模式rating/simulation/design如何在数据模型里体现为字段的可写性Q5在还不知道真实字段名的情况下怎么设计一套稳定的字段路径命名规范一、机制解析1.1 底层数据模型为什么被官方反复强调为什么这对你重要这是整个官方自动化理念里最重要的一句话。官方在知识库描述 HTRI Parametric Study Tool 时说它extends the capabilities of HTRI Xchanger Suite using Microsoft Excel and the OLE automation server interface and API紧跟着一句关键的“The tool is intended for users with experience using and knowledge of the underlying data models in Xchanger Suite.”这句话的含义是HTRI 的自动化不是点按钮式的黑箱录制而是基于数据模型的对象化操作。你必须知道这个量属于哪个面板、在哪个模式下可写、它的单位集是什么才能写出正确的自动化。GUI 是数据模型的一个视图Automation Server 是同一个数据模型的另一个视图——两个视图操作的是同一棵对象树。这条推论极有价值你在界面里看到的层级关系案例 → 分组 → 面板 → 字段几乎就是你在对象树里要走过的路径。1.2 案例里装了什么官方 Features 页称“Modern user interface allows multiple case files (containing both text and graphical inputs/outputs) to be open at the same time.”这句话透露两点一个*.htri案例同时含输入、输出与图形——不是输入文件 结果文件两分离而是合一的工程文件Xchanger Suite 支持同时打开多个案例——这对批处理既是机遇可并行装载也是风险容易把 A 案例的输出记到 B 案例名下。官方把*.htri用作 Parametric Study Tool 的template 文件即一份模板案例 一组被改变参数 一批派生案例。这直接给出了批量自动化的标准形态——模板驱动的派生而不是每个案例都从零搭。1.3 界面面板与对象树节点把 Xist 官方的 Getting Started 面板清单拿来对照Explore the Input Summary Panel / Process Conditions Panel / Exchanger Panel / Tube Geometry Panel / Nozzles Panel / Tube Layout Panel / Shells-in-Series Panel / Reboiler Panel / Name…可以画出一棵典型树的骨架案例(case) —— 一个 *.htri 文件 一个案例根 ├── 元信息(meta) # 案例名、单位集、模式 …Input Summary 面板负责展示 ├── 工艺条件(process) # Process Conditions 面板两侧流体、温度、流量、允许压降 ├── 换热器(geometry) │ ├── 壳(exchanger) # Exchanger 面板壳型、壳径、壳程 │ ├── 管(tube_geometry) # Tube Geometry 面板管径、壁厚、管长、管间距 │ ├── 接管(nozzles) # Nozzles 面板进出口接管尺寸与位置 │ ├── 布管(tube_layout) # Tube Layout 面板排布、管程数另有 Tube Layout Drawing 工具 │ └── 串联壳(shells_in_series) ├── 再沸器(reboiler) # Reboiler 面板再沸器专用参数如适用 └── 结果(outputs) ├── summary # 总览结果 ├── detailed # 局部剖面温度/压力/传热系数/热流 … ├── tema_spec # TEMA 规格书 └── graphs # 用户自定义图为什么这对你重要这张图不是装饰——它就是自动化寻址的地图。当第 07 篇里要把壳径改成 900 mm脚本要做的就是沿着case → geometry → exchanger → 壳径字段这条路走当第 09 篇要取总传热系数走的是case → outputs → summary → 该字段。1.4 模式如何体现在数据模型里第 03 篇说过模式决定字段角色。在数据模型层面这件事表现为字段的可写性可写 / 只读 / 约束随模式变化字段示例ratingsimulationdesign热负荷 duty输入已知输出求解输入已知壳径/管长等几何输入已知输入已知输出或约束出口温度可输出/部分输入输入或输出取决于给定项输出反直觉点Xist 官方说它allows specification of known process information (temperature, weight fraction vapor, and/or flow rate) with the program calculating missing information based on energy balance——也就是说同一次运行里程序靠能量平衡去补你留空的量。这意味着可写性不只是二值还有一种你留空、程序算的第三态。自动化里必须显式决定这一轮我到底给哪些量、留空哪些量。1.5 字段路径命名规范在未知真实字段名时既然真实字段名无公开文档U2我们能做的是先建自己的路径命名规范等探测完成后第 05、06 篇再把规范名映射到真实标识符。规范建议经验法则全小写 下划线分层geometry.exchanger.shell_id每段语义明确、避免缩写歧义用tube_geometry不用tg单位不写进字段名写进数据字典的单位列字段叫shell_id单位记mm输出字段前缀统一out.out.summary.overall_u。最佳实践把规范路径 → 本机真实标识符的映射单独存一张表第 06 篇的探测清单业务代码只引用规范路径。这样当 HTRI 升级改了标识符你只改映射表不动业务逻辑。1.6 为什么循环回路是数据模型的天然产物为什么这对你重要理解这一点你才不会把对象树很深当成软件设计得不好。换热器案例的数据模型里天然存在循环引用一个案例可以引用它的面板集合而面板集合的每一项又指回案例一个管束可能引用管子集合而管子又引用管束。这不是设计缺陷而是面向对象模型的双向导航——它让你既能从案例往下找字段也能从字段往上找它属于谁。对自动化的两点影响遍历必须防环第 06 篇的MAX_DEPTH与MAX_CHILDREN不只是性能护栏更是防环护栏。用深度 1 → 2 → 3逐层加深的方式测绘是最稳的防环策略。单向优先业务代码应沿着案例 → 输出这一个方向走自顶向下不要反向从字段去猜父节点——反向导航在不同版本里更不稳定。一条经验法则把数据模型当地图而不是数据库表。表是平的、字段固定地图是分层的、有路径的。你寻址的方式是走路径不是查字段名——这是本系列在自动化寻址上最重要的一次认知切换。二、完整代码与逐行剖析本篇的代码是数据字典工具代码 4-1 用 Python 表达并校验一棵案例树代码 4-2 生成模式—面板—字段数据字典 CSV作为后续探测与自动化的对照表。代码 4-1用数据结构表达案例树并校验# -*- coding: utf-8 -*- case_tree.py —— 把案例抽象成可校验的树 用法python case_tree.py 说明本文件只描述结构不含任何未经探测的真实字段标识符 字段名用规范路径真实标识符在探测清单里映射第 05/06 篇。 fromdataclassesimportdataclass,fielddataclassclassNode:name:str# 规范路径片段kind:str# group / fieldwritable:dictfield(default_factorydict)# 模式 - 可写性unit:strnote:strdefbuild_xist_tree():return{process:[Node(shell_side_inlet_T,field,{rating:True,simulation:True,design:True},C),Node(duty,field,{rating:True,simulation:False,design:True},kW,noterating/design 为输入simulation 为求解输出),Node(shell_side_flow,field,{rating:True,simulation:True,design:True},kg/s,note可留空由能量平衡补算),],geometry.exchanger:[Node(tema_shell_type,field,{rating:True,simulation:True,design:True},-),Node(shell_id,field,{rating:True,simulation:True,design:False},mm,notedesign 模式下为求解输出/约束),],geometry.tube_geometry:[Node(tube_od,field,{rating:True,simulation:True,design:True},mm),Node(tube_length,field,{rating:True,simulation:True,design:False},mm),],outputs.summary:[Node(overall_u,field,{rating:False,simulation:False,design:False},W/(m2·K),note输出字段任何模式下都不应作为输入写入),],}defcheck(tree,moderating):problems[]forgroup,nodesintree.items():forninnodes:ifmodenotinn.writable:problems.append(f{group}.{n.name}未定义模式{mode}的可写性)continue# 输出字段所有模式皆不可写若被当输入使用是常见错误ifn.kindfieldandnotany(n.writable.values()):print(f[只读]{group}.{n.name}—— 输出字段切勿写入)returnproblemsdefmain():treebuild_xist_tree()probscheck(tree,rating)totalsum(len(v)forvintree.values())print(f案例树{len(tree)}个分组{total}个字段示例)ifprobs:print([问题])forpinprobs:print( - p)else:print([OK] 字段可写性定义完整。)if__name____main__:main()逐行剖析Node.writable用字典{模式: 布尔}这是把第 03 篇模式决定字段角色的结论数据结构化。业务代码可以一句node.writable[current_mode]判断该不该写这个字段。输出字段所有模式皆不可写用not any(...)表达并打印警示这是把 a别把输出当输入的坑做成运行期提醒。note字段承载程序会补算留空量这类语义数据结构不只是名字集合还带业务规则。用dataclasses而不是裸 dict字段有单位、有可写性、有备注——这三样在数据字典里缺一不可。关键纪律整个文件里字段名都是规范路径shell_id、overall_u不含任何未经探测的真实标识符——这是铁律 1先探测后编码在数据结构层的体现。代码 4-2生成模式—面板—字段数据字典 CSV# -*- coding: utf-8 -*- gen_datadict.py —— 导出数据字典供人工填写本机真实标识符列 用法python gen_datadict.py 输出datadict.csv列group, field, unit, note, writable_rating, writable_simulation, writable_design, real_identifier 其中 real_identifier 列留空由第 05/06 篇探测后填写。 importcsvfromcase_treeimportbuild_xist_tree# 复用代码 4-1 的树defmain():treebuild_xist_tree()withopen(datadict.csv,w,newline,encodingutf-8-sig)asf:wcsv.writer(f)w.writerow([group,field,unit,note,writable_rating,writable_simulation,writable_design,real_identifier])forgroup,nodesintree.items():forninnodes:w.writerow([group,n.name,n.unit,n.note,n.writable.get(rating,),n.writable.get(simulation,),n.writable.get(design,),,# 待探测填写])print(已写出 datadict.csv请在第 05/06 篇探测后补全 real_identifier 列。)if__name____main__:main()逐行剖析real_identifier列故意留空这是本系列方法学的核心动作——把业务语义与本机真实标识符解耦。一个人填表、一次探测、永久复用。用utf-8-sig写 CSV保证 Excel 双击不乱码第 02、03 篇一路沿用的约定。from case_tree import build_xist_tree数据字典与树定义同源杜绝表里写一套、代码里写另一套。每行三列可写性rating/simulation/design让面板—字段—模式三位一体落到一张可筛选的表上。三、常见报错与排查报错 3-1脚本能连上 Automation Server但找不到某个字段。现象按记忆里的字段名去访问报属性不存在。根因真实对象树标识符无公开文档U2你用的名字很可能是别处抄来的或想当然的。解法先跑第 06 篇的对象树测绘从探测结果里取真实标识符填进datadict.csv的real_identifier列再让业务代码引用规范路径。报错 3-2改了字段但运行结果不变“写了不生效”。现象脚本无异常结果没动。根因该字段在当前模式下不可写如 design 模式写几何、或写了输出字段。解法用Node.writable[mode]先判断对照datadict.csv的 writable 三列。报错 3-3多案例同开时把 A 案例的结果记到了 B 名下。现象批量结果错位。根因官方支持同时打开多个案例若脚本没维护当前活动案例这个上下文就会读错树。解法批量脚本里一个案例一个显式句柄禁止依赖当前活动窗口这种隐式状态第 07 篇的会话管理会落实这一点。报错 3-4把单位当成字段的一部分去寻址。现象字段名里塞了_mm、_kPa跨单位集时取数出错。根因Xist 支持多单位集单位是案例级/显示级属性不是字段名的一部分。解法字段名不带单位单位单独登记Node.unit取数时显式换算。报错 3-5数据字典与代码脱节。现象表里字段名和代码里不一致改一处忘另一处。根因两份定义各写一遍。解法像代码 4-2 那样从同一棵树生成表做到单一事实来源。四、动手练习练习 1复刻案例树打开你第 03 篇建的 Xist 案例在界面上逐个面板走一遍把面板与关键字段填进代码 4-1 的树结构至少覆盖 process、geometry.exchanger、geometry.tube_geometry、outputs.summary 四组。判定树至少含 10 个字段且每个字段都有单位与三模式可写性。练习 2数据字典落盘运行代码 4-2 得到datadict.csv。判定CSV 行数 树的字段数 表头 1 行real_identifier列全为空三列可写性无空值。练习 3模式差异验证在界面上分别切到 rating 与 design观察同一几何字段的可编辑状态差异。判定至少指出 2 个在 design 下不可自由编辑或变成约束/输出的字段并把结论写进datadict.csv的note。五、小结与下一篇预告本篇建立了自动化最重要的心智模型一个案例是一棵树case → panel → field输入、输出与图形共存于一个*.htri官方要求熟悉底层数据模型正是因为自动化寻址就是在这棵树上走路径。我们还把模式—面板—字段三位一体做成可执行的数据结构代码 4-1与可筛选的表代码 4-2并确立了规范路径 ↔ 真实标识符解耦的命名规范。从第 05 篇起我们进入本系列的技术核心HTRI Automation Server 的本机探测。第一篇上讲怎么用注册表、OLE/COM Object Viewer 与 pywin32 MakePy 把这台机器上真实存在的 Automation Server 类型库挖出来——那是real_identifier列唯一的合法来源。本篇认知问题回显FAQQ1官方说的 underlying data models 指什么为什么是批量自动化的前提A指 Xchanger Suite 内部那套案例→面板→输入/输出字段的对象模型。官方在描述 HTRI Parametric Study Tool 时明确它intended for users with experience using and knowledge of the underlying data models in Xchanger Suite。因为 Automation Server 与 GUI 操作的是同一棵对象树自动化的本质就是按路径寻址读写字段不熟悉模型就不知道哪个量属于哪个面板、在哪种模式下可写。Q2一个*.htri案例里装了什么A官方称案例文件containing both text and graphical inputs/outputs即输入、输出与图形共存在一个专有工程文件里不是输入文件 结果文件两分离且软件可同时打开多个案例文件。官方还把*.htri用作 Parametric Study Tool 的 template 文件形成一份模板 一组被改参数 一批派生案例的批量形态。Q3界面上的面板和对象树上的节点是什么关系AGUI 与 Automation Server 是同一数据模型的两个视图。界面里案例 → 分组 → 面板 → 字段的层级基本对应对象树里要走的路径。例如把壳径从 800 mm 改为 900 mm就是沿 case → geometry → exchanger → 壳径字段 走一遍取总传热系数则走 case → outputs → summary → 该字段。Q4模式rating/simulation/design在数据模型里怎么体现A体现为字段的可写性随模式变化如热负荷在 rating/design 是输入、在 simulation 是求解输出几何在 design 下可能变为输出或约束。此外还有第三态——Xist 允许用户只给已知工艺信息温度、气相重量分数、流量由程序按能量平衡补算留空量因此自动化必须显式决定这一轮给哪些量、留空哪些量。Q5还不知道真实字段名时怎么设计字段路径命名规范A采用全小写 下划线分层的规范路径如geometry.exchanger.shell_id单位不写进字段名而单独登记输出字段统一out.前缀。把规范路径 → 本机真实标识符的映射单独存一张表探测清单业务代码只引用规范路径升级改动时只改映射不动逻辑。