AFT二次开发教程01AFT Fathom / Impulse 全景——五条官方自动化通道与“没有 API”的二次开发真相版本与事实声明产品与版本AFT Fathom当前主版本为15、AFT Impulse为12官方文档门户 2026-09 公告归属Datacor Flow Simulation。本篇的机制描述引用官方Fathom 13 / Impulse 10帮助文档正文具体界面以你所用版本的官方文档为准。语言/环境Python 3.x标准库 pandas/openpyxl 可选AFT 本体为 Windows 桌面应用。本文目标读完能准确说出 AFT 二次开发的边界哪些能自动化、哪些不能并能为一个具体任务选对通道。本篇不涉及任何 AFT 脚本 API凡官方未公开处一律以官方文档/厂商为准。许可与价格以 Datacor 官方渠道为准本文全部示例性说明不代表任何标准规定。一句话结论AFT 家族Applied Flow Technology / Datacor Flow Simulation没有公开的通用脚本 API其二次开发的全部合法手脚都在五条官方确证通道里——Scenario Manager场景管理 Start Batch Run批量运行 Excel Export Manager结果导出 Import Excel Change Data模型变更导入 文件格式互换因此AFT 二次开发本质是数据面工程 GUI 自动化编排而不是调 API。〇、本篇要解决的认知问题Q1AFT Fathom 与 AFT Impulse 到底各算什么两者用的是什么数值方法为什么一个是稳态、一个是瞬态Q2网上说AFT 二次开发时能用的官方通道到底有哪几条它们的官方名称是什么Q3AFT 到底有没有 API如果有一点点它在哪个授权层级、有没有公开文档Q4为什么说没有 API反而是一件好事这对工程团队的工作方式意味着什么Q5接到一个具体任务比如跑 50 个泵配置并出对比表应该怎么在五条通道里做选型一、机制解析1.1 两个产品两种物理两种数值方法先把最容易被混为一谈的事说清Fathom 与 Impulse 不是同一个软件的两个界面而是两种物理问题。维度AFT FathomAFT Impulse物理问题不可压缩流liquid low velocity gas稳态液体管网瞬态/水锤waterhammer与压力涌浪surge求解目标压力降与流量分配一套代数方程的定常解压力随时间的变化过程双曲型偏微分方程的时程解数值方法**牛顿-拉夫森法Newton-Raphson**迭代求解质量与动量守恒基本方程矩阵方法为速度优化**特征线法Method of Characteristics, MOC**求解瞬态质量与动量方程内置稳态求解器自动初始化瞬态谁依赖谁独立可用先要一个稳态解做初始条件这两条头部事实有官方原文支撑Fathom 总览页写明用Newton-Raphson解质量与动量守恒方程Impulse 产品页写明稳态解用改进牛顿-拉夫森矩阵迭代、瞬态方程用特征线法求解。为什么这对你重要它决定了二次开发的数据流方向——Fathom 的批量是改输入→跑→收输出的无状态循环而 Impulse 的批量前面永远挂着一层 Fathom是稳态模型 → 瞬态模型的两级流水线第 13、18 篇专讲。把两者当同一件事设计是行业里最常见的架构级错误。1.2 二次开发的五条官方通道AFT没有公开一个AFTFathom.Application这类脚本入口。它的自动化能力被官方明确地做进了 GUI 的五个地方全部有官方帮助文档正文可查┌──────────────────────────────────────────────┐ │ 外部编排语言Python/VBA │ └──────────────────────────────────────────────┘ ①写 ②读 ⑤写/读 │ │ │ ┌──────────────────────▼────┐ ┌───────────▼──────────┐ ┌──▼─────────────────┐ │ ①Import Excel Change Data │ │ ②Excel Export Manager│ │ ⑤文件格式互换 │ │ 用 AFT Transfer 工作表 │ │ 把 Output 映射到 │ │ PCF/CII/SHP/INP │ │ 批量改模型参数 │ │ 指定 Excel 单元格 │ │ Force File │ └──────────────┬────────────┘ └───────────▲──────────┘ │ 跨产品互转 │ │ │ └──┬─────────────────┘ │ ┌──────────────────────┴───┐ │ └────►│ ③Scenario Manager │ │ │ 同一模型内的多个变体工况 │ │ └──────────────┬───────────┘ │ │ │ ┌──────────────▼───────────┐ │ │ ④Start Batch Run │◄───────────┘ │ 自动顺序跑多场景/多模型 │ └──────────────────────────┘五条通道的官方名称与职责编号通道官方名入口职责证据①Import Excel Change DataFile 菜单用名为AFT Transfer的工作表批量修改模型对象参数支持按场景定向Fathom 13 帮助ImportingFromExcel②Excel Export ManagerFile 菜单把任意 Output 数据单值/列/行/整表/图导出到 Excel 的指定单元格支持跑完自动导出Fathom 13 帮助ExportingToExcel③Scenario Manager快速访问面板 / Tools 菜单在同一个模型文件内管理多个变体工况支持父子继承Fathom 13 帮助ScenarioManagerOverview④Start Batch RunFile 菜单顺序自动运行多个场景或多 个模型文件可后台运行、可选导出 Excel/PDFFathom 13 帮助RunningModelsinBatchMode⑤文件格式互换File 菜单PCF / CAESAR II Neutral / GIS Shapefile / EPANET 导入导出Impulse 侧Export Force File到 CAESAR II/TRIFLEX/ROHR2/AutoPIPE跨 AFT 产品直接 Open 即转换Fathom 13 / Impulse 10 帮助FileMenu、Exporting-Force-Data关键结构①是写输入、②是读输出、③是组织工况、④是执行、⑤是与外部世界交换资产。四者形成闭环⑤负责跨界。你在第 17、20 篇看到的平台就是把①~⑤用 Python 缝起来。1.3 没有 API到底意味着什么最重要的一节搜索AFT Fathom API你会看到几种说法必须在开头就钉死官方唯一与API相关的表述在授权文档里Enterprise 层级在 Core/Pro 之外增加 “the capability to use the Local License Server (LLS) for air-gapped secure sitesand metered API functionality”。也就是说计量式 API 功能存在但它挂在 Enterprise 授权上而且官方没有公开任何技术文档端点、鉴权、调用方式、计数口径全未知。除此之外AFT没有公开通用脚本语言、COM 对象模型、ProgID、类名、方法名、CLI 参数。因此本系列的立场是铁律 2凡涉及调 API一律写以官方文档/厂商为准绝不编造。需要时联系 Datacor Flow Simulation 支持官方文档门户给出的邮箱为flow-supportdatacor.com或登录客户下载门户索取 Enterprise API 说明。为什么没有通用 API反而是好事——这是本系列的价值主张它逼你把工程做在数据面而不是脚本面。吃时间的从来不是调用那一行而是50 个工况怎么组织、200 行输出怎么收干净、单位怎么不错——这些工作在任何水力软件里都一样跨软件可迁移。它天然可审计。AFT Transfer工作簿、导出件、Batch File、Force File 都是落地文件能入库、能 diff、能复现而一段调 API 的脚本出问题往往是黑箱。它把 GUI 的稳定性变成资产。GUI 通道是厂商最不可能偷偷改契约的部分改了就打断所有用户的手工工作流比一个可能随版本消失的私有 API 稳得多。1.4 通道选型做之前先分诊一条经验法则先按任务是否零判断分诊——含工程判断选规格、定拓扑、判收敛的部分留在人 GUI零判断的重复劳动才自动化。再按改输入还是收输出分到 ①/②按几个工况决定是否上 ③/④。二、完整代码与逐行剖析本篇的代码是一个通道选型器把你对任务的描述是否要改输入、是否要收输出、工况数量、是否需要跨软件交付映射到五条通道的组合输出一份该用哪些通道 关键动作的方案。它纯 Python不依赖 AFT可直接运行。代码 2-1channel_router.py通道选型规则引擎# -*- coding: utf-8 -*- channel_router.py —— AFT 二次开发通道选型器 把任务特征映射到五条官方通道的组合并打印执行清单。 运行 python channel_router.py --selftest python channel_router.py --alter-input --collect-output --cases 50 --cross-tool importargparseimportjsonimportsys# 五条官方通道名称来自官方帮助文档见 frontmatter referencesCHANNELS{1_import_excel:Import Excel Change Data用 AFT Transfer 工作表批量改模型参数,2_export_excel:Excel Export Manager把 Output 映射导出到指定 Excel 单元格,3_scenarios:Scenario Manager同一模型文件内组织多个变体工况,4_batch_run:Start Batch Run顺序自动运行多场景/多模型,5_file_io:文件格式互换PCF/CII/SHP/EPANET/Force File/跨产品互转,}defroute(alter_input:bool,collect_output:bool,cases:int,cross_tool:bool)-dict:核心规则把任务特征翻译成通道组合。返回 {channels:[...], steps:[...]}。plan{channels:[],steps:[],warnings:[]}# 规则 1要改输入 - 必须走 Import Excel Change Dataifalter_input:plan[channels].append(1_import_excel)# 规则 2要收输出 - 必须走 Excel Export Managerifcollect_output:plan[channels].append(2_export_excel)# 规则 3多于一个工况 - 用 Scenario Manager 组织而不是复制多个文件ifcases1:plan[channels].append(3_scenarios)plan[channels].append(4_batch_run)elifcases1:plan[warnings].append(单工况无需 Scenario Manager直接手工 Run 更划算。)# 规则 4要跨软件/跨产品 - 走文件格式互换ifcross_tool:plan[channels].append(5_file_io)# ---- 生成执行清单顺序有讲究先建工作面再导输入再批跑最后取数----if3_scenariosinplan[channels]:plan[steps].append(在 Scenario Manager 里建场景树Base Scenario 子场景命名遵循 Base Scenario\\单位制\\工况 的路径规范。)if1_import_excelinplan[channels]:plan[steps].append(用 Python 生成 AFT Transfer 工作表列顺序Apply / Object Type / Object Number / Parameter / Change Code / Value / Scenario Path Name。)plan[steps].append(在 AFT 里执行 File Import Excel Change Data检查 Object Change Log 是否零错误。)if5_file_ioinplan[channels]:plan[steps].append(确认跨界资产模型互转用 File Open载荷交付用 Export Force File。)if4_batch_runinplan[channels]:plan[steps].append(File Start Batch RunBatch Run Type 选 Scenarios in Current ModelAdd Scenarios 勾全勾 Run Batch in BackgroundStart Run。)if2_export_excelinplan[channels]:plan[steps].append(批跑前先在 Excel Export Manager 配好导出项批跑时选 Save Using Excel Export Manager。)plan[steps].append(用 pandas 读回导出工作簿落成 (scenario, object, parameter, unit, value) 长表。)plan[channels]sorted(set(plan[channels]))returnplandefselftest():用三个典型任务验证路由规则断言给出可量化判定。t1route(alter_inputFalse,collect_outputTrue,cases1,cross_toolFalse)assertt1[channels][2_export_excel],t1# 只收一次数t2route(alter_inputTrue,collect_outputTrue,cases50,cross_toolFalse)assertt2[channels][1_import_excel,2_export_excel,3_scenarios,4_batch_run],t2# 50 工况标准四件套t3route(alter_inputTrue,collect_outputTrue,cases10,cross_toolTrue)assert5_file_ioint3[channels],t3# 跨软件交付print(SELFTEST OK三条路由断言全部通过。)print(json.dumps(t2,ensure_asciiFalse,indent2))defmain():apargparse.ArgumentParser(descriptionAFT 二次开发通道选型器)ap.add_argument(--alter-input,actionstore_true,help是否需要批量修改模型输入)ap.add_argument(--collect-output,actionstore_true,help是否需要批量回收结果)ap.add_argument(--cases,typeint,default1,help工况数量)ap.add_argument(--cross-tool,actionstore_true,help是否需要跨软件/跨产品交付)ap.add_argument(--selftest,actionstore_true,help运行内置自检)aap.parse_args()ifa.selftest:selftest()return0planroute(a.alter_input,a.collect_output,a.cases,a.cross_tool)print(选定通道)forcinplan[channels]:print(f -{CHANNELS[c]})print(\n执行清单)fori,sinenumerate(plan[steps],1):print(f{i}.{s})forwinplan[warnings]:print(f\n[提示]{w})return0if__name____main__:sys.exit(main())逐行剖析CHANNELS字典里的中文描述逐条对应官方帮助页的原文职责不是自造名词——照抄这些名字去搜官方文档一定搜得到本系列事实可回溯底账的具体做法。route()的四条规则是工程规则而非逻辑游戏规则 3 多于一个工况就用 Scenario Manager是本系列第一条最佳实践——不要一工况一个.fth文件那会让文件系统失控且拿不到 Scenario Comparison 与继承能力。步序刻意排成先建场景树 → 再导输入 → 再批跑 → 最后取数顺序错了会踩坑导出项必须在批跑之前配好官方原文The Excel Export option can only be chosen if… the desired output must first be configured in the Excel Export Manager否则Save Using Excel Export Manager根本不可选铁律 9 的兄弟条款。selftest()的断言是可量化判定50 工况场景必须正好命中四件套多一个少一个都算失败。给你一个改代码不破坏规则的安全网。注意plan[channels] sorted(set(...))去重——用户可能同时触发多条规则命中同一通道去重是防御性编程。代码 2-2给自己做一张通道×风险速查卡下面这段把决策表生成为 Markdown贴在团队 wiki 里新人一看就懂该找谁。# -*- coding: utf-8 -*-make_card.py —— 生成 AFT 自动化通道速查卡MarkdownROWS[# 通道, 你想干的事, 官方入口, 主要风险(Import Excel Change Data,批量改模型参数,File 菜单,目标字段必须先有单位/初值否则整个字段导入失败铁律4),(Excel Export Manager,把结果落到 Excel 指定单元格,File 菜单,多 sheet 多场景时必须每场景独立工作簿起始单元格写重会覆盖数据铁律9),(Scenario Manager,在同一文件内组织多个工况,快速访问面板/Tools,跨场景变更必须用全限定 Scenario Path Name否则报场景名不唯一铁律5),(Start Batch Run,自动顺序跑多个场景/模型,File 菜单,只运行 Analysis Setup 已完整定义的场景中断后已跑完的输出保留),(文件格式互换,与应力/供水/配管工具交换资产,File 菜单,跨产品互转会把不支持结点降级为 General Component/Branch必须复核),]defmain():print(| 通道 | 你想干的事 | 官方入口 | 主要风险 |)print(|---|---|---|---|)forc,w,g,rinROWS:print(f|{c}|{w}|{g}|{r}|)if__name____main__:main()为什么这样写这张表的主要风险列每一格都是官方文档明文或本系列铁律不是拍脑袋。把风险写在选型卡上是把铁律 4/5/6/9 前置到决策阶段——比事后救火便宜一百倍。三、常见报错与排查报错 1-1照着某篇博客抄了个AFTFathom.Application之类的脚本Python 直接AttributeError / OSError。现象win32com.client.Dispatch(...)报无效的类字符串或找不到 ProgID。根因AFT没有公开的 COM/脚本 API铁律 2那段代码是编的或来自不相关产品。解法放弃调 API思路改走五条官方通道需要 Enterprise API 就联系厂商别在网上捡字符串。报错 1-2以为把.fth文件改了就能改模型结果 AFT 打不开模型。现象打开报An error occurred reading the file into AFT Fathom. Cant find [TOOLBOX PREFERENCES] heading.。根因模型文件虽是分节文本但手工编辑非官方支持一个字节错位就触发分节读取失败铁律 6。解法永远通过Import Excel Change Data改模型损坏时用同目录的.bakF-001备份改名回.fth抢救第 04 篇详述。报错 1-3设了多场景导出到一个工作簿结果场景之间数据互相覆盖。现象导出件里只剩最后一个场景的数。根因违反了 Excel Export Manager 的官方硬约束——多 sheet 多场景只能每场景独立工作簿要进同一工作簿只能指定一个 sheet铁律 9。解法要么单 sheet要么每场景一个文件第 12 篇给聚合脚本。报错 1-4批跑跑了半宿早上去看发现大部分场景跳过。现象Solution Progress 里一堆场景瞬间跳过。根因官方明确自动运行那些Analysis Setup 已完整定义的场景——未定义完全的场景会被跳过。解法批跑前对每个场景做一次Analysis Setup完整性自检把这条纳入流程第 10 篇给自检清单。报错 1-5任务卡在该用哪个通道上纠结半天。现象讨论三小时没动手。根因把通道选型当成了判断题其实是分诊题。解法跑一遍本篇代码 2-1先分诊再动手含工程判断的部分选规格/搭拓扑/判收敛明确留给人 GUI。四、动手练习练习 1边界复述不看本篇手写AFT 五条官方通道的名字与职责。判定五条名字全对错一条即不合格能说出第 ⑥ 条不存在的原因无公开 API。练习 2选型自测对你手头或虚构的一个任务跑python channel_router.py --alter-input --collect-output --cases 50 --cross-tool。判定输出中恰好包含 5 条通道中的 4 条以上且执行清单 ≥5 步写出你的任务为什么命中这些通道不超过 5 行。练习 3风险卡把代码 2-2 生成的速查卡贴到笔记为每一条主要风险补一个你自己遇到或设想的触发场景。判定5 行全部补齐每行 ≥20 字且至少 3 行能对应到本系列铁律编号。五、小结与下一篇预告本篇立起了全系列的地基Fathom 算稳态牛顿-拉夫森、Impulse 算瞬态特征线法需稳态解初始化AFT没有公开通用 API二次开发只能走五条官方通道——①写输入、②读输出、③组织工况、④执行、⑤跨界交换。把它翻译成工程语言就是你的真正工作是数据面工程。第 02 篇《环境盘点与许可》我们把 AFT 装到机器上之后先做一次彻底的环境普查——统一安装器留下了什么痕迹、Zentitle2的 Core/Pro/Enterprise 三层级分别解锁什么、气隙站点怎么用Local License Server (LLS)、崩溃后席位为什么会被孤立orphaned并给出一个先探测后编码的环境清单脚本。FAQ与第〇节一一对应Q1AFT Fathom 与 AFT Impulse 分别算什么用什么数值方法AAFT Fathom 做不可压缩流管网稳态压力降与流量分配用牛顿-拉夫森法Newton-Raphson迭代求解质量与动量守恒方程AFT Impulse 做液体管网瞬态/水锤与压力涌浪分析用特征线法Method of Characteristics解瞬态方程并用内置稳态求解器自动初始化。Q2AFT 二次开发的官方通道有哪几条官方名称是什么A五条Import Excel Change Data用 AFT Transfer 工作表批量改模型参数、Excel Export Manager把 Output 导出到 Excel 指定单元格、Scenario Manager同一模型文件内组织多个变体工况、Start Batch Run顺序自动运行多场景/多模型、文件格式互换PCF/CAESAR II Neutral/SHP/EPANET 与 Export Force File、跨产品互转。Q3AFT 到底有没有 APIAAFT 没有公开的通用脚本/COM API官方唯一与 API 相关的表述在授权文档中——Enterprise 层级提供 “metered API functionality”计量式 API 功能但该 API 无公开技术文档具体形态以厂商为准需联系 Datacor Flow Simulation 支持确认。Q4为什么没有 API反而对工程有利A因为它把工作量逼到数据面工程上工况组织、单位绑定、结果清洗这些技能跨软件可迁移同时 AFT Transfer 工作簿、Excel 导出件、Batch File、Force File 都是可入库、可 diff、可复现的落地文件比黑箱脚本更可审计也比随时可能消失的私有 API 更稳定。Q5接到跑 50 个泵配置出对比表的任务怎么选通道A用 Scenario Manager 把 50 个配置建成同一模型内的 50 个场景跨场景变更用全限定 Scenario Path Name用 Python 生成 AFT Transfer 工作表经 File Import Excel Change Data 写入参数配好 Excel Export Manager 导出项后用 File Start Batch Run 后台批跑并选 Save Using Excel Export Manager最后 pandas 读回导出件落成长表。