Introduce cosimulation interface component

[PhilipFackler]

Description

Basic implementation of cosimulation component

Closes #393

Proposed changes

Uses two output signals to transmit $V_r$ and $V_i$ from connected bus and two input signals to transfer $I_r$ and $I_i$ to connected bus.

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.

[lukelowry]

Should this be += instead of =? Unless we call the evalResidual before all other components, but check my logic here

[PhilipFackler]

That wouldn't fit MY intuition, but I don't know. I'll defer. @pelesh can you answer this?

[pelesh]

Yes, your intuition is correct, injection currents add to the sum of currents on the bus.

[lukelowry]

Only had one implementation concern regarding correctness.

The facade of the Vr/Vi being treated as an internal variable is confusing to me. What are your thoughts on an auxiliary internal state? That would be more consistent, and since we would only have a small number of CoSim components for any given system model, the state duplication isn't too costly.

[PhilipFackler]

Only had one implementation concern regarding correctness.

The facade of the Vr/Vi being treated as an internal variable is confusing to me. What are your thoughts on an auxiliary internal state? That would be more consistent, and since we would only have a small number of CoSim components for any given system model, the state duplication isn't too costly.

My opinion is that the arrays in ComponentSignals should be based on input/output ports rather than internal/external variables. I would split the Ports enum for a ComponentData implementation into InputPorts and OutputPorts. If we made that change, things would make more sense, because you would only allow signal nodes at actual ports. Internal and external variables seem orthogonal (or at least linearly independent 😸 ) to signal nodes and should not be used here.

All that to say, given the current implementation of ComponentSignals, the CoSim component has to pretend.

[lukelowry]

My opinion is that the arrays in ComponentSignals should be based on input/output ports rather than internal/external variables. I would split the Ports enum for a ComponentData implementation into InputPorts and OutputPorts.

I am a big fan of this solution, this would resolve some modeling vocab concerns I have in our exciter and stabilizers.

[nkoukpaizan]

Setting to draft for now. I have some thoughts, but I'll let @pelesh discuss this offline.

[nkoukpaizan]

Connector::CoSim as a component is confusing to me. Domain experts can chime in on the naming, but my understanding is that Co-Simulation is the approach. Perhaps we can call the class CoSimConnector (unless we plan to add other things to the namespace)? I would understand CoSim::Connector as well, though I expect the co-simulation environment to live outside of PhasorDynamics.

[lukelowry]

CoSim::Connector is okay. Most other power system frameworks actually model the interfacing component as a circuit element, so either a lossless branch with a time delay, or a Bus.

From an electrical perspective a Bus or Branch implementation (BusCoSim, or BranchCoSim) would be correct and has an equivalent circuit model which is nice.

I'm okay with either

[PhilipFackler]

Good points. I was not at all sure about the naming/organizing. Happy to change as you all see fit.

[pelesh]

I would call it BusToSignalAdapter or something along those lines. While we are developing it for use in co-simulations, it is not a co-simulation object itself. I also think "connector" is a misleading name because it is not a model of a physical connector. It is just a modeling "adapter" without physical meaning, used to convert data for use by models of different type.

[pelesh]

I suggest for the purpose of this PR to use temporary names (something that we can search/replace easily).

[nkoukpaizan]

I'm not sure this should inherit from Component. If it does, we will need a README in the Connector folder describing the model. But to me, this should behave closer to the signal nodes or buses than other components.

[pelesh]

I would let it be a component for now (and, yes, we need a README). It connects to a bus and has signal ports, so it can use the infrastructure of a component.

The other end of the connection (outside the scope of this PR) should probably inherit from the bus and allow components to connect to it.

[pelesh]

My opinion is that the arrays in ComponentSignals should be based on input/output ports rather than internal/external variables. I would split the Ports enum for a ComponentData implementation into InputPorts and OutputPorts.

I am a big fan of this solution, this would resolve some modeling vocab concerns I have in our exciter and stabilizers.

This is correct understanding. Signals represent directed communication and are defined by inputs/outputs. Physics-based couplings are based on conservation laws and have associated variables that are external to coupled components.