ESSIM is a modular, JVM-based simulation engine for Energy System Scenario analysis. It consumes ESDL (Energy System Description Language) models and exposes a REST API for running simulations, inspecting results, and converting profiles.
This repository contains:
commons: shared utilities (time/horizon, data structures, common logic)essim-engine: the REST server and simulation engine
Useful links:
- OpenAPI/Swagger UI (served by the engine):
/openapi/ - API base path:
/essim - ESDL information: https://energytransition.gitbook.io/esdl/esdl-based-tools/essim
- ESDL Model Reference Documentation: https://energytransition.github.io/index.html
- ESSIM user documentation: https://essim-documentation.readthedocs.io/en/latest/
Documentation:
- Architecture
- Database Backends (PostgreSQL vs InfluxDB)
- ESDL Profile Conversion
- External Models Documentation
- Market Prices and Carrier Price Profiles
- Power Grid Modeling / PowSyBl Integration
- Cable and Transformer Parameters
- Scenario-driven simulations (ESDL-based)
- Import Energy System Description Language (ESDL) models and translate assets, carriers, and connections into the internal model.
- Discrete time simulation with configurable horizon and time-step (see
commonsmodule utilities). - Balances carrier flows and respects transport constraints across the network.
- Simulation lifecycle via REST API (
/essim)- Create simulations, start execution, check status/progress, retrieve results/artifacts, and delete when finished.
- Built-in pagination and JSON payloads; errors reported with meaningful HTTP status codes.
- Power grid modeling and AC load-flow
- Build a Powsybl network from ESDL: substations, voltage levels, lines, transformers (see PowSyBl integration).
- Run load-flow per time step and collect flows, voltages, and thermal loading.
- Cable/transformer parameterization via
CableSpecandTransformerSpec(see Cable and Transformer parameters). - Controller:
nl.tno.essim.loadflow.EssimLoadFlowController.
- KPIs and analytics
- Pluggable KPI modules compute scenario KPIs (e.g., energy balance, curtailment, losses, grid violations).
- Managed by
nl.tno.essim.kpi.KPIManagerand exposed via REST.
- Profiles and time-series utilities
- ESDL profile conversion, resampling and alignment to simulation time steps (see ESDL profile conversion).
- Embedding of profiles into ESDL.
- Java Development Kit 21+
- Apache Maven 3.9+
- A reachable MongoDB instance
- Optional: Docker, Docker Compose
From the project root:
mvn clean package
Artifacts:
essim-engine/target/essim.jar— run this JAR to start the server
The project is a standard multi-module Maven build and works well in IntelliJ IDEA and Eclipse. Requirements: JDK 21 and Maven 3.9+.
-
IntelliJ IDEA (Community or Ultimate):
- Open the project: File > New > Project from Existing Sources… > select the root
pom.xml. - Set Project SDK to JDK 21: File > Project Structure > Project > SDK.
- Enable annotation processing (for Lombok): Settings > Build, Execution, Deployment > Compiler > Annotation Processors > check “Enable annotation processing”.
- Build: use the Maven tool window or run
mvn clean packagein the terminal. - Run the server locally:
- Create an Application run configuration with Main class
nl.tno.essim.ESSimMain. - Set Environment variables (example):
HTTP_SERVER_SCHEME=httpHTTP_SERVER_HOSTNAME=localhostHTTP_SERVER_PORT=8080MONGODB_HOST=localhostMONGODB_PORT=27017
- Start the run configuration and browse
http://localhost:8080/openapi/.
- Create an Application run configuration with Main class
- Open the project: File > New > Project from Existing Sources… > select the root
-
Eclipse (with m2e):
- Import: File > Import… > Maven > Existing Maven Projects, select the project root.
- Configure JDK 21: Preferences > Java > Installed JREs, add/select a JDK 21 and set it as default.
- Lombok/annotation processing:
- Ensure m2e-apt is installed/enabled (Eclipse may prompt to install). Then enable: Preferences > Maven > Annotation Processing > “Automatically configure JDT APT”.
- If your Eclipse installation requires it, install Lombok by running the
lombok.jarinstaller and selecting your Eclipse installation.
- Run the server: Run > Run Configurations… > Java Application, choose
nl.tno.essim.ESSimMain, and add the same Environment variables as above.
Tips:
- API base:
http://localhost:8080/essim - Swagger UI:
http://localhost:8080/openapi/ - Quick MongoDB: use the Docker Compose example below to start a local MongoDB for development.
Build the Docker image after packaging the JAR:
mvn clean package
docker build -t <repo/essim>:<tag> essim-engine
Run the container (requires a MongoDB reachable from the container):
docker run --rm \
-e HTTP_SERVER_SCHEME=http \
-e HTTP_SERVER_HOSTNAME=0.0.0.0 \
-e HTTP_SERVER_PORT=8080 \
-e MONGODB_HOST=<mongodb-host> \
-e MONGODB_PORT=27017 \
-p 8080:8080 \
<repo/essim>:<tag>
Then browse to:
- API:
http://localhost:8080/essim - Swagger UI:
http://localhost:8080/openapi/
By default, the engine uses the log4j2.xml file bundled in the Docker image at /opt/log4j2.xml. You can override the logging configuration by mounting an external log4j2.xml file:
docker run --rm \
-v /path/to/your/log4j2.xml:/opt/log4j2.xml \
...
<repo/essim>:<tag>You can extract the default configuration file to use it as a basis:
docker run --rm --entrypoint cat <repo/essim>:<tag> /opt/log4j2.xml > my-log4j2.xmlThe configuration is set to automatically reload every 30 seconds if the file is changed.
To persist or access the log files outside the container, you can mount the /opt/logs directory:
docker run --rm \
-v $(pwd)/logs:/opt/logs \
...
<repo/essim>:<tag>Tip: See essim-engine/Dockerfile for the full list of default environment variables used at runtime.
This example uses a MongoDB container and the ESSIM engine:
services:
mongodb:
image: mongo:7
ports:
- "27017:27017"
essim:
image: <repo/essim>:<tag>
depends_on:
- mongodb
environment:
HTTP_SERVER_SCHEME: http
HTTP_SERVER_HOSTNAME: 0.0.0.0
HTTP_SERVER_PORT: 8080
MONGODB_HOST: mongodb
MONGODB_PORT: 27017
ports:
- "8080:8080"
volumes:
- ./log4j2.xml:/opt/log4j2.xml
- ./logs:/opt/logsThe REST API is implemented under the base path /essim. Key groups include:
- Simulations: create, list, query status and KPIs
- Profile conversion: ESDL profile to time-series conversion
- Transport/load-flow and logs retrieval per simulation
Explore and try all endpoints via Swagger UI at /openapi/. The API description is generated from annotations in the code (e.g., nl.tno.essim.rest package).
/commons: shared classes and utilities/essim-engine:src/main/java/nl/tno/essim/rest: REST resources and server setup (Jetty + Jersey)src/main/resources/web/swagger-ui: Swagger UI assets are unpacked here during buildDockerfile: runtime image based oneclipse-temurin:21-jdk
The main entry point is nl.tno.essim.ESSimMain, which starts the HTTP server (nl.tno.essim.rest.EssimHttpServer).
Run all tests:
mvn test
- Server does not start, or exits immediately:
- Ensure all required environment variables are set and valid numbers (e.g.,
HTTP_SERVER_PORT). - Check MongoDB connectivity (
MONGODB_HOST/MONGODB_PORT).
- Ensure all required environment variables are set and valid numbers (e.g.,
- Cannot reach Swagger UI:
- Confirm the server is running and the port is exposed.
- Verify you’re browsing
/openapi/(trailing slash is accepted).
java.lang.NoClassDefFoundErroror similar:- Make sure you run the packaged JAR from
essim-engine/target/essim.jarproduced bymvn clean package.
- Make sure you run the packaged JAR from
See CONTRIBUTE.md for guidelines.
Licensed under the Apache License, Version 2.0. See LICENSE for details.