Skip to content

docs: add scalability guidance #1413

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
william-xue wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −0
Open

docs: add scalability guidance #1413

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 8 additions & 0 deletions docs/user_manual/performance-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,14 @@ 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.

## Scalability

The calculation workload generally depends on the number of connected grid elements and on the network topology.
For radial distribution grids, most calculation steps scale close to linearly with grid size.
Copy link
Copy Markdown
Member

@mgovers mgovers Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For radial distribution grids, most calculation steps scale close to linearly with grid size.
For radial distribution grids, all calculation steps scale (amortized) linearly with grid size.

It's probably also good to explicitly state that it is O(n_nodes + n_branches + ...)

Meshed grids require more coupling between buses and branches, so some steps can scale less favorably.
Copy link
Copy Markdown
Member

@mgovers mgovers Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Meshed grids require more coupling between buses and branches, so some steps can scale less favorably.
Meshed grids require more coupling between buses and branches and will result in quadratic scaling in the largest loop in the mesh (worst case: `O(n_nodes * n_branches)`)

In both cases, runtime and memory usage are also affected by the number of batch scenarios, the amount of update data per
scenario, and whether the topology can be reused between scenarios.

Copy link
Copy Markdown
Member

@mgovers mgovers Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since someone reading this is interested in scalabiltity, and we've already done the full analysis in https://github.com/orgs/PowerGridModel/discussions/24 , please:

```{note}
Copy link
Copy Markdown
Member

@mgovers mgovers Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this note should not be part of this section; please restore the original order

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.
Expand Down