GitHub

Networks

A BalancedNetwork is a positive sequence network. Its tables and scalars are properties.

net = parse("case118.m").value

net.name                       # "case118"
net.base_mva                   # 100.0
net.base_frequency             # 60.0

net.buses                      # 118-element Elements{Bus}
net.branches                   # Elements{Branch}
net.generators                 # Elements{Generator}
net.loads                      # Elements{Load}
net.shunts                     # Elements{Shunt}
net.static_var_compensators
net.storage
net.switches
net.hvdc
net.transformers_3w            # Elements{ThreeWindingTransformer}
net.areas

Each table is an Elements vector, so length, 1-based indexing, iteration, filter, collect, and broadcasting work as on any Julia vector. Every index reads one element from the C library and returns an immutable struct, so if you will read a table many times, collect(net.buses) copies it out once.

length(net.buses)
net.buses[1].vm_pu
[b.id for b in net.buses if b.bus_type == "REF"]
filter(br -> br.in_service && br.tap_ratio != 0, net.branches)
sum(g.active_power_max_mw for g in net.generators)

Element structs

Field names follow the C view names in powerio.h, with units in the name: vm_pu, va_degrees, base_kv, resistance_pu, active_power_mw, reactive_power_mvar. An optional field is nothing when the source does not give it.

  • Bus: id (the source bus number), bus_type ("PQ", "PV", "REF", "ISOLATED"), voltage and limits, area, zone, name, location.
  • Branch: from_bus_id, to_bus_id, series impedance, total and per terminal charging, ratings A, B, C and further named ratings, tap_ratio (the source value; 0 means 1) and effective_tap_ratio, phase_shift_degrees, angle limits, in_service, transformer control, geographic route.
  • Generator: dispatch, limits, voltage_setpoint_pu, machine_base_mva, cost, regulated_bus_id, capabilities, active_power_control.
  • Load and Shunt: one row per element at bus_id; several can share a bus. Shunt.control contains the switched shunt blocks.
  • StaticVarCompensator, Storage, Switch, Hvdc, ThreeWindingTransformer (with windings and pairwise impedances), Area.

Bus references in every table are source bus ids rather than positions. When you need positions, build the map once:

row = Dict(b.id => k for (k, b) in enumerate(net.buses))
from = [row[br.from_bus_id] for br in net.branches]

An element's component_id is its own identifier, and ComponentId("load", load.component_id) is how an update refers to it.

Dense tables

to_dense returns the tables as dense arrays for code that wants columns: bus_ids, per branch from, to, r, x, b, tap, shift, per generator pg, pmax, and per bus demand and shunt sums. to_graph returns the bus graph as buses and edges. reference_bus_ids lists the "REF" buses.

Detailed connectivity

Node breaker formats (XIIDM, CGMES) have substations, voltage levels, terminals, switches, and operational limits beyond the bus branch tables. net.detailed_connectivity is nothing for a bus branch source and a DetailedConnectivity otherwise; its counts property lists the table lengths and each of its 28 tables reads typed records. See Detailed connectivity.

PowerIO.BalancedNetwork — Type
BalancedNetwork

A positive sequence network: buses, branches, generators, loads, shunts, and the other balanced element tables. Read the tables through properties: net.buses, net.branches, net.generators, net.loads, net.shunts, net.static_var_compensators, net.storage, net.switches, net.hvdc, net.transformers_3w, net.areas. Scalars: net.name, net.base_mva, net.base_frequency, net.geo, net.detailed_connectivity.

source
PowerIO.Elements — Type
Elements{T,N} <: AbstractVector{T}

The elements of one network table. length, 1-based indexing, iteration, filter, collect, and broadcasting all work; each index fills one C view and converts it to an immutable element struct.

source
PowerIO.Bus — Type
Bus

One balanced bus. id is the source bus number; bus_type is "PQ", "PV", "REF", or "ISOLATED"; voltages are per unit and degrees.

source
PowerIO.Branch — Type
Branch

One balanced branch or two winding transformer between from_bus_id and to_bus_id. Impedances and charging are per unit on the system base; total_charging_susceptance_pu is the whole line charging and the four terminal terms give its split; tap_ratio is the source value (0 means 1) and effective_tap_ratio the value in effect; phase_shift_degrees, the angle limits, ratings A, B, C in MVA, further named ratings, optional current_ratings (A, B, C in amperes), the transformer control, and the geographic route.

source
PowerIO.Generator — Type
Generator

One balanced generator at bus_id: dispatch, limits, voltage setpoint, machine base, service status, cost, the regulated_bus_id when it differs from the connection bus, capabilities, active_power_control, and the voltage regulation state.

