load-flow-engine 0.1.0__py3-none-any.whl

load_flow_engine/__init__.py

@@ -0,0 +1,42 @@
+"""
+load_flow_engine — Three-phase unbalanced load flow solver package.
+
+Re-exports all public symbols for convenience::
+
+    from load_flow_engine import Network, ThreePhaseLoadFlowSolver, Bus, Branch, ...
+"""
+
+from .enums import PhaseType, BusType
+from .constants import _a, _A, _Ai
+from .models import (
+    StudyCase,
+    Bus,
+    Branch,
+    Transformer,
+    Load,
+    Generator,
+    Shunt,
+    BranchResult,
+)
+from .helpers import _active_phases, _seq_to_z_abc, _matrix_invert_3x3
+from .network import Network
+from .solver import ThreePhaseLoadFlowSolver
+from .example import build_example_network, run_example
+
+__all__ = [
+    # Enums
+    "PhaseType", "BusType",
+    # Constants
+    "_a", "_A", "_Ai",
+    # Models
+    "StudyCase", "Bus", "Branch", "Transformer", "Load",
+    "Generator", "Shunt", "BranchResult",
+    # Helpers
+    "_active_phases", "_seq_to_z_abc", "_matrix_invert_3x3",
+    # Network
+    "Network",
+    # Solver
+    "ThreePhaseLoadFlowSolver",
+    # Example
+    "build_example_network", "run_example",
+]

load_flow_engine/constants.py

@@ -0,0 +1,12 @@
+"""
+Symmetrical-component (Fortescue) transformation matrices.
+Mirrors ETAP's use of A-matrix for zero/pos/neg sequence decomposition.
+"""
+
+import numpy as np
+
+_a   = np.exp(1j * 2.0 * np.pi / 3.0)          # 1∠120°
+_A   = np.array([[1,      1,      1     ],       # Fortescue A
+                 [1,      _a**2,  _a    ],
+                 [1,      _a,     _a**2 ]], dtype=complex)
+_Ai  = np.linalg.inv(_A)                        # A⁻¹

load_flow_engine/enums.py

@@ -0,0 +1,24 @@
+"""Phase and bus type enumerations matching ETAP definitions."""
+
+from enum import IntEnum
+
+
+class PhaseType(IntEnum):
+    """
+    Matches ETAPPhaseType enum in NetworkReductionEC.h.
+    Defines which phases a bus or branch participates in.
+    """
+    ABC = 0   # three-phase
+    A   = 5   # single-phase A
+    B   = 6   # single-phase B
+    C   = 7   # single-phase C
+    AB  = 8   # two-phase A-B
+    BC  = 9   # two-phase B-C
+    CA  = 10  # two-phase C-A
+
+
+class BusType(IntEnum):
+    """Standard power-flow bus types."""
+    SLACK = 0   # swing bus — |V| and ∠V fixed per phase
+    PV    = 1   # voltage-controlled — P and |V| fixed, Q within limits
+    PQ    = 2   # load bus — P and Q fixed per phase

load_flow_engine/example.py

