Documentation: Improve Power Flow Method Comparisions#1306
Documentation: Improve Power Flow Method Comparisions#1306Jerry-Jinfeng-Guo wants to merge 1 commit intomainfrom
Conversation
Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>
Jerry-Jinfeng-Guo
added
the
documentation
There was a problem hiding this comment.
Pull request overview
Updates the user manual’s power flow documentation to help users choose an appropriate calculation method (per #1003) by adding a more practical comparison and selection guidance.
Changes:
- Replaces the power flow algorithm comparison table with columns focused on convergence and typical use cases.
- Adds a “Choosing the right power flow algorithm” section with selection guidance based on accuracy, speed, and grid characteristics.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| #### Choosing the right power flow algorithm | ||
|
|
||
| The choice of algorithm depends on your specific requirements for accuracy, speed, and grid characteristics. | ||
|
|
There was a problem hiding this comment.
The new #### Choosing the right power flow algorithm subsection now implicitly contains all following content until the next #### heading. This means the general nodal-equation explanation and bus type list end up nested under “Choosing…”, which is likely unintended and makes the document structure confusing. Consider moving this “Choosing…” section further down (e.g., after the general formulation section), or adding an explicit sibling subsection heading (e.g., “Power flow formulation”) before the nodal equations so the scope is clear.
| | Algorithm | Default | Convergence | Typical Use Cases | Algorithm call | | ||
| | --------- | ------- | ----------- | ----------------- | -------------- | | ||
| | [Newton-Raphson](#newton-raphson-power-flow) | ✔ | Fast (quadratic) | General purpose, meshed networks, accurate results required | {py:class}`CalculationMethod.newton_raphson <power_grid_model.enum.CalculationMethod.newton_raphson>` | | ||
| | [Iterative current](#iterative-current-power-flow) | | Moderate (linear) | Time-series analysis, operational studies, batch calculations | {py:class}`CalculationMethod.iterative_current <power_grid_model.enum.CalculationMethod.iterative_current>` | | ||
| | [Linear](#linear-power-flow) | | Single iteration | Constant impedance loads only, quick estimates | {py:class}`CalculationMethod.linear <power_grid_model.enum.CalculationMethod.linear>` | | ||
| | [Linear current](#linear-current-power-flow) | | Single iteration | Fast approximations, screening studies, real-time applications | {py:class}`CalculationMethod.linear_current <power_grid_model.enum.CalculationMethod.linear_current>` | |
There was a problem hiding this comment.
This table update drops the previous at-a-glance “Speed” and “Accuracy” comparison in favor of “Convergence” and “Typical Use Cases”. Since the surrounding text in this section emphasizes choosing based on speed vs accuracy, consider either keeping speed/accuracy columns (even as qualitative labels), or adjusting the surrounding prose so the selection criteria aligns with what the table presents.
|
1 participant
Improvements as requested in #1003