Improve docs and tests for PTDF calculation in Flow Decomposition

[caioluke]

Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

What kind of change does this PR introduce?

Enhancement

What is the current behavior?

Lack of clarity in signed PTDF calculation.

What is the new behavior (if this is a feature change)?
Improve docs and tests about PTDF calculation respecting the flow sign convention.

Does this PR introduce a breaking change or deprecate an API?

• Yes
• No

[OpenSuze]

Thank you for your PR !

I have a lot of questions !

1. Do you have any test to highlight this behavior ?
2. Could you document the reason of the sign flipping in the documentation ?
3. Is it an issue with any rescaler that are based on a terminal ?
4. Could you refactor this code to avoid comments ?
5. Could you provide something like an empty contingency to trigger the fixZeroFunctionReference instead of duplicating code ?
6. Why are they not rescaling when there is no contingency ?
7. Should this not be a PR in powsybl-open-loadflow ?

[caioluke]

Thanks for your reply :)

I have a test case but the data is confidential... I will try to come up with a minimal case

[caioluke]

@OpenSuze I managed to create a minimal case where the sign instability presents itself.

It showed up in a different scenario from what I had previously described.
That's why I updated the PR's description.

However, I don't have a fix in mind for this one... Could you have a look and see if you can find anything?

[OpenSuze]

Could you explain why you want to keep the same ptdf sign with or without loss compensation please ?

[caioluke]

Actually, I expect the same PTDF results with or without loss compensation.

In this case the PTDF changes sign (+1 becomes -1) and to avoid thresholding I thought it would be simpler to only compare signs.

[OpenSuze]

Yes, I understand your test but I'm wondering why does it matter to keep the same pdtf value before or after loss compensation ?

From my point of view, loss compensation allows to to DC computations that are closer to AC computations without paying AC computation costs. So having slightly different PTDF between DC-loss-compensated PTDF and AC PTDF is expected.

Futhermore, I don't understand why this test might improve sign stability ?

[caioluke]

Keeping the same PTDF sign matters to have similar (not the same due to losses) allocated flows in flow decomposition results.

Here, PTDFs are not sligthly different, they are as different as they can be (+1 and -1). I'm betting it's a sign issue somewhere.

My test doesn't improve sign stability, it's just a minimal example showing there is one.

I haven't found out why this happens...

[OpenSuze]

I have investigated your issue.

The sign difference of the PTDF comes from the fact that we change the sign of the PTDF value (see SensitivityAnalyser line 93).

If we remove this sign modification, then there is no more issue with your test.
However, this sign modification is here to ensure that burdening flows are positive and relieving flows negative without having to consider the reference flow direction.
This sign modification is only here for easier understanding of the flow decomposition results.
More details are available here

Futhermore, it could be a great idea to refactor the SensitivityAnalyser line 93 to extract a static function with a good name such as respectFlowSignConvention

    static double respectFlowSignConvention(double ptdfValue, double referenceFlow) {
        return referenceFlow < 0 ? -ptdfValue : ptdfValue;
    }

With this in mind, I think the best choice is to acknowledge this sign convention and change your test.

assertEquals(respectFlowSignConvention(ptdfValue1, dcFlow1.get(branchId)), respectFlowSignConvention(ptdfValue2, dcFlow2.get(branchId)), 1E-9);

This solution uses the fact that respectFlowSignConvention is an involution (maybe we should test that as well).
Maybe we should document the sign convention in the PTDF observer part also.

Thanks to @phiedw and @wangjer for their help.

Thank you in advance,

Hugo

[caioluke]

Thank you @OpenSuze @phiedw and @wangjer for this detailed answer!

The behaviour is much clearer to me now :)

I have updated the test and the docs accordingly.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarCloud

[OpenSuze]

Thank you for this PR !