Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

HELICS

Today the core uses 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.
https://github.com/GMLC-TDC/HELICS

Category: Energy Systems
Sub Category: Energy System Modeling Frameworks

Keywords

co-simulation hacktoberfest power-grids simulation simulation-framework

Keywords from Contributors

networks transforms measur simulator examples parallel compose optimize conversion archiving

Last synced: about 6 hours ago
JSON representation

Repository metadata

Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS)

README.md

A multi-language, cross-platform library that enables different simulators to easily exchange data and stay synchronized in time. Scalable from two simulators on a laptop to 100,000+ running on supercomputers, the cloud, or a mix of these platforms.





Cirrus Status

Releases

pre-commit.ci status

Table of contents

Introduction

Welcome to the repository for the Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS). HELICS provides a general-purpose, modular, highly-scalable co-simulation framework that runs cross-platform and has bindings for multiple languages. It is a library that enables multiple existing simulation tools (and/or 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 simulation tools from multiple domains to form a complex software simulation without having to change the individual tools.

It is important to note that HELICS cannot in and of itself simulate anything, rather it is a framework to make it easy to bring together other existing (or novel) simulation tools to tackle problems that can't readily be solved by a single tool alone. After all "simulations are better together," and HELICS is designed to help get you there easily and quickly. HELICS has also already worked out many of the more subtle aspects of synchronizing simulations so you don't have to.

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 (Supported Tools). However, it is possible to use HELICS for co-simulation in any domain; the HELICS API and language bindings make it straightforward to connect any simulation tool that provides a scripting interface or access to source code.

Previous and existing use cases have stretched across a wide range of scales in time and spatial area, from transient dynamics to long-term planning studies, and from individual appliance behavior to nation-wide simulations.

Philosophy of HELICS

The design and development of HELICS is driven by a number of philosophical considerations that have a clear path to design decisions in the code and reflect the needs of the use cases that drive HELICS development.

  • Make it as easy as possible for federates of all kinds to work together
  • Federates cannot impose restrictions or requirements on other federates
  • Federates should maintain control and autonomy
  • The design should be layered and modular to be adaptable to a wide variety of circumstances
  • Centralized control should be minimized

These design priorities directed much of the design of HELICS and supporting tools, including operation as a library vs a run time interface that requires simulations be loaded as modules into HELICS, the use of distributed timing and control, and giving federates fine grained control over the time management and operations that is independent of operations of other federates. These core philosophies support an underlying belief driving co-simulation that "Simulations are Better Together".

Getting Started

A User Guide is available with some tutorial examples. We suggest starting here if you are looking for more information on HELICS, whether it is for getting started, or learning about more advanced features, the new documentation should have something for everyone (Please let us know if it doesn't via or by creating an issue on github).

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

You can also Try HELICS online without having to install any software.

Earlier we also 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. These videos do not reflect recent HELICS advances but do introduce some basic concepts.

Several examples of HELICS federates and projects are located in HELICS-Examples with corresponding documentation in the User Guide. This repo provides a number of examples using the different libraries and interfaces, including those used in the user guide.

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 Tutorial was prepared for the IEEE PES General meeting in Atlanta. The example materials are available on Binder.

The HELICS team holds office hours every-other Thursday; bring your questions and get help from the development team.

Language Bindings

HELICS provides a rich set of APIs for other languages including Python, C, Java, Octave, Julia, Matlab, and Simulink. nim and C# APIs are available on an experimental basis, and with an active open-source community, the set of supported languages continues to grow. See Language bindings for additional details.

Documentation

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

Installation Guide

Documentation downloads

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.

CHANGELOG

A history of changes to HELICS

ROADMAP

A snapshot of some current plans for what is to come.

Installation

A guide to installing HELICS on different platforms

Quick links

Docker

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 on Tools using HELICS, 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.

Supported Tools

HELICS helper Apps

  • HELICS CLI provides a simple way to automate configuring, starting, and stopping HELICS co-simulations. This helps in overcoming the challenges associated with successfully sequencing and starting simulations of all sizes and is particularly helpful for larger simulations.
  • Broker, which is a command line tool for running a Broker, the core hub in HELICS for data exchange. One or more brokers are what tie the simulation tools together in a HELICS federation. There is also a Broker Server which can generate brokers as needed, and can include a REST API.
  • Player, which acts as a simple send-only federate that simply publishes a stream of timed HELICS messages from a user-defined file. This can be very useful when testing a federate in isolation by mimicking the data that will eventually come from other sources, and in assembling or debugging federations to stand in for any federates which might not be quite ready or that take a long time to run. The Player can also readily playback the files created by the HELICS Recorder (see below). 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. This makes it easy to monitor some or all of the data exchanged via HELICS and can also be part of debugging and modular workflows. For example it can record the data exchanged during a (partly?) successful run to play back (see Player above) to other federates without having to launch those parts again or to isolate/test changes to a subset of a federation. HELICS Recorder is included in the HELICS distribution.
  • 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.

Contributing

Contributors are welcome, see the Contributing guidelines for more details on the process of contributing. See the Code of Conduct for guidelines on the community expectations. All prior contributors can be found here along with a listing of included and optional components to HELICS.

Build Status

Publications

If you use HELICS in your research, please cite:

T. Hardy, B. Palmintier, P. Top, D. Krishnamurthy and J. Fuller, "HELICS: A Co-Simulation Framework for Scalable Multi-Domain Modeling and Analysis," in IEEE Access, doi: 10.1109/ACCESS.2024.3363615, available at https://ieeexplore.ieee.org/document/10424422

Older citation

[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.

History and Motivation

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 (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.

Source Repo

The HELICS source code is hosted on GitHub: https://github.com/GMLC-TDC/HELICS

Release

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

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 9 days ago

Total Commits: 3,073
Total Committers: 39
Avg Commits per committer: 78.795
Development Distribution Score (DDS): 0.47

Commits in past year: 70
Committers in past year: 8
Avg Commits per committer in past year: 8.75
Development Distribution Score (DDS) in past year: 0.543

Name Email Commits
Philip Top t****1@l****v 1628
Ryan Mast n****k 565
Dheepak Krishnamurthy k****9@g****m 441
Hardy, Trevor D t****y@p****v 87
github-actions[bot] 4****] 81
pre-commit-ci[bot] 6****] 69
Jeff Daily j****y@p****v 35
Niddodi s****i@p****v 26
dependabot[bot] 4****] 20
Bryan Palmintier b****r 19
Mark Eberlein m****n@p****v 14
HELICS-bot H****t 14
Himanshu Jain h****n@n****v 10
Shri Abhyankar a****r@m****v 7
Andy Fisher a****r@p****v 7
Eran e****r@g****m 4
Allison Campbell a****l@p****v 4
Ed Beroset b****t@i****g 4
Denis Nadeau d****4 3
Matt Irish 4****h 3
MuMonish m****e@p****v 3
Nitin Barthwal 4****l 3
Parth Bansal p****6@g****m 3
top1 t****1@r****v 2
Ai Enkoji 6****1 2
Brian M. Kelley b****y 2
Bryan T. Richardson b****r@d****m 2
Jacob Hansen j****n@p****v 2
Jason Fuller j****r@p****v 2
corinnegroth 5****h 2
and 9 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 676
Total pull requests: 2,026
Average time to close issues: 3 months
Average time to close pull requests: 4 days
Total issue authors: 49
Total pull request authors: 29
Average comments per issue: 2.75
Average comments per pull request: 1.26
Merged pull request: 1,828
Bot issues: 7
Bot pull requests: 659

Past year issues: 29
Past year pull requests: 53
Past year average time to close issues: about 1 month
Past year average time to close pull requests: 11 days
Past year issue authors: 10
Past year pull request authors: 8
Past year average comments per issue: 1.62
Past year average comments per pull request: 0.57
Past year merged pull request: 47
Past year bot issues: 3
Past year bot pull requests: 18

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/GMLC-TDC/HELICS

Top Issue Authors

  • phlptp (292)
  • kdheepak (102)
  • trevorhardy (98)
  • nightlark (76)
  • bpalmintier (19)
  • afisher1 (10)
  • github-actions[bot] (7)
  • xcosmos6 (5)
  • temcdrm (5)
  • HimanshuJain17 (3)
  • Jacobhansens (3)
  • blthayer (3)
  • eberleim (3)
  • pdbj (3)
  • jeffdaily (3)

Top Pull Request Authors

  • phlptp (796)
  • github-actions[bot] (573)
  • nightlark (389)
  • kdheepak (86)
  • pre-commit-ci[bot] (65)
  • trevorhardy (40)
  • dependabot[bot] (21)
  • bpalmintier (11)
  • eberleim (7)
  • dnadeau4 (4)
  • afisher1 (4)
  • eranschweitzer (4)
  • mattirish (3)
  • parthb83 (3)
  • shwethanidd (2)

Top Issue Labels

  • bug (207)
  • testing (90)
  • enhancement (88)
  • documentation (87)
  • question (50)
  • Installation/build (44)
  • Code Improvement (34)
  • Interfaces (32)
  • ux (23)
  • help wanted (18)
  • infrastructure/ci (15)
  • Examples (11)
  • performance/scalability (10)
  • On Hold (8)
  • good first issue (6)
  • cantfix (5)
  • duplicate (3)
  • wontfix (3)
  • hacktoberfest (2)
  • chore (1)

Top Pull Request Labels

  • bug (181)
  • enhancement (99)
  • Installation/build (97)
  • documentation (94)
  • Code Improvement (85)
  • testing (69)
  • infrastructure/ci (61)
  • Interfaces (41)
  • dependencies (34)
  • chore (21)
  • performance/scalability (19)
  • v3 breaking change (17)
  • github_actions (11)
  • ux (8)
  • Examples (5)
  • hacktoberfest-accepted (4)
  • python (3)
  • question (1)

Package metadata

proxy.golang.org: github.com/gmlc-tdc/helics

  • Homepage:
  • Documentation: https://pkg.go.dev/github.com/gmlc-tdc/helics#section-documentation
  • Licenses:
  • Latest release: v3.6.1+incompatible (published 2 months ago)
  • Last Synced: 2025-04-30T16:09:29.017Z (1 day ago)
  • Versions: 68
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Rankings:
    • Dependent packages count: 6.999%
    • Average: 8.173%
    • Dependent repos count: 9.346%
pypi.org: helics-apps

Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS)

  • Homepage: https://helics.org/
  • Documentation: https://docs.helics.org/en/latest/
  • Licenses: BSD License
  • Latest release: 3.6.1 (published 2 months ago)
  • Last Synced: 2025-04-30T16:09:27.241Z (1 day ago)
  • Versions: 32
  • Dependent Packages: 2
  • Dependent Repositories: 1
  • Downloads: 1,935 Last month
  • Docker Downloads: 77
  • Rankings:
    • Docker downloads count: 2.618%
    • Dependent packages count: 3.244%
    • Forks count: 6.64%
    • Stargazers count: 7.038%
    • Average: 8.634%
    • Downloads: 10.174%
    • Dependent repos count: 22.088%
  • Maintainers (2)
