geopulse.io.matpower

MATPOWER-GMD (.m) parser for power-grid GIC test cases.

Extracts only the GMD/DC-network-relevant sections used by PowerGridNetwork:

  • mpc.gmd_bus — DC ground nodes and grounding conductance g_gnd [S]

  • mpc.gmd_branch — DC-equivalent branches (lines, transformer windings) with per-branch resistance br_r [Ω] and length len_km [km]

  • mpc.bus_gmd — (lat, lon) per AC bus

  • mpc.bus / mpc.branch — AC-side metadata retained for downstream configuration helpers (baseKV, ratings, statuses)

This is a narrow parser — enough to load epri21.m (Horton et al. 2012) and equivalent PowerModelsGMD.jl test files. It is NOT a general MATPOWER reader; that is out of scope for GeoPulse core.

References

Notes

Row-position vs. AC bus number: the f_bus / t_bus fields inside mpc.gmd_branch reference 1-based row positions within mpc.gmd_bus, NOT AC bus numbers. Callers must respect this convention. The parent_index column on each gmd_bus row instead names the AC bus (substation) that DC node belongs to; use it for geographic lookup via mpc.bus_gmd.

Functions

read_matpower_gmd(path)

Parse a MATPOWER-GMD .m file.

Classes

MatpowerGMDCase(source_path, n_dc_nodes[, ...])

Structured contents of a MATPOWER-GMD .m file.
class geopulse.io.matpower.MatpowerGMDCase(source_path, n_dc_nodes, dc_nodes=<factory>, dc_branches=<factory>, bus_latlon=<factory>, ac_bus_kv=<factory>, ac_branches=<factory>)[source]

Bases: object

Structured contents of a MATPOWER-GMD .m file.

Parameters:
source_path

Path the case was loaded from.

Type:

pathlib.Path

n_dc_nodes

Number of DC (grounding) nodes.

Type:

int

dc_nodes

One entry per DC node, ordered by 1-based row position within mpc.gmd_bus. Fields:

  • row 1-based row index (DC node id used by branches)

  • parent_ac_bus AC bus number this DC node grounds

  • status 1 = in service, 0 = out

  • g_gnd_S grounding conductance in Siemens

  • name human name (e.g. "dc_sub1")

Type:

list of dict

dc_branches

DC branches. Fields:

  • from_row, to_row 1-based DC node row indices

  • parent_ac_branch 1-based AC branch index (or 0 for none)

  • status 1 in service, 0 out

  • resistance_Ohm DC resistance

  • length_km geographic length (km); 0 for xfmr windings

  • name human name

Type:

list of dict

bus_latlon

ac_bus_id -> (latitude_deg, longitude_deg).

Type:

dict of int -> (float, float)

ac_bus_kv

ac_bus_id -> baseKV.

Type:

dict of int -> float

ac_branches

AC-side branches, retained for case-configuration helpers (each has f, t, rateA, ratio, status).

Type:

list of dict

source_path: Path
n_dc_nodes: int
dc_nodes: list[dict]
dc_branches: list[dict]
bus_latlon: dict[int, tuple[float, float]]
ac_bus_kv: dict[int, float]
ac_branches: list[dict]
geopulse.io.matpower.read_matpower_gmd(path)[source]

Parse a MATPOWER-GMD .m file.

Parameters:

path (str | Path) – Path to the .m file.

Return type:

MatpowerGMDCase

Returns:

MatpowerGMDCase – Structured case data.

Raises:

DataError – If the file is missing required blocks (gmd_bus, gmd_branch, bus, bus_gmd) or has malformed rows.