Aspen HYSYS 二次开发系列教程（16）：Excel/数据库数据交换——方向性约定与列命名纪律

Aspen HYSYS 二次开发系列教程16Excel/数据库数据交换——方向性约定与列命名纪律版本声明块软件aspenONE V15基线同第 1 篇文档现实Customization Guide V7.32011-03为公开手册基线语言/环境Python(openpyxl/数据库驱动) COM 自动化未证实成员名以 dir() 守卫处理铁律 7本文目标把数据交换从功能描述升级为可复现的工程约定——方向、命名、所有权三条纪律一句话结论HYSYS 与 Excel/数据库的数据交换是双向的——Excel→HYSYS 送输入参数与工况表HYSYS→Excel/数据库回写结果批量场景的三条纪律是固定列命名与方向注释、一个 case 只允许一个写入源第 10 篇双写入源冲突、每条回写行携带审计链八列第 14 篇——缺任何一条报表错位或结果不可复现。〇、本篇要解决的认知问题数据交换的两个方向在脚本里分别对应哪些操作当前值 vs 基线值口径陷阱在哪一步出现列命名纪律的最小格式是什么——为什么哪列是输入哪列是输出必须写进文件本身双写入源冲突的工程后果是什么——如何检测与防护第 10 篇机制的数据层延伸数据库回写时 run_ref、ts、version 三列如何保证可追责第 14 篇八列的落库形态批量扫描表的可复现格式是什么——第三方重跑必须能对齐哪些字段一、机制解析1.1 两个方向的脚本映射价值锚点方向混淆是输入列被当输出读的第一根因方向A输入: Excel/DB → COM 对象写入仅输入侧成员——第 9 篇输入/解边界 方向B回写: COM 对象读取仅 status OK 时——铁律 6→ Excel/DB 记录行含审计链八列——第 14 篇口径陷阱出现点扫描过程中当前值 vs 基线值——Excel 表里同一物理量既有基线又有扫描覆盖时若方向注释缺失回写可能把扫描前的基线当结果记录第 10 篇机制在数据层的复现。判定标准练习用任取一行能指出该 value 来自哪一次 Runrun_ref 列可还原——第 14 篇。1.2 列命名纪律的最小格式col_name, direction, member_confirmed(unit_set), notes T_in, INPUT→HYSYS, dir() confirmed or 未证实, ℃/K 口径记录铁律 7 purity, HYSYS→OUTPUT, status OK only, mole basis — record explicitly为什么必须写进文件本身报表错位事故里最常见的场景是两个团队各自解读同一列——方向与口径在文件内自描述才是可复现性第 14 篇八列的表头化。经验法则回写前先做一次手工抽查随机抽 3 行对照 GUI/日志——这是数据交换层的输出层断言第 13 篇合流。1.3 双写入源冲突的检测与防护场景后果防护ASW 与脚本同时改同一对象谁最后写入谁生效结果不可复现第 10 篇一个 case 单一写入源所有权登记第 19 篇两个脚本实例并发回写同一表行级交错、run_ref 与实际写入者不一致串行化或按 case 分表审计日志记录写入源类型与时刻第 13/15 篇判定线任一 FAIL 行能还原哪一次 Run、哪个口径、哪个版本、哪个写入源——四要素齐即可追责第 14 篇八列在此增加 writer_source。1.4 数据库回写的落库形态可追责三列run_ref对应哪一次 Run 或哪个检查、ts含时区、version实际运行版本——铁律 1加上实例模式与许可形态记录第 15 篇部署侧。判定标准数据库任意一行可还原四要素——缺列即不可追责1.3。二、完整代码与逐行剖析2.1 带方向声明与审计链的 Excel 回写管线复制即跑参数为示例值importwin32com.client,datetime,csv# ——方向声明表1.2 纪律的文件化形态——列自描述——COLS[(T_in,INPUT→HYSYS),(purity,HYSYS→OUTPUT)]defexchange_row(sim,stream_name,t_value):row{param:t_value,value:None,status:OK,ts:datetime.datetime.now(datetime.timezone.utc).astimezone().isoformat(),version:actual running version — record from machine,# 铁律 1第 15 篇unit_set:record,basis:record,run_ref:None,writer_source:script,# 所有权列1.3direction:HYSYS→OUTPUT}streamsim.Flowsheet.MaterialStreamFlowsheetStreams.Item(stream_name)# 名称契约第 19 篇# ——方向A写入仅允许输入侧成员第 9 篇边界——把解当输入写会被求解覆盖——ifTemperaturenotindir(stream):row.update(statusCODE_ERROR,valuemember not confirmed (铁律 7));returnrow stream.Temperature.Valuet_valuetry:sim.Run()# 成员名以本机为准铁律 7exceptExceptionase:row.update(statusCODE_ERROR,valuestr(e));returnrow propsdir(sim)forcandin(ErrorList,Messages):# 未证实成员——存在才检查铁律 7ifcandinprops:errgetattr(sim,cand)cntgetattr(err,Count,None)ifcntandcnt0:row.update(statusFAIL,run_refcand);returnrow# 业务失败不取值铁律 6# ——方向B回写仅 status OK 时输出层断言——第 13/14 篇合流——row[value]getattr(stream.Temperature,Value,None)row[run_ref]clean runreturnrow appwin32com.client.Dispatch(HYSYS.Application)# 位数一致铁律 3实例模式记录进文档第 15 篇simapp.ActiveDocument# 服务场景用 Documents 显式绑定第 2 篇rows[exchange_row(sim,Feed,t)fortin(20,25,30)]withopen(exchange.csv,w,newline)asf:wcsv.DictWriter(f,fieldnameslist(rows[0].keys()));w.writeheader();w.writerows(rows)# ——手工抽查判定线1.2随机抽 3 行对照 GUI/日志——本脚本把抽查结果写入同一文件注释区——print(sample check:,[(r[param],r[value])forrinrows[:3]])逐行要点方向 A/B 在代码里显式分开——输入侧写入与输出侧取值各对应一条边界纪律writer_source列把所有权从口头约定变成可查询字段1.3。三、常见报错与排查输入列被当输出读报表错位—— 现象回写值与预期不符。根因方向注释缺失或当前值 vs 基线值口径混淆1.1。解法列自描述表1.2回写前手工抽查 3 行。双写入源冲突—— 现象同一对象值不可复现、run_ref 与写入者不一致1.3。根因ASW/脚本或两脚本实例并发写同一表。解法一个 case 单一写入源按 case 分表或串行化所有权登记进可复现性文档第 19 篇。把解当输入写入—— 现象Run 后值被覆盖第 9 篇机制在数据层的复现。根因方向 A 越界。解法仅输入侧成员可写——代码里用 dir() 确证后再访问铁律 7。数据库行不可追责—— 现象某行无法还原来自哪一次 Run。根因run_ref/ts/version 三列缺失1.4。解法八列writer_source 齐备后复跑缺列即判定不通过。四、动手练习方向与抽查复现按 2.1 完成并随机抽 3 行对照 GUI/日志。判定标准三行都能还原 run_ref列自描述表1.2随文件交付——第三方重跑可对齐字段即达标。双写入源实验制造一次 ASW 与脚本并发写同一对象。判定标准能观察到谁最后写入谁生效的不可复现现象恢复单一写入源后连续 10 次输出一致——写出所有权登记的最小三列writer_source、ts、case。思考题无标准答案为什么基线值 vs 当前值在扫描场景必须显式区分验证要点清单① 写出扫描覆盖与基线的两个存储位置② 举一个回写把基线当结果的场景③ 给出判定线——什么条件下允许省略基线列单点、无覆盖时。五、小结与下一篇预告本篇把数据交换升级为三条工程纪律方向自描述、单一写入源、可追责八列。第 17 篇把闭环五步接上外层优化器——黑盒不可微的代价、惩罚值与差分路线的选择第 18 篇进入数字孪生接口——实时数据接入时输入测量、输出估计的口径分离第 19 篇收拢可复现性三件套与回归测试体系。本篇认知问题回显FAQQ1HYSYS 与 Excel/数据库的数据交换两个方向分别对应什么脚本操作A方向 A——Excel/DB 向 HYSYS 送输入参数与工况表仅允许写输入侧成员方向 B——HYSYS 向 Excel/DB 回写结果仅 status OK 时读取回写行携带审计链八列。Q2当前值 vs 基线值口径陷阱出现在哪一步A扫描过程中同一物理量既有基线又有扫描覆盖时——若方向注释缺失回写可能把扫描前的基线当结果记录判定标准是任取一行能指出该 value 来自哪一次 Runrun_ref 列可还原。Q3双写入源冲突的工程后果是什么如何防护A同一对象被 ASW 与脚本或两个脚本实例同时写入时谁最后写入谁生效结果不可复现、审计链断裂防护是一个 case 只允许一个写入源、按 case 分表或串行化并把 writer_source、时刻、case 登记进可复现性文档。Q4列命名纪律的最小格式是什么为什么必须写进文件本身A每列声明 directionINPUT→HYSYS 或 HYSYS→OUTPUT、成员确证状态与口径——方向与口径在文件内自描述才能避免两个团队各自解读同一列回写前随机抽 3 行对照 GUI/日志是数据交换层的输出层断言。Q5数据库回写的可追责三列是什么Arun_ref对应哪一次 Run 或哪个检查、ts含时区、version实际运行版本——加上 writer_source 与实例模式、许可形态记录任意一行可还原哪一次 Run、哪个口径、哪个版本、哪个写入源才叫可追责。