diff --git a/docs/advanced_documentation/core-design.md b/docs/advanced_documentation/core-design.md index 0e1d0382bc..aabe682dcc 100644 --- a/docs/advanced_documentation/core-design.md +++ b/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) diff --git a/docs/user_manual/components.md b/docs/user_manual/components.md index 5968351858..5f014f033d 100644 --- a/docs/user_manual/components.md +++ b/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,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 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`. @@ -875,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 @@ -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} 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*.