@@ -0,0 +1,114 @@
+"""
+Four-bus radial distribution feeder example.
+
+Topology (12.47 kV primary, 4.16 kV secondary after transformer):
+
+  BUS1 (slack)  ──── XFM1 ────  BUS2  ──── BR1 ────  BUS3  ──── BR2 ────  BUS4
+   12.47 kV                    4.16 kV               4.16 kV              4.16 kV
+  swing bus              3φ balanced load    3φ+1φ unbalanced load    1φ-A load only
+
+BUS2: 3-phase balanced load  150 kW + j50 kVAr on each phase
+BUS3: unbalanced load  300 kW/ph-A, 100 kW/ph-B, 200 kW/ph-C + reactive
+BUS4: single-phase A load  400 kW + j200 kVAr on phase A only
+"""
+
+import numpy as np
+
+from .enums import PhaseType, BusType
+from .constants import _Ai
+from .models import Bus, Branch, Transformer, Load, StudyCase
+from .network import Network
+from .solver import ThreePhaseLoadFlowSolver
+
+
+def build_example_network() -> Network:
+    sc  = StudyCase(max_iterations=50, solution_precision=1e-4, base_mva=10.0)
+    net = Network(sc)
+
+    # ---- Buses ----
+    net.add_bus(Bus("BUS1", BusType.SLACK, PhaseType.ABC, base_kv=12.47))
+    net.add_bus(Bus("BUS2", BusType.PQ,    PhaseType.ABC, base_kv=4.16))
+    net.add_bus(Bus("BUS3", BusType.PQ,    PhaseType.ABC, base_kv=4.16))
+    net.add_bus(Bus("BUS4", BusType.PQ,    PhaseType.ABC, base_kv=4.16))
+
+    # ---- Transformer BUS1 → BUS2 ----
+    # 3 MVA, 12.47/4.16 kV, wye-grounded / wye-grounded
+    # Z1 = 1%, Z0 = 1% on transformer base
+    net.add_transformer(Transformer(
+        id="XFM1", from_bus="BUS1", to_bus="BUS2",
+        r1=0.005, x1=0.06, r0=0.005, x0=0.06,
+        mva_rating=3.0,
+        conn_primary='wye_grounded', conn_secondary='wye_grounded',
+    ))
+
+    # ---- Branch BUS2 → BUS3  (3-phase overhead line, 1 km) ----
+    # Z1 = 0.306 + j0.627 Ω/km,  Z0 = 0.745 + j1.2 Ω/km
+    # Base Z = (4.16²/10) = 1.731 Ω  →  divide to get pu
+    Zbase = 4.16**2 / 10.0   # 1.731 Ω
+    net.add_branch(Branch(
+        id="BR1", from_bus="BUS2", to_bus="BUS3",
+        phase_type=PhaseType.ABC,
+        r1=0.306/Zbase, x1=0.627/Zbase,
+        r0=0.745/Zbase, x0=1.200/Zbase,
+        b1=0.0,
+        ampacity=np.full(3, 300.0),   # 300 A rated
+    ))
+
+    # ---- Branch BUS3 → BUS4  (single-phase A, 0.5 km) ----
+    net.add_branch(Branch(
+        id="BR2", from_bus="BUS3", to_bus="BUS4",
+        phase_type=PhaseType.A,
+        r1=(0.306*0.5)/Zbase, x1=(0.627*0.5)/Zbase,
+        r0=(0.745*0.5)/Zbase, x0=(1.200*0.5)/Zbase,
+        ampacity=np.array([200.0, 0.0, 0.0]),
+    ))
+
+    # ---- Loads ----
+    # BUS2: balanced 3-phase load  150 kW + j50 kVAr / phase
+    net.add_load(Load("LD2", "BUS2", PhaseType.ABC,
+                      mw   = np.array([0.15, 0.15, 0.15]),
+                      mvar = np.array([0.05, 0.05, 0.05])))
+
+    # BUS3: unbalanced 3-phase load
+    net.add_load(Load("LD3", "BUS3", PhaseType.ABC,
+                      mw   = np.array([0.30, 0.10, 0.20]),
+                      mvar = np.array([0.15, 0.05, 0.10])))
+
+    # BUS4: single-phase A load  400 kW + j200 kVAr
+    net.add_load(Load("LD4", "BUS4", PhaseType.A,
+                      mw   = np.array([0.40, 0.0, 0.0]),
+                      mvar = np.array([0.20, 0.0, 0.0])))
+
+    return net
+
+
+def run_example() -> None:
+    print("\n" + "=" * 72)
+    print("  ETAP-Style Three-Phase Unbalanced Load Flow  —  4-Bus Feeder")
+    print("=" * 72)
+
+    net    = build_example_network()
+    solver = ThreePhaseLoadFlowSolver(net)
+
+    converged = solver.solve()
+
+    if not converged:
+        print("WARNING: solver did not converge!")
+
+    solver.print_bus_results()
+
+    br_results = solver.compute_branch_results()
+    solver.print_branch_results(br_results)
+
+    # ---- Voltage unbalance at BUS3 ----
+    b3 = net.buses["BUS3"]
+    V_abc = np.array([
+        b3.v_mag[p] * np.exp(1j * np.deg2rad(b3.v_ang[p]))
+        for p in range(3)
+    ])
+    V_012     = _Ai @ V_abc
+    vuf_neg   = abs(V_012[2]) / abs(V_012[1]) * 100.0
+    vuf_zero  = abs(V_012[0]) / abs(V_012[1]) * 100.0
+    print(f"  BUS3 Voltage Unbalance Factor (NEMA neg-seq) : {vuf_neg:.3f} %")
+    print(f"  BUS3 Voltage Unbalance Factor (zero-seq)     : {vuf_zero:.3f} %")
+    print()

