交互式潮流与暂态稳定程序

来源、许可与适用范围

本仓库是 mbheinen/bpa-ipf-tsp 的后续分支。上游 MIT 许可证原文保存在 LICENSE，本仓库新增和修改的软件代码沿用同一 MIT 条款。代码来源链和历史公开材料见 PROVENANCE.md。

项目级 MIT 许可证仅适用于软件代码，除非具体文件另有说明。第三方算例、手册和运行库不因项目整体许可证而改变授权条件，详见 THIRD_PARTY_NOTICES.md 与 data/README.md。

本项目不隶属于任何后续商业版本、机构定制版本或区域改编版本，也不声称获得其授权、合作或认可；维护者不有意包含这些版本的非公开代码、二进制、数据或文档。模型名、文件格式或算法相似可能来自共同的历史源码谱系，不能单独作为关联或来源证据。

交互式潮流（IPF） 是一套用于潮流计算的程序系列。IPF 对电力网络的平衡稳态运行进行建模，被电力系统规划人员、设计工程师和学生用于：研究电网、确定节点电压分布、分析线路有功与无功潮流、检查线路过载、理解系统无功需求、规划区域控制、考察甩负荷/切机/线路停运的影响等。

IPF 最初由美国邦纳维尔电力局（BPA）开发，并于 1994 年由 BPA 公开为公共领域。本项目是 BPA 交互式潮流（IPF）程序及暂态稳定程序（TSP）的一个分支。本仓库的原始源码来自 ftp://ftp.bpa.gov（该地址似乎已不可用）。项目目标是让该代码库重新可用，在保留核心仿真能力的前提下持续改进。当前构建提供下文介绍的命令行潮流和暂态稳定工具。原程序还带有基于 Motif X Window 的图形界面，该 GUI 不在当前构建范围内。

文档

本项目的完整文档见此处。该站点包含安装方法、可用命令行工具、模型与研究的记录/命令语法、C API 用法等。站点内容多来自这些手册中 IPF 与 TSP 的原始文档，若 ReadTheDocs 上缺少某部分，可查阅手册。另可参考 John Schaad 的网站 了解 BPA 原项目的历史。

本仓库自身的开发文档见 docs/（中文），入口建议：代码架构说明（分层、调用链、构建产物、文件格式）、BPA潮流API说明（bpf/ipfsrv/bpaflow 关系、安装与完整 Python API）、libipfpy API 用户手册（DLL C ABI 与结构体）、Windows构建运行指南。

完整分类和阅读顺序见文档中心。

构建（Linux 与 Windows）

项目使用 CMake，支持 Linux 和 Windows。

• Linux：安装 Fortran 编译器（如 gfortran），在项目根目录执行：

  mkdir build && cd build
  cmake ..
  cmake --build .
  

• Windows：须先安装 Fortran 编译器（如 Intel oneAPI 或带 gfortran 的 MinGW）。CMake 不会安装编译器。然后任选一种方式配置与构建：

  • Visual Studio（多配置 Debug/Release）：
    cmake -G "Visual Studio 17 2022" -A x64 -B _build，再打开 _build/bpa-ipf-tsp.sln
  • Ninja（单配置）：
    cmake -G "Ninja" -B _build -DCMAKE_BUILD_TYPE=Release -DCMAKE_Fortran_COMPILER=<path-to-fortran>，然后 cmake --build _build

默认安装前缀在 Windows 上为 C:\Program Files\bpa-ipf-tsp，在 Linux 上为 /usr/local；如需修改可使用 -DCMAKE_INSTALL_PREFIX=...。 构建中间文件仍位于 _build/；生成的 PF 和 SW 可执行文件输出到仓库根目录 bin/，文件名为 pf_powerx.exe 和 sw_powerx.exe（Linux 下无 .exe 后缀）。 bin/ 同时携带运行所需的 MinGW 运行库 DLL，下载后无需安装 GCC 即可运行。

示例算例

