Metadata-Version: 2.3
Name: simstadt
Version: 0.1.5
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: 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+
- [SimStadt](https://simstadt.hft-stuttgart.de/download/InstallFiles/SimStadt2_latest.zip) installed separately

## Installation

```bash
pip install simstadt
```

## Usage

```python
from simstadt import heatdemand_simulation, photovoltaic_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)

# 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="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/`.

## Health check

```bash
simstadt
```

Prints the detected SimStadt installation path and version.

## Development

```bash
uv sync
uv run pytest               # all tests
uv run pytest -m "not integration"  # skip tests requiring 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.
