HTRI二次开发教程01HTRI 全景——换热器热力设计基准软件与二次开发的四条真实通道版本与事实声明本系列版本锚点全部取自系列底账登记表当前版本Xchanger Suite 9.4官方 “What’s New in Xchanger Suite® 9.4” 文章日期 2026-02-09历史锚点 9.3 / 9.1 / 9.0 / 8.2 / 8 / 7.0。当前版本号一律以官方发布说明为准正文不写死。凡涉及 HTRI Automation ServerProgID、类名、方法名一律写作ProgID本机枚举所得等占位符必须先在本机完成注册表与类型库探测后再替换见第 05、06 篇本系列不编造任何 API 字符串。文中出现的任何工艺/几何/传热数值均为示例性建模不代表任何标准规定不对应任何真实装置数据。商业许可、价格与下载渠道信息以 HTRI 官方渠道为准。所有事实性表述可回溯至同目录《_调研素材参考.md》下称底账登记条目HTRI 为会员制闭源软件官方对象模型文档位于会员门户内公开渠道无法确证之处均显式说明。一句话结论HTRI Xchanger Suite 官方提供的唯一程序化 API 是 HTRI Automation Server——一个随软件安装的 OLE 自动化服务器官方演示用 .NET/C# 与 Excel 完成打开案例→改输入→运行→取输出→保存五动作而其 ProgID 与对象模型无公开文档因此一切二次开发的起点不是写代码而是先在本机枚举类型库、后编码。〇、本篇要解决的认知问题开始之前先带着这五个问题读完全篇——文末 FAQ 会逐一自包含地回答。Q1HTRI 到底是软件公司还是研究机构这个身份如何决定它的软件交付与许可方式Q2Xchanger Suite 到底有哪些模块加热炉模块叫 Xjoule这句话对不对Q3Xist 的 rating、simulation、design 三种模式分别是什么意思为什么自动化脚本必须先想清楚自己在跑哪种模式Q4HTRI 的官方二次开发 API 叫什么它的技术形态是什么官方用什么语言演示Q5把 Xchanger Suite 接进自动化流程一共有哪几条真实通道各自的能力与风险是什么一、机制解析1.1 身份先于能力HTRI 是一个研究联合体为什么这对你重要你调用不了的接口往往不是因为技术封死了而是因为产品的商业模式不允许它公开——先搞清楚这一点你会少走很多到处找 HTRI API 文档的弯路。HTRI 的全称是 Heat Transfer Research, Inc.官方自我定位为一家研究联合体research consortium在德克萨斯州 Navasota 设有 Research Technology CenterRTC。官方原话是For six decades, HTRI has been the recognized leader in process heat transfer and heat exchanger technology其产品与服务覆盖 60 多个国家、1,500 家以上会员单位member sites。这套会员制直接决定了三件事也是本系列的三个前提软件是会员权益的一部分不是货架商品——官网不公开报价需联系销售因此正文一律以 HTRI 官方渠道为准。文档分层Design Manual、400 余份研究报告、软件用户文档都放在会员门户内。我们抓取https://www.htri.net/software-documentation时返回的正是You do not have access to view this page——这不是网络问题是权限墙。技术支持的边界会员可提交技术咨询官方承诺三个工作日内响应。这决定了当你遇到未被公开文档覆盖的 Automation Server 细节时最靠谱的文档其实是官方技术支持而不是搜索引擎。1.2 模块矩阵二次开发能触达的业务词汇表Xchanger Suite 不是一个程序而是一组模块的集合。官方组件页列出的清单就是自动化能操作的对象词汇表规范名定位官方原文要点Xace空冷器与经济器air coolers and economizers含自然通风与强制通风、厂商风机选型、流量/温度分布不均模拟Xist管壳式换热器shell-and-tube支持所有标准 TEMA 壳型含 kettle、发夹、热虹吸、回流冷凝器、降膜蒸发器集成振动计算与布管工具Xhpe发夹式换热器hairpinXjpe套管式换热器jacketed-pipeXpfe板翅式换热器plate-fin多股流轴向/错流增量模型Xphe板式换热器plate-and-frame可用自定义板型或内部厂商板型库含端口分布模型Xspe螺旋板式换热器spiral plate单相顺/逆流螺旋流Type IXvib严格振动分析rigorous vibration analysis基于有限元算法考虑 fluidelastic instability 与 vortex sheddingXfh加热炉fired heaters圆柱形与箱式Hottel zoning 法Xfh UltraHTRI 新版通用加热炉建模软件名称纠偏必读不少资料把 HTRI 的加热炉模块写成Xjoule这是错的。HTRI 官方组件名单里没有 Xjoule加热炉模块是Xfh与Xfh Ultra。本系列一律写作 Xfh你在代码注释里写成 Xjoule 不会报错但会在同行面前暴露对产品的生疏。除核心组件外官方还把一组可独立许可的产品列入同一生态SmartPM管壳式换热器网络性能监测与预测性维护可Link Xist .htri files、连 OSIsoft PI System、XSimOp ShellTube流程模拟器内的 HTRI 管壳式单元操作已集成进 Honeywell UniSim Design Suite 与 KBC Petro-SIM、Exchanger Optimizer设计成本评估、Edgeview性能趋势分析并行运行 Xist 案例more than eight times faster、Xchanger Suite Educational教育版含 Xace/Xist/Xphe。1.3 三种计算模式自动化的意图必须先声明Xist 官方页面明确列出三种模式modesrating校核已知热负荷duty与几何求能否满足simulation模拟几何已知、热负荷未知求实际性能design设计热负荷已知、几何未知让程序反算几何。为什么这对你重要因为模式决定了哪些字段可写、哪些字段是程序输出。在 rating 模式下你写几何和 duty、读性能在 design 模式下你写约束、读几何。自动化脚本若把设计字段当作输入去写轻则被忽略重则该次运行直接失败。第 04 篇的对象模型篇会把这条规则落实到面板字段路径上。1.4 唯一官方 APIHTRI Automation Server官方 TechTip 的原话是“HTRI Xchanger Suite® provides an application programming interface (API) called theHTRI Automation Server. The HTRI Automation Server is easily accessed by external applications and may be used to access data from Xchanger Suite files and to run Xchanger Suite calculations.”官方给出的四类用途把 Xchanger Suite 数据集成进其它软件与工具程序化批量运行大量案例以生成计算数据表对计算结果做后处理完成界面里做不到的其它任务。技术形态上它是随 Xchanger Suite 安装的OLE 自动化服务器OLE automation server。官方 2014 年的 TechTip 演示用Visual Studio 2013 构建 .NETC#应用完成五个基本动作loading an existing case打开已有案例、changing input data in a case改输入、running a case运行、retrieving output data from a case取输出、saving a case保存。官方同时指出该主题面向熟悉 Visual Studio 与 C#、希望把 Xchanger Suite 集成进自有应用的工程师或软件开发者。官方还提供两个现成范例佐证 OLE 通道的可用性HTRI Parametric Study Tool官方知识库描述为extends the capabilities of HTRI Xchanger Suite usingMicrosoft Exceland theOLE automation server interface and APIthat is installed with Xchanger Suite能基于模板*.htri文件在系列中运行大量案例、改变你选择的参数用于研究灵敏度。官方特别提醒它intended for users with experience using and knowledge of the underlying data models in Xchanger Suite。第三方厂商 RCSWin 文档提到它与 HTRI 有双向接口走 automation server——旁证。关键不确定性必须诚实交代Automation Server 的 ProgID、类名、方法签名没有公开文档。我们尝试检索具体 ProgID 字符串公开渠道零命中官方软件文档页需要登录。因此本系列的方法学是铁律 1先探测、后编码——用注册表 HKCR、OLE/COM Object Viewer、pywin32 MakePy 在本机枚举类型库探测结果才是唯一合法的编码依据第 05、06 篇实操。1.5 四条真实通道与决策表把上面所有能力接出来官方可确证的数据通道归为四条通道官方证据能做什么主要风险适合场景Automation ServerOLE[A] 官方 TechTip 知识库批量改输入、驱动运行、取输出、保存官方演示为 .NET/C# 与 Excel OLEProgID/对象模型无公开文档底账 U1/U2桌面 OLE 会挂死、残留进程无人值守批处理、参数扫描、平台后台报表与文件导出[A] Xist/Xphe 页spreadsheet-style reports 可打印或导出 Excel、TEMA specification sheet、2D/3D drawings结构化取数、归档、审计留痕*.dbo 供机械设计软件导入版式随版本漂移解析脚本要容错.htri专有不可直接解析一切链路的兜底与对账流程模拟器与 CAPE-OPEN 集成[A] Features 页列process simulators与CAPE-OPEN compliant applications[A] Xist 页Can be embedded as a unit operation in any process simulator supporting CAPE-OPEN在流程模拟器里直接算换热器导入 HTFS/UniSim/Aspen EDR 文件直连机制细节未公开底账 U10依赖模拟器与 HTRI 双方许可流程-换热联合模拟、装置级物性一致Excel 自定义应用面[A] Features 页user-written applications in Microsoft® Excel® and other programming languages工艺人员人机协同的分析工作台、周期性报表工作簿与模型易脱钩需本机启用/探测报表交付、轻量批处理选择逻辑经验法则能走报表/Excel 面的不写 OLE必须批量无人值守的才上 Automation Server无论走哪条导出通道永远保留做审计与对账。二、完整代码与逐行剖析本篇的代码任务是把自动化工位搭起来第一段 Python 自检脚本验证 Python 侧 OLE/数据工具链不触碰 HTRI 本体任何机器可直接运行第二段给出最基础的 Windows 目录盘点脚本为第 02 篇的工程文件盘点打底。代码 2-1二次开发环境自检Python可直接运行# -*- coding: utf-8 -*- check_env.py —— HTRI 二次开发环境自检 只检查 Python 自动化栈是否就绪不触碰 HTRI其 OLE 足迹检查在第 02、05 篇。 运行python check_env.py importimportlibimportsys# (import 模块名, pip 安装名, 用途) —— 四个库都是公开事实PyPI 可查REQUIRED[(win32com.client,pywin32,OLE 客户端第 05/06/07 篇探测与自动化),(pandas,pandas,结果表清洗与长表规范化第 09/10 篇),(openpyxl,openpyxl,读写 xlsx报表导出件解析第 09 篇),(matplotlib,matplotlib,分布图与报表图形第 17/19 篇),]defmain():print(fPython:{sys.version.split()[0]}({sys.executable}))missing[]formod_name,pip_name,purposeinREQUIRED:try:modimportlib.import_module(mod_name)vergetattr(mod,__version__,(无 __version__属正常))print(f[OK]{mod_name:16}{ver:16}——{purpose})exceptImportError:missing.append(pip_name)print(f[MISS]{mod_name:16}未安装 —— 请: pip install{pip_name})ifmissing:print(\n安装命令: pip install .join(missing))print(pywin32 若装完仍报错再执行其官方后安装脚本)print(f python {sys.prefix}\\Scripts\\pywin32_postinstall.py -install)sys.exit(1)print(\n全部就绪。下一步第 02 篇盘点本机 HTRI 安装与工程文件。)if__name____main__:main()逐行剖析import importlib/import sys只用标准库完成探测避免自检脚本自身依赖未装好的包sys.executable打印当前解释器路径——多版本 Python 共存时先确认你在用哪个 Python这是win32com报找不到模块时的第一排查点。REQUIRED三元组把import 模块名 / pip 安装名 / 用途分开记因为win32com.client的 import 名与pywin32的安装名不一致新手最常在这里踩坑。getattr(mod, __version__, ...)pywin32 的部分子模块没有__version__用默认值兜底而不是让脚本崩——检查工具的脚本比业务脚本更要抗造。sys.exit(1)给非零退出码使脚本可直接被计划任务/CI 当作环境门禁使用第 19、20 篇的前置检查。反直觉默认值提醒pywin32在 64 位 Python 下安装后某些机器仍需手动跑pywin32_postinstall.py才能让win32com的 COM 注册生效——这一步没有出现在pip的成功输出里。代码 2-2Windows 目录盘点骨架Python 标准库可直接运行# -*- coding: utf-8 -*- scan_dirs.py —— 盘点 HTRI 可能落地的目录纯标准库零依赖 用法python scan_dirs.py C:\\Program Files\\HTRI 只负责发现文件不解析内容内容解析属第 02、09 篇。 importosimportsysfromcollectionsimportCounterdefscan(root):返回 (文件数, 扩展名计数, 最大的 10 个文件)ext_counterCounter()files[]fordirpath,_dirnames,filenamesinos.walk(root):forfninfilenames:fullos.path.join(dirpath,fn)extos.path.splitext(fn)[1].lower()or(无扩展名)ext_counter[ext]1try:files.append((os.path.getsize(full),full))exceptOSError:continue# 权限受限或已被删除的文件跳过不让盘点中断files.sort(reverseTrue)returnlen(files),ext_counter,files[:10]defmain():rootsys.argv[1]iflen(sys.argv)1elserC:\Program Files\HTRIifnotos.path.isdir(root):print(f[跳过] 目录不存在{root})print(提示HTRI 默认常装于 C:\\Program Files\\HTRI 或 C:\\Program Files (x86)\\HTRI)print( 请先用一切可用方式确认本机实际安装路径再重跑本脚本。)returntotal,ext_counter,largestscan(root)print(f根目录{root})print(f文件总数{total})print(扩展名分布Top 15)forext,ninext_counter.most_common(15):print(f{ext:14}{n})print(最大文件Top 10)forsize,fullinlargest:print(f{size/1024/1024:8.2f}MB{full})if__name____main__:main()逐行剖析os.walk不跟随符号链接、天然按目录递归try/except OSError包住getsize——权限受限的系统目录会让盘点脚本半路崩掉这是 Windows 盘点的常见坑。os.path.splitext(fn)[1].lower()统一小写Windows 上扩展名大小写混杂.HTRI/.htri不统一会导致统计表里出现两行。用Counter做扩展名直方图本篇先建立这个习惯第 02 篇就靠它一眼看出*.htri案例、*.dbo机械设计导出等业务文件是否存在。默认路径给C:\Program Files\HTRI只是代码里的示例不是官方断言——HTRI 没有公开承诺固定安装路径实际以本机为准脚本对不存在目录显式跳过而不是报错退出。files.sort(reverseTrue)取最大的 10 个文件安装包里的程序集、依赖库往往体积最大这一列能帮你快速判断这是主程序目录还是数据目录。三、常见报错与排查报错 3-1ModuleNotFoundError: No module named win32com。现象pip install pywin32显示已安装import 仍失败。根因机器上多套 Pythonpip 装到了 A 解释器、脚本跑的是 B或 pywin32 缺 postinstall 步骤导致 COM 注册不可见。解法用python -m pip install pywin32强制对齐解释器再跑代码 2-1 的自检仍异常则执行脚本打印的pywin32_postinstall.py -install。报错 3-2https://www.htri.net/software-documentation打不开。现象浏览器访问官方软件文档页返回You do not have access to view this page。根因这不是故障而是 HTRI 会员权限墙——对象模型与用户文档只对已登录会员开放。解法不要把打不开当成没有文档。要么用会员账号登录要么走本系列铁律 1 的本机类型库探测方法学需要权威确认时提交官方技术支持咨询会员权益官方承诺三个工作日内响应。报错 3-3在注册表里搜索HTRI找不到任何 ProgID。现象reg query HKCR按关键字搜不到键。根因其一Automation Server 的 ProgID 字符串无公开文档底账 U1单猜一个词当然搜不到其二可能这台机器根本没装 Xchanger Suite或只装了教育版/客户端。解法第 02 篇先做是否安装的盘点第 05 篇再用多关键字子串枚举一次撒网HTRI / Xchanger / Xist / Xace 等命中项全部落表甄别——绝不要把网上抄来的某 ProgID写进代码。报错 3-4把 design 模式的约束字段当输入写入运行被忽略或失败。现象脚本写了某个几何字段运行后结果与预期不符或直接报错。根因Xist 的 rating/simulation/design 三模式下同一面板字段的可写性与语义不同——design 模式下部分是约束、rating 模式下是已知量。解法先明确本次运行的模式意图再决定写哪些字段把模式—可写字段的对应关系固化进第 04 篇的数据字典模板。报错 3-5盘点脚本在C:\Program Files (x86)下报权限错误。现象脚本抛PermissionError。根因Program Files系列目录受 UAC 保护普通权限读元数据一般可行但某些子目录会被拒。解法脚本已用try/except OSError跳过若确需完整盘点以普通用户身份读取元数据即可不要为盘点去提权或改 ACL。四、动手练习练习 1环境门禁运行代码 2-1。判定输出恰好 4 行[OK]、0 行[MISS]退出码 0。若有 MISS按提示安装后重跑至通过。练习 2默写决策表合上本文在笔记里重建通道 × 能力 × 风险表四行五列。判定四条通道名、官方 API 名HTRI Automation Server、技术形态OLE 自动化服务器、“ProgID 须本机探测”、加热炉是 Xfh 不是 Xjoule五项全中算通过。练习 3原文对照打开官方组件页与 Automation Server TechTip抄录 4 条与二次开发相关的原文要点组件页 2 条 TechTip 2 条。判定4 条齐全且至少 2 条含模块名、1 条含 “Automation Server” 字样。练习 4目录盘点在本机确认 HTRI 安装路径或任选一个大目录后运行代码 2-2。判定输出含文件总数与扩展名分布 Top 15两段若目录含.htri或.dbo扩展名表中能各出现一行。五、小结与下一篇预告本篇立起三根柱子身份柱HTRI 是研究联合体、会员制决定了文档分层与许可形态、能力柱Xchanger Suite 十模块 SmartPM/XSimOp/Edgeview/Exchanger Optimizer加热炉是 Xfh 而非 Xjoule、通道柱四条真实数据通道及其风险账。请记住两条纪律唯一官方 API 是 HTRI Automation ServerOLE而它的对象模型没有公开文档——先探测、后编码是本系列从下一篇起就要变成操作的第一条铁律。第 02 篇《环境盘点》我们将在一台装有 HTRI 的 Windows 机器上盘点系统要求与安装布局、用 HTRI License Manager 确认许可形态HL 硬件锁 / SL 软件锁 / 网络许可并把工程与案例文件*.htri、*.dbo、报表导出件分类登记成工程清单——那是后续所有自动化脚本的输入契约。本篇认知问题回显FAQQ1HTRI 是软件公司还是研究机构这个身份对使用者意味着什么AHTRIHeat Transfer Research, Inc.是一家研究联合体在德州 Navasota 设 Research Technology Center产品与服务覆盖 60 多个国家、1,500 家以上会员单位。因此其软件是会员权益的一部分官网不公开报价需联系销售Design Manual、研究报告与软件文档位于会员门户内https://www.htri.net/software-documentation对未登录访客返回权限墙。Q2HTRI Xchanger Suite 的加热炉模块叫什么Xjoule对吗A不对。HTRI 官方组件名单中的加热炉模块是Xfh与Xfh UltraXfh 用 Hottel zoning 法算局部辐射与工艺侧性能Xfh Ultra 是新的通用炉型建模软件。HTRI 没有名为 Xjoule 的产品。Xchanger Suite 的十个组件是 Xace、Xist、Xhpe、Xjpe、Xpfe、Xphe、Xspe、Xvib、Xfh、Xfh Ultra。Q3Xist 的 rating、simulation、design 三种模式分别是什么为什么自动化要先声明模式Arating校核是已知热负荷与几何求能否满足simulation模拟是几何已知、热负荷未知求实际性能design设计是热负荷已知、几何未知反算几何。模式决定了同一面板上哪些字段是可写输入、哪些是程序输出或约束——脚本若不声明模式就写字段轻则被忽略、重则该次运行失败。Q4HTRI 官方提供的二次开发 API 叫什么技术形态与官方演示语言是什么A叫HTRI Automation Server是随 Xchanger Suite 安装的OLE 自动化服务器OLE automation server用于访问 Xchanger Suite 文件数据并程序化运行计算。官方在 2014 年 TechTip 中用Visual Studio 2013 构建 .NETC#应用演示五个动作打开案例、改输入、运行、取输出、保存官方还提供基于 Excel 与 OLE 的 HTRI Parametric Study Tool。Q5HTRI 二次开发有哪几条真实通道各自风险是什么A四条。一是 Automation ServerOLE能力最强可批量无人值守但 ProgID/对象模型无公开文档、桌面 OLE 可能挂死残留进程二是报表与文件导出spreadsheet-style reports 导出 Excel、TEMA specification sheet、2D/3D drawings、*.dbo零 API 依赖适合审计但版式随版本漂移三是流程模拟器与 CAPE-OPEN 集成Xist 可作为单元操作嵌入支持 CAPE-OPEN 的模拟器直连机制细节未公开四是 Excel 自定义应用面官方列举 user-written applications in Excel易与模型脱钩。