Components

The attributes of components are listed in the tables in the sections below. The column names of the tables are as follows:

Base

• type name: base

The base type for all power grid components.

name	data type	unit	description	required	input	update	output
id	int32_t	-	ID of a component, the id should be unique along all components, i.e. you cannot have a node with id 5 and a line with id 5.	✔	✔	❌ (id needs to be specified in the update query, but cannot be changed)	✔
energized	int8_t	-	Indicates if a component is energized, i.e. connected to a source		❌	❌	✔

Node

• type name: node

• base: Base

node is a point in the grid. Physically a node can be a busbar, a joint, or other similar component.

name	data type	unit	description	required	input	update	output	valid values
u_rated	double	volt (V)	rated line-line voltage	✔	✔	❌	❌	> 0
u_pu	RealValueOutput	-	per-unit voltage magnitude		❌	❌	✔
u_angle	RealValueOutput	rad	voltage angle		❌	❌	✔
u	RealValueOutput	volt (V)	voltage magnitude, line-line for symmetric calculation, line-neutral for asymmetric calculation		❌	❌	✔

Branch

• type name: branch

• base: Base

branch is the abstract base type for the component which connects two different nodes. For each branch two switches are always defined at from- and to-side of the branch. In reality such switches may not exist. For example, a cable usually permanently connects two joints. In this case, the attribute from_status and to_status is always 1.

name	data type	unit	description	required	input	update	output	valid values
from_node	int32_t	-	ID of node at from-side	✔	✔	❌	❌	a valid node id
to_node	int32_t	-	ID of node at to-side	✔	✔	❌	❌	a valid node id
from_status	int8_t	-	connection status at from-side	✔	✔	✔	❌	0 or 1
to_status	int8_t	-	connection status at to-side	✔	✔	✔	❌	0 or 1
p_from	RealValueOutput	watt (W)	active power flowing into the branch at from-side		❌	❌	✔
q_from	RealValueOutput	volt-ampere-reactive (var)	reactive power flowing into the branch at from-side		❌	❌	✔
i_from	RealValueOutput	ampere (A)	current at from-side		❌	❌	✔
s_from	RealValueOutput	volt-ampere (VA)	apparent power flowing at from-side		❌	❌	✔
p_to	RealValueOutput	watt (W)	active power flowing into the branch at to-side		❌	❌	✔
q_to	RealValueOutput	volt-ampere-reactive (var)	reactive power flowing into the branch at to-side		❌	❌	✔
i_to	RealValueOutput	ampere (A)	current at to-side		❌	❌	✔
s_to	RealValueOutput	volt-ampere (VA)	apparent power flowing at to-side		❌	❌	✔
loading	double	-	relative loading of the line, 1.0 meaning 100% loaded.		❌	❌	✔

Line

• type name: ‘line’

line is a Branch with specified serial impedance and shunt admittance. A cable is also modeled as line. A line can only connect two nodes with the same rated voltage.

name	data type	unit	description	required	input	update	output	valid values
r1	double	ohm (Ω)	positive-sequence serial resistance	✔	✔	❌	❌	r1 and x1 cannot be both zero
x1	double	ohm (Ω)	positive-sequence serial reactance	✔	✔	❌	❌	r1 and x1 cannot be both zero
c1	double	farad (F)	positive-sequence shunt capacitance	✔	✔	❌	❌
tan1	double	-	positive-sequence shunt loss factor (tan𝛿)	✔	✔	❌	❌
r0	double	ohm (Ω)	zero-sequence serial resistance	✨ only for asymmetric calculations	✔	❌	❌	r0 and x0 cannot be both zero
x0	double	ohm (Ω)	zero-sequence serial reactance	✨ only for asymmetric calculations	✔	❌	❌	r0 and x0 cannot be both zero
c0	double	farad (F)	zero-sequence shunt capacitance	✨ only for asymmetric calculations	✔	❌	❌
tan0	double	-	zero-sequence shunt loss factor (tan𝛿)	✨ only for asymmetric calculations	✔	❌	❌
i_n	double	ampere (A)	rated current	✔	✔	❌	❌	> 0

Link

• type name: link

link is a Branch which usually represents a short internal cable/connection between two busbars inside a substation. It has a very high admittance (small impedance) which is set to a fixed per-unit value (equivalent to 10e6 siemens for 10kV network). Therefore, it is chosen by design that no sensors can be coupled to a link. There is no additional attribute for link.

Transformer

transformer is a Branch which connects two nodes with possibly different voltage levels.

Note

it can happen that tap_min > tap_max. In this case the winding voltage is decreased if the tap position is increased.

