CGMES Import

Sparlectra reads ENTSO-E CGMES 2.4.15 deliveries (Common Grid Model Exchange Standard) and builds a bus-branch Net that solves with runpf!. The importer reports everything it skips and validates against the delivery's own solved state.

Quick start

using Sparlectra

# 1. Diagnose first: works on incomplete or broken deliveries
summary = summarizeCGMES(path = ["grid_EQ_SSH_TP_SV.zip", "boundary.zip"])
show(stdout, MIME"text/plain"(), summary)

# 2. Import (Net only)
net = createNetFromCGMES(path = ["grid.zip", "boundary.zip"])

# 3. Import with full result: Net, store, topology, short-circuit data, notices
result = importCGMES(path = ["grid.zip", "boundary.zip"])
runpf!(result.net, 30, 1e-8, 0)

# 4. Validate against the delivery's own SV profile
cmp = compareWithSV(result)
@show cmp.max_dvm cmp.max_dva

path accepts a folder, a single ZIP, or a vector of either; nested ZIPs are opened in memory. importCGMES also takes a store already loaded with loadCGMES and leaves it unchanged. Profiles are classified from the md:Model header. result.element_by_mrid maps the mRID of every imported object to the element it became (kind and index).

What is imported

Everything else is counted in the coverage report; summarizeCGMES shows the full class histogram. Short-circuit source data is harvested on every import (read, not evaluated); shortCircuitCoverage reports its per-attribute completeness, printed in cgmes.log (Short-Circuit Compendium). The record of a SynchronousMachine on a WindGeneratingUnit or SolarGeneratingUnit names that class (converter_unit) and carries GeneratingUnit.maxOperatingP: the short circuit takes such a machine as a converter current source, short_circuit.converter_current_factor times the rated current from ratedS, else from maxOperatingP. A class with terminals or with SSH active power of which no object reached the network (for example EnergySource with map_energy_source off, or PowerElectronicsConnection with map_power_electronics off) gets one class not mapped: row in the import messages and in cgmes.log, with its object count and its SSH P sum; a class without SSH active power has no P sum. One header line above the rows states the sign convention: load sign, positive means flow out of the node.

Not counted as missing are the objects the topology consumes: BusbarSection, Junction, and every switch (Switch, Breaker, Disconnector, LoadBreakSwitch, Jumper, ProtectedSwitch, Fuse, GroundDisconnector, Cut, DisconnectingCircuitBreaker) that is open, disconnected or inside one TopologicalNode. A closed switch between two nodes is a bus link for the first six classes; for the others the coupling is missing and the class gets a row. Out-of-service or disconnected objects of a class the importer maps are skipped on purpose and do not count.

Conventions

Asymmetric EquivalentBranch

EquivalentBranch.r21 and x21 are the impedance seen from terminal 2. With $z_{12} = r + jx$ and $z_{21} = r_{21} + jx_{21}$ the object is the two-port

\[I_1 = \frac{V_1 - V_2}{z_{12}}, \qquad I_2 = \frac{V_2 - V_1}{z_{21}},\]

the reading that fits the SvPowerFlow of real deliveries best. Its admittance matrix is not symmetric. The importer builds such an object as a transformer branch with ratio 1 and the phase stamp

\[\varphi = \tfrac{1}{2}\arg\frac{z_{21}}{z_{12}}, \quad c = \frac{1}{z_{12}}\sqrt{\frac{|z_{12}|}{|z_{21}|}}, \quad z_s = \frac{e^{j\varphi}}{c}, \quad y_{0f} = c\,(1 - e^{-j\varphi}), \quad y_{0t} = c\,e^{-j\varphi}(e^{-j\varphi} - 1),\]

