Skip to content

Docker

A ready-to-use SimStadt CLI image is published at simstadt/simstadt:cli. It bundles Java, INSEL, simstadtpy (installed from PyPI) with a complete SimStadt install.

It should allow to run any workflow, automatically and without GUI.

Usage

Health check: shows the bundled SimStadt version

docker run --rm simstadt/simstadt

#   simstadt - Python library for SimStadt workflows.
#   See https://simstadt.hft-stuttgart.de/ for SimStadt documentation.
#   simstadt --help for usage information.

#   SimStadt folder : /home/simstadt/Desktop/SimStadt2_0.14.0-SNAPSHOT_master_20260914_fe4fa3c
#   SimStadt version: 0.14.0-SNAPSHOT (branch: master, rev: fe4fa3c, date: 2026-09-14)

Display Help

docker run --rm simstadt/simstadt simstadt --help

#   usage: simstadt [-h] [--gui] [--csv-export] [--install] [-d DESCRIPTION]
#                   [--destination DESTINATION] [-p PROJECT_PATH] [-f] [-s PATH]
#                   [-v] [-V]
#                   [template] [citygml]

#   simstadt - Python library for SimStadt workflows.

#   positional arguments:
#     template              Template name (from SIMSTADT_TEMPLATE_PATH), path to a
#                           .flow directory, or a bundled template name.
#     citygml               Path to the CityGML input file.

#   options:
#     -h, --help            show this help message and exit
#     --gui                 Launch the SimStadt GUI.
#     --csv-export          Export CSV from workflowsteps, when available.
#     --install             Download and install the latest SimStadt release to
#                           ~/Desktop.
#     -d DESCRIPTION, --description DESCRIPTION
#                           Human-readable label for the result.
#     --destination DESTINATION
#                           Workflow folder name (default: timestamped random id).
#     -p PROJECT_PATH, --project-path PROJECT_PATH
#                           Directory where the workflow folder is created.
#     -f, --files           Show output files after the run.
#     -s PATH, --save PATH  Save result DataFrame to a file (.csv or .json).
#     -v, --verbose         Enable debug logging.
#     -V, --version         Print the simstadtpy and SimStadt versions, then exit.

Run a workflow against a mounted CityGML file

mkdir -p data
cp path/to/city.gml data/city.gml
docker run --rm -v "$(pwd)/data:/data" simstadt/simstadt \
    simstadt HeatDemand /data/city.gml \
    --project-path /data/output \
    --files

#   HeatDemand for city.gml

#     Number of buildings                 : 6
#     Number of heated buildings          : 3
#     Specific Heating demand             : 128 kWh / (m² · a)
#     Heated area                         : 1265 m²
#     Footprint area                      : 473 m²
#     Yearly Heating demand               : 143229 kWh / a
#     Total Yearly Heating + DHW demand   : 162206 kWh / a
#     Mean Uvalue                         : 1.3 W / (m² · K)
#     Year of construction                : 1959
#     Storey number                       : 3

#   Output files:
#     /data/output.proj/20260921_1501_16pq_HeatDemand.flow/02_WeatherProcessor.step/hourly_GHI_DHI_Ta_pvgis_SARAH3_2005_2023_N48_8__E9_2.prn
#     /data/output.proj/20260921_1501_16pq_HeatDemand.flow/05_MonthlyEnergyBalance.step/city_DIN18599_HEATING.csv
#     /data/output.proj/20260921_1501_16pq_HeatDemand.flow/05_MonthlyEnergyBalance.step/city_DIN18599_HEATING.log

The Dockerfile is hosted along simstadtpy.

Compose

Bring your own templates by keeping them alongside your data and pointing SIMSTADT_TEMPLATE_PATH at them — a single mount. A complete, runnable example (with sample CityGML data and a template) is in examples/.

services:
  simstadt:
    image: simstadt/simstadt:cli
    volumes:
      - ./data:/data
    environment:
      SIMSTADT_TEMPLATE_PATH: /data/templates
      LOCALE: en_GB # optional, will set decimal separator to "."
      MAX_RAM: 2g # optional. Default is 4GB, increase if needed

cd examples
docker compose run --rm simstadt simstadt \
    MyTemplate /data/city.gml \
    --project-path /data/output \
    --save /data/my_simulation.csv \
    --verbose