Detailed connectivity
Node breaker formats such as XIIDM and CGMES describe a network through substations, voltage levels, connectivity nodes, terminals, and switches. The bus branch tables on BalancedNetwork are the solved view of that description. DetailedConnectivity keeps the description itself, so a reader can see which terminal of which equipment attached to which node, and a writer can emit the source structure back.
net.detailed_connectivity is nothing for a bus branch source such as MATPOWER, and a DetailedConnectivity for a source that carries the detail.
net = parse("grid.xiidm").value
details = net.detailed_connectivity
details.counts # a NamedTuple of all 28 table lengths
details.counts.voltage_levels # 3
length(details.terminals) # 3
details.substations[1].country # "US"Each table is an Elements vector, exactly like a balanced network table: length, 1-based indexing, iteration, filter, collect, and broadcasting work, and every index reads one row from the C library and returns an immutable record.
[l.nominal_voltage_kv for l in details.voltage_levels]
filter(t -> t.connected, details.terminals)
collect(details.switches)The tables
propertynames(details) is :counts followed by the 28 tables in the order details.counts reports them.
| Table | Record | Holds |
|---|---|---|
omitted_fields | OmittedField | fields the source left unstated |
component_metadata | ComponentMetadata | names, aliases, external identifiers, properties |
subnetworks | Subnetwork | the parts of a merged network |
substations | Substation | country, operator, geographical tags |
voltage_levels | VoltageLevel | nominal voltage, limits, topology kind |
bus_breaker_buses | BusBreakerBus | configured buses of bus breaker levels |
calculated_buses | CalculatedBus | buses the source computed from closed switches |
connectivity_nodes | ConnectivityNode | nodes of node breaker levels |
busbar_sections | BusbarSection | busbar sections at nodes |
junctions | Junction | CIM junctions |
terminals | DetailedTerminal | AC terminals of equipment |
switches | TopologySwitch | node breaker switches |
internal_connections | InternalConnection | permanent node to node links |
operational_limit_groups | OperationalLimitGroup | current, active power, apparent power limits |
tap_changers | TapChanger | transformer tap changers and their steps |
equipment_reactive_limits | EquipmentReactiveLimits | reactive limits beyond the balanced bounds |
boundary_lines | BoundaryLine | half lines ending at a boundary |
tie_lines | TieLine | pairings of two boundary lines |
dc_converter_units | DcConverterUnit | converter groupings |
dc_topological_nodes, dc_nodes | DcNode | the DC topology |
dc_grounds, dc_busbars, dc_lines, dc_series_devices, dc_switches | DcEquipment | DC equipment |
voltage_source_converters, line_commutated_converters | AcDcConverter | AC/DC converter stations |
One record per view
The C ABI fills one view struct for each group of related tables, and the Julia records follow it, so several tables share a record type. Python's DetailedConnectivity splits the same rows across one dictionary type per table.
DcEquipmentservesdc_grounds,dc_busbars,dc_lines,dc_series_devices, anddc_switches. Itskindnames the table the row came from, and only the fields that kind uses are filled: a line statesresistance_ohm, a switch statesswitch_kindandopen.DcNodeservesdc_topological_nodesanddc_nodes, withkinddistinguishing a calculated topological node from a physical one.AcDcConverterservesvoltage_source_convertersandline_commutated_converters, withkindnaming the technology. A voltage source converter statesvoltage_setpoint_kvandreactive_limits, a line commutated converter the alpha and gamma firing angles. The C ABI reads reactive limit properties and capability points for voltage source converters only, so a line commutated converter'sreactive_limitscarries itskindand bounds with emptypropertiesandpoints.
details.dc_lines[1].kind # "line"
details.dc_lines[1].terminals[1].dc_node
details.voltage_source_converters[1].kind # "voltage_source"Nested tables
Rows the C ABI reads through a second accessor are materialized into the record, so one row is a complete value: a Substation carries its geographical_tags, a TapChanger its steps, a ReactiveLimits its points, an AcDcConverter its droop_curve.
group = details.operational_limit_groups[1]
group.apparent_power_limits.permanent_limit # 90.0
group.apparent_power_limits.temporary_limits[1].name # "emergency"
changer = details.tap_changers[1]
changer.winding # 2
changer.steps[1].ratio_pu # 1.05
limits = details.equipment_reactive_limits[1].limits
limits.kind # "capability_curve"
limits.points[1].maximum_reactive_power_mvarAn optional field is nothing when the source does not state it, so a tap changer whose source declares steps without assigning one has tap_position === nothing while low_tap_position still reads. An AcDcConverter distinguishes an absent droop curve (nothing) from an empty one (an empty vector).
TopologySwitch is the node breaker switch of this table. Switch remains the balanced transmission switch between two buses.
PowerIO.OmittedField — Type
OmittedField(component, field)One field the source representation did not state for component. field is the PowerIO field name, such as "voltage_setpoint".
PowerIO.ComponentMetadata — Type
ComponentMetadataIdentity metadata of one component: its display name, the equipment_container that holds it, whether the source marks it fictitious, its aliases and external_identifiers, and its string properties.
PowerIO.ComponentAlias — Type
ComponentAlias(value, alias_type)One alternative identifier of a component. alias_type names the alias scheme when the source states one.
PowerIO.ExternalIdentifier — Type
ExternalIdentifier(value, authority)One identifier a component carries from outside the source model. authority names the issuing authority when the source states one.
PowerIO.Subnetwork — Type
SubnetworkOne subnetwork of a merged network: its own identity, its parent network, the case_metadata it was merged with, and the identities of the components it contributes.
PowerIO.CaseMetadata — Type
CaseMetadataProvenance of one subnetwork: the case_date as the source wrote it, the forecast_distance in minutes, the source_model_format, and the minimum_validation_level the source declares.
PowerIO.Substation — Type
SubstationOne substation: its country and operator_name when stated, and its geographical_tags.
PowerIO.VoltageLevel — Type
VoltageLevelOne voltage level inside a substation. topology_kind is "bus_breaker" or "node_breaker", and buses lists the source bus numbers of the balanced buses assigned to this level.
PowerIO.BusBreakerBus — Type
BusBreakerBusOne configured bus of a bus breaker voltage level. calculated_bus_id names the calculated bus it merged into when the source solved the topology.
PowerIO.CalculatedBus — Type
CalculatedBusOne bus the source computed by merging closed switches. nodes are the connectivity nodes it covers.
PowerIO.ConnectivityNode — Type
ConnectivityNodeOne node of a node breaker voltage level. node_number is the number the source gave it inside its voltage level.
PowerIO.BusbarSection — Type
BusbarSection(component, voltage_level, node)One busbar section attached to a node of a node breaker voltage level.
PowerIO.Junction — Type
Junction(component)One CIM junction retained from the source.
PowerIO.DetailedTerminal — Type
DetailedTerminalOne AC terminal of a piece of equipment. terminal numbers the terminal on its equipment from 1. bus, connectable_bus, and node name the topology the terminal attaches to, and connected states whether it is in service.
PowerIO.TopologySwitch — Type
TopologySwitchOne switch of the detailed topology, between endpoint1 and endpoint2. kind is the source switch kind, such as "breaker" or "disconnector"; retained marks a switch the source keeps when it merges buses.
Switch is the balanced transmission switch table; this is the node breaker switch the detailed topology retains.
PowerIO.TopologyEndpoint — Type
TopologyEndpoint(kind, component)One end of a topology switch. kind is "bus" or "node" and names what component identifies.
PowerIO.InternalConnection — Type
InternalConnection(voltage_level, node1, node2)One permanent connection between two nodes of a node breaker voltage level.
PowerIO.OperationalLimitGroup — Type
OperationalLimitGroupOne named group of operational limits on a numbered terminal of one piece of equipment. selected marks the group in effect. Each of current_limits, active_power_limits, and apparent_power_limits is nothing unless the source states that quantity.
PowerIO.LoadingLimits — Type
LoadingLimitsThe limits of one quantity in an operational limit group: the permanent_limit and its name, and the temporary_limits ordered as the source wrote them. Currents are amperes, active power megawatts, apparent power megavolt amperes.
PowerIO.TemporaryLimit — Type
TemporaryLimitOne temporary limit: the value that applies for acceptable_duration_seconds after the permanent limit is exceeded.
PowerIO.TapChanger — Type
TapChangerOne tap changer of a transformer. winding numbers the winding it acts on from 1, kind is "ratio" or "phase", and steps are its positions. tap_position is nothing when the source declares the steps without assigning one.
PowerIO.TapChangerStep — Type
TapChangerStepOne step of a tap changer: its position, the voltage ratio_pu and phase_shift_degrees it applies, and the four percent deviations it applies to the transformer impedance and magnetizing branch.
PowerIO.EquipmentReactiveLimits — Type
EquipmentReactiveLimits(equipment, limits)The ReactiveLimits the source stated for one piece of equipment, retained beyond the balanced generator bounds.
PowerIO.ReactiveLimits — Type
ReactiveLimitsReactive power limits of one machine. kind is "min_max" or "capability_curve": a min max record fills the two bounds and leaves points empty, a capability curve fills points and leaves the bounds nothing.
PowerIO.ReactiveCapabilityCurvePoint — Type
ReactiveCapabilityCurvePointOne point of a reactive capability curve: the reactive power band available at active_power_mw, with the string properties the source attached to it.
PowerIO.BoundaryLine — Type
BoundaryLineOne boundary line: a half line whose far end is a boundary rather than a bus. Setpoints are the boundary injection, impedances are ohms and siemens at the voltage level, pairing_key matches the line against its other half, and calculation_load and calculation_generator name the balanced elements the boundary injection became.
PowerIO.BoundaryLineGeneration — Type
BoundaryLineGenerationThe generation attached to the open end of a boundary line: its regulation state, active power range and targets, and its reactive_limits.
PowerIO.TieLine — Type
TieLineOne tie line: the pairing of two boundary lines, and the balanced branch the pair became when stated.
PowerIO.DcConverterUnit — Type
DcConverterUnit(component, substation, operation_mode)One DC converter unit: the converters of one pole or bipole, grouped.
PowerIO.DcNode — Type
DcNodeOne node of the DC topology. kind distinguishes a physical node from a calculated topological node; dc_topological_node names the topological node a physical node merged into.
PowerIO.DcEquipment — Type
DcEquipmentOne piece of DC equipment. kind names the table the row came from ("ground", "busbar", "line", "series_device", "switch"), and only the fields that kind uses are filled: a line states resistance_ohm and length_km, a switch states switch_kind and open. terminals holds the one or two terminals the equipment connects through.
PowerIO.DcTerminal — Type
DcTerminalOne terminal of a piece of DC equipment. polarity is the source polarity token, and the flow fields carry the solved values when the source states them.
PowerIO.AcDcConverter — Type
AcDcConverterOne AC/DC converter station. kind names the table the row came from: "voltage_source" for a voltage source converter, "line_commutated" for a line commutated converter. Each converter fills the fields its technology uses, so a voltage source converter states voltage_setpoint_kv and reactive_limits while a line commutated converter states the alpha and gamma firing angles.
droop_curve is nothing when the source states no curve, and an empty vector when it states an empty one. The C ABI reads reactive limit properties and capability points for voltage source converters only, so a line commutated converter's reactive_limits carries its kind and bounds with empty properties and points.
PowerIO.DroopCurveSegment — Type
DroopCurveSegment(minimum_voltage_kv, maximum_voltage_kv, k)One segment of a converter DC voltage droop curve: the gain k that applies over the DC voltage band.