Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .vscode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
77 changes: 64 additions & 13 deletions docs/user_manual/calculations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 | Default | Convergence | Typical Use Cases | Algorithm call |
| --------- | ------- | ----------- | ----------------- | -------------- |
| [Newton-Raphson](#newton-raphson-power-flow) | &#10004; | Fast (quadratic), robust | 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), less robust | Time-series analysis, operational studies, batch calculations, prefer radial grids | {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>` |
Comment thread
Jerry-Jinfeng-Guo marked this conversation as resolved.
Outdated

```{note}
By default, the [Newton-Raphson](#newton-raphson-power-flow) method is used.
Expand All @@ -274,6 +274,57 @@ fastest without loss of accuracy.
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
Comment thread
nitbharambe marked this conversation as resolved.
Outdated

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

Comment thread
nitbharambe marked this conversation as resolved.
Outdated
**When accuracy is critical:**

- Use **Newton-Raphson** when you need high confidence in results
- Required for meshed networks with significant power flows
- Most robust algorithm that works in nearly all scenarios
Comment thread
nitbharambe marked this conversation as resolved.
Outdated
Comment thread
nitbharambe marked this conversation as resolved.
Outdated

**When speed is critical:**

- Use **Linear current** for initial screening, real-time applications, or large-scale studies with many scenarios
Comment thread
nitbharambe marked this conversation as resolved.
Outdated
- Use **Linear** only when loads are truly constant impedance (rare in practice; automatically selected when applicable)
- Accept that approximations may have voltage errors, especially when actual voltages deviate significantly from 1 p.u.

**For balanced performance:**

- Use **Iterative current** for time-series analysis where you need reasonable accuracy with good performance
- Excellent for radial networks and moderately meshed systems
- Particularly efficient for batch calculations (e.g., time-series) as matrix factorization is reused across scenarios

**Grid characteristics to consider:**

- **Radial distribution networks**: All methods work well; Linear current offers good speed/accuracy
balance for approximations
- **Meshed networks**: Newton-Raphson or Iterative current recommended; linear methods may be less accurate
- **Voltage deviations > 5% from nominal**: Prefer Newton-Raphson or Iterative current for accuracy
- **Constant impedance loads only**: Linear method is optimal (automatically selected)

**Load type impact:**

- **Constant power** (most common in practice): Newton-Raphson or Iterative current for accurate results;
Linear current for fast approximations
- **Constant current**: Linear current provides good approximations
- **Constant impedance**: Linear method is exact and fastest

**Quick decision guide:**

1. Start with **Newton-Raphson** (default) - it works reliably for all cases
2. If calculations are too slow for your workflow (e.g., thousands of scenarios) and you can accept
approximations, try **Iterative current** for better accuracy or **Linear current** for maximum speed
3. For real-time or interactive applications requiring sub-second response, use **Linear current**
4. Only use **Linear** if you explicitly model all loads as constant impedance

```{tip}
The accuracy of linear approximation methods depends heavily on how close actual voltages are to 1 p.u.
They are most accurate in well-regulated distribution systems with voltage control.
For transmission systems or heavily loaded networks, iterative methods are recommended.
Comment thread
figueroa1395 marked this conversation as resolved.
Outdated
```

The nodal equations of a power system network can be written as:

$$
Expand Down
7 changes: 6 additions & 1 deletion docs/user_manual/performance-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand All @@ -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
Expand Down
Loading