Grid Component Modeling

Note

This document is about components not explicitly supported by PGM that can still be modeled using PGM components. For documentation on the components supported by PGM, please refer to Components.

The power grid consists of many different component types and the list is ever-increasing. As a result, it would be an impossible task to make the list of components supported by PGM exhaustive. Moreover, many grid component types share electrical attributes, so that one such grid component may be modeled as another. This document contains a non-exhaustive list of such modeling examples. New contributions and ideas for modeling grid components are very welcome!

Ideal transformer

An ideal transformer can be modeled as a link. To this end, it is explicitly allowed to place a link between two different voltage levels. Trivially, no additional electrical parameters need to be specified.

Note

The transformer component as provided by the PGM models a real transformer in the grid, i.e., with finite impedance. This directly conflicts with the properties of an ideal transformer, so the PGM transformer cannot be used to model ideal transformers.

Grounding transformer

A grounding transformer (a.k.a. earthing transformer) can be modeled as a shunt with only zero-sequence parameters (and positive-sequence parameters set to \(0\)). In particular, a grounding transformer with resistance \(r\) and reactance \(x\) can be modeled as follows.

\[\begin{split} \begin{aligned} g_1 &= 0 \\ b_1 &= 0 \\ g_0 &= \Re\left\{\frac{1}{r + j x}\right\} \\ b_0 &= \Im\left\{\frac{1}{r + j x}\right\} \end{aligned} \end{split}\]

Phase-shifting transformer

A phase-shifting transformer (PST) can be modeled directly with generic_branch. The complex ratio

\[ N = k \cdot e^{\mathrm{j} \theta} \]

already contains the phase shift; the series impedance (r1 and x1) and the magnetizing branch (g1 and b1) are given as input for any transformer. No dedicated PST component is needed.

Note that the angle theta must be provided explicitly by user. For transformers with tap changers, the parameters k, theta, and x1 are dynamic. They must be calculated based on the current tap position, using the voltage magnitude boost and the phase injection angle defined per tap step.

Let

\(m = \text{tap\_pos} - \text{tap\_neutral}\) be the tap position relative to the neutral position,
\(\Delta u\) be the additional voltage per tap step in per-unit of the winding voltage,
\(\psi\) be the injection angle of the additional voltage relative to the winding voltage (e.g., \(\psi = 90^{\circ}\) for pure quadrature/phase regulation).

The tap-dependent complex ratio is then

\[ \rho = 1 + m \, \Delta u \, e^{\mathrm{j} \psi} \]

so that

\[\begin{split} \begin{aligned} k_{\text{tap}} &= |\rho| = \sqrt{\left(1 + m \, \Delta u \cos\psi\right)^2 + \left(m \, \Delta u \sin\psi\right)^2} \\ \theta_{\text{tap}} &= \operatorname{atan2}\!\left(m \, \Delta u \sin\psi,\; 1 + m \, \Delta u \cos\psi\right) \end{aligned} \end{split}\]

The generic_branch input attributes k and theta follow as

\[\begin{split} \begin{aligned} k &= k_{\text{off-nominal}} \cdot k_{\text{tap}} \\ \theta &= \theta_{\text{fixed}} + \theta_{\text{tap}} \end{aligned} \end{split}\]

where \(k_{\text{off-nominal}}\) is the off-nominal ratio of the transformer at the neutral tap position and \(\theta_{\text{fixed}}\) is the fixed phase shift of the winding configuration (e.g., from the clock number).

Special case: ideal phase-shifting tap changer. Some tools (e.g., pandapower with tap_changer_type="Ideal") model tap changers that change only the phase angle, while the voltage magnitude ratio stays constant. Note that “ideal” refers to the tap changer, not to a zero-impedance transformer: the series impedance and the magnetizing branch are still modeled through r1, x1, g1, b1. In this case, k and theta reduce to

\[\begin{split} \begin{aligned} k &= k_{\text{off-nominal}} \\ \theta &= \theta_{\text{fixed}} + m \cdot \theta_{\text{step}} \end{aligned} \end{split}\]

with \(\theta_{\text{step}}\) the angle shift per tap step (equivalent to tap_step_degree in pandapower: converted to radian).

A lossless but not impedance-free PST is obtained with r1 = 0, x1 > 0, g1 = 0, b1 = 0.

Warning

An impedance-free ideal phase link cannot be represented by setting both r1 and x1 to zero. The branch model uses 1 / (r1 + j x1) for its series admittance, so zero series impedance would make the model singular.

Mapping from CGMES / ENTSO-E PST models

