Aspen HYSYS 二次开发系列教程（7）：属性集、单位与量纲陷阱——差一个数量级的第一根因
版本声明块
- 软件：aspenONE V15（基线，同第 1 篇）；文档现实：Customization Guide V7.3（2011-03）为公开手册基线
- 语言/环境：Python(pywin32)/VBA；未证实属性名标注"未证实"并给 dir() 自查步骤（铁律 7）
- 本文目标：把"
.Value的口径从哪来"讲透，给出量纲错位的三类高发场景与文档记录规范
一句话结论：HYSYS 脚本读写的.Value数值依赖当前 unit set/属性集口径——同一个数字在 °C 与 K、摩尔基准与质量基准之间差一个数量级或整体平移；GUI 显示、报表与脚本三方必须使用同一口径，可复现性文档必须记录：unit set 名称、组分基准（mole/mass）与求解状态来源。
〇、本篇要解决的认知问题
.Value的数值随什么变化——unit set、属性集还是 case 设置？- 温度类量纲错位（°C vs K）在脚本里有什么可观察特征？为什么它比流量错误更隐蔽？
- 流量/组成的基准（mole basis vs mass basis）如何影响读取值？
- GUI、报表、脚本三方口径不一致时，哪个是"真值"——以什么为准判定？
- 可复现性文档应记录哪些单位信息项——最小集是什么？
一、机制解析
1.1 口径从哪来（价值锚点：这是"结果差一个数量级"的第一排查项）
case 设置 → unit set（如 SI metric / Euro / 自定义） │ GUI/报表/脚本读 .Value ←── 同一物理量按同一 unit set 呈现 属性集（property view）→ 决定"哪些物理量可访问、以什么形态呈现"关键机制：.Value返回的是"按当前口径折算后的数值"——它不是无量纲裸数。脚本与 GUI 不一致时，先比口径再怀疑算法（第 5 篇两级结构的单位侧闭环）。
1.2 三类高发场景（可观察特征）
| 场景 | 可观察特征 | 为什么隐蔽 |
|---|---|---|
| °C vs K | 数值平移 273.15；方向判断可能仍"看起来对" | 平移不破坏单调性——只有绝对值对照才暴露 |
| mole basis vs mass basis | 流量差一个数量级或组分权重错 | 守恒仍闭合（各自口径内闭合）——不报错 |
| 默认 unit set 与输入页不一致 | GUI 显示 100、脚本读到另一数 | 输入页单位标签易被忽略（铁律 3 同源） |
判定标准（练习用）：同一物理量分别按两种口径读取，差值必须等于可解释的折算关系（如 273.15 平移或分子量倍率）——差值不可解释即存在配置错误。
1.3 "真值"判定规则
三方不一致时以数据层当前状态为准：脚本读的是对象当前值；GUI 显示可能含格式化与缓存；报表是视图（第 6 篇假阳性机制在此复用）。判定顺序：① Run 状态（铁律 6）→ ② unit set 快照 → ③ 手工按口径折算对照。
1.4 可复现性文档的最小记录集（与第 19 篇三件套对齐）
- unit set 名称与逐物理量口径；
- 组分基准（mole/mass）与"表观/真实组分"影响（跨主题：Aspen Plus 系列第 12 篇）；
- 求解状态来源（Run 成功后读取，含时间戳）。
二、完整代码与逐行剖析
2.1 口径对照脚本（复制即跑）
importwin32com.client app=win32com.client.Dispatch("HYSYS.Application")# 位数一致（铁律 3）sim=app.ActiveDocument feed=sim.Flowsheet.MaterialStreamFlowsheetStreams.Item("Feed")# 名称契约（第 19 篇）# —— 1.2 场景一：温度口径对照（判定线：差值 = 可解释折算）——t_val=feed.Temperature.Value# .Value 按当前 unit set（未证实口径以本机为准，铁律 7）print("temperature value:",t_val)# 若 GUI 显示 °C 而此处数值接近 K→口径错位可观察# —— 1.2 场景二：流量基准抽查（守恒在各自口径内闭合，不报错）——flow=Noneforcandin("MassFlow","MolarFlow"):# 候选成员名——存在才访问（事实纪律）ifcandindir(feed):flow=getattr(feed,cand)print("flow object:",flow.Valueifflowelse"未证实成员，跳过")# —— 1.4 文档记录集（可复现性三件套的本篇实例）——print({"unit_set":"record from GUI/case settings",# 脚本内不可确证时如实标注"basis":"mole or mass — record explicitly","status_source":"Run success required before reading results (铁律 6)"})逐行要点：脚本对"不可确证的口径名"不硬读——dir() 守卫把口径问题从猜测变成可观察记录；输出即文档的一部分（第 13 篇审计链）。
三、常见报错与排查
- 结果差一个数量级—— 现象：脚本与报表不一致。根因：mole/mass 基准或 unit set 不同（1.2）。解法：按 1.3 判定顺序——先状态、再口径、再折算对照。
- 温度平移错误（°C vs K）—— 现象：方向判断正常但绝对值错。根因：口径混用且无对照。解法：同一物理量双口径读取，差值必须等于 273.15 或可解释折算——不可解释即配置错误（本篇判定标准）。
- 输入页单位标签被忽略—— 现象：写入值与预期不符。根因：默认 unit set 与输入页不一致（铁律 3）。解法：脚本写入前打印当前口径；文档记录逐物理量口径。
- 报表与脚本"真值"争议—— 现象：两个团队数字不同。根因：视图层缓存 vs 数据层当前状态（1.3、第 6 篇）。解法：固定判定顺序并在报告注明读取时机（Run 后、时间戳）。
四、动手练习
- 双口径对照复现：按 2.1 完成温度与流量两类对照。判定标准：差值等于可解释折算关系；不可解释时能定位配置项（unit set 或基准）。
- 文档最小集编写：为当前 case 写一份单位信息表（unit set、组分基准、读取时机）。判定标准：第三方按该表在另一台机器复跑得到一致结果（相对误差 < 1e-6）。
- 思考题（无标准答案）："守恒在各自口径内闭合"这句话为什么让量纲错误更危险？验证要点清单：① 写出 mole/mass 两种口径下守恒都成立的机制；② 举一个"报表与脚本都闭合但互不一致"的场景；③ 给出判定顺序三步骤的适用前提。
五、小结与下一篇预告
本篇把.Value的口径来源钉死为 unit set+属性集，并给出三类高发场景与文档最小记录集。第 8 篇把读→改→Run→取值→判优跑成完整实战闭环——断言层（第 6 篇）与口径纪律（本篇）在实战里合流；之后第 10 篇划清免编程路线与脚本的边界。
本篇认知问题回显（FAQ）
Q1：HYSYS 脚本里.Value的数值口径由什么决定？
A：由当前 unit set/属性集口径决定——.Value是按口径折算后的数值而非裸数；GUI、报表与脚本必须使用同一口径，不一致时先比口径再怀疑算法。
Q2：温度量纲错位（°C vs K）为什么比流量错误更隐蔽？
A：它只平移数值（差 273.15），单调性和方向判断可能仍"看起来对"——只有绝对值对照才暴露；而流量基准错误往往差一个数量级、更容易被发现。
Q3：mole basis 与 mass basis 错位时为什么软件不报错？
A：守恒在各自口径内都闭合——错误表现为脚本与报表互不一致而非内部矛盾；判定方法是同一物理量双口径读取，差值必须等于可解释折算关系（分子量倍率或基准换算）。
Q4：GUI、报表、脚本三方不一致时以什么为准？
A：以数据层当前状态为准——脚本读的是对象当前值；判定顺序为① Run 状态（铁律 6）→② unit set 快照→③ 按口径手工折算对照；报告注明读取时机与时间戳。
Q5：可复现性文档应记录哪些单位信息项？
A：最小集三项——unit set 名称与逐物理量口径、组分基准（mole/mass）、求解状态来源（Run 成功后读取，含时间戳）；这三项齐备第三方才能复跑得到一致结果。