本仓库的 data 目录下有多种示例算例，部分来自原始 IPF 代码库，部分来自公开算例（如德州农工大学合成算例集，见此处）。所有数据均非真实电网信息，因输电系统运营商通常将此类信息视为机密。

快速参考

以下为部分 IPF 命令的快速参考。

批处理潮流 — pf_powerx

批处理潮流（pf_powerx）根据潮流控制文件（.pfc）中的命令执行。用户在 .pfc 中编写命令进行潮流计算。[文档][]中描述了可用命令。可使用 data 目录下的测试算例试运行。运行方式：bin/pf_powerx <controlfile.pfc> 或 bin/pf_powerx 后按提示操作。例如：

$ cd data
$ ../bin/pf_powerx IEEE39.dat

输出为潮流结果文件 <casename>.pfo。使用 pf_powerx 时，须先创建包含相应命令的 <casename>.pfc 以完成求解。运行时 pf_powerx 会按程序确定的逻辑顺序接受并执行这些命令，因此不必关心 PFC 文件中命令的书写顺序。输入命令会先被处理，在产生任何输出前自动完成求解。若已请求，最后会生成新的基态（.bse）文件。详见 [IPF 批处理用户指南][]。

电网切割 — bpaflow.ipfcut()

独立的 ipfcut.exe 已移除；从完整系统模型中切出子系统，并为其配置独立的平衡节点以单独运行。原独立程序 ipfcut.exe 已并入 bpaflow API，切割命令流文件（(CUTTING, ...)/>SAVE_BUSES< 等）内容不变。

用法：pf.ipfcut(out_file, base_file, cmd_file)（Python，进程内直调）

输出：切割后子网的网络数据文本文件

该切割功能从已求解的基态文件（.bse）中切出子系统。切割支路上的潮流被转换为特殊格式的 +A 延续节点记录上的等值发电或负荷。随后的潮流计算应能得到与原始基态一致的内部支路潮流和节点电压。

在绝大多数情况下，需要将切割子系统中的某一节点转换为平衡节点，以替代原系统的平衡节点。

定义切割系统的方式有多种：节点名、区域、基准 kV、以及单条支路。π 型等效功能可将选定节点替换为无源节点序列（由多段组成的线路），原负荷按线路导纳比例等效到该序列上。

示例控制文件：

( CUTTING, PROJECT=EWEB, CASEID=EWEBCUT1 )
>DEBUG<
.>EXCLUDE_BUSES<
.>INCLUDE_BUSES<
.>PI_BACK_BUSES<
.>SAVE_BUSES...<
.>CUT_BRANCHES<
>SAVE_ZONES NC,SAVE_BASES 500,230,115,69<
/ DEBUG, TX = ON, DC_MODEL = ON
(STOP)

PCL 批处理 — bpaflow.run_command_file

原 ipfbat 独立程序已移除，PCL 命令文件由 Python API 经 /COMMAND 通道执行，支持嵌套命令文件：

with BPAFlow() as pf:
    rc = pf.run_command_file("test.pcl")

PCL 命令（标准扩展名 .pcl）说明见 [IPF 高级用户指南] 与 [IPF CFLOW 用户指南] 附录 A；命令集与 bpf 的 PFC 部分重叠。

IPF 报告 — /reports 命令

生成定制输出报告与汇总。原独立程序 ipf_reports.exe 已移除，改用命令通道：

pf.command('/report, append = out.txt, select=BUS_UV')   # 单表

可选 select 关键字（BUS_INPUT、BUS_BR_OUTPUT、VOLTAGE_C、AI_SUMMARY、USER_ANALYSIS 等）见 ipf/cmd/p_report.f；多条 /report 同文件名时追加合并。

IPF C 库 — libcflow

CFLOW 是 IPF 的 C 库（libcflow）。本仓库包含多个基于 CFLOW 的程序：

• pvcurve
• post_pvcurve
• qvcurve
• findout
• lineflow
• mimic