The ENTSO-E PST modelling document (CGMES v2.4) describes the standard PST types and their mapping to CIM classes. All of these types can be represented with generic_branch. In ENTSO-E models, the windings resistance and core magnetizing components are neglected (r1 = 0, g1 = 0, b1 = 0); consequently, the transformer is defined solely by its reactance (x1), tap ratio (k), and phase shift angle (theta). With \(m = n - n_0\) (in CIM: step − neutralStep), \(\Delta u\) = voltageStepIncrement, \(\theta_{\text{step}}\) = stepPhaseShiftIncrement and \(\psi\) = windingConnectionAngle, the per-tap values are:

CIM class	angle \(\alpha\) per tap	magnitude ratio
`PhaseTapChangerLinear`	\(\alpha = m \cdot \delta\theta_{\text{step}}\)	constant (\(k_{\text{off-nominal}}\))
`PhaseTapChangerSymmetrical`	\(\alpha = 2 \operatorname{atan}\!\left(\tfrac{m \, \Delta u}{2}\right)\)	constant (\(r = 1\))
`PhaseTapChangerAsymmetrical`	\(\alpha = \operatorname{atan2}\!\left(m \Delta u \sin\psi,\, 1 + m \Delta u \cos\psi\right)\)	\(\lvert\rho\rvert = \sqrt{(1 + m \Delta u \cos\psi)^2 + (m \Delta u \sin\psi)^2}\)
quadrature booster (\(\psi = 90^{\circ}\))	\(\alpha = \operatorname{atan}(m \, \Delta u)\)	\(\lvert\rho\rvert = \sqrt{1 + (m \, \Delta u)^2}\)
`PhaseTapChangerTabular`	\(\alpha\) = `angle` per tap (from table)	`ratio` per tap (from table)

The symmetrical phase shifter changes only the angle (\(r = 1\)); it is therefore the physical counterpart of the “ideal phase-shifting tap changer” described above.

Tap-dependent series reactance. The ENTSO-E document also specifies that the equivalent series reactance of a PST depends on the phase shift angle, exchanged in CIM via xMin (at neutral tap) and xMax (at maximum phase shift \(\alpha_{\max}\)):

\[\begin{split} \begin{aligned} \text{symmetrical:} \quad X(\alpha) &= X_{\min} + \left(X_{\max} - X_{\min}\right) \left(\frac{\sin(\alpha/2)}{\sin(\alpha_{\max}/2)}\right)^{2} \\ \text{quadrature booster:} \quad X(\alpha) &= X_{\min} + \left(X_{\max} - X_{\min}\right) \left(\frac{\tan\alpha}{\tan\alpha_{\max}}\right)^{2} \\ \text{asymmetrical:} \quad X(\alpha) &= X_{\min} + \left(X_{\max} - X_{\min}\right) \left(\frac{\tan\alpha}{\tan\alpha_{\max}} \cdot \frac{\sin\psi - \tan\alpha_{\max}\cos\psi} {\sin\psi - \tan\alpha\cos\psi}\right)^{2} \end{aligned} \end{split}\]

For generic_branch this means that a tap change on a CGMES PST in general requires recalculating three attributes: k, theta and x1. When PhaseTapChangerTabular data is available (recommended by ENTSO-E), k, theta and x1 can be taken directly from the per-tap table columns ratio, angle and x without evaluating the formulas above.

Note

Mind the direction convention: the ENTSO-E document defines the ratio as \(r = 1 / \lvert\rho\rvert\) (referenced from the opposite side). Depending on which side of the generic_branch the tap winding is located, either \(\lvert\rho\rvert\) or its reciprocal must be used for k, consistent with the fact that r1, x1, g1, b1 are referenced to the “to” side of the branch.

Warning

A fully impedance-free ideal phase link (r1 = x1 = 0) cannot be modeled, because the series admittance \(Y_{\text{series}} = 1 / (r_1 + \mathrm{j} x_1)\) would become singular.

Note

The attributes k, theta and x1 are not updatable. Changing the tap position of a phase-shifting transformer therefore requires recalculating these attributes and rebuilding the model.

Warning

Automatic tap control via the transformer tap regulator is not available for generic_branch.

A use case of generic_branch as PST can be found in Generic Branch Example.

Choke coil

A choke coil (a.k.a. reactance coil) can be modeled as a line with its shunt parameters (c1, tan1, c0, tan0) set to \(0\).

Note

A choke coil can also be modeled using a generic branch. However, at the time of writing (June 2026; see PGM issue #739), this component does not yet support zero-sequence parameters. As a result, asymmetric calculations are not supported, and this model currently only works for symmetric calculations.

Cable

A cable is equivalent to a line.

Ideal source

An ideal source (a.k.a. slack bus) can be modeled using a regular PGM source with a high sk, e.g. \(s_k = 10^{50}\,\text{VA}\).

Warning

At the time of writing, very high sk can result in unresolved infinities. The value mentioned here is a safe middle ground, as it is high enough for practical purposes but not so high that it would lead to those edge cases. For details, please refer to PGM issue #733, which is a good-first-issue and can be picked up by anyone who would like to.