with the phase shift $\varphi$, the series impedance $z_s$ and the shunt arms $y_{0f}$, $y_{0t}$, both impedances on the base of terminal 1 (across two voltage levels with per-unit ratio 1). $|z_s|$ is the geometric mean $\sqrt{|z_{12}||z_{21}|}$, and the arms make both row sums of the two-port zero: $Y_{11} = -Y_{12} = c$, $Y_{22} = -Y_{21} = c\,e^{-2j\varphi}$. For $|z_{21}| = |z_{12}|$ (a pure rotation) this is the two-port exactly. A branch always has $|Y_{12}| = |Y_{21}|$, so otherwise each entry is off in magnitude by $\sqrt{|z_{21}|/|z_{12}|}$ or its inverse. The stamped branch gets no tap changer and no controller.

An EquivalentBranch is a network equivalent, not equipment: a negative r or x, normal in Ward and Kron reductions, is taken over unchanged. The same holds for a leg of a three-winding transformer in its star equivalent: a single leg of a real unit can have a negative r or x, only the sum of two legs is physical. The CGMES and MATPOWER exports and the short circuit accept both; the check for a negative series resistance applies to lines and two-winding transformers.

Limit: the error per branch is of the order $|V_1 - V_2| \cdot \delta / |z|$ with $\delta = \left||z_{21}|/|z_{12}| - 1\right|$, up to 1.7 % in the real deliveries checked so far. It scales with the voltage difference, like the branch flow. A stamp that keeps $Y_{11}$, $Y_{12}$, $Y_{22}$ exact puts the whole error on $Y_{21}$, where it acts on the whole voltage $V_1$ and is of the order of the short-circuit current; on a test delivery with $\delta = 1\,\%$ that moved the solved voltages by 0.069 pu instead of 0.0002 pu. The import notice counts the stamped objects, the ones with $|z_{21}| \ne |z_{12}|$ and the largest $\delta$. The model symmetrizes the magnitudes, but the delivered r, x, r21, x21 stay with the branch (Net.equivalent_branch_metadata), and the export writes them unchanged (CGMES Export).

Node-breaker deliveries without a TP profile

Some EMS and substation-level exports ship EQ+SSH only, topology as ConnectivityNodes plus switches. The importer then derives the bus partition itself.

• Trigger. Only when the delivery contains ConnectivityNodes and no non-boundary TopologicalNode; a TP-carrying delivery is unaffected.
• Aggregation. Connectivity nodes merge across closed, non-retained switches (Switch, Breaker, Disconnector, LoadBreakSwitch, Jumper, ProtectedSwitch); a switch counts as open when SSH Switch.open says so (overriding EQ normalOpen) or when it is out of service. Retained switches become zero-impedance bus links.
• Result. Each connectivity group becomes a synthetic TopologicalNode, named after a busbar section in the group where one exists; the nominal voltage resolves through VoltageLevel (hopping over Bay containers) to the BaseVoltage. Boundary connectivity nodes adopt the boundary set's TP_BD nodes, so cross-border stitching works as with a shipped TP.
• Visibility. The import messages announce the processor (topology processor: derived N topological node(s) from M connectivity node(s) ...); without that message the shipped TP was used. A delivery with neither a TP profile nor connectivity nodes aborts with the import analysis.

On MiniGrid and SmallGrid the derived partition reproduces the shipped TP bus for bus. FullGrid's TP assigns the terminals of one connectivity node (the shared load node of BE-Load_1/BE_CL_1/BE_NC_1) to two topological nodes, which no processor can derive from the graph, so 10 MW of load sit one bus apart; dead network fragments may be partitioned differently than the sender's TP and show up as extra isolated, de-energized buses.

Configuration (cgmes_import)

The keys that steer a CGMES import: where the delivery is, the system base, whether unresolved boundary references fail the import, and the per-element handling described below. The Web UI carries the ones a delivery is usually adjusted with.

Implausible voltage setpoints

A voltage RegulatingControl.targetValue outside the vset_min_pu/vset_max_pu band is treated as a placeholder (see the table); some deliveries park units with targets such as 0.001 kV. Real targets in the tested deliveries span 0.92 … 1.15 p.u. Widen the band if a delivery legitimately regulates outside it, or set vset_min_pu: 0.0 with a large vset_max_pu to accept every value.

