CLI interface¶

CLI for running Hierarchical Engine for Large-scale Infrastructure Co-Simulations (HELICS).

Supports configurations of federates using plugins
Allows running of federation using a runner configuration

Quick Examples¶

helics --help

Usage: helics [OPTIONS] COMMAND [ARGS]...

  HELICS command line interface

Options:
  --version      Show the version and exit.
  -v, --verbose
  --help         Show this message and exit.

Commands:
  observer
  profile-plot
  run           Run HELICS federation
  server

Usage¶

helics run --path examples/pi-exchange/runner.json --profile
helics profile-plot examples/pi-exchange/profile.txt

helics¶

HELICS Runner command line interface

Usage:

helics [OPTIONS] COMMAND [ARGS]...

Options:

  --version      Show the version and exit.
  -v, --verbose
  --help         Show this message and exit.

Subcommands

kill-all-brokers:
list-brokers:
observer:
profile-plot:
run:
server:

kill-all-brokers¶

Kill all brokers

Usage:

helics kill-all-brokers [OPTIONS]

Options:

  --help  Show this message and exit.

list-brokers¶

List all brokers that are running

Usage:

helics list-brokers [OPTIONS]

Options:

  --help  Show this message and exit.

observer¶

Run helics observer and write data to sqlite file

Usage:

helics observer [OPTIONS]

Options:

  --db-folder DIRECTORY
  --help                 Show this message and exit.

profile-plot¶

Plot profiler output using matplotlib

Usage:

helics profile-plot [OPTIONS]

Options:

  --path PATH  Path to profile.txt that describes profiling results of a
               federation  [required]
  --invert     Invert plot
  --save PATH  Path to save the plot
  --help       Show this message and exit.

run¶

Run HELICS federation defined by a JSON configuration file.

We load a list of federates and a broker from a JSON file and launches federates as separate processes on the local system. We do not handle multi-node environments like a Slurm job or Kubernetes. It starts processes in the background with minimal log routing and error handling.

At the top-level, the configuration file contains - name: Federation name - federates: List of federate configurations - logging_path: (Optional) Custom path for log files - broker: (Optional) Boolean to auto-add broker

Each federate is described by a dictionary with the following keys - name: Unique federate name - directory: Working directory for the federate - exec: Command to execute - env: (Optional) Environment variables to set

Example configuration file:

{
    "name": "ExampleFederation",
    "federates": [
        {
            "name": "federate1",
            "directory": "./federate1",
            "exec": "python simulator.py --name=fed1",
            "env": {
                "HELICS_BROKER_ADDRESS": "127.0.0.1"
            }
        },
        {
            "name": "federate2",
            "directory": "./federate2",
            "exec": "python simulator.py --name=fed2"
        }
    ],
    "broker": true,
    "logging_path": "./logs"
}

Optionally add a broker to the federation
Log output from all federates to files (can be disabled)
Kill all processes if one fails (can be disabled)
Displays errors for all processes if one fails
Handle custom environment variables for each federate

When called, helics run:

Checks if the helics-cli server is available (if –connect-server)
Loads and validates the configuration
Creates log files for each federate (if logging enabled)
Launches all federate processes
Monitors processes for completion or errors
Handles graceful termination on errors or user interruption
Shows error information for failed federates

Returns:

Exits with 0 on success, -1 if duplicate federate names found, or error code 1 on failure.

Usage:

helics run [OPTIONS]

Options:

  --path PATH         Path to config.json that describes all federates
                      [required]
  --silent            Suppress informational output
  --connect-server    Attempt to connect to helics-cli server
  --no-log-files      Disable writing log files to federate
  --no-kill-on-error  Do not kill all federates on error
  --help              Show this message and exit.

server¶

Run helics web server to access web interface

Usage:

helics server [OPTIONS]

Options:

  --open / --no-open  Open browser on startup  [default: open]
  --help              Show this message and exit.