name	data type	unit	description	required	input	update	output	valid values
u1	double	volt (V)	rated voltage at from-side	✔	✔	❌	❌	> 0
u2	double	volt (V)	rated voltage at to-side	✔	✔	❌	❌	> 0
sn	double	volt-ampere (VA)	rated power	✔	✔	❌	❌	> 0
uk	double	-	relative short circuit voltage, 0.1 means 10%	✔	✔	❌	❌	>= pk / sn and > 0 and < 1
pk	double	watt (W)	short circuit (copper) loss	✔	✔	❌	❌	>= 0
i0	double	-	relative no-load current	✔	✔	❌	❌	>= p0 / sn and < 1
p0	double	watt (W)	no-load (iron) loss	✔	✔	❌	❌	>= 0
winding_from	WindingType	-	from-side winding type	✔	✔	❌	❌
winding_to	WindingType	-	to-side winding type	✔	✔	❌	❌
clock	int8_t	-	clock number of phase shift. Even number is not possible if one side is Y(N) winding and the other side is not Y(N) winding. Odd number is not possible, if both sides are Y(N) winding or both sides are not Y(N) winding.	✔	✔	❌	❌	>= 0 and <= 12
tap_side	BranchSide	-	side of tap changer	✔	✔	❌	❌
tap_pos	int8_t	-	current position of tap changer	✔	✔	✔	❌	(tap_min <= tap_pos <= tap_max) or (tap_min >= tap_pos >= tap_max)
tap_min	int8_t	-	position of tap changer at minimum voltage	✔	✔	❌	❌
tap_max	int8_t	-	position of tap changer at maximum voltage	✔	✔	❌	❌
tap_nom	int8_t	-	nominal position of tap changer	❌ default zero	✔	❌	❌	(tap_min <= tap_nom <= tap_max) or (tap_min >= tap_nom >= tap_max)
tap_size	double	volt (V)	size of each tap of the tap changer	✔	✔	❌	❌	>= 0
uk_min	double	-	relative short circuit voltage at minimum tap	❌ default same as uk	✔	❌	❌	>= pk_min / sn and > 0 and < 1
uk_max	double	-	relative short circuit voltage at maximum tap	❌ default same as uk	✔	❌	❌	>= pk_max / sn and > 0 and < 1
pk_min	double	watt (W)	short circuit (copper) loss at minimum tap	❌ default same as pk	✔	❌	❌	>= 0
pk_max	double	watt (W)	short circuit (copper) loss at maximum tap	❌ default same as pk	✔	❌	❌	>= 0
r_grounding_from	double	ohm (Ω)	grounding resistance at from-side, if relevant	❌ default zero	✔	❌	❌
x_grounding_from	double	ohm (Ω)	grounding reactance at from-side, if relevant	❌ default zero	✔	❌	❌
r_grounding_to	double	ohm (Ω)	grounding resistance at to-side, if relevant	❌ default zero	✔	❌	❌
x_grounding_to	double	ohm (Ω)	grounding reactance at to-side, if relevant	❌ default zero	✔	❌	❌

Branch3

• type name: branch3

• base: Base

branch3 is the abstract base type for the component which connects three different nodes. For each branch3 three switches are always defined at side 1, 2, or 3 of the branch. In reality such switches may not exist.

name	data type	unit	description	required	input	update	output	valid values
node_1	int32_t	-	ID of node at side 1	✔	✔	❌	❌	a valid node id
node_2	int32_t	-	ID of node at side 2	✔	✔	❌	❌	a valid node id
node_3	int32_t	-	ID of node at side 3	✔	✔	❌	❌	a valid node id
status_1	int8_t	-	connection status at side 1	✔	✔	✔	❌	0 or 1
status_2	int8_t	-	connection status at side 2	✔	✔	✔	❌	0 or 1
status_3	int8_t	-	connection status at side 3	✔	✔	✔	❌	0 or 1
p_1	RealValueOutput	watt (W)	active power flowing into the branch at side 1	✔	❌	❌	✔
q_1	RealValueOutput	volt-ampere-reactive (var)	reactive power flowing into the branch at side 1	✔	❌	❌	✔
i_1	RealValueOutput	ampere (A)	current at side 1	✔	❌	❌	✔
s_1	RealValueOutput	volt-ampere (VA)	apparent power flowing at side 1	✔	❌	❌	✔
p_2	RealValueOutput	watt (W)	active power flowing into the branch at side 2	✔	❌	❌	✔
q_2	RealValueOutput	volt-ampere-reactive (var)	reactive power flowing into the branch at side 2	✔	❌	❌	✔
i_2	RealValueOutput	ampere (A)	current at side 2	✔	❌	❌	✔
s_2	RealValueOutput	volt-ampere (VA)	apparent power flowing at side 2	✔	❌	❌	✔
p_3	RealValueOutput	watt (W)	active power flowing into the branch at side 3	✔	❌	❌	✔
q_3	RealValueOutput	volt-ampere-reactive (var)	reactive power flowing into the branch at side 3	✔	❌	❌	✔
i_3	RealValueOutput	ampere (A)	current at side 3	✔	❌	❌	✔
s_3	RealValueOutput	volt-ampere (VA)	apparent power flowing at side 3	✔	❌	❌	✔
loading	double	-	relative loading of the branch, 1.0 meaning 100% loaded.	✔	❌	❌	✔

