From 036ee0b9d7a996a42e35da88df1eb35ecf5f8118 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Tue, 22 Apr 2025 11:26:11 +0200 Subject: [PATCH 1/5] reformat docs Signed-off-by: Martijn Govers --- .../native-data-interface.md | 12 +- docs/user_manual/components.md | 188 +++++++++--------- docs/user_manual/dataset-terminology.md | 34 ++-- 3 files changed, 117 insertions(+), 117 deletions(-) diff --git a/docs/advanced_documentation/native-data-interface.md b/docs/advanced_documentation/native-data-interface.md index 1c5919ba9..2a34124ae 100644 --- a/docs/advanced_documentation/native-data-interface.md +++ b/docs/advanced_documentation/native-data-interface.md @@ -115,12 +115,12 @@ The pointers are passed into C++ code so that the C++ program can write results The basic data types used in the interface between C++ and Python are shown in the table below. -| C++ type | `numpy.dtype` | null value | usage | -| --- | --- | --- | --- | -| `int32_t` | `'i4'` | - 2^31 | ids of physical components | -| `int8_t` | `'i1'` | - 2^7 | enumeration types, boolean types, and small integers (e.g. tap position of transformer) | -| `double` | `'f8'` | NaN ([IEEE 754](https://en.wikipedia.org/wiki/NaN)) | physical quantities (e.g. voltage) | -| `double[3]` | `'(3, )f8'` | NaN ([IEEE 754](https://en.wikipedia.org/wiki/NaN)) | three-phase asymmetric physical quantities (e.g. voltage) | +| C++ type | `numpy.dtype` | null value | usage | +| ----------- | ------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------- | +| `int32_t` | `'i4'` | - 2^31 | ids of physical components | +| `int8_t` | `'i1'` | - 2^7 | enumeration types, boolean types, and small integers (e.g. tap position of transformer) | +| `double` | `'f8'` | NaN ([IEEE 754](https://en.wikipedia.org/wiki/NaN)) | physical quantities (e.g. voltage) | +| `double[3]` | `'(3, )f8'` | NaN ([IEEE 754](https://en.wikipedia.org/wiki/NaN)) | three-phase asymmetric physical quantities (e.g. voltage) | *The [endianness](https://en.wikipedia.org/wiki/Endianness) of C++ and Python side is also matched. For `x86-64` platform the little endian is used, so that diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 61305ba0d..4d2617008 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -16,8 +16,8 @@ The base type for all power-grid-model components. #### Input -| name | data type | unit | description | required | update | -| ---- | --------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :----------------------------------------------------------------------------: | +| name | data type | unit | description | required | update | +| ---- | --------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------------------: | | `id` | `int32_t` | - | ID of a component. The ID should be unique across all components within the same scenario, e.g., you cannot have a node with `id=5` and another line with `id=5`. | ✔ | ❌ (see below) | If a component update is uniform and is updating all the elements with the same component type, IDs can be omitted or set to `nan`s. In any other case, the IDs need to be present in the update dataset, but cannot be changed. @@ -173,32 +173,32 @@ levels. An example of usage of transformer is given in [Transformer Examples](.. #### Input -| 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 ` | - | from-side winding type | ✔ | ❌ | | -| `winding_to` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | | -| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | -| `x_grounding_from` | `double` | ohm (Ω) | grounding reactance at from-side, if relevant | ❌ default `0` | ❌ | | -| `r_grounding_to` | `double` | ohm (Ω) | grounding resistance at to-side, if relevant | ❌ default `0` | ❌ | | -| `x_grounding_to` | `double` | ohm (Ω) | grounding reactance at to-side, if relevant | ❌ default `0` | ❌ | | +| 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 ` | - | from-side winding type | ✔ | ❌ | | +| `winding_to` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | | +| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | +| `x_grounding_from` | `double` | ohm (Ω) | grounding reactance at from-side, if relevant | ❌ default `0` | ❌ | | +| `r_grounding_to` | `double` | ohm (Ω) | grounding resistance at to-side, if relevant | ❌ default `0` | ❌ | | +| `x_grounding_to` | `double` | ohm (Ω) | grounding reactance at to-side, if relevant | ❌ default `0` | ❌ | | ```{note} It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is @@ -238,15 +238,15 @@ Here, $s_{\text{base}}$ is a constant value determined by the solver and $u_{\te #### Input -| name | data type | unit | description | required | update | valid values | -| ------- | --------- | ---------------- | ----------------------------- | :--------------------: | :------: | :-------------: | -| `r1` | `double` | ohm | positive-sequence resistance | ✔ | ❌ | | -| `x1` | `double` | ohm | positive-sequence reactance | ✔ | ❌ | | -| `g1` | `double` | siemens | positive-sequence conductance | ✔ | ❌ | | -| `b1` | `double` | siemens | positive-sequence susceptance | ✔ | ❌ | | -| `k` | `double` | - | off-nominal ratio | ❌ default `1.0` | ❌ | `> 0` | -| `theta` | `double` | radian | angle shift | ❌ default `0.0` | ❌ | | -| `sn` | `double` | volt-ampere (VA) | rated power | ❌ default `0.0` | ❌ | `>= 0` | +| name | data type | unit | description | required | update | valid values | +| ------- | --------- | ---------------- | ----------------------------- | :--------------------: | :------: | :----------: | +| `r1` | `double` | ohm | positive-sequence resistance | ✔ | ❌ | | +| `x1` | `double` | ohm | positive-sequence reactance | ✔ | ❌ | | +| `g1` | `double` | siemens | positive-sequence conductance | ✔ | ❌ | | +| `b1` | `double` | siemens | positive-sequence susceptance | ✔ | ❌ | | +| `k` | `double` | - | off-nominal ratio | ❌ default `1.0` | ❌ | `> 0` | +| `theta` | `double` | radian | angle shift | ❌ default `0.0` | ❌ | | +| `sn` | `double` | volt-ampere (VA) | rated power | ❌ default `0.0` | ❌ | `>= 0` | ```{note} The impedance (`r1`, `x1`) and admittance (`g1`, `b1`) attributes are calculated with reference to the "to" side of the branch. @@ -331,51 +331,51 @@ voltage levels. An example of usage of three-winding transformer is given in [Tr #### Input -| 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 ` | - | side 1 winding type | ✔ | ❌ | | -| `winding_2` | {py:class}`WindingType ` | - | side 2 winding type | ✔ | ❌ | | -| `winding_3` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | `side_1` or `side_2` or `side_3` | -| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | -| `x_grounding_1` | `double` | ohm (Ω) | grounding reactance at side 1, if relevant | ❌ default `0` | ❌ | | -| `r_grounding_2` | `double` | ohm (Ω) | grounding resistance at side 2, if relevant | ❌ default `0` | ❌ | | -| `x_grounding_2` | `double` | ohm (Ω) | grounding reactance at side 2, if relevant | ❌ default `0` | ❌ | | -| `r_grounding_3` | `double` | ohm (Ω) | grounding resistance at side 3, if relevant | ❌ default `0` | ❌ | | -| `x_grounding_3` | `double` | ohm (Ω) | grounding reactance at side 3, if relevant | ❌ default `0` | ❌ | +| 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 ` | - | side 1 winding type | ✔ | ❌ | | +| `winding_2` | {py:class}`WindingType ` | - | side 2 winding type | ✔ | ❌ | | +| `winding_3` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | `side_1` or `side_2` or `side_3` | +| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | +| `x_grounding_1` | `double` | ohm (Ω) | grounding reactance at side 1, if relevant | ❌ default `0` | ❌ | | +| `r_grounding_2` | `double` | ohm (Ω) | grounding resistance at side 2, if relevant | ❌ default `0` | ❌ | | +| `x_grounding_2` | `double` | ohm (Ω) | grounding reactance at side 2, if relevant | ❌ default `0` | ❌ | | +| `r_grounding_3` | `double` | ohm (Ω) | grounding resistance at side 3, if relevant | ❌ default `0` | ❌ | | +| `x_grounding_3` | `double` | ohm (Ω) | grounding reactance at side 3, if relevant | ❌ default `0` | ❌ | ```{note} It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is @@ -680,13 +680,13 @@ Valid combinations of `power_sigma`, `p_sigma` and `q_sigma` are: | `power_sigma` | `p_sigma` | `q_sigma` | result | | :-----------: | :-------: | :-------: | :------: | -| ✔ | ✔ | ✔ | ✔ | -| ✔ | ✔ | | ❌ | -| ✔ | | ✔ | ❌ | -| ✔ | | | ✔ | -| | ✔ | ✔ | ✔ | -| | ✔ | | ❌ | -| | | ✔ | ❌ | +| ✔ | ✔ | ✔ | ✔ | +| ✔ | ✔ | | ❌ | +| ✔ | | ✔ | ❌ | +| ✔ | | | ✔ | +| | ✔ | ✔ | ✔ | +| | ✔ | | ❌ | +| | | ✔ | ❌ | | | | | ❌ | ```{note} @@ -809,13 +809,13 @@ The actual grid state is not changed after calculations are done. #### Input -| name | data type | unit | description | required | update | valid values | +| name | data type | unit | description | required | update | valid values | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- | :--------------------------: | :------: | :--------------------------------------------------------------: | | `control_side` | {py:class}`BranchSide ` if the regulated object is a {hoverxreftooltip}`user_manual/components:transformer` and {py:class}`Branch3Side ` if it the regulated object is a {hoverxreftooltip}`user_manual/components:Three-Winding Transformer` | - | the controlled side of the transformer | ✨ only for power flow | ❌ | `control_side` should be the relatively further side to a source | -| `u_set` | `double` | volt (V) | the voltage setpoint (at the center of the band) | ✨ only for power flow | ✔ | `>= 0` | -| `u_band` | `double` | volt (V) | the width of the voltage band ($=2*\left(\Delta U\right)_{\text{acceptable}}$) | ✨ only for power flow | ✔ | `> 0` (see below) | -| `line_drop_compensation_r` | `double` | ohm (Ω) | compensation for voltage drop due to resistance during transport (see [below](#line-drop-compensation)) | ❌ default `0.0` | ✔ | `>= 0` | -| `line_drop_compensation_x` | `double` | ohm (Ω) | compensation for voltage drop due to reactance during transport (see [below](#line-drop-compensation)) | ❌ default `0.0` | ✔ | `>= 0` | +| `u_set` | `double` | volt (V) | the voltage setpoint (at the center of the band) | ✨ only for power flow | ✔ | `>= 0` | +| `u_band` | `double` | volt (V) | the width of the voltage band ($=2*\left(\Delta U\right)_{\text{acceptable}}$) | ✨ only for power flow | ✔ | `> 0` (see below) | +| `line_drop_compensation_r` | `double` | ohm (Ω) | compensation for voltage drop due to resistance during transport (see [below](#line-drop-compensation)) | ❌ default `0.0` | ✔ | `>= 0` | +| `line_drop_compensation_x` | `double` | ohm (Ω) | compensation for voltage drop due to reactance during transport (see [below](#line-drop-compensation)) | ❌ default `0.0` | ✔ | `>= 0` | The following additional requirements exist on the input parameters. diff --git a/docs/user_manual/dataset-terminology.md b/docs/user_manual/dataset-terminology.md index 850be114f..610de8164 100644 --- a/docs/user_manual/dataset-terminology.md +++ b/docs/user_manual/dataset-terminology.md @@ -90,12 +90,12 @@ graph TD The dimensions of numpy arrays and the interpretation of each dimension is as follows. -| **Data Type** | **1D** |**2D** | **3D** | -|--------------------------|-----------------------------------|-------------------------------------------------------|-------------------------------------------------------------------------------| -| **SingleArray** | Corresponds to a single dataset. | ❌ | ❌ | -| **DenseBatchArray** | ❌ | Batch number $\times$ Component within that batch | ❌ | -| **SingleColumn** | Component within that batch. | Component within that batch $\times$ Phases ✨ | ❌ | -| **BatchColumn** | ❌ | Batch number $\times$ Component within that batch | Batch number $\times$ Component within that batch $\times$ Phases ✨ | +| **Data Type** | **1D** | **2D** | **3D** | +| ------------------- | -------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- | +| **SingleArray** | Corresponds to a single dataset. | ❌ | ❌ | +| **DenseBatchArray** | ❌ | Batch number $\times$ Component within that batch | ❌ | +| **SingleColumn** | Component within that batch. | Component within that batch $\times$ Phases ✨ | ❌ | +| **BatchColumn** | ❌ | Batch number $\times$ Component within that batch | Batch number $\times$ Component within that batch $\times$ Phases ✨ | ```{note} ✨ The "Phases" dimension is optional and is available only when the attributes are asymmetric. @@ -145,14 +145,14 @@ Exemplary datasets attributes are given in a dataset containing a `line` compone ## Attributes of Components -| Attribute | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| name | Name of the attribute. It is exactly the same as the attribute name in `power_grid_model.power_grid_meta_data`. | -| data type | Data type of the attribute. It is either a type from the table in [Native Data Interface](../advanced_documentation/native-data-interface.md#basic-data-types), or an enumeration as defined above. There are two special data types that are independent from one another, namely, `RealValueInput` and `RealValueOutput`. | -| | `RealValueInput` is used for some input attributes. It is a `double` for a symmetric class (e.g. `sym_load`) and `double[3]` an asymmetric class (e.g. `asym_load`). It is explained in detail in the corresponding types. | -| | `RealValueOutput` is used for many output attributes. It is a `double` in symmetric calculation and `double[3]` for asymmetric and short circuit calculations. | -| unit | Unit of the attribute, if applicable. As a general rule, only standard SI units without any prefix are used. | -| description | Description of the attribute. | -| required | Whether the attribute is required. If not, then it is optional. Note if you choose not to specify an optional attribute, it should have the null value as defined in [](../advanced_documentation/native-data-interface.md#basic-data-types). | -| update | Whether the attribute can be mutated by the update call `PowerGridModel.update` on an existing instance, only applicable when this attribute is part of an input dataset. | -| valid values | Whether applicable or not; an indication of value validity for the input data. | +| Attribute | Description | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | Name of the attribute. It is exactly the same as the attribute name in `power_grid_model.power_grid_meta_data`. | +| data type | Data type of the attribute. It is either a type from the table in [Native Data Interface](../advanced_documentation/native-data-interface.md#basic-data-types), or an enumeration as defined above. There are two special data types that are independent from one another, namely, `RealValueInput` and `RealValueOutput`. | +| | `RealValueInput` is used for some input attributes. It is a `double` for a symmetric class (e.g. `sym_load`) and `double[3]` an asymmetric class (e.g. `asym_load`). It is explained in detail in the corresponding types. | +| | `RealValueOutput` is used for many output attributes. It is a `double` in symmetric calculation and `double[3]` for asymmetric and short circuit calculations. | +| unit | Unit of the attribute, if applicable. As a general rule, only standard SI units without any prefix are used. | +| description | Description of the attribute. | +| required | Whether the attribute is required. If not, then it is optional. Note if you choose not to specify an optional attribute, it should have the null value as defined in [](../advanced_documentation/native-data-interface.md#basic-data-types). | +| update | Whether the attribute can be mutated by the update call `PowerGridModel.update` on an existing instance, only applicable when this attribute is part of an input dataset. | +| valid values | Whether applicable or not; an indication of value validity for the input data. | From d5553a7c8ac035d820d974329d55c407031f382e Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Tue, 22 Apr 2025 14:36:15 +0200 Subject: [PATCH 2/5] minor Signed-off-by: Martijn Govers --- .markdownlint.yaml | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 480231ada..7c57d79ed 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -26,24 +26,3 @@ MD013: false # MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md024.md MD024: false - -# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md033.md -MD033: false - -# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md040.md -MD040: false - -# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md041.md -MD041: false - -# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md042.md -MD042: false - -# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md045.md -MD045: false - -# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md051.md -MD051: false - -# MD056/table-column-count : Table column counts should match : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md056.md -MD056: false From 167587c5162238beb6f3d347b8a8340681202461 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Tue, 22 Apr 2025 14:07:28 +0200 Subject: [PATCH 3/5] apply formatting + linting Signed-off-by: Martijn Govers --- README.md | 8 +- docs/quickstart.md | 4 +- docs/user_manual/components.md | 98 ++++++++++--------- docs/user_manual/data-model.md | 6 +- docs/user_manual/data-validator.md | 2 +- docs/user_manual/model-validation.md | 4 +- docs/user_manual/performance-guide.md | 2 +- docs/user_manual/serialization.md | 2 +- .../data/power_flow/generic_branch/README.md | 4 +- .../components/asymmetric/asym_gen/README.md | 6 +- .../components/asymmetric/asym_load/README.md | 6 +- .../components/asymmetric/line/README.md | 6 +- .../components/asymmetric/node/README.md | 6 +- .../components/asymmetric/shunt/README.md | 6 +- .../components/asymmetric/source/README.md | 6 +- .../components/asymmetric/sym_gen/README.md | 6 +- .../components/asymmetric/sym_load/README.md | 6 +- .../asymmetric/transformer/README.md | 4 +- .../components/symmetric/basic-node/README.md | 4 +- .../components/symmetric/line/README.md | 4 +- .../components/symmetric/node/README.md | 4 +- .../components/symmetric/shunt/README.md | 4 +- .../components/symmetric/source/README.md | 4 +- .../components/symmetric/sym_gen/README.md | 4 +- .../components/symmetric/sym_load/README.md | 4 +- .../three_winding_transformer/README.md | 4 +- .../symmetric/transformer/README.md | 4 +- .../asymmetric/distribution-case/README.md | 4 +- .../asymmetric/transmission-case/README.md | 4 +- .../symmetric/distribution-case/README.md | 4 +- .../symmetric/transmission-case/README.md | 4 +- .../distribution-case/README.md | 4 +- .../transmission-case/README.md | 4 +- 33 files changed, 122 insertions(+), 120 deletions(-) diff --git a/README.md b/README.md index 8af47d2ce..e02b25b01 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -[![PyPI version](https://badge.fury.io/py/power-grid-model.svg?no-cache)](https://badge.fury.io/py/power-grid-model) +[![PyPI version](https://badge.fury.io/py/power-grid-model.svg?no-cache)](https://badge.fury.io/py/power-grid-model) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/power-grid-model/badges/version.svg?no-cache)](https://anaconda.org/conda-forge/power-grid-model) [![License: MPL2.0](https://img.shields.io/badge/License-MPL2.0-informational.svg)](https://github.com/PowerGridModel/power-grid-model/blob/main/LICENSE) [![Downloads](https://static.pepy.tech/badge/power-grid-model)](https://pepy.tech/project/power-grid-model) @@ -24,7 +24,7 @@ SPDX-License-Identifier: MPL-2.0 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8054429.svg)](https://zenodo.org/record/8054429) -[![](https://github.com/PowerGridModel/.github/blob/main/artwork/svg/color.svg)](#) +[![Power Grid Model logo](https://github.com/PowerGridModel/.github/blob/main/artwork/svg/color.svg)](#) # Power Grid Model @@ -50,7 +50,7 @@ Want to be updated on the latest news and releases? Subscribe to the Power Grid You can directly install the package from PyPI. -``` +```sh pip install power-grid-model ``` @@ -58,7 +58,7 @@ pip install power-grid-model If you are using `conda`, you can directly install the package from `conda-forge` channel. -``` +```sh conda install -c conda-forge power-grid-model ``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 5ea2c4b50..64b555b4d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -10,7 +10,7 @@ In this quick start a simple 10kV network as below is calculated. A line connects two nodes. One node has a source. The other node has a symmetric load. The full code for this section is provided in {{ "[quick_example.py]({}/scripts/quick_example.py)".format(gh_link_head_blob) }}. -``` +```txt node_1 ---line_3--- node_2 | | source_5 sym_load_4 @@ -134,7 +134,7 @@ print(pd.DataFrame(result['node'])) The result data can then be viewed in tabular forms. -``` +```txt Node Input id u_rated 0 1 10500.0 diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 4d2617008..a8079ad92 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -173,32 +173,32 @@ levels. An example of usage of transformer is given in [Transformer Examples](.. #### Input -| 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 ` | - | from-side winding type | ✔ | ❌ | | -| `winding_to` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | | -| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | -| `x_grounding_from` | `double` | ohm (Ω) | grounding reactance at from-side, if relevant | ❌ default `0` | ❌ | | -| `r_grounding_to` | `double` | ohm (Ω) | grounding resistance at to-side, if relevant | ❌ default `0` | ❌ | | -| `x_grounding_to` | `double` | ohm (Ω) | grounding reactance at to-side, if relevant | ❌ default `0` | ❌ | | +| 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 ` | - | from-side winding type | ✔ | ❌ | | +| `winding_to` | {py:class}`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 ` | - | side of tap changer | ✔ | ❌ | | +| `tap_pos` | `int8_t` | - | current position of tap changer | ❌ default `tap_nom`, if no `tap_nom` default `0` | ✔ | `(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 `0` | ❌ | `(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 `0` | ❌ | | +| `x_grounding_from` | `double` | ohm (Ω) | grounding reactance at from-side, if relevant | ❌ default `0` | ❌ | | +| `r_grounding_to` | `double` | ohm (Ω) | grounding resistance at to-side, if relevant | ❌ default `0` | ❌ | | +| `x_grounding_to` | `double` | ohm (Ω) | grounding reactance at to-side, if relevant | ❌ default `0` | ❌ | | ```{note} It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is @@ -375,7 +375,7 @@ voltage levels. An example of usage of three-winding transformer is given in [Tr | `r_grounding_2` | `double` | ohm (Ω) | grounding resistance at side 2, if relevant | ❌ default `0` | ❌ | | | `x_grounding_2` | `double` | ohm (Ω) | grounding reactance at side 2, if relevant | ❌ default `0` | ❌ | | | `r_grounding_3` | `double` | ohm (Ω) | grounding resistance at side 3, if relevant | ❌ default `0` | ❌ | | -| `x_grounding_3` | `double` | ohm (Ω) | grounding reactance at side 3, if relevant | ❌ default `0` | ❌ | +| `x_grounding_3` | `double` | ohm (Ω) | grounding reactance at side 3, if relevant | ❌ default `0` | ❌ | | ```{note} It can happen that `tap_min > tap_max`. In this case the winding voltage is decreased if the tap position is @@ -669,12 +669,12 @@ the meaning of `RealValueInput` is different, as shown in the table below. ##### Input -| 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. | ✔ | `> 0` | -| `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. | ✔ | `> 0` | +| name | data type | unit | description | required | update | valid values | +| ------------ | ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------: | :------: | :----------: | +| `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. | ✔ | `> 0` | +| `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. | ✔ | `> 0` | Valid combinations of `power_sigma`, `p_sigma` and `q_sigma` are: @@ -730,14 +730,14 @@ $$ #### Input -| 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 ` | - | the type of the fault | ✨ only for short circuit | ✔ | | -| `fault_phase` | {py:class}`FaultPhase ` | - | the phase(s) of the fault | ❌ default `FaultPhase.default_value` (see [below](#default-values-for-fault_phase)) | ✔ | | -| `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` | ✔ | | +| 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 ` | - | the type of the fault | ✨ only for short circuit | ✔ | | +| `fault_phase` | {py:class}`FaultPhase ` | - | the phase(s) of the fault | ❌ default `FaultPhase.default_value` (see [below](#fault-types-and-default-values-for-fault-phase)) | ✔ | | +| `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` | ✔ | | ```{note} Multiple faults may exist within one calculation. Currently, all faults in one scenario are required to have the @@ -763,16 +763,18 @@ A `fault` has no steady state output. #### Electric Model +##### Fault types and default values for fault phase + 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 fault phases for different values of `fault_type` as specified in the table below. -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`. +| `fault_type` | Supported values of `FaultPhase` | `FaultPhase.default_value` | description | +| ---------------------------------- | ------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------- | +| `FaultType.three_phase` | `FaultPhase.abc` | `FaultPhase.abc` | Three phases are connected with fault impedance. | +| `FaultType.single_phase_to_ground` | `FaultPhase.a`, `FaultPhase.b`, `FaultPhase.c` | `FaultPhase.a` | One phase is grounded with fault impedance, and other phases are open. | +| `FaultType.two_phase` | `FaultPhase.bc`, `FaultPhase.ac`, `FaultPhase.ab` | `FaultPhase.bc` | Two phases are connected with fault impedance. | +| `FaultType.two_phase_to_ground` | `FaultPhase.bc`, `FaultPhase.ac`, `FaultPhase.ab` | `FaultPhase.bc` | Two phases are connected with fault impedance then grounded. | ## Regulator diff --git a/docs/user_manual/data-model.md b/docs/user_manual/data-model.md index edf42359e..207bcafce 100644 --- a/docs/user_manual/data-model.md +++ b/docs/user_manual/data-model.md @@ -4,12 +4,12 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project +# Component Type Hierarchy and Graph Data Model + To represent the physical grid components and the calculation results, this library utilizes a graph data model. In this document, the graph data model is presented with the list of all components types, and their relevant input/output attributes. -# Component Type Hierarchy and Graph Data Model - The components types are organized in an inheritance-like hierarchy. A sub-type has all the attributes from its parent type. The hierarchy tree of the component types is shown below. @@ -54,7 +54,7 @@ together. An `appliance` is a component that is connected (coupled) to a node, a The figure below shows a simple example: -``` +```txt node_1 ---line_3 (branch)--- node_2 --------------three_winding_transformer_8 (branch3)------ node_6 | | | source_5 (appliance) sym_load_4 (appliance) node_7 diff --git a/docs/user_manual/data-validator.md b/docs/user_manual/data-validator.md index 898d706de..53376d06f 100644 --- a/docs/user_manual/data-validator.md +++ b/docs/user_manual/data-validator.md @@ -29,7 +29,7 @@ Each validation error is an object which can be converted to a compact human-rea It contains three member variables `component`, `field` and `ids`, which can be used to gather more specific information about the validation error, e.g. which object IDs are involved. -``` +```py class ValidationError: # Component(s): e.g. "node" or ["node", "line"] diff --git a/docs/user_manual/model-validation.md b/docs/user_manual/model-validation.md index d334dae66..54d62b270 100644 --- a/docs/user_manual/model-validation.md +++ b/docs/user_manual/model-validation.md @@ -193,7 +193,7 @@ one end of Line 13 in asymmetrical batch calculation. The circuit diagram is as follows: -``` +```txt asym_load(22) sym_load(19) | | |------trafo(17)------|-----cable(9)-----|(3)----cable(11)---|(5)----OHL(13)---(On/off)-| @@ -209,7 +209,7 @@ This is a minimal case representing a simple transmission grid. The circuit diagram is as follows (The node 6 is same in both lines): -``` +```txt Gen(_21)---|_1--transformer(_30)--|_3--line(_12)-----| |---line(_14)----------| |--line(_13)---| | Gen(_22)---|_2--transformer(_31)--|_4 |_5-------line(_15)----|_6 diff --git a/docs/user_manual/performance-guide.md b/docs/user_manual/performance-guide.md index 6762ffcd7..602adc2ab 100644 --- a/docs/user_manual/performance-guide.md +++ b/docs/user_manual/performance-guide.md @@ -62,7 +62,7 @@ With the introduction of columnar data input to PGM, integrating with databases Depending on the details of the batch, a number of performance optimizations are possible: - [Topology constructions](#topology-caching), especially, may significantly impact the computation time of a scenario. -- The way the [batch data set](#using-independent-batches) is provided to the model can also affect the performance. +- The way the [batch data set](#batch-data-set) is provided to the model can also affect the performance. ### Topology caching diff --git a/docs/user_manual/serialization.md b/docs/user_manual/serialization.md index f5a56902a..36ef38ee8 100644 --- a/docs/user_manual/serialization.md +++ b/docs/user_manual/serialization.md @@ -318,7 +318,7 @@ The msgpack serialization format is a compressed version of the [JSON serializat #### msgpack schema nil (absence of value) -**NOTE:** This is the [`msgpack`](#msgpack-serialization-format-specification)-specific version of [absence of value](#msgpack-schema-absence-of-value). +**NOTE:** This is the [`msgpack`](#msgpack-serialization-format-specification)-specific version of [absence of value](#msgpack-schema-nil-absence-of-value). For [JSON](#json-serialization-format-specification), refer to [absence of value for JSON](#json-schema-null-absence-of-value). - [absence of value](#msgpack-schema-nil-absence-of-value): `nil` (the byte `\xc0`) diff --git a/tests/data/power_flow/generic_branch/README.md b/tests/data/power_flow/generic_branch/README.md index 0f9e28865..2158b01cb 100644 --- a/tests/data/power_flow/generic_branch/README.md +++ b/tests/data/power_flow/generic_branch/README.md @@ -4,12 +4,12 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Generic_Branch +# Component Test Case: Generic_Branch Test case for validation of the generic_branch component for symmetrical power flow calculations. The circuit diagram is as follows: -``` +```txt source_4--node_1--genric_branch_3--node_2--load_5 ``` diff --git a/tests/data/power_flow/pandapower/components/asymmetric/asym_gen/README.md b/tests/data/power_flow/pandapower/components/asymmetric/asym_gen/README.md index 24a719397..1cce87fef 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/asym_gen/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/asym_gen/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Asymmetrical generator +# Component Test Case: Asymmetrical generator Test case for validation of asymmetrical generator component for asymmetrical power flow calculations in pandapower. @@ -12,11 +12,11 @@ Test case for validation of asymmetrical generator component for asymmetrical po The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--asym_gen_6 (status=1) node_2--asym_gen_7 (status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/asym_load/README.md b/tests/data/power_flow/pandapower/components/asymmetric/asym_load/README.md index cf7ebff8f..e01ad830a 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/asym_load/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/asym_load/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Asymmetrical load +# Component Test Case: Asymmetrical load Test case for validation of asymmetrical load component for asymmetrical power flow calculations in pandapower. @@ -12,11 +12,11 @@ Test case for validation of asymmetrical load component for asymmetrical power f The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--asym_load_5 (status=1) node_2--asym_load_6 (status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/line/README.md b/tests/data/power_flow/pandapower/components/asymmetric/line/README.md index b26d2083e..a594fcc4a 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/line/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/line/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Line +# Component Test Case: Line Test case for validation of the line component for asymmetrical power flow calculations in pandapower. @@ -12,13 +12,13 @@ Test case for validation of the line component for asymmetrical power flow calcu The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--line_6--node_5 (Line from_status=to_status=1) node_2--line_7--node_5--asym_load_9 (Line from_status=0) node_2--line_8--node_5 (Line to_status=0) node_2--line_10--node_5 (Line from_status=to_status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/node/README.md b/tests/data/power_flow/pandapower/components/asymmetric/node/README.md index 1ff875e1a..d7d4d8bf0 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/node/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/node/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Node +# Component Test Case: Node Second test case for validation of node component for asymmetrical power flow calculations in Pandapower. @@ -12,10 +12,10 @@ Second test case for validation of node component for asymmetrical power flow ca The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2 ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/shunt/README.md b/tests/data/power_flow/pandapower/components/asymmetric/shunt/README.md index 8e825e1e6..4013c0bd9 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/shunt/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/shunt/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Shunt +# Component Test Case: Shunt Test case for validation of shunt component for asymmetrical power flow calculations in pandapower. @@ -12,11 +12,11 @@ Test case for validation of shunt component for asymmetrical power flow calculat The circuit diagram is as follows: -``` +```txt source_1--node_1--line_3--node_2--shunt_6 (status=1) node_2--shunt_7 (status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/source/README.md b/tests/data/power_flow/pandapower/components/asymmetric/source/README.md index 48e44db4d..b954e41c9 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/source/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/source/README.md @@ -4,16 +4,16 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Source +# Component Test Case: Source Test case for validation of source component for asymmetrical power flow calculations in pandapower. - While source is present in all cases, this case tests two sources being used together. -``` +```txt source_4--node_1--line_3--node_2--line_6--node_5--source_7 ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored diff --git a/tests/data/power_flow/pandapower/components/asymmetric/sym_gen/README.md b/tests/data/power_flow/pandapower/components/asymmetric/sym_gen/README.md index 00ab2d417..f04cefde9 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/sym_gen/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/sym_gen/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Symmetrical generator +# Component Test Case: Symmetrical generator Test case for validation of a symmetrical generator component for asymmetrical power flow calculations in pandapower. @@ -13,12 +13,12 @@ Test case for validation of a symmetrical generator component for asymmetrical p The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--sym_gen_6 (const_power) node_2--sym_gen_7 (status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored - Only constant power implementation is possible in pandapower for asymmetrical calculations. diff --git a/tests/data/power_flow/pandapower/components/asymmetric/sym_load/README.md b/tests/data/power_flow/pandapower/components/asymmetric/sym_load/README.md index e9b0053fc..29373e92b 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/sym_load/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/sym_load/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Symmetrical Load +# Component Test Case: Symmetrical Load Test case for validation of a symmetrical load component for asymmetrical power flow calculations in pandapower. @@ -13,12 +13,12 @@ Test case for validation of a symmetrical load component for asymmetrical power The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--sym_load_6 (const_power) node_2--sym_load_7 (status=0) ``` -### Modelling incompatibility with pandapower +## Modelling incompatibility with pandapower - Source impedance is set too low. Result of source component here should be ignored - Only constant power implementation is possible in pandapower for asymmetrical calculations. diff --git a/tests/data/power_flow/pandapower/components/asymmetric/transformer/README.md b/tests/data/power_flow/pandapower/components/asymmetric/transformer/README.md index eb443b600..ab32ad308 100644 --- a/tests/data/power_flow/pandapower/components/asymmetric/transformer/README.md +++ b/tests/data/power_flow/pandapower/components/asymmetric/transformer/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Transformer +# Component Test Case: Transformer Test case for validation of the transformer component for asymmetrical power flow calculations in pandapower. @@ -14,7 +14,7 @@ The tap changing functionality is tested using a batch calculation for various t The circuit diagram is as follows: -``` +```txt source_7--node_1--transformer_3--node_2 (Transformer from_status=to_status=1) ``` diff --git a/tests/data/power_flow/pandapower/components/symmetric/basic-node/README.md b/tests/data/power_flow/pandapower/components/symmetric/basic-node/README.md index 7d7c645dc..9aa89c7d3 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/basic-node/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/basic-node/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Node (Basic) +# Component Test Case: Node (Basic) Test case for validation of basic functioning the node component for symmetrical power flow calculations in pandapower. @@ -12,6 +12,6 @@ Test case for validation of basic functioning the node component for symmetrical The circuit diagram is as follows: -``` +```txt source_4--node_1 node_2 ``` diff --git a/tests/data/power_flow/pandapower/components/symmetric/line/README.md b/tests/data/power_flow/pandapower/components/symmetric/line/README.md index 7d33be1fe..7cfdf24eb 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/line/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/line/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Line +# Component Test Case: Line Test case for validation of the line component for symmetrical power flow calculations in pandapower. @@ -12,7 +12,7 @@ Test case for validation of the line component for symmetrical power flow calcul The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--line_6--node_5 (Line from_status=to_status=1) node_2--line_7--node_5--load_9 (Line from_status=0) node_2--line_8--node_5 (Line to_status=0) diff --git a/tests/data/power_flow/pandapower/components/symmetric/node/README.md b/tests/data/power_flow/pandapower/components/symmetric/node/README.md index c5ef1afdf..6333f65ab 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/node/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/node/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Node +# Component Test Case: Node Second test case for validation of node component for symmetrical power flow calculations in Pandapower. @@ -12,6 +12,6 @@ Second test case for validation of node component for symmetrical power flow cal The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2 ``` diff --git a/tests/data/power_flow/pandapower/components/symmetric/shunt/README.md b/tests/data/power_flow/pandapower/components/symmetric/shunt/README.md index 0177729af..77fe7f3c4 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/shunt/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/shunt/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Shunt +# Component Test Case: Shunt Test case for validation of shunt component for symmetrical power flow calculations in pandapower. @@ -12,7 +12,7 @@ Test case for validation of shunt component for symmetrical power flow calculati The circuit diagram is as follows: -``` +```txt source_1--node_1--line_3--node_2--shunt_6 (status=1) node_2--shunt_7 (status=0) ``` diff --git a/tests/data/power_flow/pandapower/components/symmetric/source/README.md b/tests/data/power_flow/pandapower/components/symmetric/source/README.md index df52473e8..fe6b178f4 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/source/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/source/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Source +# Component Test Case: Source Test case for validation of source component for symmetrical power flow calculations in pandapower. @@ -12,6 +12,6 @@ Test case for validation of source component for symmetrical power flow calculat The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--line_6--node_5--source_7 ``` diff --git a/tests/data/power_flow/pandapower/components/symmetric/sym_gen/README.md b/tests/data/power_flow/pandapower/components/symmetric/sym_gen/README.md index a9531e095..ae7b38e5e 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/sym_gen/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/sym_gen/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Symmetrical generator +# Component Test Case: Symmetrical generator Test case for validation of a symmetrical generator component for symmetrical power flow calculations in pandapower. @@ -13,7 +13,7 @@ Test case for validation of a symmetrical generator component for symmetrical po The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--sym_gen_6 (const_power) node_2--sym_gen_7 (const_current) node_2--sym_gen_8 (const_impedance) diff --git a/tests/data/power_flow/pandapower/components/symmetric/sym_load/README.md b/tests/data/power_flow/pandapower/components/symmetric/sym_load/README.md index 916da40a3..73a6d5249 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/sym_load/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/sym_load/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Symmetrical Load +# Component Test Case: Symmetrical Load Test case for validation of a symmetrical load component for symmetrical power flow calculations in pandapower. @@ -13,7 +13,7 @@ Test case for validation of a symmetrical load component for symmetrical power f The circuit diagram is as follows: -``` +```txt source_4--node_1--line_3--node_2--sym_load_6 (const_power) node_2--sym_load_7 (const_current) node_2--sym_load_8 (const_impedance) diff --git a/tests/data/power_flow/pandapower/components/symmetric/three_winding_transformer/README.md b/tests/data/power_flow/pandapower/components/symmetric/three_winding_transformer/README.md index dc24c265d..990accdbd 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/three_winding_transformer/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/three_winding_transformer/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Three Winding Transformer +# Component Test Case: Three Winding Transformer Test case for validation of the three winding transformer component for symmetrical power flow calculations in pandapower. The implementation of both the libraries are similar. Three 2-winding transformers are used in star connection for creating a 3 winding transformer. @@ -12,7 +12,7 @@ Test case for validation of the three winding transformer component for symmetri The circuit diagram is as follows: -``` +```txt source_7--node_1--three_winding_transformer_3--node_2---sym_load_41 (3wdg Transformer status=1) | node_3---sym_load_42 diff --git a/tests/data/power_flow/pandapower/components/symmetric/transformer/README.md b/tests/data/power_flow/pandapower/components/symmetric/transformer/README.md index 1f0a86ab5..8a134ca41 100644 --- a/tests/data/power_flow/pandapower/components/symmetric/transformer/README.md +++ b/tests/data/power_flow/pandapower/components/symmetric/transformer/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Component Test Case: Transformer +# Component Test Case: Transformer Test case for validation of the transformer component for symmetrical power flow calculations in pandapower. @@ -14,7 +14,7 @@ The tap changing functionality is tested using a batch calculation for various t The circuit diagram is as follows: -``` +```txt source_7--node_1--transformer_3--node_2 (Transformer from_status=to_status=1) node_1--transformer_4--node_2--load_6 (Transformer from_status=0) node_1--transformer_5--node_2 (Transformer to_status=0) diff --git a/tests/data/power_flow/pandapower/networks/asymmetric/distribution-case/README.md b/tests/data/power_flow/pandapower/networks/asymmetric/distribution-case/README.md index 43ec6ec6e..230930240 100644 --- a/tests/data/power_flow/pandapower/networks/asymmetric/distribution-case/README.md +++ b/tests/data/power_flow/pandapower/networks/asymmetric/distribution-case/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Distribution grid +# Network Test Case: Distribution grid Test case representing a typical distribution grid. The grid has 2 identical parallel transformers. @@ -15,7 +15,7 @@ one end of Line 13 in symmetrical batch calculation. The circuit diagram is as follows: -``` +```txt asym_load(22) sym_load(19) | | |------trafo(17)------|-----cable(9)-----|(3)----cable(11)---|(5)----OHL(13)---(On/off)-| diff --git a/tests/data/power_flow/pandapower/networks/asymmetric/transmission-case/README.md b/tests/data/power_flow/pandapower/networks/asymmetric/transmission-case/README.md index 21e29d246..33392a001 100644 --- a/tests/data/power_flow/pandapower/networks/asymmetric/transmission-case/README.md +++ b/tests/data/power_flow/pandapower/networks/asymmetric/transmission-case/README.md @@ -4,13 +4,13 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Transmission grid +# Network Test Case: Transmission grid Test case representing a typical transmission grid. The circuit diagram is as follows (The node 6 is same in both lines): -``` +```txt Gen(_21)---|_1--transformer(_30)--|_3--line(_12)-----| |---line(_14)----------| |--line(_13)---| | Gen(_22)---|_2--transformer(_31)--|_4 |_5-------line(_15)----|_6 diff --git a/tests/data/power_flow/pandapower/networks/symmetric/distribution-case/README.md b/tests/data/power_flow/pandapower/networks/symmetric/distribution-case/README.md index 265e7dc8f..1d419bfe3 100644 --- a/tests/data/power_flow/pandapower/networks/symmetric/distribution-case/README.md +++ b/tests/data/power_flow/pandapower/networks/symmetric/distribution-case/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Distribution grid +# Network Test Case: Distribution grid Test case representing a typical distribution grid. The grid has 2 identical parallel transformers. @@ -17,7 +17,7 @@ Note: the transformer result values cannot be validated because of modelling dif The circuit diagram is as follows: -``` +```txt asym_load(22) sym_load(19) | | |------trafo(17)------|-----cable(9)-----|(3)----cable(11)---|(5)----OHL(13)---(On/off)-| diff --git a/tests/data/power_flow/pandapower/networks/symmetric/transmission-case/README.md b/tests/data/power_flow/pandapower/networks/symmetric/transmission-case/README.md index 21e29d246..33392a001 100644 --- a/tests/data/power_flow/pandapower/networks/symmetric/transmission-case/README.md +++ b/tests/data/power_flow/pandapower/networks/symmetric/transmission-case/README.md @@ -4,13 +4,13 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Transmission grid +# Network Test Case: Transmission grid Test case representing a typical transmission grid. The circuit diagram is as follows (The node 6 is same in both lines): -``` +```txt Gen(_21)---|_1--transformer(_30)--|_3--line(_12)-----| |---line(_14)----------| |--line(_13)---| | Gen(_22)---|_2--transformer(_31)--|_4 |_5-------line(_15)----|_6 diff --git a/tests/data/state_estimation/distribution-case/README.md b/tests/data/state_estimation/distribution-case/README.md index c392c5881..cc99dd180 100644 --- a/tests/data/state_estimation/distribution-case/README.md +++ b/tests/data/state_estimation/distribution-case/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Distribution grid +# Network Test Case: Distribution grid Test case representing a typical distribution grid. The grid has 2 identical parallel transformers. @@ -18,7 +18,7 @@ one end of Line 13 in symmetrical batch calculation. The circuit diagram is as follows: -``` +```txt Load(22) Load(19) | | |------trafo(17)------|-----cable(9)-----|(3)----cable(11)---|(5)----OHL(13)---(On/off)-| diff --git a/tests/data/state_estimation/transmission-case/README.md b/tests/data/state_estimation/transmission-case/README.md index 0fa1a5541..063f99214 100644 --- a/tests/data/state_estimation/transmission-case/README.md +++ b/tests/data/state_estimation/transmission-case/README.md @@ -4,7 +4,7 @@ SPDX-FileCopyrightText: Contributors to the Power Grid Model project -## Network Test Case: Transmission grid +# Network Test Case: Transmission grid Test case representing a typical transmission grid. Symmetrical voltage sensors are installed on all nodes and power sensors are installed at both ends of lines and @@ -12,7 +12,7 @@ transformers. The circuit diagram is as follows (The node 6 is same in both lines): -``` +```txt Gen(_21)---|_1--transformer(_30)--|_3--line(_12)-----| |---line(_14)----------| |--line(_13)---| | Gen(_22)---|_2--transformer(_31)--|_4 |_5-------line(_15)----|_6 From f0ca3659468569c588c71bf6c77c7aae8e4f43fc Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Tue, 22 Apr 2025 16:23:20 +0200 Subject: [PATCH 4/5] add to workspace recommendations Signed-off-by: Martijn Govers --- .vscode/extensions.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index d56195297..bdd0c4e2b 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -24,6 +24,7 @@ "matepek.vscode-catch2-test-adapter", "cschlosser.doxdocgen", "fredericbonnet.cmake-test-adapter", - "sonarsource.sonarlint-vscode" + "sonarsource.sonarlint-vscode", + "davidanson.vscode-markdownlint" ] } \ No newline at end of file From 8255abe5dc5164ff21a68328f4c777e36944fd49 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 23 Apr 2025 08:51:26 +0200 Subject: [PATCH 5/5] update fault type and default values text Signed-off-by: Martijn Govers --- docs/user_manual/components.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index a8079ad92..8ed0990fe 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -730,14 +730,14 @@ $$ #### Input -| 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 ` | - | the type of the fault | ✨ only for short circuit | ✔ | | -| `fault_phase` | {py:class}`FaultPhase ` | - | the phase(s) of the fault | ❌ default `FaultPhase.default_value` (see [below](#fault-types-and-default-values-for-fault-phase)) | ✔ | | -| `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` | ✔ | | +| 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 ` | - | the type of the fault | ✨ only for short circuit | ✔ | | +| `fault_phase` | {py:class}`FaultPhase ` | - | the phase(s) of the fault | ❌ default `FaultPhase.default_value` (see [below](#fault-types-fault-phases-and-default-values)) | ✔ | | +| `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` | ✔ | | ```{note} Multiple faults may exist within one calculation. Currently, all faults in one scenario are required to have the @@ -763,13 +763,13 @@ A `fault` has no steady state output. #### Electric Model -##### Fault types and default values for fault phase +##### Fault types, fault phases and default values -Four types of short circuit fault are included in power-grid-model. +Four types of short circuit fault are included in power-grid-model, each with their own set of supported values for `fault_phase`. +In case the `fault_phase` is not specified or is equal to `FaultPhase.default_value`, the power-grid-model assumes a `fault_type`-dependent set of fault phases. +The supported values of `fault_phase`, as well as its default value, are listed in the table below. -In case the `fault_phase` is not specified or is equal to `FaultPhase.default_value`, the power-grid-model assumes the fault phases for different values of `fault_type` as specified in the table below. - -| `fault_type` | Supported values of `FaultPhase` | `FaultPhase.default_value` | description | +| `fault_type` | supported values of `fault_phase` | `FaultPhase.default_value` | description | | ---------------------------------- | ------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------- | | `FaultType.three_phase` | `FaultPhase.abc` | `FaultPhase.abc` | Three phases are connected with fault impedance. | | `FaultType.single_phase_to_ground` | `FaultPhase.a`, `FaultPhase.b`, `FaultPhase.c` | `FaultPhase.a` | One phase is grounded with fault impedance, and other phases are open. |