Mutualize usage rules with powsybl

[pet-mit]

Describe the current behavior

OpenRAO and PowSyBl's security analysis API have different objects that represent the same business concept: the application condition of a remedial action.

• In PowSyBl, the interface is called "Condition". Currently, this can represent 4 cases:
  • Condition can always be True, meaning that the RA will be applied no matter the situation given the conditions of the contingency context are met
  • "all in violation": RA is applied if all network elements of a given set have operational limit violations
  • "any violation": RA is applied if any violation is met in the network
  • "at least one violation": RA is applied if any network element of a given set has operational limit violations
• in OpenRAO, the interface is called "UsageRule" and covers more cases:
  • it can make the RA available, unavailable, or it can force its application
  • it has the concept of instant (of application), contingency (after which the RA can be applied), country, etc

Describe the expected behavior

Try to converge to a common object model, even though it might not be easy!

Describe the motivation

Common code with PowSyBl, and streamlined experience across RAO & sensitivity analysis APIs

Extra Information

No response

[pet-mit]

To share your opinion
@annetill @phiedw @pjeanmarie @obrix @bqth29

[bqth29]

I believe that what you described is some kind of a mix between our UsageMethods and our UsageRules. The big difference comes from the fact that PowSyBl allows multiple CNECs to be included in a Condition whereas in OpenRAO it is only one for the moment.

I guess some changes to include could be:

• An OnConstraint usage rule can have multiple CNECs and must, in addition to the UsageMethod, contain another Enum Field that can be either ANY or ALL to precise how many CNECs must be overloaded for the UsageRule to be triggered
• The OnFlowConstraintInCountry could also be expanded to cover multiple countries at once, such that if all countries (or none) are passed, the any violation case from PowSyBl could be covered

In any case, we should carry this reflection based on the POC in #1050 that attempts to generify UsageRules and make them more flexible.

[bqth29]

Also, based on what I wrote previously, here is how I would map PowSyBl's Conditions on what exists in OpenRAO:

• Always TRUE: that would correspond to OnInstant and OnContingencyState usage rules with a FORCED usage method
• All in violation: that would correspond to an OnConstraint usage rule with several CNECs declared and an ALL strategy (cf. previous answer)
• At least one violation: that would correspond to an OnConstraint usage rule with several CNECs declared and an ANY strategy (cf. previous answer)
• Any violation: I can see several ways to represent this without having to create a new kind of usage rule
  • OnConstraint with all CNECs and ALL strategy
  • OnContraint with empty set of CNECs that implicitly means that all CNECs are considered + ALL strategy
  • OnFlowConstraintInCountry with all countries
  • OnFlowConstraintInCOuntry with no country which implicitly means that all countries are considered

[pet-mit]

Condition class (powsybl-core):

Current usage rules in open-rao:

[pet-mit]

Option 1 : Implement new usage rules

Transformation examples:

[pet-mit]

Option 2 : use OperatorStrategy more extensively, but a big refacto would be needed

Transformation examples:

[pet-mit]

@annetill @obrix @pjeanmarie
We discussed things in our team, there are two options (see above). Option 1 seems a lot easier but does not make use of OperatorStrategy. What do you think?

[pjeanmarie]

What seems common between Rao and powsybl-core, in particular between Security Analysis Condition and Rao UsageRule?

We consider UsageMethod to be specific to Rao, so we will not try to link it to powsybl-core.
We consider we will need a Condition with Country (Area in powsybl-core?) instead of violationIds, for perf reasons, and case with Country seems only an extension of existing Rao UsageRule cases so we will not talk about it here.

Observations:

Rao Instant in UsageRule, with its 'order', seems to be linked to the order of the list of ConditionalActions in a OperatorStrategy:
In theory, in a list of ConditionalAction, the network limits are computed, then the first condition is evaluted, if true its actions are used on the network, and then we compute the new limits and evaluate the second condition etc. For Rao usage-rule, we have the idea of doing actions in a specific order linked to an instant. On powsybl-core side, we have the idea that the conditions are ordered in a list so 'linked to an instant'.

But Instant is also linked to Cnec especially to limits of Cnec, which in powsybl-core seems to be the idea of temporary limits with different duration and permanent limit on network element. Condition seems to be on limit violation ('violationIds') but for now violationIds contains only 'elementIds on which we can have a limit violation' which is not very precise, for instance condition do not have a filter on limit-duration (but we have one on limit-type) and so we cannot target specificaly violation for some temporary limits. (We also cannot target a specific side (or limit holder)). But if each limit (one tatl or patl on one side of a network element) in powybl-core had an id (extend Identifiable) than this id could be use in violationIds to descibe a violation of a specific limit (without adding filter on duration or side). For Rao, we can used these limitIds for violationIds, or we can also imagine that violationIds will contain cnecIds which also target a limit at a specific instant (and a specific contingency).

Proposition for Rao:

Choose option 1 above, in details:

• OnInstant UsageRule: ContingencyContext is NONE if Instant is PREVENTIVE, else ContingecyContext is ALL_CONTINGENCIES. Condition is a TrueCondition.
• OnContingencyState UsageRule: the ContingencyContext is SPECIFIC with the contingencyId of the State and the condition is TrueCondition.
• OnConstraint UsageRule: The Condition is AtLeastOne with the cnecIds in violationIds (or limitIds). The ContingencyContext depends on the Instant (of the usageRule, not of the Cnec) and so its like OnInstant: ContingencyContext is NONE if Instant is PREVENTIVE, else ContingencyContext is ALL_CONTINGENCIES (NB. could be SPECIFIC with the contingency of the Cnec if needed)
  NB. ContingencyContext xor Condition ?