Placeholder guards: shunt admittances and tap corrections

Two guards catch filler values such as FullGrid's X.99 attributes; cgmes_import.placeholder_guards: strict aborts with an error naming the object instead of skipping.

• a shunt whose admittance exceeds 10 × baseMVA at nominal voltage is skipped (not clamped) with a warning:;
• a single tap correction factor outside 0.5 … 2.0 is ignored with a warning:; the transformer keeps its nominal ratio.

With the guards FullGrid solves from a flat start; its shipped SV profile is internally inconsistent, so the SV start and comparison are meaningless there.

Machine Q limits: the ReactiveCapabilityCurve is Q(P), not Q(U)

A ReactiveCapabilityCurve gives reactive limits as a function of active power: the CurveData x axis is the machine's own P in the CGMES machine convention (it may span both signs), y1/y2 are the Q limits there. The importer evaluates the curve once, at the scheduled SSH P (linear interpolation, clamped to the curve's P domain), passes the pair through the same sign-convention hull as the scalar minQ/maxQ, and stores the result as ordinary Q limits. Priority: curve, then scalar hull, then a wide symmetric fallback when the scalars are the degenerate 0/0 pair. An EquivalentInjection follows the same order without the fallback: it has no rating to derive one from, so without a usable pair it keeps no Q limits. A machine may carry both a Q(U) characteristic (Voltage Dependent Control) and curve-derived limits. Under distributed slack the λ_P correction shifts machine P; the curve limits stay at the SSH operating point.

EnergySource

Some deliveries carry generation as EnergySource instead of SynchronousMachine. With cgmes_import.map_energy_source: true every EnergySource that is in service, has a connected terminal and sits on a TopologicalNode becomes a fixed PQ injection with p = -activePower and q = -reactivePower from the SSH. CGMES states both in load sign convention (positive means flow out of the node into the source), like SvPowerFlow at the source's terminal, so a consistent delivery reproduces p = -SvPowerFlow.p. The injection has no voltage regulation and no Q limits, and the importer's slack choice passes it over. It is addressed as :generator in element_by_mrid, and compareWithSV counts it with the units of its bus.

A mapped EnergySource with P > 0 (injecting) is a source, so an island it feeds stays energized (with the key off the same island is de-energized as sourceless). In an island whose only infeed is EnergySource the importer makes the largest one the slack, by the rule for islands without a reference, with a warning; that source's P then follows the island balance instead of the SSH value. With multi_slack: false such an island has no slack after the import: the island-wise solve (power_flow.islands) makes its strongest EnergySource the island reference, with power_flow.islands.enabled: false the solve rejects the island, and the import names each such island in a notice.

The key is off by default, because it changes the imported network of every delivery that carries such objects. Off, they stay out of the network and are listed in skipped_equipment; one notice in the import messages (and in cgmes.log) names the key that maps them, and their count and P sum stand in the table of classes not mapped. On, one notice counts the mapped and skipped objects with the P and Q sums. A delivery whose generation sits in EnergySource objects reproduces its SV state only with the key on.

PowerElectronicsConnection

CGMES 3.0 models wind and solar parks and batteries behind a converter as PowerElectronicsConnection, with PowerElectronicsUnits (BatteryUnit, PhotoVoltaicUnit, PowerElectronicsWindUnit) behind it. With cgmes_import.map_power_electronics: true every connection that is in service, has a connected terminal and sits on a TopologicalNode is mapped. The injection is p = -p and q = -q from the SSH, which uses the load sign like EnergySource.

