PHAST-SAFETI二次开发教程03界面与数据模型——Study Folder / Study / Scenario 与参数树导航版本声明块工具与软件Phast™ 与 Safeti™ 的版本主线为 9.x9.0 于 2023 年 12 月发布9.1 增补粉尘爆炸与个体风险类度量历史锚点版本为 8.x。界面措辞在各小版本间可能微调一律以官方用户手册为准。语言与环境官方 Python 库 PyPWS 要求 Python 3.11 及以上数据层次与字段命名以官方 PyPWS 参考文档为对照。本文目标把点点点的界面翻译成可编程的数据模型让你在写脚本之前就知道每个输入项在对象世界里对应什么。一句话结论Phast™ 与 Safeti™ 的数据层次是 Study Folder 收纳 Study、Study 收纳 Scenario 的三层结构以官方用户手册表述为准其中 Study 承载这一组场景共用的假设物料库选择、气象工况集、地面条件、结果选项Scenario 承载这一个工况的差异量源项与泄漏参数、点火假设等把这个层次理解成默认值与覆盖值的关系你就同时得到了 GUI 的操作逻辑与脚本的实体组织方式。〇、本篇要解决的认知问题Q1Study Folder / Study / Scenario 三层各自是什么为什么值得分成三层而不是一张平表Q2一个 Scenario 的输入区到底包含哪几类内容它们的先后顺序为什么不能随意调换Q3全局设置与局部覆盖谁赢这种默认值加覆盖的机制对批量场景意味着什么Q4结果视图有哪几种形态它们各自适合承接什么产物哪些能被自动化管道消费Q5界面上的参数树里哪些点是可自动化点怎么判断一个输入项能不能被脚本设置一、机制解析1.1 三层数据层次容器、研究、场景官方用户手册用 Study Folder / Study / Scenario 组织数据。把它画出来结构非常直观Study Folder一个容器通常对应一个项目、一个厂区或一次交付 |-- Study一个研究一组可相互比较的场景共享大部分假设 | |-- Scenario 1一个工况例如V-101 10mm 孔泄漏夏季风速 3 m/s | |-- Scenario 2同一泄漏在不同气象下的对照 | |-- Scenario N | -- 结果视图2D 图 / 3D 视图 / 地图与 plot plan / 表格 / Word 与 Excel 报告 |-- Study另一个研究例如换一套物料或换一套气象工况集 -- Study ...三层的分工可以总结成一句话层次语义典型承载内容变更频率Study Folder容器项目级归档、跨研究组织最低Study共用假设气象工况集、地面条件、结果选项、物料库范围中Scenario单个工况物料与源项细节、点火假设、局部覆盖项最高为什么分成三层因为工程实践本来就是同一套假设下比较多个工况。如果只有一张平表你改一次气象就要改一百行有了 Study 层你改一处一百个 Scenario 全部继承。1.2 场景输入区的四类内容与设置顺序一个 Scenario 的输入区参数树通常按下列顺序组织。这个顺序不是装饰它反映了模型链路的依赖方向第 05 篇会展开顺序输入类别关键项为什么排在这个位置1物料Material物料选择、组分、相态与物性来源后续所有计算都以物料物性为起点2源项Source Term / Discharge容器或管道形态、容积与充装、孔径、泄漏高度、隔离与放空由物料与容器状态推导泄漏速率3气象与地形Weather风速、大气稳定度、地面与基底条件、建筑与阻塞区扩散与后果都需要气象输入4点火与结果选项Ignition / Results点火假设、需要输出的结果类型决定效应计算与出图内容经验法则当你排查结果看起来不对时按这个顺序从上往下查——物料错了后面全错源项错了结论量级全变气象错了影响范围形状结果选项错了只是该出的图没出。按链路顺序排查比随机翻参数树快十倍。1.3 全局与局部默认值加覆盖界面里同一参数常常出现在多个层级Study 层设一次Scenario 层可以再设一次。这就是全局设置与局部覆盖的关系。规则是越靠近叶子的设置优先级越高属情景覆盖研究、研究覆盖文件夹。参数类型建议放在哪层理由结果选项要输出哪些量Study 层同一研究内通常统一便于批量汇总气象工况集Study 层批量扫描的公共维度地面与基底条件Study 层必要时单点覆盖同一厂区一般一致孔径、泄漏高度、相态假设Scenario 层这是工况差异的本质单点特殊物料Scenario 层少数场景有特殊物料时只覆盖个别场景对批量化的意义这条机制决定了你的参数矩阵应该怎么切。放在 Study 层的维度是乘法放在 Scenario 层的维度是具体取值——第 08 篇的 Excel 导入与第 13 篇的批处理工程化都建立在这个切分之上。铁律 10能力边界不越界不要假设界面上的每一项都能被脚本设置。能自动化的输入项必须能在官方接口中找到对应实体或字段找不到的就老老实实留在 GUI 里。把哪些要手工、哪些要脚本划清楚比追求 100% 自动化更重要。1.4 结果视图五种形态五种用途视图形态适合承接什么自动化友好度2D 曲线图浓度随时间/距离的变化、热辐射剖面中可导出数据后自绘3D 视图云团形状、火焰几何的直观检查低用于人工判断地图与 plot plan厂区布置叠加结果等值线、受体位置中需先声明 GIS 坐标基准结果表格关键量的数值清单高最适合进数据管道Word / Excel 报告交付物、评审材料高Excel 尤其适合批量汇总选择策略把结果表格与 Excel当作自动化管道的目标产物把2D/3D/地图当作人工审查与交付配图。不要在脚本里生成截图去做数值比对——那既不稳健也无法定位差异。1.5 界面层级到可自动化输入项的映射这是本篇最重要的一张表它是第 16 篇 API 实体讲解的前置铺垫。下表右列只写官方已公开的实体名来自官方 PyPWS 参考文档未列出的项表示本系列未获官方证据留待 GUI铁律 2界面层级界面上的输入项可自动化对应Scenario物料与组分Material、MaterialComponentScenario物料状态温度、压力、相态State、枚举FluidSpecScenario容器形态与充装Vessel、枚举VesselShape、VesselConditionsScenario泄漏参数孔径、高度等Leak、枚举TimeVaryingOption、FlashAtOrificeScenario泄漏模型选择容器泄漏等VesselLeakCalculationStudy气象工况Weather、枚举AtmosphericStabilityClassStudy地面与基底条件Substrate、枚举SurfaceType、PoolSurfaceTypeStudy池火类型与热辐射类型枚举PoolFireType、RadiationTypeStudy等值线与分辨率设置枚举ContourType、Resolution结果射流火与热辐射剖面JetFireCalculation、RadiationTransectCalculation运行成功判定与诊断消息run()返回ResultCode、print_messages()二、完整操作与脚本/API 代码逐段剖析2.1 参数树导航操作步骤清单步骤 1 新建 Study Folder命名采用“项目代号_阶段”规则例如 PRJ-A_FEED 步骤 2 在文件夹下新建 Study命名包含“物料族 场景族”例如 LPG_TankFarm 步骤 3 在 Study 层先把“共用假设”设好气象工况集、地面与基底条件、结果选项 步骤 4 在 Study 下新建 Scenario命名包含“设备号 释放类型 尺寸”例如 V101_LEAK_10mm 步骤 5 在 Scenario 层只设“差异量”物料与状态、容器与充装、孔径与泄漏高度、点火假设 步骤 6 运行单个 Scenario确认结果无异常后再复制出其余 Scenario 步骤 7 复制时保持参数树结构一致仅改动差异字段保证场景间可比 步骤 8 在结果视图切换 2D / 3D / 地图 / 表格四种形态确认哪些产物要进入交付包 步骤 9 导出 Excel 结果表作为后续批量汇总的模板基准 步骤 10 记录“哪些项已能从脚本设置、哪些必须手工”写入项目文档见 §1.5 映射表2.2 场景即数据用一张字典描述一个 Scenario要把界面变成脚本第一步不是写代码而是把界面上的输入写成结构化数据。下面的形态在任何语言里都通用scenario_spec一个 Scenario 的完整描述 -- material : {组分列表, 相态假设, 物性来源} - 对应界面物料Material / MaterialComponent -- state : {温度, 压力, 相态} - 对应界面物料状态State / FluidSpec -- vessel : {形状, 容积, 充装比例, 条件} - 对应界面容器Vessel / VesselShape / VesselConditions -- leak : {孔径, 泄漏高度, 时变选项, 闪蒸假设} - 对应界面泄漏Leak / TimeVaryingOption / FlashAtOrifice -- weather : {风速, 大气稳定度, 地面与基底条件} - 对应界面气象与地形Weather / Substrate / SurfaceType -- results : {需要的效应类型, 等值线类型, 分辨率} - 对应界面结果选项PoolFireType / RadiationType / ContourType / Resolution -- meta : {场景编号, 设备号, 版本, 备注} - 对应界面命名与项目文档纯工程管理字段为什么先做这一步因为界面里看得见的输入和脚本里传得进的实体是同构的。当你把场景写成上面这棵树你实际上已经完成了 80% 的 API 对接设计——剩下 20% 是把每棵子树映射到官方实体见 §2.3并处理单位与枚举取值。最佳实践为每一类场景建立一份场景规范模板可以是 CSV、YAML 或 Excel 模板并把它与 GUI 的参数树逐项对齐。模板字段名与官方实体名保持一致这样第 08 篇的 Excel 导入与第 17 篇的 PyPWS 流水线可以用同一份数据源避免两套字段名各说各话。2.3 用官方实体搭建场景骨架Python下面的脚本演示把场景字典映射成官方实体的骨架。注意实体的构造参数名与必填项以官方 PyPWS 参考文档为准铁律 2本代码的价值在于展示层次如何落到对象上而不是提供可照抄的签名。# scenario_skeleton.py —— 把“场景字典”映射成官方实体骨架# 说明本脚本演示 Study/Scenario 的层次如何落到对象上# 各实体的构造参数名与必填项以官方 PyPWS 参考文档为准铁律 2。frompypws.entitiesimport(# 官方实体构成一个场景的零件Material,# 物料含组分MaterialComponent,# 物料组分State,# 物料状态温度、压力、相态Vessel,# 容器形状、容积、充装、条件Leak,# 泄漏参数孔径、高度、时变选项Weather,# 气象工况风速、大气稳定度Substrate,# 地面与基底条件)frompypws.enumsimport(# 官方枚举把界面上的下拉选项变成取值FluidSpec,# 流体状态表示方式VesselShape,# 容器形状VesselConditions,# 容器条件TimeVaryingOption,# 时变泄漏选项FlashAtOrifice,# 孔口闪蒸假设AtmosphericStabilityClass,# 大气稳定度分类SurfaceType,# 地面类型PoolSurfaceType,# 池体表面类型)defbuild_scenario(study_defaults:dict,scenario:dict)-dict:按“Study 提供默认值、Scenario 提供覆盖值”的规则组装一个场景。merged{**study_defaults,**scenario}# 关键机制场景覆盖研究默认值§1.3components[# 逐组分构建物料组分对象MaterialComponent(**c)forcinmerged[components]]# 组分参数以官方参考文档为准materialMaterial(**merged[material])# 物料对象承载组分与相态设置stateState(**merged[state])# 状态对象温度、压力与相态vesselVessel(**merged[vessel])# 容器对象形状/容积/充装/条件leakLeak(**merged[leak])# 泄漏对象孔径、高度、时变选项weatherWeather(**merged[weather])# 气象对象风速与大气稳定度substrateSubstrate(**merged[substrate])# 地面与基底对象return{# 返回场景骨架供后续计算对象使用components:components,# 组分供物料校验material:material,# 物料state:state,# 状态vessel:vessel,# 容器leak:leak,# 泄漏weather:weather,# 气象substrate:substrate,# 地面与基底}if__name____main__:study_defaults{# Study 层这一组场景共用的假设weather:{windSpeed:3.0},# 风速取 SI 单位铁律 4substrate:{},# 地面条件沿用研究默认results:{contours:concentration},}scenario{# Scenario 层这一个工况的差异量material:{},# 物料覆盖留空表示沿用默认state:{},# 状态覆盖vessel:{},# 容器覆盖leak:{holeDiameter:0.01},# 10 mm 孔径单位为米SI}skeletonbuild_scenario(study_defaults,scenario)print(场景骨架已构建零件数:,len(skeleton))# 打印零件数量作为结构完整性检查逐行要点{**study_defaults, **scenario}这一行就是全局设置加局部覆盖的代码形态——理解它就理解了整个数据层次导入语句把官方实体与枚举分开列出是为了让后续脚本一眼看出哪些是可构造的实体、哪些只是取值域所有量值一律按 SI 单位填写铁律 410 mm 写成 0.01 m避免量级事故。三、常见报错与排查报错 3-1批量场景结果互相污染。现象改了某个 Scenario 的物料结果另一个 Scenario 也变了。根因把本该放在 Scenario 层的差异量设在了 Study 层全局于是覆盖变成了继承。解法用 §1.3 的分层表逐项复核——差异量必须落在 Scenario 层共用假设才放 Study 层。报错 3-2结果视图里该有的图没出。现象计算跑完了但缺少某一类结果例如没有热辐射图。根因结果选项要输出哪些效应类型、等值线类型未开启或分辨率设置过低导致视图稀疏。解法回到 §1.2 的第四类输入检查结果选项与等值线、分辨率枚举取值不要怀疑模型算错了——先确认你有没有要求它输出。报错 3-3脚本里构造实体的参数名报错未知关键字或缺少必填项。现象TypeError类错误。根因实体构造参数名与必填项以官方 PyPWS 参考文档为准凭记忆猜名称几乎一定出错。解法打开官方 PyPWS 参考文档逐项对照把参数集中在字典里如 §2.3 的做法可以一次性看清缺了哪个键。报错 3-4地图视图与 plot plan 叠加时位置错位。现象等值线与厂区布置图对不上。根因GIS 坐标基准未声明或与底图不一致铁律 4。解法在导入地图或布置图前先明确坐标系与投影把基准写进项目文档位置问题一律先在坐标层面排查不要先去调模型参数。报错 3-5“我以为改的是全局结果只改了一个场景”。现象希望在研究层面统一改动实际只生效于当前场景。根因在参数树中误在 Scenario 层做了局部覆盖局部值优先级更高。解法查看参数树上哪一层有值局部有值即覆盖修复方式是删除局部值让它回落继承而不是在上一层再改一遍。四、动手练习练习 1三层落地为你的项目建一个 Study Folder、两个 Study、每个 Study 下三个 Scenario。判定三个 Scenario 共享的气象与结果选项只设一次差异量全部落在 Scenario 层。练习 2分层复核用 §1.3 的分层表逐项标注你项目里的参数位置找出至少一处放错层的参数并修正。判定能说明修正前后哪些场景的行为发生了变化。练习 3场景即数据按 §2.2 的模板把两个真实场景写成结构化文件CSV 或 YAML。判定字段名与 §1.5 映射表中的官方实体名可一一对应无自造字段。练习 4视图选择为你的交付包设计视图组合哪几个量走表格与 Excel、哪几个量走 2D/3D 图、要不要地图叠加。判定能说明每个产物将来由人工还是由管道消费。练习 5可自动化点盘点对照 §1.5 映射表列出你项目里能自动化与必须手工的输入项并各举一例。判定对必须手工的项能引用官方证据缺失未确证作为理由而不是凭感觉。五、小结与下一篇预告本篇完成了从界面到数据模型的翻译三层层次Study Folder 收纳 Study、Study 收纳 Scenario、四类输入与设置顺序物料 → 源项 → 气象与地形 → 结果选项顺序即链路依赖方向、全局与局部的覆盖关系越靠近叶子优先级越高决定参数矩阵怎么切、五种结果视图表格与 Excel 最适合进数据管道以及一张界面层级与可自动化输入项的映射表。第 04 篇《第一个后果分析》将把本篇的骨架填上血肉用最小可跑场景压力容器、储罐或管道泄漏走完整条链路逐项讲源项参数孔径、相态、隔离与放空、逐类讲结果量浓度、火焰长度、池径、热辐射、闪火、超压与冲量、毒性剂量与致死并给出与第 17 篇 PyPWS 流水线同场景的对照钩子。本篇认知问题回显FAQQ1Study Folder / Study / Scenario 三层各是什么为什么要分三层A官方用户手册以 Study Folder、Study、Scenario 组织数据Study Folder 是容器通常对应一个项目、厂区或一次交付Study 是一个研究承载这一组场景共用的假设气象工况集、地面条件、结果选项、物料库范围Scenario 是单个工况承载差异量物料与状态细节、源项与泄漏参数、点火假设等。分三层是因为工程实践本身就是同一套假设下比较多个工况若只有一张平表改一次气象要改上百行。Q2一个 Scenario 的输入区包含哪几类内容顺序为什么不能随意调换A通常按四类组织物料选择与组分、相态、物性来源、源项容器或管道形态、容积与充装、孔径、泄漏高度、隔离与放空、气象与地形风速、大气稳定度、地面与基底条件、建筑与阻塞区、点火与结果选项点火假设、需要输出的结果类型。顺序反映模型链路的依赖方向物料是计算起点源项由物料与容器状态推导扩散与后果都需要气象结果选项决定输出内容。因此排查问题时应按此顺序从上往下查。Q3全局设置与局部覆盖谁赢这对批量场景意味着什么A越靠近叶子的设置优先级越高即事件覆盖研究、研究覆盖文件夹。对批量的意义是放在 Study 层的维度是乘法一次设置全部场景继承放在 Scenario 层的维度是具体取值每个场景的差异参数矩阵应按这条规则切分。若把差异量误设到 Study 层就会出现改一个场景另一个场景也跟着变的污染现象。Q4结果视图有哪几种形态各自适合承接什么产物A五种。2D 曲线图适合浓度随距离或时间的变化、热辐射剖面3D 视图适合云团形状与火焰几何的人工检查地图与 plot plan 适合厂区布置叠加等值线与受体位置但需先声明 GIS 坐标基准结果表格适合关键量的数值清单自动化友好度最高Word 与 Excel 报告适合交付物与批量汇总其中 Excel 尤其适合批量回收。建议把表格与 Excel 当作自动化管道目标产物把 2D/3D/地图当作人工审查与交付配图。Q5参数树里哪些是可自动化点怎么判断A判断标准是该项能否在官方接口中找到对应实体或字段。官方已公开的对应关系包括物料与组分对应 Material / MaterialComponent状态对应 State 与枚举 FluidSpec容器对应 Vessel 与枚举 VesselShape / VesselConditions泄漏对应 Leak 与枚举 TimeVaryingOption / FlashAtOrifice气象对应 Weather 与 AtmosphericStabilityClass地面条件对应 Substrate 与 SurfaceType / PoolSurfaceType结果选项对应 PoolFireType / RadiationType / ContourType / Resolution。找不到对应实体的项就留在 GUI 手工操作不要假设它能被脚本设置。