load_flow_engine/helpers.py

@@ -0,0 +1,84 @@
+"""Helper functions for impedance transforms and phase mapping."""
+
+from typing import List, Optional
+
+import numpy as np
+
+from .enums import PhaseType
+
+
+def _active_phases(phase_type: PhaseType) -> List[int]:
+    """
+    Return the sorted list of active phase indices (0=A, 1=B, 2=C)
+    for a given PhaseType, matching ETAPPhaseType handling in
+    NetworkReductionEC.cpp.
+    """
+    mapping = {
+        PhaseType.ABC: [0, 1, 2],
+        PhaseType.A:   [0],
+        PhaseType.B:   [1],
+        PhaseType.C:   [2],
+        PhaseType.AB:  [0, 1],
+        PhaseType.BC:  [1, 2],
+        PhaseType.CA:  [0, 2],
+    }
+    return sorted(mapping.get(phase_type, [0, 1, 2]))
+
+
+def _seq_to_z_abc(z1: complex, z0: complex) -> np.ndarray:
+    """
+    Convert positive- and zero-sequence impedances to the 3×3 phase-domain
+    impedance matrix for a fully transposed line.
+
+    Mirrors NetworkReductionEC's use of the symmetrical-component transform:
+        Z_abc = A · diag(Z0, Z1, Z1) · A⁻¹
+
+    For a transposed line this reduces to the Toeplitz form:
+        Zs = (Z0 + 2·Z1) / 3    (self impedance)
+        Zm = (Z0 −    Z1) / 3   (mutual impedance)
+
+        Z_abc = [[Zs, Zm, Zm],
+                 [Zm, Zs, Zm],
+                 [Zm, Zm, Zs]]
+    """
+    Zs = (z0 + 2.0 * z1) / 3.0
+    Zm = (z0       - z1) / 3.0
+    return np.array([[Zs, Zm, Zm],
+                     [Zm, Zs, Zm],
+                     [Zm, Zm, Zs]], dtype=complex)
+
+
+def _matrix_invert_3x3(Z: np.ndarray) -> Optional[np.ndarray]:
+    """
+    Invert a 3×3 complex matrix using Gauss-Jordan elimination.
+    Mirrors MatrixInvert(DComplexEC mtxZ[3][3]) in NetworkReductionEC.cpp,
+    including the same singular-matrix guard (returns None on failure).
+    """
+    SMALL = 1e-12
+    A = Z.astype(complex).copy()
+    I = np.eye(3, dtype=complex)
+
+    for i in range(3):
+        # Partial pivoting (mirrors ETAP's row-sum fallback)
+        if abs(A[i, i]) < SMALL:
+            swapped = False
+            for k in range(i + 1, 3):
+                if abs(A[k, i]) >= SMALL:
+                    A[[i, k]] = A[[k, i]]
+                    I[[i, k]] = I[[k, i]]
+                    swapped = True
+                    break
+            if not swapped:
+                return None   # singular
+
+        pivot = A[i, i]
+        A[i] /= pivot
+        I[i] /= pivot
+
+        for k in range(3):
+            if k != i and abs(A[k, i]) >= SMALL:
+                factor = A[k, i]
+                A[k] -= factor * A[i]
+                I[k] -= factor * I[i]
+
+    return I

load_flow_engine/models.py

