Skip to content

Docs: improve documentation on slack bus + ideal source - #1463

Merged
figueroa1395 merged 3 commits into
mainfrom
pgm/feature/slack-bus-docs
Jul 7, 2026
Merged

figueroa1395 merged 3 commits into
mainfrom
pgm/feature/slack-bus-docs

Conversation

@mgovers

@mgovers mgovers commented Jul 7, 2026

Copy link
Copy Markdown
Member

Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@mgovers mgovers self-assigned this Jul 7, 2026
@mgovers mgovers added documentation Improvements or additions to documentation improvement Improvement on internal implementation labels Jul 7, 2026
Comment thread docs/user_manual/non-pgm-components.md Resolved
Comment thread docs/user_manual/calculations.md Resolved
Comment thread docs/user_manual/calculations.md Resolved
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@mgovers
mgovers enabled auto-merge July 7, 2026 10:56
@TonyXiang8787

Copy link
Copy Markdown
Member

Hi @mgovers @figueroa1395,

I wonder the usefulness of such a documentation for slack bus. In PGM implementation, we do not use slack bus at all. The name "slack bus" is just some convenient programming variable for the first found source in an island. It does not really have physical meaning.

Explaining this to the user does not seem to be useful.

We can indeed, only explain how to set source parameter so that it will behaves like a real power system slack bus (ideal source). That has actualy meaning for the user.

@figueroa1395

Copy link
Copy Markdown
Member

@TonyXiang8787 This was asked in a recent post, so we thought that since we answered it there, perhaps other users would find that information useful as well, so why not add it to the documentation, since the effort is minimal.

figueroa1395
figueroa1395 previously approved these changes Jul 7, 2026
@mgovers
mgovers added this pull request to the merge queue Jul 7, 2026
@figueroa1395
figueroa1395 removed this pull request from the merge queue due to a manual request Jul 7, 2026
nitbharambe
nitbharambe previously approved these changes Jul 7, 2026
@nitbharambe

Copy link
Copy Markdown
Member

Its actually been asked multiple times in past, including the discussion thread. And the response has indeed been what you mention. This text itself in this PR does not seem to have incorrect statements if we are only comparing slack bus and source bus. It would indeed be misleading though.

Hi @mgovers @figueroa1395,

I wonder the usefulness of such a documentation for slack bus. In PGM implementation, we do not use slack bus at all. The name "slack bus" is just some convenient programming variable for the first found source in an island. It does not really have physical meaning.

Explaining this to the user does not seem to be useful.

We can indeed, only explain how to set source parameter so that it will behaves like a real power system slack bus (ideal source). That has actualy meaning for the user.

@nitbharambe
nitbharambe dismissed their stale review July 7, 2026 12:25

Lets rewrite this doc in a different way that helps a non technical person draw a parallel amongst these concepts.

Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@mgovers
mgovers force-pushed the pgm/feature/slack-bus-docs branch from 74f7025 to 1488a0c Compare July 7, 2026 13:47
@sonarqubecloud

sonarqubecloud Bot commented Jul 7, 2026

Copy link
Copy Markdown

@figueroa1395
figueroa1395 enabled auto-merge July 7, 2026 14:47
@nitbharambe

nitbharambe commented Jul 7, 2026 •

Copy link
Copy Markdown
Member

As per offline discussions, we decided to go ahead with it.

@figueroa1395
figueroa1395 added this pull request to the merge queue Jul 7, 2026
Merged via the queue into main with commit b85e52b Jul 7, 2026
34 checks passed
@figueroa1395
figueroa1395 deleted the pgm/feature/slack-bus-docs branch July 7, 2026 17:10
@llru-fhv

Copy link
Copy Markdown

Hi @mgovers @figueroa1395,

I wonder the usefulness of such a documentation for slack bus. In PGM implementation, we do not use slack bus at all. The name "slack bus" is just some convenient programming variable for the first found source in an island. It does not really have physical meaning.

Explaining this to the user does not seem to be useful.

We can indeed, only explain how to set source parameter so that it will behaves like a real power system slack bus (ideal source). That has actually meaning for the user.

Sorry, but I got surprised to read "In PGM implementation, we do not use slack bus at all". Then, how do you solve the power flow if no slack bus is used? From a mathematical point of view, one has to define the slack node (to set the reference angle) to match the number of variables with the number of power flow equations (then to solve these nonlinear equations, e.g., with Newton Raphson algorithm). From a physical point of view, the selection of the slack bus is also relevant, and normally assigned to the largest generation unit, if there are multiples. Or to the low voltage side of a transformer for low voltage networks.

@mgovers

mgovers commented Jul 30, 2026

Copy link
Copy Markdown
Member Author

Hi @mgovers @figueroa1395,
I wonder the usefulness of such a documentation for slack bus. In PGM implementation, we do not use slack bus at all. The name "slack bus" is just some convenient programming variable for the first found source in an island. It does not really have physical meaning.
Explaining this to the user does not seem to be useful.
We can indeed, only explain how to set source parameter so that it will behaves like a real power system slack bus (ideal source). That has actually meaning for the user.

Sorry, but I got surprised to read "In PGM implementation, we do not use slack bus at all". Then, how do you solve the power flow if no slack bus is used? From a mathematical point of view, one has to define the slack node (to set the reference angle) to match the number of variables with the number of power flow equations (then to solve these nonlinear equations, e.g., with Newton Raphson algorithm). From a physical point of view, the selection of the slack bus is also relevant, and normally assigned to the largest generation unit, if there are multiples. Or to the low voltage side of a transformer for low voltage networks.

Hi @llru-fhv,

Yes exactly, that is where this whole PR came from. We are gradually trying to split the documentation for users from the internal documentation. Quoting the form of the internal documentation we settled on:

PGM does not have the common notion of a slack bus in the sense of an ideal source, both for computational and
ambiguity reasons when there are multiple sources in the grid.
However, it is still useful to select a slack bus to fix the otherwise ambiguous complex phase.

In PGM, slack buses are selected as follows.

  1. Source nodes are slack buses.
  2. If there are multiple isolated islands, each island's source is selected as the slack bus.
  3. If there are multiple sources within an isolated island, it is
    implementation-defined which source node is
    selected as the slack bus.
    The simplest choice is to select the first-occuring source in the input data, but note that this behavior may change
    over time.
The slack bus used by PGM internally differs from the slack bus in the sense of an ideal source.
For documentation on ideal source modeling, please refer to [its documentation](./non-pgm-components.md#ideal-source).

So, yes, we do in fact assign a slack bus internally (the Mathematical interpretation you mentioned), but it is not a slack bus in the classical sense (the Physical interpretation you mentioned).

The reason we make this distinction is that - in principle - there is no "order" in the power flow equations - all nodes are equal. Choosing the gauge is required but arbitrary (by definition of gauge symmetry), so WLOG we can do what we are doing.

I hope that somewhat explains the comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation improvement Improvement on internal implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants