AFT二次开发教程15边界条件与规格对象参数化——Reservoir / Assigned Pressure / Control Valve版本与事实声明产品与版本AFT Fathom 15 / AFT Impulse 12当前本篇参数与数值映射引用官方Fathom 13帮助页Importing From ExcelTable 1/3/4正文当前版以官方文档为准。语言/环境Python 3.x openpyxl。本文目标读完能安全地把罐液位、定压点、控制阀设定点这类边界与规格写成可批量导入的变更表并避开超定/欠定与单位未打底两个坑。所有对象编号与数值为示例性建模不代表任何标准规定。一句话结论管网的外部世界由三类对象锚定——Reservoir罐/池参数为 Liquid Surface Elevation / Liquid Surface Pressure / Liquid Temperature / Cross-Sectional Area / Tank Bottom Elevation / Surface Elevation Type、**Assigned Pressure定压边界Pressure/Elevation/Temperature**与Assigned Flow定流边界Flow Rate/Elevation/Temperature而内部规格由Control Valve 的 Setpoint等承担批量改这些对象的铁律是单位/初值必须预置否则导入失败与规格不可叠加否则超定。〇、本篇要解决的认知问题Q1什么是边界对象与规格对象它们为什么在参数化里特别重要Q2Reservoir 的参数有哪些改液位和改罐底面积各自意味着什么Q3Assigned Pressure / Assigned Flow 与 Branch 的区别是什么该怎么选Q4为什么某些字段必须先有单位/初值才能导入Global Edit怎么配合Q5什么是超定/欠定它与删除错误Parameter conflict什么关系一、机制解析15.1 两类特殊对象管网模型里绝大多数对象是内部件管、弯头、三通、阀。但有少数对象定义了系统与外部世界的接口或某种约束它们对结果的影响是全局性的类别对象作用边界对象Reservoir定义液面/罐给定液面高度、液面压力、温度、罐截面积边界对象Assigned Pressure直接给定某点压力定压边界边界对象Assigned Flow直接给定某点流量定流边界规格对象Control Valve通过 Setpoint 控制某目标如下游压力/流量规格对象Pump变速/控压/控流通过 Control Setpoint 控制为什么它们特别重要边界与规格决定了方程组的已知量。改一个罐液位整个系统的流量分配可能重排改一个控制阀设定点工作点会移动。所以参数扫描时这些量往往是最有信息量的变量——也最容易因为单位/超定问题让整批跑挂掉。15.2 Reservoir 的参数层级官方 Table 1 给出的Reservoir参数Liquid Surface Elevation液面标高Liquid Surface Pressure液面压力Liquid Temperature液体温度Cross-Sectional Area横截面积Tank Bottom Elevation罐底标高Junction Name结点名C 型Sizing/Cost SettingI 型Surface Elevation TypeI 型语义解读工程改Liquid Surface Elevation改变可用压头重力驱动系统的驱动力来源直接改变流量改Liquid Surface Pressure改变罐内气相压力加压罐/常压罐的区别改Cross-Sectional Area Tank Bottom Elevation影响液位随时间变化的速率——这在XTSExtended Time Simulation模块下才有意义罐液位自动计算是 XTS 的能力。一个容易被忽略的点Surface Elevation Type是 I 型整数。它决定了标高是按什么基准解释的——批量改液位时若不注意这类类型型参数可能改了数却改了语义。凡是 I 型参数写之前都要确认它的取值域官方 Table 1 只给了类型码具体枚举以官方文档/界面为准。15.3 Assigned Pressure / Assigned Flow / Branch官方 Table 1 的相关条目对象参数节选Special ConditionAssigned PressurePressure、Elevation、Temperature、Design Factor、Initial Guess Pressure/Temperature、Junction Name、Sizing/Cost Setting官方表中未列Assigned FlowFlow Rate、Elevation、Temperature、Design Factor、Initial Guess Pressure、Junction Name、Sizing/Cost Setting0None、1ClosedBranchSource/Sink Flow Rate、Source/Sink Temperature、Elevation、Initial Guess Pressure/Temperature、Design Factor、Junction Name、Sizing/Cost Setting0None、1Closed怎么选工程判据你要这点压力固定如接市政管网、接某个恒压母管→Assigned Pressure你要这点流量固定如给定抽取量、给定注入量→Assigned Flow你要这点有外部进/出流但压力流量都没固定 →BranchSource/Sink。关键区别Assigned Pressure固定的是压力看流量结果Assigned Flow固定的是流量看压力结果。选错这两个物理问题就变了——这是参数化里最根本的一类错误不是数值错是问题本身错了。15.4 单位必须预置铁律 4 的原文出处官方Importing From Excel页末尾的 Note 是本系列铁律 4 的直接来源“In order for the junction to accept the changes, some fields must already contain data.”例如若你要改控制阀的 control setpoint该控制阀对象必须已经有一个 setpoint 与单位。目的确保使用正确的单位集。官方建议可先用Global Edit给这些字段填一个任意值再导入变更。机制解读AFT 的导入是按值改不是创建字段字段若从未设过值/单位它不知道该把50理解成 50 psi 还是 50 bar所以先在建模时打底再批量改。标准流程最佳实践建模阶段用 Global Edit 给所有待扫字段填一个合法占位值带上单位 ↓ 生成阶段Python 生成 AFT Transfer 变更表 ↓ 导入阶段File Import Excel Change Data → 看 Object Change Log15.5 超定/欠定与Parameter conflict水力学基本事实每个规格对象贡献一个约束。若你在同一个对象上同时固定了会冲突的两个量例如既固定控制阀目标、又用另一设置约束同一自由度系统会超定over-determined——求解器无从下手反之某些自由度缺少约束则欠定under-determined。官方错误表里的Parameter conflict就是这类冲突的一个具体表现官方举的例子是当该结点正在使用阻力曲线resistance curve时不能再设 loss value——因为两者都在定义同一个损失特性。工程纪律一个对象一种约束方式。选了控制阀的 Setpoint就别再叠一个等价的流量约束批量改参时要检查改完是否仍恰好一套约束。这是参数扫描里最容易悄悄引入的错误某一行的变更让模型从恰好变成超定整批里的这个工况就废了。二、完整代码与逐行剖析代码 15-1boundary_tpl.py边界对象变更模板 冲突预检# -*- coding: utf-8 -*- boundary_tpl.py —— 边界/规格对象变更模板与导入前冲突预检 参数与 Special Condition 取自官方 Table 1/3预检覆盖单位未打底、参数错配、规格叠加。 运行python boundary_tpl.py --selftest importsysfromopenpyxlimportWorkbook SHEETAFT TransferCOLS[Apply,Object Type,Object Number,Parameter,Change Code,Value,Scenario Path Name]# 官方 Table 1 节选边界/规格对象 - {参数: 类型码}BOUNDARY_PARAMS{Reservoir:{Liquid Surface Elevation:S,Liquid Surface Pressure:S,Liquid Temperature:S,Cross-Sectional Area:S,Tank Bottom Elevation:S,Surface Elevation Type:I,Junction Name:C},Assigned Pressure:{Pressure:S,Elevation:S,Temperature:S},Assigned Flow:{Flow Rate:S,Elevation:S,Temperature:S,Special Condition:I},Control Valve:{Setpoint:S,Loss When Fully Open:S,Special Condition:I},}# 官方 Table 3Special Condition - 整数SC_VALUES{Assigned Flow:{0:None,1:Closed},Control Valve:{0:None,1:Closed,2:Fully Open - No Control},}# 单位敏感字段官方明示必须先有数据/单位才能接受变更UNIT_SENSITIVE{Setpoint,Loss When Fully Open,Pressure,Flow Rate}defprecheck(rows:list)-list:静态预检参数错配、Special Condition 取值、单位敏感字段是否声明已打底。problems[]fori,rinenumerate(rows,2):ot,pr.get(Object Type),r.get(Parameter)ifotnotinBOUNDARY_PARAMS:problems.append((i,f未知/未登记的边界对象类型{ot}))continuetBOUNDARY_PARAMS[ot].get(p)iftisNone:problems.append((i,fInvalid parameter ID{p}不属于{ot}))continueifpSpecial Condition:valr.get(Value)ifvalnotinSC_VALUES.get(ot,{}):problems.append((i,fInvalid parameter value{ot}的 Special Condition f应为 {sorted(SC_VALUES.get(ot, {}))}当前{val!r}))ifpinUNIT_SENSITIVEandnotr.get(_prefilled,False):problems.append((i,f[铁律4]{p}属单位敏感字段须先用 Global Edit 预置单位/初值))ifnotr.get(Scenario Path Name):problems.append((i,缺少 Scenario Path Name))returnproblemsdefwrite_wb(rows:list,path:str):wbWorkbook();wswb.active;ws.titleSHEET ws.append(COLS)forrinrows:ws.append([r.get(c,)forcinCOLS])wb.save(path)defdemo_rows():return[{Apply:Yes,Object Type:Reservoir,Object Number:1,Parameter:Liquid Surface Elevation,Change Code:Set equal to value,Value:12.0,Scenario Path Name:rBase Scenario\US Units\HighLevel},{Apply:Yes,Object Type:Assigned Pressure,Object Number:9,Parameter:Pressure,Change Code:Set equal to value,Value:60.0,Scenario Path Name:rBase Scenario\US Units\HighLevel,_prefilled:True},{Apply:Yes,Object Type:Control Valve,Object Number:2,Parameter:Setpoint,Change Code:Set equal to value,Value:45.0,Scenario Path Name:rBase Scenario\US Units\HighLevel,_prefilled:True},]defselftest():rowsdemo_rows()assertprecheck(rows)[],precheck(rows)# 正例零问题# 反例 1Special Condition 非法值bad1rows[{Apply:Yes,Object Type:Control Valve,Object Number:3,Parameter:Special Condition,Change Code:Set equal to value,Value:9,Scenario Path Name:rB\X}]assertany(Invalid parameter valueinmfor_,minprecheck(bad1))# 反例 2单位敏感字段未预置bad2[{Apply:Yes,Object Type:Assigned Pressure,Object Number:9,Parameter:Pressure,Change Code:Set equal to value,Value:60.0,Scenario Path Name:rB\X}]assertany(铁律4inmfor_,minprecheck(bad2))write_wb(rows,boundary_selftest.xlsx)print(SELFTEST OK正例零问题Special Condition 非法值与未预置单位字段均被拦截。)print(样例参数域Control Valve.Special Condition ,SC_VALUES[Control Valve])if__name____main__:if--selftestinsys.argv:selftest()逐行剖析BOUNDARY_PARAMS把官方 Table 1 的四类边界/规格对象及其参数类型码结构化。只登记本篇讨论的四类比抄全更诚实——其余以官方文档为准。SC_VALUES把官方 Table 3 的Control Valve0/1/2与Assigned Flow0/1映射成字典预检直接查表。枚举写错是跑得通但物理错的头号来源必须拦。UNIT_SENSITIVE集合实现铁律 4 的程序化Setpoint / Loss When Fully Open / Pressure / Flow Rate这些必须先有单位的字段若没声明已打底_prefilled直接报错。这把记得先 Global Edit从人脑负担变成脚本强制。预检返回(行号, 原因)元组便于在 Excel 里定位。selftest()三个断言正例零问题、非法枚举被拦、未预置被拦。反例 2 用的正是官方 Note 里那个例子改 control setpoint。代码 15-2spec_conflict.py规格叠加预检# -*- coding: utf-8 -*- spec_conflict.py —— 规格叠加超定预检同一对象不许同时叠加等价约束。 运行python spec_conflict.py --selftest importsys# 经验规则这些参数组合若同时出现在同一对象上视为可能超定CONFLICT_PAIRS[({Setpoint,Loss When Fully Open}),# 同一控制阀既给目标又给固定损失特性({Pressure,Flow Rate}),# 同一点既定压又定流]defcheck(assignments:dict)-list:assignments: {(对象类型, 编号): {参数集合}} - 冲突列表。problems[]for(ot,num),paramsinassignments.items():forgroupinCONFLICT_PAIRS:ifgroupparams:problems.append(f{ot}{num}同时设置了{sorted(group)}可能超定/规格冲突)ifSpecial Conditioninparamsandlen(params)2:problems.append(f{ot}{num}Special Condition 与多个规格量并存请确认约束数1)returnproblemsdefselftest():ok{(Control Valve,2):{Setpoint}}assertcheck(ok)[]bad{(Control Valve,2):{Setpoint,Loss When Fully Open}}assertcheck(bad),规格叠加必须被检出bad2{(Assigned Pressure,9):{Pressure,Flow Rate}}assertcheck(bad2),定压定流必须被检出print(SELFTEST OK正常单规格放行两组叠加约束均被拦截。)if__name____main__:if--selftestinsys.argv:selftest()逐行剖析CONFLICT_PAIRS是本篇的工程经验编码属经验法则而非铁律它把哪些参数组合同现于一个对象可能超定写下来。注意用词可能——因为是否真超定取决于物理脚本只提示。check()的第二个规则更谨慎“Special Condition与多个规格量并存时请确认约束数1”——它不做断言只做提醒。工具替人缩小搜索范围但不替人做物理判断。selftest()用三组正常、控制阀叠加、定压定流覆盖正反例。三、常见报错与排查报错 15-1改 Control Valve 的 Setpoint 报错日志提示需要已有数据。现象导入失败/未生效。根因官方 Note——该字段必须先有 setpoint 与单位以保证单位集正确铁律 4。解法先用Global Edit给该控制阀填一个合法占位值再导入。报错 15-2报Parameter conflict。现象某参数改不了。根因与另一设置冲突官方例结点用阻力曲线时不能再设 loss value。解法确认该对象只保留一种约束方式先解除冲突设置再导。报错 15-3改完参数模型不收敛或结果离谱但日志没报错。现象批跑里某些工况废掉。根因变更后超定或欠定如既定了 Setpoint 又叠加等价流量约束。解法用spec_conflict.py预检每个规格对象确认约束数 1。报错 15-4把 Reservoir 液位当绝对高度结果压头算错。现象重力驱动流量异常。根因忽略了Surface Elevation TypeI 型等基准型参数对标高的解释。解法改标高前确认基准设置I 型参数不凭猜以官方文档/界面为准。报错 15-5本应定压的点用了 Assigned Flow物理问题被改掉。现象结果与预期完全不同但流程正常收敛。根因选错了对象类型——定压 vs 定流是两种不同的问题。解法按 15.3 判据重选对象这类错误不会有报错只能靠建模复核。四、动手练习练习 1模板自检跑python boundary_tpl.py --selftest。判定输出SELFTEST OK随后把某行Special Condition的值从1改9自检必须失败恢复后通过。练习 2打底实操对一个从未设过 Setpoint的控制阀先直接导入Setpoint观察结果再用Global Edit预置后重导。判定实测未打底失败、打底成功各一次并写出一行单位集结论。练习 3超定演练构造一个同一点既用 Assigned Pressure 又改 Flow Rate的场景跑spec_conflict.py。判定check()报出冲突说明为什么这属于超定。练习 4Reservoir 扫描设 3 个液位水平示例值生成变更表并批跑。判定得到 3 个工况的流量结果画出液位 → 流量的趋势并解释单调性示例性建模不代表任何标准。五、小结与下一篇预告本篇把外部世界参数化了Reservoir / Assigned Pressure / Assigned Flow是三类边界Control Valve 的 Setpoint是规格Special Condition是整数枚举Control Valve 0/1/2、Assigned Flow 0/1单位敏感字段必须先用 Global Edit 预置铁律 4一个对象只能有一种约束叠加即超定。两个预检脚本把这两条纪律从人脑搬进代码。第 16 篇《外部数据面集成PCF / CAESAR II Neutral / EPANET / GIS 与第三方衔接》我们讲 AFT 与外部世界交换资产的入口——Import Piping Layout From的四类格式、Export Piping Layout To的 EPANET、.inp双语义陷阱以及导入件的清点与命名标准化脚本。FAQ与第〇节一一对应Q1什么是边界对象与规格对象为什么重要A边界对象Reservoir、Assigned Pressure、Assigned Flow定义系统与外部世界的接口规格对象Control Valve 的 Setpoint、泵的控制设定点定义内部约束它们决定了方程组的已知量改动会产生全局影响所以既是最有信息量的扫描变量也最容易因单位或超定让整批跑失败。Q2Reservoir 有哪些参数改液位与改面积分别意味着什么A官方 Table 1 列出 Reserved 参数含 Liquid Surface Elevation、Liquid Surface Pressure、Liquid Temperature、Cross-Sectional Area、Tank Bottom Elevation、Surface Elevation Type 等改液面标高改变可用压头重力驱动系统的驱动力改横截面积与罐底标高影响液位随时间变化的速率属 XTS 扩展时间模拟的范畴。Q3Assigned Pressure / Assigned Flow 与 Branch 怎么选A需要某点压力固定用 Assigned Pressure结果看流量需要某点流量固定用 Assigned Flow结果看压力只需要外部进/出流而两者都不固定用 BranchSource/Sink Flow Rate定压与定流是两种不同的物理问题选错不会有报错但结论全错。Q4为什么某些字段必须先有单位/初值Global Edit 怎么配合A因为官方明确为了让结点接受变更、某些字段必须已含数据例如改控制阀 control setpoint 前该阀必须已有 setpoint 与单位目的是确保使用正确的单位集做法是先用 Global Edit 给待改字段填一个合法占位值再导入变更表。Q5超定/欠定与 Parameter conflict 是什么关系A每个规格对象贡献一个约束在同一对象上叠加等价约束会导致超定、缺少约束会欠定而 Parameter conflict 就是这类冲突在导入时的表现例如结点正使用阻力曲线时不能再设 loss value纪律是一个对象只保留一种约束方式导入前用脚本预检约束数是否为 1。