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.
Input
name |
data type |
unit |
description |
required |
update |
---|---|---|---|---|---|
|
|
- |
ID of a component, the ID should be unique along all components, i.e. you cannot have a node with |
✔ |
❌ (id needs to be specified in the update query, but cannot be changed) |
Steady state output and Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
- |
ID of a component, the ID should be unique along all components, i.e. you cannot have a node with |
|
|
- |
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
volt (V) |
rated line-line voltage |
✔ |
❌ |
|
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
- |
per-unit voltage magnitude |
|
|
rad |
voltage angle |
|
|
volt (V) |
voltage magnitude, line-line for symmetric calculation, line-neutral for asymmetric calculation |
|
|
watt (W) |
active power injection |
|
|
volt-ampere-reactive (var) |
reactive power injection |
Note
The p
and q
output of injection follows the generator
reference direction as mentioned in
Reference Direction
Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
- |
per-unit voltage magnitude |
|
|
rad |
voltage angle |
|
|
volt (V) |
voltage magnitude (line-neutral) |
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
ID of node at from-side |
✔ |
❌ |
a valid node ID |
|
|
- |
ID of node at to-side |
✔ |
❌ |
a valid node ID |
|
|
- |
connection status at from-side |
✔ |
✔ |
|
|
|
- |
connection status at to-side |
✔ |
✔ |
|
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
watt (W) |
active power flowing into the branch at from-side |
|
|
volt-ampere-reactive (var) |
reactive power flowing into the branch at from-side |
|
|
ampere (A) |
current at from-side |
|
|
volt-ampere (VA) |
apparent power flowing at from-side |
|
|
watt (W) |
active power flowing into the branch at to-side |
|
|
volt-ampere-reactive (var) |
reactive power flowing into the branch at to-side |
|
|
ampere (A) |
current at to-side |
|
|
volt-ampere (VA) |
apparent power flowing at to-side |
|
|
- |
relative loading of the line, |
Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
ampere (A) |
current at from-side |
|
|
rad |
current angle at from-side |
|
|
ampere (A) |
current at to-side |
|
|
rad |
current angle at to-side |
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.
If i_n
is not provided, loading
of line will be a nan
value.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
ohm (Ω) |
positive-sequence serial resistance |
✔ |
❌ |
|
|
|
ohm (Ω) |
positive-sequence serial reactance |
✔ |
❌ |
|
|
|
farad (F) |
positive-sequence shunt capacitance |
✔ |
❌ |
|
|
|
- |
positive-sequence shunt loss factor (tan𝛿) |
✔ |
❌ |
|
|
|
ohm (Ω) |
zero-sequence serial resistance |
✨ only for asymmetric calculations |
❌ |
|
|
|
ohm (Ω) |
zero-sequence serial reactance |
✨ only for asymmetric calculations |
❌ |
|
|
|
farad (F) |
zero-sequence shunt capacitance |
✨ only for asymmetric calculations |
❌ |
|
|
|
- |
zero-sequence shunt loss factor (tan𝛿) |
✨ only for asymmetric calculations |
❌ |
|
|
|
ampere (A) |
rated current |
❌ |
❌ |
|
Note
In case of short circuit calculations, the zero-sequence parameters are required only
if any of the faults in any of the scenarios within a batch are not three-phase faults
(i.e. fault_type
is not FaultType.three_phase
).
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
volt (V) |
rated voltage at from-side |
✔ |
❌ |
|
|
|
volt (V) |
rated voltage at to-side |
✔ |
❌ |
|
|
|
volt-ampere (VA) |
rated power |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage, |
✔ |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss |
✔ |
❌ |
|
|
|
- |
relative no-load current |
✔ |
❌ |
|
|
|
watt (W) |
no-load (iron) loss |
✔ |
❌ |
|
|
- |
from-side winding type |
✔ |
❌ |
||
|
- |
to-side winding type |
✔ |
❌ |
||
|
|
- |
clock number of phase shift. |
✔ |
❌ |
|
|
- |
side of tap changer |
✔ |
❌ |
||
|
|
- |
current position of tap changer |
✔ |
✔ |
|
|
|
- |
position of tap changer at minimum voltage |
✔ |
❌ |
|
|
|
- |
position of tap changer at maximum voltage |
✔ |
❌ |
|
|
|
- |
nominal position of tap changer |
❌ default zero |
❌ |
|
|
|
volt (V) |
size of each tap of the tap changer |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage at minimum tap |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at maximum tap |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at minimum tap |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at maximum tap |
❌ default same as |
❌ |
|
|
|
ohm (Ω) |
grounding resistance at from-side, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding reactance at from-side, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding resistance at to-side, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding reactance at to-side, if relevant |
❌ default zero |
❌ |
Note
It can happen that tap_min > tap_max
. In this case the winding voltage is decreased if the tap position is
increased.
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
ID of node at side 1 |
✔ |
❌ |
a valid node ID |
|
|
- |
ID of node at side 2 |
✔ |
❌ |
a valid node ID |
|
|
- |
ID of node at side 3 |
✔ |
❌ |
a valid node ID |
|
|
- |
connection status at side 1 |
✔ |
✔ |
|
|
|
- |
connection status at side 2 |
✔ |
✔ |
|
|
|
- |
connection status at side 3 |
✔ |
✔ |
|
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
watt (W) |
active power flowing into the branch at side 1 |
|
|
volt-ampere-reactive (var) |
reactive power flowing into the branch at side 1 |
|
|
ampere (A) |
current at side 1 |
|
|
volt-ampere (VA) |
apparent power flowing at side 1 |
|
|
watt (W) |
active power flowing into the branch at side 2 |
|
|
volt-ampere-reactive (var) |
reactive power flowing into the branch at side 2 |
|
|
ampere (A) |
current at side 2 |
|
|
volt-ampere (VA) |
apparent power flowing at side 2 |
|
|
watt (W) |
active power flowing into the branch at side 3 |
|
|
volt-ampere-reactive (var) |
reactive power flowing into the branch at side 3 |
|
|
ampere (A) |
current at side 3 |
|
|
volt-ampere (VA) |
apparent power flowing at side 3 |
|
|
- |
relative loading of the branch, |
Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
ampere (A) |
current at side 1 |
|
|
rad |
current angle at side 1 |
|
|
ampere (A) |
current at side 2 |
|
|
rad |
current angle at side 2 |
|
|
ampere (A) |
current at side 3 |
|
|
rad |
current angle at side 3 |
Three-Winding Transformer
three_winding_transformer
is a Branch3 connects three nodes with possibly different
voltage levels.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
volt (V) |
rated voltage at side 1 |
✔ |
❌ |
|
|
|
volt (V) |
rated voltage at side 2 |
✔ |
❌ |
|
|
|
volt (V) |
rated voltage at side 3 |
✔ |
❌ |
|
|
|
volt-ampere (VA) |
rated power at side 1 |
✔ |
❌ |
|
|
|
volt-ampere (VA) |
rated power at side 2 |
✔ |
❌ |
|
|
|
volt-ampere (VA) |
rated power at side 3 |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage across side 1-2, |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage across side 1-3, |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage across side 2-3, |
✔ |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss across side 1-2 |
✔ |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss across side 1-3 |
✔ |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss across side 2-3 |
✔ |
❌ |
|
|
|
- |
relative no-load current with respect to side 1 |
✔ |
❌ |
|
|
|
watt (W) |
no-load (iron) loss |
✔ |
❌ |
|
|
- |
side 1 winding type |
✔ |
❌ |
||
|
- |
side 2 winding type |
✔ |
❌ |
||
|
- |
side 3 winding type |
✔ |
❌ |
||
|
|
- |
clock number of phase shift across side 1-2, odd number is only allowed for Dy(n) or Y(N)d configuration. |
✔ |
❌ |
|
|
|
- |
clock number of phase shift across side 1-3, odd number is only allowed for Dy(n) or Y(N)d configuration. |
✔ |
❌ |
|
|
- |
side of tap changer |
✔ |
❌ |
|
|
|
|
- |
current position of tap changer |
✔ |
✔ |
|
|
|
- |
position of tap changer at minimum voltage |
✔ |
❌ |
|
|
|
- |
position of tap changer at maximum voltage |
✔ |
❌ |
|
|
|
- |
nominal position of tap changer |
❌ default zero |
❌ |
|
|
|
volt (V) |
size of each tap of the tap changer |
✔ |
❌ |
|
|
|
- |
relative short circuit voltage at minimum tap, across side 1-2 |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at maximum tap, across side 1-2 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at minimum tap, across side 1-2 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at maximum tap, across side 1-2 |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at minimum tap, across side 1-3 |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at maximum tap, across side 1-3 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at minimum tap, across side 1-3 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at maximum tap, across side 1-3 |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at minimum tap, across side 2-3 |
❌ default same as |
❌ |
|
|
|
- |
relative short circuit voltage at maximum tap, across side 2-3 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at minimum tap, across side 2-3 |
❌ default same as |
❌ |
|
|
|
watt (W) |
short circuit (copper) loss at maximum tap, across side 2-3 |
❌ default same as |
❌ |
|
|
|
ohm (Ω) |
grounding resistance at side 1, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding reactance at side 1, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding resistance at side 2, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding reactance at side 2, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding resistance at side 3, if relevant |
❌ default zero |
❌ |
|
|
|
ohm (Ω) |
grounding reactance at side 3, if relevant |
❌ default zero |
❌ |
Note
It can happen that tap_min > tap_max
. In this case the winding voltage is decreased if the tap position is
increased.
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
ID of the coupled node |
✔ |
❌ |
a valid node ID |
|
|
- |
connection status to the node |
✔ |
✔ |
|
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
watt (W) |
active power |
|
|
volt-ampere-reactive (var) |
reactive power |
|
|
ampere (A) |
current |
|
|
volt-ampere (VA) |
apparent power |
|
|
- |
power factor |
Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
ampere (A) |
current |
|
|
rad |
current angle |
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
reference voltage in per-unit |
✨ only for power flow |
✔ |
|
|
|
rad |
reference voltage angle |
❌ default 0.0 |
✔ |
|
|
|
volt-ampere (VA) |
short circuit power |
❌ default 1e10 |
❌ |
|
|
|
- |
R to X ratio |
❌ default 0.1 |
❌ |
|
|
|
- |
zero sequence to positive sequence impedance ratio |
❌ default 1.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 |
update |
---|---|---|---|---|---|
|
- |
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 |
---|---|---|
|
load |
|
|
generator |
|
|
load |
|
|
generator |
|
Input
name |
data type |
unit |
description |
required |
update |
---|---|---|---|---|---|
|
|
watt (W) |
specified active power |
✨ only for power flow |
✔ |
|
|
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
.
Input
name |
data type |
unit |
description |
required |
update |
---|---|---|---|---|---|
|
|
siemens (S) |
positive-sequence shunt conductance |
✔ |
❌ |
|
|
siemens (S) |
positive-sequence shunt susceptance |
✔ |
❌ |
|
|
siemens (S) |
zero-sequence shunt conductance |
✨ only for asymmetric calculation |
❌ |
|
|
siemens (S) |
zero-sequence shunt susceptance |
✨ only for asymmetric calculation |
❌ |
Note
In case of short circuit calculations, the zero-sequence parameters are required only
if any of the faults in any of the scenarios within a batch are not three-phase faults
(i.e. fault_type
is not FaultType.three_phase
).
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.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
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
.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
volt (V) |
standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3. |
✨ only for state estimation |
✔ |
|
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 |
---|---|
|
|
|
|
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
volt (V) |
measured voltage magnitude |
✨ only for state estimation |
✔ |
|
|
|
rad |
measured voltage angle (only possible with phasor measurement units) |
❌ |
✔ |
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
volt (V) |
residual value between measured voltage magnitude and calculated voltage magnitude |
|
|
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 alink
, even though a link is abranch
The node injection power sensor gets placed on a node. In the state estimation result, the power from this injection is distributed equally among the connected appliances at that node. Because of this distribution, at least one appliance is required to be connected to the node where an injection sensor is placed for it to function.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
- |
indicate if it measures an |
✔ |
❌ |
the terminal type should match the |
|
|
|
volt-ampere (VA) |
standard deviation of the measurement error. Usually this is the absolute measurement error range divided by 3. |
✨ only for state estimation |
✔ |
|
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 |
---|---|
|
|
|
|
Input
name |
data type |
unit |
description |
required |
update |
---|---|---|---|---|---|
|
|
watt (W) |
measured active power |
✨ only for state estimation |
✔ |
|
|
volt-ampere-reactive (var) |
measured reactive power |
✨ only for state estimation |
✔ |
Steady state output
name |
data type |
unit |
description |
---|---|---|---|
|
|
watt (W) |
residual value between measured active power and calculated active power |
|
|
volt-ampere-reactive (var) |
residual value between measured reactive power and calculated reactive power |
Fault
type name:
fault
base: Base
fault
defines a short circuit location in the grid. At this moment a fault can only happen at a node
.
Input
name |
data type |
unit |
description |
required |
update |
valid values |
---|---|---|---|---|---|---|
|
|
- |
whether the fault is active |
✔ |
✔ |
|
|
- |
the type of the fault |
✨ only for short circuit |
✔ |
||
|
- |
the phase(s) of the fault |
❌ default |
✔ |
||
|
|
- |
ID of the component where the short circuit happens |
✔ |
✔ |
A valid |
|
|
ohm (Ω) |
short circuit resistance |
❌ default 0.0 |
✔ |
|
|
|
ohm (Ω) |
short circuit reactance |
❌ default 0.0 |
✔ |
Note
Multiple faults may exist within one calculation. Currently, all faults in one scenario are required to have the
same fault_type
and fault_phase
. Across scenarios in a batch, the fault_type
and fault_phase
may differ.
Note
If any of the faults in any of the scenarios within a batch are not three_phase
(i.e. fault_type
is not FaultType.three_phase
),
the calculation is treated as asymmetric.
Default values for fault_phase
In case the fault_phase
is not specified or is equal to FaultPhase.default_value
, the power-grid-model assumes the following fault phases for different values of fault_type
.
|
|
---|---|
|
|
|
|
|
|
|
|
Steady state output
A fault
has no steady state output.
Short circuit output
name |
data type |
unit |
description |
---|---|---|---|
|
|
ampere (A) |
current |
|
|
rad |
current angle |