Three-Winding Transformer

three_winding_transformer is a Branch3 connects three nodes with possibly different voltage levels.

Note

It can happen that tap_min > tap_max. In this case the winding voltage is decreased if the tap position is increased.

name	data type	unit	description	required	input	update	output	valid values
u1	double	volt (V)	rated voltage at side 1	✔	✔	❌	❌	> 0
u2	double	volt (V)	rated voltage at side 2	✔	✔	❌	❌	> 0
u3	double	volt (V)	rated voltage at side 3	✔	✔	❌	❌	> 0
sn_1	double	volt-ampere (VA)	rated power at side 1	✔	✔	❌	❌	> 0
sn_2	double	volt-ampere (VA)	rated power at side 2	✔	✔	❌	❌	> 0
sn_3	double	volt-ampere (VA)	rated power at side 3	✔	✔	❌	❌	> 0
uk_12	double	-	relative short circuit voltage across side 1-2, 0.1 means 10%	✔	✔	❌	❌	>= pk_12 / min(sn_1, sn_2) and > 0 and < 1
uk_13	double	-	relative short circuit voltage across side 1-3, 0.1 means 10%	✔	✔	❌	❌	>= pk_13 / min(sn_1, sn_3) and > 0 and < 1
uk_23	double	-	relative short circuit voltage across side 2-3, 0.1 means 10%	✔	✔	❌	❌	>= pk_23 / min(sn_2, sn_3) and > 0 and < 1
pk_12	double	watt (W)	short circuit (copper) loss across side 1-2	✔	✔	❌	❌	>= 0
pk_13	double	watt (W)	short circuit (copper) loss across side 1-3	✔	✔	❌	❌	>= 0
pk_23	double	watt (W)	short circuit (copper) loss across side 2-3	✔	✔	❌	❌	>= 0
i0	double	-	relative no-load current with respect to side 1	✔	✔	❌	❌	>= p0 / sn and < 1
p0	double	watt (W)	no-load (iron) loss	✔	✔	❌	❌	>= 0
winding_1	WindingType	-	side 1 winding type	✔	✔	❌	❌
winding_2	WindingType	-	side 2 winding type	✔	✔	❌	❌
winding_3	WindingType	-	side 3 winding type	✔	✔	❌	❌
clock_12	int8_t	-	clock number of phase shift across side 1-2, odd number is only allowed for Dy(n) or Y(N)d configuration.	✔	✔	❌	❌	>= 0 and <= 12
clock_13	int8_t	-	clock number of phase shift across side 1-3, odd number is only allowed for Dy(n) or Y(N)d configuration.	✔	✔	❌	❌	>= 0 and <= 12
tap_side	Branch3Side	-	side of tap changer	✔	✔	❌	❌	side_1 or side_2 or side_3
tap_pos	int8_t	-	current position of tap changer	✔	✔	✔	❌	(tap_min <= tap_pos <= tap_max) or (tap_min >= tap_pos >= tap_max)
tap_min	int8_t	-	position of tap changer at minimum voltage	✔	✔	❌	❌
tap_max	int8_t	-	position of tap changer at maximum voltage	✔	✔	❌	❌
tap_nom	int8_t	-	nominal position of tap changer	❌ default zero	✔	❌	❌	(tap_min <= tap_nom <= tap_max) or (tap_min >= tap_nom >= tap_max)
tap_size	double	volt (V)	size of each tap of the tap changer	✔	✔	❌	❌	> 0
uk_12_min	double	-	relative short circuit voltage at minimum tap, across side 1-2	❌ default same as uk_12	✔	❌	❌	>= pk_12_min / min(sn_1, sn_2) and > 0 and < 1
uk_12_max	double	-	relative short circuit voltage at maximum tap, across side 1-2	❌ default same as uk_12	✔	❌	❌	>= pk_12_max / min(sn_1, sn_2) and > 0 and < 1
pk_12_min	double	watt (W)	short circuit (copper) loss at minimum tap, across side 1-2	❌ default same as pk_12	✔	❌	❌	>= 0
pk_12_max	double	watt (W)	short circuit (copper) loss at maximum tap, across side 1-2	❌ default same as pk_12	✔	❌	❌	>= 0
uk_13_min	double	-	relative short circuit voltage at minimum tap, across side 1-3	❌ default same as uk_13	✔	❌	❌	>= pk_13_min / min(sn_1, sn_3) and > 0 and < 1
uk_13_max	double	-	relative short circuit voltage at maximum tap, across side 1-3	❌ default same as uk_13	✔	❌	❌	>= pk_13_max / min(sn_1, sn_3) and > 0 and < 1
pk_13_min	double	watt (W)	short circuit (copper) loss at minimum tap, across side 1-3	❌ default same as pk_13	✔	❌	❌	>= 0
pk_13_max	double	watt (W)	short circuit (copper) loss at maximum tap, across side 1-3	❌ default same as pk_13	✔	❌	❌	>= 0
uk_23_min	double	-	relative short circuit voltage at minimum tap, across side 2-3	❌ default same as uk_23	✔	❌	❌	>= pk_23_min / min(sn_2, sn_3) and > 0 and < 1
uk_23_max	double	-	relative short circuit voltage at maximum tap, across side 2-3	❌ default same as uk_23	✔	❌	❌	>= pk_23_max / min(sn_2, sn_3) and > 0 and < 1
pk_23_min	double	watt (W)	short circuit (copper) loss at minimum tap, across side 2-3	❌ default same as pk_23	✔	❌	❌	>= 0
pk_23_max	double	watt (W)	short circuit (copper) loss at maximum tap, across side 2-3	❌ default same as pk_23	✔	❌	❌	>= 0
r_grounding_1	double	ohm (Ω)	grounding resistance at side 1, if relevant	❌ default zero	✔	❌	❌
x_grounding_1	double	ohm (Ω)	grounding reactance at side 1, if relevant	❌ default zero	✔	❌	❌
r_grounding_2	double	ohm (Ω)	grounding resistance at side 2, if relevant	❌ default zero	✔	❌	❌
x_grounding_2	double	ohm (Ω)	grounding reactance at side 2, if relevant	❌ default zero	✔	❌	❌
r_grounding_3	double	ohm (Ω)	grounding resistance at side 3, if relevant	❌ default zero	✔	❌	❌
x_grounding_3	double	ohm (Ω)	grounding reactance at side 3, if relevant	❌ default zero	✔	❌	❌

