Operational limits group

[pjeanmarie]

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)

Does this PR already have an issue describing the problem?

Fixes #2110

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

• Yes
• No

If yes, please check if the following requirements are fulfilled

• The Breaking Change or Deprecated label has been added
• The migration steps are described in the following section

What changes might users need to make in their application due to this PR? (migration steps)

Operational limits serialization in IIDM v1.12

For each network element side:
Instead of having objects for currentLimits, activePowerLimits and apparentPowerLimits directly on the network element, they are grouped together in an operationalLimitsGroup object which have an ID.
There can be several operationalLimitsGroup objects but only one is used for limit violations detection. The ID of this "selected" OperationLimitsGroup is indicated by an attribute of the network element.

Example in IIDM

Before (IIDM 1.11):

<iidm:line id="NHV1_NHV2_2" r="3.0" x="33.0" g1="0.0" b1="1.93E-4" g2="0.0" b2="1.93E-4" bus1="NHV1" connectableBus1="NHV1" voltageLevelId1="VLHV1" bus2="NHV2" connectableBus2="NHV2" voltageLevelId2="VLHV2">
  <iidm:activePowerLimits1 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:activePowerLimits1>
  <iidm:apparentPowerLimits1 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:apparentPowerLimits1>
  <iidm:currentLimits1 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:currentLimits1>
  <iidm:activePowerLimits2 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:activePowerLimits2>
  <iidm:apparentPowerLimits2 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:apparentPowerLimits2>
  <iidm:currentLimits2 permanentLimit="350.0">
      <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
      <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
  </iidm:currentLimits2>
</iidm:line>

After (IIDM 1.12):

<iidm:line id="NHV1_NHV2_2" r="3.0" x="33.0" g1="0.0" b1="1.93E-4" g2="0.0" b2="1.93E-4" bus1="NHV1"
         connectableBus1="NHV1" voltageLevelId1="VLHV1" bus2="NHV2" connectableBus2="NHV2"
         voltageLevelId2="VLHV2" selectedOperationalLimitsGroupId1="DEFAULT" selectedOperationalLimitsGroupId2="DEFAULT">
  <iidm:operationalLimitsGroup1 id="DEFAULT">
      <iidm:activePowerLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:activePowerLimits>
      <iidm:apparentPowerLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:apparentPowerLimits>
      <iidm:currentLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:currentLimits>
  </iidm:operationalLimitsGroup1>
  <iidm:operationalLimitsGroup2 id="DEFAULT">
      <iidm:activePowerLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:activePowerLimits>
      <iidm:apparentPowerLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:apparentPowerLimits>
      <iidm:currentLimits permanentLimit="350.0">
          <iidm:temporaryLimit name="20'" acceptableDuration="1200" value="370.0"/>
          <iidm:temporaryLimit name="10'" acceptableDuration="600" value="380.0"/>
      </iidm:currentLimits>
  </iidm:operationalLimitsGroup2>
</iidm:line>

Operational limits are grouped by side in 2 objects operationalLimitsGroup1 (for side 1) and operationalLimitsGroup2 (for side 2). Here, both groups are called with the default id DEFAULT. They are defined as the selected group on both sides with the attributes selectedOperationalLimitsGroupId1="DEFAULT" selectedOperationalLimitsGroupId2="DEFAULT".

When there are several groups for a side n, they are listed using several operationalLimitsGroupn objects. For instance, if a line has the operational limit groups A and B on side 1 and the groups G1 and G2 on side two, the XIIDM will look like:

<iidm:line id="NHV1_NHV2_2" r="3.0" x="33.0" g1="0.0" b1="1.93E-4" g2="0.0" b2="1.93E-4" bus1="NHV1"
        connectableBus1="NHV1" voltageLevelId1="VLHV1" bus2="NHV2" connectableBus2="NHV2"
         voltageLevelId2="VLHV2" selectedOperationalLimitsGroupId1="A" selectedOperationalLimitsGroupId2="G2">
  <iidm:operationalLimitsGroup1 id="A">
      <!-- ... -->
  </iidm:operationalLimitsGroup1>
  <iidm:operationalLimitsGroup1 id="B">
      <!-- ... -->
  </iidm:operationalLimitsGroup1>
  <iidm:operationalLimitsGroup2 id="G1">
      <!-- ... -->
  </iidm:operationalLimitsGroup2>
  <iidm:operationalLimitsGroup2 id="G2">
      <!-- ... -->
  </iidm:operationalLimitsGroup2>
