bpaflow 0.1.0__py3-none-win_amd64.whl

bpaflow/__init__.py

@@ -0,0 +1,3546 @@
+# bpaflow: Python 直调 libipfpy 的潮流 API 包（ctypes，无第三方硬依赖）。
+#
+# 与 pyflow（socket 客户端）并存；本包在同一进程内以 DLL 直调方式驱动
+# 潮流求解内核，并额外暴露内部计算数据：
+#   - y_matrix():        导纳矩阵（稀疏 CSR，G/B 分列）
+#   - jacobian():        因子化雅可比（/amtrx/ 布局，含行指针 jndex）
+#   - mismatch():        求解后偏差汇总（P/Q/总/角度 与迭代计数）
+#   - iteration_history(): 每次迭代误差最大的 8 条母线（/errbus/）
+#   - voltages():        电压实部/虚部/基准电压及内外序映射
+#
+# 修改类（P0，详见 docs/api/BPA潮流API说明.md）:
+#   - cards.py:          120 列变更卡构造/解析（列位与引擎源码逐字段对齐）
+#   - actions.py:        高层动作（Changeset：set_gen_p/outage_branch/
+#                        scale_load/...，带快照与读回校验）
+#   - put_inrecs():      批量提交变更卡（逐卡 rc + 引擎日志）
+#   - solve_case():      求解并返回结构化结果（收敛性/偏差/电压/重载/违规）
+#   - violations():      电压越限、支路过载、无功出力受限清单
+#   - capture():         引擎调用期间捕获 fd 1/2 输出；engine_log() 取回
+#
+# 用法:
+#   from bpaflow import BPAFlow
+#   pf = BPAFlow()            # 自动定位 libipfpy.dll，或 BPAFLOW_DLL 环境变量
+#   pf.init()
+#   pf.load_oldbase("bench.bse")
+#   with pf.changes() as cs:
+#       cs.set_gen_p("GEN1", 230.0, 150.0)
+#       cs.outage_branch("BUS1", 230.0, "BUS2", 230.0, "1")
+#   rpt = pf.solve_case(changes=cs)
+#   print(rpt["violations"]["counts"])
+#   pf.close()                # 收尾（关闭引擎文件单元；也可省略）
+#
+# 或用上下文管理器（自动 init，退出时自动 close）:
+#   with BPAFlow() as pf:
+#       pf.load_oldbase("bench.bse")
+#       pf.solution()
+"""BPAFlow: 潮流 Python API（直调 libipfpy）。"""
+
+import ctypes
+import json
+import math
+import os
+import sys
+import tempfile
+import time
+
+from ctypes import (CDLL, c_int, c_float, c_double, c_char, c_char_p,
+                    byref, create_string_buffer, c_void_p)
+
+from . import cards as _cards
+from .actions import Changeset as _Changeset
+from .actions import submit_card as _submit_card
+
+__all__ = ["BPAFlow", "PyFlowError", "SolutionRC", "connect", "__version__"]
+
+__version__ = "0.1.0"
+
+
+class SolutionRC:
+    """潮流求解返回码语义（pf_solution / pf_solve_area）。
+    
+    用法::
+        if rc == 0:
+            print("收敛")
+        elif rc == SolutionRC.NOT_CONVERGED:
+            print("发散")
+    
+    返回码对应 BPA-IPF 引擎 erfp.f 63-71 (±8Δ²ΔбäÁ¿¼ì²é) 及 p_cmde2.f
+    退出状态（er_quit 累计 fatal error 计数）。
+    """
+    CONVERGED = 0
+    NOT_CONVERGED = 7
+    ERROR = -1
+    _DESC = {
+        0: "收敛（CONVERGED）",
+        7: "发散（NOT CONVERGED）",
+        -1: "引擎错误（ERROR）",
+    }
+
+    @classmethod
+    def describe(cls, rc):
+        return cls._DESC.get(rc, "未知返回码 %d" % rc)
+
+MAXBUS = 13000
+MAXBRN = MAXBUS * 5 // 2
+MAXYE = MAXBRN * 5 // 2
+MAXLTC = MAXBRN // 10
+MAXTIE = MAXBRN // 10
+MAXMTX = 8 * MAXYE
+
+# 引擎日志环形缓冲上限（8 MiB，足够覆盖一次完整求解输出）
+_ENGINE_LOG_LIMIT = 8 * 1024 * 1024
+
+
+class PyFlowError(RuntimeError):
+    """潮流引擎错误。"""
+
+
+def _candidate_dll_paths():
+    cands = []
+    env = os.environ.get("BPAFLOW_DLL")
+    if env:
+        cands.append(env)
+    here = os.path.dirname(os.path.abspath(__file__))
+    roots = [here] + [os.path.dirname(here)]
+    for r in roots:
+        for sub in ("_native", "", "bin", "_build/pf/lib/cflow", "_build/apps",
+                    "_build/apps/bin",
+                    "_build/apps/Release", "_build", "_build/Release",
+                    "_build/apps/lib/cflow", "_build/apps/lib"):
+            cands.append(os.path.join(r, sub, "libipfpy.dll"))
+    return cands
+
+
+def _find_dll():
+    for p in _candidate_dll_paths():
+        if os.path.isfile(p):
+            return p
+    raise PyFlowError(
+        "libipfpy.dll 未找到；请设置环境变量 BPAFLOW_DLL 指向 DLL 路径。"
+    )
+
+
+def _runtime_dirs():
+    """候选的 MinGW 运行库目录（libgfortran-5.dll 等所在目录）。"""
+    here = os.path.dirname(os.path.abspath(__file__))
+    dirs = [os.path.join(here, "_native")]
+    env = os.environ.get("BPAFLOW_RUNTIME_DIR")
+    if env:
+        dirs += [d for d in env.split(os.pathsep) if d]
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        d = d.strip('"')
+        if d and os.path.isfile(os.path.join(d, "libgfortran-5.dll")):
+            dirs.append(d)
+    return dirs
+
+
+_RESOLVED_DLL_PATH = None
+
+
+def _gfortran_flush_candidates():
+    """libgfortran-5.dll 的候选路径（刷新 Fortran unit 缓冲用）。"""
+    cands = []
+    if _RESOLVED_DLL_PATH:
+        cands.append(os.path.join(os.path.dirname(_RESOLVED_DLL_PATH),
+                                  "libgfortran-5.dll"))
+    for d in _runtime_dirs():
+        cands.append(os.path.join(d, "libgfortran-5.dll"))
+    # 进程里已由 libipfpy 依赖载入时，按模块名即可解析。
+    cands.append("libgfortran-5.dll")
+    return cands
+
+
+def _flush_gfortran_streams(units=(0, 6)):
+    """尽力刷新 libgfortran 预连接单元（0=stderr, 6=stdout）。
+
+    重定向期间 Fortran 输出停在 libgfortran 的缓冲里，C 运行时的
+    fflush 推不动它；必须经 _gfortran_flush_i4 调用。失败静默。
+    """
+    import ctypes
+    for cand in _gfortran_flush_candidates():
+        try:
+            lib = ctypes.CDLL(cand)
+        except OSError:
+            continue
+        fn = getattr(lib, "_gfortran_flush_i4", None)
+        if fn is None:
+            continue
+        fn.argtypes = [ctypes.POINTER(ctypes.c_int)]
+        fn.restype = None
+        for u in units:
+            unit = ctypes.c_int(u)
+            try:
+                fn(ctypes.byref(unit))
+            except Exception:  # pragma: no cover - 防御性
+                pass
+        return
+
+
+def _load_lib(dll_path):
+    global _RESOLVED_DLL_PATH
+    _RESOLVED_DLL_PATH = os.path.abspath(dll_path)
+    if os.name == "nt" and hasattr(os, "add_dll_directory"):
+        for d in [os.path.dirname(os.path.abspath(dll_path))] + \
+                _runtime_dirs():
+            try:
+                os.add_dll_directory(d)
+            except OSError:
+                pass
+    return CDLL(dll_path)
+
+
+# 尝试加载 numpy（可选）；无 numpy 时退回 ctypes 数组
+try:
+    import numpy as _np
+except ImportError:
+    _np = None
+
+
+def _arr(ct_array, n, dtype=None):
+    """ctypes 数组 -> numpy 数组（无 numpy 时返回 ctypes 数组切片）。"""
+    if _np is not None:
+        a = _np.frombuffer(ct_array, count=n, dtype=dtype
+                           if dtype is not None else _np.float64)
+        return a.copy()
+    return list(ct_array[:n])
+
+
+def _ascii(s):
+    return s.encode("ascii") if isinstance(s, str) else s
+
+
+def _text(b):
+    return bytes(b).split(b"\x00")[0].decode("ascii", "replace")
+
+
+def _norm_name(name):
+    return (name or "").strip().upper()
+
+
+def _branch_dedup_key(branch):
+    """方向无关的支路去重键，保留分段号。"""
+    endpoints = tuple(sorted([
+        (_norm_name(branch.get("bus1_name")), round(float(branch.get("kv1", 0.0)), 2)),
+        (_norm_name(branch.get("bus2_name")), round(float(branch.get("kv2", 0.0)), 2)),
+    ]))
+    return (endpoints, (branch.get("ckt") or "").strip(),
+            (branch.get("type") or "").strip(),
+            int(branch.get("section") or 0))
+
+
+def _branch_kind(btype):
+    t = (btype or "").strip().upper()
+    if t in ("L", "E"):
+        return "line"
+    if t in ("T", "TP"):
+        return "transformer"
+    if t in ("LD", "LM"):
+        return "dc_line"
+    if t in ("R", "RM", "RN", "RQ", "RV", "RP"):
+        return "control"
+    return "unknown"
+
+
+def _branch_loading(branch):
+    """按 BPA 输出语义计算支路负载率。
+
+    L/E 类支路使用安培负载率，T/TP/R 类使用 MVA 负载率；优先采用
+    引擎输出中的 tot_*_load_pct，其次采用 crit_* 负载/额定，最后才
+    用端子视在功率除以 nominal rating 回退。返回值中的
+    loading_ratio 为比值，loading_pct 为百分数。
+    """
+    available = bool(branch.get("solution_available", True))
+    if not available:
+        return {"loading_ratio": None, "loading_pct": None,
+                "loading_kind": None, "rating_used": None,
+                "rating_code": None, "s_mva": None, "i_amps": None}
+
+    try:
+        s_mva = max(math.hypot(float(branch.get("Pin") or 0.0),
+                               float(branch.get("Qin") or 0.0)),
+                    math.hypot(float(branch.get("Pout") or 0.0),
+                               float(branch.get("Qout") or 0.0)))
+    except (TypeError, ValueError):
+        s_mva = 0.0
+    btype = (branch.get("type") or "").strip().upper()
+    if btype in ("LD", "LM"):
+        return {"loading_ratio": None, "loading_pct": None,
+                "loading_kind": "dc_line", "rating_used": None,
+                "rating_code": None, "s_mva": None, "i_amps": None}
+    if btype in ("R", "RM", "RN", "RQ", "RV", "RP"):
+        return {"loading_ratio": None, "loading_pct": None,
+                "loading_kind": "control_record", "rating_used": None,
+                "rating_code": None, "s_mva": None, "i_amps": None}
+    kv1 = float(branch.get("kv1") or 0.0)
+    total_rating = float(branch.get("total_rating") or 0.0)
+    ratio = None
+    kind = None
+    rating = None
+    code = None
+    i_amps = None
+
+    if btype in ("L", "E"):
+        pct = float(branch.get("tot_line_load_pct") or 0.0)
+        if pct > 0.0:
+            ratio = pct / 100.0
+            kind = "line_amps"
+        else:
+            amps = float(branch.get("crit_line_load_amps") or 0.0)
+            rating = float(branch.get("crit_line_rat_amps") or 0.0)
+            if rating > 0.0 and amps > 0.0:
+                ratio = amps / rating
+                kind = "line_amps"
+            elif kv1 > 0.0 and total_rating > 0.0:
+                i_amps = s_mva * 1000.0 / (math.sqrt(3.0) * kv1)
+                ratio = i_amps / total_rating
+                kind = "line_amps_fallback"
+                rating = total_rating
+        if i_amps is None:
+            i_amps = float(branch.get("crit_line_load_amps") or 0.0)
+        if rating is None:
+            rating = float(branch.get("crit_line_rat_amps") or 0.0)
+        code = branch.get("crit_line_rat_code") or "N"
+    elif btype in ("T", "TP", "R", "RM", "RN", "RQ", "RV", "RP"):
+        pct = float(branch.get("tot_xfmr_load_pct") or 0.0)
+        if pct > 0.0:
+            ratio = pct / 100.0
+            kind = "transformer_mva"
+        else:
+            load = float(branch.get("crit_xfmr_load_mva") or 0.0)
+            rating = float(branch.get("crit_xfmr_rat_mva") or 0.0)
+            if rating > 0.0 and load > 0.0:
+                ratio = load / rating
+                kind = "transformer_mva"
+            elif total_rating > 0.0:
+                ratio = s_mva / total_rating
+                kind = "transformer_mva_fallback"
+                rating = total_rating
+        if rating is None:
+            rating = float(branch.get("crit_xfmr_rat_mva") or 0.0)
+        code = branch.get("crit_xfmr_rat_code") or "N"
+    else:
+        kind = "unsupported_branch_type"
+
+    if ratio is None:
+        loading_pct = None
+    else:
+        loading_pct = ratio * 100.0
+    return {"loading_ratio": ratio, "loading_pct": loading_pct,
+            "loading_kind": kind, "rating_used": rating,
+            "rating_code": code, "s_mva": s_mva, "i_amps": i_amps}
+
+
+def _pfc_filename(command):
+    """Extract FILE= from a PFC command, including quoted paths with spaces."""
+    import re
+    match = re.search(
+        r"FILE\s*=\s*(?:\"([^\"]+)\"|'([^']+)'|([^,\s]+))",
+        command, re.IGNORECASE)
+    if not match:
+        return None
+    return next(value for value in match.groups() if value is not None)
+
+
+class _EngineCapture(object):
+    """引擎调用期间捕获 fd 1/2（gfortran unit 6 直写 stdout）。
+
+    输出落到临时文件（避免管道阻塞死锁），结束后整段读回追加到 sink
+    （bytes 片段列表）。替代旧 batch_n1._quiet 的"丢 NUL"方式。
+    """
+
+    def __init__(self, sink):
+        self._sink = sink
+
+    def __enter__(self):
+        sys.stdout.flush()
+        sys.stderr.flush()
+        self._saved_out = os.dup(1)
+        self._saved_err = os.dup(2)
+        fd, self._path = tempfile.mkstemp(prefix="bpaflow_cap_",
+                                          suffix=".log")
+        os.close(fd)
+        self._cap = os.open(self._path, os.O_WRONLY | os.O_APPEND)
+        os.dup2(self._cap, 1)
+        os.dup2(self._cap, 2)
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        # 重定向期间 C 运行时把 stdout 视为全缓冲，引擎 printf / Fortran
+        # unit 6 的尾部滞留缓冲；先刷新二者，再恢复 fd 并读回日志。
+        import ctypes
+        for _crt in ("msvcrt", "ucrtbase"):
+            try:
+                ctypes.CDLL(_crt).fflush(None)
+            except OSError:
+                pass
+        _flush_gfortran_streams()
+        sys.stdout.flush()
+        os.dup2(self._saved_out, 1)
+        os.dup2(self._saved_err, 2)
+        os.close(self._cap)
+        os.close(self._saved_out)
+        os.close(self._saved_err)
+        try:
+            with open(self._path, "rb") as f:
+                data = f.read()
+        finally:
+            try:
+                os.unlink(self._path)
+            except OSError:
+                pass
+        if data:
+            self._sink.append(data)
+        return False
+
+
+class BPAFlow(object):
+    """潮流引擎客户端（ctypes 直调 libipfpy）。"""
+
+    # ---- pf_get_list 枚举值（cflowlib.h enum pf_list_type）----
+    AREA_LIST, BUS_LIST, KV_LIST, OWNER_LIST, REC_TYPE_LIST, ZONE_LIST = \
+        range(6)
+
+    def __init__(self, dll=None, audit=None):
+        self._lib = _load_lib(dll or _find_dll())
+        self._setup_prototypes()
+        self._initialized = False
+        self._closed = False
+        # 引擎输出捕获（P0）：最近一次捕获 + 累积环形缓冲
+        self._log_parts = []
+        self._log = bytearray()
+        # 快照字典（P1）：tag -> 临时 .bse 路径
+        self._snapshots = {}
+        # 单步牛顿会话与实例级支路开断快照。
+        self._solution_session = "IDLE"
+        self._solution_config = {
+            "method": "newton", "decoupled": None,
+            "newton": None, "optim": None, "flat_start": None,
+        }
+        self._branch_snapshots = {}
+        # 查询缓存：load/change/solution 后统一失效，避免 solve_case
+        # 重复走逐记录 IPC。
+        self._cache = {}
+        # 审计日志（P0，可选）: 文件路径或文件对象；记录 put_inrecs/
+        # solve_case 调用摘要（JSONL）
+        self._audit = audit
+        self._audit_owned = False
+        if audit is not None and not hasattr(audit, "write"):
+            self._audit = open(audit, "a", encoding="utf-8")
+            self._audit_owned = True
+
+    def _invalidate_cache(self):
+        """清空查询缓存。**所有**改变算例、解或查询基准的入口都要调用。"""
+        self._cache.clear()
+
+    # ------------------------------------------------------------------
+    # 引擎输出捕获（P0）
+    # ------------------------------------------------------------------
+    def _append_log(self, data):
+        if not data:
+            return
+        self._log += data
+        if len(self._log) > _ENGINE_LOG_LIMIT:
+            del self._log[:len(self._log) - _ENGINE_LOG_LIMIT]
+        self._log_parts.append(data)
+        if len(self._log_parts) > 100:
+            del self._log_parts[:len(self._log_parts) - 100]
+
+    def capture(self):
+        """上下文管理器: 引擎调用期间捕获 fd 1/2 输出。
+
+        用法::
+            with pf.capture():
+                rc = pf.solution()
+            log = pf.last_engine_log()
+        """
+        return _EngineCapture(self._log_parts)
+
+    def last_engine_log(self, n=None):
+        """最近一次 capture() 块内的引擎输出（str）。"""
+        parts = self._log_parts
+        if not parts:
+            return ""
+        text = b"".join(parts[-1:]).decode("ascii", "replace")
+        return text[-n:] if n else text
+
+    def engine_log(self, n=None):
+        """自会话开始累积的引擎输出（str，环形缓冲尾部）。"""
+        if n:
+            return bytes(self._log[-n:]).decode("ascii", "replace")
+        return bytes(self._log).decode("ascii", "replace")
+
+    def _audit_log(self, event, detail=None):
+        if self._audit is None:
+            return
+        rec = {"t": time.time(), "event": event}
+        if detail:
+            rec.update(detail)
+        try:
+            self._audit.write(json.dumps(rec, ensure_ascii=False) + "\n")
+            self._audit.flush()
+        except (OSError, ValueError):
+            pass
+
+    # ------------------------------------------------------------------
+    # 变更卡批量提交（P0）
+    # ------------------------------------------------------------------
+    def put_inrecs(self, cards_list, capture=True):
+        """批量提交变更卡（逐卡 pf_put_inrec）。
+
+        cards_list 为 [(描述, 卡文本), ...] 或 [卡文本, ...]；
+        capture=True 时引擎调用输出被捕获（不刷屏）。
+        返回 {"n": 卡数, "rcs": [每卡 rc], "fail": [rc!=0 的描述]}
+        """
+        if isinstance(cards_list, (str, bytes)):
+            raise TypeError(
+                "cards_list 必须是卡片序列；提交单张卡请使用 put_inrec()，"
+                "或传入 [card]")
+        seq = []
+        for item in cards_list:
+            if isinstance(item, (tuple, list)) and len(item) == 2:
+                if not isinstance(item[1], (str, bytes)):
+                    raise TypeError("变更卡文本必须是 str 或 bytes")
+                seq.append((str(item[0]), item[1]))
+            else:
+                if not isinstance(item, (str, bytes)):
+                    raise TypeError("变更卡必须是 str/bytes 或 (描述, 卡文本)")
+                seq.append(("", item))
+        rcs, fail = [], []
+        sink = []
+        cap = _EngineCapture(sink) if capture else None
+
+        def _run():
+            for desc, card in seq:
+                rc = self._lib.pf_put_inrec(_ascii(card))
+                rcs.append(rc)
+                if rc != 0:
+                    preview = (_text(card) if isinstance(card, bytes)
+                               else card)[:20]
+                    fail.append(desc or preview)
+
+        if cap:
+            with cap:
+                _run()
+        else:
+            _run()
+        self._append_log(b"".join(sink))
+        self._invalidate_cache()
+        self._audit_log("put_inrecs", {"n": len(seq), "fail": fail})
+        return {"n": len(seq), "rcs": rcs, "fail": fail}
+
+# ------------------------------------------------------------------
+    # LTC 变压器数据（直接读取内核 COMMON 块）
+    # ------------------------------------------------------------------
+    def ltc_data(self):
+        """返回 LTC 变压器列表。
+
+        读取内核 /tran/ 公共块，不依赖 PFO 输出。每项包含变压器两端、
+        kctrl 原始控制码、受控母线映射、tap 位置/限值、Q 限值和变比侧。
+        tap 为内核标幺变比，tap_max/tap_min 同量纲；qmax_mvar/qmin_mvar
+        为 MVAr，仅对 RQ/RN 类控制有效。
+        """
+        if "ltc" in self._cache:
+            return self._cache["ltc"]
+        ci = self.case_info()
+        nltc = c_int()
+        maxltc = max(int(ci.get("num_LTC_xfmrs", 0)) + 10, 64)
+        while True:
+            cbus1 = (c_char * (8 * maxltc))()
+            cbus2 = (c_char * (8 * maxltc))()
+            base1 = (c_float * maxltc)()
+            base2 = (c_float * maxltc)()
+            kctrl = (c_int * maxltc)()
+            tap_pos = (c_double * maxltc)()
+            tap_max = (c_float * maxltc)()
+            tap_min = (c_float * maxltc)()
+            tap_steps = (c_float * maxltc)()
+            rtype = (c_int * maxltc)()
+            lim_reached = (c_int * maxltc)()
+            qmax = (c_double * maxltc)()
+            qmin = (c_double * maxltc)()
+            num_taps = (c_int * maxltc)()
+            var_tap_side = (c_int * maxltc)()
+            use_ext = hasattr(self._lib, "ipfpy_get_ltc_ext")
+            if use_ext:
+                self._lib.ipfpy_get_ltc_ext(
+                    byref(nltc), byref(c_int(maxltc)),
+                    cbus1, cbus2, base1, base2, kctrl, tap_pos,
+                    tap_max, tap_min, tap_steps, rtype, lim_reached,
+                    qmax, qmin, num_taps, var_tap_side)
+            else:
+                self._lib.ipfpy_get_ltc(
+                    byref(nltc), byref(c_int(maxltc)),
+                    cbus1, cbus2, base1, base2, kctrl, tap_pos,
+                    tap_max, tap_min, tap_steps, rtype, lim_reached)
+            if nltc.value < maxltc or maxltc >= MAXLTC:
+                break
+            maxltc = min(maxltc * 2, MAXLTC)
+        n = nltc.value
+        if n <= 0:
+            self._cache["ltc"] = []
+            return []
+        vd = self.voltages()
+        names, bases = vd["names"], vd["base"]
+        out = []
+        for i in range(n):
+            n1 = _text(bytes(cbus1[i * 8:(i + 1) * 8])).strip()
+            n2 = _text(bytes(cbus2[i * 8:(i + 1) * 8])).strip()
+            kc = kctrl[i]
+            ctrl_name = None
+            ctrl_kv = None
+            control_side = None
+            if 0 < kc <= len(names):
+                ctrl_name = names[kc - 1].strip()
+                ctrl_kv = bases[kc - 1]
+                control_side = "remote"
+            elif kc == -1:
+                ctrl_name, ctrl_kv, control_side = n1, base1[i], "bus1"
+            elif kc == -2:
+                ctrl_name, ctrl_kv, control_side = n2, base2[i], "bus2"
+            out.append({
+                "bus1": {"name": n1, "kv": base1[i]},
+                "bus2": {"name": n2, "kv": base2[i]},
+                "kctrl": kc,
+                "controlled_bus": ({"name": ctrl_name, "kv": ctrl_kv}
+                                   if ctrl_name is not None else None),
+                "control_side": control_side,
+                "tap": tap_pos[i],
+                "tap_max": tap_max[i],
+                "tap_min": tap_min[i],
+                "steps": tap_steps[i],
+                "num_taps": int(num_taps[i]) if use_ext else None,
+                "var_tap_side": (int(var_tap_side[i]) if use_ext else None),
+                "qmax_mvar": float(qmax[i]) if use_ext else None,
+                "qmin_mvar": float(qmin[i]) if use_ext else None,
+                "rtype": rtype[i],
+                "lim_reached": bool(lim_reached[i]),
+            })
+        self._cache["ltc"] = out
+        return out
+
+    # ------------------------------------------------------------------
+    # 结构数据与违规报告（P0）
+    # ------------------------------------------------------------------
+    def violations(self, v_tol=0.005, load_pct=1.0, q_tol=None,
+                   capture=True):
+        """扫描电压/支路/无功/LTC/孤岛违规。
+
+        过载门槛按支路类型取引擎负载率：L/E 用安培负载率，T/TP 用
+        MVA 负载率；R/RP 控制记录和 DC 线路不参与 AC 过载。load_pct
+        为比值，1.0 表示 100%。无功受限只检查
+        BQ/BG/BX 母线；B 类母线的 Qsch 是计划注入，BS 平衡机的 Qgen
+        是平衡结果，二者都不作为限值。
+        """
+        return self._violations_from(
+            self._buses_all(), self._branches_all(False),
+            v_tol=v_tol, load_pct=load_pct, q_tol=q_tol)
+
+    def _violations_from(self, buses, branches, v_tol=0.005,
+                         load_pct=1.0, q_tol=None):
+        v_under, v_over, overload, q_limited = [], [], [], []
+        for b in buses:
+            btype = (b.get("type") or "").strip().upper()
+            if b.get("is_dc") or btype in ("BD", "BM"):
+                continue
+            kv = float(b.get("kv") or 0.0)
+            if kv <= 0.0:
+                continue
+            vmag_pu = float(b.get("Vmag") or 0.0) / kv
+            vmax = float(b.get("Vhold_Vmax") or 0.0)
+            vmin = float(b.get("Vmin_Vdeg") or 0.0)
+            if btype == "BS":
+                # BS 母线的 Vmin_Vdeg 字段保存电压角，不是电压下限。
+                vmin = 0.0
+            if vmin > 0.0 and vmag_pu < vmin - v_tol:
+                v_under.append({"bus": b["name"], "kv": b["kv"],
+                                "vmag": vmag_pu, "limit": vmin,
+                                "bus_type": btype})
+            if vmax > 0.0 and vmag_pu > vmax + v_tol:
+                v_over.append({"bus": b["name"], "kv": b["kv"],
+                               "vmag": vmag_pu, "limit": vmax,
+                               "bus_type": btype})
+            if btype not in ("BQ", "BG", "BX"):
+                continue
+            qmax = float(b.get("Qsch_Qmax") or 0.0)
+            qmin = float(b.get("Qmin") or 0.0)
+            if qmax <= 0.0 and qmin >= 0.0:
+                continue
+            tol = q_tol if q_tol is not None else max(
+                0.5, 0.01 * max(abs(qmax), abs(qmin)))
+            qgen = float(b.get("Qgen") or 0.0)
+            if qgen >= qmax - tol or qgen <= qmin + tol:
+                q_limited.append({"bus": b["name"], "kv": b["kv"],
+                                  "qgen": qgen, "qmax": qmax,
+                                  "qmin": qmin, "bus_type": btype})
+
+        seen = set()
+        for br in branches:
+            if not br.get("solution_available", True):
+                continue
+            key = _branch_dedup_key(br)
+            if key in seen:
+                continue
+            seen.add(key)
+            ratio = br.get("loading_ratio")
+            if ratio is None:
+                continue
+            if ratio > load_pct:
+                overload.append({
+                    "bus1": br["bus1_name"].strip(),
+                    "bus2": br["bus2_name"].strip(),
+                    "ckt": br["ckt"],
+                    "pct": ratio,
+                    "loading_pct": ratio * 100.0,
+                    "s_mva": br.get("s_mva"),
+                    "i_amps": br.get("i_amps"),
+                    "rating": br.get("rating_used"),
+                    "rating_code": br.get("rating_code"),
+                    "loading_kind": br.get("loading_kind"),
+                    "section": br.get("section", 0),
+                })
+
+        ltc_limited = []
+        for l in self.ltc_data():
+            if not l["lim_reached"]:
+                continue
+            ltc_limited.append({
+                "bus1": l["bus1"]["name"],
+                "bus2": l["bus2"]["name"],
+                "controlled_bus": l.get("controlled_bus"),
+                "control_side": l.get("control_side"),
+                "tap": l["tap"],
+                "tap_min": l["tap_min"],
+                "tap_max": l["tap_max"],
+                "steps": l["steps"],
+                "qmax_mvar": l.get("qmax_mvar"),
+                "qmin_mvar": l.get("qmin_mvar"),
+                "rtype": l["rtype"],
+            })
+
+        islands = self._find_islands(buses, branches)
+        return {
+            "v_under": v_under, "v_over": v_over,
+            "overload": overload, "q_limited": q_limited,
+            "ltc_limited": ltc_limited, "islands": islands,
+            "counts": {"v_under": len(v_under), "v_over": len(v_over),
+                       "overload": len(overload),
+                       "q_limited": len(q_limited),
+                       "ltc_limited": len(ltc_limited),
+                       "islands": len(islands)},
+        }
+
+    def _find_islands(self, buses=None, branches=None):
+        """检测不含平衡母线（BS）的连通分量（孤岛）。
+
+        节点 = 当前活动的 AC 母线，边 = 当前活动支路。停运支路不参与
+        连通性。返回 [{"buses": [...], "pgen_mw", "pload_mw",
+        "n_buses"}, ...]。
+        """
+        if buses is None:
+            buses = self._buses_all()
+        if branches is None:
+            branches = self._branches_all(False)
+        if not buses:
+            return []
+        key = lambda b: (b["name"].strip().upper(), round(b["kv"], 3))
+        nodes = [key(b) for b in buses
+                 if not b.get("is_dc")
+                 and (b.get("type") or "").strip().upper() not in ("BD", "BM")]
+        adj = {n: [] for n in nodes}
+        for br in branches:
+            if not br.get("solution_available", True):
+                continue
+            if br.get("branch_kind") not in ("line", "transformer"):
+                continue
+            a = (br["bus1_name"].strip().upper(), round(br["kv1"], 3))
+            b = (br["bus2_name"].strip().upper(), round(br["kv2"], 3))
+            if a in adj and b in adj:
+                adj[a].append(b)
+                adj[b].append(a)
+        seen = set()
+        comps = []
+        for n in nodes:
+            if n in seen:
+                continue
+            comp, stack = [], [n]
+            seen.add(n)
+            while stack:
+                cur = stack.pop()
+                comp.append(cur)
+                for nb in adj.get(cur, ()):
+                    if nb not in seen:
+                        seen.add(nb)
+                        stack.append(nb)
+            comps.append(comp)
+        slack_keys = set(
+            key(b) for b in buses
+            if b["type"].strip().upper() == "BS")
+        busmap = {key(b): b for b in buses}
+        islands = []
+        for comp in comps:
+            if any(c in slack_keys for c in comp):
+                continue
+            pgen = sum(busmap[c]["Pgen"] for c in comp if c in busmap)
+            pload = sum(busmap[c]["Pload"] for c in comp if c in busmap)
+            islands.append({
+                "buses": [{"name": c[0], "kv": c[1]}
+                          for c in sorted(comp)],
+                "n_buses": len(comp),
+                "pgen_mw": pgen, "pload_mw": pload,
+            })
+        return islands
+
+    def solve_case(self, changes=None, capture=True, v_tol=0.005,
+                   load_pct=1.0, auto_rollback=True,
+                   include_violations=True, include_loss=True,
+                   include_voltage_summary=True):
+        """施加变更卡（可选）并求解，返回结构化结果。
+
+        changes: Changeset 实例或 [(描述, 卡)] 列表；
+        auto_rollback: True 时变更提交前自动快照，失败时自动回滚；
+        include_violations/include_loss/include_voltage_summary:
+            批量场景可关闭不需要的后处理，显著减少逐记录查询。
+        返回 dict:
+          rc / converged          求解返回码 / 是否收敛
+          mismatch                最终偏差（MW/MVAr）
+          iterations              迭代计数
+          vmin/vmax               全网电压上下限（pu，含所在母线）
+          worst_loading           最重载支路（比值为 1.0 表示 100%）
+          loss                    网损（MW/MVAr）
+          violations              violations() 结果；跳过时为 None
+          engine_log              capture=True 时的引擎输出
+          rolled_back             auto_rollback 触发回滚时为 True
+        """
+        rc = 0
+        sink = []
+        cap = _EngineCapture(sink) if capture else None
+        snap_tag = None
+
+        def _run():
+            nonlocal rc
+            if changes is not None:
+                if isinstance(changes, _Changeset):
+                    seq = list(changes.cards())
+                else:
+                    if isinstance(changes, (str, bytes)):
+                        raise PyFlowError(
+                            "changes 必须是 Changeset 或 (描述, 卡文本) 序列")
+                    seq = list(changes)
+                for item in seq:
+                    if not isinstance(item, (tuple, list)) or len(item) != 2:
+                        raise PyFlowError(
+                            "changes 的每一项必须是 (描述, 卡文本)")
+                    desc, card = item
+                    if not isinstance(card, (str, bytes)):
+                        raise PyFlowError("变更卡文本必须是 str 或 bytes")
+                    r = _submit_card(self, card)
+                    if r != 0:
+                        raise PyFlowError(
+                            "变更卡提交失败 rc=%d: %s\n%s"
+                            % (r, desc, card))
+            rc = self._lib.pf_solution()
+
+        if changes is not None and auto_rollback:
+            try:
+                snap_tag = self.snapshot()
+            except PyFlowError:
+                snap_tag = None
+
+        try:
+            if cap:
+                with cap:
+                    _run()
+            else:
+                _run()
+        except PyFlowError as e:
+            if snap_tag is not None:
+                try:
+                    self.restore(snap_tag)
+                finally:
+                    self.drop_snapshot(snap_tag)
+            rpt = {
+                "rc": -1,
+                "converged": False,
+                "error": str(e),
+                "rolled_back": snap_tag is not None,
+                "engine_log": b"".join(sink).decode("ascii", "replace")
+                if capture else "",
+            }
+            return rpt
+
+        self._invalidate_cache()
+        self._append_log(b"".join(sink))
+
+        m = self.mismatch()
+        rpt = {
+            "rc": rc,
+            "converged": rc == 0,
+            "mismatch": {"dp_mw": m["dptot"], "dq_mvar": m["dqtot"],
+                         "total": m["dttot"], "angle": m["datot"]},
+            "iterations": {"total": m["ittot"],
+                           "decoupled": m["itrhis_decoupled"],
+                           "nr": m["itrhis_nr"]},
+            "violations": None,
+            "violations_skipped": not include_violations,
+            "loss": None,
+            "worst_loading": None,
+        }
+        if rc == 0:
+            buses = (self._buses_all()
+                     if (include_voltage_summary or include_violations)
+                     else None)
+            branches = (self._branches_all(False)
+                        if (include_loss or include_violations)
+                        else None)
+            if include_voltage_summary:
+                vmin_b = vmax_b = None
+                vmin = float("inf")
+                vmax = float("-inf")
+                for b in buses:
+                    if b.get("is_dc"):
+                        continue
+                    kv = float(b.get("kv") or 0.0)
+                    if kv <= 0.0:
+                        continue
+                    vmag_pu = float(b.get("Vmag") or 0.0) / kv
+                    if vmag_pu < vmin:
+                        vmin, vmin_b = vmag_pu, b["name"]
+                    if vmag_pu > vmax:
+                        vmax, vmax_b = vmag_pu, b["name"]
+                rpt["vmin"], rpt["vmax"] = vmin, vmax
+                rpt["vmin_bus"], rpt["vmax_bus"] = vmin_b, vmax_b
+            if include_loss:
+                worst, who, kind, code = 0.0, "", None, None
+                p_loss, q_loss = 0.0, 0.0
+                seen = set()
+                for br in branches:
+                    if not br.get("solution_available", True):
+                        continue
+                    if br.get("branch_kind") not in ("line", "transformer"):
+                        continue
+                    key = _branch_dedup_key(br)
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    p_loss += br["Ploss"]
+                    q_loss += br["Qloss"]
+                    ratio = br.get("loading_ratio")
+                    if ratio is not None and ratio > worst:
+                        worst = ratio
+                        who = "%s-%s %s" % (
+                            br["bus1_name"].strip(),
+                            br["bus2_name"].strip(), br["ckt"])
+                        kind = br.get("loading_kind")
+                        code = br.get("rating_code")
+                rpt["worst_loading"] = {
+                    "pct": worst, "loading_pct": worst * 100.0,
+                    "branch": who, "loading_kind": kind,
+                    "rating_code": code,
+                }
+                rpt["loss"] = {"p_mw": p_loss, "q_mvar": q_loss}
+            if include_violations:
+                rpt["violations"] = self._violations_from(
+                    buses, branches, v_tol=v_tol, load_pct=load_pct)
+        else:
+            if include_violations:
+                rpt["violations"] = {
+                    "counts": {"v_under": 0, "v_over": 0,
+                               "overload": 0, "q_limited": 0,
+                               "ltc_limited": 0, "islands": 0}}
+        if capture:
+            rpt["engine_log"] = b"".join(sink).decode("ascii", "replace")
+        if snap_tag is not None:
+            rolled_back = False
+            try:
+                if rc != 0:
+                    self.restore(snap_tag)
+                    rolled_back = True
+            finally:
+                self.drop_snapshot(snap_tag)
+            rpt["rolled_back"] = rolled_back
+        self._audit_log("solve_case", {"rc": rc, "converged": rc == 0})
+        return rpt
+
+    # ------------------------------------------------------------------
+    # PFO 报告（P1，封装引擎标准输出报告）
+    # ------------------------------------------------------------------
+    def write_pfo(self, path):
+        """将引擎当前解的标准输出报告写入文件。
+
+        求解一次（如已求解则快速返回）并将 stdout 捕获写至 path。
+        返回 rc。
+        """
+        with self.capture():
+            rc = self._lib.pf_solution()
+        self._invalidate_cache()
+        log = self.last_engine_log()
+        with open(path, "w", encoding="ascii", errors="replace") as f:
+            f.write(log)
+        return rc
+
+    def parse_pfo(self, path):
+        """解析 PFO 文件为结构化 dict（不触发求解）。
+
+        PFO 文件的格式为引擎标准输出报告，含求解参数、迭代表、
+        母线/支路统计、收敛状态等。此解析器提取关键字段。
+        """
+        with open(path, encoding="ascii", errors="replace") as f:
+            text = f.read()
+        return self._parse_pfo_text(text)
+
+    def report_pfo(self, path=None):
+        """生成 PFO 报告并解析为结构化 dict。
+
+        用法::
+            rpt = pf.report_pfo()           # 用当前缓存的引擎输出
+            rpt = pf.report_pfo("case.pfo") # 写入文件 + 解析
+
+        返回 dict:
+          converged          是否收敛
+          rc                 求解返回码
+          n_buses/n_branches 母线/支路统计
+          iterations         迭代计数（含各类型）
+          final_mismatch     最终 P/Q 偏差
+          warnings           警告消息列表
+          raw_text           完整原始文本
+        """
+        if path:
+            rc = self.write_pfo(path)
+            text = open(path, encoding="ascii", errors="replace").read()
+        else:
+            log = self.last_engine_log()
+            if not log:
+                with self.capture():
+                    rc = self._lib.pf_solution()
+                self._invalidate_cache()
+                log = self.last_engine_log()
+            else:
+                rc = 0
+            text = log
+        return self._parse_pfo_text(text, rc=rc)
+
+    @staticmethod
+    def _parse_ltc_line(line):
+        """解析 PFO "Summary of LTC Transformers" 段中的一行（ltcsum.f 160 格式）。
+
+        定宽列（0 索引）:
+          1-8    被控母线名      a8
+          9-14   被控母线基准    f6.1
+          17-34  vmin/vmax/vact 3f6.3
+          37-44  bus1（T 卡首端）a8
+          45-50  bus1 基准       f6.1
+          52-59  bus2（T 卡末端）a8
+          60-65  bus2 基准       f6.1
+          68-80  tap1/tap2      'xxx.xx/xxx.xx'
+          81-88  tapmin         f8.2
+          89-96  tapmax         f8.2
+          97-102 istep '/' itstep
+          104+   状态标记（'TMIN limit reached' / 'TMAX limit reached' /
+                  'V violation  =x.xxx'）
+        返回 dict 或 None（行格式不符）。
+        """
+        def _f(s):
+            s = s.strip()
+            return float(s) if s else None
+
+        import re
+        try:
+            item = {
+                "controlled_bus": line[1:9].strip(),
+                "controlled_kv": _f(line[9:15]),
+                "bus1": line[37:45].strip(),
+                "kv1": _f(line[45:51]),
+                "bus2": line[52:60].strip(),
+                "kv2": _f(line[60:66]),
+                "vmin": _f(line[17:23]),
+                "vmax": _f(line[23:29]),
+                "v_actual": _f(line[29:35]),
+                "tap1": None, "tap2": None,
+                "tapmin": _f(line[81:89]),
+                "tapmax": _f(line[89:97]),
+            }
+        except ValueError:
+            return None
+        tap_pair = line[68:81].strip()
+        if "/" in tap_pair:
+            t1, t2 = tap_pair.split("/", 1)
+            item["tap1"] = _f(t1)
+            item["tap2"] = _f(t2)
+        if "TMIN limit reached" in line:
+            item["limit"] = "TMIN"
+        elif "TMAX limit reached" in line:
+            item["limit"] = "TMAX"
+        elif "V violation" in line:
+            item["limit"] = "VVIOL"
+            try:
+                item["violation_mw_kv"] = _f(
+                    line[104:].split("=", 1)[1].strip())
+            except (IndexError, ValueError):
+                pass
+        else:
+            item["limit"] = None
+        m = re.match(r"(\d+)/(\d+)", line[97:103].strip())
+        if m:
+            item["step"] = int(m.group(1))
+            item["nsteps"] = int(m.group(2))
+        return item
+
+    @staticmethod
+    def _parse_pfo_text(text, rc=0):
+        """解析 PFO 文本，提取关键字段。
+
+        返回 dict:
+          converged          是否收敛
+          rc                 求解返回码
+          n_buses/n_branches 母线/支路统计
+          iterations         迭代计数
+          final_mismatch     最终 P/Q 偏差
+          vmin/vmax          解后电压上下限（pu）
+          worst_loading      最重载支路
+          loss               网损 MW+MVAr
+          area_interchange   区域交换摘要
+          ltc_summary        LTC 统计摘要
+          warnings           警告消息列表
+          raw_text           完整原始文本
+        """
+        import re
+        result = {"rc": rc, "converged": False, "warnings": []}
+        lines = text.split("\n")
+
+        # 母线/支路计数
+        for m in re.finditer(r"(\d+)\s+BUSES", text):
+            result["n_buses"] = int(m.group(1))
+        for m in re.finditer(r"(\d+)\s+BRANCHES", text):
+            result["n_branches"] = int(m.group(1))
+        for m in re.finditer(r"(\d+)\s+--\s+LTC\s+TRANSFORMERS", text):
+            result["ltc_summary"] = {"n_ltc": int(m.group(1))}
+        for m in re.finditer(r"(\d+)\s+--\s+SLACK\s+BUSES", text):
+            result.setdefault("ltc_summary", {})["n_slack"] = int(m.group(1))
+
+        # "Summary of LTC Transformers" 段（ltcsum.f 160 格式）:
+        #   '0' + 被控母线 a8 + 基准 f6.1 + 3f6.3(电压限/实际) + bus_k + base_k
+        #   + bus_m + base_m + tap1/tap2(列 69 起) + tapmin/tapmax(列 82/90 起)
+        #   + istep/itstep + 行尾状态标记（TMIN/TMAX limit reached、
+        #   V violation =x.xxx）
+        for i, line in enumerate(lines):
+            if "Summary of LTC Transformers" in line:
+                ltc = result.setdefault("ltc_summary", {})
+                ltc.setdefault("limited", [])
+                j = i + 1
+                while j < len(lines) and (
+                        "min max actual" in lines[j]
+                        or "Controlling" in lines[j]
+                        or "Tap" in lines[j]
+                        or "----" in lines[j]
+                        or not lines[j].strip()):
+                    j += 1
+                while j < len(lines):
+                    l = lines[j]
+                    if not l.startswith("0") or "/" not in l:
+                        break
+                    if "limit reached" not in l and "V violation" not in l:
+                        j += 1
+                        continue
+                    item = BPAFlow._parse_ltc_line(l)
+                    if item:
+                        if "limit reached" in l:
+                            ltc["limited"].append(item)
+                    j += 1
+                break
+
+        # 收敛状态
+        if "SUCCESSFUL SOLUTION REACHED" in text:
+            result["converged"] = True
+        elif "SOLUTION DID NOT CONVERGE" in text:
+            result["converged"] = False
+        elif rc != 0:
+            result["converged"] = False
+
+        # 迭代表行 → 最终偏差
+        iter_rows = []
+        for line in lines:
+            parts = line.strip().split()
+            if len(parts) >= 6 and parts[0].isdigit():
+                try:
+                    p_err = float(parts[1])
+                    q_err = float(parts[2])
+                    iter_rows.append((int(parts[0]), p_err, q_err))
+                except (ValueError, IndexError):
+                    pass
+        if iter_rows:
+            last = iter_rows[-1]
+            result["final_mismatch"] = {
+                "P_mw": last[1], "Q_mvar": last[2],
+                "iterations": last[0],
+            }
+            result["iterations"] = {"total": len(iter_rows)}
+
+        # 迭代数与总线/支路统计中提取
+        for m in re.finditer(
+                r"ITERATION\s+.*\(+\s*(\d+)\s*\)\s+Decoupled\s+"
+                r".*\(+\s*(\d+)\s*\)\s+Modified\s+Newton\s+"
+                r".*\(+\s*(\d+)\s*\)\s+Newton",
+                text):
+            result.setdefault("iterations", {})
+            result["iterations"].update({
+                "max": int(m.group(1)),
+                "decoupled": int(m.group(2)),
+                "modified_newton": int(m.group(3)),
+            })
+
+        # 警告消息
+        for line in lines:
+            s = line.strip("* \r").strip()
+            if s.startswith("WARNING") or "  WARNING  " in line:
+                result["warnings"].append(s)
+
+        # 网损（从后往前找 "LOSSES" 或 "Ploss" 不适合，PFO 不含明细）
+        # 高/低电压与重载支路由 solve_case 提供，PFO 不直接含
+
+        return result
+
+    def changes(self):
+        """新建一个 Changeset（变更卡集合 + 快照 + 校验）。"""
+        return _Changeset(self)
+
+    # ---- 高层动作便捷方法（P0；委托给 actions.Changeset）------------
+    def _one_shot(self, method, *args, **kwargs):
+        self._ensure_mutation_allowed()
+        cs = _Changeset(self)
+        getattr(cs, method)(*args, **kwargs)
+        return cs.apply()
+
+    def set_gen_p(self, name, kv, pgen):
+        """设置母线有功出力调度（MW）并提交。"""
+        return self._one_shot("set_gen_p", name, kv, pgen)
+
+    def set_gen_q_limits(self, name, kv, qmax=None, qmin=None):
+        """设置无功出力上下限（MVAr）并提交。"""
+        return self._one_shot("set_gen_q_limits", name, kv, qmax=qmax,
+                              qmin=qmin)
+
+    def set_q_sched(self, name, kv, q):
+        """设置母线无功出力调度（MVAr）并提交。"""
+        return self._one_shot("set_q_sched", name, kv, q)
+
+    def set_volt_target(self, name, kv, vmax=None, vmin=None):
+        """设置母线电压上下限（pu）并提交。"""
+        return self._one_shot("set_volt_target", name, kv, vmax=vmax,
+                              vmin=vmin)
+
+    def set_load(self, name, kv, pload=None, qload=None):
+        """设置母线负荷（MW/MVAr）并提交。"""
+        return self._one_shot("set_load", name, kv, pload=pload,
+                              qload=qload)
+
+    def set_bus_generation(self, name, kv, p_mw, allow_slack=False):
+        """设置 BPA B 卡母线的聚合有功出力。
+
+        该数据模型没有机组 ID，因此本方法明确采用母线聚合语义；默认
+        拒绝修改平衡母线，避免求解器重新分配后造成“设置未生效”错觉。
+        """
+        bus = self.bus(name, kv)
+        if bus is None:
+            raise PyFlowError("母线 %s %g kV 不存在" % (name, kv))
+        if bus["type"].strip().upper() == "BS" and not allow_slack:
+            raise PyFlowError(
+                "平衡母线出力由潮流平衡决定；确需改卡请显式传 "
+                "allow_slack=True")
+        result = self.set_gen_p(name, kv, float(p_mw))
+        result["semantics"] = "aggregate_bus_generation"
+        return result
+
+    def set_bus_load(self, name, kv, p_mw=None, q_mvar=None):
+        """设置 BPA B 卡母线的聚合负荷（MW/MVAr）。"""
+        if p_mw is None and q_mvar is None:
+            raise ValueError("p_mw 与 q_mvar 至少指定一个")
+        if self.bus(name, kv) is None:
+            raise PyFlowError("母线 %s %g kV 不存在" % (name, kv))
+        result = self.set_load(name, kv, pload=p_mw, qload=q_mvar)
+        result["semantics"] = "aggregate_bus_load"
+        return result
+
+    def get_branch_status(self, bus1, kv1, bus2, kv2, ckt=None,
+                          section=None):
+        """返回支路当前是否在运，以及是否可由本实例快照恢复。
+
+        支路在内核支路表中出现时为在运；否则检查本实例 outage_branch
+        保存的快照。基础算例中已经停运、从未进入内核支路表的支路无法
+        通过该接口识别。
+        """
+        def same(br, a, akv, b, bkv):
+            return (br["bus1_name"].strip().upper() == a.strip().upper()
+                    and abs(br["kv1"] - akv) < 0.005
+                    and br["bus2_name"].strip().upper() == b.strip().upper()
+                    and abs(br["kv2"] - bkv) < 0.005
+                    and (ckt is None or br["ckt"] == ckt)
+                    and (section is None
+                         or int(br.get("section", 0)) == int(section)))
+
+        active = next((br for br in self.branches(input_only=True)
+                       if same(br, bus1, kv1, bus2, kv2)
+                       or same(br, bus2, kv2, bus1, kv1)), None)
+        snap = None
+        for candidate in self._branch_snapshots.values():
+            if (same(candidate, bus1, kv1, bus2, kv2)
+                    or same(candidate, bus2, kv2, bus1, kv1)):
+                snap = candidate
+                break
+        if active is not None:
+            return {"in_service": True, "branch": active,
+                    "status": "IN", "restorable": snap is not None}
+        if snap is not None:
+            out = dict(snap)
+            out.update({"in_service": False, "status": "OUT",
+                        "solution_available": False})
+            out.update(_branch_loading(out))
+            return {"in_service": False, "branch": out,
+                    "status": "OUT", "restorable": True}
+        return {"in_service": False, "branch": None,
+                "status": "UNKNOWN", "restorable": False}
+
+    def set_branch_status(self, bus1, kv1, bus2, kv2, ckt=None,
+                          in_service=True, section=None):
+        """幂等设置线路投切状态，并返回设置后的状态。"""
+        state = self.get_branch_status(bus1, kv1, bus2, kv2, ckt,
+                                       section=section)
+        wanted = bool(in_service)
+        if state["in_service"] == wanted:
+            state.update({"changed": False, "result": None})
+            return state
+        if wanted:
+            result = self.restore_branch(bus1, kv1, bus2, kv2, ckt=ckt,
+                                         section=section)
+        else:
+            result = self.outage_branch(bus1, kv1, bus2, kv2, ckt=ckt,
+                                        section=section)
+        state = self.get_branch_status(bus1, kv1, bus2, kv2, ckt,
+                                       section=section)
+        state.update({"changed": True, "result": result})
+        if state["in_service"] != wanted:
+            raise PyFlowError("支路状态设置后读回不一致")
+        return state
+
+    def delete_bus(self, name, kv):
+        """删除母线并提交（相连支路随之删除）。"""
+        return self._one_shot("delete_bus", name, kv)
+
+    def outage_branch(self, bus1, kv1, bus2, kv2, ckt=None,
+                      section=None):
+        """支路开断并提交（需参数供恢复时使用）。"""
+        return self._one_shot("outage_branch", bus1, kv1, bus2, kv2,
+                              ckt=ckt, section=section)
+
+    def restore_branch(self, bus1, kv1, bus2, kv2, ckt=None,
+                       section=None, **fields):
+        """恢复此前开断的支路并提交（参数取自开断快照）。"""
+        return self._one_shot("restore_branch", bus1, kv1, bus2, kv2,
+                              ckt=ckt, section=section, **fields)
+
+    def change_tap(self, bus1, kv1, bus2, kv2, ckt=None, tap1=None,
+                   tap2=None):
+        """修改变压器变比并提交。"""
+        return self._one_shot("change_tap", bus1, kv1, bus2, kv2, ckt=ckt,
+                              tap1=tap1, tap2=tap2)
+
+    def change_branch(self, bus1, kv1, bus2, kv2, ckt=None, **fields):
+        """通用支路参数修改并提交（字段见 cards.branch_card）。"""
+        return self._one_shot("change_branch", bus1, kv1, bus2, kv2,
+                              ckt=ckt, **fields)
+
+    def add_branch(self, bus1, kv1, bus2, kv2, ckt="1", **fields):
+        """新增支路并提交。"""
+        return self._one_shot("add_branch", bus1, kv1, bus2, kv2, ckt=ckt,
+                              **fields)
+
+    def scale_load(self, pct=1.0, zone=None, owner=None, area=None):
+        """按分区/所有者/全网缩放负荷并提交（pct=1.1 即 +10%）。"""
+        return self._one_shot("scale_load", pct=pct, zone=zone,
+                              owner=owner, area=area)
+
+    def scale_gen(self, pct=1.0, zone=None, owner=None):
+        """按分区/所有者缩放出力并提交。"""
+        return self._one_shot("scale_gen", pct=pct, zone=zone,
+                              owner=owner)
+
+    # ------------------------------------------------------------------
+    # ctypes 原型
+    # ------------------------------------------------------------------
+    def _setup_prototypes(self):
+        L = self._lib
+
+        # 基础 pf_* API（libcflow 直调层）
+        L.pf_init.argtypes = []
+        L.pf_init.restype = c_int
+        L.pf_solution.argtypes = []
+        L.pf_solution.restype = c_int
+        L.pf_load_oldbase.argtypes = [c_char_p]
+        L.pf_load_oldbase.restype = c_int
+        L.pf_load_netdata.argtypes = [c_char_p]
+        L.pf_load_netdata.restype = c_int
+        L.pf_load_changes.argtypes = [c_char_p]
+        L.pf_load_changes.restype = c_int
+        L.pf_load_refbase.argtypes = [c_char_p]
+        L.pf_load_refbase.restype = c_int
+        L.pf_save_newbase.argtypes = [c_char_p]
+        L.pf_save_newbase.restype = c_int
+        L.pf_save_changes.argtypes = [c_char_p]
+        L.pf_save_changes.restype = c_int
+        L.pf_put_inrec.argtypes = [c_char_p]
+        L.pf_put_inrec.restype = c_int
+        L.pf_command.argtypes = [c_char_p]
+        L.pf_command.restype = c_int
+        L.pf_select_base.argtypes = [c_char]
+        L.pf_select_base.restype = c_int
+        L.pf_solve_area.argtypes = [c_char]
+        L.pf_solve_area.restype = c_int
+        L.pf_bus_exists.argtypes = [c_char_p, c_float]
+        L.pf_bus_exists.restype = c_int
+        L.pf_get_list.argtypes = [c_char_p, c_int, c_int, c_char_p]
+        L.pf_get_list.restype = c_int
+        L.pf_area_of_zone.argtypes = [c_char_p, c_char_p]
+        L.pf_area_of_zone.restype = c_int
+        L.pf_rename_bus.argtypes = [c_char_p, c_float, c_char_p, c_float]
+        L.pf_rename_bus.restype = c_int
+        L.pf_rename_area.argtypes = [c_char_p, c_char_p]
+        L.pf_rename_area.restype = c_int
+        L.pf_rename_zone.argtypes = [c_char_p, c_char_p]
+        L.pf_rename_zone.restype = c_int
+        L.pf_del_area.argtypes = [c_char_p]
+        L.pf_del_area.restype = c_int
+        L.pf_del_zone.argtypes = [c_char_p]
+        L.pf_del_zone.restype = c_int
+        L.pf_save_netdata.argtypes = [c_char_p, c_char_p, c_char_p, c_int]
+        L.pf_save_netdata.restype = c_int
+        L.pf_save_wscc_stab_data.argtypes = [c_char_p, c_char_p]
+        L.pf_save_wscc_stab_data.restype = c_int
+        # 工具箱直调（ipfpy_tools.c：puf / ipfcut 的替代入口）。
+        L.bpaflow_puf.argtypes = [c_int, ctypes.POINTER(c_char_p)]
+        L.bpaflow_puf.restype = c_int
+        L.bpaflow_ipfcut.argtypes = [c_char_p, c_char_p, c_char_p]
+        L.bpaflow_ipfcut.restype = c_int
+        # 收尾：只调 pflend_（打印运行时间并关闭引擎打开的文件单元）。
+        # 不可调 ipf_fexit_cw —— 其内部 call exit 会终止宿主 Python 进程。
+        L.pflend_.argtypes = []
+        L.pflend_.restype = None
+
+        # ---- 内部数据访问（ipfpy_api.c）----
+        L.ipfpy_y_info.argtypes = [ctypes.POINTER(c_int)] * 3
+        L.ipfpy_y_info.restype = None
+        L.ipfpy_y_data.argtypes = [
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_double), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_double), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int)]
+        L.ipfpy_y_data.restype = None
+        L.ipfpy_mismatch.argtypes = (
+            [ctypes.POINTER(c_double)] * 5 +
+            [ctypes.POINTER(c_int)] * 10)
+        L.ipfpy_mismatch.restype = None
+        L.ipfpy_errbus.argtypes = [
+            ctypes.POINTER(c_float), ctypes.POINTER(c_int)]
+        L.ipfpy_errbus.restype = None
+        L.ipfpy_jac_data.argtypes = [
+            ctypes.POINTER(c_int), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_double), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int)]
+        L.ipfpy_jac_data.restype = None
+        L.ipfpy_voltage.argtypes = [
+            ctypes.POINTER(c_double), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_float), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int)]
+        L.ipfpy_voltage.restype = None
+        L.ipfpy_busnames.argtypes = [
+            ctypes.POINTER(c_int),
+            ctypes.POINTER(c_char), ctypes.POINTER(c_char),
+            ctypes.POINTER(c_char)]
+        L.ipfpy_busnames.restype = None
+        L.ipfpy_get_ltc.argtypes = [
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_char), ctypes.POINTER(c_char),
+            ctypes.POINTER(c_float), ctypes.POINTER(c_float),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_float), ctypes.POINTER(c_float),
+            ctypes.POINTER(c_float), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int)]
+        L.ipfpy_get_ltc.restype = None
+        L.ipfpy_mismatch_bus.argtypes = [
+            ctypes.POINTER(c_int), ctypes.POINTER(c_char),
+            ctypes.POINTER(c_double), ctypes.POINTER(c_double),
+            ctypes.POINTER(c_float)]
+        L.ipfpy_mismatch_bus.restype = None
+        L.ipfpy_step_state.argtypes = [
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int)]
+        L.ipfpy_step_state.restype = None
+        L.ipfpy_step_reset.argtypes = []
+        L.ipfpy_step_reset.restype = None
+        L.ipfpy_iteration_info.argtypes = (
+            [ctypes.POINTER(c_int)] * 7 + [ctypes.POINTER(c_float)])
+        L.ipfpy_iteration_info.restype = None
+        L.ipfpy_iteration_bus.argtypes = (
+            [ctypes.POINTER(c_int)] + [ctypes.POINTER(c_double)] * 6
+            + [ctypes.POINTER(c_int)] * 3)
+        L.ipfpy_iteration_bus.restype = None
+        L.ipfpy_iteration_jac.argtypes = (
+            [ctypes.POINTER(c_int)] * 4
+            + [ctypes.POINTER(c_double)] * 6)
+        L.ipfpy_iteration_jac.restype = None
+        L.ipfpy_case_info.argtypes = [
+            ctypes.POINTER(c_float),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_char)]
+        L.ipfpy_case_info.restype = None
+        L.ipfpy_case_info_ext.argtypes = [
+            ctypes.POINTER(c_float), ctypes.POINTER(c_int),
+            ctypes.POINTER(c_char)]
+        L.ipfpy_case_info_ext.restype = None
+        L.ipfpy_get_buses.argtypes = [
+            c_void_p, c_void_p, c_void_p, c_void_p, c_void_p, c_int]
+        L.ipfpy_get_buses.restype = c_int
+        L.ipfpy_get_branches.argtypes = [
+            c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+            c_void_p, c_void_p, c_int]
+        L.ipfpy_get_branches.restype = c_int
+        L.ipfpy_get_branches_input.argtypes = [
+            c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+            c_void_p, c_void_p, c_int]
+        L.ipfpy_get_branches_input.restype = c_int
+        L.ipfpy_get_areas.argtypes = [
+            c_void_p, c_void_p, c_void_p, c_int]
+        L.ipfpy_get_areas.restype = c_int
+
+        # ---- 扩展导出（新 DLL 才提供；旧 DLL 下方法自动回退）----
+        if hasattr(L, "ipfpy_get_branches_ext"):
+            L.ipfpy_get_branches_ext.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+                c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+                c_int, c_int]
+            L.ipfpy_get_branches_ext.restype = c_int
+        if hasattr(L, "ipfpy_get_ltc_ext"):
+            L.ipfpy_get_ltc_ext.argtypes = [
+                ctypes.POINTER(c_int), ctypes.POINTER(c_int),
+                ctypes.POINTER(c_char), ctypes.POINTER(c_char),
+                ctypes.POINTER(c_float), ctypes.POINTER(c_float),
+                ctypes.POINTER(c_int), ctypes.POINTER(c_double),
+                ctypes.POINTER(c_float), ctypes.POINTER(c_float),
+                ctypes.POINTER(c_float), ctypes.POINTER(c_int),
+                ctypes.POINTER(c_int), ctypes.POINTER(c_double),
+                ctypes.POINTER(c_double), ctypes.POINTER(c_int),
+                ctypes.POINTER(c_int)]
+            L.ipfpy_get_ltc_ext.restype = None
+        if hasattr(L, "ipfpy_get_ities"):
+            L.ipfpy_get_ities.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p, c_int]
+            L.ipfpy_get_ities.restype = c_int
+        if hasattr(L, "ipfpy_get_cbuses"):
+            L.ipfpy_get_cbuses.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+                c_void_p, c_int]
+            L.ipfpy_get_cbuses.restype = c_int
+        if hasattr(L, "ipfpy_get_qcurves"):
+            L.ipfpy_get_qcurves.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+                c_void_p, c_int]
+            L.ipfpy_get_qcurves.restype = c_int
+        if hasattr(L, "ipfpy_get_xdata"):
+            L.ipfpy_get_xdata.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p, c_void_p,
+                c_void_p, c_void_p, c_int]
+            L.ipfpy_get_xdata.restype = c_int
+        if hasattr(L, "ipfpy_get_comments"):
+            L.ipfpy_get_comments.argtypes = [
+                c_void_p, c_void_p, c_void_p, c_void_p]
+            L.ipfpy_get_comments.restype = c_int
+
+    # ------------------------------------------------------------------
+    # 基础 pf_* API
+    # ------------------------------------------------------------------
+    def init(self):
+        """初始化直调引擎。
+
+        先调 cflow_pf_init()（initlz+pfinit：设置逻辑单元号、打开单元 13
+        临时输入文件等），再发 /initialize 命令（等价 pf_init）。
+        """
+        if self._closed:
+            raise PyFlowError("BPAFlow 实例已关闭；请创建新实例")
+        if self._initialized:
+            return 0
+        if not hasattr(self._lib, "ipfpy_set_embedded"):
+            raise PyFlowError(
+                "libipfpy 过旧，缺少 ipfpy_set_embedded；请重建 libipfpy "
+                "或设置 BPAFLOW_DLL 指向当前构建")
+        self._lib.ipfpy_set_embedded.argtypes = [ctypes.POINTER(c_int)]
+        self._lib.ipfpy_set_embedded.restype = None
+        embedded_flag = c_int(1)
+        self._lib.ipfpy_set_embedded(byref(embedded_flag))
+        self._lib.cflow_pf_init.argtypes = []
+        self._lib.cflow_pf_init.restype = None
+        self._lib.cflow_pf_init()
+        self._initialized = True
+        return self._lib.pf_init()
+
+    def close(self):
+        """收尾：打印运行时间并关闭引擎打开的文件单元（等价 pflend）。
+
+        注意不可调 ipf_fexit_cw（其内部 call exit 会终止宿主 Python
+        进程）。不调用 close() 也无妨 —— 进程退出时由 OS 回收。
+        """
+        if self._closed:
+            return
+        if self._initialized:
+            self._lib.pflend_()
+        self._invalidate_cache()
+        self.drop_snapshot()
+        self._closed = True
+        if self._audit is not None and self._audit_owned:
+            try:
+                self._audit.close()
+            except (OSError, ValueError):
+                pass
+
+    exit = close
+
+    def __enter__(self):
+        if not self._initialized:
+            self.init()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
+    def _ensure_mutation_allowed(self):
+        """防止在线性化点与网络模型之间制造不一致。"""
+        if self._solution_session == "ITERATING":
+            raise PyFlowError(
+                "单步潮流会话正在迭代；修改网络前请先调用 "
+                "abort_solution()，修改后再 start_solution()")
+
+    def configure_solution(self, decoupled=None, newton=None, optim=None,
+                           flat_start=None):
+        """设置并记录潮流计算参数，返回当前 API 配置快照。"""
+        if any(v is not None for v in (decoupled, newton, optim)):
+            rc = self.set_solution_iterations(decoupled=decoupled,
+                                              newton=newton, optim=optim)
+            if rc != 0:
+                raise PyFlowError("设置潮流迭代次数失败，rc=%s" % rc)
+        if flat_start is not None:
+            rc = self.set_misc_controls(vflatstart=bool(flat_start))
+            if rc != 0:
+                raise PyFlowError("设置平启动参数失败，rc=%s" % rc)
+        return self.get_solution_config()
+
+    def get_solution_config(self):
+        """返回本实例经公共 API 设置的有效潮流参数。"""
+        return dict(self._solution_config)
+
+    def start_solution(self, max_iterations=None, flat_start=None):
+        """启动严格 Newton 单步会话，但不执行迭代。
+
+        单步模式强制跳过解耦法和最优乘子预迭代，保证每次
+        step_solution() 只推进一次 Newton 线性化/回代/更新。
+        """
+        if max_iterations is None:
+            max_iterations = self._solution_config.get("newton") or 30
+        if int(max_iterations) <= 0:
+            raise ValueError("max_iterations 必须为正整数")
+        self._lib.ipfpy_step_reset()
+        self.configure_solution(decoupled=0, newton=int(max_iterations),
+                                optim=0, flat_start=flat_start)
+        self._solution_session = "READY"
+        return self.solution_status()
+
+    def solution_status(self):
+        """返回单步会话状态：IDLE/READY/ITERATING/CONVERGED/FAILED。"""
+        active, iteration, engine_state = c_int(), c_int(), c_int()
+        self._lib.ipfpy_step_state(byref(active), byref(iteration),
+                                   byref(engine_state))
+        return {
+            "status": self._solution_session,
+            "iteration": iteration.value,
+            "engine_active": bool(active.value),
+            "engine_state": engine_state.value,
+            "converged": self._solution_session == "CONVERGED",
+        }
+
+    def abort_solution(self):
+        """终止并清空当前单步会话；网络状态保留在当前迭代点。"""
+        self._lib.ipfpy_step_reset()
+        self._solution_session = "IDLE"
+        return self.solution_status()
+
+    reset_solution = abort_solution
+
+    def solution(self):
+        """完整求解当前案例（直接调用 pf_solution）。"""
+        self._lib.ipfpy_step_reset()
+        self._solution_session = "IDLE"
+        rc = self._lib.pf_solution()
+        self._invalidate_cache()
+        self._solution_session = "CONVERGED" if rc == 0 else "FAILED"
+        return rc
+
+    def step_solution(self):
+        """执行单步潮流迭代。
+
+        每次调用执行一次 NR 迭代，保留中间电压/偏差状态，
+        可在迭代间通过 voltages()/mismatch()/iteration_history()
+        读取中间结果。
+
+        首次调用会完成 Y 矩阵与状态初始化并执行第 1 次 NR 迭代；
+        后续调用从保留的中间状态继续执行恰好一次迭代。
+
+        Returns
+        -------
+        dict
+            ``status`` 为 ``in_progress``、``converged`` 或 ``failed``，
+            同时返回 ``rc``、``iteration``、``mismatch`` 和
+            ``voltage_summary``。
+        """
+        if self._solution_session in ("IDLE", "CONVERGED", "FAILED"):
+            self.start_solution()
+        self.command("/ STEP_SOLUTION = 1")
+        rc = self._lib.pf_solution()
+        self._invalidate_cache()
+        active, iteration, state = c_int(), c_int(), c_int()
+        self._lib.ipfpy_step_state(byref(active), byref(iteration),
+                                   byref(state))
+        if active.value:
+            status = "in_progress"
+            self._solution_session = "ITERATING"
+        elif state.value == 1:
+            status = "converged"
+            self._solution_session = "CONVERGED"
+        else:
+            status = "failed"
+            self._solution_session = "FAILED"
+        r = {"rc": rc, "status": status,
+             "converged": status == "converged",
+             "iteration": iteration.value,
+             "mismatch": self.mismatch()}
+        v = self.voltages()
+        if v["nbus"] > 0:
+            vm = [(v["e"][i] ** 2 + v["f"][i] ** 2) ** 0.5 * v["base"][i]
+                  for i in range(v["nbus"])]
+            r["voltage_summary"] = {
+                "vmin_kv": min(vm), "vmax_kv": max(vm),
+                "vmin_bus": v["names"][vm.index(min(vm))].strip(),
+                "vmax_bus": v["names"][vm.index(max(vm))].strip(),
+            }
+        return r
+
+    def solution_step(self):
+        """step_solution() 的向后兼容别名。"""
+        return self.step_solution()
+
+    def load_oldbase(self, filename):
+        """加载潮流数据文件（BSE/DAT，等价 pf_load_oldbase）。"""
+        self.abort_solution()
+        self._branch_snapshots.clear()
+        self._invalidate_cache()
+        return self._lib.pf_load_oldbase(_ascii(filename))
+
+    def load_netdata(self, filename):
+        self.abort_solution()
+        self._branch_snapshots.clear()
+        self._invalidate_cache()
+        return self._lib.pf_load_netdata(_ascii(filename))
+
+    def load_changes(self, filename):
+        self._ensure_mutation_allowed()
+        self._invalidate_cache()
+        return self._lib.pf_load_changes(_ascii(filename))
+
+    def load_refbase(self, filename):
+        self._invalidate_cache()
+        return self._lib.pf_load_refbase(_ascii(filename))
+
+    def save_newbase(self, filename):
+        return self._lib.pf_save_newbase(_ascii(filename))
+
+    def save_changes(self, filename):
+        return self._lib.pf_save_changes(_ascii(filename))
+
+    def put_inrec(self, record):
+        self._ensure_mutation_allowed()
+        self._invalidate_cache()
+        return self._lib.pf_put_inrec(_ascii(record))
+
+    def command(self, command):
+        self._invalidate_cache()
+        return self._lib.pf_command(_ascii(command))
+
+    def run_command_file(self, pcl_file):
+        """执行 PCL 命令文件，等价原 ipfbat 批处理入口。
+
+        经 /COMMAND 通道由引擎解析执行：文件中的 PCL 命令按顺序送入
+        srv_cmdprs，支持嵌套命令文件；任一命令返回非零即中止并返回该状态。
+        取代已移除的 ipfbat 独立程序。
+
+        Parameters
+        ----------
+        pcl_file : str
+            PCL 命令文件路径（相对路径按当前工作目录解析）。
+
+        Returns
+        -------
+        int
+            0 成功，非零为失败命令的状态码。
+        """
+        return self.command("/COMMAND, FILE=%s" % pcl_file)
+
+    # ------------------------------------------------------------------
+    # .pfc 批处理文件解析与执行
+    def load_pfc(self, pfc_path):
+        """加载并执行 .pfc 批处理控制文件中的控制命令。
+
+        解析 .pfc 文件中的控制命令（/ 和 . 开头行），按顺序通过
+        pf_command() 发送给引擎。数据卡（B/L/T/E/R/P 等）会被跳过，
+        因为它们由 / NEW_BASE 或 / OLD_BASE 引用的 BSE 文件提供。
+
+        注意: 不处理内联数据卡（B/L/T/E/R 等），仅处理控制命令。
+
+        Parameters
+        ----------
+        pfc_path : str
+            .pfc 文件路径
+
+        Returns
+        -------
+        int
+            0 成功，非零失败
+        """
+        pfc_dir = os.path.dirname(os.path.abspath(pfc_path))
+        with open(pfc_path, encoding="ascii", errors="replace") as f:
+            raw = f.read()
+
+        # 预处理：移除续行符（行尾反斜杠，后接可选空格），保留换行
+        import re
+        raw = re.sub(r'\\(\s*[\r\n]+)', r'\1', raw)
+        lines = raw.splitlines()
+
+        # 执行所有控制命令（/ 和 . 开头）
+        for raw_line in lines:
+            stripped = raw_line.strip()
+            if not stripped or stripped.startswith("C") or stripped.startswith("("):
+                continue
+            if not (stripped.startswith("/") or stripped.startswith(".")):
+                continue  # 跳过数据卡
+
+            upper = stripped.upper()
+            # 处理 NEW_BASE/OLD_BASE 命令
+            if upper.startswith("/ NEW_BASE") or upper.startswith("/NEW_BASE"):
+                fname = _pfc_filename(stripped)
+                if fname:
+                    # 尝试相对路径
+                    fpath = fname if os.path.isabs(fname) else \
+                        os.path.join(pfc_dir, fname)
+                    rc = self.load_oldbase(fpath)
+                    if rc != 0:
+                        # 尝试原始文件名（可能全大写）
+                        import glob
+                        dir_files = os.listdir(pfc_dir)
+                        match = [f for f in dir_files if
+                                 f.upper() == fname.upper()]
+                        if match:
+                            rc = self.load_oldbase(
+                                os.path.join(pfc_dir, match[0]))
+                            if rc != 0:
+                                return rc
+                        else:
+                            return rc
+                continue
+            if upper.startswith("/ OLD_BASE") or upper.startswith("/OLD_BASE"):
+                fname = _pfc_filename(stripped)
+                if fname:
+                    fpath = fname if os.path.isabs(fname) else \
+                        os.path.join(pfc_dir, fname)
+                    rc = self.load_oldbase(fpath)
+                    if rc != 0:
+                        return rc
+                continue
+            # 跳过 NETWORK_DATA（内联数据由 BSE 文件提供）
+            if upper.startswith("/ NETWORK_DATA") or upper.startswith("/NETWORK_DATA"):
+                continue
+
+            # 其他控制命令直接发送
+            rc = self.command(stripped)
+            if rc != 0:
+                return rc
+
+        return 0
+
+    @staticmethod
+    def parse_pfc(pfc_path):
+        """解析 .pfc 批处理控制文件，返回结构化命令列表。
+
+        返回每条控制命令的类别、原始文本和解析后的参数，不执行任何操作。
+
+        Parameters
+        ----------
+        pfc_path : str
+            .pfc 文件路径
+
+        Returns
+        -------
+        dict
+            {"header": {...}, "controls": [{...}, ...], "data_cards": int}
+        """
+        import re
+        with open(pfc_path, encoding="ascii", errors="replace") as f:
+            raw = f.read()
+        raw = re.sub(r'\\(\s*[\r\n]+)', r'\1', raw)
+        lines = raw.splitlines()
+
+        result = {"header": {}, "controls": [], "data_cards": 0}
+
+        for raw_line in lines:
+            stripped = raw_line.strip()
+            if not stripped or stripped.startswith("C"):
+                continue
+
+            # 头部: (POWERFLOW, ...)
+            if stripped.startswith("("):
+                m = re.match(r'\(\s*POWERFLOW\s*,?\s*(.*?)\)', stripped,
+                             re.IGNORECASE)
+                if m:
+                    params = m.group(1)
+                    for kv in re.finditer(r'(\w+)\s*=\s*([^,]+)', params):
+                        result["header"][kv.group(1).upper()] = \
+                            kv.group(2).strip()
+                continue
+
+            # 控制命令: / 或 . 开头
+            if stripped.startswith("/") or stripped.startswith("."):
+                upper = stripped.upper()
+                entry = {"raw": stripped, "type": "unknown", "params": {}}
+
+                if upper.startswith("./ P_INPUTLIST"):
+                    entry["type"] = "INPUT_LIST"
+                    m = re.search(r'FULL|NONE|ZONES', upper)
+                    entry["params"]["mode"] = m.group(0) if m else "FULL"
+                elif upper.startswith("./ P_OUTPUTLIST"):
+                    entry["type"] = "OUTPUT_LIST"
+                    m = re.search(r'FULL|NONE|ZONES', upper)
+                    entry["params"]["mode"] = m.group(0) if m else "FULL"
+                elif upper.startswith("/ P_ANALYSIS_RPT"):
+                    entry["type"] = "ANALYSIS_RPT"
+                    m = re.search(r'LEVEL\s*=\s*(\d+)', upper)
+                    if m:
+                        entry["params"]["level"] = int(m.group(1))
+                elif (upper.startswith("/ NEW_BASE") or
+                      upper.startswith("/NEW_BASE") or
+                      upper.startswith("/ OLD_BASE") or
+                      upper.startswith("/OLD_BASE")):
+                    entry["type"] = "BASE"
+                    fname = _pfc_filename(stripped)
+                    if fname:
+                        entry["params"]["file"] = fname
+                elif upper.startswith("/ NETWORK_DATA"):
+                    entry["type"] = "NETWORK_DATA"
+                    m = re.search(r'FILE\s*=\s*(\S+)', stripped,
+                                  re.IGNORECASE)
+                    entry["params"]["file"] = m.group(1) if m else "*"
+                elif upper.startswith("/ MISC_CNTRL"):
+                    entry["type"] = "MISC_CNTRL"
+                    for kv in re.finditer(r'(\w+)\s*=\s*(\S+)', stripped):
+                        entry["params"][kv.group(1).upper()] = \
+                            kv.group(2).strip()
+                elif upper.startswith("/ LIMITS"):
+                    entry["type"] = "LIMITS"
+                    for kv in re.finditer(r'(\w+)\s*=\s*([\d.]+)', upper):
+                        entry["params"][kv.group(1).upper()] = \
+                            float(kv.group(2))
+                elif upper.startswith("/ SOL_ITER"):
+                    entry["type"] = "SOL_ITER"
+                    for kv in re.finditer(r'(\w+)\s*=\s*(\d+)', upper):
+                        entry["params"][kv.group(1).upper()] = \
+                            int(kv.group(2))
+                elif upper.startswith("/ TOLERANCE"):
+                    entry["type"] = "TOLERANCE"
+                    for kv in re.finditer(r'(\w+)\s*=\s*([\d.]+)', upper):
+                        entry["params"][kv.group(1).upper()] = \
+                            float(kv.group(2))
+                elif upper.startswith("/ LTC"):
+                    entry["type"] = "LTC"
+                    m = re.search(r'=\s*(\S+)', stripped)
+                    if m:
+                        entry["params"]["mode"] = m.group(1).strip()
+                elif upper.startswith("/ MVA_BASE"):
+                    entry["type"] = "MVA_BASE"
+                    m = re.search(r'=\s*([\d.]+)', stripped)
+                    if m:
+                        entry["params"]["mva"] = float(m.group(1))
+                elif upper.startswith("/ AI_LIST"):
+                    entry["type"] = "AI_LIST"
+                    m = re.search(r'=\s*(\S+)', stripped)
+                    if m:
+                        entry["params"]["mode"] = m.group(1).strip()
+                elif upper.startswith("/ OI_LIST"):
+                    entry["type"] = "OI_LIST"
+                    m = re.search(r'=\s*(\S+)', stripped)
+                    if m:
+                        entry["params"]["mode"] = m.group(1).strip()
+                elif upper.startswith("/ RPT_SORT"):
+                    entry["type"] = "RPT_SORT"
+                    m = re.search(r'=\s*(\S+)', stripped)
+                    if m:
+                        entry["params"]["mode"] = m.group(1).strip()
+                elif upper.startswith("/ EXTENDED_RATINGS"):
+                    entry["type"] = "EXTENDED_RATINGS"
+                    m = re.search(r'=\s*(\S+)', stripped)
+                    if m:
+                        entry["params"]["season"] = m.group(1).strip()
+
+                result["controls"].append(entry)
+                continue
+
+            # 数据卡
+            if stripped[0] in "BLTERPX":
+                result["data_cards"] += 1
+
+        return result
+
+    # ------------------------------------------------------------------
+    # 控制参数设置（等价于 .pfc 控制命令）
+    # ------------------------------------------------------------------
+    def set_limits(self, qres=None, pha=None, del_ang=None,
+                   del_volt=None):
+        """设置潮流限值（等价于 / LIMITS 命令）。
+
+        Parameters
+        ----------
+        qres : float, optional
+            Q 残差限值 (MVAr pu)
+        pha : float, optional
+            相角差限值 (度)
+        del_ang : float, optional
+            区域交换功率偏差限值 (MW)
+        del_volt : float, optional
+            电压偏差限值 (%)
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        cmd = "/ LIMITS"
+        parts = []
+        if qres is not None: parts.append(f"QRES={qres}")
+        if pha is not None: parts.append(f"PHA={pha}")
+        if del_ang is not None: parts.append(f"DEL_ANG={del_ang}")
+        if del_volt is not None: parts.append(f"DEL_VOLT={del_volt}")
+        if parts:
+            cmd += ", " + ", ".join(parts)
+        rc = self.command(cmd)
+        if rc == 0:
+            self._solution_config.setdefault("limits", {}).update(
+                {k: v for k, v in {
+                    "qres": qres, "pha": pha, "del_ang": del_ang,
+                    "del_volt": del_volt}.items() if v is not None})
+        return rc
+
+    def set_solution_iterations(self, decoupled=None, newton=None,
+                                 optim=None):
+        """设置最大迭代次数（等价于 / SOL_ITER 命令）。
+
+        Parameters
+        ----------
+        decoupled : int, optional
+            最大分解法迭代次数
+        newton : int, optional
+            最大牛顿法迭代次数
+        optim : int, optional
+            最优乘子法迭代次数
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        cmd = "/ SOL_ITER"
+        parts = []
+        if decoupled is not None: parts.append(f"DECOUPLED={decoupled}")
+        if newton is not None: parts.append(f"NEWTON={newton}")
+        if optim is not None: parts.append(f"OPTIM={optim}")
+        if parts:
+            cmd += ", " + ", ".join(parts)
+        rc = self.command(cmd)
+        if rc == 0:
+            for key, value in (("decoupled", decoupled),
+                               ("newton", newton), ("optim", optim)):
+                if value is not None:
+                    self._solution_config[key] = int(value)
+        return rc
+
+    def set_misc_controls(self, vflatstart=None, relaxfactor=None,
+                           xrghostnode=None, voltagerelax=None,
+                           savebe=None):
+        """设置杂项控制（等价于 / MISC_CNTRL 命令）。
+
+        Parameters
+        ----------
+        vflatstart : bool, optional
+            是否启用平启动
+        relaxfactor : float, optional
+            松弛因子
+        xrghostnode : bool, optional
+            是否启用 XRGHOST 节点
+        voltagerelax : bool, optional
+            是否启用电压松弛
+        savebe : bool, optional
+            是否保存 BE 文件
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        cmd = "/ MISC_CNTRL"
+        parts = []
+        onoff = lambda v: "ON" if v else "OFF"
+        if vflatstart is not None: parts.append(f"VFLATSTART={onoff(vflatstart)}")
+        if relaxfactor is not None: parts.append(f"RELAXfactor={relaxfactor}")
+        if xrghostnode is not None: parts.append(f"XRGHOSTnode={onoff(xrghostnode)}")
+        if voltagerelax is not None: parts.append(f"VOLTAGERelax={onoff(voltagerelax)}")
+        if savebe is not None: parts.append(f"SAVEBE={onoff(savebe)}")
+        if parts:
+            cmd += ", " + ", ".join(parts)
+        rc = self.command(cmd)
+        if rc == 0:
+            if vflatstart is not None:
+                self._solution_config["flat_start"] = bool(vflatstart)
+            self._solution_config.setdefault("misc", {}).update(
+                {k: v for k, v in {
+                    "relaxfactor": relaxfactor,
+                    "xrghostnode": xrghostnode,
+                    "voltagerelax": voltagerelax,
+                    "savebe": savebe}.items() if v is not None})
+        return rc
+
+    def set_tolerances(self, bus=None, area=None, tx=None, q=None,
+                        opcut=None):
+        """设置收敛容差（等价于 / TOLERANCE 命令）。
+
+        Parameters
+        ----------
+        bus : float, optional
+            母线电压容差 (pu)
+        area : float, optional
+            区域交换功率容差 (MW)
+        tx : float, optional
+            变压器容差 (pu)
+        q : float, optional
+            无功容差 (MVAr)
+        opcut : float, optional
+            最优乘子截止值
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        cmd = "/ TOLERANCE"
+        parts = []
+        if bus is not None: parts.append(f"BUS={bus}")
+        if area is not None: parts.append(f"AREA={area}")
+        if tx is not None: parts.append(f"TX={tx}")
+        if q is not None: parts.append(f"Q={q}")
+        if opcut is not None: parts.append(f"OPCUT={opcut}")
+        if parts:
+            cmd += ", " + ", ".join(parts)
+        rc = self.command(cmd)
+        if rc == 0:
+            self._solution_config.setdefault("tolerances", {}).update(
+                {k: v for k, v in {
+                    "bus": bus, "area": area, "tx": tx,
+                    "q": q, "opcut": opcut}.items() if v is not None})
+        return rc
+
+    def set_ltc_control(self, mode="ON"):
+        """设置 LTC 控制模式（等价于 / LTC 命令）。
+
+        Parameters
+        ----------
+        mode : str
+            控制模式: ON, OFF, ON_NV, ON_NPS
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        return self.command(f"/ LTC = {mode}")
+
+    def set_input_listing(self, mode="FULL"):
+        """设置输入列表（等价于 ./ P_INPUTLIST 命令）。
+
+        Parameters
+        ----------
+        mode : str
+            列表模式: FULL, NONE, ZONES=<z1,z2,...>
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        return self.command(f"./ P_INPUTLIST,{mode}")
+
+    def set_output_listing(self, mode="FULL"):
+        """设置输出列表（等价于 ./ P_OUTPUTLIST 命令）。
+
+        Parameters
+        ----------
+        mode : str
+            列表模式: FULL, NONE, ZONES=<z1,z2,...>
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        return self.command(f"./ P_OUTPUTLIST,{mode}")
+
+    def set_analysis_report(self, level=1, zones=None, owners=None):
+        """设置分析报表级别（等价于 / P_ANALYSIS_RPT 命令）。
+
+        Parameters
+        ----------
+        level : int
+            报表级别: 1-4（1=仅 UNSCH, 2=1-17 号报表,
+            3=1-18 号, 4=全部 23 号）
+        zones : str, optional
+            分区过滤
+        owners : str, optional
+            所有者过滤
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        cmd = f"/ P_ANALYSIS_RPT,LEVEL={level}"
+        if zones:
+            cmd += f", ZONES={zones}"
+        if owners:
+            cmd += f", OWNERS={owners}"
+        return self.command(cmd)
+
+    def set_mva_base(self, mva):
+        """设置系统 MVA 基准值（等价于 / MVA_BASE 命令）。
+
+        Parameters
+        ----------
+        mva : float
+            MVA 基准值
+
+        Returns
+        -------
+        int
+            引擎返回码
+        """
+        return self.command(f"/ MVA_BASE = {mva}")
+
+    def select_base(self, base):
+        value = _ascii(base)
+        if not isinstance(value, bytes) or len(value) != 1:
+            raise ValueError("base 必须是单字符 'O' 或 'R'")
+        self._invalidate_cache()
+        return self._lib.pf_select_base(value)
+
+    def solve_area(self, base):
+        value = _ascii(base)
+        if not isinstance(value, bytes) or len(value) != 1:
+            raise ValueError("base 必须是单字符 'O' 或 'R'")
+        return self._lib.pf_solve_area(value)
+
+    def bus_exists(self, name, kv):
+        return self._lib.pf_bus_exists(_ascii(name), c_float(kv))
+
+    def area_of_zone(self, area, zone):
+        return self._lib.pf_area_of_zone(_ascii(area), _ascii(zone))
+
+    # ------------------------------------------------------------------
+    # 修改类（/changes 记录）
+    # ------------------------------------------------------------------
+    def rename_bus(self, oldname, oldkv, newname, newkv):
+        """母线改名（ZB 变更记录）。"""
+        rc = self._lib.pf_rename_bus(_ascii(oldname), c_float(oldkv),
+                                     _ascii(newname), c_float(newkv))
+        self._invalidate_cache()
+        return rc
+
+    def rename_area(self, oldname, newname):
+        """控制区改名（ZA 变更记录）。"""
+        rc = self._lib.pf_rename_area(_ascii(oldname), _ascii(newname))
+        self._invalidate_cache()
+        return rc
+
+    def rename_zone(self, oldname, newname):
+        """分区改名（Z 变更记录）。"""
+        rc = self._lib.pf_rename_zone(_ascii(oldname), _ascii(newname))
+        self._invalidate_cache()
+        return rc
+
+    def del_area(self, area):
+        """按控制区删除（DA 变更记录）。
+
+        警告：该卡删除属于该控制区的**全部母线**（chread.f "DA" 语义），
+        而非仅删除区域定义；不存在的区域名返回非零状态。
+        """
+        rc = self._lib.pf_del_area(_ascii(area))
+        self._invalidate_cache()
+        return rc
+
+    def del_zone(self, zone):
+        """按分区删除（DZ 变更记录）。
+
+        警告：该卡删除属于该分区的**全部母线**（chread.f "DZ" 语义），
+        而非仅删除分区定义；不存在的分区名静默成功（0 条母线被删）。
+        """
+        rc = self._lib.pf_del_zone(_ascii(zone))
+        self._invalidate_cache()
+        return rc
+
+    def save_netdata(self, filename, dialect="BPA", ratings="EXTENDED",
+                     size=120):
+        """导出网络数据（/save_file, type=network_data）。
+
+        dialect: BPA / WSCC / WSCC1 / PTI；
+        ratings: EXTENDED / MINIMUM / NOMINAL；
+        size:    每行字符数 120 或 80。
+        """
+        return self._lib.pf_save_netdata(_ascii(filename), _ascii(dialect),
+                                         _ascii(ratings), c_int(size))
+
+    def save_wscc_stab_data(self, filename, type="ascii_stability"):
+        """导出 WSCC 稳定数据；type: ascii_stability / binary_stability。"""
+        return self._lib.pf_save_wscc_stab_data(_ascii(filename),
+                                                _ascii(type))
+
+    # ------------------------------------------------------------------
+    # 工具箱直调（原 puf / ipfcut 独立程序，已 API 化；报表走 /REPORTS 命令）
+    # ------------------------------------------------------------------
+    def puf(self, args):
+        """路径使用因子（PUF）分析，参数与命令行版 puf 相同。
+
+        args: 字符串列表，例如 ["-G", "base.bse", "out.txt", "brn.dat"]；
+        位置参数依次为 BASE 文件、输出文件、支路数据文件。
+        返回 0 成功；-1 表示参数个数非法。
+        """
+        argv_list = [_ascii(a) for a in args]
+        argc = len(argv_list)
+        argv = (c_char_p * argc)(*argv_list) if argc > 0 else None
+        rc = self._lib.bpaflow_puf(c_int(argc), argv)
+        self._invalidate_cache()
+        return rc
+
+    def ipfcut(self, out_file, base_file, cmd_file):
+        """电网切割：out_file=BUS/BRANCH 输出，base_file=基态，
+        cmd_file=CUT 命令文件。返回 0 成功，1=CUT 文件不存在，
+        2=BUS/BRANCH 打开失败，3=命令文件打开失败，4=基态加载失败。"""
+        rc = self._lib.bpaflow_ipfcut(_ascii(out_file), _ascii(base_file),
+                                      _ascii(cmd_file))
+        self._invalidate_cache()
+        return rc
+
+    def reports(self, out_file, selects):
+        """潮流报表：经 /REPORTS 命令生成报表文件。
+
+        selects: 报表名或列表，如 "BUS_INPUT"、["BUS_INPUT", "LINEFLOW"]。
+        语法要点：引擎要求 `select NAME` 空格分隔且不带 '='，带 '=' 会
+        落入通用回退分支；每条命令只处理第一个 select；引擎的 append
+        模式在 gfortran 下存在缺陷（open_apnd），因此多选时本方法自动
+        分文件生成再合并。返回引擎 rc（0 成功）。
+        """
+        if isinstance(selects, str):
+            selects = [selects]
+        targets = [out_file] if len(selects) == 1 else [
+            "%s.part%d" % (out_file, i) for i in range(len(selects))]
+        rc = 0
+        for tgt, sel in zip(targets, selects):
+            rc = self.command("/reports, overwrite = %s, select %s"
+                              % (tgt, sel))
+            if rc != 0:
+                break
+        if rc == 0 and len(targets) > 1:
+            with open(out_file, "wb") as out:
+                for tgt in targets:
+                    with open(tgt, "rb") as f:
+                        out.write(f.read())
+            for tgt in targets:
+                try:
+                    os.remove(tgt)
+                except OSError:
+                    pass
+        return rc
+
+    def get_list(self, list_type, maxlen=4096):
+        """按类型取列表（AREA/BUS/KV/OWNER/REC_TYPE/ZONE）。
+
+        pf_get_list 的 listlen 参数是"条目数"（每条定长），故缓冲区按
+        maxlen * 最大条目宽 16 字节分配，避免 C 侧越界写。
+        """
+        list_type = int(list_type)
+        maxlen = int(maxlen)
+        if list_type not in range(6):
+            raise ValueError("list_type 必须是 BPAFlow.*_LIST（0..5）")
+        if maxlen <= 0:
+            raise ValueError("maxlen 必须为正整数")
+        buf = create_string_buffer(maxlen * 16)
+        rc = self._lib.pf_get_list(buf, maxlen, list_type, b"")
+        if rc != 0:
+            raise PyFlowError("pf_get_list 失败, rc=%d" % rc)
+        parts = bytes(buf.raw).split(b"\x00")
+        return [p.decode("ascii", "replace") for p in parts if p]
+
+    # ------------------------------------------------------------------
+    # 算例概况
+    # ------------------------------------------------------------------
+    def case_info(self):
+        """返回算例概况字典（含完整 ``pf_case_stats`` 与求解状态）。
+
+        ``num_branches`` 是引擎的双向支路记录数；``num_circuits`` 是
+        物理回路统计口径（并行线路组按一个 circuit 计数）。
+        """
+        base_mva = c_float()
+        stats = (c_int * 20)()
+        ver = create_string_buffer(11)
+        self._lib.ipfpy_case_info_ext(byref(base_mva), stats, ver)
+        return {
+            "pf_version": _text(ver.raw),
+            "base_mva": base_mva.value,
+            "num_DC_systems": stats[0],
+            "num_areas": stats[1],
+            "num_ities": stats[2],
+            "num_interties": stats[2],
+            "num_zones": stats[3],
+            "num_owners": stats[4],
+            "num_buses": stats[5],
+            "num_area_slack_buses": stats[6],
+            "num_DC_buses": stats[7],
+            "num_AGC_buses": stats[8],
+            "num_BX_buses": stats[9],
+            "num_adjustable_buses": stats[10],
+            "num_pct_var_ctrl_buses": stats[11],
+            "num_branches": stats[12],
+            "num_circuits": stats[13],
+            "num_DC_lines": stats[14],
+            "num_LTC_xfmrs": stats[15],
+            "num_phase_shifters": stats[16],
+            "soln_status": stats[17],
+            "num_diff_kv": stats[18],
+            "num_rec_types": stats[19],
+        }
+
+    # ------------------------------------------------------------------
+    # 快照/回滚（P1，基于临时 .bse 文件）
+    # ------------------------------------------------------------------
+    def snapshot(self, tag=None):
+        """保存当前算例快照到临时文件。
+
+        tag 可选标识，用于 restore(tag=tag)。返回标识串（缺省为文件
+        路径）。快照文件在进程退出时由 tempdir 清理，也可显式调用
+        drop_snapshot(tag=tag)。
+
+        用法::
+            tag = pf.snapshot("before_N1")
+            # ... apply changes, solve ...
+            pf.restore(tag)
+        """
+        import tempfile
+        fd, path = tempfile.mkstemp(prefix="bpaflow_snap_", suffix=".bse")
+        os.close(fd)
+        rc = self.save_newbase(path)
+        if rc != 0:
+            # 引擎 /save_file 偶尔瞬态失败（如 PCL 命令排队中）；
+            # 重试一次
+            rc = self.save_newbase(path)
+        if rc != 0:
+            os.unlink(path)
+            raise PyFlowError("快照保存失败 rc=%d（path=%r）" % (rc, path))
+        tag = tag if tag is not None else path
+        old_path = self._snapshots.get(tag)
+        if old_path and old_path != path:
+            try:
+                os.unlink(old_path)
+            except OSError:
+                pass
+        self._snapshots[tag] = path
+        return tag
+
+    def restore(self, tag=None):
+        """恢复到快照状态（加载 .bse 临时文件，默认最近一个快照）。"""
+        if tag is None:
+            if not self._snapshots:
+                raise PyFlowError("无可用快照")
+            tag = list(self._snapshots.keys())[-1]
+        path = self._snapshots.get(tag)
+        if path is None:
+            raise PyFlowError("快照 %r 不存在" % tag)
+        rc = self.load_oldbase(path)
+        if rc != 0:
+            raise PyFlowError("快照恢复失败 rc=%d" % rc)
+        return rc
+
+    def drop_snapshot(self, tag=None):
+        """删除快照临时文件。不传 tag 则删除全部。"""
+        if tag is None:
+            for p in self._snapshots.values():
+                try:
+                    os.unlink(p)
+                except OSError:
+                    pass
+            self._snapshots.clear()
+        else:
+            path = self._snapshots.pop(tag, None)
+            if path:
+                try:
+                    os.unlink(path)
+                except OSError:
+                    pass
+
+    # ------------------------------------------------------------------
+    # 母线/支路/控制区（扁平数组导出，免 ctypes 复刻 pf_rec）
+    # ------------------------------------------------------------------
+    def _buses_all(self):
+        """无过滤的母线全量查询，带缓存与 refbase 扩容。"""
+        if "buses_all" in self._cache:
+            return self._cache["buses_all"]
+        ci = self.case_info()
+        n = int(ci.get("num_buses") or 0)
+        maxbus = max(n * 2, 64)
+        while True:
+            fields = (c_double * (maxbus * 15))()
+            names_arr = ((c_char * 9) * maxbus)()
+            types_arr = ((c_char * 3) * maxbus)()
+            zones_arr = ((c_char * 3) * maxbus)()
+            kvs = (c_float * maxbus)()
+            got = self._lib.ipfpy_get_buses(
+                ctypes.byref(fields), ctypes.byref(names_arr),
+                ctypes.byref(types_arr), ctypes.byref(zones_arr),
+                ctypes.byref(kvs), maxbus)
+            if got >= 0:
+                break
+            if maxbus >= MAXBUS * 2:
+                raise PyFlowError("ipfpy_get_buses 缓冲区不足")
+            maxbus = min(maxbus * 2, MAXBUS * 2)
+        out = []
+        f = fields
+        for i in range(got):
+            btype = _text(types_arr[i].raw)
+            out.append({
+                "name": _text(names_arr[i].raw),
+                "type": btype,
+                "bus_kind": "dc" if btype.strip().upper() in ("BD", "BM") else "ac",
+                "is_dc": btype.strip().upper() in ("BD", "BM"),
+                "zone": _text(zones_arr[i].raw),
+                "kv": kvs[i],
+                "Pgen": f[i * 15 + 0], "Qgen": f[i * 15 + 1],
+                "Vmag": f[i * 15 + 2], "Vdeg": f[i * 15 + 3],
+                "Pload": f[i * 15 + 4], "Qload": f[i * 15 + 5],
+                "Pshunt": f[i * 15 + 6], "Qshunt": f[i * 15 + 7],
+                "Qsch_Qmax": f[i * 15 + 8], "Qmin": f[i * 15 + 9],
+                "Vhold_Vmax": f[i * 15 + 10], "Vmin_Vdeg": f[i * 15 + 11],
+                "pct_vars": f[i * 15 + 12], "Qunsch": f[i * 15 + 13],
+                "Bshunt_used": f[i * 15 + 14],
+            })
+        self._cache["buses_all"] = out
+        return out
+
+    def buses(self, zone=None, kv=None, name=None, bus_names=None,
+              filter_zone=None):
+        """返回母线列表，每项含输入与求解字段（字典）。
+
+        字段包含 `bus_kind`/`is_dc`；DC 母线（BD/BM）不参与 AC 电压、
+        q_limited 和孤岛扫描。
+
+        可选过滤参数（Python 侧过滤）:
+          zone         分区码（2 字符，如 "30"）
+          kv           基准电压 kV
+          name         母线名
+          bus_names    母线名集合（set/list），匹配其一即返回
+          filter_zone  同 zone（别名）
+        """
+        zone = zone or filter_zone
+        out = self._buses_all()
+        if zone:
+            out = [b for b in out if b["zone"].strip() == zone]
+        if kv is not None:
+            out = [b for b in out if abs(b["kv"] - kv) < 0.005]
+        if name is not None:
+            nm = name.strip().upper()
+            out = [b for b in out if b["name"].strip().upper() == nm]
+        if bus_names is not None:
+            nms = set(n.strip().upper() for n in bus_names)
+            out = [b for b in out if b["name"].strip().upper() in nms]
+        return [dict(b) for b in out]
+
+    def bus(self, name, kv):
+        """返回单条母线（字典）或 None。
+
+        用法::
+            b = pf.bus("BUS1", 230.0)
+            if b is not None:
+                print(b["Vmag"], b["Pgen"])
+        """
+        for b in self.buses():
+            if (b["name"].strip().upper() == name.strip().upper()
+                    and abs(b["kv"] - kv) < 0.005):
+                return b
+        return None
+
+    def _branches_all(self, input_only=False):
+        """无过滤支路全量查询，带缓存和 refbase 扩容。"""
+        cache_key = "branches_input" if input_only else "branches_solved"
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+        ci = self.case_info()
+        n = int(ci.get("num_branches") or 0)
+        maxbr = max(n * 2 + 64, 64)
+        use_ext = hasattr(self._lib, "ipfpy_get_branches_ext")
+        while True:
+            if use_ext:
+                fields = (c_double * (maxbr * 29))()
+                names1_arr = ((c_char * 9) * maxbr)()
+                names2_arr = ((c_char * 9) * maxbr)()
+                types_arr = ((c_char * 3) * maxbr)()
+                ckts_arr = (c_char * maxbr)()
+                owners_arr = ((c_char * 4) * maxbr)()
+                kvs1 = (c_float * maxbr)()
+                kvs2 = (c_float * maxbr)()
+                sections_arr = (c_int * maxbr)()
+                codes_arr = (c_char * (maxbr * 2))()
+                got = self._lib.ipfpy_get_branches_ext(
+                    ctypes.byref(fields), ctypes.byref(names1_arr),
+                    ctypes.byref(names2_arr), ctypes.byref(types_arr),
+                    ctypes.byref(ckts_arr), ctypes.byref(owners_arr),
+                    ctypes.byref(kvs1), ctypes.byref(kvs2),
+                    ctypes.byref(sections_arr), ctypes.byref(codes_arr),
+                    maxbr, 0 if input_only else 1)
+            else:
+                fields = (c_double * (maxbr * 15))()
+                names1_arr = ((c_char * 9) * maxbr)()
+                names2_arr = ((c_char * 9) * maxbr)()
+                types_arr = ((c_char * 3) * maxbr)()
+                ckts_arr = (c_char * maxbr)()
+                kvs1 = (c_float * maxbr)()
+                kvs2 = (c_float * maxbr)()
+                getter = (self._lib.ipfpy_get_branches_input if input_only
+                          else self._lib.ipfpy_get_branches)
+                got = getter(
+                    ctypes.byref(fields), ctypes.byref(names1_arr),
+                    ctypes.byref(names2_arr), ctypes.byref(types_arr),
+                    ctypes.byref(ckts_arr), ctypes.byref(kvs1),
+                    ctypes.byref(kvs2), maxbr)
+            if got >= 0:
+                break
+            if maxbr >= MAXBUS * 8:
+                raise PyFlowError("ipfpy_get_branches 缓冲区不足")
+            maxbr = min(maxbr * 2, MAXBUS * 8)
+
+        out = []
+        for i in range(got):
+            if use_ext:
+                f = fields
+                base = i * 29
+                br = {
+                    "type": _text(types_arr[i].raw),
+                    "bus1_name": _text(names1_arr[i].raw),
+                    "bus2_name": _text(names2_arr[i].raw),
+                    "kv1": kvs1[i], "kv2": kvs2[i],
+                    "ckt": ckts_arr.raw[i:i + 1].decode("ascii", "replace"),
+                    "owner": _text(owners_arr[i].raw),
+                    "section": int(sections_arr[i]),
+                    "r": f[base + 0], "x": f[base + 1],
+                    "g": f[base + 2], "b": f[base + 3],
+                    "tap1": f[base + 4], "tap2": f[base + 5],
+                    "total_rating": f[base + 6],
+                    "num_ckts": int(f[base + 7]),
+                    "Pin": f[base + 8], "Qin": f[base + 9],
+                    "Pout": f[base + 10], "Qout": f[base + 11],
+                    "Ploss": f[base + 12], "Qloss": f[base + 13],
+                    "meter": int(f[base + 14]),
+                    "thermal_rating": f[base + 15],
+                    "bottleneck_rating": f[base + 16],
+                    "emergency_rating": f[base + 17],
+                    "crit_line_load_amps": f[base + 18],
+                    "crit_line_rat_amps": f[base + 19],
+                    "tot_line_load_pct": f[base + 20],
+                    "crit_line_load_term": int(f[base + 21]),
+                    "crit_xfmr_load_mva": f[base + 22],
+                    "crit_xfmr_rat_mva": f[base + 23],
+                    "tot_xfmr_load_pct": f[base + 24],
+                    "crit_xfmr_load_term": int(f[base + 25]),
+                    "tot_line_load_amps": f[base + 26],
+                    "tot_xfmr_load_mva": f[base + 27],
+                    "solution_available": bool(f[base + 28]) and not input_only,
+                    "crit_line_rat_code": (
+                        codes_arr.raw[i * 2:i * 2 + 1].decode(
+                            "ascii", "replace").strip() or "N"),
+                    "crit_xfmr_rat_code": (
+                        codes_arr.raw[i * 2 + 1:i * 2 + 2].decode(
+                            "ascii", "replace").strip() or "N"),
+                }
+            else:
+                f = fields
+                base = i * 15
+                br = {
+                    "type": _text(types_arr[i].raw),
+                    "bus1_name": _text(names1_arr[i].raw),
+                    "bus2_name": _text(names2_arr[i].raw),
+                    "kv1": kvs1[i], "kv2": kvs2[i],
+                    "ckt": ckts_arr.raw[i:i + 1].decode("ascii", "replace"),
+                    "owner": "", "section": 0,
+                    "r": f[base + 0], "x": f[base + 1],
+                    "g": f[base + 2], "b": f[base + 3],
+                    "tap1": f[base + 4], "tap2": f[base + 5],
+                    "total_rating": f[base + 6],
+                    "num_ckts": int(f[base + 7]),
+                    "Pin": f[base + 8], "Qin": f[base + 9],
+                    "Pout": f[base + 10], "Qout": f[base + 11],
+                    "Ploss": f[base + 12], "Qloss": f[base + 13],
+                    "meter": int(f[base + 14]),
+                    "thermal_rating": 0.0, "bottleneck_rating": 0.0,
+                    "emergency_rating": 0.0,
+                    "crit_line_load_amps": 0.0,
+                    "crit_line_rat_amps": 0.0,
+                    "tot_line_load_pct": 0.0, "crit_line_load_term": 0,
+                    "crit_xfmr_load_mva": 0.0,
+                    "crit_xfmr_rat_mva": 0.0,
+                    "tot_xfmr_load_pct": 0.0, "crit_xfmr_load_term": 0,
+                    "tot_line_load_amps": 0.0, "tot_xfmr_load_mva": 0.0,
+                    "solution_available": not input_only,
+                    "crit_line_rat_code": "N",
+                    "crit_xfmr_rat_code": "N",
+                }
+            br.update(_branch_loading(br))
+            br["branch_kind"] = _branch_kind(br["type"])
+            if br["branch_kind"] not in ("line", "transformer"):
+                br["solution_available"] = False
+                for key in ("Pin", "Qin", "Pout", "Qout",
+                            "Ploss", "Qloss"):
+                    br[key] = 0.0
+            out.append(br)
+        self._cache[cache_key] = out
+        return out
+
+    def branches(self, brtype=None, kv=None, bus1=None, bus2=None,
+                 input_only=False, include_outaged=False):
+        """返回支路列表，每项含输入、求解和负载率字段。
+
+        新增 owner/section/thermal_rating/bottleneck_rating/
+        emergency_rating、crit_line_*/crit_xfmr_*/tot_* 负载率字段，
+        以及 loading_ratio/loading_pct/loading_kind/rating_used/
+        rating_code/s_mva/i_amps/in_service/status。
+
+        input_only=True 时不读取求解量。include_outaged=True 时把本实例
+        通过 outage_branch 开断、尚未恢复的支路以 in_service=False
+        追加入结果；基础算例中已经停运、从未出现在内核支路表中的支路
+        无法由该接口还原。
+        """
+        out = [dict(b) for b in self._branches_all(input_only)]
+        for b in out:
+            b["in_service"] = True
+            b["status"] = "IN"
+        if include_outaged and not input_only:
+            active_keys = set(_branch_dedup_key(b) for b in out)
+            for snap in self._branch_snapshots.values():
+                if _branch_dedup_key(snap) in active_keys:
+                    continue
+                b = dict(snap)
+                b.update({"in_service": False, "status": "OUT",
+                          "solution_available": False})
+                b.update(_branch_loading(b))
+                out.append(b)
+        if brtype is not None:
+            bt = brtype.strip().upper()
+            out = [b for b in out if b["type"].strip().upper() == bt]
+        if kv is not None:
+            out = [b for b in out if abs(b["kv1"] - kv) < 0.005
+                   or abs(b["kv2"] - kv) < 0.005]
+        if bus1 is not None:
+            b1 = bus1.strip().upper()
+            out = [b for b in out if b["bus1_name"].strip().upper() == b1]
+        if bus2 is not None:
+            b2 = bus2.strip().upper()
+            out = [b for b in out if b["bus2_name"].strip().upper() == b2]
+        return out
+
+    def branch(self, bus1, kv1, bus2, kv2, ckt=None, section=None,
+               include_outaged=False):
+        """返回单条支路（字典）或 None。section 为分段号过滤。"""
+        for b in self.branches(include_outaged=include_outaged):
+            if (b["bus1_name"].strip().upper() == bus1.strip().upper()
+                    and abs(b["kv1"] - kv1) < 0.005
+                    and b["bus2_name"].strip().upper() == bus2.strip().upper()
+                    and abs(b["kv2"] - kv2) < 0.005
+                    and (ckt is None or b["ckt"] == ckt)
+                    and (section is None
+                         or int(b.get("section", 0)) == int(section))):
+                return b
+        return None
+
+    def outaged_branches(self):
+        """返回本实例中通过 outage_branch 开断且尚未恢复的支路。"""
+        return [b for b in self.branches(include_outaged=True)
+                if not b.get("in_service", True)]
+
+    def _areas_all(self):
+        if "areas_all" in self._cache:
+            return self._cache["areas_all"]
+        ci = self.case_info()
+        n = int(ci.get("num_areas") or 0)
+        maxarea = max(n * 2, 64)
+        while True:
+            fields = (c_double * (maxarea * 6))()
+            names = ((c_char * 11) * maxarea)()
+            sbuses = ((c_char * 9) * maxarea)()
+            got = self._lib.ipfpy_get_areas(
+                ctypes.byref(fields), ctypes.byref(names),
+                ctypes.byref(sbuses), maxarea)
+            if got >= 0:
+                break
+            if maxarea >= 10000:
+                raise PyFlowError("ipfpy_get_areas 缓冲区不足")
+            maxarea *= 2
+        out = []
+        f = fields
+        for i in range(got):
+            out.append({
+                "name": _text(names[i].raw),
+                "sbus_name": _text(sbuses[i].raw),
+                "sched_export": f[i * 6 + 0],
+                "Pgen": f[i * 6 + 1], "Pload": f[i * 6 + 2],
+                "Ploss": f[i * 6 + 3], "Pexport": f[i * 6 + 4],
+                "max_Vpu": f[i * 6 + 5],
+            })
+        self._cache["areas_all"] = out
+        return out
+
+    def areas(self):
+        """返回控制区列表（含求解字段）。"""
+        return [dict(a) for a in self._areas_all()]
+
+    def ities(self):
+        """返回联络线输入与求解数据。"""
+        if "ities" in self._cache:
+            return [dict(x) for x in self._cache["ities"]]
+        if not hasattr(self._lib, "ipfpy_get_ities"):
+            return []
+        maxitie = 64
+        while True:
+            fields = (c_double * (maxitie * 4))()
+            area1 = ((c_char * 11) * maxitie)()
+            area2 = ((c_char * 11) * maxitie)()
+            types = ((c_char * 3) * maxitie)()
+            got = self._lib.ipfpy_get_ities(
+                ctypes.byref(fields), ctypes.byref(area1),
+                ctypes.byref(area2), ctypes.byref(types), maxitie)
+            if got >= 0:
+                break
+            if maxitie >= MAXTIE * 2:
+                raise PyFlowError("ipfpy_get_ities 缓冲区不足")
+            maxitie *= 2
+        out = []
+        for i in range(got):
+            out.append({
+                "type": _text(types[i].raw),
+                "area1": _text(area1[i].raw),
+                "area2": _text(area2[i].raw),
+                "sched_export": fields[i * 4 + 0],
+                "Pexport": fields[i * 4 + 1],
+                "Pcirc": fields[i * 4 + 2],
+                "input_exists": bool(fields[i * 4 + 3]),
+            })
+        self._cache["ities"] = out
+        return [dict(x) for x in out]
+
+    def cbuses(self):
+        """返回连续母线 + 记录数据。"""
+        if "cbuses" in self._cache:
+            return [dict(x) for x in self._cache["cbuses"]]
+        if not hasattr(self._lib, "ipfpy_get_cbuses"):
+            return []
+        maxc = 256
+        while True:
+            fields = (c_double * (maxc * 13))()
+            names = ((c_char * 9) * maxc)()
+            types = ((c_char * 3) * maxc)()
+            owners = ((c_char * 4) * maxc)()
+            years = ((c_char * 3) * maxc)()
+            kvs = (c_float * maxc)()
+            got = self._lib.ipfpy_get_cbuses(
+                ctypes.byref(fields), ctypes.byref(names),
+                ctypes.byref(types), ctypes.byref(owners),
+                ctypes.byref(years), ctypes.byref(kvs), maxc)
+            if got >= 0:
+                break
+            if maxc >= MAXBUS:
+                raise PyFlowError("ipfpy_get_cbuses 缓冲区不足")
+            maxc *= 2
+        out = []
+        for i in range(got):
+            out.append({
+                "type": _text(types[i].raw),
+                "owner": _text(owners[i].raw),
+                "name": _text(names[i].raw),
+                "kv": kvs[i],
+                "year": _text(years[i].raw),
+                "Pload": fields[i * 13 + 0],
+                "Qload": fields[i * 13 + 1],
+                "Gshunt": fields[i * 13 + 2],
+                "Bshunt": fields[i * 13 + 3],
+                "Pgen_sched": fields[i * 13 + 4],
+                "Qgen_Qmax": fields[i * 13 + 5],
+                "Qmin": fields[i * 13 + 6],
+                "Pgen": fields[i * 13 + 7],
+                "Qgen": fields[i * 13 + 8],
+                "Pload_solved": fields[i * 13 + 9],
+                "Qload_solved": fields[i * 13 + 10],
+                "Gshunt_solved": fields[i * 13 + 11],
+                "Bshunt_solved": fields[i * 13 + 12],
+            })
+        self._cache["cbuses"] = out
+        return [dict(x) for x in out]
+
+    def qcurves(self):
+        """返回无功能力曲线原始点，p_levels 为 Pgen0..Pgen9。"""
+        if "qcurves" in self._cache:
+            return [dict(x) for x in self._cache["qcurves"]]
+        if not hasattr(self._lib, "ipfpy_get_qcurves"):
+            return []
+        maxq = 256
+        while True:
+            fields = (c_double * (maxq * 10))()
+            names = ((c_char * 9) * maxq)()
+            types = ((c_char * 3) * maxq)()
+            pu_codes = ((c_char * 3) * maxq)()
+            actives = ((c_char * 1) * maxq)()
+            kvs = (c_float * maxq)()
+            got = self._lib.ipfpy_get_qcurves(
+                ctypes.byref(fields), ctypes.byref(names),
+                ctypes.byref(types), ctypes.byref(pu_codes),
+                ctypes.byref(actives), ctypes.byref(kvs), maxq)
+            if got >= 0:
+                break
+            if maxq >= MAXBUS:
+                raise PyFlowError("ipfpy_get_qcurves 缓冲区不足")
+            maxq *= 2
+        out = []
+        for i in range(got):
+            out.append({
+                "type": _text(types[i].raw),
+                "pu_code": _text(pu_codes[i].raw),
+                "active": actives.raw[i:i + 1].decode(
+                    "ascii", "replace"),
+                "bus": _text(names[i].raw),
+                "kv": kvs[i],
+                "p_levels": [fields[i * 10 + j] for j in range(10)],
+            })
+        self._cache["qcurves"] = out
+        return [dict(x) for x in out]
+
+    def xdata(self):
+        """返回可投切电抗器各段计划/实际步数与 MVAr。"""
+        if "xdata" in self._cache:
+            return [dict(x) for x in self._cache["xdata"]]
+        if not hasattr(self._lib, "ipfpy_get_xdata"):
+            return []
+        maxx = 256
+        while True:
+            fields = (c_double * (maxx * 40))()
+            names = ((c_char * 9) * maxx)()
+            owners = ((c_char * 4) * maxx)()
+            types = ((c_char * 3) * maxx)()
+            rmt_names = ((c_char * 9) * maxx)()
+            kvs = (c_float * maxx)()
+            rmt_kvs = (c_float * maxx)()
+            got = self._lib.ipfpy_get_xdata(
+                ctypes.byref(fields), ctypes.byref(names),
+                ctypes.byref(owners), ctypes.byref(types),
+                ctypes.byref(rmt_names), ctypes.byref(kvs),
+                ctypes.byref(rmt_kvs), maxx)
+            if got >= 0:
+                break
+            if maxx >= MAXBUS:
+                raise PyFlowError("ipfpy_get_xdata 缓冲区不足")
+            maxx *= 2
+        out = []
+        for i in range(got):
+            base = i * 40
+            segments = []
+            for j in range(8):
+                segments.append({
+                    "num_steps": int(fields[base + j]),
+                    "delta_mva": fields[base + 8 + j],
+                    "sch_units": int(fields[base + 16 + j]),
+                    "used_units": int(fields[base + 24 + j]),
+                    "mvar_per_unit": fields[base + 32 + j],
+                })
+            out.append({
+                "type": _text(types[i].raw),
+                "owner": _text(owners[i].raw),
+                "bus": _text(names[i].raw),
+                "kv": kvs[i],
+                "remote_bus": _text(rmt_names[i].raw),
+                "remote_kv": rmt_kvs[i],
+                "segments": segments,
+            })
+        self._cache["xdata"] = out
+        return [dict(x) for x in out]
+
+    def comments(self):
+        """返回算例名、描述、三行标题和最多 20 行注释。"""
+        if "comments" in self._cache:
+            return dict(self._cache["comments"])
+        if not hasattr(self._lib, "ipfpy_get_comments"):
+            return {"case_name": "", "case_desc": "", "headers": [],
+                    "comments": []}
+        case_name = create_string_buffer(11)
+        case_desc = create_string_buffer(21)
+        headers = create_string_buffer(3 * 133)
+        comments = create_string_buffer(20 * 121)
+        rc = self._lib.ipfpy_get_comments(case_name, case_desc,
+                                          headers, comments)
+        if rc != 0:
+            raise PyFlowError("ipfpy_get_comments 失败, rc=%d" % rc)
+
+        def _fixed(raw):
+            return bytes(raw).decode("ascii", "replace").rstrip(
+                "\x00 ").strip()
+
+        out = {
+            "case_name": _fixed(case_name.raw),
+            "case_desc": _fixed(case_desc.raw),
+            "headers": [_fixed(headers.raw[i * 133:(i + 1) * 133])
+                        for i in range(3)],
+            "comments": [_fixed(comments.raw[i * 121:(i + 1) * 121])
+                         for i in range(20)],
+        }
+        self._cache["comments"] = out
+        return dict(out)
+
+    # 兼容旧方案文档命名的别名
+    get_buses = buses
+    get_branches = branches
+    get_areas = areas
+
+    # ------------------------------------------------------------------
+    # pandas 集成（可选依赖；未安装时回退 list[dict]，pd.DataFrame 可直接转）
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _require_pandas():
+        try:
+            import pandas as pd
+        except ImportError:
+            raise PyFlowError(
+                "pandas 未安装；可 pip install pandas，或直接对 "
+                "buses()/branches()/areas() 返回的 list[dict] 调 "
+                "pd.DataFrame(...)")
+        return pd
+
+    def buses_df(self):
+        """母线数据 -> pandas.DataFrame。"""
+        return self._require_pandas().DataFrame(self.buses())
+
+    def branches_df(self):
+        """支路数据 -> pandas.DataFrame。"""
+        return self._require_pandas().DataFrame(self.branches())
+
+    def areas_df(self):
+        """控制区数据 -> pandas.DataFrame。"""
+        return self._require_pandas().DataFrame(self.areas())
+
+    # ------------------------------------------------------------------
+    # 内部计算数据
+    # ------------------------------------------------------------------
+    def y_matrix(self):
+        """导纳矩阵（稀疏 CSR，母线按输入（外部）序排列）。
+
+        /alpha/ 中 km/kmlen 是"母线号 -> 行池起点/行长"的散列指针，
+        行池顺序为内部（最优）序。此处按母线输入序逐行 scatter 重建。
+
+        返回字典:
+          nbus   母线数（含平衡机）
+          nnz    非对角元素个数
+          indptr, indices   0-based CSR（scipy 兼容）
+          G, B              非对角元素实部/虚部
+          Gdiag, Bdiag      对角元素实部/虚部（母线输入序）
+        """
+        nbus = c_int()
+        nnz = c_int()
+        iord = c_int()
+        self._lib.ipfpy_y_info(byref(nbus), byref(nnz), byref(iord))
+
+        n = nbus.value
+        m = nnz.value
+        km = (c_int * max(n, 1))()
+        kmlen = (c_int * max(n, 1))()
+        ikmu = (c_int * max(m, 1))()
+        gkmu = (c_double * max(m, 1))()
+        bkmu = (c_double * max(m, 1))()
+        gkku = (c_double * max(n, 1))()
+        bkku = (c_double * max(n, 1))()
+        self._lib.ipfpy_y_data(
+            km, kmlen, ikmu, gkmu, bkmu, gkku, bkku,
+            byref(nbus), byref(nnz))
+
+        indptr, indices, g, b = self._y_build_csr(
+            km, kmlen, ikmu, gkmu, bkmu, n, m, iord.value)
+        gdiag = _arr(gkku, n)
+        bdiag = _arr(bkku, n)
+        # 当 ordymx=2 时，gkku/bkku 为最优序，indices 已转为输入序，
+        # 此处将 gdiag/bdiag 也转为输入序以保持一致
+        if iord.value == 2:
+            inp2opt = self._mapping_arrays()[0]
+            if _np is not None:
+                inp2opt_0 = _np.asarray(inp2opt, dtype=_np.int64) - 1
+                gdiag = _np.asarray(gdiag, dtype=_np.float64)
+                bdiag = _np.asarray(bdiag, dtype=_np.float64)
+                gdiag = gdiag[inp2opt_0]
+                bdiag = bdiag[inp2opt_0]
+            else:
+                gdiag = [gdiag[int(j) - 1] for j in inp2opt]
+                bdiag = [bdiag[int(j) - 1] for j in inp2opt]
+
+        return {
+            "nbus": n,
+            "nnz": m,
+            "ordymx": iord.value,
+            "order": "input",
+            "indptr": indptr,
+            "indices": indices,
+            "G": g,
+            "B": b,
+            "Gdiag": gdiag,
+            "Bdiag": bdiag,
+        }
+
+    def _y_build_csr(self, km, kmlen, ikmu, gkmu, bkmu, n, m, iord):
+        """把 /alpha/ 行池按母线输入序 scatter 为 0-based CSR。
+
+        ``ordymx==2`` 时 km/kmlen 的行号和 ikmu 的列号都是内部最优序；
+        通过 inp2opt/opt2inp 同时转换行、列，输出始终为输入序。
+        """
+        inp2opt, opt2inp = self._mapping_arrays()
+        if iord != 2:
+            inp2opt = list(range(1, n + 1))
+            opt2inp = list(range(1, n + 1))
+        if _np is None:
+            km_a = _arr(km, n)
+            kmlen_a = _arr(kmlen, n)
+            ikmu_a = _arr(ikmu, m)
+            g_a = _arr(gkmu, m)
+            b_a = _arr(bkmu, m)
+            indptr = [0]
+            indices = []
+            g = []
+            b = []
+            for input_i in range(n):
+                opt_i = int(inp2opt[input_i]) - 1
+                ln = kmlen_a[opt_i]
+                s = km_a[opt_i] - 1
+                indptr.append(indptr[-1] + ln)
+                for j in range(ln):
+                    indices.append(opt2inp[ikmu_a[s + j] - 1] - 1)
+                    g.append(g_a[s + j])
+                    b.append(b_a[s + j])
+            return indptr, indices, g, b
+        km_a = _np.asarray(_arr(km, n, _np.int32), dtype=_np.int64)
+        kmlen_a = _np.asarray(_arr(kmlen, n, _np.int32), dtype=_np.int64)
+        ikmu_a = _np.asarray(_arr(ikmu, m, _np.int32), dtype=_np.int64)
+        g_a = _np.asarray(_arr(gkmu, m))
+        b_a = _np.asarray(_arr(bkmu, m))
+        inp2opt_a = _np.asarray(inp2opt, dtype=_np.int64)
+        opt2inp_a = _np.asarray(opt2inp, dtype=_np.int64)
+        if n > 0:
+            opt_rows = inp2opt_a - 1
+            pool_pos = _np.concatenate([
+                km_a[i] - 1 + _np.arange(kmlen_a[i])
+                for i in opt_rows])
+            indices = (opt2inp_a[ikmu_a[pool_pos] - 1] - 1).astype(
+                _np.int32)
+            indptr = _np.zeros(n + 1, dtype=_np.int64)
+            indptr[1:] = _np.cumsum(kmlen_a[opt_rows])
+            return indptr, indices, g_a[pool_pos], b_a[pool_pos]
+        return (_np.zeros(1, dtype=_np.int64), _np.array([],
+                dtype=_np.int32), _np.array([]), _np.array([]))
+    def _mapping_arrays(self):
+        """内外序映射（voltages() 内缓存）。"""
+        if not hasattr(self, "_map"):
+            self.voltages()
+        return self._inp2opt, self._opt2inp
+
+    def _iteration_info(self, require_valid=True):
+        values = [c_int() for _ in range(7)]
+        base_mva = c_float()
+        self._lib.ipfpy_iteration_info(
+            *[byref(v) for v in values], byref(base_mva))
+        info = {
+            "valid": bool(values[0].value),
+            "iteration": values[1].value,
+            "nbus": values[2].value,
+            "nblock": values[3].value,
+            "nnz_blocks": values[4].value,
+            "overflow": bool(values[5].value),
+            "nltc": values[6].value,
+            "base_mva": base_mva.value,
+        }
+        if require_valid and not info["valid"]:
+            raise PyFlowError(
+                "尚无有效迭代快照；请先 start_solution() 并调用 "
+                "step_solution()")
+        return info
+
+    def iteration_jacobian(self, format="csr"):
+        """返回本次迭代消元前的原始 Newton 雅可比。
+
+        ``format='bsr'`` 返回 2x2 块稀疏矩阵；``'csr'`` 将其无损展开为
+        标准标量 CSR。行方程为 ``[P, Q/电压控制]``，列变量为
+        ``[angle_rad, relative_voltage]``；前 ``nltc`` 个块是 LTC 控制
+        变量/方程，随后为按引擎最优序排列的母线块。
+        """
+        info = self._iteration_info()
+        nblock, nnz = info["nblock"], info["nnz_blocks"]
+        rowmax, nnzmax = c_int(nblock + 1), c_int(nnz)
+        rowptr_c = (c_int * (nblock + 1))()
+        colind_c = (c_int * max(nnz, 1))()
+        jh = (c_double * max(nnz, 1))()
+        jn = (c_double * max(nnz, 1))()
+        jj = (c_double * max(nnz, 1))()
+        jl = (c_double * max(nnz, 1))()
+        rhs1 = (c_double * max(nblock, 1))()
+        rhs2 = (c_double * max(nblock, 1))()
+        self._lib.ipfpy_iteration_jac(
+            byref(rowmax), byref(nnzmax), rowptr_c, colind_c,
+            jh, jn, jj, jl, rhs1, rhs2)
+        rowptr = _arr(rowptr_c, nblock + 1,
+                      _np.int32 if _np is not None else None)
+        indices = _arr(colind_c, nnz,
+                       _np.int32 if _np is not None else None)
+        if _np is not None:
+            rowptr = rowptr.astype(_np.int64) - 1
+            indices = indices - 1
+            blocks = _np.empty((nnz, 2, 2), dtype=_np.float64)
+            blocks[:, 0, 0] = _arr(jh, nnz)
+            blocks[:, 0, 1] = _arr(jn, nnz)
+            blocks[:, 1, 0] = _arr(jj, nnz)
+            blocks[:, 1, 1] = _arr(jl, nnz)
+            rhs = _np.empty(2 * nblock, dtype=_np.float64)
+            rhs[0::2] = _arr(rhs1, nblock)
+            rhs[1::2] = _arr(rhs2, nblock)
+        else:
+            rowptr = [v - 1 for v in rowptr]
+            indices = [v - 1 for v in indices]
+            blocks = [[[jh[k], jn[k]], [jj[k], jl[k]]]
+                      for k in range(nnz)]
+            rhs = [value for i in range(nblock)
+                   for value in (rhs1[i], rhs2[i])]
+
+        common = {
+            "iteration": info["iteration"], "nblock": nblock,
+            "nltc": info["nltc"], "nbus": info["nbus"],
+            "rhs": rhs, "base_mva": info["base_mva"],
+            "equation_order": ("active_power", "reactive_or_control"),
+            "variable_order": ("angle_rad", "relative_voltage"),
+            "linear_system": "J * correction = rhs",
+            "phase": "pre_update",
+        }
+        if format.lower() == "bsr":
+            common.update({
+                "format": "bsr", "shape": (2 * nblock, 2 * nblock),
+                "blocksize": (2, 2), "indptr": rowptr,
+                "indices": indices, "data": blocks,
+            })
+            return common
+        if format.lower() != "csr":
+            raise ValueError("format 仅支持 'csr' 或 'bsr'")
+
+        scalar_ptr, scalar_col, scalar_data = [0], [], []
+        for block_row in range(nblock):
+            for local_row in range(2):
+                for pos in range(int(rowptr[block_row]),
+                                 int(rowptr[block_row + 1])):
+                    block_col = int(indices[pos])
+                    for local_col in range(2):
+                        scalar_col.append(2 * block_col + local_col)
+                        scalar_data.append(float(blocks[pos][local_row][local_col]))
+                scalar_ptr.append(len(scalar_col))
+        if _np is not None:
+            scalar_ptr = _np.asarray(scalar_ptr, dtype=_np.int64)
+            scalar_col = _np.asarray(scalar_col, dtype=_np.int32)
+            scalar_data = _np.asarray(scalar_data, dtype=_np.float64)
+        common.update({
+            "format": "csr", "shape": (2 * nblock, 2 * nblock),
+            "indptr": scalar_ptr, "indices": scalar_col,
+            "data": scalar_data,
+        })
+        return common
+
+    def iteration_snapshot(self, include_jacobian=True,
+                           jacobian_format="csr"):
+        """返回同一 Newton 迭代相位的一致状态快照。
+
+        快照包含更新前/后电压、原始节点不平衡量、实际施加修正量、
+        当前 PV/PQ 控制映射；可选附带消元前雅可比。所有母线向量均按
+        输入顺序排列。
+        """
+        info = self._iteration_info()
+        n = info["nbus"]
+        arrays = [(c_double * max(n, 1))() for _ in range(6)]
+        mode = (c_int * max(n, 1))()
+        inp2opt = (c_int * max(n, 1))()
+        opt2inp = (c_int * max(n, 1))()
+        nmax = c_int(n)
+        self._lib.ipfpy_iteration_bus(
+            byref(nmax), *arrays, mode, inp2opt, opt2inp)
+        pre_e, pre_f, post_e, post_f, dtheta, dvrel = [
+            _arr(a, n) for a in arrays]
+        mode_a = _arr(mode, n, _np.int32 if _np is not None else None)
+        inp_a = _arr(inp2opt, n, _np.int32 if _np is not None else None)
+        opt_a = _arr(opt2inp, n, _np.int32 if _np is not None else None)
+        vd = self.voltages()
+        names = vd["names"][:n]
+        bases = vd["base"][:n]
+        mismatch = self.mismatch_bus()
+
+        if _np is not None:
+            pre_mag = _np.hypot(pre_e, pre_f)
+            post_mag = _np.hypot(post_e, post_f)
+            pre_ang = _np.arctan2(pre_f, pre_e)
+            post_ang = _np.arctan2(post_f, post_e)
+        else:
+            import math
+            pre_mag = [math.hypot(pre_e[i], pre_f[i]) for i in range(n)]
+            post_mag = [math.hypot(post_e[i], post_f[i]) for i in range(n)]
+            pre_ang = [math.atan2(pre_f[i], pre_e[i]) for i in range(n)]
+            post_ang = [math.atan2(post_f[i], post_e[i]) for i in range(n)]
+        result = dict(info)
+        result.update({
+            "phase_contract": {
+                "voltage_before": "x_k",
+                "mismatch": "F(x_k)",
+                "jacobian": "J(x_k)",
+                "correction": "applied_delta_x_k",
+                "voltage_after": "x_k_plus_1",
+            },
+            "bus_order": "input", "names": names, "base_kv": bases,
+            "voltage_before": {"e": pre_e, "f": pre_f,
+                               "magnitude_pu": pre_mag,
+                               "angle_rad": pre_ang},
+            "voltage_after": {"e": post_e, "f": post_f,
+                              "magnitude_pu": post_mag,
+                              "angle_rad": post_ang},
+            "correction": {"angle_rad": dtheta,
+                           "relative_voltage": dvrel},
+            "control_bus_opt_index": mode_a,
+            "inp2opt": inp_a, "opt2inp": opt_a,
+            "bus_mismatch": mismatch,
+        })
+        if include_jacobian:
+            result["jacobian"] = self.iteration_jacobian(jacobian_format)
+        return result
+
+    def jacobian(self):
+        """因子化雅可比矩阵数据。
+
+        返回字典:
+          ntotx   变量数（母线数 + LTC 数）
+          koptsw  求解选项（>2 时 amtrx 含完整因子化矩阵）
+          jaclen  amtrx 实际元素个数（jndex[1,ntotx]-1）
+          jndex   (2,ntotx) 行指针（jndex[1,row] 为 1-based 起始位置）
+          amtrx   因子化矩阵元素（5 字/非对角，见文档）
+          dpt     (2,ntotx) 每次迭代残差（dpt[1,row]=P 偏差, dpt[2,row]=Q 偏差）
+        """
+        ntotx = c_int()
+        koptsw = c_int()
+        jaclen = c_int()
+        jndex = (c_int * (2 * (MAXLTC + MAXBUS)))()
+        amtrx = (c_double * MAXMTX)()
+        dpt = (c_double * (2 * (MAXBUS + 2 * MAXLTC)))()
+        self._lib.ipfpy_jac_data(jndex, amtrx, dpt, byref(jaclen),
+                                 byref(ntotx), byref(koptsw))
+        n = ntotx.value
+        jl = max(jaclen.value, 0)
+        return {
+            "ntotx": n,
+            "koptsw": koptsw.value,
+            "jaclen": jl,
+            "jndex": _arr(jndex, 2 * n, _np.int32 if _np else None),
+            "amtrx": _arr(amtrx, jl),
+            "dpt": _arr(dpt, 2 * n),
+        }
+    def mismatch(self):
+        """求解后偏差汇总（/ecvar/ + /itrhis/）。
+
+        返回字典:
+          dptot/dqtot/dttot/datot/ddtot  总体 P/Q/总和/角度 偏差
+          kownt..kowntd  各类约束计数
+          ittot          当前迭代计数
+          itrtyp         1=解耦法 2=Newton-Raphson
+          itrhis[1/2]    解耦/NR 迭代次数
+          ntot           母线数
+        """
+        dp, dq, dt, da, dd = (c_double() for _ in range(5))
+        kw, kwa, kwb, kwc, kwd = (c_int() for _ in range(5))
+        it, typ, rh1, rh2, ntot = (c_int() for _ in range(5))
+
+        self._lib.ipfpy_mismatch(
+            byref(dp), byref(dq), byref(dt), byref(da), byref(dd),
+            byref(kw), byref(kwa), byref(kwb), byref(kwc), byref(kwd),
+            byref(it), byref(typ), byref(rh1), byref(rh2), byref(ntot))
+        return {
+            "dptot": dp.value, "dqtot": dq.value, "dttot": dt.value,
+            "datot": da.value, "ddtot": dd.value,
+            "kownt": kw.value, "kownta": kwa.value, "kowntb": kwb.value,
+            "kowntc": kwc.value, "kowntd": kwd.value,
+            "ittot": it.value, "itrtyp": typ.value,
+            "itrhis_decoupled": rh1.value, "itrhis_nr": rh2.value,
+            "ntot": ntot.value,
+        }
+
+    def mismatch_bus(self):
+        """返回逐节点不平衡功率（MW/MVAr）。
+
+        读取本次 NR 迭代中 ``jacbus`` 形成、且尚未被稀疏消元修改的
+        母线方程残差，单位为 MW/MVAr。P 残差为计划注入减网络注入；
+        PV/受控母线的第二方程是电压约束，因此 ``dq_mvar`` 返回 0。
+
+        Returns
+        -------
+        list[dict]
+            [{"name": str, "kv": float, "dp_mw": float, "dq_mvar": float}, ...]
+        """
+        nbus = c_int()
+        maxbus = self.case_info().get("num_buses", 2000) + 100
+        cbus = (c_char * (8 * maxbus))()
+        p_mismatch = (c_double * maxbus)()
+        q_mismatch = (c_double * maxbus)()
+        base_mva = c_float()
+        self._lib.ipfpy_mismatch_bus(
+            byref(nbus), cbus, p_mismatch, q_mismatch, byref(base_mva))
+        n = nbus.value
+        out = []
+        vd = self.voltages()
+        for i in range(n):
+            name = _text(bytes(cbus[i * 8:(i + 1) * 8]))
+            out.append({
+                "name": name,
+                "kv": vd["base"][i] if i < len(vd["base"]) else 0.0,
+                "dp_mw": p_mismatch[i],
+                "dq_mvar": q_mismatch[i],
+            })
+        return out
+
+    def iteration_history(self):
+        """每次迭代误差最大的 8 条母线（/errbus/ 历史）。
+
+        返回列表，每项: {"iter": k, "top": [{"bus": 母线序号(1-based),
+        "perr": 误差平方和, "dp": P 偏差, "dq": Q 偏差}, ...]}；
+        另有 "buscor" 键存放第二条统计（i=5 行）。
+        """
+        buser = (c_float * (8 * 8 * 100))()
+        ibuser = (c_int * (8 * 8 * 100))()
+        self._lib.ipfpy_errbus(buser, ibuser)
+        m = self.mismatch()
+        # /errbus/ third dimension is fixed at 100 in the Fortran COMMON
+        # block; clamp defensively if callers configure a larger iteration cap.
+        niter = min(m["ittot"] + m["itrhis_decoupled"], 100)
+        out = []
+        for k in range(niter):
+            top, buscor = [], []
+            for i in range(1, 5):
+                base = ((i - 1) * 100 + k) * 8
+                b = ibuser[base + 0]
+                if b > 0:
+                    top.append({
+                        "bus": b,
+                        "perr": buser[base + 1],
+                        "dp": buser[base + 2],
+                        "dq": buser[base + 3],
+                    })
+            for i in range(5, 9):
+                base = ((i - 1) * 100 + k) * 8
+                b = ibuser[base + 0]
+                if b > 0:
+                    buscor.append({
+                        "bus": b,
+                        "perr": buser[base + 1],
+                        "dp": buser[base + 2],
+                        "dq": buser[base + 3],
+                    })
+            out.append({"iter": k + 1, "top": top, "buscor": buscor})
+        return out
+
+    def voltages(self):
+        """电压向量与内外序映射（/bus_x/ + /bus_c/）。
+
+        返回字典:
+          nbus   母线数
+          ordvlt 1=外部序 / 2=内部最优序（内核原始数组的排序）
+          e, f   电压实部/虚部（已统一转换为输入序，pu）
+          e_internal/f_internal  内核原始顺序，供数值内核诊断
+          base   基准电压（kV，外部序）
+          names/zone/owner  母线名（外部序，8/2/3 字符）
+          inp2opt, opt2inp  外部<->内部序映射（1-based）
+        """
+        nbus = c_int()
+        iordvlt = c_int()
+        e = (c_double * MAXBUS)()
+        f = (c_double * MAXBUS)()
+        base = (c_float * MAXBUS)()
+        inp2opt = (c_int * MAXBUS)()
+        opt2inp = (c_int * MAXBUS)()
+        self._lib.ipfpy_voltage(e, f, base, inp2opt, opt2inp,
+                                byref(iordvlt), byref(nbus))
+        n = nbus.value
+        cbus = (c_char * (8 * MAXBUS))()
+        czone = (c_char * (2 * MAXBUS))()
+        cowner = (c_char * (3 * MAXBUS))()
+        self._lib.ipfpy_busnames(byref(nbus), cbus, czone, cowner)
+        names = [_text(bytes(cbus[i * 8:(i + 1) * 8])) for i in range(n)]
+        zones = [_text(bytes(czone[i * 2:(i + 1) * 2])) for i in range(n)]
+        owners = [_text(bytes(cowner[i * 3:(i + 1) * 3])) for i in range(n)]
+        self._inp2opt = _arr(inp2opt, n, _np.int32 if _np else None)
+        self._opt2inp = _arr(opt2inp, n, _np.int32 if _np else None)
+        e_internal = _arr(e, n)
+        f_internal = _arr(f, n)
+        if iordvlt.value == 2:
+            if _np is not None:
+                input_to_opt = _np.asarray(
+                    self._inp2opt, dtype=_np.int64) - 1
+                e_input = _np.asarray(e_internal)[input_to_opt].copy()
+                f_input = _np.asarray(f_internal)[input_to_opt].copy()
+            else:
+                e_input = [e_internal[int(j) - 1] for j in self._inp2opt]
+                f_input = [f_internal[int(j) - 1] for j in self._inp2opt]
+        else:
+            e_input, f_input = e_internal, f_internal
+        return {
+            "nbus": n,
+            "ordvlt": iordvlt.value,
+            "order": "input",
+            "e": e_input,
+            "f": f_input,
+            "e_internal": e_internal,
+            "f_internal": f_internal,
+            "base": _arr(base, n, _np.float32 if _np else None),
+            "names": names,
+            "zone": zones,
+            "owner": owners,
+            "inp2opt": self._inp2opt,
+            "opt2inp": self._opt2inp,
+        }
+
+
+def connect(url, token=None, timeout=60.0):
+    """Connect to a remote bpa-server (see :mod:`bpaflow.remote`)."""
+    from .remote import connect as _connect
+    return _connect(url, token=token, timeout=timeout)