pypi.org: helics

Python HELICS bindings

  • Homepage: https://github.com/GMLC-TDC/pyhelics
  • Documentation: https://python.helics.org/
  • Licenses: BSD License
  • Latest release: 3.6.1 (published 2 months ago)
  • Last Synced: 2025-04-30T16:09:28.288Z (1 day ago)
  • Versions: 106
  • Dependent Packages: 6
  • Dependent Repositories: 2
  • Downloads: 18,259 Last month
  • Docker Downloads: 77
  • Rankings:
    • Dependent packages count: 1.854%
    • Docker downloads count: 2.885%
    • Downloads: 4.531%
    • Average: 9.734%
    • Dependent repos count: 11.575%
    • Forks count: 12.55%
    • Stargazers count: 25.009%
  • Maintainers (2)
spack.io: helics

HELICS is a general-purpose, modular, highly-scalable co-simulation framework that runs cross-platform (Linux, Windows, and Mac OS X) and supports both event driven and time series simulation.

  • Homepage: https://github.com/GMLC-TDC/HELICS
  • Licenses: []
  • Latest release: 3.0.1 (published about 3 years ago)
  • Last Synced: 2025-04-30T16:09:58.171Z (1 day ago)
  • Versions: 15
  • Dependent Packages: 2
  • Dependent Repositories: 0
  • Rankings:
    • Dependent repos count: 0.0%
    • Average: 13.53%
    • Forks count: 16.729%
    • Stargazers count: 18.41%
    • Dependent packages count: 18.98%
  • Maintainers (1)