source
PowerIO.Load — Type
Load

One balanced load at bus_id: p_mw, q_mvar, in_service, and its voltage_model.

source
PowerIO.Shunt — Type
Shunt

One balanced shunt at bus_id: conductance_mw and susceptance_mvar at nominal voltage, in_service, the section_count when stated, and the switched shunt control when present.

source
PowerIO.Switch — Type
Switch

One balanced transmission switch between from_bus_id and to_bus_id.

source
PowerIO.ThreeWindingTransformer — Type
ThreeWindingTransformer

One balanced three winding transformer: its windings, pairwise impedances, star point voltage, magnetizing branch, and service status.

source
PowerIO.Location — Type
Location(x, y, kind)

One point in the network coordinate space. kind names the point kind when the source states one.

source
PowerIO.Geo — Type
Geo

Coordinate metadata of a network: the coordinate space, its crs and kind when stated, and the canvas size (canvas_width, canvas_height, canvas_units) for display coordinates.

source
PowerIO.ComponentId — Type
ComponentId(component_type, local_id)

Stable identity of one component: its structural type ("bus", "load", "generator", "branch", "switch", ...) and its local identity. An element's component_id field is the local identity, so ComponentId("load", load.component_id) names that load in an update.

source
PowerIO.LoadVoltageModel — Type
LoadVoltageModel

Voltage dependence of one load: kind names the model; the constant power, constant current, and constant impedance shares and the exponential terms follow the C view field for field.

source
PowerIO.ShuntControl — Type
ShuntControl

Switched shunt control: mode, the voltage band vmax_pu and vmin_pu, the controlled bus_id when it differs from the shunt's bus, the reactive range percent, and the switchable blocks.

source
PowerIO.GeneratorCost — Type
GeneratorCost

One MATPOWER style cost curve: model (1 piecewise linear, 2 polynomial), startup and shutdown costs, ncost, and the coefficients.

source
PowerIO.GeneratorCapability — Type
GeneratorCapability(name, value)

One optional generator capability or ramp field; value is nothing when the source leaves it unset.

source
PowerIO.DetailedConnectivity — Type
DetailedConnectivity

Source neutral detailed connectivity retained from node breaker formats such as XIIDM and CGMES. dc.counts is a NamedTuple of table lengths, and each of the 28 tables is a property returning an Elements vector of the matching record:

details = parse("grid.xiidm").value.detailed_connectivity

details.counts.voltage_levels       # 3
details.substations[1].country      # "US"
details.switches[1].endpoint1.kind  # "node"
[t.equipment for t in details.terminals]
source
PowerIO.reference_bus_ids — Function
reference_bus_ids(net::BalancedNetwork) -> Vector{Int}

The ids of the buses whose type is "REF", in table order.

source
PowerIO.to_dense — Function
to_dense(net::BalancedNetwork) -> NamedTuple
to_dense(m::PioModule{BalancedNetwork}) -> NamedTuple

The balanced tables as dense arrays. Fields:

  • n, m, ng, ns: bus, branch, generator, and switch counts.
  • base_mva: system base.
  • bus_ids::Vector{Int}: source bus ids in table order; row k of every per bus table is bus bus_ids[k].
  • branch: from, to (bus ids), r, x, b (per unit; b is the total charging), g_fr, b_fr, g_to, b_to (terminal split), tap (source value, 0 means 1), shift (degrees), in_service::Vector{Bool}.
  • gen: bus, pg, qg, pmax, pmin, qmax, qmin (MW and MVAr), vg (per unit), mbase (MVA), in_service.
  • demand, shunt: per bus sums of in-service loads (pd, qd) and shunts (gs, bs), in MW and MVAr at nominal voltage.
  • reference_bus: the 1-based row of the single "REF" bus, or nothing when there is none or several.
  • switch: from, to, closed::Vector{Bool}, thermal_rating, current_rating, pf, qf, pt, qt (absent optionals are 0.0).
source
PowerIO.to_graph — Function
to_graph(net::BalancedNetwork) -> NamedTuple
to_graph(net::MulticonductorNetwork) -> NamedTuple

The bus graph of a network. buses lists every bus with its id, 1-based index in the bus table, and for balanced networks its kind and name. edges lists the connections that carry power: in-service branches for a balanced network; lines, closed switches, and transformer winding pairs for a multiconductor network. Each edge has a kind, its 1-based index in the source table, and from and to bus ids. Parallel elements stay separate edges.

source

Geographic data

bus.location provides x/y coordinates, and net.geo names their coordinate space. Balanced branches and multiconductor lines expose optional route points. Geographic layers covers the coordinate documents kept beside a case and how their coordinates reach a network.