Documentation: Improve Power Flow Method Comparisions

.vscode/README.md

@@ -2,5 +2,7 @@
 
 <!-- SPDX-License-Identifier: MPL-2.0 -->
 
-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.

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)       | &#10004; |          | &#10004; | {py:class}`CalculationMethod.newton_raphson <power_grid_model.enum.CalculationMethod.newton_raphson>`       |
-| [Iterative current](#iterative-current-power-flow) |          |          | &#10004; | {py:class}`CalculationMethod.iterative_current <power_grid_model.enum.CalculationMethod.iterative_current>` |
-| [Linear](#linear-power-flow)                       |          | &#10004; |          | {py:class}`CalculationMethod.linear <power_grid_model.enum.CalculationMethod.linear>`                       |
-| [Linear current](#linear-current-power-flow)       |          | &#10004; |          | {py:class}`CalculationMethod.linear_current <power_grid_model.enum.CalculationMethod.linear_current>`       |
+| Algorithm                                          | Speed                       | Result                            | Convergence         | Typical Use Cases                                                       | Algorithm call                                                                                             |
+|--------------------------------------------------- |---------------------------- |---------------------------------- |-------------------- |------------------------------------------------------------------------ |----------------------------------------------------------------------------------------------------------- |
+| [Newton-Raphson](#newton-raphson-power-flow)       | Medium                      | Accurate within `error_tolerance` | Quadratic, robust   | General purpose, any type of grid                                       | {py:class}`CalculationMethod.newton_raphson <power_grid_model.enum.CalculationMethod.newton_raphson>`      |
+| [Iterative current](#iterative-current-power-flow) | Fast (Radial) Slow (Meshed) | Accurate within `error_tolerance` | Linear, less robust | Non-topological change batch calculations like timeseries, radial grids | {py:class}`CalculationMethod.iterative_current <power_grid_model.enum.CalculationMethod.iterative_current>`|
+| [Linear](#linear-power-flow)                       | Much Faster                 | Approximate                       | Single iteration    | Large number of calculations, troubleshooting iterative methods         | {py:class}`CalculationMethod.linear <power_grid_model.enum.CalculationMethod.linear>`                      |
+| [Linear current](#linear-current-power-flow)       | Much Faster                 | Approximate                       | Single iteration    | Large number of calculations                                            | {py:class}`CalculationMethod.linear_current <power_grid_model.enum.CalculationMethod.linear_current>`      |
 
 ```{note}
 By default, the [Newton-Raphson](#newton-raphson-power-flow) method is used.
@@ -274,6 +274,41 @@ 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)
+, 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 the newton raphson method if the
+network is not radial.
+
+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 recommended 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
+[Power Flow Algorithm Comparisons](https://github.com/PowerGridModel/power-grid-model-workshop/blob/main/demonstrations/Power%20Flow%20Algorithm%20Comparison.ipynb)
+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:
 
 $$

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