企业官网建设流程全解析

PHAST-SAFETI二次开发教程（03）：界面与数据模型——Study Folder / Study / Scenario 与参数树导航

版本声明块

• 工具与软件：Phast™ 与 Safeti™ 的版本主线为 9.x（9.0 于 2023 年 12 月发布，9.1 增补粉尘爆炸与个体风险类度量）；历史锚点版本为 8.x。界面措辞在各小版本间可能微调，一律以官方用户手册为准。
• 语言与环境：官方 Python 库 PyPWS 要求 Python 3.11 及以上；数据层次与字段命名以官方 PyPWS 参考文档为对照。
• 本文目标：把"点点点的界面"翻译成"可编程的数据模型"，让你在写脚本之前就知道每个输入项在对象世界里对应什么。

一句话结论：Phast™ 与 Safeti™ 的数据层次是 Study Folder 收纳 Study、Study 收纳 Scenario 的三层结构（以官方用户手册表述为准），其中 Study 承载"这一组场景共用的假设"（物料库选择、气象工况集、地面条件、结果选项），Scenario 承载"这一个工况的差异量"（源项与泄漏参数、点火假设等）；把这个层次理解成"默认值与覆盖值"的关系，你就同时得到了 GUI 的操作逻辑与脚本的实体组织方式。

〇、本篇要解决的认知问题

• Q1：Study 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 层，你改一处，一百个 Scenario 全部继承。

1.2 场景输入区的四类内容与设置顺序

一个 Scenario 的输入区（参数树）通常按下列顺序组织。这个顺序不是装饰，它反映了模型链路的依赖方向（第 05 篇会展开）：

经验法则：当你排查"结果看起来不对"时，按这个顺序从上往下查——物料错了后面全错，源项错了结论量级全变，气象错了影响范围形状，结果选项错了只是"该出的图没出"。按链路顺序排查，比随机翻参数树快十倍。

1.3 全局与局部：默认值加覆盖

界面里同一参数常常出现在多个层级：Study 层设一次，Scenario 层可以再设一次。这就是全局设置与局部覆盖的关系。规则是：越靠近叶子的设置优先级越高（属情景覆盖研究、研究覆盖文件夹）。

对批量化的意义：这条机制决定了你的参数矩阵应该怎么切。放在 Study 层的维度是"乘法"，放在 Scenario 层的维度是"具体取值"——第 08 篇的 Excel 导入与第 13 篇的批处理工程化都建立在这个切分之上。

铁律 10（能力边界不越界）：不要假设界面上的每一项都能被脚本设置。能自动化的输入项必须能在官方接口中找到对应实体或字段；找不到的，就老老实实留在 GUI 里。把"哪些要手工、哪些要脚本"划清楚，比追求 100% 自动化更重要。

1.4 结果视图：五种形态，五种用途

选择策略：把"结果表格与 Excel"当作自动化管道的目标产物，把"2D/3D/地图"当作人工审查与交付配图。不要在脚本里生成截图去做数值比对——那既不稳健，也无法定位差异。

1.5 界面层级到可自动化输入项的映射

这是本篇最重要的一张表，它是第 16 篇 API 实体讲解的前置铺垫。下表右列只写官方已公开的实体名（来自官方 PyPWS 参考文档），未列出的项表示本系列未获官方证据，留待 GUI（铁律 2）：

二、完整操作与脚本/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.3）components=[# 逐组分构建物料组分对象MaterialComponent(**c)forcinmerged["components"]]# 组分参数以官方参考文档为准material=Material(**merged["material"])# 物料对象：承载组分与相态设置state=State(**merged["state"])# 状态对象：温度、压力与相态vessel=Vessel(**merged["vessel"])# 容器对象：形状/容积/充装/条件leak=Leak(**merged["leak"])# 泄漏对象：孔径、高度、时变选项weather=Weather(**merged["weather"])# 气象对象：风速与大气稳定度substrate=Substrate(**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 单位（铁律 4）"substrate":{},# 地面条件沿用研究默认"results":{"contours":"concentration"},}scenario={# Scenario 层：这一个工况的差异量"material":{},# 物料覆盖（留空表示沿用默认）"state":{},# 状态覆盖"vessel":{},# 容器覆盖"leak":{"holeDiameter":0.01},# 10 mm 孔径，单位为米（SI）}skeleton=build_scenario(study_defaults,scenario)print("场景骨架已构建，零件数:",len(skeleton))# 打印零件数量，作为结构完整性检查

逐行要点：{**study_defaults, **scenario}这一行就是"全局设置加局部覆盖"的代码形态——理解它，就理解了整个数据层次；导入语句把官方实体与枚举分开列出，是为了让后续脚本一眼看出"哪些是可构造的实体、哪些只是取值域"；所有量值一律按 SI 单位填写（铁律 4），10 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 流水线同场景的对照钩子。

本篇认知问题回显（FAQ）

Q1：Study 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 手工操作，不要假设它能被脚本设置。