Adding README

README.md

+# 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
+
+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)
+```
+
+SimStadt is located automatically via the `SIMSTADT_FOLDER` environment variable, or by searching `~/Desktop` for a `SimStadt2_0.*/` directory.
+
+Workflow templates are resolved via `SIMSTADT_TEMPLATE_PATH`, or a `Template/` directory in the current working directory.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```