Module network 

Format-neutral network model: the hub every converter meets at.

Readers map their format into a Network; writers map a Network back out. It is the one canonical data model: format-neutral tables with loads and shunts first-class, so a format that carries several loads per bus (PSS/E, PowerModels) maps without losing them, while MATPOWER (which folds demand and shunts onto the bus row) splits them out on read. The dense-indexed analysis view the matrix builders consume is IndexedNetwork, derived from a Network. Two things make conversion honest:

• Retained source. A Network keeps the raw text it was read from plus its SourceFormat, so writing back to the same format echoes it byte-for-byte (no round-trip drift).
• Extras passthrough. Every element carries an Extras map of source-format fields the neutral model doesn’t name, so X→Network→X keeps them and a cross-format writer can pass through what its target understands.

Fully lossless any-to-any isn’t possible (formats model different things); the guarantee is byte-exact same-format and maximal-fidelity cross-format with the writer reporting whatever it can’t represent.

Structs

Area

An area record: the area’s scheduled net interchange and its swing bus.

Branch

BranchCharging

Per terminal branch shunt admittance in p.u. This is the canonical physical branch shunt model when present.

BranchCurrentRatings

Current limits for a branch, in source units.

BranchRatingSet

Extra branch MVA rating set beyond the canonical A/B/C columns.

BranchSolution

Solved branch terminal flows in MW/MVAr.

Bus

BusId

A bus identifier as it appears in the source file: the external, stable id (1-based in MATPOWER, and possibly sparse; pegase has gaps in its ids). Distinct from the dense [0, n) analysis index, which only IndexedNetwork produces, via bus_index. The two are both integers and trivially confused; making the id its own type stops one being used where the other is meant (using a 1-based id to index a matrix is off-by-one on a contiguous case and pure garbage on a sparse one).

Diagnostic

A value-domain finding from Network::validate_values: an element field whose value falls outside its physical range, paired with the value repair would set in its place.

GenCost

A generator cost curve (mpc.gencost row).

Generator

Hvdc

A two-terminal HVDC line (MATPOWER dcline).

Impedance

A series impedance with the MVA base it is expressed on. Used pairwise by Transformer3W; a self-contained unit so the base travels with the value instead of being implied by position.

Load

Network

A format-neutral power network.

Shunt

ShuntBlock

One block of a switched shunt: steps equal increments of susceptance b.

SolverParams

Solver / solution-control metadata: the Newton tolerance and iteration cap, the zero-impedance threshold, and the per-quantity adjustment-enable flags.

Storage

Switch

A transmission switch. Closed switches are preserved as data; matrix builders do not lower them into zero impedance branches.

SwitchedShuntControl

Switching-control data for a switched shunt (Shunt::control): the mode, the regulated voltage band and bus, the reactive-range percentage, and the adjustable susceptance blocks. The shunt’s b is the initial value within the blocks’ total range.

Transformer3W

A three-winding transformer: three terminal buses joined at a common star point, with the series impedance given pairwise (winding 1-2, 2-3, 3-1).

TransformerControl

Automatic-control data for a regulating transformer (Branch::control).

Winding

One winding of a Transformer3W: its terminal bus, off-nominal ratio, phase shift, nominal voltage, and thermal ratings.

Enums

BusType

Bus type per MATPOWER convention: 1=PQ, 2=PV, 3=ref/slack, 4=isolated.

LoadVoltageModel

Voltage dependence for a transmission load.

SourceFormat

Which format a Network was read from. Drives the same format byte exact echo on write.

SwitchedShuntMode

How a switched shunt adjusts its susceptance. Maps to the PSS/E MODSW code.

TransformerControlMode

What a regulating transformer’s tap (or phase shift) automatically controls. Maps to the PSS/E control code COD and the PSLF transformer type.

Constants

DEFAULT_BASE_FREQUENCY

System base frequency in hertz when a format records none. Power networks run at 50 or 60 Hz; 60 is the default for the formats (MATPOWER, PowerModels, egret) that carry no frequency field.

Type Aliases

BalancedNetwork

v1-facing name for the canonical scalar positive sequence model.

Extras

Source-format fields the neutral model doesn’t name, kept for round-trip and cross-format passthrough. Keys are the field names; values are JSON scalars.

GenCaps

A generator’s capability / ramp columns, one slot per GEN_EXTRA_KEYS name.