simstadt

A Python library for running and testing SimStadt workflows programmatically.

SimStadt is a city simulation tool for energy and urban analysis developed at HFT Stuttgart. This library wraps its CLI to execute workflows against CityGML files and parse the results into pandas DataFrames.

Requirements

• Python 3.10+
• Java 17+
• SimStadt installed separately (or use simstadt --install)

Installation

pip install simstadt

Usage

from simstadt import (
    heatdemand_simulation,
    photovoltaic_simulation,
    greenwater_simulation,
    energy_plus_simulation,
    clean_old_workflows,
)

results = heatdemand_simulation("path/to/city.gml")
print(results.dataframe)
print(results.kpis)

pv = photovoltaic_simulation("path/to/city.gml")
print(pv.dataframe)

gw = greenwater_simulation("path/to/city.gml", "Wuerzburg-hour.csv", irrigation_ratio=0.5)
print(gw.dataframe)

eplus = energy_plus_simulation("path/to/city.gml", "Wuerzburg-hour.csv", keep_run_folders=True)
print(eplus.dataframe)  # yearly, monthly and peak heating and cooling loads per building
print(eplus.hourly_heating)  # kW per building, with keep_run_folders=True

# Custom building usage and physics libraries instead of SimStadt's standard ones, e.g. for reference buildings
reference = energy_plus_simulation(
    "path/to/reference.gml", "Wuerzburg-hour.csv", usage_library="usage.xml", physics_library="physics.xml"
)

# Remove workflow folders older than 1 hour from a project directory
clean_old_workflows(Path("path/to/project.proj"))

For more control, use run_workflow_with_citygml directly:

from simstadt import run_workflow_with_citygml

results = run_workflow_with_citygml(
    template="HeatDemandWithShadow",   # name in templates/ or full Path
    citygml_path="path/to/city.gml",
    replaces={"<string>METEONORM_FILE</string>": "<string>Wuerzburg-hour.csv</string>"}, # optional
    project_path=Path("path/to/project.proj"),  # optional
)
print(results.kpis)

SimStadt is located automatically via the SIMSTADT_FOLDER environment variable, or by searching ~/Desktop for a SimStadt2_0.*/ directory.

Bundled workflow templates are used by default. Custom templates are resolved via SIMSTADT_TEMPLATE_PATH, or a templates/ directory in the current working directory.

If no project path is specified, workflows are run in a temporary repository under /tmp/simstadt_repo/.

CLI

# Print detected SimStadt installation path and version
simstadt

# See help
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.

# Print the simstadtpy and SimStadt versions
simstadt --version

# Download and install the latest SimStadt release to ~/Desktop
simstadt --install

# Launch the SimStadt GUI
simstadt --gui

# Run a workflow from the command line
simstadt HeatDemandWithShadow.flow path/to/city.gml -v

# Save results to CSV or JSON
simstadt PVWithShadow path/to/city.gml --save results.csv

# Save results to CSV or JSON
simstadt HeatDemand path/to/city.gml --save results.csv

# List output files
simstadt HeatDemand.flow path/to/city.gml --files

# Debug information
simstadt PV path/to/city.gml --verbose

# Run RegionChooser (separate entry point)
regionchooser

Docker

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

# Health check: shows the detected SimStadt version
docker run --rm simstadt/simstadt:cli

# Display help
docker run --rm simstadt/simstadt:cli simstadt --help

# 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:cli simstadt HeatDemand /data/city.gml -p /data/output --files

Results are written to data/output.proj/ on the host:

HeatDemand for city.gml

  Number of buildings                 : 137
  Number of heated buildings          : 91
  Specific Heating demand             : 95 kWh / (m² · a)
  Heated area                         : 83034 m²
  Footprint area                      : 19767 m²
  Yearly Heating demand               : 6598939 kWh / a
  Total Yearly Heating + DHW demand   : 7916193 kWh / a
  Mean Uvalue                         : 1.3 W / (m² · K)
  Year of construction                : 1946
  Storey number                       : 5

Output files:
  /data/output.proj/20260921_0932_96on_HeatDemand.flow/02_WeatherProcessor.step/hourly_GHI_DHI_Ta_pvgis_SARAH3_2005_2023_N49_8__E9_9.prn
  /data/output.proj/20260921_0932_96on_HeatDemand.flow/05_MonthlyEnergyBalance.step/city_DIN18599_HEATING.csv
  /data/output.proj/20260921_0932_96on_HeatDemand.flow/05_MonthlyEnergyBalance.step/city_DIN18599_HEATING.log

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/:

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

Available tags are:

• base: with Java + INSEL + SimStadt
• cli: with Java + INSEL + SimStadt + simstadtpy

As the name implies, base can be used by other projects as a base image, adding their own libraries on top. base can run SimStadt workflows with the simple SimStadt.sh syntax, pointing to a repository, project or workflow:

  docker run --rm -v "$(pwd)/data:/data" simstadt/simstadt:base \
    /opt/SimStadt2/SimStadt.sh /data/output.proj/MyWorkflow.flow

#   Launching: java -classpath lib/*:workflows/* -Xms512m -Xmx4g -Dlogback.configurationFile=./logging_configuration.xml -Dcolor eu.simstadt.desktop.SimStadtCommandLineInterface /data/output.proj/20260921_2007_zeo9_HeatDemand.flow
#   06:33:53 |INFO | e.s.d.SimStadtCommandLineInterface - Launching SimStadt 0.14.0-SNAPSHOT (master, rev. fe4fa3c, 20260914) [main]
#   06:33:53 |INFO | e.s.d.SimStadtCommandLineInterface - Input looks like a Workflow. [main]
#   06:33:54 |INFO | e.s.d.SimStadtCommandLineInterface - Found repository: /data [main]
#   06:33:54 |INFO | e.s.d.SimStadtCommandLineInterface - Found project: output [main]
#   06:33:54 |INFO | e.s.d.SimStadtCommandLineInterface - Found workflow: CityGmlWorkflow [name=CGSC_HeatDe
#   ...

gui will be added too, allowing to run the SimStadt GUI in the browser, similarly to web-insel.

Development

uv sync
uv run pytest               # all tests
uv run pytest -m "not integration"  # skip tests requiring SimStadt

Links

• Code is hosted at https://transfer.hft-stuttgart.de/gitlab/simstadt/simstadtpy
• Python package is hosted at https://pypi.org/project/simstadt/

AI agent

SimStadtResults and tests have been written manually during research projects.

Claude Code has been used to refactor and package the scripts into this library.