crates.io: helics-sys

HELICS cosimulation library

  • Homepage: https://helics.org
  • Documentation: https://docs.rs/helics-sys/
  • Licenses: non-standard
  • Latest release: 0.1.2 (published about 4 years ago)
  • Last Synced: 2025-04-30T16:09:28.692Z (1 day ago)
  • Versions: 3
  • Dependent Packages: 1
  • Dependent Repositories: 0
  • Downloads: 3,996 Total
  • Rankings:
    • Forks count: 9.66%
    • Stargazers count: 13.64%
    • Dependent packages count: 16.956%
    • Average: 22.864%
    • Dependent repos count: 29.318%
    • Downloads: 44.747%
  • Maintainers (1)
crates.io: helics

helics.rs: Safe rust bindings to HELICS cosimulation library

  • Homepage: https://helics.org
  • Documentation: https://docs.rs/helics/
  • Licenses: non-standard
  • Latest release: 0.1.0 (published about 4 years ago)
  • Last Synced: 2025-04-30T16:09:27.731Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 1,351 Total
  • Rankings:
    • Forks count: 9.66%
    • Stargazers count: 13.64%
    • Dependent repos count: 29.318%
    • Average: 31.985%
    • Dependent packages count: 33.812%
    • Downloads: 73.495%
  • Maintainers (1)
