Metadata-Version: 2.3
Name: simstadt
Version: 0.3.2
Summary: Python library for using and testing SimStadt workflows.
Author: Eric Duminil
Author-email: Eric Duminil <eric.duminil@hft-stuttgart.de>
Requires-Dist: matplotlib>=3.7
Requires-Dist: msgspec>=0.21.1
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: python-dotenv>=1.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# simstadt

A Python library for running and testing [SimStadt](https://simstadt.hft-stuttgart.de/) 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](https://simstadt.hft-stuttgart.de/download/InstallFiles/SimStadt2_latest.zip) installed separately (or use `simstadt --install`)

## Installation

```bash
pip install simstadt
```

## Usage

```python
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:

```python
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

```bash
# 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`](https://hub.docker.com/r/simstadt/simstadt). It bundles Java, [INSEL](https://insel.eu/), [simstadtpy](https://transfer.hft-stuttgart.de/gitlab/simstadt/simstadtpy) (installed from [PyPI](https://pypi.org/project/simstadt/)) with a complete [SimStadt install](https://simstadt.hft-stuttgart.de/).

```bash
# 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/`](examples/):

```bash
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`](hub.docker.com/r/inseleu/web-insel).


## Development

```bash
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.
