Skip to content

WIP improve condition readability (loadflow-validation) #3830

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

Draft
samirromdhani wants to merge 17 commits into
base: main
Choose a base branch
from
Draft

WIP improve condition readability (loadflow-validation) #3830

Show file tree
Hide file tree
Changes from 15 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
4ea0788
refactor(loadflow-validation): WIP improve condition readability
samirromdhani Mar 18, 2026
b885258
review conditions in ShuntCompensators validation WIP
samirromdhani Mar 19, 2026
9903454
refactor(loadflow-validation): remove duplicated code
samirromdhani Mar 19, 2026
5768c19
ShuntCompensator validation review, prepare actions
samirromdhani Mar 20, 2026
2f721d6
ShuntCompensator validation review, prepare example
samirromdhani Mar 20, 2026
b2d959d
SVC validation review
samirromdhani Mar 23, 2026
a5c5ced
SVC validation review, prepare actions
samirromdhani Mar 23, 2026
96843f0
Generators validation review
samirromdhani Mar 23, 2026
8ce175a
Buses validation review
samirromdhani Mar 23, 2026
5f24bb2
notes Flows, TWT and 2W TWT validation
samirromdhani Mar 23, 2026
c3d51eb
improve ShuntCompensator validation rules
samirromdhani Mar 24, 2026
4c4e8ea
improve SVC validation rules wip
samirromdhani Mar 24, 2026
c17af49
fix gaps between current code and current doc for Shunt and SVC
samirromdhani Mar 24, 2026
4667241
improve SVC validation rules
samirromdhani Mar 24, 2026
9389f8d
improve Generator validation rules
samirromdhani Mar 25, 2026
eb54d24
resume SVC rules for valid results
samirromdhani Mar 25, 2026
7a46c3c
resume Generator rules for valid results
samirromdhani Mar 26, 2026
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
42 changes: 28 additions & 14 deletions docs/user/itools/loadflow-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,32 +211,46 @@ $$
\end{align*}
$$

In the PowSyBl validation, there are a few tricks to handle special cases:
In the PowSyBl validation, there are a few tricks to handle special cases before applying the nominal active/reactive/voltage rules
- if `P` or `Q` is missing, validation fails if setpoints are defined and non-zero
- if $minQ > maxQ$, then the values are switched to recover a meaningful interval if `noRequirementIfReactiveBoundInversion = false`
- in case of a missing value, the corresponding test is OK
- $minQ$ and $maxQ$ are function of $P$. If $targetP$ is outside $[minP, maxP]$, no test is done.
- $minQ$ and $maxQ$ are function of $P$. If $targetP$ is outside $[minP, maxP]$, and `noRequirementIfSetpointOutsidePowerBounds = true`, generator validation checks are bypassed.

### Loads
<span style="color: red">To be implemented, with tests similar to generators with voltage regulation.</span>

### Shunts
The two following conditions must be fulfilled in valid results:
### Shunt Compensator
#### Linear model
For connected shunts, the two following conditions must be fulfilled for valid results:

$$
\begin{align*}
\left| P \right| < \epsilon \\
\left| Q + \text{#sections} * B V^2 \right| < \epsilon
\end{align*}
\begin{aligned}
|P| &< \epsilon \\
|Q + N_{\text{sections}} \cdot B \cdot V^2| &< \epsilon
\end{aligned}
$$

Additional condition for disconnected shunts:
- If the shunt is disconnected, `Q` must be undefined (`NaN`) or equal to `0`.
#### Non linear model
<span style="color: red">Is not supported, to be done.</span>

### Static VAR Compensators
The following conditions must be fulfilled in valid results:
$targetP = 0$ MW
- If the regulation mode is `OFF`, then
$$\left| targetQ - Q \right| < \epsilon$$
- If the regulation mode is `REACTIVE_POWER`, same checks as a generator without voltage regulation
The following conditions must be fulfilled for valid results:

- If `regulating = false`, then $|Q| <= \epsilon$.
- $|P - targetP| <= \epsilon$, with $targetP = 0$ MW.
- If `P` or `Q` is missing, then `reactivePowerSetpoint` must be `NaN` or `0`.
- If the regulation mode is `REACTIVE_POWER`, same checks as a generator without voltage regulation:

$|Q - reactivePowerSetpoint| <= \epsilon$.
- If the regulation mode is `VOLTAGE`, same checks as a generator with voltage regulation with the following bounds:
$$minQ = - Bmax * V^2$$ and $$maxQ = - Bmin V^2$$

$minQ = -Bmax * V^2$ and $maxQ = -Bmin * V^2$.
- If $V < voltageSetpoint$, then `Q` must match `maxQ`.
- If $V > voltageSetpoint$, then `Q` must match `minQ`.
- If $|V - voltageSetpoint| <= \epsilon$, then `Q` must be within `[minQ, maxQ]`.

### HVDC lines
<span style="color: red">To be done.</span>
Expand Down
190 changes: 190 additions & 0 deletions loadflow/loadflow-validation/notes/note.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
## Rules / loadflow validation rules review (this file just for review purpose, do not merge )

- [x] ShuntCompensator
- [x] Static VAR Compensator (SVC)
- [x] Generator
- [x] Buses
- [ ] Flows (Branch Data :Line, TwoWindingsTransformer, TieLine)
- [ ] Transformers (TWT)
- [ ] Transformers3W (TWT 3W)

### ShuntCompensator validation

##### Doc
- core grid model: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#shunt-compensator
- core tool loadflow-validation: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#shunts
#### Notes
##### Gaps between current code and current doc:
- Disconnected rule (Rule 3) is missing in docs
- Code/comment includes: if disconnected, Q must be NaN or 0
- doc only lists 2 rules; no disconnected terminal rule.
##### Current doc:
> [!NOTE]
> Rule1: **|p| < e**
>
> if connected, p must be undefined or 0

> [!NOTE]
> Rule2: **| q + #sections * B * v^2 | < e**
>
> if connected, q must match expectedQ (within threshold), ( **expectedQ = - #sections * B * v^2** ==> **| q + expectedQ | < e** )
> - if LinearModel then #sections = bPerSection else #sections = B
> - **bPerSection**: the susceptance per section in S
> - **currentSectionCount** = B (The susceptance of the shunt compensator in its current state)

> [!WARNING]
> Rule3: if the shunt is disconnected, q should be undefined or 0

#### Summary and actions

| | Documentation | Code (ShuntCompensatorsValidation) | Description | Suggestions (TODO) |
|:-----------|:---------------------------------:|------------------------------------------------------------------------------------------------------------------:|----------------------------------------------------------------------------------------------:|--------------------------------------------------------------------------:|
| Condition1 | \|P\| < ε | if(!Double.isNaN(p)) return false | if shunt compensator is connected, p must be undefined | - Add to condition: `or p != 0 return false`, to match the rule \|P\| < ε |
| Condition2 | \| q + #sections * B * v^2 \| < ε | if (ValidationUtils.areNaN(config, q, expectedQ) \| Math.abs(q - expectedQ) > config.getThreshold()) return false | if connected, q must match expectedQ (within threshold) <br/> expectedQ = #sections * B * v^2 | - |
| Condition3 | - | if (!connected && !Double.isNaN(q) && q != 0) return false | if the shunt is disconnected, q should be undefined or 0 | - `add this rule in the doc` |

- Added util methods inValidationUtils
- `isUndefinedOrZero`
- `isOutsideTolerance`
- `isConnectedAndMainComponent`
- `computeShuntExpectedQ`

### Static VAR compensator validation

##### Doc
- core grid model: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#static-var-compensator
- core tool loadflow-validation: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#static-var-compensators

#### Notes
##### Gaps between current code and current doc:
- `OFF` mode in docs does not exist in `SVC validation API`
- In IIDM, StaticVarCompensator.RegulationMode has only:
- VOLTAGE
- REACTIVE_POWER
- => The code equivalent of “OFF” is actually regulating = false.
- Rule for missing P/Q exists in code but not in docs
- Current code behavior:
- if P or Q is NaN, if it fails when reactivePowerSetpoint is defined and non zero.
---
##### Current code rules
> [!NOTE]
> Rule1: active power (p) (within threshold) should be equal to 0

> [!WARNING]
> Rule2: **reactivePowerSetpoint** must be undefined or equal to 0 if NO (**p** or **q**)

> [!WARNING]
> Rule3: **regulationMode = REACTIVE_POWER** then same condition as generator without voltage regulation
> - Rule3.1: => (config, reactivePowerSetpoint, qMin, qMax) not defined => OK
> - Rule3.2: => q must match reactivePowerSetpoint (within threshold)

> [!WARNING]
> Rule4: **regulationMode = VOLTAGE** then same condition as generator with voltage regulation
> - Rule4.1: => (config, qMin, qMax, vControlled, voltageSetpoint) not defined => OK
> - Rule4.2: => V is lower than voltageSetpoint (within threshold) AND q must match qMax (within threshold)
> - Rule4.3: => V is higher than voltageSetpoint (within threshold) AND q must match Qmin (within threshold)
> - Rule4.4: => V is at the controlled bus (within threshold) AND q is bounded within [Qmin=-bMax*V*V, Qmax=-bMin*V*V]

> [!WARNING]
> Rule5: if regulating is false then reactive power (q) should be equal to 0
> - If the regulation mode is OFF: remove this rule from the doc source: #2790

##### Actions

| | Documentation | Code (StaticVarCompensator) | Description | Suggestions (TODO) |
|:-----------|:------------------------------------------------------------------------------------------:|------------------------------------------:|---------------------------------------------------------------------------------:|-------------------------------------------------------------------------------------------------------------:|
| Condition1 | `targetP = 0 MW` | if (Math.abs(p) > Threshold) return false | active power should be equal to 0 | ? |
| Condition2 | - | `checkSVCsNaNValues` | **reactivePowerSetpoint** must be undefined or equal to 0 if NO (**p** or **q**) | - `add this rule in the doc`, - check only if (q undefined or equal to 0 then **reactivePowerSetpoint** ~ 0) |
| Condition3 | `same checks as a generator without voltage regulation` | `reactivePowerRegulationModeKo` | Rule3.1, Rule3.2 | - |
| Condition4 | `same checks as a generator with voltage regulation with the following bounds: Qmin, Qmax` | `voltageRegulationModeKo` | Rule4.1, Rule4.2, Rule4.3, Rule4.4 | - |
| Condition5 | - | `notRegulatingKo` | if regulating is false then reactive power should be equal to 0 | - `add this rule in the doc` |

- Used util methods in ValidationUtils
- `isUndefinedOrZero`
- `isOutsideTolerance`
### Generator validation

##### Doc
- core grid model: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#generator
- core tool loadflow-validation: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#generators
##### Notes (draft)

> [!NOTE]
> Rule1 : If `P` or `Q` is missing, validation fails if setpoints are defined and non-zero

> [!NOTE]
> Rule2 : If reactive limits are inverted (`maxQ < minQ`) and noRequirementIfReactiveBoundInversion = true, generator validation are bypassed.

> [!NOTE]
> Rule3 : active setpoint outside bounds bypass
> If `targetP` is outside `[minP, maxP]` (with tolerance) and noRequirementIfSetpointOutsidePowerBounds = true, generator validation are bypassed

> [!NOTE]
> Rule4: Active power p matches expected setpoint
> Active power p must match setpoint (expectedP) (within threshold)

> [!NOTE]
> Rule5: If voltage regulator is disabled, Q matches targetQ
> Reactive power q should match to setpoint (targetQ) (within threshold) when voltageRegulatorOn = false

> [!NOTE]
> Rule6: If voltage regulator ON, Reactive power q follow V/targetV logic
> - qGen at minQ if V > targetV + threshold
> - qGen at maxQ if V < targetV - threshold
> - else qGen within [minQ, maxQ])

##### Actions TODO

| | Documentation | Code (GeneratorValidation) | Description | Suggestions (TODO) |
|:-----------|:------------------------------------:|-------------------------------------------------------------------------------------------------------------:|-------------------------------------------------------------------------------:|---------------------------------------------------------|
| Condition1 | - | `p or q should be defined if voltage and a target (targetP and targetQ) defined` | - | - `voltage not mentioned in the condition in code TODO` |
| Condition2 | - | `when maxQ < minQ if noRequirementIfReactiveBoundInversion (parameter) return true` | - | - `Add to the doc` |
| Condition3 | - | `when targetP < minP or targetP > maxP if noRequirementIfSetpointOutsidePowerBounds (parameter) return true` | - | - `Add to the doc` |
| Condition4 | (added with recompute of expected P) | | - Active power (p) must match setpoint (expectedP) (within threshold) | |
| Condition5 | \|targetQ - Q\| < ε | `voltageRegulatorOn="false"` | - The reactive power (Q) should match to setpoint (targetQ) (within threshold) | |
| Condition6 | .. | `voltageRegulatorOn="true" ` | - Rule6.1, Rule6.2, Rule6.3, Rule6.4 | |

- Used util methods in ValidationUtils
- `isActivePowerKo`
- `isReactivePowerKo`
- `isVoltageRegulationKo`

### Buses validation

##### Doc
- core grid model:
- core tool loadflow-validation: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#buses
##### Notes
- [x] Rule1: load p = incoming p (within threshold)
- [x] Rule2: load q = incoming q (within threshold)

### Flows validation (Branch Data :Line, TwoWindingsTransformer, TieLine)

##### Doc
- core grid model: ..
- core tool loadflow-validation: ..
- No doc (TODO)
##### Notes (draft)
- Flows (BranchData) can be constructed from
- Line Flows => Line specific rules to clarify (TODO)
- TwoWindingsTransformer Flows => TWT specific rules to clarify (TODO)
- TieLine Flows => TieLine specific rules to clarify (TODO)
- Rule 1: checks disconnected terminal
- Rule 2: checks connected terminal
##### Actions
- Refactor: `isUndefinedOrZero`
- Documentation: add Flows section

### Transformers (TWT) validation TODO

##### Doc
##### Notes
##### Actions

### Transformers3W (TWT 3W) TODO

##### Doc
##### Notes
##### Actions


Loading
Loading