Add simple one-sided co-sim example taking constant current over zmq

[PhilipFackler]

Description

See #469

Introduce a minimal example using zmq for communication between GridKit processes.

Proposed changes

This example duplicates the behavior of the ThreeBusConstantSource example, but with the ConstantSignalSource component removed and its behavior reproduced in the app (external to the system model) with currents being received over zmq from another app.

Checklist

• All tests pass.
• Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
• The new code follows GridKit™ style guidelines.
• [N/A] There are unit tests for the new code.
• The new code is documented.
• The feature branch is rebased with respect to the target branch.
• [N/A] 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

A lot of comments here. 😄 I have numbered them for reference in discussion.

1. I verified locally that the solution output is equal to that of the ConstantSignalSource example.
2. This example code is temporary; longer-term, this will be generalized and moved to the applications directory.
3. This example uses the "step_callback" in Ida::runSimulation rather than managing the stepping itself; this is questionable :), since we are intending to remove that.
4. The app implementation is a bit crude because this proof-of-concept (first attempt) was meant to be non-invasive (no modification to the phasor dynamics libraries). In order to move forward with a more general implementation, we will need some other tools.
   1. The immediate next step would be to add a "branch-terminal-adapter" (not sure what to name it) so that bus voltage (coming in over zmq) could be read from outside the system. This would enable a true co-simulation example with two systems solving in step with one another.
   2. Beyond that, the path diverges depending on how often we want to synchronize: just at every time step OR at every call to evaluateResidual
      1. Every residual: Use the "IOPorts" PR replacement of ComponentSignals. Extend it to make ports configurable...enabling the zmq exchange to be triggered when signals are read from ports.
      2. Every step
         1. Add a modified version of ConstantSignalSource that would use zmq to update its "constant" values.
         2. Use "IOPorts" as-is/was to enable this more naturally from outside the system (no new component needed). This would make the most sense from the application perspective because the application input file could simply specify which signals to assign to the network.

I'll add that in either of the "IOPorts" scenarios the co-simulation "manager" could be set up to exchange all necessary variables in one send/recv.

[pelesh]

It would be good to document code and add a README file with description of the cosimulation app and the example.

[pelesh]

Please document the code per developer guidelines. Also, please add a README file explaining what the co-sim application does.

If changes to the SystemModel class are needed that needs to be tracked in an issue. Modifying SystemModel is out of scope of this PR.

[nkoukpaizan]

I have a few requests for better documentation and (sparse) diagnostic messages. Otherwise looks good.

[superwhiskers]

just one more comment and this should be good to go. runs fine on my machine

[superwhiskers]

one more comment in this file, we should not expect PWD to contain these files. i think it would be an improvement to:

• copy this file to the build/ directory
• change the current working directory to the directory containing the file (retrieved using dirname(1) over realpath(1) over $0)
• then do ./CoSimServer, ./CoSimClient

or do COSIM_DIRECTORY=$(dirname $(realpath $0)) and then ${COSIM_DIRECTORY}/CoSimServer, etc. either works

[superwhiskers]

alternatively, you could substitute in the build/... directory using cmake. your choice

[PhilipFackler]

I added this script as an easy way to run both apps together in the build directory. I'm thinking now that it might be better if it were removed altogether. When the time comes for a full-fledged co-simulation application, there should be a discussion about how users may best launch it. What do you think?

[superwhiskers]

the way i would probably go about doing it is to manually launch a bunch of workers on the hardware you would like to run a simulation on, then have a "frontend" program that is configured with a list of addresses to workers that submits a job to the worker services.

alternatively, perhaps one of these workers is delegated a "leader" and maintains a list of all of the details of a job or something like that and only serves as a way for other workers to retrieve parts of a job to simulate. this would be the only worker the frontend needs to connect to as it could be polled by other workers for more work to do.

maybe this doesn't answer your question, but this is my first thought as to how this could be launched and how it could operate. maybe the direction you were going in was different.

[PhilipFackler]

Oh, yes. 😄 My question was more "should we remove this for now?". But these are definitely interesting ideas for the (future) discussion I was anticipating.