Proposition for Core:

Create id for limits to be used in violationIds (and remove the filter on limit type in Condition because no longer necessary)
Create "ConditionOnCountry"

[pjeanmarie]

plant uml schema (temporary and permanents limits could be added and linked to cnec):

@startuml
'https://plantuml.com/class-diagram
skinparam useBetaStyle true
<style>
     .oneContingency {
        FontColor DeepPink
     }
    .preventive {
     FontColor DarkOrange
    }
    .limitType {
       FontColor Green
    }
</style>
hide <<oneContingency>> stereotype
hide <<preventive>> stereotype
hide <<limitType>> stereotype


package powsybl-core {

SecurityAnalysisRunParameters o-- "many" OperatorStrategy
OperatorStrategy o-- "1" ContingencyContext
OperatorStrategy o-[#red]-- "<color:#red>0, 1, 2, 3, ..." ConditionalActions : <color:#red>stages
note on link: theory: conditional actions are taken one after the other: \n evaluate condition then apply actions, etc\n (practice: current load flow algo do not implement that for now)

interface ContingencyContext
ContingencyContext <|.. ALL
ContingencyContext <|.. ONLY_CONTINGENCIES
ContingencyContext <|.. NONE
ContingencyContext <|.. SPECIFIC 

class SPECIFIC <<oneContingency>>
class NONE <<preventive>>

note top of ALL
all contingencies + preventive
end note

note top of ONLY_CONTINGENCIES
all contingencies without preventive
end note

note top of NONE
<=> preventive
end note

SPECIFIC o.. "1" Contingency : contingencyId

ConditionalActions o-- "1" Condition
ConditionalActions o.. "many" Action : actionIds


interface Condition
Condition <|--- All
Condition <|--- AtLeastOne
Condition <|--- Any
Condition <|--- True

class All {
<color:#blue>List<String> violationIds
}
All o-- "many" LimitViolationType : filter

class AtLeastOne {
<color:#blue>List<String> violationIds
}
AtLeastOne o-- "many" LimitViolationType : filter

class Any {
}
Any o-- "many" LimitViolationType : filter

class Contingency {
}

class Action {
}

class LimitViolation {
<color:#blue>String SubjectId
}
LimitViolation o- "1" LimitViolationType

enum LimitViolationType <<limitType>>

note "In load-flow algo, violationIds should be \nthe same than subjectId in LimitViolation \n(and subjectId is an elementId)" as NoteViolationId
NoteViolationId .. LimitViolation
NoteViolationId .. All
NoteViolationId .. AtLeastOne

}

package powsybl-rao {

RemedialAction <|-- RangeAction
RemedialAction <|-- NetworkAction
RangeAction o.. "1" Action
NetworkAction o-- "many" Action

RemedialAction o--- "many" UsageRule
note on link: logic 'or' relation between usage rules
class UsageRule {
UsageMethod method
}
UsageRule <|- OnInstant
UsageRule <|-- OnContingencyState
UsageRule <|-- OnConstraint

interface Instant {
int <color:#red>order
}
Instant <|.. PREVENTIVE
Instant <|.. OUTAGE
Instant <|.. AUTO
Instant <|.. CURATIVE
class CURATIVE {
String id
}

OnInstant o-[#red]- "1" Instant : <color:#red>action used at
OnContingencyState o-[#red]- "1" State : <color:#red>action used at
OnConstraint o-[#red]- "1" Instant : <color:#red>action used at

class OnFlowConstraintInCountry {
Country country
}
OnInstant <|.. OnFlowConstraintInCountry: xor
OnContingencyState <|.. OnFlowConstraintInCountry: xor

OnConstraint o-- "1" Cnec
interface Cnec
Cnec o-- "1" State
State <|.. NonPrevState
class NonPrevState <<oneContingency>>
State <|.. PreventiveState
class PreventiveState <<preventive>>
NonPrevState o-- "1" Contingency
PreventiveState o-- "1" PREVENTIVE
NonPrevState o..  OUTAGE
NonPrevState o..  AUTO
NonPrevState o..  CURATIVE
class PREVENTIVE <<preventive>>



Cnec <|----- BranchCnec
BranchCnec <|-- "<color:#green>Flow</color>Cnec"
Cnec <|----- "<color:#green>Angle</color>Cnec"
Cnec <|----- "<color:#green>Voltage</color>Cnec"
class BranchCnec {
<color:#purple>Set<BranchThreshold> thresholds
}
BranchCnec o--- "1" NetworkElement
class "<color:#green>Voltage</color>Cnec" {
<color:#purple>Set<Threshold> thresholds
}
"<color:#green>Voltage</color>Cnec" o--- "1" NetworkElement
class "<color:#green>Angle</color>Cnec" {
<color:#purple>Set<Threshold> thresholds
}
"<color:#green>Angle</color>Cnec" o--- "1" NetworkElement: importing
"<color:#green>Angle</color>Cnec" o--- "1" NetworkElement: exporting

class NetworkElement {
<color:#blue>String id
}
}

@enduml