编写 CFLOW 程序或例程时，使用 C 语言（至少 main 须为 C）并包含头文件 cflowlib.h，该头文件定义了访问潮流输入与解的所有结构体与联合体。通过调用各类 CFLOW 例程获取这些值，也可向 ipfsrv 传递修改、请求新解等。编写方法见 [IPF CFLOW 用户指南]。在 .PCL 控制文件中包含这些例程及其他流程的说明见 [IPF 高级用户指南] 第 3.4 节。

BPAFlow（推荐的 Python 进程内潮流 API）

bpaflow 通过 ctypes 加载 libipfpy.dll，在 Python 进程内直接驱动与 bpf/ipfsrv 相同的 Fortran 潮流内核。它不需要 ipfsrv、socket 或 端口，除常规加载、修改、求解和查询外，还支持严格单步 Newton、同相位 迭代快照、消元前 Jacobian、节点不平衡功率和 Y 矩阵访问。

• 位置：bpaflow/；原生共享库目标：libipfpy。
• 安装：python -m pip install bpaflow；wheel 已包含 libipfpy.dll 和 MinGW/Fortran 运行库，无需配置 DLL 环境变量。
• 安装后最小验证：

  python -c "import bpaflow; from bpaflow import BPAFlow; p=BPAFlow(); print(bpaflow.__version__); p.close()"
  

• 带 BSE 的完整验证脚本：

  python examples/installed_quickstart.py path/to/case.bse --expect-buses 39
  

  该脚本不修改 sys.path，会加载 pip 安装的包。
• 本地 wheel：按发布指南配置专用的 _build/wheel Release 构建，再执行 python -m pip wheel . --no-deps --no-build-isolation -w dist；打包脚本会拒绝 误用 Debug DLL。
• 完整关系、安装步骤和 API 见 BPA潮流API说明、 libipfpy API 用户手册与 Windows构建运行指南；维护者发布流程见 BPAFlow打包发布指南。

PyFlow（早期 socket 客户端实验）

pyflow/ 与 bpaflow 不是同一包。当前 pyflow.client 和 ipfsrv 都按 主动连接方实现，尚缺少创建监听 socket、拉起 ipfsrv 和接收连接的控制端 生命周期，所以不能仅靠“先启动 ipfsrv、再运行 pyflow”直接配对。 新 Python 项目应优先使用已完成系统回归的 bpaflow；继续开发 socket 模式时，应先补齐上述控制端逻辑。

findout（CFLOW 程序）

潮流（bpf/ipfsrv）输出报告后处理。从多个 .pfo 文件生成停运与对应支路过载或节点电压越限表，支持排序与筛选。使用 CFLOW 库。

开发者：William D. Rogers, BPA

对 /OUTAGE_SIMULATION 运行的 .pfo 输出进行后处理，筛选、排序并以表格形式呈现。可生成“停运与过载”或“停运与节点越限”表，可按区域、业主、基准 kV、负荷与节点电压筛选，按区域、业主、基准 kV 或字母排序，便于自动化停运结果报告。输出表字段以字符分隔，便于导入 MS Excel 或 DECwrite。输入要求、提示、输出文件及数据格式见原文 README 中 findout 小节。

用法：$ findout，可选后跟 .pfo、trace 或列表文件。按提示操作，直接回车即使用方括号内的默认值。

lineflow（CFLOW 程序）

对多个基态算例在指定支路上生成支路量表格，支持排序、筛选与脚本化。

生成多基态下指定支路量的表格。可按支路列表、节点、kV、业主、区域、负荷水平或通配符选择线路；按字母、业主、区域、kV、负荷百分比或输入顺序排序；可生成控制脚本以自动重复类似研究。报告的量包括：以安培或 MVA 及关键额定百分比表示的负荷，或功率入、功率出与损耗（MW）。输出表字段以字符分隔，便于导入 MS Excel 或 DECwrite。

用法：$ lineflow

mimic（CFLOW 程序）

潮流（ipfsrv）算例生成与筛选。生成新算例并检查负荷与电压越限。

原作者：William D. Rogers, BPA

自动化基态求解与筛选、对基态施加修改、基态对比与图形生成。