• With controlEnabled and a voltage RegulatingControl that is enabled and has a target above zero, the connection regulates like a SynchronousMachine: PV at its bus on the target. A target outside vset_min_pu/vset_max_pu holds it PV at its bus voltage with a warning. A target at another bus holds it PV at its own bus, or with machine_control = true gives it an outer-loop controller.
• No target, a target of zero or below, controlEnabled = false, a disabled control or a control in another mode leave a fixed PQ injection.
• Q limits come from the minQ/maxQ hull of the machines. A regulating connection without them gets ±max(ratedS, baseMVA) with a notice.
• P limits are the sums of minP and maxP over its units.
• It is addressed as :generator in element_by_mrid, and compareWithSV counts it with the units of its bus. The importer's slack choice passes it over. An island whose only infeed are such PQ injections is treated like an EnergySource island: the largest one becomes its slack, with multi_slack: false the island gets the same notice.
• In the short circuit the connection is a current source of maxIFault (per unit of the rated current) times ratedS/(√3·ratedU), in the maximum case only. Without maxIFault or ratedS it feeds nothing and flags its island, so Ik''max there is a lower bound (see Short Circuit). maxIFault is a CIM17 attribute that no CGMES 3.0 profile defines, so a conforming delivery has none and its connections take the flag, unless short_circuit.converter_current_factor sets a multiple of the rated current for them.
• The CGMES export (2.4.15) writes it as an EquivalentInjection with its regulation and IdentifiedObject.description = PowerElectronicsConnection; an EquivalentInjection with that description imports with the converter type again, so the short circuit flags its island (see CGMES Export).

The key is off by default, like map_energy_source. Off, the connections stay out of the network and are listed in skipped_equipment; one notice names the key that maps them, and their count and P sum stand in the table of classes not mapped. On, one notice counts the mapped, regulating and skipped connections with their P and Q sums.

Out-of-service equipment (Equipment.inService)

CGMES 3.0 carries the operational status on the equipment itself in the SSH profile; 2.4.15 only has Terminal.connected. The importer treats inService = false as out of service for every mapped class: injections, loads and shunts are skipped, branches go out of service, switches count as open, each skip reported. The ignore_connected override revives such equipment.

HVDC

The importer never maps the DC side (DCLineSegment, DCNode); each converter station is a fixed injection at its AC connection point, and areas joined only through HVDC stay separate islands. Model ladder, pairing controller and the reason there is no angle coupling: HVDC Back-to-Back. Three delivery patterns:

• Explicit converters (VsConverter, CsConverter): fixed injections with the SSH operating point (p, q); the setpoint difference between the two stations of a link is the DC loss.
• Ends without an SSH power: a DC-voltage-controlling end may carry ACDCConverter.p = 0 in the SSH (its power is a result in CIM, not a setpoint); with targetUdc > 0 it gets its power from the opposite end, reduced by both converters' idleLoss, with a message. A classic LCC link with CsConverter.targetIdc (pPccControl = dcCurrent) on one end and ACDCConverter.targetUdc (pPccControl = dcVoltage) on the other gets their product as the DC power, CsConverter.operatingMode saying which end draws (rectifier) and which delivers (inverter); the DC line resistance is not applied. A pair with neither target is reported as not recoverable.
• DC border crossings in assembled multi-area models: a boundary node whose equivalent-injection pair does not cancel is such a crossing (a cancelling pair declares the same AC exchange twice and is discarded); the node is split per side, each area keeping its tie line and its equivalent on its own bus. Side identity comes from the defining file (CIMObject.source), so the split needs separate files per area; a CGM merged into a single file loses the criterion, the split silently does not apply, and the crossing stays galvanically joined.

Tap control

With tap_control = true the importer starts from the SSH tap positions and attaches outer-loop controllers for every tap changer whose controlEnabled and TapChangerControl.enabled flags are set: voltage control on ratio tap changers, active-power control on phase shifters, also on three-winding transformers. The run then goes through run_sparlectra instead of a plain runpf!. A voltage controller whose target bus is held by a generator (slack or PV) is disabled with a notice; CGMES target deadbands are often wide, so a controller may settle one step away from the recorded position.

