Merge links into nodes: Documentation

docs/advanced_documentation/core-design.md

@@ -7,23 +7,27 @@ 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
 
-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              |
 | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| I/O                                                | Constructing, updating and outputting components in the power grid                                                | Software Engineering   |
-| Topology construction                              | Constructing the topological graph of the grid                                                                    | Topology               |
-| $Y_{\text{bus}}$ construction/Component extraction | Constructing $Y_{\text{bus}}$ from the power grid components and topology                                         | Electrical 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 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                |
-| Solving                                            | Abstract solution to the system of equations                                                                      | Mathematics            |
+| Math solving                                       | Abstract solution to the macro-scale system of equations                                                          | 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
@@ -35,18 +39,30 @@ 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]
 
-    Topo -->|Ybus construction| Ybus(Ybus)
-    Components --> Ybus
+    Params[Electrical parameters]
+    Components -->|Electrical parameter construction| Params
+    Components -->|Static topology construction| GeneralTopo["General Topology (including disabled components)"]
 
-    Ybus -->|Solver construction/extraction| Equations(Solvable system of equations)
-    Equations -->|Solving| Solution(Solution)
+    GeneralTopo -->|Topology reduction| ReducedTopo["Reduced Topology (split into topological nodes and substructures)"]
 
-    Solution -->|Grid extraction| GridResult(Grid result)
-    Ybus --> GridResult
+    ReducedTopo -->|Mathematical topology construction| MathTopo[Mathematical topology]
 
-    GridResult -->|Component extraction| ComponentsOutput(Components result)
+    MathTopo -->|Ybus construction| Ybus(Ybus)
+    Params --> Ybus
+
+    Ybus -->|Solver construction| Equations(Solvable system of equations)
+    Equations -->|Math solving| Solution(Mathematical solution)
+
+    Solution -->|Grid extraction| MacroGridResult(Macro-grid result)
+    Ybus --> MacroGridResult
+
+    MacroGridResult -->|Optional optimization| Params
+
+    MacroGridResult -->|Topological node solving| FullGridResult("Full grid result")
+    ReducedTopo --> FullGridResult
+
+    FullGridResult -->|Component extraction| ComponentsOutput(Components result)
     Components --> ComponentsOutput
 
     ComponentsOutput -->|Output| Output(Output data)

docs/user_manual/components.md

@@ -122,6 +122,67 @@ 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          |
 
+### Link
+
+* type name: `link`
+
+`link` is an [edge](#edge) which usually represents a short internal cable/connection between two busbars inside a
+substation.
+In reality, it has a very high admittance (small impedance).
+
+Because of this, the power-grid-model choses to model this accordingly:
+
+* If there are no node injection sensors in the grid, links are modeled as infinite (but equal) admittance connections.
+* If there are node injection sensors in the grid, link admittances are modeled with a fixed per-unit value, equivalent
+  to 10e6 siemens for a 10kV network.
+
+```{note}
+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.
+```
+
+Because links have very high admittance, it also is chosen by design that no sensors can be coupled to a `link`.
+There are no additional attributes for `link`.
+
+It is explicitly allowed to connect a link between nodes with different voltage levels to allow modeling
+[ideal transformers](./non-native-components.md#ideal-transformer).
+
+#### Electric Model
+
+`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, a large but finite admittance is used:
+
+$$
+Y_{\text{series}} = (1 + \mathrm{j}) \cdot 10^6 \,\mathrm{p.u.}
+$$
+
+##### Handling infinite admittances
+
+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, 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.
+
+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 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`
@@ -170,47 +231,6 @@ $$
 \end{aligned}
 $$
 
-### Link
-
-* type name: `link`
-
-`link` is an [edge](#edge) which usually represents a short internal cable/connection between two busbars inside a
-substation.
-In reality, it has a very high admittance (small impedance).
-
-Because of this, the power-grid-model choses to model this accordingly:
-
-* If there are no node injection sensors in the grid, links are modeled as infinite (but equal) admittance connections.
-* If there are node injection sensors in the grid, link admittances are modeled with a fixed per-unit value, equivalent
-  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.
-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.
-```
-
-Because links have very high admittance, it also is chosen by design that no sensors can be coupled to a `link`.
-There are no additional attributes for `link`.
-
-It is explicitly allowed to connect a link between nodes with different voltage levels to allow modeling
-[ideal transformers](./non-native-components.md#ideal-transformer).
-
-#### Electric Model
-
-`link` is modeled by a constant admittance $Y_{\text{series}}$.
-If there are no node injection sensors in the grid:
-
-$$
-Y_{\text{series}}\rightarrow \infty
-$$
-
-If there are node injection sensors in the grid:
-
-$$
-Y_{\text{series}} = (1 + \mathrm{j}) \cdot 10^6 \,\mathrm{p.u.}
-$$
-
 ### Transformer
 
 `transformer` is a [branch](#branch) which connects two nodes with possibly different
@@ -866,17 +886,15 @@ 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`.
 For example, if a `power_sensor` is measuring a `source`, a positive `p_measured` indicates that the active power flows
 from the source to the node.
 
 ```{note}
-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
@@ -979,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}

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*.