</iidm:line>

For custom IIDM implementations maintainers

If you have defined your own IIDM implementation, you should:

• implement the OperationalLimitGroup interface;

• in your Branch implementations:

  • implement the following methods:

    Collection<OperationalLimitsGroup> getOperationalLimitsGroups1();
    Optional<String> getSelectedOperationalLimitsGroupId1();
    Optional<OperationalLimitsGroup> getOperationalLimitsGroup1(String id);
    Optional<OperationalLimitsGroup> getSelectedOperationalLimitsGroup1();
    OperationalLimitsGroup newOperationalLimitsGroup1(String id);
    void setSelectedOperationalLimitsGroup1(String id);
    void removeOperationalLimitsGroup1(String id);
    void cancelSelectedOperationalLimitsGroup1();
  
    Collection<OperationalLimitsGroup> getOperationalLimitsGroups2();
    Optional<String> getSelectedOperationalLimitsGroupId2();
    Optional<OperationalLimitsGroup> getOperationalLimitsGroup2(String id);
    Optional<OperationalLimitsGroup> getSelectedOperationalLimitsGroup2();
    OperationalLimitsGroup newOperationalLimitsGroup2(String id);
    void setSelectedOperationalLimitsGroup2(String id);
    void removeOperationalLimitsGroup2(String id);
    void cancelSelectedOperationalLimitsGroup2();

  • redefine your implementation of the following methods (note that for some of these, default methods are defined in the interface ancestors, you may just have to remove your own implementation):

    Optional<CurrentLimits> getCurrentLimits1();
    CurrentLimits getNullableCurrentLimits1();
    Optional<ActivePowerLimits> getActivePowerLimits1();
    ActivePowerLimits getNullableActivePowerLimits1();
    Optional<ApparentPowerLimits> getApparentPowerLimits1();
    ApparentPowerLimits getNullableApparentPowerLimits1();
    CurrentLimitsAdder newCurrentLimits1();
    ActivePowerLimitsAdder newActivePowerLimits1();
    ApparentPowerLimitsAdder newApparentPowerLimits1();
  
    Optional<CurrentLimits> getCurrentLimits2();
    CurrentLimits getNullableCurrentLimits2();
    Optional<ActivePowerLimits> getActivePowerLimits2();
    ActivePowerLimits getNullableActivePowerLimits2();
    Optional<ApparentPowerLimits> getApparentPowerLimits2();
    ApparentPowerLimits getNullableApparentPowerLimits2();
    CurrentLimitsAdder newCurrentLimits2();
    ActivePowerLimitsAdder newActivePowerLimits2();
    ApparentPowerLimitsAdder newApparentPowerLimits2();

• in your TieLine and ThreeWindingsTransformer.Leg implementations:

  • implement the following methods:

    Collection<OperationalLimitsGroup> getOperationalLimitsGroups();
    Optional<String> getSelectedOperationalLimitsGroupId();
    Optional<OperationalLimitsGroup> getOperationalLimitsGroup(String id);
    Optional<OperationalLimitsGroup> getSelectedOperationalLimitsGroup();
    OperationalLimitsGroup newOperationalLimitsGroup1String id);
    void setSelectedOperationalLimitsGroup(String id);
    void removeOperationalLimitsGroup(String id);
    void cancelSelectedOperationalLimitsGroup();

  • redefine your implementation of the following methods (note that for some of these, default methods are defined in the interface ancestors, you may just have to remove your own implementation):

    Optional<CurrentLimits> getCurrentLimits();
    CurrentLimits getNullableCurrentLimits();
    Optional<ActivePowerLimits> getActivePowerLimits();
    ActivePowerLimits getNullableActivePowerLimits();
    Optional<ApparentPowerLimits> getApparentPowerLimits();
    ApparentPowerLimits getNullableApparentPowerLimits();
    CurrentLimitsAdder newCurrentLimits();
    ActivePowerLimitsAdder newActivePowerLimits();
    ApparentPowerLimitsAdder newApparentPowerLimits();

Other information:

@flo-dup made the final changes.

[sonarqubecloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
84.5% Coverage on New Code
0.1% Duplication on New Code

See analysis details on SonarCloud