Appliance

• type name: appliance

• base: Base

appliance is an abstract user which is coupled to a node. For each appliance a switch is defined between the appliance and the node. The reference direction for power flows is mentioned in Reference Direction.

name	data type	unit	description	required	input	update	output	valid values
node	int32_t	-	ID of the coupled node	✔	✔	❌	❌	a valid node id
status	int8_t	-	connection status to the node	✔	✔	✔	❌	0 or 1
p	RealValueOutput	watt (W)	active power		❌	❌	✔
q	RealValueOutput	volt-ampere-reactive (var)	reactive power		❌	❌	✔
i	RealValueOutput	ampere (A)	current		❌	❌	✔
s	RealValueOutput	volt-ampere (VA)	apparent power		❌	❌	✔
pf	RealValueOutput	-	power factor		❌	❌	✔

Source

• type name: source

• Reference Direction: generator

source is an Appliance representing the external network with a Thévenin’s equivalence. It has an infinite voltage source with an internal impedance. The impedance is specified by convention as short circuit power.

name	data type	unit	description	required	input	update	output	valid values
u_ref	double	-	reference voltage in per-unit	✨ only for power flow	✔	✔	❌	> 0
u_ref_angle	double	rad	reference voltage angle	❌ default 0.0	✔	✔	❌
sk	double	volt-ampere (VA)	short circuit power	❌ default 1e10	✔	❌	❌	> 0
rx_ratio	double	-	R to X ratio	❌ default 0.1	✔	❌	❌	>= 0
z01_ratio	double	-	zero sequence to positive sequence impedance ratio	❌ default 1.0	✔	❌	❌	> 0

Generic Load and Generator

• type name: generic_load_gen

generic_load_gen is an abstract load/generation Appliance which contains only the type of the load/generation with response to voltage.

name	data type	unit	description	required	input	update	output
type	LoadGenType	-	type of load/generator with response to voltage	✔	✔	❌	❌

Load/Generator Concrete Types

There are four concrete types of load/generator. They share similar attributes: specified active/reactive power. However, the reference direction and meaning of RealValueInput is different, as shown in the table below.

