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, clean_old_workflows

results = heatdemand_simulation("path/to/city.gml", "Wuerzburg-hour.csv")
print(results.dataframe)
print(results.kpis)

pv = photovoltaic_simulation("path/to/city.gml", "Wuerzburg-hour.csv")
print(pv.dataframe)

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

# 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="104_HeatDemandWithShadow",   # name in templates/ or full Path
    citygml_path="path/to/city.gml",
    replaces={"<string>METEONORM_FILE</string>": "<string>Wuerzburg-hour.csv</string>"},
    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

# 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 104_HeatDemandWithShadow path/to/city.gml -v

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

# Run RegionChooser (separate entry point)
regionchooser

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.