diff --git a/.vscode/README.md b/.vscode/README.md index d60dd00cce..a6f39267bb 100644 --- a/.vscode/README.md +++ b/.vscode/README.md @@ -2,5 +2,7 @@ -This directory contains example IDE settings and configurations for demonstration purposes only. +# About + +This directory contains example IDE settings and configurations for demonstration purposes only. These settings are not required for working with the project. diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index dc88539853..d02821e5cf 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -247,22 +247,22 @@ Outputs for short circuit calculations always give asymmetric output, independen Two types of power flow algorithms are implemented in power-grid-model; iterative algorithms (Newton-Raphson / Iterative current) and linear algorithms (Linear / Linear current). -Iterative methods are more accurate and should thus be selected when an accurate solution is required. -Linear approximation methods are many times faster than the iterative methods, but are generally less accurate. -They can be used where approximate solutions are acceptable. -Their accuracy is not explicitly calculated and may vary a lot. -The user should have an intuition of their applicability based on the input grid configuration. -The table below can be used to pick the right algorithm. -Below the table a more in depth explanation is given for each algorithm. +Iterative methods converge to accurate solutions through multiple iterations +and should be selected when accurate results are required. +Linear approximation methods perform a single iteration and are significantly faster, but their accuracy depends on grid +conditions and may vary. +The table below summarizes the convergence characteristics and typical use cases for each algorithm to help you pick the +right one. +A more in-depth explanation of each algorithm is given below the table. At the moment, the following power flow algorithms are implemented. -| Algorithm | Default | Speed | Accuracy | Algorithm call | -| -------------------------------------------------- | -------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| [Newton-Raphson](#newton-raphson-power-flow) | ✔ | | ✔ | {py:class}`CalculationMethod.newton_raphson ` | -| [Iterative current](#iterative-current-power-flow) | | | ✔ | {py:class}`CalculationMethod.iterative_current ` | -| [Linear](#linear-power-flow) | | ✔ | | {py:class}`CalculationMethod.linear ` | -| [Linear current](#linear-current-power-flow) | | ✔ | | {py:class}`CalculationMethod.linear_current ` | +| Algorithm | Default | Convergence | Typical Use Cases | Algorithm call | +| --------- | ------- | ----------- | ----------------- | -------------- | +| [Newton-Raphson](#newton-raphson-power-flow) | ✔ | Quadratic, robust | General purpose, meshed networks, accurate results required | {py:class}`CalculationMethod.newton_raphson ` | +| [Iterative current](#iterative-current-power-flow) | | Linear, less robust | Time-series analysis, operational studies, batch calculations, prefer radial grids | {py:class}`CalculationMethod.iterative_current ` | +| [Linear](#linear-power-flow) | | Single iteration | Constant impedance loads only, quick estimates | {py:class}`CalculationMethod.linear ` | +| [Linear current](#linear-current-power-flow) | | Single iteration | Fast approximations | {py:class}`CalculationMethod.linear_current ` | ```{note} By default, the [Newton-Raphson](#newton-raphson-power-flow) method is used. @@ -274,6 +274,42 @@ fastest without loss of accuracy. Therefore power-grid-model will use this method regardless of the input provided by the user in this case. ``` +#### Quick decision guide for power flow algorithm + +The choice of algorithm depends on your specific requirements for (non)convergence, accuracy, speed, +and grid configuration: radial or meshed. +Accuracy and convergence should be the first consideration, followed by speed. + +Hence if speed is not critical or is a small concern, we recommend using the default +[Newton-Raphson](#newton-raphson-power-flow) method for its robustness across all scenarios. +If the scenarios are mainly timeseries, you can try [Iterative current](#iterative-current-power-flow) +then this method can improve speed significantly via +[Matrix prefactorization](performance-guide.md#matrix-prefactorization) +There is a possibility you can face non convergence or lower performance compared to newton raphson method +in case of meshing of networks. + +When speed becomes a major concern and desired performance is not achieved with the iterative methods, you can try to +explore linear methods. +It is recommended to limit the range of loading conditions when using linear methods to avoid unrealistic scenarios +where the approximations can give highly inaccurate results. + +Overall, these methods are reecommended only for a range of possible voltage deviations that are close to 1 p.u. +The linear current method will generally give better approximations than the linear method. +However at unrealistically high load levels it can give worse approximations than the linear method. + +Check Power Flow Algorithm Comparison demonstration in +[PGM workshop demonstrations](https://github.com/PowerGridModel/power-grid-model-workshop) +to know more about this behavior. +A strategy for post calculation verification of results is also provided there. + +You can identify applicability of linear methods for your use case by experimenting with the Newton-Raphson method to +find the range of loading conditions that are relevant for your use case and then +only use linear methods within this range for the specific grid configuration. +Non convergence of newton raphson is a good signal of unpractical or unfeasible systems. +This signal can be ignored when using linear methods. +Similarly, having atleast some results from linear methods can aid in finding data errors or the reason +for non convergence of newton raphson method. + The nodal equations of a power system network can be written as: $$ diff --git a/docs/user_manual/performance-guide.md b/docs/user_manual/performance-guide.md index 987ec6e689..a25f18ef55 100644 --- a/docs/user_manual/performance-guide.md +++ b/docs/user_manual/performance-guide.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: MPL-2.0 # Guidelines for performance enhancement -The `power-grid-model` is a library that shines in its ability to handle calculations at scale. +The `power-grid-model` is designed to handle calculations at scale. It remains performant, even when doing calculations with one or a combination of the following extremes (non-exhaustive): @@ -17,6 +17,11 @@ It remains performant, even when doing calculations with one or a combination of To achieve that high performance, several optimizations are made. To use those optimizations to the fullest, we recommend our users to follow the following guidelines. +```{note} +This guide focuses on system-level performance optimization (batching, caching, parallelization). +For algorithm-level details such as calculation method selection, see the [Calculations](calculations.md) documentation. +``` + ## Data validity Many of our optimizations assume input data validity and rely on the fact that the provided grid is reasonably close to