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]

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.

[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.

[PhilipFackler]

@nkoukpaizan after name changes, I believe this PR should be ready for review again. Let me know what you think.

[nkoukpaizan]

A couple of minor comments.

The Jacobian may be out of scope for this PR. Just let me know if you want me to take a crack at the implemetation.

[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.

I believe that was the original intent: You would have signal-in, signal-out and bus ports. Note that electrical buses cannot be considered in or out because they enforce algebraic constraints, which are not directional.

[nkoukpaizan]

This is almost there in my opinion. I would just add a REAME file to the folder describing the purpose of the component and the ports (reads voltages from the bus to make them available via signals and adds external current injections).

[nkoukpaizan]

Suggested change

	static constexpr auto IREAL = BusToSignalAdapterExternalVariables::IREAL;
	static constexpr auto IIMAG = BusToSignalAdapterExternalVariables::IIMAG;
	if (signals_.template isAttached<IREAL>())
	{
	bus_->Ir() += signals_.template readExternalVariable<IREAL>();
	}
	if (signals_.template isAttached<IIMAG>())
	{
	bus_->Ii() += signals_.template readExternalVariable<IIMAG>();
	}

I don't think this is needed in initialize. evaluateResidual is sufficient.

[nkoukpaizan]

Please update the comments. I would include somewhere in those comments that this component only passes bus voltages and updates residual information, which justifies ignoring the indices.