Debugging

Debugging a co-simulation can be challenging. There are often many components running a on multiple machines and traditional debugging doesn’t work that well for coordinating since the processes are often independent. Enhancing the tools for debugging a HELICS based co-simulation is one area of focus for the coming year and we expect significant changes and improvements as we gain experience in this area. There are now a few basic capabilities in HELICS that support and help with debugging. Those capabilities are outlined in this document and will continue to be expanded.

Queries

Queries are regarded as a key component of debugging. They are asynchronous from the main simulation timing and can be used from anywhere in the co-simulation. There are a number of queries that can be used to get the publications, inputs, endpoints, and filters in a co-simulation and get structures with the connections between them. See Queries for more details on the specific queries and how to execute them.

HELICS-CLI

The HELICS CLI tool is a tool that can help set up a co-simulation and will eventually have significant debugging capabilities which make use of the underlying capabilities documented here. It is recommended that this tool be used to help with debugging.

Global Time Barrier

The capability of halting execution at a particular simulation time is a fundamental underlying capability for debugging a co-simulation. The global time barrier capability in HELICS will prevent any simulation that has not reached the given time from granting any time greater or equal to the barrier time. If the barrier is issued and a federate is already passed the given time, it will be blocked at its current time. Once a barrier is issued it will not halt an executing co-simulation until a requestTime operation is called by the federate. There are two mechanisms for creating a barrier, some API calls on the broker, and through a REST API in the webserver.

API calls

The Broker API has two functions related to the time barrier

setTimeBarrier(Time time);
clearTimeBarrier();

For the C API

helicsBrokerSetTimeBarrier(helics_broker brk, helics_time time, helics_error *err);
helicsBrokerClearTimeBarrier(helics_broker brk);

For Python and the other language API’s

helicsBrokerSetTimeBarrier(helics_broker brk, helics_time time)
helicsBrokerClearTimeBarrier(helics_broker brk)

The first function creates or updates a time barrier. The second clears it. There are no restrictions on what can be done. Simulations start at time 0 so giving a negative time to the setTimeBarrier operation will effectively clear the barrier.

Webbserver interface

Barriers can also be created and updated through the Webserver. This includes the websocket server and the HTTP REST API components of the webserver.

Barriers can be created or updated with an HTTP post command <webserver>\<broker_name>\barrier with time=<value> in the body. The time can be specified as decimal seconds of simulation or as a value+unit such as “15 ms” or “34 min”

They can be deleted through an HTTP delete command to <webserver>\<broker_name>\clear_barrier

Json instructions are also accepted to a websocket interface. Some examples follow:

{
  "command": "barrier",
  "broker": "broker1",
  "time": 15.5
}
{
  "command": "barrier",
  "broker": "broker1",
  "time": "275 ms"
}
{
  "command": "barrier_clear",
  "broker": "broker1"
}

It is expected that some additional mechanics for handling time barriers and manipulating them at finer granualarity will be available in the future and particularly in HELICS 3.0