Skip to content
Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS)
C++ C CMake Java Python MATLAB Other
Branch: master
Clone or download

Latest commit

nightlark Add spack install to list of package managers (#1169)
* Add spack install to available package managers

* Add link to package managers page in QuickStart install
Latest commit 2ab5cc8 Apr 1, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Toml11 update (#1151) Mar 20, 2020
.githooks Fix pre-commit hook to no longer block Dec 16, 2019
.github Add 'helics-release-build' dispatch event trigger (#1123) Mar 6, 2020
ThirdParty Toml11 update (#1151) Mar 20, 2020
benchmarks Fix the timing benchmark federates names Mar 14, 2020
config Fix linking with C++ MPI library in OpenMPI2 installs (#1163) Mar 27, 2020
docs Add spack install to list of package managers (#1169) Apr 1, 2020
examples Test fails (#1143) Mar 23, 2020
interfaces change CSharp interface module name to be helics instead of csharp (#… Mar 20, 2020
src Query cleanup (#1160) Mar 27, 2020
tests Query cleanup (#1160) Mar 27, 2020
.cirrus.yml Add FreeBSD CI build (#1105) Mar 1, 2020
.clang-format Tsan failure fixes (#964) Dec 9, 2019
.clang-tidy More code tidy (#593) Jan 15, 2019
.cmake-format.json Cmake update (#845) Oct 15, 2019
.codacy.yml do some cleanup of the codacy identified issues (#731) Jul 15, 2019
.codecov.yml Core app tests (#1152) Mar 22, 2020
.editorconfig Renormalize line endings for md, json, player, and bat files (#1107) Mar 3, 2020
.gitattributes Renormalize line endings for md, json, player, and bat files (#1107) Mar 3, 2020
.gitignore Matlab example update (#429) Aug 9, 2018
.gitmodules Switch to netif git submodule (#1103) Feb 29, 2020
CMakeLists.txt update changelog and release notes and some other docs in preparation… ( Mar 27, 2020 Minor doc formatting changes Nov 11, 2019 Switch to netif git submodule (#1103) Feb 29, 2020
DISCLAIMER update the copyright notice and license file to match lab standards (#… Feb 20, 2019
LICENSE remove some line breaks in the license file so github detect the lice… Mar 28, 2019
NOTICE update the copyright notice and license file to match lab standards (#… Feb 20, 2019 Add spack install to list of package managers (#1169) Apr 1, 2020
appveyor.yml update changelog and release notes and some other docs in preparation… ( Mar 27, 2020

CircleCI Documentation Status Releases

Build Status

Service Master Develop
Travis CI Build Status Build Status
Azure Build Status Build Status
Appveyor Build Status Build Status
Coverage codecov codecov

Table of contents


Welcome to the repository for the Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS). HELICS provides an open-source, general-purpose, modular, highly-scalable co-simulation framework that runs cross-platform (Linux, Windows, and Mac OS X). It is not a modeling tool by itself, but rather an integration tool that enables multiple existing simulation tools (and/or multiple instances of the same tool), known as "federates," to exchange data during runtime and stay synchronized in time such that together they act as one large simulation, or "federation". This enables bringing together established (or new/emerging) off-the-shelf tools from multiple domains to form a complex software-simulation without having to change the individual tools (known as "black-box" modeling). All that is required is for someone to write a thin interface layer for each tool that interfaces with existing simulation time control and data value updating, such as through an existing scripting interface. Moreover, the HELICS community has a growing ecosystem of established interfaces for popular tools, such that many users can simply mix and match existing tools with their own data and run complex co-simulations with minimal coding.

Today the core uses of HELICS are in the energy domain, where there is extensive and growing support for a wide-range of electric power system, natural gas, communications and control-schemes, transportation, buildings, and related domain tools. However, it is possible to use HELICS for co-simulation in any domain. Previous and existing HELICS efforts have stretched across a wide range of scales in time and space: From transient dynamics (e.g. power system frequency response or electromechanical transient simulation) through steady-state power flow and markets to long-term planning studies. And from individual appliance behaviors, through distribution & bulk systems, and to nation-wide simulations.

HELICS is also highly scalable, enabling everything from simple connections between 2 software federates on a laptop to large-scale simulations with 10s of thousands of federates (or more) running on high-performance computers, in the cloud, or a mix of all of these. Written in modern C++ (C++14), HELICS provides a rich set of APIs for other languages including Python, C, Java, Octave, Julia, and Matlab. nim and C# APIs are available on an experimental basis, and with an active open-source community, the set of supported languages and simulation tools is growing all the time.

Brief History: HELICS began as the core software development of the Grid Modernization Laboratory Consortium (GMLC) project on integrated Transmission-Distribution-Communication simulation (TDC, GMLC project 1.4.15) supported by the U.S. Department of Energy's Offices of Electricity Delivery and Energy Reliability (OE) and Energy Efficiency and Renewable Energy (EERE). As such, its first use cases were around modern electric power systems, though today it is used for a much larger range of applications. HELICS's layered, high-performance, co-simulation framework builds on the collective experience of multiple national labs.

Motivation: Energy systems and their associated information and communication technology systems are becoming increasingly intertwined. As a result, effectively designing, analyzing, and implementing modern energy systems increasingly relies on advanced modeling that simultaneously captures both the cyber and physical domains in combined simulations.



Each release comes with a Windows installer and zip file containing the HELICS apps and C shared library with Python 3.6 and Java 1.8 interfaces, zip files containing compiled HELICS static libraries built against several MSVC versions, and an archive containing just the C shared library with headers. For building with Debug support it is generally recommended to build from Source or use HELICS as a subproject.


Some support to Conda is provided see conda install for the instructions. It is supported through a separate repo.


Support for installing the Python interface and HELICS apps is provided with pip, see pip install for the instructions. The files used to build the pip package are in a separate repo.


HELICS can be installed on Linux (and macOS) using Spack, a package manager aimed at HPC environments. See spack install for the instructions.

Build from Source Instructions




Getting Started

We've created a series of roughly 10-minute mini-tutorial videos that discuss various design topics, concepts, and interfaces, including how to use the tool. They can be found on our YouTube channel.

The Introduction to the HELICS documentation goes through a series of examples that step through the basic usage and concepts of HELICS.

Several examples of HELICS federates and projects are located in HELICS-Examples. This repo provides a number of examples using the different libraries and interfaces.

The HELICS-Tutorial repository provides a series of tutorials using HELICS to build a co-simulation using domain-specific external modeling tools that is built around an electric power system use case with integrated transmission-distribution-market-communication quasi-steady-state-timeseries (QSTS) simulation.

The HELICS-Use-Cases repository includes examples for a growing range of research use cases for inspiration.

A Users guide for getting started

A Tutorial was prepared for the IEEE PES General meeting in Atlanta. The example materials are available on Binder.


Our ReadTheDocs site provides a set of documentation including a set of introductory examples, a developers guide, complete Doxygen generated API documentation, and more. A few more questions and answers are available on the Wiki.

Additionally, our initial design requirements document can be found here, which describes a number of our early design considerations and some directions that might be possible in the future.


For a history of changes to HELICS


For a snapshot of some current plans for what is to come


Some of the HELICS apps are available from docker. This image does not include any libraries for linking just the executables. helics_broker, helics_app, helics_recorder, helics_player, and helics_broker_server. Other images are expected to be available in the future. See Docker for a few more details.

Tools with HELICS support

As a co-simulation framework, HELICS is designed to bring together domain-specific modeling tools so they interact during run time. It effectively tries to build on the shoulders of giants by not reinventing trusted simulation tools, but instead, merely acting as a mediator to coordinate such interactions. HELICS's full power is only apparent when you use it to combine these domain-specific tools.

Thankfully the HELICS API is designed to be minimally invasive and make it straightforward to connect most any tool that provides either a scripting interface or access to source code. As listed below, a growing set of energy domain tools have HELICS support either natively or through an external interface. We also provide a set of helper apps for various utility and testing purposes.

We are always looking for help adding support for more tools, so please contact us if you have any additions.


HELICS helper Apps

  • HELICS CLI provides a simple way to automate configuring, starting, and stopping HELICS co-simulations.
  • Player, which acts as a simple send-only federate that simply publishes a stream of timed HELICS messages from a user-defined file. HELICS Player is included in the HELICS distribution.
  • Recorder, which acts as a simple receive-only federate that prints out or saves messages from one or more subscribed streams. HELICS Recorder is included in the HELICS distribution.
  • Broker, which is a command line tool for running a Broker. There is also a Broker Server which can generate brokers as needed, and can include a REST API.
  • App is a general app executable which can run a number of other apps including Player and Recorder, as well as a Tracer, Echo, Source, and Clone.


Contributors are welcome see the Contributing guidelines for more details on the process of contributing. And the Code of Conduct for guidelines on the community expectations. All prior contributors can be found here

Optional components

A list of optional component that are not included in HELICS but are optionally used by the library


ZeroMQ message passing is used in the ZMQ core networking. The automatic download currently uses version 4.3.1. No ZMQ library code is included in the HELICS source. HELICS installers include ZeroMQ binary libraries. ZeroMQ is licensed under LGPL with a modification to allow for linking and in various forms and distribution of the binary under different terms if the library was not modified. Clarification on static linking being okay can be found in this github issue. No modification of the ZMQ library or any of the ZeroMQ source files is included in the HELICS source code. Currently the Windows installers and shared library builds static link ZeroMQ. When building from source it is an optional component and can be excluded by setting ENABLE_ZMQ_CORE to OFF

Google Test

HELICS tests are written to use the Google Test and mock frameworks. Google Test is included in the source tarball but is downloaded as an optional component. Google Test is released with a BSD-3 clause license.

Google Benchmark

Some timing benchmarks with HELICS are written to use the Google Benchmark library. Benchmarks is an optional component and is not included in the main source tarball and must be downloaded separately. Google Benchmark is released with an Apache 2.0 license.


[1] B. Palmintier, D. Krishnamurthy, P. Top, S. Smith, J. Daily, and J. Fuller, “Design of the HELICS High-Performance Transmission-Distribution-Communication-Market Co-Simulation Framework,” in Proc. of the 2017 Workshop on Modeling and Simulation of Cyber-Physical Energy Systems, Pittsburgh, PA, 2017. pre-print | published

In the News

HELICS was selected as an R&D 100 Award Finalist.

Source Repo

The HELICS source code is hosted on GitHub:


HELICS is distributed under the terms of the BSD-3 clause license. All new contributions must be made under this license. LICENSE

SPDX-License-Identifier: BSD-3-Clause

portions of the code written by LLNL with release number LLNL-CODE-739319

You can’t perform that action at this time.