type name	reference direction	meaning of RealValueInput
sym_load	load	double
sym_gen	generator	double
asym_load	load	double[3]
asym_gen	generator	double[3]

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output
p_specified	RealValueInput	watt (W)	specified active power	✨ only for power flow	✔	✔	❌
q_specified	RealValueInput	volt-ampere-reactive (var)	specified reactive power	✨ only for power flow	✔	✔	❌

Shunt

• type name: shunt

• Reference Direction: load

shunt is an Appliance with a fixed admittance (impedance). It behaves similar to a load/generator with type const_impedance.

name	data type	unit	description	required	input	update	output
g1	double	siemens (S)	positive-sequence shunt conductance	✔	✔	❌	❌
b1	double	siemens (S)	positive-sequence shunt susceptance	✔	✔	❌	❌
g0	double	siemens (S)	zero-sequence shunt conductance	✨ only for asymmetric calculation	✔	❌	❌
b0	double	siemens (S)	zero-sequence shunt susceptance	✨ only for asymmetric calculation	✔	❌	❌

Sensor

• type name: sensor

• base: Base

sensor is an abstract type for all the sensor types. A sensor does not have any physical meaning. Rather, it provides measurement data for the state estimation algorithm. The state estimator uses the data to evaluate the state of the grid with the highest probability.

name	data type	unit	description	required	input	update	output	valid values
measured_object	int32_t	-	id of the measured object	✔	✔	❌	❌	a valid object id

Generic Voltage Sensor

• type name: generic_voltage_sensor

generic_voltage_sensor is an abstract class for symmetric and asymmetric voltage sensor and derived from Sensor. It measures the magnitude and (optionally) the angle of the voltage of a node.

name	data type	unit	description	required	input	update	output	valid values
u_sigma	double	volt (V)	standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3.	✨ only for state estimation	✔	✔	❌	> 0

Voltage Sensor Concrete Types

There are two concrete types of voltage sensor. They share similar attributes: the meaning of RealValueInput is different, as shown in the table below. In a sym_voltage_sensor the measured voltage is a line-to-line voltage. In a asym_voltage_sensor the measured voltage is a 3-phase line-to-ground voltage.

type name	meaning of RealValueInput
sym_voltage_sensor	double
asym_voltage_sensor	double[3]

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output	valid values
u_measured	RealValueInput	volt (V)	measured voltage magnitude	✨ only for state estimation	✔	✔	❌	> 0
u_angle_measured	RealValueInput	rad	measured voltage angle (only possible with phasor measurement units)	❌	✔	✔	❌
u_residual	RealValueOutput	volt (V)	residual value between measured voltage magnitude and calculated voltage magnitude		❌	❌	✔
u_angle_residual	RealValueOutput	rad	residual value between measured voltage angle and calculated voltage angle (only possible with phasor measurement units)		❌	❌	✔

Generic Power Sensor

• type name: generic_power_sensor

power_sensor is an abstract class for symmetric and asymmetric power sensor and is derived from Sensor. It measures the active/reactive power flow of a terminal. The terminal is either connecting an appliance and a node, or connecting the from/to end of a branch (except link) and a node. In case of a terminal between an appliance and a node, the power Reference Direction in the measurement data is the same as the reference direction of the appliance. For example, if a power_sensor is measuring a source, a positive p_measured indicates that the active power flows from the source to the node.

Note: due to the high admittance of a link it is chosen that a power sensor cannot be coupled to a link, even though a link is a branch

name	data type	unit	description	required	input	update	output	valid values
measured_terminal_type	MeasuredTerminalType	-	indicate if it measures an appliance or a branch	✔	✔	❌	❌	the terminal type should match the measured_object
power_sigma	double	volt-ampere (VA)	standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3.	✨ only for state estimation	✔	✔	❌	> 0

Power Sensor Concrete Types

There are two concrete types of power sensor. They share similar attributes: the meaning of RealValueInput is different, as shown in the table below.

type name	meaning of RealValueInput
sym_power_sensor	double
asym_power_sensor	double[3]

The table below shows a list of attributes.

name	data type	unit	description	required	input	update	output
p_measured	RealValueInput	watt (W)	measured active power	✨ only for state estimation	✔	✔	❌
q_measured	RealValueInput	volt-ampere-reactive (var)	measured reactive power	✨ only for state estimation	✔	✔	❌
p_residual	RealValueOutput	watt (W)	residual value between measured active power and calculated active power		❌	❌	✔
q_residual	RealValueOutput	volt-ampere-reactive (var)	residual value between measured reactive power and calculated reactive power		❌	❌	✔