输入需求（根据用户选择部分或全部）：供 ipfsrv 加载、修改、求解并返回数据的潮流基态；施加到基态的修改文件；基态文件名列表文本文件；修改文件名列表文本文件；指定全部或部分输入的 trace 文件；绘图用坐标文件；停运仿真控制文件。

运行模式：MIMIC 根据已提供信息智能提示，减少用户需回答的提问。可自动化：对多基态施加多组修改、多基态求解与筛选、两或多个基态对比、生成图形（含差异图）、生成适于 Excel 的报告表、将用户输入记录到 TRACE 文件、重复类似研究、用更新基态重跑、/Outage_simulation 研究、以及带 /SOLUTION 选项的基态求解。筛选条件包括：线路与变压器负荷（最大允许负荷、负荷变化、超过阈值的负荷变化）、节点电压（500 kV 与 500 kV 以下分别限值、最大/最小电压、重冬季条件、电压变化等）、业主/区域/基准 kV（包含、排除、通配符）。报告内容与报告格式详见原文 README 中 mimic 小节。

用法：$ mimic，可选后跟 .pfo、trace 或列表文件；按提示操作，回车使用默认值。

IPF 网络数据提取 — bpaflow.save_netdata / load_netdata

原独立程序 netdat.exe 已移除，改用命令通道与 bpaflow 方法：

pf.save_netdata("case.net", dialect="BPA", ratings="EXTENDED", size=120)  # 写网络数据文件
pf.load_netdata("case.net")                                                # 读回

将二进制基态文件（.BSE）转换为 ASCII 网络数据库文件（.NET、.BPA、.PTI 或 .GE）。

这是 GUI/IPFSRV 中“保存网络数据文件”功能的批处理版本，可生成以下任一方言的 WSCC 格式网络数据文件：BPA、WSCC 或 PTI。“方言”指仍为 WSCC 格式，但经特殊处理或限制，供其他程序使用；PTI 方言需经 PTI 专用转换程序 WSCFOR 预处理。文档见 [IPF 批处理用户指南] 附录 F。BPA/GE/PTI 网络数据格式说明见 [IPF 批处理用户指南] 附录 F。

路径使用因子 — bpaflow.puf

新版“puf”（Path Use Factors，即线潮流分析）修正了分解错误并增加了命令行选项。原独立程序 puf.exe 已并入 bpaflow API。

用法：pf.puf(["-x|", "base.bse", "out.txt", "flowgate.txt"])（Python，进程内直调；选项与位置参数分别对应原命令行）

参数含义：

• -x<flag>：Excel 字段分隔符，通常为 "|"
• -pv：所有节点设为 PV，默认为 PV 与 PQ
• -ai：开启区域交换控制，默认关
• -g：灵敏度仅限发电机节点，默认所有节点
• -ps：包含移相器灵敏度，默认不包含
• -lossless：无损耗灵敏度，宜与 -pv 同用，减少平衡节点位置影响；默认使用完整雅可比解
• -l1：灵敏度为 dLine/dP（默认）
• -l2：灵敏度为 1.0 + dLine/dP
• -c <cutfile>：用切割命令文件定义的切割系统约束潮流路径

示例：puf -x|。程序会提示三个文件：基态文件名（.bse）、输出文件名（.out）、流控门文件（.txt）。流控门文件为定义某切割平面的 WSCC 格式支路列表；例如可将关键支路 L RAVER 500 PAUL 5001 放入 flowgate.txt。

pvcurve — P-V 曲线

pvcurve 是当前 CMake 构建的 CFLOW 程序，用于按交互提示或 trace 文件执行 P-V 研究。旧的 pvcurve_pro 独立程序不再构建。

用法：$ pvcurve，可选后跟 trace（.trc）文件；按提示操作，回车使用默认值。

qvcurve — Q-V 曲线

qvcurve 是当前 CMake 构建的 CFLOW 程序，用于 Q-V 研究。旧的 qvcurve_pro 独立程序不再构建。

用法：$ qvcurve，可选后跟 trace（.trc）文件；按提示操作，回车使用默认值。

---