企业官网建设流程全解析

AFT二次开发教程（15）：边界条件与规格对象参数化——Reservoir / Assigned Pressure / Control Valve

版本与事实声明

• 产品与版本：AFT Fathom 15 / AFT Impulse 12（当前）；本篇参数与数值映射引用官方Fathom 13帮助页Importing From Excel（Table 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：什么是"边界对象"与"规格对象"？它们为什么在参数化里特别重要？
• Q2：Reservoir 的参数有哪些？改液位和改罐底面积各自意味着什么？
• Q3：Assigned Pressure / Assigned Flow 与 Branch 的区别是什么？该怎么选？
• Q4：为什么"某些字段必须先有单位/初值"才能导入？Global Edit怎么配合？
• Q5：什么是超定/欠定？它与"删除错误Parameter conflict"什么关系？

一、机制解析

15.1 两类特殊对象

管网模型里绝大多数对象是"内部件"（管、弯头、三通、阀）。但有少数对象定义了系统与外部世界的接口或某种约束，它们对结果的影响是全局性的：

为什么它们特别重要：边界与规格决定了方程组的"已知量"。改一个罐液位，整个系统的流量分配可能重排；改一个控制阀设定点，工作点会移动。所以参数扫描时，这些量往往是最有信息量的变量——也最容易因为单位/超定问题让整批跑挂掉。

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 Setting（I 型）
• Surface Elevation Type（I 型）

语义解读（工程）：

• 改Liquid Surface Elevation：改变可用压头（重力驱动系统的驱动力来源），直接改变流量；
• 改Liquid Surface Pressure：改变罐内气相压力（加压罐/常压罐的区别）；
• 改Cross-Sectional Area + Tank Bottom Elevation：影响液位随时间变化的速率——这在XTS（Extended Time Simulation）模块下才有意义（罐液位自动计算是 XTS 的能力）。

一个容易被忽略的点：Surface Elevation Type是 I 型（整数）。它决定了"标高"是按什么基准解释的——批量改液位时若不注意这类"类型型参数"，可能改了数却改了语义。凡是 I 型参数，写之前都要确认它的取值域（官方 Table 1 只给了类型码，具体枚举以官方文档/界面为准）。

15.3 Assigned Pressure / Assigned Flow / Branch

官方 Table 1 的相关条目：

怎么选（工程判据）：

• 你要"这点压力固定"（如接市政管网、接某个恒压母管）→Assigned Pressure；
• 你要"这点流量固定"（如给定抽取量、给定注入量）→Assigned Flow；
• 你要"这点有外部进/出流"但压力流量都没固定 →Branch（Source/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 Log

15.5 超定/欠定与Parameter conflict

水力学基本事实：每个规格对象贡献"一个约束"。若你在同一个对象上同时固定了会冲突的两个量（例如既固定控制阀目标、又用另一设置约束同一自由度），系统会超定（over-determined）——求解器无从下手；反之某些自由度缺少约束则欠定（under-determined）。

官方错误表里的Parameter conflict就是这类冲突的一个具体表现，官方举的例子是：当该结点正在使用阻力曲线（resistance curve）时，不能再设 loss value——因为两者都在定义同一个损失特性。

工程纪律：

• 一个对象，一种约束方式。选了控制阀的 Setpoint，就别再叠一个等价的流量约束；
• 批量改参时要检查"改完是否仍恰好一套约束"。这是参数扫描里最容易悄悄引入的错误：某一行的变更让模型从"恰好"变成"超定"，整批里的这个工况就废了。

二、完整代码与逐行剖析

代码 15-1：boundary_tpl.py（边界对象变更模板 + 冲突预检）

