Implement bus <--> signal node connections in phasor dynamics models

[pelesh]

Summary

In order to allow for GridKit to be used in co-simulation context, implement connections allowing for bus voltages to be read by a signal node. Similarly, implement connections where buses can read injection currents from a signal node.

Rationale

Co-simulations are commonly used in industry to connect different simulation tools or to include hardware data streams in hardware-in-the-loop simulations. Phasor domain dynamic co-simulated models are connected by exchanging bus voltages and injection currents between co-simulated parts. Providing signal connection to buses is a step towards enabling co-simulations in GridKit.

Description

Consider adding signal ports like this to the bus model:

• voltage_r
• voltage_i
• injection_current_r
• injection_current_i
  Voltage ports should be outgoing , while current ports should be incoming signal ports.

This is a good time to review signal ports implementation.

Additional information

CC @abirchfield @lukelowry @alexander-novo

[PhilipFackler]

The ComponentSignals class is parameterized on "internal" and "external" variables.

• Is this define-able for buses?
  • If so, what would those variables be?
• What about ports? (e.g., GenrouPorts)
  • Is there a correlate for buses? And how would they relate to internal/external variables?

If these concepts don't exist for buses, we can go a different route.

[pelesh]

The ComponentSignals class is parameterized on "internal" and "external" variables.

• Is this define-able for buses?

  • If so, what would those variables be?

• What about ports? (e.g., GenrouPorts)

  • Is there a correlate for buses? And how would they relate to internal/external variables?

If these concepts don't exist for buses, we can go a different route.

Good point! We need to write down those definitions in the code documentation.

Component internal variables are variables "owned" by the component object. Component external variables are variables entering component's equations but are owned by other objects.

[pelesh]

In case of buses, internal variables will be bus voltages Vr and Vi. External variables will be injection currents Ir and Ii coming from external components. The external component would have to expose its injection current.

For simplicity and for this first stab at the implementation, we can assume each bus can receive only one injection current through the signal node. All other injection currents would be added through regular bus coupling that is already implemented in the code.

For now, it is sufficient if only branches expose their bus injection currents. We don't need other components to do so at this time.

[lukelowry]

As a related note, the IEEEST stabilizer has six signal input configurations:

• (speed) Machine speed deviation
• (???) Bus frequency deviation
• Some machine states (no issues here)
• (???) Bus voltage magnitude
• (???) Derivative of bus voltage magnitude

Bus voltage magnitude (as implemented) is the algebraic var of Bus, and we cannot get the derivative of an algebraic var with the current implementation of signals. Also, we have no way to compute bus frequency (which can be computed in a few ways), but this is more or less the derivative of the voltage angle. Related #369

Not a show stopper, but it would kneecap the stabilizer.

[PhilipFackler]

I'm still working out the semantics of how we use ComponentSignals. I need some clarification.

I see that internal/external variable enums for a given component type have more members than the "Ports" enum for the associated model data class (e.g., GenrouInternalVariables vs GenrouPorts). But looking at the implementation for assigning/attaching signal nodes, it looks like this should be one-to-one relationship. That is, it looks like the component should have a port for each variable...that is, the number of ports should be equal to the total number of internal and external variables.

Is this correct? (and we have simply not yet implemented behavior for the other variables?)

[pelesh]

I'm still working out the semantics of how we use ComponentSignals. I need some clarification.

I see that internal/external variable enums for a given component type have more members than the "Ports" enum for the associated model data class (e.g., GenrouInternalVariables vs GenrouPorts). But looking at the implementation for assigning/attaching signal nodes, it looks like this should be one-to-one relationship. That is, it looks like the component should have a port for each variable...that is, the number of ports should be equal to the total number of internal and external variables.

Is this correct? (and we have simply not yet implemented behavior for the other variables?)

Not all internal variables need to be connected to control devices. For example, we most likely will not need to connect some of the flux variables to the signal nodes. The plan for now is to add signal connections as needed.

[lukelowry]

My mental model has been that ExternalVariables represent variables used in equations that exist at the boundary of the Component or are external to it. So they are either (1) a constant determined by the boundary/initial conditions, or (2) a stand-in for another Components's ExternalVariable or InternalVariable. Then, Ports represent either a Component boundary/input or a variable we choose to expose to the system. Does that align with target @pelesh?

Could we consider moving to something like PortInput and PortOutput for external routing? to better specify ownership and direction

[pelesh]

Could we consider moving to something like PortInput and PortOutput for external routing? to better specify ownership and direction

I think that would be a better solution. To do this, a component would need to instantiate its output ports at runtime based on the component data. Components receiving signal(s) would need to instantiate their input ports, also based on component data populated from JSON input file. Finally, inputs should be connected through signal connectors at runtime.

If inputs are constant, then we should connect them to a signal block with a constant output.

What we have in the code is an "abbreviated" version of signal/physical components.