PHAST-SAFETI二次开发教程（14）：自定义源项与物料——用户自定义源项、user-defined material 与混合物（MC）

PHAST-SAFETI二次开发教程14自定义源项与物料——用户自定义源项、user-defined material 与混合物MC版本声明块工具/软件Phast™ / Safeti™版本主线 9.x用户自定义源项在 9.0 有简化改进具体范围以官方发布说明为准语言/环境Python ≥ 3.11官方库 PyPWS包名pypws端点https://phastwebservices.dnv.com/api/analytics/v1/本文目标把自定义拆成「GUI 配置」与「官方 API 传参」两块说清各自能做什么、不能做什么一句话结论自定义的官方可编程面只有两块——GUI 层的用户自定义源项user-defined source与可调参数adjustable parameters以及物料层的官方 API 传参Material/MaterialComponent配PropertyTemplate混合物建模方式在State.mixtureModelling传入MixtureModelling混合物在脚本里用Material.componentCount与Material.components表达Multi-ComponentMC扩展用于复杂混合物与两相体系更深的源项脚本级扩展能力未见官方证据本系列不作主张。本篇铁律适用三级标注取自系列登记的 10 条[硬约束] 铁律 2 闭源事实纪律属性名与枚举名只取官方 PyPWS 参考文档口径未确证的字段与接口一律不写死。[硬约束] 铁律 3 只用官方接口自定义只经 GUI 配置与官方 APIPhast Web Services / PyPWS实现不引入第三方包装器。[强约束] 铁律 8 物理量不臆造自定义物性参数的来源必须登记不得凭经验填充。[提示] 铁律 7 改完必验自定义物料须与官方物料在同工况下做交叉回归。〇、本篇要解决的认知问题用户自定义源项在官方口径里是什么9.0 的「简化」指什么可调参数adjustable parameters怎么用它与 Scenario 是什么关系user-defined material 与代表物料representative material怎么选Multi-ComponentMC扩展解决什么问题什么时候必须用它混合物在官方 API 里怎么构造PropertyTemplate与MixtureModelling各管什么自定义的能力边界与验证要求是什么以下「认知问题回显FAQ」与上列问题一一对应、同序作答。一、机制解析1.1 自定义的三条路径与各自的能力边界自定义这四个字在工程实践中被用得很宽必须收窄成三条明确的路径① GUI 层用户自定义源项user-defined source ├── 在界面里定义一个源项而不是从既有的容器/管道源项族中选 ├── 9.0 对此有“简化”改进范围以官方发布说明为准 └── 边界配置能力不是编程接口 │ ② GUI 层可调参数adjustable parameters ├── 在同一个场景内把若干输入暴露为可调项 └── 边界可调 ≠ 新模型一个 Scenario 锁定一组取值 │ ③ API 层物料与混合物 ├── user-defined material把本项目特有的物料写进用户物料体系 ├── 多组分componentCount components └── 边界可编程面到「物料 API 传参」为止路径层级官方抓手可变范围明确不做的事用户自定义源项GUIuser-defined source源项输入与计算方式的选择不提供脚本级源项扩展接口可调参数GUIadjustable parameters同一场景内的可调输入项不产生新的物理模型物料自定义GUI APIuser-defined material组元构成与物性来源不自造物性数值这张表是能力边界的书面口径项目评审时若有人问「能不能用脚本写一个新的源项模型」答案必须回到这张表——不能。1.2 9.0 的简化改进保守口径官方 9.0 更新材料述及对用户自定义源项的简化改进。这里必须守住保守口径简化的是使用流程不是物理内核。工程含义有两点第一用户自定义源项的配置成本下降因此在项目里使用它的门槛降低但随之而来的责任上升——配置越容易越容易在缺乏依据时随手定义一个源项。因此第 2.1 节的输入清单与来源登记不是可选项。第二简化意味着界面表单可能发生调整历史的输入快照必须存档。否则界面一改老项目的自定义源项设置就再也无法原样复现。1.3 user-defined material 与代表物料物料自定义有两条互补的路子选择取决于「物性数据是否可获得」情形推荐做法理由物料在官方库中不存在但本项目有完整物性数据用 user-defined material登记组元与物性来源数据可得直接建模最准确物料是复杂混合物、物性数据不完整用代表物料representative material做保守替代缺数据时保守替代优于臆造物性物料在官方库中存在2,000 物料物性源自 DIPPR直接用官方物料可追溯性最好跨项目口径统一三行之外还有一条铁律级纪律同一物质在项目内只能有一种表示方式。要么统一用官方物料以 CAS 号定位要么统一用自建组元与用户自定义物料同一种物质在两张工况表里出现两种写法会让批处理的分组统计与风险贡献分解直接失真而这种错误在单场景调试时根本看不出来。1.4 Multi-ComponentMC扩展MC 扩展针对的是复杂混合物与两相体系的相行为当释放物是多组分混合物或泄漏过程中存在两相气液共存、闪蒸、气溶胶时单一组元的处理方式会产生系统性偏差。官方以多组分插件Multi-Component add-on的形式提供该能力。在数据模型里MC 相关的两个抓手是抓手所在对象作用示例取值PropertyTemplateMaterial决定按哪套物性模板处理该物料PropertyTemplate.PHAST_MCMixtureModellingState决定混合物的建模方式MixtureModelling.MC___SINGLE_AEROSOL注意这两者落在不同对象上物性模板属物料层混合物建模方式属状态层。这个分工很容易记混而记混的后果是把状态层的开关写进物料对象——语法可能通过语义已经错了。1.5 自定义的验证要求自定义带来的自由度必须用验证来平衡。三条验证动作缺一不可第一条黄金场景回归。为每个自定义源项或自定义物料建立一个固定工况的「黄金场景」任何自定义改动的效果都必须先在这个场景上体现出来并与改动前的版本对比。第二条与官方物料交叉核对。若自定义物料在物理上近似某个官方物料例如某混合物近似某纯组分把两者放在同一工况下比较关键指标火焰长度、辐射份额、扩散距离等相对偏差超过容差即须复核。第三条输入快照存档。自定义的来源就是自定义本身组元与摩尔分数、物性来源、可调参数取值、验证状态必须与结果一并归档否则半年后无法复现。二、完整操作与脚本逐段剖析2.1 第一段界面侧的自定义配置操作步骤步骤 1 先判断是否需要自定义能在官方物料库2,000 物料里找到的不自定义 步骤 2 若走用户自定义源项在界面中定义源项逐项填入输入并标注每项的单位与来源 步骤 3 若走可调参数把本次研究需要扫描的输入暴露为可调项其余保持固定 步骤 4 确认可调参数与 Scenario 的对应关系一个 Scenario 锁定一组取值不要在同一场景内留两个自由度 步骤 5 若走 user-defined material登记组元构成与物性来源缺数据的用代表物料替代 步骤 6 保存输入快照组元、摩尔分数、可调参数取值、来源、验证状态 步骤 7 建一个黄金场景作为该自定义项的固定回归基准 步骤 8 与最接近的官方物料做一次交叉核对记录关键指标的相对偏差 步骤 9 把快照、回归基线与核对结论一并归档再进入批量工况2.2 第二段用户自定义源项输入清单与可调参数登记说明本清单是项目侧的输入登记表用于管理自定义源项的输入与来源界面录入口径以官方 User Manual 为准。# -*- coding: utf-8 -*-# 演示登记「用户自定义源项输入清单」与「可调参数表」并做完整性校验importcsv# 标准库CSV 读写importyaml# 第三方 PyYAML契约落盘# —— 用户自定义源项输入清单每条输入都要有单位、来源与验证状态 ——SOURCE_INPUTS[{input:release_rate,unit:SI:kg/s,value:None,# 排放速率时间序列入口source:工艺数据-正常工况,verified:pending},{input:release_duration,unit:SI:s,value:None,# 释放持续时间source:操作规程-隔离时间,verified:pending},{input:phase,unit:-,value:two_phase,# 相态气/液/两相source:工艺数据-相态,verified:pending},{input:release_height,unit:SI:m,value:None,# 释放点高度source:总图-释放点标高,verified:pending},]# —— 可调参数表界面层可调项与 Scenario 的关系是「一个 Scenario 锁定一组取值」——ADJUSTABLE[{param:hole_diameter,unit:SI:m,options:[0.02,0.05],# 孔径可调档位source:设计基准-孔径系列},{param:isolation,unit:-,options:[none,esd_30s],# 隔离策略档位source:操作规程-隔离策略},]defvalidate_source_inputs(rows:list)-list:校验自定义源项输入单位声明、来源、验证状态三件套必须齐全。errors[]# 错误容器seenset()# 输入名集合forindex,rowinenumerate(rows,start1):# 逐条检查namestr(row.get(input,)).strip()# 输入名ifnotname:# 名称必填errors.append(第 %d 条input 名缺失%index)elifnameinseen:# 名称唯一errors.append(第 %d 条input 重复 %s%(index,name))else:seen.add(name)# 登记名称ifnotstr(row.get(unit,)).strip():# 单位必须声明errors.append(第 %d 条unit 未声明%index)ifnotstr(row.get(source,)).strip():# 来源可追铁律 9errors.append(第 %d 条source 未登记%index)ifrow.get(verified)notin(pending,verified):# 验证状态取值受限errors.append(第 %d 条verified 取值非法%index)returnerrors# 返回错误清单errorsvalidate_source_inputs(SOURCE_INPUTS)# 执行校验print(源项输入校验,errorsiferrorselse通过)# 打印结论assertnoterrors,自定义源项输入未通过校验# 硬门禁# —— 落成 YAML 契约清单 可调参数 能力边界声明 ——contract{source_type:user_defined_source,# 源项类型GUI 层配置capability_boundary:仅 GUI 层自定义源项与可调参数加官方 API 传参,# 能力边界显式声明source_inputs:SOURCE_INPUTS,# 输入清单adjustable_parameters:ADJUSTABLE,# 可调参数表}withopen(user_defined_source_contract.yaml,w,encodingutf-8)asfh:yaml.safe_dump(contract,fh,allow_unicodeTrue,sort_keysFalse)# 写 YAML 契约# —— 同步落一份 CSV便于在评审会上用 Excel 直接打开 ——withopen(user_defined_source_inputs.csv,w,newline,encodingutf-8-sig)asfh:writercsv.DictWriter(fh,fieldnames[input,unit,value,source,verified])writer.writeheader()# 表头forrowinSOURCE_INPUTS:# 逐条写出writer.writerow(row)# 写整行print(源项输入 %d 条可调参数 %d 条%(len(SOURCE_INPUTS),len(ADJUSTABLE)))# 规模确认要点capability_boundary这一字段是刻意写进契约的。它把「本项目只使用 GUI 层自定义与官方 API 传参」写成显式约定避免后续有人在这条路径上继续“扩展”出并不存在的能力。2.3 第三段用官方 API 构造混合物# -*- coding: utf-8 -*-# 演示用官方 API 构造多组分混合物并区分物性模板物料层与建模方式状态层frompypws.entitiesimportMaterial,MaterialComponent,State# 官方实体frompypws.enumsimportPropertyTemplate,MixtureModelling,FluidSpec# 官方枚举defbuild_mixture(components:list,template)-Material:由组元清单构造混合物物料层。 components[(名称, 摩尔分数), ...]template物性模板如 PHAST_MC materialMaterial()# 声明物料对象material.componentCountlen(components)# 组元数与列表长度一致forname,fractionincomponents:# 逐组元componentMaterialComponent()# 声明组元对象component.namename# 组元名称官方写法component.moleFractionfraction# 摩尔分数无量纲material.components.append(component)# 追加到组元列表material.propertyTemplatetemplate# 物性模板决定按哪套物性处理returnmaterial# 返回物料对象# —— 构造一个三组分混合物复杂混合物示意数值须来自项目工艺数据铁律 8——mixbuild_mixture([(METHANE,0.70),(ETHANE,0.20),(PROPANE,0.10)],PropertyTemplate.PHAST_MC)# 多组分物性模板# —— 状态层混合物建模方式在 State 上而不是在 Material 上 ——stateState()# 声明状态对象state.pressure1.5e6# Pa绝压铁律 4state.temperature300.0# K铁律 4state.flashFlagFluidSpec.TP# 以温度—压力作为状态规格state.mixtureModellingMixtureModelling.MC___SINGLE_AEROSOL# 混合物建模方式示例取值# —— 一致性校验组元数、归一化、取值范围 ——assertlen(mix.components)mix.componentCount,组元数与 componentCount 不一致totalsum(c.moleFractionforcinmix.components)# 摩尔分数合计assertabs(total-1.0)1e-9,摩尔分数合计不为 1repr(total)# 归一化门禁forcinmix.components:# 逐组元范围检查assert0.0c.moleFraction1.0,摩尔分数越界c.name# 取值合法print(混合物组元,[c.nameforcinmix.components])# 确认构成print(物性模板,mix.propertyTemplate)# 确认物性模板print(混合物建模方式,state.mixtureModelling)# 确认建模方式这段最关键的设计是分层归属propertyTemplate挂在物料上mixtureModelling挂在状态上。把两者写反脚本仍可能跑通但得到的相行为不是你设定的那一种。2.4 第四段自定义物料入库与交叉回归# -*- coding: utf-8 -*-# 演示把自建组元写入用户物料体系并与官方物料做交叉核对frompypws.materialsimport(getDIPPRComponents,getUserComponents,# 物料库查询与写入函数storeMaterialComponentAndCreateMaterial)beforelen(getUserComponents())# 写入前用户组元数dipprgetDIPPRComponents()# 取回 DIPPR 组元数据列表assertdippr,DIPPR 组元列表为空请检查连接与权限# 前置检查templatedippr[0]# 取一条作为字段骨架new_materialstoreMaterialComponentAndCreateMaterial(template)# 写入组元并创建含它的物料afterlen(getUserComponents())# 写入后用户组元数assertafterbefore1,用户组元数未按预期增加写入可能未生效# 入库闭环断言print(新物料,new_material.name,用户组元数,before,→,after)# 打印入库结论defcompare_key_metrics(custom_result:dict,official_result:dict,tol:float)-list:比较自定义物料与官方物料在关键指标上的相对偏差返回超差项。 custom_result / official_result{指标名: 数值}tol允许相对偏差 outliers[]# 超差容器forkey,custom_valueincustom_result.items():# 逐指标official_valueofficial_result.get(key)# 取对应官方值ifofficial_valuein(None,0):# 缺值或以零为基准则跳过continue# 避免除零relabs(custom_value-official_value)/abs(official_value)# 相对偏差ifreltol:# 超过容差outliers.append({metric:key,custom:custom_value,# 记录超差项official:official_value,rel:round(rel,4)})returnoutliers# 返回超差清单# —— 交叉核对用近似代表物料做保守性验证数值为占位须来自实际回归——custom_metrics{flame_length:28.4,radiative_fraction:0.21}# 自定义物料关键指标official_metrics{flame_length:27.1,radiative_fraction:0.22}# 官方物料关键指标outlierscompare_key_metrics(custom_metrics,official_metrics,0.10)# 容差 10%print(超差项,outliersifoutlierselse无)# 打印回归结论# —— 边界声明本脚本只使用官方物料 API不存在脚本级源项扩展接口 ——print(能力边界自定义仅经 GUI 配置与官方 API 传参实现)# 显式声明边界交叉回归是自定义物料的准入条件不是可选项没有交叉回归的自定义物料其物性来源无法在评审时被验证用它算出的所有后果结论都缺少可验证性支撑。三、常见报错与排查现象 1自定义物料算出的结果与其他项目同类工况差异明显。根因自定义物料与官方物料是两条物性来源路径物性不一致导致相行为与后果量级偏移。解法按 2.4 节做关键指标交叉核对超差项逐个复核同一物质在项目内只保留一种表示方式。现象 2组元数量与componentCount不一致或摩尔分数合计不为 1。根因componentCount与components长度手工维护不同步或把质量分数填进了摩尔分数字段。解法构造后立即断言长度一致与归一化数据来自 Excel 时增加「分数类型」列并做转换校验。现象 3设了混合物建模方式结果却像单组元。根因把MixtureModelling写在Material上属状态层或物料未使用多组分物性模板。解法propertyTemplate挂物料、mixtureModelling挂状态两者同时设置后用相态输出来确认设置生效。现象 4界面升级后老项目的自定义源项设置无法原样复现。根因只依赖界面表单保存配置没有把输入快照落盘。解法把 2.2 节的 YAML/CSV 快照与结果一并归档快照的字段名与界面字段建立映射表维护。现象 5可调参数在同一场景里出现两个自由度结果无法归因。根因把多个本应固定的输入也暴露为可调项导致一次运行同时改变多个维度。解法遵循「一个 Scenario 锁定一组取值」的原则需要多维度扫描时交给第 13 篇的全因子设计在场景层展开。四、动手练习把 2.3 节的混合物改为四组分加入丁烷验证归一化断言与componentCount一致并打印组元清单。把PropertyTemplate从多组分模板改为单组分模板观察相态输出或运行结果的差异并记录差异现象。为compare_key_metrics()增加「按指标类型设定不同容差」的能力例如几何类指标容差更紧、比分类指标更松并用一组超差数据验证分类生效。五、小结与下一篇预告本篇划清了自定义的能力边界GUI 层的用户自定义源项与可调参数、物料层的官方 API 传参两条路径之外没有脚本级源项扩展接口混合物用Material.componentCount与Material.components表达物性模板挂物料、混合物建模方式挂状态Multi-ComponentMC扩展用于复杂混合物与两相体系自定义必须搭配黄金场景回归、交叉核对与输入快照三项验证。下一篇15 风险标准定制与影响分析配置将回到判据侧Individual Risk 与 LSIR 验收标准的定制方式、FN curve 基准与 ALARP 区带、建筑类型与占用者脆弱性OBRA以及 Explosions extension 的超压与热辐射超越曲线与频率等值线读取——只描述配置方式与来源不写死任何阈值数字。本篇认知问题回显FAQQ1用户自定义源项在官方口径里是什么9.0 的「简化」指什么答用户自定义源项user-defined source是 GUI 层的一种源项定义方式即在界面中定义一个源项而不是从既有的容器或管道源项族中选择官方 9.0 更新材料述及对该能力的简化改进。这里必须保持保守口径简化的是使用流程与配置成本不是物理内核同时因为界面表单可能调整历史的输入快照必须存档否则老项目设置无法原样复现。更深的源项脚本级扩展能力未见官方证据本系列不作主张。Q2可调参数怎么用它与 Scenario 是什么关系答可调参数adjustable parameters是在同一个场景内把若干输入暴露为可调项用于在不改变场景结构的前提下改变输入取值。它与 Scenario 的关系是「一个 Scenario 锁定一组取值」场景是工况的容器可调参数是场景内被允许变动的输入项若需要多维度同时变化应在场景层展开而不是在同一场景里留多个自由度否则结果无法归因。Q3user-defined material 与代表物料怎么选答按「物性数据是否可获得」选择。物料在官方库中不存在但项目有完整物性数据时用 user-defined material 并登记组元与物性来源物料是复杂混合物且物性数据不完整时用代表物料做保守替代避免凭经验臆造物性物料在官方库中存在时官方物料规模为 2,000物性源自 DIPPR直接使用官方物料可追溯性最好。无论走哪条路同一物质在项目内只能有一种表示方式。Q4Multi-ComponentMC扩展解决什么问题什么时候必须用它答MC 扩展针对复杂混合物与两相体系的相行为。当释放物是多组分混合物或泄漏过程存在两相气液共存、闪蒸、气溶胶时用单一组元的处理方式会产生系统性偏差此时应使用 MC 能力。官方以多组分插件Multi-Component add-on的形式提供该能力在数据模型上它体现为物料层的物性模板与状态层的混合物建模方式两个抓手。Q5混合物在官方 API 里怎么构造答分两层。物料层用Material与MaterialComponent构造material.componentCount与material.components表达组元构成material.propertyTemplate指定物性模板多组分场景示例取PropertyTemplate.PHAST_MC。状态层用State其flashFlag指定状态规格示例FluidSpec.TPmixtureModelling指定混合物建模方式示例MixtureModelling.MC___SINGLE_AEROSOL。构造后必须断言组元数与列表长度一致、摩尔分数归一化且各值落在 [0, 1]。Q6自定义的能力边界与验证要求是什么答边界有两条一是自定义只经 GUI 层的用户自定义源项与可调参数、以及物料层的官方 API 传参实现不存在脚本级的源项扩展接口二是物料自定义只处理组元构成与物性来源不臆造物性数值。验证要求三项黄金场景回归每个自定义项建立固定工况基准任何改动先在基准上对比、与官方物料的交叉核对近似官方物料时比较关键指标的相对偏差、输入快照存档组元、摩尔分数、可调参数取值、来源与验证状态与结果一并归档。