gmlc-tdc / helics-examples Goto Github PK

Right now we don't have any examples that make a practical use of initialization mode. We should add one so that users know how to use it effectively.

I am trying to run the following cpp example from HELICS-Examples repo:
https://github.com/GMLC-TDC/HELICS-Examples/blob/main/cpp/valueFederate1/valueFed.cpp
using instructions:
https://github.com/GMLC-TDC/HELICS-Examples

I have downloaded the HELICS pre-compiled library for cpp (v2.8). I have also set the HELICS_DIR environment variable to the required path:

However, I keep getting the following error in cmake:

We should add an octave pi exchange example

Describe the solution you'd like
In addition to the traditional pub/sub/message handles that the observer captures, add the ability to send custom messages to the observer to be displayed in the web interface.

Describe alternatives you've considered
The messages being sent by federates could be considered logging messages so maybe we just want to think about a way to expose existing logging functionalities to the observer (though this is likely practically impossible to support across all languages and libraries). Maybe is we just display log files?

Alternatively, we could give the observer a "logging" endpoint and just let any federate write to it and display those message in the web interface.

However the implementation, we'll likely need a way of distinguishing the source of the message and probably the time it was received.

Having a working co-simulation that uses the broker server would be helpful for users. It shouldn't be difficult to re-impement that simultaneous co-simulation example using a broker server.

In all User Guide examples where it is possible, convert to using helics_cli internal broker. This makes better use of helics_cli and allows for the demonstration of the profiling functionality most directly.

Describe the solution you'd like
To help with debugging and monitoring in general, create a graphing display/tab where the user can specify one or more values to be plotted in real-time as the federation is running. These would necessarily be values in the database.

We'll have to put in some time and figure out the best way to make this manageable as feature scope could be a problem. Multiple graphs? Multiple axis on each graph? Arbitrary number of traces on each graph?

Create versions of one or two specific examples (maybe Advanced Default as it has value, message, and combo federates) and implement them in all the supported language bindings.

Describe the bug
advanced_default and fundamental_integration are intended to be two implementations of the same functionality and thus should produce the identical results.

Environment (please complete the following information):

• Operating System: Mac
• Language Extension: Python (pyhelics 2.7.1)
• HELICS version: beta, compiled from source

An example of the translator feature has been added to the HELICS-Examples repository but no documentation of the example or the feature exists in the User Guide. These pages need to be added.