Every tap changer, regulated or not and with or without tap_control, gives its branch the tap range, the ratios of its RatioTapChangerTable and the impedance per step. A controller added later through the control section then steps on the delivered table; the solve itself uses the imported tap position.

Bank regulators

With shunt_control = true every mapped LinearShuntCompensator with SSH controlEnabled = true and an enabled voltage RegulatingControl at its own bus becomes a switched bank: a ShuntVoltageControl in discrete mode that takes over the imported shunt (addShuntVoltageControl! with shunt_idx).

A bank stays a fixed shunt, with a notice, when its target lies at another bus, its target lies outside the vset_min_pu/vset_max_pu band, it has a conductance per section, its bus is held by a generator, or the bus has a bank regulator already. A NonlinearShuntCompensator with a regulating control stays fixed too, as its blocks are not uniform. One notice counts the regulators and the banks kept fixed. With the default false every bank stays at its SSH sections.

Machine remote voltage control

With machine_control = true a machine whose voltage RegulatingControl terminal sits at a foreign bus is imported as a PQ injection with the SSH operating point and gets a MachineVoltageControl that moves its reactive output within the imported Q limits until the remote bus reaches the target. A machine with controlEnabled = false gets no controller and stays PQ. By default, and when the target bus is already voltage-held (PV/slack), isolated, not part of the built network or claimed by another machine controller (one per target bus), the machine is held PV at its own bus with a notice in result.messages. The same holds when its regulation is the only source of its island (no slack, no PV bus, no unit with P > 0, for example a pump): only units with infeed are slack candidates, so the island gets no slack from the importer, and the machine is held PV at its own bus at its start voltage. The target value passes through the vset_min_pu/vset_max_pu band against the remote bus's nominal voltage.

Validation against the SV profile

compareWithSV(result) compares the solved state with the delivery's SV profile:

• Voltages: per-bus Δvm/Δva against SvVoltage, with max and RMS. Angles are only defined up to one constant per island, so the comparison removes the median offset per island (dva_aligned drives max_dva/rms_dva) and reports it as va_ref_offset_deg (cgmes.log, run metadata, Web UI summary row); the raw dva column stays in sv_compare.csv.
• Flows (.flows): per-terminal comparison against SvPowerFlow in the CGMES sign convention (branch terminals, shunts at the solved voltage, loads as an SSH-SV consistency check, units aggregated per group of buses joined by closed switches, since a switch carries power the balance of a single bus does not see). The ENTSO-E conformity sets only ship injection terminals.
• Tap steps: a two-winding transformer whose SvPowerFlow at both terminals fits another tap step clearly better than its SvTapStep (mismatch at most a tenth and at least 1 MVA smaller, at the SV voltages) was solved with a step the delivery does not state. The import counts such tap changers in one notice in result.messages and lists them in result.sv_tap_step_fits with both steps and mismatches; the fixed-reference self-check lists them in self_check.log.

De-energized and isolated buses are excluded, except a bus that a closed switch joins to a bus with a branch. examples/run_cgmes_suite.jl sweeps every cached or fetchable test set.

Limitations

• CGMES 3.0 deliveries are read (dcat:Dataset headers, per-border boundary files, SSH Equipment.inService), validated against the ReliCapGrid/Svedala 3.0 sets only. These sets carry no PowerElectronicsConnection; its mapping is tested on connections added in memory.
• Node-breaker deliveries are imported at bus-branch granularity (shipped TP, or the topology processor); switches do not become model elements (retained ones become bus links).
• Multi-valued references: ref() reads the first occurrence of a repeated property, refsAll the full list; the import emits one notice per affected class/property (typically TopologicalIsland.TopologicalNodes). No mapped path consumes a list-valued reference.
• An EquivalentBranch with $|z_{21}| \ne |z_{12}|$ is not reproduced exactly: the branch model has $|Y_{12}| = |Y_{21}|$, so it is built with the geometric mean of the two magnitudes (Asymmetric EquivalentBranch).
• Difference models (dm:DifferenceModel) are skipped with a report line.