Documentation: Improve Power Flow Method Comparisions by Jerry-Jinfeng-Guo · Pull Request #1306 · PowerGridModel/power-grid-model

Jerry-Jinfeng-Guo · 2026-02-19T14:21:34Z

Improvements as requested in #1003

Methods comparision

Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>

Copilot

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.

Copilot · 2026-02-19T14:25:48Z

docs/user_manual/calculations.md

+#### Choosing the right power flow algorithm
+
+The choice of algorithm depends on your specific requirements for accuracy, speed, and grid characteristics.
+


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.

Copilot · 2026-02-19T14:25:49Z

docs/user_manual/calculations.md

+| Algorithm | Default | Convergence | Typical Use Cases | Algorithm call |
+| --------- | ------- | ----------- | ----------------- | -------------- |
+| [Newton-Raphson](#newton-raphson-power-flow) | &#10004; | 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>` |


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.

mgovers · 2026-02-20T08:43:33Z

docs/user_manual/calculations.md

 Therefore power-grid-model will use this method regardless of the input provided by the user in this case.
 ```

+#### Choosing the right power flow algorithm


probably also good to reference this in the performance guide

Please make an issue for that.

why? it's a very small change that can be added to this PR, or immediately solved as a follow-up if you really don't want to do it in one go

mgovers · 2026-02-20T09:25:43Z

docs/user_manual/calculations.md

+
+- Use **Newton-Raphson** for regulatory submissions, protection studies, or when you need high confidence in results
+- Required for meshed networks with significant power flows
+- Most robust algorithm that works in nearly all scenarios


do we want to explicitly mention that it is more likely to run into convergence issues than iterative current?

Probably a good idea. Also maybe a good idea to re-iterate on contacting us if SparseMatrixError or converge error reaches them.

I would recommend against it. We have this integrated in the error message for SparseMatrixError and convergence errors are not bugs of PGM.

figueroa1395

Looks good to me. Nothing more to add besides what was already pointed out.

docs/user_manual/calculations.md

nitbharambe · 2026-02-26T07:48:16Z

docs/user_manual/calculations.md

+
+- Use **Newton-Raphson** for regulatory submissions, protection studies, or when you need high confidence in results
+- Required for meshed networks with significant power flows
+- Most robust algorithm that works in nearly all scenarios


Add this to table instead under convergence.
Newton raphson: robust
Iterative current: less robust

How do you mean?

nitbharambe · 2026-02-26T07:49:08Z

docs/user_manual/calculations.md

+
+**When speed is critical:**
+
+- Use **Linear current** for initial screening, real-time applications, or large-scale studies with many scenarios


What do initial screening or screening studies mean?

Work that does not require most accurate result but at faster paces.

Let's explicitly write that then.

Co-authored-by: Nitish Bharambe <78108900+nitbharambe@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com>

Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>

docs/user_manual/calculations.md

figueroa1395 · 2026-03-06T09:50:31Z

docs/user_manual/calculations.md

+
+**When speed is critical:**
+
+- Use **Linear current** for initial screening, real-time applications, or large-scale studies with many scenarios


Let's explicitly write that then.

Signed-off-by: Nitish Bharambe <nitish.bharambe@alliander.com>

sonarqubecloud · 2026-03-27T12:09:00Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

figueroa1395

Minor comments only. Looks good to me.

figueroa1395 · 2026-03-30T08:54:52Z

docs/user_manual/calculations.md

+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


Suggested change

then this method can improve speed significantly via

, this method can improve speed significantly via

figueroa1395 · 2026-03-30T08:55:47Z

docs/user_manual/calculations.md

+There is a possibility you can face non convergence or lower performance compared to newton raphson method
+in case of meshing of networks.


Suggested change

There is a possibility you can face non convergence or lower performance compared to newton raphson method

in case of meshing of networks.

There is a possibility you can face non convergence or lower performance compared to the newton raphson method if the network is not radial.

figueroa1395 · 2026-03-30T08:56:48Z

docs/user_manual/calculations.md

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


Is this what you inteded to say with "these" here? Or is it for all methods?

Also, small typo:

Suggested change

Overall, these methods are reecommended only for a range of possible voltage deviations that are close to 1 p.u.

Overall, these methods are recommended only for a range of possible voltage deviations that are close to 1 p.u.

figueroa1395 · 2026-03-30T08:59:06Z

docs/user_manual/calculations.md

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


Suggested change

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.

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.

I just realized this code suggestion is hard to read here. But if you look at the generated docs, you'll see why I suggested this.

figueroa1395 · 2026-03-30T09:03:13Z

@nitbharambe should #1316 follow after this one? Do you think it isn't needed? Or what's the status there?

figueroa1395 · 2026-03-30T09:34:33Z

docs/user_manual/calculations.md

+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)


Let's directly cite what you added in https://github.com/PowerGridModel/power-grid-model-workshop/pull/45/changes

method comparisions

7ef117c

Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>

Jerry-Jinfeng-Guo requested review from Copilot and nitbharambe February 19, 2026 14:21

Jerry-Jinfeng-Guo self-assigned this Feb 19, 2026

Jerry-Jinfeng-Guo added the documentation Improvements or additions to documentation label Feb 19, 2026

Copilot started reviewing on behalf of Jerry-Jinfeng-Guo February 19, 2026 14:22 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes

Merge branch 'main' into documentation/improve_pf_documentation_01

9b942f8

mgovers reviewed Feb 20, 2026

View reviewed changes

Jerry-Jinfeng-Guo marked this pull request as draft February 20, 2026 08:49

mgovers reviewed Feb 20, 2026

View reviewed changes

figueroa1395 reviewed Feb 23, 2026

View reviewed changes

nitbharambe reviewed Feb 26, 2026

View reviewed changes

docs/user_manual/calculations.md Outdated Show resolved Hide resolved

nitbharambe reviewed Feb 26, 2026

View reviewed changes

docs/user_manual/calculations.md Outdated Show resolved Hide resolved

nitbharambe reviewed Feb 26, 2026

View reviewed changes

docs/user_manual/calculations.md Outdated Show resolved Hide resolved

nitbharambe reviewed Feb 26, 2026

View reviewed changes

Jerry-Jinfeng-Guo and others added 5 commits March 2, 2026 13:50

Update docs/user_manual/calculations.md

959fc1d

Co-authored-by: Nitish Bharambe <78108900+nitbharambe@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com>

Update docs/user_manual/calculations.md

53843ef

Co-authored-by: Nitish Bharambe <78108900+nitbharambe@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com>

Update docs/user_manual/calculations.md

ef261ff

Co-authored-by: Nitish Bharambe <78108900+nitbharambe@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com>

cross-reference and fix existing imperfections

50a39f3

Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>

review comment

d00349c

Signed-off-by: Jerry Jinfeng Guo <jerry.jinfeng.guo@alliander.com>

Jerry-Jinfeng-Guo requested a review from nitbharambe March 2, 2026 16:16

Jerry-Jinfeng-Guo marked this pull request as ready for review March 3, 2026 15:42

figueroa1395 reviewed Mar 6, 2026

View reviewed changes

Jerry-Jinfeng-Guo enabled auto-merge March 18, 2026 10:43

nitbharambe added 2 commits March 27, 2026 12:55

add quick decision guide

f0776e1

Signed-off-by: Nitish Bharambe <nitish.bharambe@alliander.com>

cleanup

b33ce48

Signed-off-by: Nitish Bharambe <nitish.bharambe@alliander.com>

nitbharambe disabled auto-merge March 27, 2026 12:17

figueroa1395 reviewed Mar 30, 2026

View reviewed changes

		#### Choosing the right power flow algorithm

		The choice of algorithm depends on your specific requirements for accuracy, speed, and grid characteristics.


		When speed is critical:

		- Use Linear current for initial screening, real-time applications, or large-scale studies with many scenarios

	then this method can improve speed significantly via
	, this method can improve speed significantly via

		There is a possibility you can face non convergence or lower performance compared to newton raphson method
		in case of meshing of networks.

	Overall, these methods are reecommended only for a range of possible voltage deviations that are close to 1 p.u.
	Overall, these methods are recommended only for a range of possible voltage deviations that are close to 1 p.u.

Conversation

Jerry-Jinfeng-Guo commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

figueroa1395 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Mar 27, 2026

Quality Gate passed

Uh oh!

figueroa1395 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

figueroa1395 commented Mar 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants