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")
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)

# 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

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

    simstadt - Python library for SimStadt workflows.

    positional arguments:
      template              Template name (from SIMSTADT_TEMPLATE_PATH) or path to a .flow directory.
      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.

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