pypi.org: helics-cli-extras

Python HELICS bindings

  • Homepage: https://github.com/GMLC-TDC/pyhelics
  • Documentation: https://python.helics.org/
  • Licenses: MIT License
  • Latest release: 0.0.1 (published 6 months ago)
  • Last Synced: 2025-04-30T16:09:27.751Z (1 day ago)
  • Versions: 1
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 270 Last month
  • Rankings:
    • Dependent packages count: 10.142%
    • Average: 33.612%
    • Dependent repos count: 57.082%
  • Maintainers (1)

Dependencies

docs/requirements.txt pypi
  • breathe ==4.31.0
  • gmlc-tdc-sphinxcontrib-redoc ==1.6.1a1
  • ipykernel ==6.4.2
  • ipython ==7.31.1
  • myst-parser ==0.15.2
  • nbsphinx ==0.8.7
  • requests ==2.26.0
  • sphinx ==4.2.0
  • sphinx_rtd_theme ==1.0.0
  • sphinxcontrib-svg2pdfconverter ==1.1.1
.github/actions/linux-release-builder/action.yml actions
  • Dockerfile * docker
.github/workflows/benchmark-package.yml actions
  • ./.github/actions/linux-release-builder * composite
  • actions/checkout v2 composite
  • actions/upload-artifact v2 composite
.github/workflows/code-coverage.yml actions
  • actions/checkout v3 composite
.github/workflows/compress-images.yml actions
  • actions/checkout v2 composite
  • calibreapp/image-actions main composite
.github/workflows/create-release-checklist.yml actions
  • actions/checkout v3 composite
.github/workflows/docker.yml actions
  • actions/checkout v3 composite
  • docker/login-action v2 composite
  • docker/metadata-action v4 composite
.github/workflows/msys2.yml actions
  • actions/checkout v3 composite
  • msys2/setup-msys2 v2 composite
.github/workflows/release-build.yml actions
  • ./.github/actions/linux-release-builder * composite
  • actions/checkout v3 composite
  • actions/checkout v2 composite
  • actions/download-artifact v1 composite
  • actions/upload-artifact v1 composite
.github/workflows/static-analyzers.yml actions
  • actions/checkout v3 composite
.github/workflows/swig-interface-gen.yml actions
  • actions/cache v1 composite
  • actions/checkout v3 composite
  • actions/setup-python v2 composite
  • gmlc-tdc/helics-action/update-swig-interfaces main composite
  • peter-evans/create-pull-request v4 composite
  • pre-commit/action v2.0.3 composite
.github/actions/linux-release-builder/Dockerfile docker
  • phusion/holy-build-box-64 2.1.0 build
vcpkg.json vcpkg
  • boost-core *
  • boost-spirit *

Score: 19.262558377126428