# -*- coding: utf-8 -*-""" boundary_tpl.py —— 边界/规格对象变更模板与导入前冲突预检 参数与 Special Condition 取自官方 Table 1/3；预检覆盖：单位未打底、参数错配、规格叠加。 运行：python boundary_tpl.py --selftest """importsysfromopenpyxlimportWorkbook SHEET="AFT Transfer"COLS=["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 3：Special 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,p=r.get("Object Type"),r.get("Parameter")ifotnotinBOUNDARY_PARAMS:problems.append((i,f"未知/未登记的边界对象类型：{ot}"))continuet=BOUNDARY_PARAMS[ot].get(p)iftisNone:problems.append((i,f"Invalid parameter ID：{p}不属于{ot}"))continueifp=="Special Condition":val=r.get("Value")ifvalnotinSC_VALUES.get(ot,{}):problems.append((i,f"Invalid 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):wb=Workbook();ws=wb.active;ws.title=SHEET 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":r"Base 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":r"Base 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":r"Base Scenario\US Units\HighLevel","_prefilled":True},]defselftest():rows=demo_rows()assertprecheck(rows)==[],precheck(rows)# 正例零问题# 反例 1：Special Condition 非法值bad1=rows+[{"Apply":"Yes","Object Type":"Control Valve","Object Number":3,"Parameter":"Special Condition","Change Code":"Set equal to value","Value":9,"Scenario Path Name":r"B\X"}]assertany("Invalid parameter value"inmfor_,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":r"B\X"}]assertany("铁律4"inmfor_,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"--selftest"insys.argv:selftest()

逐行剖析：

• BOUNDARY_PARAMS把官方 Table 1 的四类边界/规格对象及其参数类型码结构化。只登记本篇讨论的四类，比抄全更诚实——其余"以官方文档为准"。
• SC_VALUES把官方 Table 3 的Control Valve（0/1/2）与Assigned Flow（0/1）映射成字典，预检直接查表。枚举写错是"跑得通但物理错"的头号来源，必须拦。
• UNIT_SENSITIVE集合实现铁律 4 的程序化：Setpoint / Loss When Fully Open / Pressure / Flow Rate这些"必须先有单位"的字段，若没声明已打底（_prefilled），直接报错。这把"记得先 Global Edit"从人脑负担变成脚本强制。
• 预检返回(行号, 原因)元组，便于在 Excel 里定位。
• selftest()三个断言：正例零问题、非法枚举被拦、未预置被拦。反例 2 用的正是官方 Note 里那个例子（改 control setpoint）。

代码 15-2：spec_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:ifgroup<=params:problems.append(f"{ot}{num}：同时设置了{sorted(group)}，可能超定/规格冲突")if"Special Condition"inparamsandlen(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"--selftest"insys.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 Type（I 型）等基准型参数对"标高"的解释。解法：改标高前确认基准设置；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()报出冲突；说明为什么这属于超定。
• 练习 4（Reservoir 扫描）：设 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、泵的控制设定点）定义内部约束；它们决定了方程组的已知量，改动会产生全局影响，所以既是最有信息量的扫描变量，也最容易因单位或超定让整批跑失败。

Q2：Reservoir 有哪些参数，改液位与改面积分别意味着什么？
A：官方 Table 1 列出 Reserved 参数含 Liquid Surface Elevation、Liquid Surface Pressure、Liquid Temperature、Cross-Sectional Area、Tank Bottom Elevation、Surface Elevation Type 等；改液面标高改变可用压头（重力驱动系统的驱动力），改横截面积与罐底标高影响液位随时间变化的速率（属 XTS 扩展时间模拟的范畴）。

Q3：Assigned Pressure / Assigned Flow 与 Branch 怎么选？
A：需要某点压力固定用 Assigned Pressure（结果看流量），需要某点流量固定用 Assigned Flow（结果看压力），只需要外部进/出流而两者都不固定用 Branch（Source/Sink Flow Rate）；定压与定流是两种不同的物理问题，选错不会有报错但结论全错。

Q4：为什么某些字段必须先有单位/初值，Global Edit 怎么配合？
A：因为官方明确为了让结点接受变更、某些字段必须已含数据（例如改控制阀 control setpoint 前该阀必须已有 setpoint 与单位），目的是确保使用正确的单位集；做法是先用 Global Edit 给待改字段填一个合法占位值再导入变更表。

Q5：超定/欠定与 Parameter conflict 是什么关系？
A：每个规格对象贡献一个约束，在同一对象上叠加等价约束会导致超定、缺少约束会欠定，而 Parameter conflict 就是这类冲突在导入时的表现（例如结点正使用阻力曲线时不能再设 loss value）；纪律是一个对象只保留一种约束方式，导入前用脚本预检约束数是否为 1。