The attributes of components are listed in the tables in the sections below. The column names of the tables are as follows:
- type name:
base
The base type for all power grid components.
name | data type | unit | description | required | update |
---|---|---|---|---|---|
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) |
name | data type | unit | description |
---|---|---|---|
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. |
energized |
int8_t |
- | Indicates if a component is energized, i.e. connected to a source |
- type name:
node
- base: {hoverxreftooltip}
user_manual/components: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 | update | valid values |
---|---|---|---|---|---|---|
u_rated |
double |
volt (V) | rated line-line voltage | ✔ | ❌ | > 0 |
name | data type | unit | description |
---|---|---|---|
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 |
p |
RealValueOutput |
watt (W) | active power injection |
q |
RealValueOutput |
volt-ampere-reactive (var) | reactive power injection |
The `p` and `q` output of injection follows the `generator` reference direction as mentioned in
{hoverxreftooltip}`user_manual/data-model:Reference Direction`
name | data type | unit | description |
---|---|---|---|
u_pu |
RealValueOutput |
- | per-unit voltage magnitude |
u_angle |
RealValueOutput |
rad | voltage angle |
u |
RealValueOutput |
volt (V) | voltage magnitude (line-neutral) |
- type name:
branch
- base: {hoverxreftooltip}
user_manual/components: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 | update | 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 |
name | data type | unit | description |
---|---|---|---|
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. |
name | data type | unit | description |
---|---|---|---|
i_from |
RealValueOutput |
ampere (A) | current at from-side |
i_from_angle |
RealValueOutput |
rad | current angle at from-side |
i_to |
RealValueOutput |
ampere (A) | current at to-side |
i_to_angle |
RealValueOutput |
rad | current angle at to-side |
- type name:
line
line
is a {hoverxreftooltip}user_manual/components: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.
name | data type | unit | description | required | update | 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 |
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`).
line
is described by a
- type name:
link
link
is a {hoverxreftooltip}user_manual/components: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
.
link
is modeled by a constant reactance
transformer
is a {hoverxreftooltip}user_manual/components:branch
which connects two nodes with possibly different voltage
levels.
name | data type | unit | description | required | update | 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 |
{py:class}WindingType <power_grid_model.enum.WindingType> |
- | from-side winding type | ✔ | ❌ | |
winding_to |
{py:class}WindingType <power_grid_model.enum.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 |
{py:class}BranchSide <power_grid_model.enum.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 | ❌ |
It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is
increased.
transformer
is described by a
and
where to_node
.
- type name:
branch3
- base: {hoverxreftooltip}
user_manual/components: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 | update | 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 |
name | data type | unit | description |
---|---|---|---|
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. |
name | data type | unit | description |
---|---|---|---|
i_1 |
RealValueOutput |
ampere (A) | current at side 1 |
i_1_angle |
RealValueOutput |
rad | current angle at side 1 |
i_2 |
RealValueOutput |
ampere (A) | current at side 2 |
i_2_angle |
RealValueOutput |
rad | current angle at side 2 |
i_3 |
RealValueOutput |
ampere (A) | current at side 3 |
i_3_angle |
RealValueOutput |
rad | current angle at side 3 |
three_winding_transformer
is a {hoverxreftooltip}user_manual/components:branch3
connects three nodes with possibly different
voltage levels.
name | data type | unit | description | required | update | 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 |
{py:class}WindingType <power_grid_model.enum.WindingType> |
- | side 1 winding type | ✔ | ❌ | |
winding_2 |
{py:class}WindingType <power_grid_model.enum.WindingType> |
- | side 2 winding type | ✔ | ❌ | |
winding_3 |
{py:class}WindingType <power_grid_model.enum.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 |
{py:class}Branch3Side <power_grid_model.enum.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 | ❌ |
It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is
increased.
three_winding_transformer
is modelled as 3 transformers of pi
model each connected together in star configuration.
However, there are only 2 pi
"legs": One at side_1
and one in the centre of star.
The values between windings (for eg. uk_12
or pk_23
) are converted from delta to corresponding star configuration values.
The calculation of series and shunt admittance from uk
, pk
, i0
and p0
is same as mentioned in {hoverxreftooltip}user_manual/components:transformer
.
- type name:
appliance
- base: {hoverxreftooltip}
user_manual/components: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
{hoverxreftooltip}user_manual/data-model:Reference Direction
.
name | data type | unit | description | required | update | 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 |
name | data type | unit | description |
---|---|---|---|
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 |
name | data type | unit | description |
---|---|---|---|
i |
RealValueOutput |
ampere (A) | current |
i_angle |
RealValueOutput |
rad | current angle |
- type name:
source
- {hoverxreftooltip}
user_manual/data-model:Reference Direction
: generator
source
is an {hoverxreftooltip}user_manual/components: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 | update | 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 |
source
is modeled by an internal constant impedance
- for positive sequence,
where rx_ratio
as input.
- for zero sequence,
- type name:
generic_load_gen
generic_load_gen
is an abstract load/generation {hoverxreftooltip}user_manual/components:appliance
which contains only the
type of the load/generation with response to voltage.
name | data type | unit | description | required | update |
---|---|---|---|---|---|
type |
{py:class}LoadGenType <power_grid_model.enum.LoadGenType> |
- | type of load/generator with response to voltage | ✔ | ❌ |
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] |
name | data type | unit | description | required | update |
---|---|---|---|---|---|
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 | ✔ |
generic_load_gen
is modelled by using the so-called ZIP load model in power-grid-model,
where a load/generator is represented as a composition of constant power (P), constant current (I) and constant impedance (Z).
The injection of each ZIP model type can be computed as follows:
- for a constant impedance (Z) load/generator,
- for a constant current (I) load/generator,
- for a constant power (P) load/generator:,
where
- type name:
shunt
- {hoverxreftooltip}
user_manual/data-model:Reference Direction
: load
shunt
is an {hoverxreftooltip}user_manual/components:appliance
with a fixed admittance (impedance). It behaves similar to a
load/generator with type const_impedance
.
name | data type | unit | description | required | update |
---|---|---|---|---|---|
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 | ✔ |
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`).
shunt
is modelled by a fixed admittance which equals to
- type name:
sensor
- base: {hoverxreftooltip}
user_manual/components: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 | update | valid values |
---|---|---|---|---|---|---|
measured_object |
int32_t |
- | ID of the measured object | ✔ | ❌ | a valid object ID |
- type name:
generic_voltage_sensor
generic_voltage_sensor
is an abstract class for symmetric and asymmetric voltage sensor and derived from
{hoverxreftooltip}user_manual/components:sensor
. It measures the magnitude and (optionally) the angle of the voltage of
a node
.
name | data type | unit | description | required | update | 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 |
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] |
name | data type | unit | description | required | update | 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) | ❌ | ✔ |
name | data type | unit | description |
---|---|---|---|
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_voltage_sensor
is modeled by following equations:
- type name:
generic_power_sensor
power_sensor
is an abstract class for symmetric and asymmetric power sensor and is derived from
{hoverxreftooltip}user_manual/components: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 {hoverxreftooltip}user_manual/data-model: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.
1. 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`
2. 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.
name | data type | unit | description | required | update | valid values |
---|---|---|---|---|---|---|
measured_terminal_type |
{py:class}MeasuredTerminalType <power_grid_model.enum.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. See {hoverxreftooltip}user_manual/components:Power Sensor Concrete Types . |
✨ only for state estimation. | ✔ | > 0 |
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] |
name | data type | unit | description | required | update |
---|---|---|---|---|---|
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_sigma |
RealValueInput |
watt (W) | standard deviation of the active power measurement error. Usually this is the absolute measurement error range divided by 3. | ❌ see the explanation below. | ✔ |
q_sigma |
RealValueInput |
volt-ampere-reactive (var) | standard deviation of the reactive power measurement error. Usually this is the absolute measurement error range divided by 3. | ❌ see the explanation below. | ✔ |
1. If both `p_sigma` and `q_sigma` are provided, they represent the standard deviation of the active and reactive power, respectively, and the value of `power_sigma` is ignored. Any infinite component invalidates the entire measurement.
2. If neither `p_sigma` nor `q_sigma` are provided, `power_sigma` represents the standard deviation of the apparent power.
3. Providing only one of `p_sigma` and `q_sigma` results in undefined behaviour.
See the documentation on state estimation calculation methods for details per method on how the variances are taken into account for both the active and reactive power and for the individual phases.
name | data type | unit | description |
---|---|---|---|
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 |
Generic Power Sensor
is modeled by following equations:
- type name:
fault
-
- base: {hoverxreftooltip}
user_manual/components:base
- base: {hoverxreftooltip}
fault
defines a short circuit location in the grid. At this moment a fault can only happen at a node
.
name | data type | unit | description | required | update | valid values |
---|---|---|---|---|---|---|
status |
int8_t |
- | whether the fault is active | ✔ | ✔ | 0 or 1 |
fault_type |
{py:class}FaultType <power_grid_model.enum.FaultType> |
- | the type of the fault | ✨ only for short circuit | ✔ | |
fault_phase |
{py:class}FaultPhase <power_grid_model.enum.FaultPhase> |
- | the phase(s) of the fault | ❌ default FaultPhase.default_value (see below) |
✔ | |
fault_object |
int32_t |
- | ID of the component where the short circuit happens | ✔ | ✔ | A valid node ID |
r_f |
double |
ohm (Ω) | short circuit resistance | ❌ default 0.0 | ✔ | |
x_f |
double |
ohm (Ω) | short circuit reactance | ❌ default 0.0 | ✔ |
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.
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.
A fault
has no steady state output.
name | data type | unit | description |
---|---|---|---|
i_f |
RealValueOutput |
ampere (A) | current |
i_f_angle |
RealValueOutput |
rad | current angle |
Four types of short circuit fault are included in power-grid-model.
fault_type |
fault_phase |
description |
---|---|---|
FaultType.three_phase |
FaultPhase.abc |
Three phases are connected with fault impedance. |
FaultType.single_phase_to_ground |
FaultPhase.a |
One phase is grounded with fault impedance, and other phases are open. |
FaultType.two_phase |
FaultPhase.bc |
Two phases are connected with fault impedance. |
FaultType.two_phase_to_ground |
FaultPhase.bc |
Two phases are connected with fault impedance then grounded. |
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
.