scr-screen 0.1.0__py3-none-any.whl

scr_screen/__init__.py

@@ -0,0 +1,3 @@
+"""SCR-Screen: short-circuit ratio screening for inverter-based resource interconnection."""
+
+__version__ = "0.1.0"

scr_screen/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m scr_screen``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

scr_screen/check.py

@@ -0,0 +1,138 @@
+"""Check whether a network is ready for SCR-Screen, before scanning.
+
+Lists, in plain language, anything missing or unsupported (for example a
+generator without sub-transient reactance), and says which short-circuit
+methods can run.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+from .classical import UNSUPPORTED_TABLES, connected_to_source
+from .netmap import MAX_MAP_BUSES, bus_label
+
+ERROR, WARNING, INFO = "error", "warning", "info"
+CLASSICAL_SLOW_ABOVE = 5000
+
+
+@dataclass
+class Finding:
+    level: str      # error, warning, info
+    applies_to: str  # "both", "classical", "iec60909", or "report"
+    message: str
+
+
+@dataclass
+class CheckReport:
+    n_buses: int
+    findings: list[Finding] = field(default_factory=list)
+
+    def ready(self, method: str) -> bool:
+        return not any(f.level == ERROR and f.applies_to in ("both", method) for f in self.findings)
+
+    def add(self, level, applies_to, message):
+        self.findings.append(Finding(level, applies_to, message))
+
+
+def check_network(net) -> CheckReport:
+    live = [int(b) for b in net.bus.index[net.bus["in_service"]]] if len(net.bus) else []
+    rep = CheckReport(n_buses=len(live))
+    if not live:
+        rep.add(ERROR, "both", "The network has no in-service buses.")
+        return rep
+
+    # --- Sources --------------------------------------------------------------
+    eg = net.ext_grid[net.ext_grid["in_service"]] if "ext_grid" in net else []
+    gens = net.gen[net.gen["in_service"]] if "gen" in net else []
+    if len(eg) == 0 and len(gens) == 0:
+        rep.add(ERROR, "both", "No in-service external grid or synchronous generator: "
+                "there is no source of short-circuit current.")
+
+    for idx, row in (eg.iterrows() if len(eg) else []):
+        name = _name(row, f"external grid {idx}")
+        if not _pos(row.get("s_sc_max_mva")) or not _nonneg(row.get("rx_max")):
+            rep.add(ERROR, "both", f"{name} (bus {bus_label(net, int(row['bus']))}) needs "
+                    "s_sc_max_mva and rx_max (short-circuit MVA and R/X of the grid source).")
+
+    missing_classical, missing_iec = [], []
+    for idx, row in (gens.iterrows() if len(gens) else []):
+        name = f"{_name(row, f'generator {idx}')} (bus {bus_label(net, int(row['bus']))})"
+        if not _pos(row.get("xdss_pu")) or not _pos(row.get("sn_mva")):
+            missing_classical.append(name)
+        elif not (_pos(row.get("vn_kv")) and _nonneg(row.get("rdss_ohm")) and _pos(row.get("cos_phi"))):
+            missing_iec.append(name)
+    if missing_classical:
+        rep.add(ERROR, "both", f"{len(missing_classical)} generator(s) lack sub-transient data "
+                f"(xdss_pu and sn_mva): {_short(missing_classical)}.")
+    if missing_iec:
+        rep.add(ERROR, "iec60909", f"{len(missing_iec)} generator(s) lack vn_kv, rdss_ohm or cos_phi, "
+                f"which IEC 60909 needs: {_short(missing_iec)}.")
+
+    # --- Elements the classical method does not model in v0.1 ---------------
+    for table in UNSUPPORTED_TABLES:
+        if table in net and len(net[table]) and "in_service" in net[table]:
+            n = int(net[table]["in_service"].sum())
+            if n:
+                rep.add(ERROR, "classical", f"{n} in-service '{table}' element(s): not modeled by "
+                        "the classical method in v0.1 (try --method iec60909).")
+    if "switch" in net and len(net.switch):
+        n = int(((net.switch["et"] == "b") & net.switch["closed"]).sum())
+        if n:
+            rep.add(ERROR, "classical", f"{n} closed bus-bus switch(es): not supported by the "
+                    "classical method in v0.1 (merge those buses, or try --method iec60909).")
+
+    # --- Connectivity ---------------------------------------------------------
+    if len(eg) or len(gens):
+        reach = connected_to_source(net, set(live))
+        isolated = [b for b in live if b not in reach]
+        if isolated:
+            rep.add(WARNING, "both", f"{len(isolated)} bus(es) have no path to any source and will "
+                    f"be skipped in scans: {_short([bus_label(net, b) for b in isolated])}.")
+
+    # --- Information ------------------------------------------------------------
+    n_ibr = sum(int(net[t]["in_service"].sum()) for t in ("sgen", "storage") if t in net and len(net[t]))
+    if n_ibr:
+        rep.add(INFO, "both", f"{n_ibr} inverter-based resource(s) (sgen/storage) found; their "
+                "contribution is excluded from short-circuit MVA, as NERC's SCR definition requires.")
+    labels = [bus_label(net, b) for b in live]
+    if len(set(labels)) != len(labels):
+        rep.add(INFO, "report", "Bus names are not unique, so reports label buses by pandapower index.")
+    if "geo" in net.bus.columns and net.bus.loc[live, "geo"].notna().all():
+        rep.add(INFO, "report", "All buses have coordinates: the map will use them.")
+    else:
+        rep.add(INFO, "report", "Not all buses have coordinates: the map will use an automatic layout.")
+    if len(live) > MAX_MAP_BUSES:
+        rep.add(INFO, "report", f"{len(live)} buses: above the {MAX_MAP_BUSES}-bus limit, so the "
+                "report will omit the network map.")
+    if len(live) > CLASSICAL_SLOW_ABOVE:
+        rep.add(WARNING, "classical", f"{len(live)} buses: the classical method may be slow or run "
+                "out of memory at this size in v0.1; IEC 60909 may be faster.")
+    return rep
+
+
+def _name(row, default):
+    n = row.get("name")
+    if n is None or (isinstance(n, float) and math.isnan(n)) or str(n).strip() == "":
+        return default
+    return str(n)
+
+
+def _pos(v):
+    try:
+        return v is not None and math.isfinite(float(v)) and float(v) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _nonneg(v):
+    try:
+        return v is not None and math.isfinite(float(v)) and float(v) >= 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _short(items, n=8):
+    items = [str(i) for i in items]
+    return ", ".join(items[:n]) + (f" and {len(items) - n} more" if len(items) > n else "")

scr_screen/classical.py

@@ -0,0 +1,256 @@
+"""Classical flat-start short-circuit MVA (Option B).
+
+Method (common U.S. planning practice for SCR screening):
+    1. Every bus starts at 1.0 pu voltage ("flat start").
+    2. Sources are modeled as impedances to ground:
+         - external grids: Z = 1 / S_sc (pu), split by R/X, with NO IEC c-factor;
+         - synchronous generators: sub-transient reactance X''d (plus R).
+       Inverter-based resources (sgen, storage) are not sources, so their
+       contribution is excluded automatically.
+    3. Lines and transformers are series impedances. Loads, shunts and line
+       charging are ignored; transformers are at nominal ratio.
+    4. Build the bus admittance matrix Y, then for each bus i:
+         Z_th,i = [Y^-1]_ii   and   SCMVA_i = S_base / |Z_th,i|   (V = 1.0 pu)
+
+v0.1 supports: bus, ext_grid, gen, line, trafo (two-winding), and
+line/transformer switches. Other in-service elements raise a clear error
+rather than being silently ignored.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .metrics import InputError
+
+S_BASE_MVA = 100.0
+
+# Element tables that would change the result but aren't modeled in v0.1.
+UNSUPPORTED_TABLES = ("trafo3w", "impedance", "xward", "ward", "dcline", "tcsc", "ssc", "vsc")
+
+
+def scmva_classical(net, bus_list: list[int], skip_isolated: bool = False
+                    ) -> tuple[dict[int, float], list[str]]:
+    """Return {bus: SCMVA} using the classical flat-start method, plus notes.
+
+    Buses with no electrical path to any source cannot have a short-circuit
+    level. With skip_isolated=True (used by full-network scans) they are left
+    out and listed in the notes; otherwise requesting one raises InputError.
+    """
+    _check_supported(net)
+
+    live = [int(b) for b in net.bus.index[net.bus["in_service"]]]
+    reachable = connected_to_source(net, set(live))
+    isolated = [b for b in live if b not in reachable]
+    buses = [b for b in live if b in reachable]
+    pos = {b: k for k, b in enumerate(buses)}
+    n = len(buses)
+    y = np.zeros((n, n), dtype=complex)
+    notes = [
+        "Classical flat-start: 1.0 pu pre-fault voltage, no IEC c-factor or "
+        "correction factors; loads, shunts and line charging ignored; "
+        "transformers at nominal ratio.",
+    ]
+
+    open_lines, open_trafos = _open_switches(net)
+
+    # --- Series branches: lines -------------------------------------------
+    for idx, ln in net.line.iterrows():
+        if not ln["in_service"] or idx in open_lines:
+            continue
+        f, t = int(ln["from_bus"]), int(ln["to_bus"])
+        if f not in pos or t not in pos:
+            continue
+        vn = float(net.bus.at[f, "vn_kv"])
+        par = float(ln.get("parallel", 1) or 1)
+        z_ohm = complex(ln["r_ohm_per_km"], ln["x_ohm_per_km"]) * ln["length_km"] / par
+        z_pu = z_ohm * S_BASE_MVA / vn**2
+        _add_branch(y, pos[f], pos[t], z_pu, f"line {idx}")
+
+    # --- Series branches: two-winding transformers ------------------------
+    for idx, tr in net.trafo.iterrows():
+        if not tr["in_service"] or idx in open_trafos:
+            continue
+        hv, lv = int(tr["hv_bus"]), int(tr["lv_bus"])
+        if hv not in pos or lv not in pos:
+            continue
+        zk = tr["vk_percent"] / 100.0
+        rk = tr["vkr_percent"] / 100.0
+        if zk <= 0 or rk < 0 or rk > zk:
+            raise InputError(f"Transformer {idx} has invalid vk_percent/vkr_percent.")
+        xk = math.sqrt(zk**2 - rk**2)
+        par = float(tr.get("parallel", 1) or 1)
+        z_pu = complex(rk, xk) * (S_BASE_MVA / tr["sn_mva"]) / par
+        _add_branch(y, pos[hv], pos[lv], z_pu, f"transformer {idx}")
+
+    # --- Sources: external grids ------------------------------------------
+    n_sources = 0
+    for idx, eg in net.ext_grid.iterrows():
+        if not eg["in_service"]:
+            continue
+        b = int(eg["bus"])
+        s_sc = eg.get("s_sc_max_mva", np.nan)
+        rx = eg.get("rx_max", np.nan)
+        if not _is_pos(s_sc) or not _is_nonneg(rx):
+            raise InputError(
+                f"External grid {idx} needs s_sc_max_mva and rx_max for the "
+                "classical method."
+            )
+        z_mag = S_BASE_MVA / s_sc
+        x = z_mag / math.sqrt(1 + rx**2)
+        _add_shunt(y, pos[b], complex(rx * x, x), f"external grid {idx}")
+        n_sources += 1
+
+    # --- Sources: synchronous generators -----------------------------------
+    for idx, g in net.gen.iterrows():
+        if not g["in_service"]:
+            continue
+        b = int(g["bus"])
+        xdss, sn = g.get("xdss_pu", np.nan), g.get("sn_mva", np.nan)
+        if not _is_pos(xdss) or not _is_pos(sn):
+            raise InputError(
+                f"Generator {idx} needs xdss_pu and sn_mva (sub-transient data) "
+                "for the classical method."
+            )
+        vn = float(net.bus.at[b, "vn_kv"])
+        rdss_ohm = g.get("rdss_ohm", 0.0)
+        r_pu = 0.0 if not _is_nonneg(rdss_ohm) else rdss_ohm * S_BASE_MVA / vn**2
+        x_pu = xdss * S_BASE_MVA / sn
+        _add_shunt(y, pos[b], complex(r_pu, x_pu), f"generator {idx}")
+        n_sources += 1
+
+    if n_sources == 0:
+        raise InputError("The network has no in-service external grid or generator.")
+
+    try:
+        z_bus = np.linalg.inv(y)
+    except np.linalg.LinAlgError:
+        raise InputError(
+            "The network matrix could not be inverted. Part of the network is "
+            "probably isolated from every source."
+        ) from None
+
+    if isolated:
+        notes.append(f"{len(isolated)} bus(es) have no path to any source and were "
+                     "excluded: " + ", ".join(str(b) for b in isolated[:20])
+                     + (" ..." if len(isolated) > 20 else "") + ".")
+    values = {}
+    for b in bus_list:
+        if b in isolated:
+            if skip_isolated:
+                continue
+            raise InputError(f"Bus {b} has no path to any source (isolated part of the network).")
+        if b not in pos:
+            raise InputError(f"Bus {b} is out of service.")
+        z_th = abs(z_bus[pos[b], pos[b]])
+        if not math.isfinite(z_th) or z_th <= 0:
+            raise InputError(f"Bus {b} has no valid path to a source.")
+        values[b] = S_BASE_MVA / z_th
+    return values, notes
+
+
+# ---------------------------------------------------------------------------
+
+def connected_to_source(net, live: set[int]) -> set[int]:
+    """Buses connected (through in-service lines/transformers) to a grid source or generator."""
+    open_lines, open_trafos = _open_switches(net, allow_bus_bus=True)
+    adj: dict[int, set[int]] = {b: set() for b in live}
+
+    def link(a, b):
+        if a in adj and b in adj:
+            adj[a].add(b)
+            adj[b].add(a)
+
+    for idx, ln in net.line.iterrows():
+        if ln["in_service"] and idx not in open_lines:
+            link(int(ln["from_bus"]), int(ln["to_bus"]))
+    for idx, tr in net.trafo.iterrows():
+        if tr["in_service"] and idx not in open_trafos:
+            link(int(tr["hv_bus"]), int(tr["lv_bus"]))
+    if "trafo3w" in net and len(net.trafo3w):
+        for _, t3 in net.trafo3w.iterrows():
+            if t3["in_service"]:
+                link(int(t3["hv_bus"]), int(t3["mv_bus"]))
+                link(int(t3["hv_bus"]), int(t3["lv_bus"]))
+    if "impedance" in net and len(net.impedance):
+        for _, im in net.impedance.iterrows():
+            if im["in_service"]:
+                link(int(im["from_bus"]), int(im["to_bus"]))
+    if "switch" in net and len(net.switch):
+        for _, sw in net.switch.iterrows():
+            if sw["et"] == "b" and sw["closed"]:
+                link(int(sw["bus"]), int(sw["element"]))
+
+    stack = []
+    for table in ("ext_grid", "gen"):
+        if table in net and len(net[table]):
+            stack += [int(b) for b in net[table].loc[net[table]["in_service"], "bus"] if int(b) in adj]
+    seen = set(stack)
+    while stack:
+        b = stack.pop()
+        for n in adj[b]:
+            if n not in seen:
+                seen.add(n)
+                stack.append(n)
+    return seen
+
+
+def _add_branch(y, i, j, z_pu, label):
+    if abs(z_pu) == 0:
+        raise InputError(f"{label} has zero impedance; merge the buses instead.")
+    adm = 1.0 / z_pu
+    y[i, i] += adm
+    y[j, j] += adm
+    y[i, j] -= adm
+    y[j, i] -= adm
+
+
+def _add_shunt(y, i, z_pu, label):
+    if abs(z_pu) == 0:
+        raise InputError(f"{label} has zero impedance.")
+    y[i, i] += 1.0 / z_pu
+
+
+def _open_switches(net, allow_bus_bus: bool = False):
+    """Lines and transformers disconnected by an open switch."""
+    open_lines, open_trafos = set(), set()
+    if "switch" not in net or len(net.switch) == 0:
+        return open_lines, open_trafos
+    for _, sw in net.switch.iterrows():
+        if sw["et"] == "b" and sw["closed"] and not allow_bus_bus:
+            raise InputError(
+                "Closed bus-bus switches are not supported by the classical "
+                "method in v0.1. Merge those buses in the model."
+            )
+        if not sw["closed"]:
+            if sw["et"] == "l":
+                open_lines.add(int(sw["element"]))
+            elif sw["et"] == "t":
+                open_trafos.add(int(sw["element"]))
+    return open_lines, open_trafos
+
+
+def _check_supported(net):
+    for table in UNSUPPORTED_TABLES:
+        if table in net and len(net[table]) > 0 and "in_service" in net[table]:
+            if bool(net[table]["in_service"].any()):
+                raise InputError(
+                    f"The network contains in-service '{table}' elements, which "
+                    "the classical method does not model in v0.1."
+                )
+
+
+def _is_pos(v) -> bool:
+    try:
+        return v is not None and math.isfinite(float(v)) and float(v) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _is_nonneg(v) -> bool:
+    try:
+        return v is not None and math.isfinite(float(v)) and float(v) >= 0
+    except (TypeError, ValueError):
+        return False