PHAST-SAFETI二次开发教程06源项与物料——容器与管道泄漏源项及物料库二次开发版本声明块工具/软件Phast™ / Safeti™版本主线 9.x具体以官方发布说明为准语言/环境Python ≥ 3.11官方库 PyPWS包名pypws接口端点https://phastwebservices.dnv.com/api/analytics/v1/本文目标把「物料 容器/管道几何与工况 泄漏本身」三要素稳定翻译成 PyPWS 实体并分清哪些值必须回到官方文档核对一句话结论Phast™ 泄漏源项Discharge只由三组输入决定——物料Material/MaterialComponent、容器或管道几何与工况Vessel/State、泄漏本身Leak稳态泄漏的dischargeRecords恒为2 条记录时变泄漏记录条数随计算步长变化官方示例中甲烷时变泄漏得到118 条下游扩散与火灾模型消费的就是这段确定性响应。本篇铁律适用三级标注取自系列登记的 10 条[硬约束] 铁律 2 闭源事实纪律物料与泄漏相关的属性名、枚举名一律取自官方 PyPWS 参考文档未确证的字段不写死。[硬约束] 铁律 4 单位与坐标系纪律Phast Web Services 全部使用SI 单位压力为绝压。[强约束] 铁律 3 只用官方接口只经由 Phast API / Phast Web Services / PyPWS 构造源项。[提示] 铁律 7 改完必验任何脚本源项都要与桌面 GUI 同参数结果做一次回归。〇、本篇要解决的认知问题源项到底有几种「族」容器、储罐、管道、长输管道、埋地管道在数据上差在哪一层稳态泄漏与时变泄漏含 blowdown、隔离段在结果结构上如何体现标况、滞止、闪蒸、两相这些术语在数据模型里分别对应哪个字段的哪个枚举值Phast™ 自带的 2,000 物料从哪来脚本里怎么查、怎么用用户自定义物料user-defined material与混合物在脚本里如何落地边界在哪哪些源项细节公开资料不足以支撑必须回到官方 User Manual以下「认知问题回显FAQ」逐条回答顺序一一对应。一、机制解析1.1 源项族与共用输入契约官方 PyPWS 文档在描述概念时明确Phast Web Services 以「对象」组织工作对象是物理对象vessel 或 pipe加关联数据对象leaks、pipe ruptures、weathers这些对象在调用 vessel leak 或 pipe breach 计算时被消费。由此可把源项族归纳为下表表内「族名」为功能语义归类落地时仍以官方 User Manual 的界面表述为准。源项族物理对象关键几何备注压力容器泄漏Vesseldiameter、length、shape官方示例用VesselShape.HORIZONTAL_CYLINDER储罐泄漏Vesseldiameter、length、liquidFillFractionByVolume液位由装量分数表达压力容器/储罐灾难性破裂Vessel 破裂数据对象同上官方述及 vessel catastrophic rupture管道破口pipe breach管道对象 破口数据对象孔径、管径官方述及 pipe rupture长输管道 / 埋地管道管道对象分段、埋深等埋地管道为 8.x 历史锚点能力9.x 以发布说明为准三条共用输入契约是稳定的物料 → 相态 → 泄漏几何。官方文档对三个计算对象的职责描述可直接引用Vessel state对用户定义物料在给定压力/温度下做闪蒸计算得到流体物性并返回容器工况即Pure gas / Stratified Two-Phase vessel / Pressurised Liquid三类可输入到 vessel leak 与 vessel catastrophic rupture 源项模型Vessel leak计算压力容器或储罐的稳态或时变泄漏包含从容器孔口到大气条件的膨胀建模把某时刻的排放速率、温度等随时间变化的输出以discharge records回报Downstreamjet fire 用锥模型cone model对时变排放取20 s 平均排放数据对连续排放则用初始恒定排放数据。1.2 稳态与时变的差别┌──────────────────────────────┐ Material ─┐ │ VesselStateCalculation │ ├─────▶│ 闪蒸 → 相态判定 │ State ────┘ │ (PureGas / Two-Phase / Liq) │ └──────────────┬───────────────┘ │ outputState / material / vesselConditions ▼ ┌──────────────────────────────┐ Leak(孔径/时变)─▶│ VesselLeakCalculation │ Vessel(几何) ───▶│ 孔口 → 大气 膨胀建模 │ └──────────────┬───────────────┘ │ dischargeRecords稳态2 条时变可变条数 ▼ JetFireCalculation → RadiationTransectCalculation维度稳态泄漏时变泄漏枚举TimeVaryingOption非时变取值TimeVaryingOption.TIME_VARYING_RATE记录条数恒为 2 条随计算步长变化官方示例 118 条下游消费取初始恒定排放数据jet fire 取 20 s 平均1.3 相态与闪蒸的判定位置相态不是「手感」问题而是由两个开关共同决定State.flashFlag示例取FluidSpec.TP表示以温度—压力作为规格与VesselLeakCalculation.dischargeParameters.flashAtOrifice示例取FlashAtOrifice.DISALLOW_LIQUID_FLASH。前者决定物料在容器内的相态后者决定液体在孔口处是否允许闪蒸——这就是「孔口闪蒸」在数据模型里的确切位置。1.4 物料库Phast™ 内置物料规模为2,000官方产品页说明其物性来源为DIPPR数据库。脚本侧通过 materials 模块访问官方文档列出 4 类获取函数与自定义写入函数getAllCasIds()、getMaterialByCasId(casId)、getDNVComponents()、getDIPPRComponents()、getUserComponents()、getComponentById(id)、getComponentByName(name)、getComponentByCasId(casId)、storeMaterialComponent(...)、storeMaterialComponentAndCreateMaterial(...)。1.5 源项建模的四条工程法则第一条先定相态再定孔径。相态由容器状态计算给出孔径是工况输入若先扫孔径、再回头改物料整批工况的相态结论都会失效前面的计算全部作废。第二条同一物质只能有一种表示方式。项目内要么统一用 CAS 号定位官方物料要么统一用自建组元与用户自定义物料同一种物质在工况表里出现两种写法会让批处理的分组统计与风险贡献分解直接失真而这种错误在单场景调试时根本看不出来。第三条源项必须留下可复算的输入快照。把「物料组元与摩尔分数、容器几何与装量、孔径与时变选项、状态规格与孔口闪蒸假设」这四组值原样落盘存档任何结果异议都能用同一快照复现铁律 6。源项快照是整个流水线里唯一不可再生的输入改动它等同于换了一个研究。第四条不要用下游结果反推源项。若扩散浓度或热辐射剖面不符预期正确的排查顺序是先回到源项的排放速率时间序列核对量级与形态再看相态假设最后才怀疑扩散环节的参数越过源项去调扩散参数等于用一个错误的输入去补偿另一个错误的参数结果看似「对上了」实则两处都错。二、完整操作与脚本逐段剖析2.1 第一段构造多组分物料并做合法性检查# -*- coding: utf-8 -*-# 演示构造多组分物料甲烷 0.8 / 乙烷 0.2并回查物料库importos# 标准库读环境变量frompypws.entitiesimportMaterial,MaterialComponent# 官方实体物料与组元frompypws.enumsimportPropertyTemplate# 物性模板枚举frompypws.utilitiesimportgetAnalyticsApiTarget# 打印当前 API 目标frompypws.materialsimportgetAllCasIds,getMaterialByCasId# 物料库查询函数# 先打印当前连接的 Phast Web Services 实例避免打错版本print(\n******************************************************************************************)print( Running against: %s%(getAnalyticsApiTarget()))print(******************************************************************************************\n)assertos.environ.get(PHAST_API_TOKEN),未配置 PHAST_API_TOKEN铁律 5令牌不硬编码materialMaterial()# 声明物料对象material.componentCount2# 明确组元数量与 components 长度必须一致# 组元一甲烷摩尔分数 0.8componentMaterialComponent()# 声明组元对象component.nameMETHANE# 名称写法沿用官方示例的大写形式component.moleFraction0.8# 摩尔分数无量纲material.components.append(component)# 追加到物料组元列表# 组元二乙烷摩尔分数 0.2componentMaterialComponent()component.nameETHANEcomponent.moleFraction0.2material.components.append(component)# 物性模板官方示例对多组分使用 PHAST_MC表示按 Phast™ 多组分方式处理material.propertyTemplatePropertyTemplate.PHAST_MC# 校验一组元数量自检防止 append 次数与 componentCount 不一致assertlen(material.components)material.componentCount,组元数与 componentCount 不一致# 校验二摩尔分数归一化自检totalsum(c.moleFractionforcinmaterial.components)# 累加摩尔分数assertabs(total-1.0)1e-9,摩尔分数合计不为 1str(total)# 校验三回查物料库确认该物料可被 CAS 号定位示例取库中第一条以验证通路cas_listgetAllCasIds()# 返回 MaterialCasIdInfo 列表含名称与 CAS 号print(物料库条目数,len(cas_list))# 2,000 量级用于确认连通性probegetMaterialByCasId(cas_list[0].casId)# 按 CAS 号取回官方物料对象print(探针物料,probe.name)# 打印名称确认对象可读要点官方文档强调Phast Web Services 始终使用 SI 单位每个属性的期望单位在参考章的实体表中给出。写脚本时不要在本地做「英尺/磅」换算后直接塞进去。2.2 第二段从相态判定到排放记录# 演示VesselStateCalculation → VesselLeakCalculation并统计排放记录frompypws.calculationsimportVesselStateCalculation,VesselLeakCalculationfrompypws.entitiesimportState,Vessel,Leak# 状态、容器、泄漏三个数据对象frompypws.enumsimport(ResultCode,FluidSpec,MixtureModelling,VesselShape,TimeVaryingOption,FlashAtOrifice)# —— 步骤 1设定状态规格。压力为绝压温度为开尔文 ——stateState()state.pressure1521325.0# 单位 Pa注意是绝压而非表压铁律 4state.temperature365.15# 单位 K铁律 4全 SIstate.liquidFraction0.0# 初始液化分数state.flashFlagFluidSpec.TP# 以温度—压力作为状态规格做闪蒸state.mixtureModellingMixtureModelling.MC___SINGLE_AEROSOL# 混合物建模方式# —— 步骤 2跑容器状态计算得到相态PureGas / 两相 / 加压液体——vesselStateCalculationVesselStateCalculation()vesselStateCalculation.materialmaterial# 复用上一段构造的物料vesselStateCalculation.statestate# 复用上面设定的状态resultCodevesselStateCalculation.run()# 返回 ResultCodeifresultCodeResultCode.SUCCESS:vesselStateCalculation.print_messages()# 打印该计算收集到的全部消息print( 容器状态计算成功)else:raiseSystemExit(容器状态计算失败请先读消息域排查)# —— 步骤 3组装容器几何与泄漏参数 ——vesselVessel()vessel.statevesselStateCalculation.outputState# 用上游计算结果作为状态vessel.materialvesselStateCalculation.material# 物料随上游一起传递vessel.vesselConditionsvesselStateCalculation.vesselConditions# 相态结论vessel.diameter4.0# 直径 mvessel.length7.0# 长度 mvessel.shapeVesselShape.HORIZONTAL_CYLINDER# 卧式圆筒容器vessel.liquidFillFractionByVolume0.0# 体积装量分数leakLeak()leak.timeVaryingOptionTimeVaryingOption.TIME_VARYING_RATE# 时变排放leak.holeDiameter0.05# 孔径 m# —— 步骤 4运行容器泄漏计算 ——vesselLeakCalculationVesselLeakCalculation()vesselLeakCalculation.leakleak# 映射泄漏对象vesselLeakCalculation.vesselvessel# 映射容器对象vesselLeakCalculation.dischargeParameters.flashAtOrificeFlashAtOrifice.DISALLOW_LIQUID_FLASH# 孔口闪蒸开关resultCodevesselLeakCalculation.run()# 执行ifresultCodeResultCode.SUCCESS:vesselLeakCalculation.print_messages()# 诊断信息recordsvesselLeakCalculation.dischargeRecords# 排放记录列表print( 排放记录条数,len(records))# 时变场景条数可变# 稳态场景说明稳态泄漏恒返回 2 条记录可用于快速断言fori,recordinenumerate(records[:3]):# 只打印前三条样例print(记录,i,record)# 具体字段以官方参考章为准else:raiseSystemExit(容器泄漏计算失败)工程纪律把「稳态 2 条记录」写进断言可以在批处理中低成本发现参数误配例如本想稳态却传了时变枚举。2.3 第三段用户自定义物料入库# 演示把自建组元写入用户物料库并直接生成含该组元的物料frompypws.materialsimport(getDIPPRComponents,getUserComponents,storeMaterialComponentAndCreateMaterial)# 先看库里已有什么DIPPR 组元与用户自建组元分别取回dippr_componentsgetDIPPRComponents()# 返回 MaterialComponentData 列表user_componentsgetUserComponents()# 用户自建组元列表print(DIPPR 组元数,len(dippr_components))print(用户组元数,len(user_components))# 取一条 DIPPR 组元数据作为模板骨架字段以官方参考章为准逐项补齐templatedippr_components[0]# 写入用户组元并顺带创建含该组元的物料返回新建的 Material 对象new_materialstoreMaterialComponentAndCreateMaterial(template)# 回读确认新物料已在用户物料体系中可被检索print(新物料,new_material.name)print(当前用户组元数,len(getUserComponents()))# 数量应增加 1此处必须强调边界官方公开材料只支撑GUI 层的用户自定义源项 / 可调参数与物料层user-defined material、混合物的 API 传参更深的源项脚本级扩展能力未见官方证据本系列不作主张。三、常见报错与排查现象 1脚本能连上但所有计算都返回失败消息域提示单位异常。根因压力传了表压或英制换算值。官方明确容器实体中的压力为绝对压力是为了与其在闪蒸规格、最终状态排放等场景的用途保持一致。解法压力统一以 Pa 绝压传入温度统一开尔文建立「本地单位 → SI」的单一转换函数并在入口处一次性完成。现象 2组元数量与组分列表不符或摩尔分数合计不为 1。根因componentCount与components手工维护不同步或从 Excel 读入时按质量分数填进了摩尔分数字段。解法如 2.1 段那样在构造后立即断言len(components) componentCount与归一化校验。现象 3想复用上游结果却重算了相态导致下游结果漂移。根因下游容器对象只赋了几何值忘了把outputState、material、vesselConditions从上游带过来。解法固定「三件套传递」模式即vessel.state、vessel.material、vessel.vesselConditions一律取上游计算属性。现象 4时变场景结果条数与预期不符。根因时变泄漏的记录条数本身可变官方示例为 118 条按稳态的 2 条去断言必然失败。解法按TimeVaryingOption分支断言时变场景只校验「条数 0 且单调时间轴」。现象 5同一物质在两次运行里结果不同。根因一次用官方物料体系里的物料一次用自建组元构造的物料两条路径的物性来源不同。解法规定同一物质在项目内只能有一种表示方式并在工况表的来源列里固定下来对关键物质建立一个「黄金场景」做交叉核对铁律 7。四、动手练习把 2.2 段的物料换成单组元甲烷componentCount 1观察vesselConditions的取值变化并记录相态结论。将leak.holeDiameter从 0.05 m 改为 0.02 m 与 0.10 m各跑一次时变泄漏比较dischargeRecords条数与初段排放速率的相对变化趋势。用getAllCasIds()找出一个你项目常用的物料用getMaterialByCasId()取回再据此构造Material与 GUI 中同名物料的结果做一次一致性核对铁律 7。五、小结与下一篇预告本篇确立了源项的三要素输入契约物料 / 几何工况 / 泄漏、稳态与时变在结果结构上的硬差别2 条 vs 可变条数、孔口闪蒸与相态判定的确切字段位置以及物料库与用户自定义物料的脚本通路。下一篇07 气象与地形工况将补齐源项之外的第二组「环境输入」Weather、大气稳定度、地面条件与建筑/阻塞区并给出气象组合的笛卡尔积工程化写法。本篇认知问题回显FAQQ1源项有几种「族」容器、储罐、管道、长输管道、埋地管道差在哪一层答官方 PyPWS 把工作对象分成物理对象vessel 或 pipe与关联数据对象leaks、pipe ruptures、weathers泄漏计算据此分为 vessel leak 与 pipe breach 两大调用。容器与储罐同属Vessel这一类物理对象差别主要体现在几何与装量字段如liquidFillFractionByVolume管道类以管道对象加破口数据对象表达长输管道与埋地管道属更细分的能力其中埋地管道为 8.x 历史锚点9.x 的适用性以官方发布说明与 User Manual 为准。Q2稳态泄漏与时变泄漏在结果结构上如何体现答由Leak.timeVaryingOption控制。稳态泄漏恒返回 2 条 discharge records时变泄漏记录条数随计算步长变化官方甲烷时变示例为 118 条。官方对 vessel leak 的定位是「压力容器或储罐的稳态或时变泄漏并包含从容器孔口到大气条件的膨胀建模」因此两类泄漏共用同一计算对象只是记录条数与下游取数方式不同。Q3标况、滞止、闪蒸、两相这些术语对应哪些字段和枚举答相态结论由 Vessel state 计算给出输出为 Pure gas、Stratified Two-Phase vessel、Pressurised Liquid 三类通过vesselConditions传给下游。状态规格由State.flashFlag指定示例用FluidSpec.TP即温度—压力规格孔口处是否允许液体闪蒸由VesselLeakCalculation.dischargeParameters.flashAtOrifice指定示例值FlashAtOrifice.DISALLOW_LIQUID_FLASH混合物建模方式由State.mixtureModelling指定示例值MixtureModelling.MC___SINGLE_AEROSOL。Q4Phast™ 的 2,000 物料从哪来脚本里怎么查怎么用答规模与来源以官方产品页为准——2,000 物料、物性源自 DIPPR 数据库。脚本侧用 materials 模块的getAllCasIds()列出全部名称与 CAS 号用getMaterialByCasId(casId)取回具体 MaterialgetDNVComponents()与getDIPPRComponents()分别取回 DNV 组元与 DIPPR 组元数据getComponentById/getComponentByName/getComponentByCasId用于精确定位单个组元。Q5用户自定义物料与混合物在脚本里如何落地边界在哪答落地方式是「组元数据 写入函数」storeMaterialComponent(...)写入组元storeMaterialComponentAndCreateMaterial(...)写入组元并直接创建含该组元的 Material多组分物料用Material.componentCount与Material.components表达物性模板示例取PropertyTemplate.PHAST_MC。边界是可编程面只到物料与 API 传参层更深的源项脚本级扩展能力没有官方证据因此本系列不主张该类能力。Q6哪些源项细节必须回到官方 User Manual答主要包括三类。一是研究文件与工程层的命名/结构细节二是各源项族在 9.x 中的界面级参数与默认值三是实体属性表的完整字段与单位清单。官方 PyPWS 参考文档给出了属性名与「始终 SI 单位」的纪律但完整字段表与界面语义应回到 Knowledge Centre 的 User Manual 与 Technical Documentation 核对。