Documentation Index
Fetch the complete documentation index at: https://mintlify.com/GMLC-TDC/HELICS/llms.txt
Use this file to discover all available pages before exploring further.
HELICS provides a set of utility apps that act as lightweight federates for common data-handling tasks. Rather than writing a full federate, you can use the Player to inject pre-recorded values, the Recorder to save what the federation produces, the Clone to capture an entire federate for later replay, the Echo app to verify that messages travel end-to-end, and the Tracer to watch live data on the console. The Source app fills the same role as the Player but generates signals from mathematical functions instead of a data file.
Player
The Player reads a file of time-stamped values or messages and publishes them into the federation at the specified simulation times. It acts as a send-only federate — it never subscribes to anything. Use it to supply known inputs to a federate under test without running the full set of production simulators.
Starting the Player
helics_player player_file.txt --stop 5
helics_app player player_file.txt --stop 5
Player command-line flags
| Flag | Short | Description |
|---|
--stop | | Simulation time at which the player stops |
--local | | Prepend the player’s federate name to all publication keys |
--time_units | | Default time unit for all timestamps in the file (s, ms, us, min, hr, day, ns) |
--datatype | | Default data type for publications |
--marker | | Print a progress message every N seconds of simulation time |
--name | -n | Name for the player federate |
--broker | -b | Address or name of the broker to connect to |
--core | -c | Core type to use |
--coreinit | -i | Core initialization string |
--flags | -f | Named flags for the federate |
--quiet | | Suppress most console output |
# are comments.
# second topic type(opt) value
-1.0, pub1, d, 0.3
1, pub1, 0.5
3, pub1, 0.8
2, pub1, 0.7
# pub 2
1, pub2, d, 0.4
2, pub2, 0.6
3, pub2, 0.9
Values with a negative time are sent during the initialization phase. Values at time 0 are sent immediately after the federation enters the execution phase.
| Identifier | Type | Example |
|---|
d, f, double | Double-precision float | 45.1 |
s, string | String | "this is a test" |
i, i64, int | Integer | 456 |
c, complex | Complex number | 23+2j, -23.1j |
v, vector | Vector of doubles | [23.1,34,17.2,-5.6] |
cv, complex_vector | Vector of complex numbers | [23+2j, -23.1j, 1+3i] |
5) or numbers with units (500 ms, 23.7us). If a number and unit are separated by a space, enclose the value in quotes: "500 ms".
Messages use either a two-timestamp or single-timestamp form:
# Single-timestamp: message sent and delivered at the same time
m 1.0 src dest "this is a test message"
# Two-timestamp: sent at sendtime, delivered at deliverytime
m 1.0 2.0 src dest "this is test message 2"
b64[<base64data>].
JSON Player file
The same data can be expressed in JSON, which is convenient for programmatic generation:
{
"points": [
{ "key": "pub1", "type": "double", "value": 0.3, "time": -1 },
{ "key": "pub1", "type": "double", "value": 0.5, "time": 1.0 },
{ "key": "pub1", "type": "double", "value": 0.7, "time": 2.0 },
{ "key": "pub1", "type": "double", "value": 0.8, "time": 3.0 },
{ "key": "pub2", "type": "double", "value": 0.4, "time": 1.0 },
{ "key": "pub2", "type": "double", "value": 0.6, "time": 2.0 },
{ "key": "pub2", "type": "double", "value": 0.9, "time": 3.0 }
],
"messages": [
{ "source": "src", "dest": "dest", "time": 1.0, "data": "hello" },
{ "source": "src", "dest": "dest", "time": 2.0, "data": "world" }
]
}
stop, local, separator, and time_units can also be set from within the file. Additional files can be loaded via a file element.
Recorder
The Recorder subscribes to publications and captures endpoint messages, saving everything to a file that the Player can replay later. It acts as a receive-only federate.
Starting the Recorder
helics_recorder record_config.txt --stop 100
helics_app recorder record_config.txt --stop 100
Recorder command-line flags
| Flag | Short | Description |
|---|
--output | -o | Output file path |
--tags | | Publication keys to subscribe to (repeatable) |
--endpoints | | Endpoints to capture (repeatable) |
--sourceclone | | Capture all packets from the specified endpoint |
--destclone | | Capture all packets destined for the specified endpoint |
--clone | | Capture all packets to and from the specified endpoint |
--capture | | Capture all publications of a specific federate; supports "fed1;fed2" lists |
--allow_iteration | | Allow iteration on values |
--verbose | | Print captured values to the console in addition to saving them |
--marker | | Print a progress message every N simulation seconds |
--mapfile | | Write progress to a memory-mapped file for external monitoring |
--stop | | Simulation time at which to stop recording |
--name | -n | Name for the recorder federate |
--broker | -b | Address or name of the broker to connect to |
# Subscribe to two publications
sub pub1
subscription pub2
# Capture an endpoint
endpoint src1
# Clone all traffic to/from an endpoint
clone myFederate/output
| Keyword | Description |
|---|
s, sub, subscription | Subscribe to a publication |
endpoint, ept, e | Create an endpoint to receive targeted packets |
source, sourceclone, src | Capture all messages sent from an endpoint |
dest, destination, destclone | Capture all messages sent to an endpoint |
capture | Capture all data from a specific federate |
clone | Capture all messages to and from an endpoint |
JSON Recorder config
{
"subscriptions": [
{ "key": "pub1", "type": "double" },
{ "key": "pub2", "type": "double" }
],
"endpoints": [
{ "name": "src1", "global": true }
]
}
Recorder output
The Recorder writes output in the same format that the Player reads, so any recording can be directly fed back into a federation using the Player. The --verbose flag also echoes every captured value to the screen.
Clone
The Clone app captures a complete snapshot of a specific federate: all its publications, subscriptions, endpoints, and the values and messages they exchange. The output is a single JSON file that a Player can use to replay the captured federate — useful for replacing a slow or expensive simulator with pre-recorded data.
Starting Clone
helics_app clone fed1 -o fed1.json --stop 10
Clone command-line flags
| Flag | Short | Description |
|---|
capture | | Name of the federate to clone (positional argument) |
--output | -o | Output file path (default: clone.json) |
--allow_iteration | | Allow iteration on values |
Clone does not capture nameless publications or filters. Publications in the output are created as global with the name of the original federate, so a Player using the file can have a different federate name without affecting data routing.
Echo
The Echo app responds to every message it receives by sending that message back to its original source, with an optional configurable delay. It is primarily a testing and diagnostics tool: use it to confirm that an endpoint is reachable, that filters are applying transformations correctly, or that round-trip latency is within acceptable bounds.
Starting Echo
helics_app echo echo_config.txt --stop 5
Echo command-line flags
| Flag | Short | Description |
|---|
--delay | | Time delay before echoing the message back |
--stop | | Simulation time at which to stop |
--local | | Prepend the echo federate’s name to endpoint keys |
--name | -n | Name for the echo federate |
--broker | -b | Address or name of the broker |
--core | -c | Core type |
Tracer
The Tracer subscribes to publications and endpoint messages and prints every received value to the console in real time. Unlike the Recorder it does not write to a file — its purpose is to give a live, human-readable view of data flowing through the federation while it runs.
Starting Tracer
helics_app tracer tracer_config.txt --stop 5
Tracer command-line flags
The Tracer accepts the same subscription and capture flags as the Recorder:
| Flag | Short | Description |
|---|
--tags | | Publications to subscribe to (repeatable) |
--endpoints | | Endpoints to monitor (repeatable) |
--sourceclone | | Monitor all packets from an endpoint |
--destclone | | Monitor all packets destined for an endpoint |
--clone | | Monitor all packets to and from an endpoint |
--capture | | Monitor all publications of a specific federate |
--output | -o | Write output to a file as well as the console |
--mapfile | | Write progress to a memory-mapped file |
--stop | | Simulation time at which to stop |
{
"subscriptions": [
{ "key": "pub1", "type": "double" },
{ "key": "pub2", "type": "double" }
],
"endpoints": [
{ "name": "src1", "global": true }
]
}
Source
The Source app generates synthetic signals and publishes them into the federation, functioning like the Player but without a pre-recorded file. Instead of replaying known data, it produces signals from defined mathematical functions. Use it to stress-test federates against controlled waveforms or to generate random probing signals.
Supported signal types include sine waves, ramps, pulses, square waves, and random walks.
Starting Source
helics_app source source_config.json --stop 100
Source command-line flags
| Flag | Short | Description |
|---|
--stop | | Simulation time at which to stop generating signals |
--datatype | | Default publication data type |
--local | | Prepend the source federate’s name to publication keys |
--separator | | Separator character for local publications and endpoints |
--time_units | | Default time unit for timestamps in the config |
--name | -n | Name for the source federate |
--broker | -b | Address or name of the broker |
--core | -c | Core type |
--flags | -f | Named flags for the federate |
Signal definitions for the Source app are specified in its JSON config file, where you define each output’s function type, frequency, amplitude, and other parameters.
Connector
The Connector app automatically wires unconnected interfaces together using rules defined in a match-file, eliminating the need to manually specify every connection in large federations. It queries the federation during initialization, identifies unconnected publications, inputs, and endpoints, then creates the connections according to the rules before the simulation begins. Once all connections are made, the Connector exits the federation.
Starting Connector
helics_connector matchfile.txt
# Connect inp1 to pub1 (from_to direction)
inp1 pub1 from_to
# Bidirectional matching: either interface may be unconnected
inp2 pub2 bi
# Match with tags (only connects if tag1 is set on a federate)
inp3 pub3 from_to tag1
from_to (origin must be unconnected), to_from (target must be unconnected), and bi (either may be unconnected). Tags allow connections to be filtered by global values or federate tags.
Regex matching
For large federations with many similarly-named interfaces, use regular expressions in the match-file:
REGEX:pub_num_(?<interface_num>\d*)_(?<alpha_index>[A-Za-z]*), REGEX:input_num_(?<interface_num>\d*)_(?<alpha_index>[A-Za-z]*)
interface_num and alpha_index) must match between the source and target patterns. This would connect pub_num_1_a to input_num_1_a, pub_num_204_voltage to input_num_204_voltage, and so on.
Connector command-line flags
| Flag | Description |
|---|
--connection | Specify a single connection inline: --connection INTF1,INTF2,DIRECTIONALITY |
--match_target_endpoints | Also connect unconnected target endpoints |
--match_multiple | Allow one source to match multiple targets (default: false) |
--always_check_regex | Apply regex rules even when direct match rules also exist |
The Connector also supports a two-phase interface creation workflow in which federates report their potential interfaces via a query, the Connector determines which ones to activate, and then sends commands back to the federates before the execution phase begins. See the Connector source documentation for details.