@@ -0,0 +1,219 @@
+"""Data classes mirroring ETAP DB accessor structures."""
+
+from dataclasses import dataclass, field
+from typing import List
+
+import numpy as np
+
+from .enums import PhaseType, BusType
+
+
+@dataclass
+class StudyCase:
+    """
+    Mirrors LF3PH_STUDY_CASE_DATA from dataTyp6.h.
+    Controls solver parameters.
+    """
+    max_iterations:     int   = 100     # maximumIteration
+    solution_precision: float = 1e-4    # solutionPrecision (MVA mismatch)
+    base_mva:           float = 100.0   # system MVA base
+    flat_start:         bool  = True    # use 1.0 pu / nominal angles
+
+
+@dataclass
+class Bus:
+    """
+    Mirrors IBusLF3PHAccessor from IBusLF3PH.h.
+
+    All voltage magnitudes are in per-unit; angles in degrees.
+    Powers are in MW and MVAr (converted to pu internally during solve).
+    Array index 0=A, 1=B, 2=C throughout.
+    """
+    id:         str
+    bus_type:   BusType   = BusType.PQ
+    phase_type: PhaseType = PhaseType.ABC
+    base_kv:    float     = 12.47          # m_BasekV
+    name:       str       = ''             # MC source name for cross-referencing
+
+    # Solved voltages — m_VMagA/B/C, m_VAngA/B/C
+    v_mag: np.ndarray = field(
+        default_factory=lambda: np.ones(3))
+    v_ang: np.ndarray = field(
+        default_factory=lambda: np.array([0.0, -120.0, 120.0]))
+
+    # Initial voltage guess — m_IniVMagA/B/C, m_IniAngA/B/C
+    ini_v_mag: np.ndarray = field(
+        default_factory=lambda: np.ones(3))
+    ini_v_ang: np.ndarray = field(
+        default_factory=lambda: np.array([0.0, -120.0, 120.0]))
+
+    # Scheduled generation per phase (MW, MVAr) — m_GenMWA/B/C, m_GenMvarA/B/C
+    gen_mw:   np.ndarray = field(default_factory=lambda: np.zeros(3))
+    gen_mvar: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Scheduled load per phase (MW, MVAr) — m_LoadMWA/B/C, m_LoadMvarA/B/C
+    load_mw:   np.ndarray = field(default_factory=lambda: np.zeros(3))
+    load_mvar: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Reactive limits (PV buses) — m_MvarMax, m_MvarMin
+    mvar_max: float = 9999.0
+    mvar_min: float = -9999.0
+
+
+@dataclass
+class Branch:
+    """
+    Mirrors IConnectLF3PHAccessor from IConnectLF3PH.h.
+
+    Stores positive- and zero-sequence impedances in per-unit.
+    The 3×3 phase-domain matrix Z_abc is computed at build time via the
+    symmetrical-component transform (same as NetworkReductionEC).
+    """
+    id:         str
+    from_bus:   str
+    to_bus:     str
+    phase_type: PhaseType = PhaseType.ABC
+    name:       str       = ''
+
+    # Positive-sequence series impedance (pu) — m_R, m_X
+    r1: float = 0.0
+    x1: float = 0.0
+
+    # Zero-sequence series impedance (pu) — m_R0, m_X0
+    r0: float = 0.0
+    x0: float = 0.0
+
+    # Shunt charging susceptance (pu, positive-sequence total line charging)
+    b1: float = 0.0
+
+    # Ampacity per phase (amps) for loading-% calc — m_AmpacityA/B/C
+    ampacity: np.ndarray = field(default_factory=lambda: np.full(3, 9999.0))
+
+
+@dataclass
+class Transformer:
+    """
+    Two-winding transformer.
+    Mirrors LF3PH_Xfmr2Data from dataTyp6.h.
+
+    Impedances are in pu on the transformer's own MVA base; they are
+    converted to the system base during Network.build().
+    """
+    id:           str
+    from_bus:     str          # primary (HV) bus
+    to_bus:       str          # secondary (LV) bus
+    phase_type:   PhaseType  = PhaseType.ABC
+    name:         str        = ''
+
+    # Leakage impedance (pu on xfmr base) — positive-sequence
+    r1: float = 0.0
+    x1: float = 0.01
+
+    # Zero-sequence leakage impedance
+    r0: float = 0.0
+    x0: float = 0.01
+
+    # Transformer MVA rating (used for base conversion)
+    mva_rating: float = 1.0
+
+    # Off-nominal tap (pu of nominal ratio) — m_TapPctPrim / m_TapPctSec
+    tap_primary:   float = 1.0
+    tap_secondary: float = 1.0
+
+    # Winding connections (affects zero-sequence path)
+    # Supported: 'wye_grounded', 'wye', 'delta'
+    conn_primary:   str = 'wye_grounded'
+    conn_secondary: str = 'wye_grounded'
+
+    # HV phases this transformer is connected to (0=A, 1=B, 2=C)
+    hv_phases: List[int] = field(default_factory=lambda: [0, 1, 2])
+
+
+@dataclass
+class Load:
+    """
+    Static load element — mirrors LF3PH_StaticLoadData from dataTyp6.h.
+    Per-phase MW and MVAr. add_load() aggregates these onto the bus.
+    """
+    id:         str
+    bus_id:     str
+    phase_type: PhaseType = PhaseType.ABC
+    name:       str       = ''
+    mw:   np.ndarray = field(default_factory=lambda: np.zeros(3))
+    mvar: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+
+@dataclass
+class Generator:
+    """
+    Synchronous generator — mirrors LF3PH_SynGenData from dataTyp6.h.
+    """
+    id:       str
+    bus_id:   str
+    bus_type: BusType = BusType.PV
+    name:     str     = ''
+
+    mw:       np.ndarray = field(default_factory=lambda: np.zeros(3))
+    v_set_pu: float      = 1.0
+    mvar_max: float      = 9999.0
+    mvar_min: float      = -9999.0
+
+
+@dataclass
+class Shunt:
+    """
+    Shunt element — per-phase MW and MVAr (capacitor/reactor banks).
+    """
+    id:         str
+    bus_id:     str
+    phase_type: PhaseType = PhaseType.ABC
+    name:       str       = ''
+    p_mw:  np.ndarray = field(default_factory=lambda: np.zeros(3))
+    q_mvar: np.ndarray = field(default_factory=lambda: np.zeros(3))
+    vn_kv:  float = 12.47
+    closed: bool = True
+
+
+@dataclass
+class Switch:
+    """
+    Switch element — connects two buses with optional resistance.
+    """
+    id:      str
+    bus:     int = 0
+    element: int = 0
+    et:      str = 'b'       # 'b' = bus-bus, 'l' = line
+    sw_type: str = 'LBS'
+    closed:  bool = True
+    phase:   int = 0
+    r_ohm:   float = 0.0
+
+
+@dataclass
+class BranchResult:
+    """
+    Post-solve per-branch results.
+    Field names mirror LFSumBranchLF3PHAccessor from LFSumBranchLF3PH.h.
+    """
+    id:       str
+    from_bus: str
+    to_bus:   str
+
+    # Per-phase current — m_LoadingAmpMagA/B/C, m_LoadingAmpAngA/B/C
+    i_mag_abc: np.ndarray = field(default_factory=lambda: np.zeros(3))
+    i_ang_abc: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Per-phase apparent power (MVA) from/to — m_LoadingInMVAA/B/C, m_LoadingOutMVAA/B/C
+    mva_from: np.ndarray = field(default_factory=lambda: np.zeros(3))
+    mva_to:   np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Per-phase loading percent — m_Loading_A/B/C
+    loading_pct: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Sequence currents — m_LoadingAmpMag0/1/2, m_LoadingAmpAng0/1/2
+    i_mag_012: np.ndarray = field(default_factory=lambda: np.zeros(3))
+    i_ang_012: np.ndarray = field(default_factory=lambda: np.zeros(3))
+
+    # Unbalance factors — m_CUF2 (negative-seq), m_CUF0 (zero-seq)
+    cuf2: float = 0.0
+    cuf0: float = 0.0