Describe the solution you'd like
Currently the web interface queries return a block of text (generally JSON but not always, see GMLC-TDC/HELICS#1746). Once all the queries are returning JSON, we should pretty-print.

Long-term we should think about which of the data fields in each JSON need to be presented to users to minimize the visual clutter.

Create an advanced example that uses as many of the features as possible.

Demonstrate these applications/features so that new users know they are there and know how to use them.

To help new users start their work on creating a new federate, we should create federate template code (for each language we support, ideally) that demonstrates the most common HELICS features, APIs, and configuration options. The template should do enough that it would actually run as an example and uses all the features such that automated testing could be used to ensure that it is kept up to date. It should be internally documented such that it would be clear to new users how all the features are working and where they would need to customize and insert their code.

Due to segfaults seen on some platforms when using matplotlib and helics, the User Guide examples need to load matplotlib before helics.

Describe the solution you'd like
Poor performance of a co-simulation can be challenging to understand and diagnose. Creating a means for users to see where the slow-downs for their federation will be very helpful.

With information on the wall-clock time a federate is requesting time and granted time we should be able to determine which federates are having the largest impact on federation performance. I'm imagining a dedicated portion of the interface to perform profiling evaluation.

I can imagine a graphical representation of the profiling being useful but supporting calculations/metrics that are able to be specific about which federates at which time grants are the holding things up most might be the less visually appealing but more actionable use of the data.

Since the APIs have changed, we will need to support examples for HELICS version 1.x and 2.x

Add an example in the HELICS-examples repo (with supporting documentation in the User Guide, both in the Examples section as well as narrative section) on how to use the iteration APIs.

Describe the bug
The pi-exchange examples for different languages have differences in implementation that make some of them behave differently.

What is the expected behavior?
The pi-exchange federates written in different languages should be drop in replacements for each other when running examples. A pisender written in Python should work with a pireceiver written in C.

We probably should have a travis build of the examples that ideally is triggered from HELICS-SRC commits to develop.

It would be nice if we could actually run them and check as well, but that that will be a next step after compiling.

Describe the solution you'd like
In the design of the web interface and the back-end interface we haven't given any thought on the best schema for handling data from federates when they are iterating at a single tilmestep. I suspect the database will just add new records for pubs/subs at a single timestep but presenting this, even in a table view, can be confusing and less than helpful.

Federates do have an understanding of the integration count but this value is unique to the federate. This can be useful information in sorting out the data but because it is not a unique value, it isn't enough in itself to help sort out the order of the data being exchanged between federates.

Should we migrate HELICS-Examples to use a gitflow or gitflow-like structure/workflow? Notably switching to have a develop branch from which we occassionally pull ready to share versions to masters, and a more strict habit of using new branches and pull requests.

Similarly I'd propose adopting some form of semantic versioning, but perhaps where the first and second numbers match those from HELICS-src, but the third number is kept separate to mange internal updates for examples.

Thoughts?

We should have this set up to run on Travis and appveyor.

Targeted endpoints are the new v3 mechanism the provides co-simulation efficiency advantages over a default endpoint. In our examples, since we always know where the messages are going, we could use targeted over default.

It might be good to make a good example that shows both and can clearly demonstrate the efficiency advantage.

Virtually all (if not all) the User Guide examples end up with the following warning in "broker.log" at the completion of a co-simulation:

[2020-12-23 09:49:32.925] [console] [warning] commWarning||70067-p25hp-dh0jY-KmEiZ-kbGGI (1)::unknown route and no broker, dropping message pub:From (131072) handle(5) size 16 at 604800 to 131073

With help from Phil I've determined it is caused by publications from one federate being sent after the intended receiving federate has disconnected from the federation at the end of the co-simulation. This likely means at least one data point for one federate is not being processed/logged properly with trivial consequences to the co-simulation results.

The biggest problem is that its a warning message that is easy to accidentally generate that is a little obtuse to understand.

The fix is relatively straight-forward: integrate the simulator so that all messages are received before disconnecting the federate. For example, I was able to just have all federates request the same very large time before each disconnected from the federation. This ensured all the federates got all the messages (and ignored some).

Since HELICS Integration Users will be forming their own communication patterns for each tool in the federation, it is unclear if there is a better way of avoiding this warning.

For most/all of the messages the User Guide examples send, they are sent to the default endpoint. The current implementation uses helicsEndpointSendBytesTo() and leaves the destination field blank. Though functionally equivalent, it is philosophically better to use helicsEndpointSendBytes() since that is what the API is there for and we want to set a good example.

Part of the effort to create an example in all the supported languages.

Using the MATLAB language, create an example

To demonstrate an alternative method of writing federate code, create versions of Battery.py and Charger.py where the code only models one of each. This will create 11 federates in total in the federation (5 Batteries, 5 Chargers, 1 Controller) and a lot more config files but it will be a good example of a more direct federation architecture.

I don't know where the fundamental final example fits into the flow of the examples but given that it is largely a repeat of the fundamental integration example, it seems like a good candidate for conversion to the Pythonic API. Let me know if you think this is a good idea.

To help users get a handle on writing new federates, create a video of the process of writing a toy example. Use the opportunity to show off some features and add it as an example to the repository

When running default example with the instruction, I got the following error from the log of the Charger:

Requesting time 6480.0
Granted time 9223372036.854774
EV 1 time 9223372036.854774
Charging current: 3.87 from input Battery/EV1_current
Traceback (most recent call last):
File "/home/developer/HELICS-Examples/user_guide_examples/fundamental/fundamental_default/Charger.py", line 184, in
h.helicsPublicationPublishDouble(pubid[j], charging_voltage[j])
File "/usr/local/lib/python3.10/site-packages/helics/capi.py", line 7750, in helicsPublicationPublishDouble
raise HelicsException("[" + str(err.error_code) + "] " + ffi.string(err.message).decode())
helics.capi.HelicsException: [-10] publications not allowed outside of execution and initialization state

The log of helic_cli is:

helics-cli [info]: Running federation: fundamental_default
helics-cli [info]: Running federate Charger as a background process
helics-cli [info]: Running federate Battery as a background process
helics-cli [info]: Waiting for 3 processes to finish ...
Error: Process Charger has failed, killing other processes
helics-cli [error]: Process broker exited with return code -9
helics-cli [error]: Process Charger exited with return code 1
helics-cli [error]: Process Battery exited with return code 1
helics-cli [info]: Done.
Exception in thread Thread-1:
Traceback (most recent call last):
File "/usr/local/lib/python3.10/threading.py", line 1009, in _bootstrap_inner
self.run()
File "/usr/local/lib/python3.10/site-packages/helics_cli/status_checker.py", line 40, in run
raise HELICSRuntimeError("Error has occurred")
helics_cli.exceptions.HELICSRuntimeError: Error has occurred

Environment: a Docker container based on python:3-slim

return_result got renamed to return_output, and *_result becomes *_call. This is not part of the public API the change is okay.

I'd like to investigate the cause of the long run times in some/many/all of the HELICS examples and see if there's something simple we can do to reduce the runtimes.

Part of the effort to create an example in all the supported languages.

HELICS has a number of callback hooks that are supported in PyHELICS with no good documentation on how to use them..

The current working Python API in the v3 alpha 2 release for sending messages is:

h.helicsEndpointSendBytesTo(endpoint: HelicsEndpoint, destination: str, data: bytes)

If the endpoint has a default destination, this looks like:

h.helicsEndpointSendBytesTo(endpoint: HelicsEndpoint, "", str(message).encode())

$ helics_app --version
3.0.0-alpha.2-helics3-gd501f17 (2020-11-10)

Once the v3 release is complete, we should review the APIs to confirm/update for consistency.

Should we be using `h.helicsEndpointSendBytes' ?

Or this ?

h.helicsEndpointSendBytesTo(endpoint: HelicsEndpoint, str(message).encode(), "")

Describe the bug
The comboFed c example is out of date (as is the run script) and fails to run successfully.

What is the expected behavior?
This example works.

To Reproduce
Build and attempt to run the example with the run files.

Environment (please complete the following information):

• Operating System: Windows
• Language Extension: C
• Eclipse IDE
• HELICS version: 2.6.1

Update the old User Guide examples to work with HELICS v3 and find a good way to distribute them.

User Guide page with list of trouble-shooting techniques, such as check log files, make a query, etc.

For many of the federates in the User Guide their time step is very regular (by design) and rather than calculating the time to be requested, we could use the API HELICS has to make this easy.

Describe the bug
PyPOWER, used in the original set of examples with GridLAB-D, has been unmaintained for some time and is now requiring deprecated versions of numpy (v1.21.5) which contained the asscalar() method. Python v3.10 used numpy v1.23 by default and does not contain that method.

We need to decide what to do about these older examples as they are valuable in that they were using more than Python (GridLAB-D) but were intended to be manageable in terms of installation.

To work around a bug when running the Advanced Default on Ubuntu (that didn't fail on macOS), I updated the way the time data was collected for us in plotting results at the end of the example. This change should be applied to all the examples as it guarantees that the time vector matches the data vector.

There should be an example that is built using it, and is run with it. This could be moved to the examples repo once that is running.

There is no folder for the advanced orchestration example that contains Battery.py, Charger.py, and make_samples.py -- based on the code in https://github.com/GMLC-TDC/HELICS-Examples/blob/main/user_guide_examples/advanced/advanced_orchestration/simple/ev_uq_example.yaml#L15 which expects all 3 of these files to be in the same folder ($(SPECROOT)). My best guess is that line 15 should read $(SPECROOT)/simple/make_samples_merlin.py.

Part of the effort to create an example in all the supported languages.

Describe the solution you'd like
So that users don't need to edit their helics_cli configuration file when using the web interface, use a separate configuration file for configuring the web interface.

Proposed syntax: helics run --path=./runner.json --web=./observer.json

@phlptp informed me there's a flag that can be set to indicate to the broker that a federate should be included in the federation but not count towards the federate count of the federation. This feature should allow the separation of the web interface/observer configuration from the configuration of the rest of the federation.

Setup:
Ubuntu 16.04
CMake 3.5.1
Boost 1.5.8
ZeroMQ 4.1.6
HELICS release v1.3.1

I am unable to run this example successfully. I was able to address a couple of smaller issues that prohibited it from running at all. They are as follows:

1. I needed to add the argument "--target" in the run.sh file. Otherwise the two federates would not communicate. The full run.sh file I use is as follows:
   #!/bin/sh
helics_broker 2 --loglevel=4 > broker.out &
./valueFed --name=fed1 --target=fed2 > fed1.out &
./valueFed --name=fed2 --target=fed1 > fed2.out &
wait

2. Changed line 56 in valueFederate.cpp to publish a double and not int. This is needed as the published property is defined as a double on line 47. I changed line 56 to the following:
   vFed->publish(id, (double) i);

3. Changed \n to std::endl on lines 50,52,54,61 and 64 to force a flush after each write. If the federate would exist cleanly this is not needed, but was a nice easy way to find the point at which it fails.

With the above changes I can run the example but each of the federates will not exit. When the finalize function is invoked the federates will hang indefinitely. Running with gdb gives the following error:

[Thread 0x7ffff5440700 (LWP 15043) exited]
[Thread 0x7ffff5c41700 (LWP 15042) exited]
^C
Thread 1 "valueFed" received signal SIGINT, Interrupt.
0x00007ffff681598d in pthread_join (threadid=140737299871488, thread_return=0x0)
at pthread_join.c:90
90 pthread_join.c: No such file or directory.
(gdb)

And using where gives more information:

#0 0x00007ffff681598d in pthread_join (threadid=140737299871488, thread_return=0x0) at pthread_join.c:90
#1 0x00007ffff7001b97 in std::thread::join() () from /usr/lib/x86_64-linux-gnu/libstdc++.so.6
#2 0x000000000064941b in helics::CommsInterface::~CommsInterface() ()
#3 0x00000000005dab7e in helics::zeromq::ZmqComms::~ZmqComms() ()
#4 0x00000000005dabb2 in helics::zeromq::ZmqComms::~ZmqComms() ()
#5 0x000000000058118d in std::default_delete<helics::zeromq::ZmqComms>::operator()(helics::zeromq::ZmqComms*) const ()
#6 0x00000000005811e3 in std::unique_ptr<helics::zeromq::ZmqComms, std::default_delete<helics::zeromq::ZmqComms> >::reset(helics::zeromq::ZmqComms*) ()
#7 0x0000000000580c3d in std::unique_ptr<helics::zeromq::ZmqComms, std::default_delete<helics::zeromq::ZmqComms> >::operator=(decltype(nullptr)) ()
#8 0x000000000057e1dc in helics::CommsBroker<helics::zeromq::ZmqComms, helics::CommonCore>::~CommsBroker() ()
#9 0x00000000004cba9a in helics::zeromq::ZmqCore::~ZmqCore() ()
#10 0x00000000004cbb0a in void __gnu_cxx::new_allocator<helics::zeromq::ZmqCore>::destroy<helics::zeromq::ZmqCore>(helics::zeromq::ZmqCore*) ()

Any help would be greatly appreciated.

Right now the destination of the filter federate is hard-coded to the Controller. It should be adjusted to always use the original destination of the message so that its filtering action can take place on messages flowing to and from the Controller.

Describe the bug
I do not know whether it was intended. Class name helics in gmlc namespace was changed to csharp in SWIG generated helics.cs at least starting with 2.4.1, may be even earlier.

What is the expected behavior?
It used to be gmlc.helics.helicsGetVersion(). Now I have to change it to gmlc.csharp.helicsGetVersion()

To Reproduce
Steps to reproduce the behavior:
Please provide a minimal working example of the bug if possible.

Environment (please complete the following information):

• Operating System: Windows 10
• Language Extension: csharp
• what compiler or setup process did you use VisualStudio, swig v4.0.0
• HELICS version: v2.4.1

$ helics_app --version

Additional context and information
(e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. stackoverflow, gitter, etc)