Skip to content


Repository files navigation

Grid Singularity Energy Exchange


The Grid Singularity Energy Exchange Engine is developed by Grid Singularity as an interface (Singularity Map) and open source codebase (see Licensing to model, simulate, optimize and (coming soon) download and deploy interconnected, grid-aware energy marketplaces. Grid Singularity has been proclaimed the World Tech Pioneer by the World Economic Forum and is also known as a co-founder of the Energy Web Foundation that gathers leading energy corporations globally co-developing a shared blockchain-based platform.

Code of Conduct

Please refer to:

How to contribute:

Please refer to:

Basic setup

(For instructions using Docker see below)

After cloning this project setup a Python 3.8 virtualenv and install fabric3:

~# pip install fabric3

Without using virtualenv (e.g. using conda envs) you can just install gsy-e using

~# pip install -e .

The Simulation

Running the simulation

After installation the simulation can be run with the following command:

~# gsy-e run

There are various options available to control the simulation run. Help on there is available via:

~# gsy-e run --help

Controlling the simulation

While running a simulation, the following keyboard commands are available:

Key Command
i Show information about simulation
p Pause simulation
q Quit simulation
r Reset and restart simulation
R Start a Python REPL at the current simulation step
s Save current state of simulation to file (see below for resuming)


Updating requirements

We use pip-tools managed by fabric3 to handle requirements. To update the pinned requirements use the following command:

~# fab compile

There is also a command to compile and sync in one step:

~# fab reqs

_`pip-tools`: _`fabric3`:


We use py.test managed by tox to run the (unit) tests. To run the test suite simply run the following command:

~# tox

_`py.test`: _`tox`:


The repository contains a docker Dockerfile. To build an image use the following command (change into repository folder first):

~# docker build -t gsy-e .

After building is complete you can run the image with:

~# docker run --rm -it gsy-e

Command line parameters can be given normally after the image name:

~# docker run --rm gsy-e --help
~# docker run --rm gsy-e run --help
~# docker run --rm gsy-e run --setup default_2a -t15s

There is also a handy script that deals with the building of the image and running the provided command:

~# ./ "$docker_command" $export_path

where you can provide the gsy_e_command and export path where the simulation results are stored. For example:

~# ./ "gsy-e -l ERROR run --setup default_2a -t 15s" $HOME/gsy_e-simulation

builds a gsy-e docker image (if not already present), runs the simulation with setup-file default_2a, tick-length 15s and stores the simulation output data into $HOME/gsy_e-simulation. If no export_path is provided, simulation results will be stored in $HOME/gsy_e-simulation.


Detailed Documentation

Please refer to: