gPROMS二次开发教程（13）：构建自定义模型库——从单文件模型到可维护的库工程

gPROMS二次开发教程13构建自定义模型库——从单文件模型到可维护的库工程版本声明块工具/软件gPROMS 桌面建模环境gPROMS ModelBuilder检索期官方发布锚点gPROMS Process 2022.1.0适用版本以官方发布说明为准语言/环境gPROMS 语言equation-oriented modelling基线与比对脚本用 Python 3标准库 可选 NumPy仅处理自己的 CSV不调用任何 gPROMS 组件本文目标把一个人写的几个模型升级为团队可复用、可审计、可回归的库工程一句话结论模型库不是把模型放进一个文件夹而是一套三层结构 接口契约 回归基线的工程以官方能力名Models in hierarchy的思想做层次化组织用PORT定义稳定的接口契约用PARAMETER支撑一个模型多种工况再用固定算例的回归基线保证每次改动都改完必验。〇、本篇要解决的认知问题Q1库的必要性到底在哪里“模型能跑为什么还不是模型可用”Q2模型库该怎么组织层次化官方能力名Models in hierarchy在工程上意味着什么Q3参数化怎么写才能让一个模型覆盖多种工况而不是复制十份Q4库的版本管理与变更影响评估该怎么做改了底层单元怎么知道影响了哪些流程Q5回归基线怎么立、怎么跑、怎么判为什么它是库的免疫系统一、机制解析1.1 为什么必须有模型库一个模型能跑只证明了它对某一次工况有效。库要解决的是下面四类反复出现的成本痛点症状库如何解决团队复用同一个反应器三个人写了三份参数与假设各不相同一份经过回归验证的权威实现 接口契约版本管理论文复现时找不到当时那一版模型库的版本号 / 变更记录与基线快照论文复现审稿人问这个结果用哪个模型算的答不上来交付包 库版本号 参数 基线结果变更失控改了底层速率式十几个流程悄悄变了结果变更影响评估 回归基线拦截经验法则当同一台设备被第二次建模时就该建库了。复制粘贴是沉淀负资产——第二份拷贝产生的那一刻两份就开始分叉。铁律 9改完必验库的全部价值建立在可验证之上。没有回归基线的库不是库只是一堆文件。1.2 库的组织三层结构 Models in hierarchy官方自学资源目录中的能力名Models in hierarchy层次化模型给出了 gPROMS 的组织范式大模型由子模型组装子模型可被多处复用。落到库工程上建议固定为三层第 1 层 原子层element —— 最小物理单元/本构关系 例速率式、传热关联式、物性关联式、单个平衡级 第 2 层 单元层unit —— 一台设备对外暴露 PORT端口 例CSTR、固定床、闪蒸罐、换热器 第 3 层 流程层flowsheet—— 由单元组装成的流程PROCESSES TOPOLOGY 例反应-分离回路、带循环的工艺链三条配套纪律单向依赖第 3 层可依赖第 2 层第 2 层可依赖第 1 层绝不允许反向。反向依赖原子层引用流程层会让库彻底失去复用性只在第 2 层开PORT接口契约只出现在单元层原子层不应暴露端口否则接口数量爆炸命名带层前缀如el_kin_arrhenius、un_cstr_iso、fs_reaction_loop。层前缀让该模型归哪一层无需猜测。铁律 1先查底账后落笔层次化的组织方式与模型组装语法随版本存在差异具体声明与实例化语法以官方《gPROMS ModelBuilder Guide》为准本文只给组织结构与纪律。1.3 参数化一个模型覆盖多种工况参数化的意思是把随工况变化的东西全部提到PARAMETER段模型体内不留魔数。反面例子与正面做法对照✗ 反例魔数写死 r - 8.0e6*exp(-5.8e4/(8.314*300.0))*C_A 0 想换温度只能改方程体——这就是复制粘贴的来源 ✓ 正例参数化 在 PARAMETER 段声明 k0、Ea、R、T 方程体内只出现名字r - k0*exp(-Ea/(R*T))*C_A 0 换工况 在同一工程里换一组参数赋值模型体一字不动判断标准很简单如果换工况需要动方程区说明参数化没做干净。1.4 版本管理与变更影响评估库要有版本号且版本号必须能对应到一组模型文件快照 一份基线结果。推荐三条轻量纪律不引入重型工具也能落地纪律做法版本号进模型头每个模型头的变更记录里写清版本与日期沿用第 05 篇的模型头模板影响面登记库内维护一张谁用了谁表依赖清单改第 1 层时先查这张表变更即跑基线任何第 1/2 层改动后跑一遍全部基线算例并比对变更影响评估的核心一句话“改了 X要重跑哪些基线”有了依赖清单答案就是一句查询改 el_kin_arrhenius → 被 un_cstr_iso、un_pfr_noniso 引用 → 被 fs_reaction_loop、fs_batch_train 引用 → 因此必须重跑上述 4 个基线算例经验法则依赖清单要人可读、机器可查。用一张 CSV谁引用谁就够了不必上重型工具关键是每次改动前真的去查它。1.5 回归基线库的免疫系统**基线baseline**是在某个已知良好的版本上用固定算例得到的、被记录下来的期望结果。回归测试就是重跑固定算例与基线比对。要素要求算例固定、可重复、覆盖关键路径正常工况 边界工况 已知难收敛工况参数全部显式写在基线文件里不许用默认值判据数值容差要显式给出例如相对误差 ≤ 1e-6不能只说差不多记录基线结果 当时的库版本号 求解设置三者一起存档基线比对的价值在于拦截无声错误改了底层速率式模型照样编译、照样求解成功但结果悄悄变了 ——只有基线能发现它。铁律 2两层证据分级库的权威性只能来自回归通过不能来自作者资历。没有基线记录的模型无论谁写的都只能算草稿。1.6 与前后篇的衔接库在工具链里是资产层第 09 篇的自定义单元操作是往库里生产内容的工序UNIT声明 PORT接口第 11、12 篇的参数估计 / Global System Analysis / Design Space是库的消费者它们都要求模型可解且可复现——这正是库提供的保证第 15 篇的优化与第 20 篇的综合项目则把库当作可以反复调用的底座。二、完整代码/模型与逐行剖析代码 2-1反应器库的目录与文件规划示意% % 反应器库 reactorlib —— 目录与文件规划 % 说明gPROMS 工程文件的官方扩展名为 .gPJ项目与 .gENCRYPT加密运行文件。 % 库工程的一个工程多模型还是多工程组合的组织方式 % 以官方文档与团队约定为准。 % reactorlib/ ├─ reactorlib.gPJ % 库工程文件官方扩展名 .gPJ ├─ 01_element/ % 第 1 层原子模型速率式、传热、物性 │ ├─ el_kin_arrhenius.md % 说明书假设、适用范围、参数含义、文献来源 │ └─ el_kin_arrhenius.note % 数据字典参数名/单位/典型范围/来源 ├─ 02_unit/ % 第 2 层单元模型对外开 PORT 接口 │ ├─ un_cstr_iso.md │ ├─ un_cstr_iso.contract % 接口契约表见代码 2-3 │ └─ un_pfr_noniso.md ├─ 03_flowsheet/ % 第 3 层流程组装PROCESSES TOPOLOGY │ ├─ fs_reaction_loop.md │ └─ fs_batch_train.md ├─ regression/ % 回归基线 │ ├─ baseline_v1.0.csv % 基线结果含库版本号、求解设置 │ ├─ cases_v1.0.csv % 固定算例的参数表 │ └─ check_regression.py % 比对脚本见代码 2-4 └─ CHANGELOG.md % 变更记录版本 / 日期 / 影响面 / 基线结果逐行剖析三层目录与 1.2 节的三层结构一一对应01_element/02_unit/03_flowsheet。用目录强行固化层次这样某个模型属于哪一层永远不需要口头确认。每个模型配两份文档.md说明书假设、适用范围、文献来源与.note数据字典参数名、单位、典型范围、来源。说明书回答它为什么成立字典回答参数从哪来——两者缺一模型就只能靠作者解释铁律 10。regression/目录与库代码并列基线是库的组成部分不是有空再说的附加物。cases_v1.0.csv算例参数与baseline_v1.0.csv期望结果分开存改期望值必须走评审。CHANGELOG.md里的四列版本 / 日期 / 影响面 / 基线结果这是 1.4 节影响面登记的落地载体也是论文复现时回答用哪一版算的的唯一凭据。代码 2-2层次化 参数化的库内模型结构示意% % 文件 : 01_element / el_kin_arrhenius 02_unit / un_cstr_iso % 物理背景 : 一级不可逆反应 A - B 的 Arrhenius 速率式及其在等温 CSTR 中的使用 % 说明 : 本块为结构示意。PARAMETER / VARIABLE / MODELS 为已确证关键字 % 子模型的组装/实例化语法以官方《gPROMS ModelBuilder Guide》为准。 % 层次纪律 : 单元层引用原子层原子层不引用任何上层单向依赖 % 自体版本 : 库版本 v1.0.0 改动后须重跑 regression/ 下全部基线 % %% %% 块 A —— 第 1 层原子模型 %% 模型名 el_kin_arrhenius单个模型的声明关键字与组织方式以官方文档为准 %% MODELS PARAMETER % 全部提到参数段模型体内不留魔数1.3 节 k0 8.0e6 % 指前因子 [1/s]来源见 el_kin_arrhenius.note Ea 5.8e4 % 活化能 [J/mol]来源同上 R 8.314 % 通用气体常数 [J/(mol*K)]文献值 VARIABLE T % 温度 [K]由上层传入此处声明为待求量之一 k % 速率常数 [1/s]本原子模型的输出 %% 方程残差式把 Arrhenius 关系原样写出不做变形 k - k0*exp(-Ea/(R*T)) 0%% %% 块 B —— 第 2 层单元模型 %% 模型名 un_cstr_iso引用块 A 的原子模型 k 作为输入 %% MODELS PARAMETER % 几何与操作参数换工况只改这里 V 1.0e-3 % 反应器有效体积 [m^3] F 1.0e-4 % 进料体积流量 [m^3/s] C_Ain 1.0 % 进料浓度 [kmol/m^3] T 300.0 % 等温操作温度 [K] VARIABLE C_A_out % 出口浓度 [kmol/m^3] r % 反应速率 [kmol/(m^3*s)] k % 速率常数 [1/s]由原子模型 el_kin_arrhenius 提供 %% 方程区 F*(C_Ain - C_A_out) - V*r 0 % 守恒稳态物料衡算 r - k*C_A_out 0 % 本构一级反应速率式 %% 说明k 由原子模型 el_kin_arrhenius 计算本处通过层次化组装接入 %% 组装实例化/连接的具体语法以官方文档为准。 %% 自由度核验铁律 8待求量 C_A_out, r, k 共 3 个本层给出 2 条 %% 原子模型给出 1 条 ⇒ 合计 3 条 ⇒ 自由度 0逐行剖析原子层把T也声明为VARIABLE这是刻意的设计——原子层不预设温度是已知还是待求它只负责给定温度算出速率常数。这样同一个原子模型既能服务等温反应器T由参数给定也能服务非等温反应器T由能量衡算求出。这一手把已知/待求的判定权上移是原子层能复用的关键。单元层的三个PARAMETERV、F、C_Ain、T就是工况旋钮多工况 多组赋值模型体一字不改1.3 节的判据。第 15 篇做优化时被优化的决策变量也多半就在这几个量里。自由度核验写在注释里而不是靠记忆铁律 8跨层组装时最容易出现的错误就是两层各自都闭合、合起来超定或欠定。把核验写进注释是在替未来的维护者做体检。模型边界与自证闭合库内每个模型块只写自己的参数、变量与方程必须自证闭合因为上层流程在组装时无法替你补制度方程。这也是为什么把原子层单独成块它的方程条目数就是它提供给上层的约束配额。代码 2-3第 2 层的接口契约表PORT契约% % 接口契约表un_cstr_iso 第 2 层单元模型对外暴露的 PORT % 契约纪律端口内变量的名字 / 单位 / 方向 / 物理含义四列一旦发布即冻结 % 任何改动都属破坏性变更须升主版本号并重跑全部相关基线。 % 连接语义TOPOLOGY 中一条连接 两个 PORT 内同名变量逐一写成相等方程第 04/09 篇。 % 端口名 PORT : inlet 变量名 单位 方向 物理含义 F m^3/s in 体积流量 C_Ain kmol/m^3 in 进料 A 浓度 T_in K in 进料温度 端口名 PORT : outlet 变量名 单位 方向 物理含义 F m^3/s out 体积流量等体积假设下与 inlet 相等 C_A_out kmol/m^3 out 出口 A 浓度 T_out K out 出口温度等温模型中 操作温度逐行剖析四列缺一不可名称装配靠它、单位错配的第一来源、方向进/出决定了连接的两端语义、物理含义防止同名不同义例如两个F一个是质量一个是体积。契约冻结是本表的全部价值接口一旦发布就给下游用改名字 让所有引用它的流程同时失效。因此接口变更必须显式升版本并重跑基线1.4 节。接口乱改是库失去信任的最短路径。inlet/outlet两个端口与TOPOLOGY的连接语义对应连接即同名变量逐一等价因此端口里多一个变量就等于连接时多一条等式——这也是为什么端口里不该放内部辅助量如反应速率r它们不属于接口。代码 2-4回归基线比对脚本Python# -*- coding: utf-8 -*- 回归基线比对脚本读入固定算例参数表与基线结果与本次运行结果逐项比对。 纪律 - 基线文件必须记录库版本号与求解设置否则比对结论无意义 - 容差必须显式给出改容差等于改判据必须走评审 - 本脚本只处理自己的 CSV 文件不调用任何 gPROMS 组件。 importcsvimportsys TOL_REL1.0e-6# 相对容差显式给出不得差不多就行TOL_ABS1.0e-9# 绝对容差防止期望值接近 0 时相对判据失效BASELINE_LIB_VERSIONv1.0.0# 基线所对应的库版本与 CHANGELOG 对齐defload_csv(path):读入两列式 CSVkey,value返回 dict。data{}withopen(path,r,encodingutf-8)asfh:forrowincsv.DictReader(fh):data[row[key]]float(row[value])# 全部按浮点读入便于比数值returndatadefcompare(expected,actual):逐项比对返回 (是否全部通过, 明细列表)。ok_allTruedetails[]forkey,expinexpected.items():ifkeynotinactual:details.append((key,exp,None,MISSING))# 结果缺项直接判失败ok_allFalsecontinueactactual[key]# 双判据绝对差 OK 或 相对差 OK任一满足即通过passed(abs(act-exp)TOL_ABS)or\(abs(exp)0andabs(act-exp)/abs(exp)TOL_REL)details.append((key,exp,act,PASSifpassedelseFAIL))ok_allok_allandpassedreturnok_all,detailsif__name____main__:# 实际使用时expected 来自 regression/baseline_v1.0.csv# actual 来自本次运行的输出导出为同格式 CSVexpectedload_csv(regression/baseline_v1.0.csv)actualload_csv(regression/actual_latest.csv)print(f基线库版本 {BASELINE_LIB_VERSION})print(f容差相对{TOL_REL:g}绝对{TOL_ABS:g})ok_all,detailscompare(expected,actual)forkey,exp,act,tagindetails:act_strNoneifactisNoneelsef{act:.10g}print(f{tag:7s}{key:24s}期望{exp:.10g}实际{act_str})print(回归结论 ,ALL PASSifok_allelseFAILED)sys.exit(0ifok_allelse1)# 退出码可直接接入自动化流水线逐行剖析TOL_REL与TOL_ABS双判据只有相对容差时期望值接近 0 的项会永远失败只有绝对容差时大数值项又会过松。双判据是工程上最省事的稳妥做法。BASELINE_LIB_VERSION硬编码在脚本里这是 1.5 节基线 库版本号 求解设置三者一起存档的代码化。基线换了版本脚本里的这一行必须同步改——否则比对的是苹果与橘子。MISSING判定结果缺项直接判失败不允许缺项算通过。库回归里最常见的无声错误就是某个输出量忘了导出此时若缺项不判失败回归等于没跑。sys.exit(0/1)退出码让脚本能直接挂进自动化流水线——回归必须是跑得起来、看得见、拦得住的三件事第 14 篇会讲如何把这类脚本串成自动化。三、常见报错与排查报错 3-1库内改动后上层流程编译通过但结果悄悄变了。现象无报错结果与历史记录不符。根因改了第 1/2 层而没跑基线1.5 节。解法任何底层改动后按CHANGELOG.md的影响面清单重跑全部相关基线把回归不通过不许合入作为团队纪律。报错 3-2单元模型在流程里组装后自由度不为 0。现象单独求解单元模型正常放进流程就报自由度问题。根因跨层组装时同一物理约束被写了两遍或端口里带了不该由连接决定的量。解法核对代码 2-2 那样的分层自由度清单把内部辅助量如r从PORT里移出代码 2-3 的剖析。报错 3-3改了PORT变量名一片流程同时报未定义。现象接口改名引发大面积错误。根因破坏了接口契约代码 2-3。解法接口变更视为破坏性变更——升主版本号、同步所有引用方、重跑基线能不改名就不改名。报错 3-4换工况要改方程区。现象每接一个新工况都要动模型体。根因参数化没做干净1.3 节的魔数反例。解法把随工况变化的量全部提到PARAMETER模型体内只出现名字。报错 3-5回归比对大面积 FAIL但模型看起来没动。现象基线全线失败。根因求解设置容差、初值、输出频率变了或基线记录的库版本与实际不符。解法先核对库版本号与求解设置再怀疑模型基线文件里必须存这些元信息。铁律 3版本先声明库内每个模型都应声明适用版本因为跨版本的语言与默认设置差异会导致回归结果漂移。以官方发布说明为准。四、动手练习练习 1建最小库按代码 2-1 建一个只含 1 个原子模型、1 个单元模型的库工程。判定三层目录齐备、每个模型有说明书与数据字典、CHANGELOG.md存在且写明版本。练习 2参数化改造把代码 2-2 中un_cstr_iso的温度从300.0改成由上层给出并构造 3 个工况。判定3 个工况共用同一份模型体方程区字符完全一致在cases_v1.0.csv中记录三组参数。练习 3接口契约为你的单元模型写一份代码 2-3 格式的契约表。判定四列齐全能指出哪个变量若改名会影响几个流程。练习 4基线建立与拦截用代码 2-4 建立baseline_v1.0.csv随后故意把原子模型的Ea改成5.7e4模拟一次错误改动重跑回归。判定脚本输出FAILED、指出具体偏差项、退出码为 1改回后回归恢复ALL PASS。练习 5思考题无标准答案为什么只在第 2 层开PORT能显著降低接口维护成本从接口数量与变更影响面两个角度写两条理由。五、小结与下一篇预告本篇把模型升级为库用三层结构原子 / 单元 / 流程 单向依赖 只在单元层开PORT落实官方能力名Models in hierarchy用全参数化实现一个模型多种工况判据换工况不动方程区用接口契约表冻结PORT用依赖清单 CHANGELOG做变更影响评估用固定算例 显式容差 双判据脚本建立回归基线拦截编译通过但结果变了的无声错误。库的权威性来自回归通过不来自作者资历。第 14 篇《自动化与外部连接一》把库接到外面的世界三类连接方向——gO:Python从 Python 调用 gPROMS、gO:MATLABgPROMS Object for MATLAB把整个模型当单个函数调用、AdaptorFO从 gPROMS 调用 Python 脚本、以及运行时双向的gPROMS Foreign Process InterfaceC/C 接口并给出三方向决策表与常见的环境/路径/版本/许可失败模式。本篇认知问题回显FAQQ1库的必要性在哪里模型能跑为什么还不是模型可用A能跑只证明它对某一次工况有效。库要解决四类反复出现的成本团队复用上避免同一台设备被多人写成多份且假设参数不一致版本管理上避免找不到当时那一版模型论文复现上避免无法回答结果用哪个模型算的变更控制上避免改了底层速率式而十几个流程结果悄悄变化。库通过一份经回归验证的权威实现、稳定的接口契约、版本号与基线快照来消除这些成本。Q2模型库该怎么组织层次化在工程上意味着什么A建议固定为三层原子层放最小物理单元与本构关系如速率式、传热关联式单元层放一台设备对外暴露端口流程层由单元组装成流程。配套三条纪律单向依赖上层可依赖下层而绝不允许反向端口只开在单元层原子层不暴露端口以免接口数量爆炸命名带层前缀如原子层用 el 前缀、单元层用 un 前缀、流程层用 fs 前缀使模型归属无需猜测。Q3参数化怎么写才能让一个模型覆盖多种工况A把随工况变化的所有量全部提到参数段模型体内不留魔数方程区只出现参数名与变量名。反面做法是把速率常数写成含固定数值的复合表达式想换温度就必须改方程体这正是复制粘贴的来源。判断标准很直接如果换工况需要动方程区就说明参数化没做干净。参数化做干净后多工况就等于在同一工程里换一组参数赋值模型体一字不改。Q4库的版本管理与变更影响评估该怎么做A三条轻量纪律版本号进模型头在变更记录里写清版本与日期维护依赖清单登记库内谁引用谁改底层前先查它据此确定要重跑哪些基线任何底层改动后立刻跑基线并比对。变更影响评估的核心问题就是改了某个模型要重跑哪些基线有了依赖清单这个答案就是一次查询。交付与论文复现时库版本号加参数加基线结果三者一起给出。Q5回归基线怎么立、怎么跑、怎么判为什么它是库的免疫系统A基线是在已知良好的版本上用固定算例得到的被记录下来的期望结果。四个要素必须齐全算例要固定可重复并覆盖正常工况、边界工况与已知难收敛工况参数全部显式写在基线文件里不许用默认值判据要显式给出数值容差且最好同时用相对与绝对双判据以避免期望值接近零时判据失效基线结果要与当时的库版本号、求解设置一起存档。它被称为免疫系统是因为底层改动后模型照样编译、照样求解成功但结果已悄悄变化只有基线能拦截这种无声错误。本文涉及的语言细节以所购版本随附的官方 gPROMS 文档为准。