From 06d56dfc38fab51d95138a7a8cec33d0f8f9fe85 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 14:32:14 +0200 Subject: [PATCH 01/11] document infinite admittance handling Signed-off-by: Martijn Govers --- docs/user_manual/components.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 5968351858..274a9c225d 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -211,6 +211,24 @@ $$ Y_{\text{series}} = (1 + \mathrm{j}) \cdot 10^6 \,\mathrm{p.u.} $$ +##### Handling infinite admittances + +Because an admittance matrix with infinities is ill-conditioned, the power-grid-model runs a multi-scale calculation. + +To set up this multi-scale calculation, any nodes connected by links are merged into topological nodes. +The remaining grid is a topologically well-conditioned grid with finite impedance branches. +At the same time, each topological node have a substructure of infinite-admittance links and "external" +finite-impedance branches and appliances. + +The calculation itself is done as follows. + +1. Solve the topological grid using the [user-specified calculation type and method](./calculations.md). + This yields a complete mathematical calculation output for all components except link flows and node injections, + including node voltages, branch flows and admittance flows. +2. Solve each topological node separately to obtain the node injection sums and link flows, using the mathematical + calculation outputs from the previous step as inputs. + This fills in the remaining gaps in the output. + ### Transformer `transformer` is a [branch](#branch) which connects two nodes with possibly different From 4f588e492c828ab83d71dd8d7e3baa92602971a0 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 14:37:41 +0200 Subject: [PATCH 02/11] cleanup Signed-off-by: Martijn Govers --- docs/user_manual/components.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 274a9c225d..b4e8339c06 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -198,14 +198,14 @@ It is explicitly allowed to connect a link between nodes with different voltage #### Electric Model -`link` is modeled by a constant admittance $Y_{\text{series}}$. -If there are no node injection sensors in the grid: +`link` is modeled by a constant series admittance $Y_{\text{series}}$. +If there are no node injection sensors in the grid, the link is an ideal (lossless) connection: $$ Y_{\text{series}}\rightarrow \infty $$ -If there are node injection sensors in the grid: +If there are node injection sensors in the grid, a large but finite admittance is used: $$ Y_{\text{series}} = (1 + \mathrm{j}) \cdot 10^6 \,\mathrm{p.u.} @@ -213,14 +213,15 @@ $$ ##### Handling infinite admittances -Because an admittance matrix with infinities is ill-conditioned, the power-grid-model runs a multi-scale calculation. +An admittance matrix that contains infinities is ill-conditioned and cannot be solved directly, so the power-grid-model +runs a multi-scale calculation. To set up this multi-scale calculation, any nodes connected by links are merged into topological nodes. -The remaining grid is a topologically well-conditioned grid with finite impedance branches. -At the same time, each topological node have a substructure of infinite-admittance links and "external" -finite-impedance branches and appliances. +The remaining grid is a topologically well-conditioned grid with finite-impedance branches. +Each topological node in turn has a substructure of infinite-admittance links together with the "external" +finite-impedance branches and appliances connected to it. -The calculation itself is done as follows. +The calculation itself is done in two steps. 1. Solve the topological grid using the [user-specified calculation type and method](./calculations.md). This yields a complete mathematical calculation output for all components except link flows and node injections, From fe600bb9fa709b186712866fd7cb8e2e3d9cab5c Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 15:13:08 +0200 Subject: [PATCH 03/11] minor additions Signed-off-by: Martijn Govers --- docs/user_manual/components.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index b4e8339c06..6598c107e7 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -185,7 +185,8 @@ Because of this, the power-grid-model choses to model this accordingly: to 10e6 siemens for a 10kV network. ```{note} -New in version [`v1.13.142`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.142): links may be modeled as infinite (but equal) admittance connections. +New in version [`v1.13.142`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.142): links may be +modeled as infinite (but equal) admittance connections. In the old behavior, link admittances were always modeled with the same fixed per-unit value. Starting with version `v2.0.0`, link admittances are always modeled as infinite-admittance connections. ``` @@ -216,7 +217,7 @@ $$ An admittance matrix that contains infinities is ill-conditioned and cannot be solved directly, so the power-grid-model runs a multi-scale calculation. -To set up this multi-scale calculation, any nodes connected by links are merged into topological nodes. +To set up this multi-scale calculation, nodes are grouped into clusters internally connected by links, called topological nodes. The remaining grid is a topologically well-conditioned grid with finite-impedance branches. Each topological node in turn has a substructure of infinite-admittance links together with the "external" finite-impedance branches and appliances connected to it. @@ -226,8 +227,8 @@ The calculation itself is done in two steps. 1. Solve the topological grid using the [user-specified calculation type and method](./calculations.md). This yields a complete mathematical calculation output for all components except link flows and node injections, including node voltages, branch flows and admittance flows. -2. Solve each topological node separately to obtain the node injection sums and link flows, using the mathematical - calculation outputs from the previous step as inputs. +2. Solve for the flows within each topological node separately to obtain the node injection sums and link flows, using the + mathematical calculation outputs from the previous step as inputs. This fills in the remaining gaps in the output. ### Transformer From fe443b67e248b017aea1271b335f7b1781bd6bf0 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 15:40:49 +0200 Subject: [PATCH 04/11] update core design Signed-off-by: Martijn Govers --- docs/advanced_documentation/core-design.md | 29 ++++++++++++++++------ 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/advanced_documentation/core-design.md b/docs/advanced_documentation/core-design.md index 0e1d0382bc..ae7c65edc0 100644 --- a/docs/advanced_documentation/core-design.md +++ b/docs/advanced_documentation/core-design.md @@ -20,10 +20,14 @@ Coincidentally, those phases also translate to fields of expertise, which enable | Logic/control module | Description | Expertise | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------- | | I/O | Constructing, updating and outputting components in the power grid | Software Engineering | -| Topology construction | Constructing the topological graph of the grid | Topology | +| General topology construction | Constructing the overall topological layout of the grid, including open connections and disabled components | Topology | +| Topology reduction | Splitting the general topological layout into a multi-scale topological representation by merging nodes on links | Topology | +| Mathematical topology construction | Constructing a topological representation of the grid optimized for efficient matrix solving | Topology | | $Y_{\text{bus}}$ construction/Component extraction | Constructing $Y_{\text{bus}}$ from the power grid components and topology | Electrical Engineering | | Solver construction/Grid extraction | Translation from $Y_{\text{bus}}$ to a solvable system of equations and from the solution back to physical values | Physics | -| Solving | Abstract solution to the system of equations | Mathematics | +| Math solving | Abstract solution to the macro-scale system of equations | Mathematics | +| Optimization | Abstract optimization of parameters to ensure optimal grid configuration | Mathematics | +| Topological node solving | Abstract solution to the micro-scale power/current flow (within a topological node) | Mathematics | ```{note} Software Engineering obviously also plays a role in the general design, but that general design does not involve the @@ -35,18 +39,27 @@ The data flow can be visualized as such: ```{mermaid} graph TD ComponentInput(Input/Update data) -->|Input| Components[Power Grid Components] - Components -->|Topology construction| Topo[Topology] + Components -->|Static topology construction| GeneralTopo[General Topology (including disabled components)] - Topo -->|Ybus construction| Ybus(Ybus) + GeneralTopo -->|Topology reduction| ReducedTopo[Reduced Topology (split into topological nodes and substructures)] + + ReducedTopo -->|Mathematical topology construction| MathTopo[Mathematical topology] + + MathTopo -->|Ybus construction| Ybus(Ybus) Components --> Ybus Ybus -->|Solver construction/extraction| Equations(Solvable system of equations) - Equations -->|Solving| Solution(Solution) + Equations -->|Math solving| Solution(Solution) + + Solution -->|Grid extraction| MacroGridResult(Macro-grid result) + Ybus --> MacroGridResult + + MacroGridResult -->|Optimization| MacroGridResult - Solution -->|Grid extraction| GridResult(Grid result) - Ybus --> GridResult + MacroGridResult -->|Topological node solving| FullGridResult(Full grid result) + ReducedTopo --> FullGridResult - GridResult -->|Component extraction| ComponentsOutput(Components result) + FullGridResult -->|Component extraction| ComponentsOutput(Components result) Components --> ComponentsOutput ComponentsOutput -->|Output| Output(Output data) From 11fcdb4becf67401da1299664e0c5e4d37f813ff Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 15:44:27 +0200 Subject: [PATCH 05/11] update core design Signed-off-by: Martijn Govers --- docs/advanced_documentation/core-design.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/advanced_documentation/core-design.md b/docs/advanced_documentation/core-design.md index ae7c65edc0..c71ff80c47 100644 --- a/docs/advanced_documentation/core-design.md +++ b/docs/advanced_documentation/core-design.md @@ -14,7 +14,7 @@ The `MainModel` itself can be deconstructed into an API part, a dispatch part, t ## Calculation logic and data flow -The logic involved in power grid calculations in turn can be devided in a number of separate modules. +The logic involved in power grid calculations in turn can be divided in a number of separate modules. Coincidentally, those phases also translate to fields of expertise, which enables a reasonably clean architecture. | Logic/control module | Description | Expertise | @@ -39,16 +39,16 @@ The data flow can be visualized as such: ```{mermaid} graph TD ComponentInput(Input/Update data) -->|Input| Components[Power Grid Components] - Components -->|Static topology construction| GeneralTopo[General Topology (including disabled components)] + Components -->|Static topology construction| GeneralTopo["General Topology (including disabled components)"] - GeneralTopo -->|Topology reduction| ReducedTopo[Reduced Topology (split into topological nodes and substructures)] + GeneralTopo -->|Topology reduction| ReducedTopo["Reduced Topology (split into topological nodes and substructures)"] ReducedTopo -->|Mathematical topology construction| MathTopo[Mathematical topology] MathTopo -->|Ybus construction| Ybus(Ybus) Components --> Ybus - Ybus -->|Solver construction/extraction| Equations(Solvable system of equations) + Ybus -->|Solver construction| Equations(Solvable system of equations) Equations -->|Math solving| Solution(Solution) Solution -->|Grid extraction| MacroGridResult(Macro-grid result) From 19d7b72d33f4726b43b1f437989a3631599d49db Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 15:54:52 +0200 Subject: [PATCH 06/11] improve Signed-off-by: Martijn Govers --- docs/advanced_documentation/core-design.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/advanced_documentation/core-design.md b/docs/advanced_documentation/core-design.md index c71ff80c47..039da94399 100644 --- a/docs/advanced_documentation/core-design.md +++ b/docs/advanced_documentation/core-design.md @@ -39,6 +39,9 @@ The data flow can be visualized as such: ```{mermaid} graph TD ComponentInput(Input/Update data) -->|Input| Components[Power Grid Components] + + Params[Electrical parameters] + Components -->|Electrical parameter construction| Params Components -->|Static topology construction| GeneralTopo["General Topology (including disabled components)"] GeneralTopo -->|Topology reduction| ReducedTopo["Reduced Topology (split into topological nodes and substructures)"] @@ -46,17 +49,17 @@ graph TD ReducedTopo -->|Mathematical topology construction| MathTopo[Mathematical topology] MathTopo -->|Ybus construction| Ybus(Ybus) - Components --> Ybus + Params --> Ybus Ybus -->|Solver construction| Equations(Solvable system of equations) - Equations -->|Math solving| Solution(Solution) + Equations -->|Math solving| Solution(Mathematical solution) Solution -->|Grid extraction| MacroGridResult(Macro-grid result) Ybus --> MacroGridResult - MacroGridResult -->|Optimization| MacroGridResult + MacroGridResult -->|Optional optimization| Params - MacroGridResult -->|Topological node solving| FullGridResult(Full grid result) + MacroGridResult -->|Topological node solving| FullGridResult("Full grid result") ReducedTopo --> FullGridResult FullGridResult -->|Component extraction| ComponentsOutput(Components result) From f4cb001c6f18efa32363b16402b8187d92e01c82 Mon Sep 17 00:00:00 2001 From: Martijn Govers Date: Wed, 26 Aug 2026 15:59:54 +0200 Subject: [PATCH 07/11] update version Signed-off-by: Martijn Govers --- docs/user_manual/components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 6598c107e7..417a8d0f86 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -185,7 +185,7 @@ Because of this, the power-grid-model choses to model this accordingly: to 10e6 siemens for a 10kV network. ```{note} -New in version [`v1.13.142`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.142): links may be +New in version [`v1.13.142`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.152): links may be modeled as infinite (but equal) admittance connections. In the old behavior, link admittances were always modeled with the same fixed per-unit value. Starting with version `v2.0.0`, link admittances are always modeled as infinite-admittance connections. From a1fa3896f3b09f0b3f243c15e5f5b284e6a7a9af Mon Sep 17 00:00:00 2001 From: Santiago Figueroa Manrique Date: Tue, 1 Sep 2026 10:01:43 +0200 Subject: [PATCH 08/11] core-design Signed-off-by: Santiago Figueroa Manrique --- docs/advanced_documentation/core-design.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/advanced_documentation/core-design.md b/docs/advanced_documentation/core-design.md index 039da94399..aabe682dcc 100644 --- a/docs/advanced_documentation/core-design.md +++ b/docs/advanced_documentation/core-design.md @@ -7,9 +7,9 @@ SPDX-License-Identifier: MPL-2.0 # Design of the Power Grid Model core The Power Grid Model at its core is a header-only C++ interface library, wrapped by a dynamic/shared C API library. -The core itself is an engine called the `MainModel` that provides the C++ interface and exhibits logic for the various +The core itself is an engine called the `MainModel` that provides the C++ interface and contains the logic for the various aspects that play a role in power grid calculations. -The `MainModel` itself can be deconstructed into an API part, a dispatch part, the grid model and the actual +The `MainModel` itself can be decomposed into an API part, a dispatch part, the grid model and the actual [calculation logic](#calculation-logic-and-data-flow). ## Calculation logic and data flow @@ -19,15 +19,15 @@ Coincidentally, those phases also translate to fields of expertise, which enable | Logic/control module | Description | Expertise | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------- | -| I/O | Constructing, updating and outputting components in the power grid | Software Engineering | +| I/O | Constructing, updating, and outputting components in the power grid | Software Engineering | +| Electrical parameter construction | Constructing electrical parameters from the power grid components | Electrical Engineering | | General topology construction | Constructing the overall topological layout of the grid, including open connections and disabled components | Topology | -| Topology reduction | Splitting the general topological layout into a multi-scale topological representation by merging nodes on links | Topology | -| Mathematical topology construction | Constructing a topological representation of the grid optimized for efficient matrix solving | Topology | -| $Y_{\text{bus}}$ construction/Component extraction | Constructing $Y_{\text{bus}}$ from the power grid components and topology | Electrical Engineering | +| Topology reduction | Splitting the general topological layout into a multi-scale topological representation by merging links on nodes | Topology | +| Mathematical topology construction | Constructing a graph representation of the reduced topology for efficient matrix solving | Topology | +| $Y_{\text{bus}}$ construction | Constructing the $Y_{\text{bus}}$ from the electrical parameters and the mathematical topology | Electrical Engineering | | Solver construction/Grid extraction | Translation from $Y_{\text{bus}}$ to a solvable system of equations and from the solution back to physical values | Physics | | Math solving | Abstract solution to the macro-scale system of equations | Mathematics | -| Optimization | Abstract optimization of parameters to ensure optimal grid configuration | Mathematics | -| Topological node solving | Abstract solution to the micro-scale power/current flow (within a topological node) | Mathematics | +| Topological node solving | Abstract solution to the micro-scale structure using the macro-scale solution | Mathematics | ```{note} Software Engineering obviously also plays a role in the general design, but that general design does not involve the From 927e8e156f32bd9b8dbeb4dfd5f3b99e76926ed6 Mon Sep 17 00:00:00 2001 From: Santiago Figueroa Manrique Date: Tue, 1 Sep 2026 10:44:29 +0200 Subject: [PATCH 09/11] components Signed-off-by: Santiago Figueroa Manrique --- docs/user_manual/components.md | 109 ++++++++++++++++----------------- 1 file changed, 53 insertions(+), 56 deletions(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 417a8d0f86..099e57dd3d 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -122,54 +122,6 @@ In this case, the attribute `from_status` and `to_status` is always 1. | `i_to` | `RealValueOutput` | ampere (A) | magnitude of current at to-side | | `i_to_angle` | `RealValueOutput` | rad | current angle at to-side | -## Branch - -* type name: `branch` -* base: [edge](#edge) - -`branch` is the abstract base type for the component which connects two (possibly identical) nodes with finite -impedance. -All input, update and output attributes are identical to the ones for [Edges](#edge). - -### Line - -* type name: `line` - -`line` is a [branch](#branch) with specified serial impedance and shunt admittance. -A cable is also modeled as `line`. -A `line` can only connect two nodes with the same rated voltage. -If `i_n` is not provided, `loading` of line will be a `nan` value. - -#### Input - -| name | data type | unit | description | required | update | valid values | -|--------|-----------|------------|----------------------------------------------------|:-----------------------------------------:|:--------:|:----------------------------------:| -| `r1` | `double` | ohm (Ω) | positive-sequence serial resistance | ✔ | ❌ | `r1` and `x1` cannot be both `0.0` | -| `x1` | `double` | ohm (Ω) | positive-sequence serial reactance | ✔ | ❌ | `r1` and `x1` cannot be both `0.0` | -| `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 `0.0` | -| `x0` | `double` | ohm (Ω) | zero-sequence serial reactance | ✨ only for asymmetric calculations | ❌ | `r0` and `x0` cannot be both `0.0` | -| `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` | - -```{note} -In case of short circuit calculations, the zero-sequence parameters are required only if any of the faults in any of the -scenarios within a batch are not three-phase faults (i.e. `fault_type` is not `FaultType.three_phase`). -``` - -#### Electric Model - -`line` is described by a $\pi$ model, where - -$$ -\begin{aligned} - Z_{\text{series}} &= r + \mathrm{j}x \\ - Y_{\text{shunt}} &= 2 \pi fc (\tan \delta +\mathrm{j}) -\end{aligned} -$$ - ### Link * type name: `link` @@ -185,7 +137,7 @@ Because of this, the power-grid-model choses to model this accordingly: to 10e6 siemens for a 10kV network. ```{note} -New in version [`v1.13.142`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.152): links may be +New in version [`v1.13.156`](https://github.com/PowerGridModel/power-grid-model/releases/tag/v1.13.156): links may be modeled as infinite (but equal) admittance connections. In the old behavior, link admittances were always modeled with the same fixed per-unit value. Starting with version `v2.0.0`, link admittances are always modeled as infinite-admittance connections. @@ -230,6 +182,54 @@ The calculation itself is done in two steps. 2. Solve for the flows within each topological node separately to obtain the node injection sums and link flows, using the mathematical calculation outputs from the previous step as inputs. This fills in the remaining gaps in the output. + +## Branch + +* type name: `branch` +* base: [edge](#edge) + +`branch` is the abstract base type for the component which connects two (possibly identical) nodes with finite +impedance. +All input, update and output attributes are identical to the ones for [Edges](#edge). + +### Line + +* type name: `line` + +`line` is a [branch](#branch) with specified serial impedance and shunt admittance. +A cable is also modeled as `line`. +A `line` can only connect two nodes with the same rated voltage. +If `i_n` is not provided, `loading` of line will be a `nan` value. + +#### Input + +| name | data type | unit | description | required | update | valid values | +|--------|-----------|------------|----------------------------------------------------|:-----------------------------------------:|:--------:|:----------------------------------:| +| `r1` | `double` | ohm (Ω) | positive-sequence serial resistance | ✔ | ❌ | `r1` and `x1` cannot be both `0.0` | +| `x1` | `double` | ohm (Ω) | positive-sequence serial reactance | ✔ | ❌ | `r1` and `x1` cannot be both `0.0` | +| `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 `0.0` | +| `x0` | `double` | ohm (Ω) | zero-sequence serial reactance | ✨ only for asymmetric calculations | ❌ | `r0` and `x0` cannot be both `0.0` | +| `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` | + +```{note} +In case of short circuit calculations, the zero-sequence parameters are required only if any of the faults in any of the +scenarios within a batch are not three-phase faults (i.e. `fault_type` is not `FaultType.three_phase`). +``` + +#### Electric Model + +`line` is described by a $\pi$ model, where + +$$ +\begin{aligned} + Z_{\text{series}} &= r + \mathrm{j}x \\ + Y_{\text{shunt}} &= 2 \pi fc (\tan \delta +\mathrm{j}) +\end{aligned} +$$ ### Transformer @@ -886,8 +886,7 @@ The $\pmod{2\pi}$ is handled such that $-\pi \lt \theta_{\text{angle},\text{resi `power_sensor` is an abstract class for symmetric and asymmetric power sensor and is derived from [sensor](#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`. +The terminal is either connecting an `appliance` and a `node`, or connecting the from/to end of a `branch` and a `node`. In case of a terminal between an `appliance` and a `node`, the power [Reference Direction](data-model.md#reference-direction) in the measurement data is the same as the reference direction of the `appliance`. @@ -895,8 +894,7 @@ For example, if a `power_sensor` is measuring a `source`, a positive `p_measured from the source to the node. ```{note} -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` +1. Due to the high admittance of a `link` it is chosen that a power sensor cannot be coupled to a `link`. 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 @@ -999,11 +997,10 @@ $$ `current_sensor` is an abstract class for symmetric and asymmetric current sensor and is derived from [sensor](#sensor). It measures the magnitude and angle of the current flow of a terminal. -The terminal is connecting the from/to end of a `branch` (except `link`) and a `node`. +The terminal is connecting the from/to end of a `branch` and a `node`. ```{note} -Due to the high admittance of a `link` it is chosen that a current sensor cannot be coupled to a `link`, even though a -link is a `branch`. +Due to the high admittance of a `link` it is chosen that a current sensor cannot be coupled to a `link`. ``` ```{note} From 74546d523f22b033d88baa9ef169f8d478b19c41 Mon Sep 17 00:00:00 2001 From: Santiago Figueroa Manrique Date: Tue, 1 Sep 2026 10:55:58 +0200 Subject: [PATCH 10/11] data-model Signed-off-by: Santiago Figueroa Manrique --- docs/user_manual/data-model.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/user_manual/data-model.md b/docs/user_manual/data-model.md index 64b2c0e55a..62fb48196e 100644 --- a/docs/user_manual/data-model.md +++ b/docs/user_manual/data-model.md @@ -17,11 +17,12 @@ The hierarchy tree of the component types is shown below. ```{mermaid} graph LR base-->node - base-->branch - branch-->line - branch-->link - branch-->generic_branch - branch-->transformer + base-->edge + edge-->link + edge-->branch + branch-->line + branch-->generic_branch + branch-->transformer base-->branch3 branch3-->three_winding_transformer base-->appliance @@ -50,8 +51,8 @@ the {py:class}`power_grid_model.power_grid_meta_data`, see [Native Data Interface](../advanced_documentation/native-data-interface.md). ``` -There are four generic component types: `node`, `branch`, `branch3` and `appliance`. -A `node` is similar to a vertex in a graph, a `branch` is similar to an edge in a graph and a `branch3` connects three +There are five generic component types: `node`, `edge`, `branch`, `branch3` and `appliance`. +A `node` is similar to a vertex in a graph, an `edge` is similar to an edge in a graph, a `branch` is an `edge` with finite admittance, and a `branch3` connects three nodes together. An `appliance` is a component that is connected (coupled) to a node, and it is seen as a user of this node. @@ -60,12 +61,13 @@ 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 +source_5 (appliance) sym_load_4 (appliance) node_7 ---link_9 (edge)--- node_10 ``` * There are four nodes (points/vertices) in the graph of this simple grid. * `node_1` and `node_2` are connected by `line_3` which is a branch (edge). * `node_2`, `node_6`, and `node_7` are connected by `three_winding_transformer_8`, which is a `branch3`. +* `node_10` is connected by `link_9` which is an edge, but not a branch. * There are two appliances in the grid. `source_5` is coupled to `node_1` and `sym_load_4` is coupled to `node_2`. @@ -103,5 +105,5 @@ The sign of active/reactive power of the {ref}`user_manual/components:Branch`, { *appliance/sensor*. * For generator reference direction, positive active/reactive power means the power flows *from the appliance/sensor to* *the node*. -* For `branch` and `branch3` type of components, positive active/reactive power means the power flows *from the node to* +* For `edge`, `branch` and `branch3` type of components, positive active/reactive power means the power flows *from the node to* *the branch*. From e5c5609a751b2e08b3e35633b5ff42e59964bb10 Mon Sep 17 00:00:00 2001 From: Santiago Figueroa Manrique Date: Wed, 2 Sep 2026 08:40:22 +0200 Subject: [PATCH 11/11] resolve comments Signed-off-by: Santiago Figueroa Manrique --- docs/user_manual/components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 099e57dd3d..5f014f033d 100644 --- a/docs/user_manual/components.md +++ b/docs/user_manual/components.md @@ -886,7 +886,7 @@ The $\pmod{2\pi}$ is handled such that $-\pi \lt \theta_{\text{angle},\text{resi `power_sensor` is an abstract class for symmetric and asymmetric power sensor and is derived from [sensor](#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` and a `node`. +The terminal is always connected to a `node` on the one side, and either `appliance`, or the from/to end of a `branch` on the other. In case of a terminal between an `appliance` and a `node`, the power [Reference Direction](data-model.md#reference-direction) in the measurement data is the same as the reference direction of the `appliance`. @@ -894,7 +894,7 @@ For example, if a `power_sensor` is measuring a `source`, a positive `p_measured from the source to the node. ```{note} -1. Due to the high admittance of a `link` it is chosen that a power sensor cannot be coupled to a `link`. +1. Due to the high admittance of a `link`, it is chosen that a power sensor cannot be coupled to a `link`. 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