Event Cues + Branch Trips for more Diverse Simulations

[lukelowry]

Description

After some reflection, I think it is wise to model events as a typed Action performed on a Component, much like BusFault is implemented now.

• A model of the Component class can perform an Action, which is expressed by the implementation of the interface apply(Action) .
• The SystemModel cues a target Component to perform said Action by invoking sys->cue(target, action)
• Alternatively, a component can be directly invoked via target->apply(Action).
• A Study is a timed sequence of Cues and Component targets.

For every event I can consider, this is very intuitive (i.e., Fault a Bus, Fault a Branch, Close/Open a Branch, Oscillate a machine (forced oscillation), Ramp a Signal, etc.).

Proposed changes

• Using this representation, I have implemented a Branch trip action that opens a broad class of studies in Power Systems.
• SystemModel no longer treats BusFaults as a special set of components. In the future, we should probably make Fault or Faultable and interface so that Bus and Branch can implement, so there is no need for a dedicated BusFault component.
• A README for PDSim which details the proposed *.study.json schema.

Checklist

• All tests pass.
• Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
• The new code follows GridKit™ style guidelines.
• There are unit tests for the new code.
• The new code is documented.
• The feature branch is rebased with respect to the target branch.
• I have updated CHANGELOG.md to reflect the changes in this PR. If this is a minor PR that is part of a larger fix already included in the file, state so.

Further comments

Nice to have before we merge #374 so that we can do more diverse studies and non-fault events!

A stepping stone toward a more general solution to #377.

[PhilipFackler]

This took me a while to think about. I kept thinking there has to be a better way to handle this. But honestly (like you mention yourself) until we have more complicated use-cases, we don't need a more complicated solution. This fits the current need quite well.

I like using the concept of "schedule" and moving toward being able to define actions generically on different components.

I have one true request and one subjective complaint. Respectively:

• The SystemModel member by_id_ needs a more descriptive name.
• I don't like the word "cue" here. 😸 This is just preference, and I can easily live with it if it makes sense to everyone else. I would suggest "trigger" or "execute". 🤷 @pelesh thoughts?

Finally, since you are allowing for a case with multiple events at the same time point, you should document the fact that those must be listed consecutively. Maybe add some logic to check for this (or even sort the events with respect to time...). It would be good to have a helpful error when that mistake is made.

[lukelowry]

• I don't like the word "cue" here. 😸 This is just preference, and I can easily live with it if it makes sense to everyone else. I would suggest "trigger" or "execute". 🤷 @pelesh thoughts?

Not married to cue either, tried to be creative, but now I think it's confusing. Some other options:

• Event
• Task
• Directive

We can let @pelesh choose!

Finally, since you are allowing for a case with multiple events at the same time point, you should document the fact that those must be listed consecutively. Maybe add some logic to check for this (or even sort the events by time). It would be good to have a helpful error when that mistake is made.

Agree, I will do so once @pelesh gives feedback

[pelesh]

Having branch faults implemented would be a valuable feature. Thank you, @lukelowry!

As for the earlier questions, my recommendation would be to have two configuration files: model and simulation. Model would describe a grid (and that is already documented and implemented in GridKit), while the simulation file would describe solver settings, simulation time, events, etc.

I think "event" is the most commonly used name for what is described in this PR as "cue".

Given the scope of changes here, my recommendation would be to have documentation-only PR first, and then make changes to the code in a follow on PR. I think we first need to decide how we implement faults and then modify bus faults (if necessary) and add branch faults.

[pelesh]

For a more agile review I suggest we split this PR in documentation/specs and implementation PR, respectively.

[lukelowry]

For a more agile review I suggest we split this PR in documentation/specs and implementation PR, respectively.

I can get behind this. I will break this into two ASAP

Also, just to clarify, the event type I added is not a Branch fault (tho that would be easy to add, now). It's a line opening and closing, which is different from a branch fault.

Doing documentation first will help with clarification!

[pelesh]

I suggest we set this to draft for now. This idea might need more offline discussion.