simstadt 0.1.0__tar.gz

simstadt-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.3
+Name: simstadt
+Version: 0.1.0
+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>=2.0
+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
+
+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
+```

simstadt-0.1.0/README.md

@@ -0,0 +1,40 @@
+# 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
+```

simstadt-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "simstadt"
+version = "0.1.0"
+description = "Python library for using and testing SimStadt workflows."
+readme = "README.md"
+authors = [
+    { name = "Eric Duminil", email = "eric.duminil@hft-stuttgart.de" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "matplotlib>=3.7",
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "python-dotenv>=1.0",
+]
+
+[project.scripts]
+simstadt = "simstadt:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: tests that require a SimStadt installation and a live project path",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"

simstadt-0.1.0/src/simstadt/__init__.py

@@ -0,0 +1,32 @@
+from .results import (
+    GreenWaterResults,
+    HeatDemandResults,
+    KPI,
+    LoadProfileResults,
+    PhotovoltaicResults,
+    SimStadtResults,
+    SolarPotentialResults,
+    create_simstadt_results,
+)
+from .runner import run_workflow_with_citygml
+from .workflows import greenwater_simulation, heatdemand_simulation, photovoltaic_simulation
+
+__all__ = [
+    "KPI",
+    "SimStadtResults",
+    "HeatDemandResults",
+    "LoadProfileResults",
+    "PhotovoltaicResults",
+    "GreenWaterResults",
+    "SolarPotentialResults",
+    "create_simstadt_results",
+    "run_workflow_with_citygml",
+    "photovoltaic_simulation",
+    "heatdemand_simulation",
+    "greenwater_simulation",
+]
+
+
+def main() -> None:
+    print("simstadt - Python library for SimStadt workflows.")
+    print("See https://simstadt.hft-stuttgart.de/ for SimStadt documentation.")

simstadt-0.1.0/src/simstadt/results.py

@@ -0,0 +1,612 @@
+"""Parse SimStadt output files into typed result objects.
+
+Supports HeatDemand, Photovoltaic, and GreenWater workflows.
+Each result type exposes: .dataframe, .kpis, .diagrams, .csv_path,
+.to_json() / .from_json(), and .zip_content().
+"""
+
+import io
+import json
+import logging
+import re
+import zipfile
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import ClassVar, Dict, Sequence, Type
+from xml.etree import ElementTree as et
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class KPI:
+    """Metric with name, value, unit and display precision."""
+
+    name: str
+    value: float
+    unit: str | None = None
+    precision: int = 2
+    NAME_AND_UNIT = re.compile(r"^(.*?) \[(.*?)\]$")
+
+    def __post_init__(self):
+        """Move units embedded in column names (e.g. 'Area [m²]') into the unit field."""
+        if match := self.NAME_AND_UNIT.match(self.name):
+            self.name, self.unit = match.groups()
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @property
+    def rounded_value(self) -> float:
+        return round(self.value, self.precision)
+
+    def __str__(self):
+        s = f"{self.name:35s} : {self.value:.{self.precision}f}"
+        if self.unit:
+            s = f"{s} {self.unit}"
+        return s
+
+    def __repr__(self):
+        return str(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "KPI":
+        return cls(**data)
+
+
+class Providers(str, Enum):
+    HEAT_DEMAND = "de.hftstuttgart.simstadtworkflows.energy.HeatDemandAnalysisWorkflowProvider"
+    HEAT_DEMAND_WITH_REFURBISHMENT = (
+        "de.hftstuttgart.simstadtworkflows.energy.HeatDemandAnalysisWithRefurbishmentStrategyWorkflowProvider"
+    )
+    HEAT_DEMAND_WITH_HISTORIC_REFURBISHMENT = (
+        "de.hftstuttgart.simstadtworkflows.energy.HeatDemandAnalysisWithHistoricAndFutureRefurbishmentWorkflowProvider"
+    )
+    HEAT_DEMAND_WITH_SHADOW = (
+        "de.hftstuttgart.simstadtworkflows.shadow.HeatDemandCalculationWithShadowProcessingProvider"
+    )
+    PHOTOVOLTAIC = "de.hftstuttgart.simstadtworkflows.energy.PhotovoltaicPotentialAnalysisWorkflowProvider"
+    PHOTOVOLTAIC_WITH_SHADOW = "de.hftstuttgart.simstadtworkflows.shadow.PVPotentialWithShadowProcessingProvider"
+    PHOTOVOLTAIC_FINANCE = (
+        "de.hftstuttgart.simstadtworkflows.economics.PhotovoltaicPotentialFinancialAnalysisWorkflowProvider"
+    )
+    GREEN_WATER = "de.hftstuttgart.simstadtworkflows.greenwater.GreenWaterWorkflowProvider"
+    LOAD_PROFILE = "de.hftstuttgart.simstadtworkflows.energy.LoadProfileProvider"
+    SOLAR_POTENTIAL = "de.hftstuttgart.simstadtworkflows.energy.SolarPotentialAnalysisWorkflowProvider"
+
+
+def detect_decimal(csv_path: Path, line_number: int, check: str = "") -> str:
+    """Detect whether '.' or ',' is used as decimal separator on the given line."""
+    with open(csv_path, encoding="utf-8") as csv:
+        for _ in range(line_number):
+            next(csv)
+        line = next(csv)
+        if check and (check not in line):
+            raise ValueError(f"Couldn't find '{check}' in '{line}'.")
+        possible_delimiters = [".", ","]
+        delimiter = next(d for d in possible_delimiters if d in line)
+        logger.debug("Decimal for %s is '%s'", csv_path.name, delimiter)
+        return delimiter
+
+
+def get_workflow_provider(output_files: list[Path]) -> str:
+    """Determine the SimStadt workflow provider class name from a params.xml file."""
+    if len(output_files) == 0:
+        raise ValueError("No output files were provided!")
+    first_output_file = output_files[0]
+    workflow_path = next(d for d in first_output_file.parents if d.suffix == ".flow")
+    params_xml = workflow_path / "params.xml"
+
+    tree = et.parse(params_xml)
+    root = tree.getroot()
+    element = root.find(".//void[@property='workflowProvider']/object")
+    assert element is not None, "workflowProvider element not found"
+    return element.get("class", "UnknownWorkflowProvider")
+
+
+@dataclass
+class SimStadtResults(ABC):
+    """Abstract base class for SimStadt workflow results.
+
+    Subclasses register themselves via __init_subclass__ so that
+    create_simstadt_results() can instantiate the correct type automatically.
+    """
+
+    description: str
+    output_files: list[Path]
+
+    supported_providers: ClassVar[list[str]]
+    csv_identifier: ClassVar[str]
+    _registry: ClassVar[Dict[str, Type["SimStadtResults"]]] = {}
+
+    _df: pd.DataFrame | None = field(default=None, init=False, repr=False)
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        for provider in cls.supported_providers:
+            SimStadtResults._registry[provider] = cls
+
+    @abstractmethod
+    def _parse_results(self) -> pd.DataFrame:
+        pass
+
+    @property
+    def dataframe(self) -> pd.DataFrame:
+        if self._df is None:
+            self._df = self._parse_results()
+        return self._df
+
+    @property
+    def more_info(self) -> dict[str, list[KPI]]:
+        return {}
+
+    @property
+    @abstractmethod
+    def kpis(self) -> list[KPI]:
+        pass
+
+    def kpi(self, name: str) -> KPI:
+        for kpi in self.kpis:
+            if kpi.name == name:
+                return kpi
+        raise ValueError(f"No '{name}' KPI found for {self}")
+
+    def _prepare_kpis(self, sums: Sequence, averages: Sequence) -> list[KPI]:
+        kpis = []
+        default_precision = 0
+        for item in sums:
+            name, unit, precision = (item + (default_precision,))[:3]
+            kpis.append(KPI(name, self.dataframe[name].sum(), unit, precision))
+        for item in averages:
+            name, unit, precision = (item + (default_precision,))[:3]
+            kpis.append(KPI(name, float(self.dataframe[name].mean()), unit, precision))
+        return kpis
+
+    def _params_xml(self) -> Path:
+        return self.workflow_path / "params.xml"
+
+    def _params(self) -> et.Element:
+        tree = et.parse(self._params_xml())
+        return tree.getroot()
+
+    def _params_element(self, xpath: str) -> et.Element:
+        element = self._params().find(xpath)
+        if element is None:
+            raise ValueError(f"'{xpath}' not found in XML")
+        return element
+
+    @property
+    def name(self) -> str:
+        return self._params_element(".//void[@property='name']/string").text or "Unknown"
+
+    @property
+    def short_name(self) -> str:
+        return self._params_element(".//void[@property='shortName']/string").text or "Unknown"
+
+    @property
+    def workflow_provider(self) -> str:
+        return self._params_element(".//void[@property='workflowProvider']/object").get("class", "Unknown provider")
+
+    @property
+    def workflow_path(self) -> Path:
+        first_output_file = self.output_files[0]
+        return next(d for d in first_output_file.parents if d.suffix == ".flow")
+
+    @property
+    def citygml(self) -> str:
+        return self._params_element(".//void[@property='cityGmlFileNames']//string").text or "Unknown CityGML"
+
+    @property
+    def project_path(self) -> Path:
+        return self.workflow_path.parent
+
+    @property
+    def project(self) -> str:
+        return self.project_path.stem
+
+    @property
+    def repository(self) -> Path:
+        return self.project_path.parent
+
+    def relative_paths(self) -> list[str]:
+        return [f.relative_to(self.workflow_path).as_posix() for f in self.output_files]
+
+    def __str__(self) -> str:
+        return f"{self.description} ({self.class_name})"
+
+    def __repr__(self) -> str:
+        files_description = "\n".join(f"  - {f}" for f in self.relative_paths())
+        kpis = "\n".join(f"  {k}" for k in self.kpis)
+        return (
+            f"{self.description} ({self.class_name}, {self.project}, "
+            f"{self.workflow_path.name}, {self.citygml})\n{files_description}\n{kpis}"
+        )
+
+    @property
+    def class_name(self) -> str:
+        return type(self).__name__
+
+    @property
+    def csv_path(self) -> Path:
+        csvs = self.get_all_by_extension(".csv")
+        relevant_csvs = [csv for csv in csvs if self.csv_identifier in csv.name]
+        if len(relevant_csvs) == 0:
+            raise ValueError("Workflow didn't seem to have returned any CSV file!")
+        if len(relevant_csvs) > 1:
+            logger.warning("Too many CSV results found for %s", self)
+        return relevant_csvs[-1]
+
+    def csv_content(self) -> bytes:
+        with open(self.csv_path, "rb") as f:
+            return f.read()
+
+    def get_all_by_extension(self, ext: str) -> list[Path]:
+        return [f for f in sorted(self.output_files) if f.suffix == ext]
+
+    @property
+    def diagrams(self) -> dict[str, Path]:
+        return {}
+
+    def log_content(self) -> bytes:
+        logs = self.get_all_by_extension(".log")
+        if len(logs) == 0:
+            return b""
+        with open(logs[-1], "rb") as f:
+            return f.read()
+
+    def zip_content(self) -> bytes:
+        zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED, False) as zf:
+            for file_path in self.output_files:
+                zf.write(file_path, arcname=file_path.name)
+        zip_buffer.seek(0)
+        return zip_buffer.read()
+
+    def to_dict(self) -> dict:
+        data = {
+            "description": self.description,
+            "output_files": [str(path) for path in self.output_files],
+            "_type": self.class_name,
+            "_df_dict": self.dataframe.to_dict("records"),
+        }
+        if self.dataframe.attrs:
+            data["_df_attrs"] = self.dataframe.attrs
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SimStadtResults":
+        data.pop("_type", None)
+        df_dict = data.pop("_df_dict", None)
+        df_attrs = data.pop("_df_attrs", {})
+        data["output_files"] = [Path(p) for p in data["output_files"]]
+
+        if cls is SimStadtResults:
+            provider = get_workflow_provider(data["output_files"])
+            result = cls.create(provider, **data)
+        else:
+            result = cls(**data)
+
+        result._df = pd.DataFrame(df_dict)
+        result._df.attrs = df_attrs
+        return result
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "SimStadtResults":
+        return cls.from_dict(json.loads(json_str))
+
+    @classmethod
+    def create(cls, provider: str, **kwargs) -> "SimStadtResults":
+        if provider not in cls._registry:
+            raise ValueError(f"Unknown workflow provider: {provider}")
+        return cls._registry[provider](**kwargs)
+
+
+@dataclass(repr=False)
+class HeatDemandResults(SimStadtResults):
+    """Results for Heat Demand (and Heat+Cool Demand) workflows."""
+
+    MAX_FLAT_ROOF_DIFFERENCE = 0.1  # [m]
+    TOTAL_DEMAND = "Total Yearly Heating + DHW demand"
+
+    supported_providers: ClassVar[list[str]] = [
+        Providers.HEAT_DEMAND,
+        Providers.HEAT_DEMAND_WITH_SHADOW,
+        Providers.HEAT_DEMAND_WITH_REFURBISHMENT,
+        Providers.HEAT_DEMAND_WITH_HISTORIC_REFURBISHMENT,
+    ]
+    csv_identifier = "DIN18599"
+
+    def _parse_results(self) -> pd.DataFrame:
+        csv_decimal = detect_decimal(self.csv_path, 5, "Latitude")
+        df = pd.read_csv(self.csv_path, skiprows=list(range(19)) + [20], sep=";", decimal=csv_decimal)
+        df["has_flat_roof"] = (
+            df["Ridge/mean Height"] - df["Eaves/mean Height"] < self.MAX_FLAT_ROOF_DIFFERENCE
+        ).fillna(False)
+        df.attrs["Heating"] = "Yearly Heating demand" in df.columns
+        df.attrs["Cooling"] = "Yearly Cooling demand" in df.columns
+        return df
+
+    @property
+    def kpis(self) -> list[KPI]:
+        df = self.dataframe
+        custom_kpis = [KPI("Number of buildings", df.shape[0], precision=0)]
+        sums = [("Heated area", "m²"), ("Footprint area", "m²")]
+
+        if df.attrs["Heating"]:
+            specific_heat_demand = df[self.TOTAL_DEMAND].sum() / df["Heated area"].sum()
+            heated_buildings = int((df[self.TOTAL_DEMAND] > 10_000).sum())
+            custom_kpis.extend(
+                [
+                    KPI("Number of heated buildings", heated_buildings, precision=0),
+                    KPI("Specific Heating Demand", specific_heat_demand, "kWh / (m² · a)", precision=0),
+                ]
+            )
+            sums.extend(
+                [
+                    ("Yearly Heating demand", "kWh / a"),
+                    (self.TOTAL_DEMAND, "kWh / a"),
+                ]
+            )
+
+        if df.attrs["Cooling"]:
+            specific_cooling_demand = df["Yearly Cooling demand"].sum() / df["Heated area"].sum()
+            custom_kpis.append(KPI("Specific Cooling Demand", specific_cooling_demand, "kWh / (m² · a)", precision=0))
+            sums.append(("Yearly Cooling demand", "kWh / a"))
+
+        averages = [("Mean Uvalue", "W / (m² · K)", 1), ("Year of construction", None), ("Storey number", None)]
+        return custom_kpis + self._prepare_kpis(sums, averages)
+
+    @property
+    def diagrams(self) -> dict[str, Path]:
+        heat_png = self.workflow_path / "heating.png"
+        ax = self.monthly_df().plot.bar(
+            rot=0,
+            ylabel="[MWh]",
+            width=0.8,
+            color={"Monthly Heating Demand": "darkred", "Monthly Cooling Demand": "darkblue"},
+        )
+        plt.savefig(heat_png, bbox_inches="tight", dpi=300)
+        plt.close(ax.figure)
+        return {"Monthly demands": heat_png}
+
+    def monthly_df(self) -> pd.DataFrame:
+        months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+        df = self.dataframe
+        monthly_df = pd.DataFrame([], index=pd.Index(months))
+        for mode in ["Heating", "Cooling"]:
+            search_str = f"{mode} demand"
+            found_cols = [
+                col for col in df.columns if search_str in col and "Yearly" not in col and "Specific" not in col
+            ]
+            if found_cols:
+                monthly_df[f"Monthly {mode} Demand"] = (df[found_cols].sum() / 1000).values
+        return monthly_df
+
+
+@dataclass(repr=False)
+class PhotovoltaicResults(SimStadtResults):
+    """Results for Photovoltaic (PV) workflows."""
+
+    supported_providers: ClassVar[list[str]] = [
+        Providers.PHOTOVOLTAIC,
+        Providers.PHOTOVOLTAIC_FINANCE,
+        Providers.PHOTOVOLTAIC_WITH_SHADOW,
+    ]
+    csv_identifier = "_pv_potential"
+
+    def _count_header_lines(self) -> int:
+        count = 0
+        with open(self.csv_path) as csv:
+            for line in csv:
+                if line.startswith("Building ID"):
+                    return count
+                count += 1
+        raise ValueError(f"Header not found in {self.csv_path}")
+
+    def _parse_results(self) -> pd.DataFrame:
+        csv_decimal = detect_decimal(self.csv_path, 4, "Latitude")
+        header_length = self._count_header_lines()
+        df = pd.read_csv(
+            self.csv_path,
+            skiprows=list(range(header_length)) + [header_length + 1],
+            sep=";",
+            decimal=csv_decimal,
+        )
+        df = df.rename(columns={"Area": "Roof area for PV"})
+        return df.dropna(axis=1, how="all")
+
+    @property
+    def kpis(self) -> list[KPI]:
+        sums = [("Roof area for PV", "m²"), ("PV potential nominal power", "kWp"), ("PV potential yield", "MWh / a")]
+        averages = [("Irradiance in module plane", "W / m²"), ("PV specific yield", "kWh / (kWp · a)")]
+        return self._prepare_kpis(sums, averages)
+
+
+@dataclass(repr=False)
+class LoadProfileResults(SimStadtResults):
+    """Results for LoadProfile workflows.
+
+    The dataframe has one column per building (building GML ID as column name)
+    and 8760 rows of hourly energy demand [kWh/h].
+    """
+
+    supported_providers: ClassVar[list[str]] = [Providers.LOAD_PROFILE]
+    csv_identifier = "_load_profile_Hourly"
+
+    def _parse_results(self) -> pd.DataFrame:
+        csv_decimal = detect_decimal(self.csv_path, 6, "Area")
+        df = pd.read_csv(self.csv_path, skiprows=range(1, 12), sep=";", decimal=csv_decimal)
+        # First column is the timestamp; remaining columns are per-building loads
+        return df.drop(columns=[df.columns[0]])
+
+    @property
+    def kpis(self) -> list[KPI]:
+        # TODO: Add sum, average. Add timestep too?
+        # TODO: Add people? Add total heated area?
+        df = self.dataframe
+        total = df.sum().sum()
+        return [
+            KPI("Number of buildings", df.shape[1], precision=0),
+            KPI("Total load", total, "kWh/a", precision=1),
+            KPI("Average load", total / 8760, "kWh/h", precision=1),
+        ]
+
+
+@dataclass(repr=False)
+class SolarPotentialResults(SimStadtResults):
+    """Results for SolarPotential workflows.
+
+    The output is a .prn weather file with 8760 hourly rows and three columns:
+    GHI (W/m²), DHI (W/m²), Ta (°C).
+    """
+
+    supported_providers: ClassVar[list[str]] = [Providers.SOLAR_POTENTIAL]
+    csv_identifier = "_solar_potential"  # no CSV output; csv_path will raise if called
+
+    def _parse_results(self) -> pd.DataFrame:
+        prn_paths = self.get_all_by_extension(".prn")
+        if len(prn_paths) != 1:
+            raise ValueError(f"Expected exactly one .prn file, found {len(prn_paths)}")
+        return pd.read_csv(prn_paths[0], sep=r"\s+", names=["GHI", "DHI", "Ta"], header=None)
+
+    @property
+    def kpis(self) -> list[KPI]:
+        df = self.dataframe
+        return [
+            #TODO: Add averages too?
+            KPI("Annual GHI", df["GHI"].sum() / 1000, "kWh/m²", precision=1),
+            KPI("Annual DHI", df["DHI"].sum() / 1000, "kWh/m²", precision=1),
+            KPI("Mean temperature", float(df["Ta"].mean()), "°C", precision=1),
+        ]
+
+
+@dataclass(repr=False)
+class GreenWaterResults(SimStadtResults):
+    """Results for GreenWater workflows (hourly time series with tree species breakdown)."""
+
+    csv_identifier = "_greenwater"
+    supported_providers: ClassVar[list[str]] = [Providers.GREEN_WATER]
+
+    def _parse_results(self) -> pd.DataFrame:
+        csv_decimal = detect_decimal(self.csv_path, 5, "tree area")
+        df = pd.read_csv(
+            self.csv_path,
+            sep=";",
+            header=[0, 1],
+            skiprows=list(range(8)) + list(range(10, 13)),
+            decimal=csv_decimal,
+        )
+
+        # Flatten multi-level columns: species names are forward-filled across sub-columns
+        cols = df.columns.tolist()
+        new_cols = []
+        current_species = "All"
+        species = []
+
+        for col in cols:
+            level0, level1 = col
+            if pd.notna(level0) and not level0.startswith("Unnamed") and not level0.startswith("#"):
+                current_species = level0
+                species.append(current_species)
+            new_cols.append(level1 if current_species == "All" else f"{current_species} - {level1}")
+
+        df.columns = new_cols
+
+        # Parse header metadata (tree counts, areas per species)
+        with open(self.csv_path, encoding="utf-8") as csv:
+            line = ""
+            for _ in range(5):
+                line = next(csv)
+            tree_count = int(line.split(";")[1])
+            line = next(csv)
+            tree_area_header = re.split("[;,]", line.strip())
+            total_tree_area = float(tree_area_header[1].replace(",", "."))
+            if tree_count == 0:
+                raise ValueError(f"CityGML {self.citygml} does not have any tree!")
+            for _ in range(5):
+                line = next(csv)
+            species_count = [int(c) for c in re.split(";+", line.strip())[1:-1]]
+            line = next(csv)
+            species_area = [float(c.replace(",", ".")) for c in re.split(";+", line.strip())[1:-1]]
+
+        species.pop(0)
+        df.attrs = {
+            "species": {
+                name: {"count": count, "area": area}
+                for name, count, area in zip(species, species_count, species_area)
+            },
+            "tree count": tree_count,
+            "tree area": total_tree_area,
+        }
+        return df
+
+    def df_with_time(self) -> pd.DataFrame:
+        """Return the dataframe with a DatetimeIndex (year 2005, hourly)."""
+        df = self.dataframe
+        times = pd.date_range(start="2005-01-01 00:00", freq="1h", periods=8760)
+        df = df.set_index(times)
+        return df.drop(columns=["#"])
+
+    @property
+    def kpis(self) -> list[KPI]:
+        df = self.dataframe
+        rain = df["Rain [mm]"].sum()
+        etc = df["Average ETc [mm]"].sum()
+        cooling = df["Evaporative cooling [kWh/h]"].sum() / 1000
+        irrigation_mm = df["Average irrigation [mm]"].sum()
+        tree_area = df.attrs["tree area"]
+        irrigation_m3 = irrigation_mm * tree_area / 1000
+        return [
+            KPI("Number of trees", df.attrs["tree count"], precision=0),
+            KPI("Projected tree area", tree_area, "m²", precision=1),
+            KPI("Rain", rain, "mm / a", precision=0),
+            KPI("Average ETc", etc, "mm / a", precision=0),
+            KPI("Irrigation", irrigation_m3, "m³ / a", precision=0),
+            KPI("Evaporative cooling", cooling, "MWh / a", precision=0),
+        ]
+
+    @property
+    def more_info(self) -> dict[str, list[KPI]]:
+        df = self.dataframe
+        all_info = {}
+        for name, info in df.attrs["species"].items():
+            count = info["count"]
+            area = info["area"]
+            irrigation_mm = df[f"{name} - Average irrigation [mm]"].sum()
+            average_area = area / count
+            all_info[f"_{name}_"] = [
+                KPI("Number of trees", count, precision=0),
+                KPI("Average tree area", average_area, "m²", precision=1),
+                KPI("Average ETc", df[f"{name} - Average ETc [mm]"].sum(), "mm / a", precision=0),
+                KPI("Irrigation", irrigation_mm, "mm / a", precision=0),
+                KPI("Average irrigation", average_area * irrigation_mm / 1000, "m³ / a", precision=0),
+            ]
+        return all_info
+
+    @property
+    def diagrams(self) -> dict[str, Path]:
+        rain_irrigation_png = self.workflow_path / "rain_and_irrigation.png"
+        df_months = self.df_with_time()[["Rain [mm]", "Average irrigation [mm]"]].resample("ME").sum()
+        fig, ax = plt.subplots()
+        df_months = df_months.rename(
+            columns={"Rain [mm]": "Niederschlag", "Average irrigation [mm]": "Künstliche Bewässerung"}
+        )
+        df_months.plot(kind="bar", stacked=True, ax=ax, ylabel="[mm]", figsize=(13, 6))
+        ax.set_xticklabels([x.strftime("%b") for x in df_months.index], rotation=0)
+        plt.savefig(rain_irrigation_png, bbox_inches="tight", dpi=300)
+        plt.close(fig)
+        return {"Rain and Irrigation": rain_irrigation_png}
+
+
+def create_simstadt_results(description: str, output_files: list[Path]) -> SimStadtResults:
+    """Factory: detect workflow type from params.xml and return the correct subclass."""
+    provider = get_workflow_provider(output_files)
+    return SimStadtResults.create(provider, description=description, output_files=sorted(output_files))

simstadt-0.1.0/src/simstadt/runner.py

@@ -0,0 +1,265 @@
+"""Run SimStadt workflows from Python.
+
+SimStadt is located via the SIMSTADT_FOLDER environment variable, or by globbing
+~/Desktop for SimStadt2_0.*/.
+
+Workflow templates (.flow directories) are located via the SIMSTADT_TEMPLATE_PATH
+environment variable. If unset, a Template/ directory in the current working directory
+is used as a fallback.
+"""
+
+import logging
+import os
+import platform
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from xml.etree import ElementTree as et
+
+from dotenv import load_dotenv
+
+from .results import SimStadtResults, create_simstadt_results
+from .utils import chdir, random_id
+
+PARAMS = "params.xml"
+SIMSTADT2_GLOB = "SimStadt2_0.*/"
+
+load_dotenv()
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# SimStadt discovery
+# ---------------------------------------------------------------------------
+
+def find_simstadt(parent_folder: Path, simstadt_glob: str = SIMSTADT2_GLOB) -> Path:
+    try:
+        found = next(parent_folder.glob(simstadt_glob))
+        log.info("# SimStadt found in %s\n", found)
+        return found
+    except StopIteration as e:
+        raise ValueError(
+            f"SimStadt not found in {parent_folder}/{simstadt_glob}. "
+            "Set the SIMSTADT_FOLDER environment variable."
+        ) from e
+
+
+def get_simstadt_folder() -> Path:
+    if "SIMSTADT_FOLDER" in os.environ:
+        return Path(os.environ["SIMSTADT_FOLDER"])
+    return find_simstadt(Path.home() / "Desktop")
+
+
+def get_template_path() -> Path:
+    if "SIMSTADT_TEMPLATE_PATH" in os.environ:
+        return Path(os.environ["SIMSTADT_TEMPLATE_PATH"])
+    fallback = Path.cwd() / "Template"
+    if fallback.exists():
+        return fallback
+    raise ValueError(
+        "No template path found. Set SIMSTADT_TEMPLATE_PATH or create a Template/ directory."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Low-level workflow helpers
+# ---------------------------------------------------------------------------
+
+def _simstadt_script() -> str:
+    return "SimStadt.bat" if platform.system().lower() == "windows" else "./SimStadt.sh"
+
+
+def _regionchooser_script() -> str:
+    return "RegionChooser.bat" if platform.system().lower() == "windows" else "./RegionChooser.sh"
+
+
+def check_paths(repo_path: Path, workflow_path: Path) -> None:
+    if not repo_path.exists():
+        raise ValueError(f"Repository not found: {repo_path}")
+    if not workflow_path.exists():
+        raise ValueError(f"Workflow not found: {workflow_path}")
+    if not (workflow_path / PARAMS).exists():
+        raise ValueError(f"No params.xml in {workflow_path}")
+
+
+def prepare_workflow(workflow_path: Path, citygmls: list[str]) -> str:
+    """Inject CityGML file names into the workflow's params.xml. Returns the workflow name."""
+    tree = et.parse(workflow_path / PARAMS)
+    root = tree.getroot()
+
+    node = root.find(".//void[@property='name']/string")
+    if node is None:
+        raise ValueError("Unknown workflow!")
+    name = node.text or "workflow"
+    log.info("# Preparing '%s' workflow (%s):", name, workflow_path.name)
+
+    citygml_node = root.find(".//void[@property='cityGmlFileNames']")
+    if citygml_node is not None:
+        for child in list(citygml_node):
+            citygml_node.remove(child)
+    else:
+        workflow_node = root.find(".//object[@class='eu.simstadt.workflows.CityGmlWorkflow']")
+        if workflow_node is None:
+            raise ValueError("Broken workflow!")
+        citygml_node = et.SubElement(workflow_node, "void")
+        citygml_node.set("property", "cityGmlFileNames")
+
+    for citygml in citygmls:
+        log.info("  * Adding %s", citygml)
+        add_node = et.SubElement(citygml_node, "void")
+        add_node.set("method", "add")
+        gml = et.SubElement(add_node, "string")
+        gml.text = citygml
+
+    tree.write(workflow_path / PARAMS)
+    return name
+
+
+def replace_params(workflow_path: Path, replaces: dict[str, str]) -> None:
+    """Apply regex substitutions to all params.xml files under the workflow path."""
+    param_files = list(workflow_path.glob(f"**/{PARAMS}"))
+    replaced = False
+    for param_file in param_files:
+        with open(param_file, encoding="utf-8") as f:
+            content = f.read()
+        new_content = content
+        for old, new in replaces.items():
+            new_content = re.sub(old, new, new_content)
+        if new_content != content:
+            log.debug("Replacing parameters in %s", param_file)
+            replaced = True
+            with open(param_file, "w", encoding="utf-8") as f:
+                f.write(new_content)
+    if not replaced:
+        log.warning("No parameter has been replaced! %r", replaces)
+
+
+def copy_workflow_from_template(
+    template_path: Path,
+    project_path: Path,
+    destination: str,
+    replaces: dict | None = None,
+) -> Path:
+    template_path = template_path.with_suffix(".flow")
+    workflow_path = (project_path / destination).with_suffix(".flow")
+    shutil.copytree(template_path, workflow_path, dirs_exist_ok=True)
+    if replaces:
+        replace_params(workflow_path, replaces)
+    return workflow_path
+
+
+def _get_all_files(folder: Path) -> dict[Path, float]:
+    return {f: f.stat().st_mtime for f in folder.glob("**/*") if f.is_file() and f.name != PARAMS}
+
+
+def _compare_written_files(repo_path: Path, before: dict, after: dict) -> list[Path]:
+    modified = []
+    log.info("# Listing written files:")
+    for result_file, mtime in after.items():
+        if mtime > before.get(result_file, 0):
+            log.info("  * '%s'", result_file.relative_to(repo_path))
+            modified.append(result_file)
+    log.info("")
+    return modified
+
+
+# ---------------------------------------------------------------------------
+# Public execution API
+# ---------------------------------------------------------------------------
+
+def get_simstadt_output(path: Path) -> str:
+    """Run SimStadt with the given path and return stdout regardless of exit code.
+
+    Useful for extracting version information from the startup banner.
+    """
+    with chdir(get_simstadt_folder()):
+        result = subprocess.run([_simstadt_script(), str(path)], text=True, capture_output=True, check=False)
+        return result.stdout
+
+
+def run_simstadt(workflow_path: Path, name: str) -> str:
+    """Invoke the SimStadt CLI for the given workflow. Returns stdout."""
+    with chdir(get_simstadt_folder()):
+        log.info("Launching %s:", name)
+        result = subprocess.run(
+            [_simstadt_script(), str(workflow_path)], text=True, capture_output=True, check=False
+        )
+        if result.returncode != 0:
+            log.warning("  Workflow failed!\n%s", result.stdout)
+            raise ValueError("Workflow failed!")
+        log.debug(result.stdout)
+        log.info("  Workflow finished successfully!\n")
+        return result.stdout
+
+
+def run_regionchooser(*params: str) -> str:
+    """Invoke the SimStadt RegionChooser CLI. Returns stdout."""
+    with chdir(get_simstadt_folder()):
+        result = subprocess.run(
+            [_regionchooser_script(), *params], text=True, capture_output=True, check=True
+        )
+        log.debug(result.stdout)
+        return result.stdout
+
+
+def run_workflow(workflow_path: Path, citygmls: list[str]) -> list[Path]:
+    """Prepare and run a SimStadt workflow. Returns the list of files written by SimStadt."""
+    repo_path = workflow_path.parent.parent
+    check_paths(repo_path, workflow_path)
+    name = prepare_workflow(workflow_path, citygmls)
+    before = _get_all_files(workflow_path)
+    run_simstadt(workflow_path, name)
+    after = _get_all_files(workflow_path)
+    return _compare_written_files(repo_path, before, after)
+
+
+def run_workflow_with_citygml(
+    template: str | Path,
+    citygml_path: Path,
+    replaces: dict | None = None,
+    description: str | None = None,
+    destination: str | None = None,
+    project_path: Path | None = None,
+) -> SimStadtResults:
+    """Copy a workflow template, inject parameters, run SimStadt, and return parsed results.
+
+    Args:
+        template: Template name (resolved via SIMSTADT_TEMPLATE_PATH) or full Path.
+        citygml_path: Path to the CityGML input file.
+        replaces: Optional dict of XML-fragment regex replacements for params.xml.
+        description: Human-readable label for the result object.
+        destination: Output workflow folder name; defaults to a timestamped random id.
+        project_path: Directory where the workflow folder is created. Defaults to
+            citygml_path.parent. When set to a different directory, citygml_path is
+            passed as an absolute path so SimStadt can locate it.
+    """
+    if isinstance(template, str):
+        template_path = get_template_path() / template
+    else:
+        template_path = Path(template)
+    template_name = template_path.stem
+
+    if destination is None:
+        destination = random_id() + "_" + template_name.rsplit("_", 1)[-1]
+
+    if project_path is None:
+        project_path = citygml_path.parent
+        citygml_ref = citygml_path.name
+    else:
+        repo_path = project_path.parent
+        try:
+            citygml_ref = str(citygml_path.relative_to(repo_path))
+        except ValueError as e:
+            raise ValueError(
+                f"CityGML file {citygml_path} is not under the repository root {repo_path}. "
+                "Place the GML file inside the repository directory or omit project_path."
+            ) from e
+
+    workflow_path = copy_workflow_from_template(template_path, project_path, destination, replaces)
+    output_files = run_workflow(workflow_path, [citygml_ref])
+
+    if description is None:
+        description = f"{template_name} for {citygml_path.name}"
+    return create_simstadt_results(description, output_files)

simstadt-0.1.0/src/simstadt/utils.py

@@ -0,0 +1,66 @@
+import datetime
+import logging
+import os
+import random
+import re
+import string
+from contextlib import contextmanager
+from math import floor, log10
+from pathlib import Path
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+
+def significant_digits(value: float, sig_digits: int = 4) -> float:
+    """Round a number to a chosen number of significant digits."""
+    if value == 0:
+        return 0
+    order = floor(log10(abs(value)))
+    digits_after_point = sig_digits - order - 1
+    return round(value, digits_after_point)
+
+
+def format_number(value, decimal_sep=",", thousand_sep=" "):
+    """Format a number with thousand/decimal separators, removing trailing zeros."""
+    if value is None:
+        return ""
+    if not isinstance(value, (int, float)):
+        return value
+    return (
+        f"{value:,f}".rstrip("0").rstrip(".").replace(",", "X").replace(".", decimal_sep).replace("X", thousand_sep)
+    )
+
+
+def set_random_seed(input_string: str) -> None:
+    """Seed both random and numpy from a string so sampling is reproducible between runs."""
+    random.seed(input_string)
+    np.random.seed(random.randrange(1000))
+
+
+def random_id(n: int = 4, time: bool = True) -> str:
+    """Return a random string of n chars, optionally prefixed with YYYYMMDD_HHMM.
+    Uses a fresh Random() instance to avoid being affected by set_random_seed()."""
+    generator = random.Random()
+    generator.seed()
+    result = "".join(generator.choices(string.ascii_lowercase + string.digits, k=n))
+    if time:
+        result = datetime.datetime.now().strftime("%Y%m%d_%H%M_") + result
+    return result
+
+
+def remove_random_id(text: str) -> str:
+    """Strip a leading random_id prefix from a filename."""
+    return re.sub(r"^(20\d{6}_\d{4}_)?[a-z0-9]{4}_", "", text)
+
+
+@contextmanager
+def chdir(path: Path):
+    """Context manager that temporarily changes the working directory."""
+    oldpwd = os.getcwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(oldpwd)

simstadt-0.1.0/src/simstadt/workflows.py

@@ -0,0 +1,115 @@
+"""High-level simulation helpers for common SimStadt workflows.
+
+Each function wraps run_workflow_with_citygml() with a pre-built parameter dict
+for a specific workflow type (PV, heat demand, green water).
+"""
+
+from pathlib import Path
+
+from .results import SimStadtResults
+from .runner import run_workflow_with_citygml
+from .utils import remove_random_id, set_random_seed
+
+
+def _set_weather_file(meteonorm_filename: str) -> dict[str, str]:
+    """Build the params.xml replacement for the weather file."""
+    return {"<string>METEONORM_FILE</string>": f"<string>{Path(meteonorm_filename).name}</string>"}
+
+
+def _set_calculation_mode(calculation_mode: str) -> dict[str, str]:
+    allowed = ["HEATING", "COOLING", "HEATING_AND_COOLING"]
+    if calculation_mode not in allowed:
+        raise ValueError(f"{calculation_mode!r} must be one of {allowed}")
+    return {"<string>CALCULATION_MODE</string>": f"<string>{calculation_mode}</string>"}
+
+
+def _set_refurbishment(geg_ratio: float) -> dict[str, str]:
+    return {"<double>GEG_RATIO</double>": f"<double>{geg_ratio}</double>"}
+
+
+def photovoltaic_simulation(
+    citygml_path: Path | str,
+    meteonorm_filename: str,
+    roof_percentage: float = 100.0,
+    pv_share_flat: float = 40,
+    pv_share_tilted: float = 50,
+    min_roof_insolation: float = 1000,
+    hourly_pv: bool = False,
+    with_shadows: bool = True,
+    description: str = "Photovoltaic",
+) -> SimStadtResults:
+    """Run a PhotovoltaicPotential workflow.
+
+    Args:
+        citygml_path: Path to the CityGML input file.
+        meteonorm_filename: Weather file name (basename only, e.g. 'Wuerzburg-hour.csv').
+        roof_percentage: Fraction of roof surfaces to include (sampled randomly but reproducibly).
+        pv_share_flat: PV coverage [%] on flat roofs.
+        pv_share_tilted: PV coverage [%] on tilted roofs.
+        min_roof_insolation: Minimum irradiance threshold [kWh/(m²·a)].
+        hourly_pv: Whether to request hourly PV output.
+        with_shadows: Use the shadow-aware workflow template.
+        description: Label stored on the result object.
+    """
+    citygml_path = Path(citygml_path)
+    replaces = _set_weather_file(meteonorm_filename) | {
+        "<int>PV_SHARE_FLAT_ROOF</int>": f"<int>{pv_share_flat}</int>",
+        "<int>PV_SHARE_TILTED_ROOF</int>": f"<int>{pv_share_tilted}</int>",
+        "<int>MIN_ROOF_INSOLATION</int>": f"<int>{min_roof_insolation}</int>",
+        "<boolean>HOURLY_PV</boolean>": f"<boolean>{str(hourly_pv).lower()}</boolean>",
+    }
+    template = "105_PVWithShadow" if with_shadows else "103_PV"
+    pv_results = run_workflow_with_citygml(template, citygml_path, replaces=replaces, description=description)
+
+    set_random_seed(remove_random_id(citygml_path.name))
+    pv_results._df = pv_results.dataframe.sample(frac=roof_percentage / 100.0)
+    return pv_results
+
+
+def heatdemand_simulation(
+    citygml_path: Path | str,
+    meteonorm_filename: str,
+    with_shadows: bool = True,
+    calculation_mode: str = "HEATING",
+    refurbishment_ratio: float = 0.0,
+    description: str = "Heat demand",
+) -> SimStadtResults:
+    """Run a HeatDemand workflow.
+
+    Args:
+        citygml_path: Path to the CityGML input file.
+        meteonorm_filename: Weather file name or full path (basename is used).
+        with_shadows: Use the shadow-aware workflow template.
+        calculation_mode: One of 'HEATING', 'COOLING', or 'HEATING_AND_COOLING'.
+        refurbishment_ratio: GEG refurbishment ratio (0.0 = no refurbishment, 1.0 = full).
+        description: Label stored on the result object.
+    """
+    citygml_path = Path(citygml_path)
+    template = "104_HeatDemandWithShadow" if with_shadows else "101_HeatDemand"
+    replaces = (
+        _set_weather_file(meteonorm_filename)
+        | _set_calculation_mode(calculation_mode)
+        | _set_refurbishment(refurbishment_ratio)
+    )
+    return run_workflow_with_citygml(template, citygml_path, replaces=replaces, description=description)
+
+
+def greenwater_simulation(
+    citygml_path: Path | str,
+    meteonorm_filename: str,
+    irrigation_ratio: float,
+    description: str = "Green water",
+) -> SimStadtResults:
+    """Run a GreenWater workflow.
+
+    Args:
+        citygml_path: Path to the CityGML input file.
+        meteonorm_filename: Weather file name (basename only).
+        irrigation_ratio: 1.0 = always irrigate when needed; 0.0 = no irrigation.
+        description: Label stored on the result object.
+    """
+    citygml_path = Path(citygml_path)
+    replaces = _set_weather_file(meteonorm_filename) | {
+        "<double>MAX_WATER_STRESS</double>": f"<double>{1 - irrigation_ratio}</double>",
+    }
+    return run_workflow_with_citygml("102_GreenWater", citygml_path, replaces=replaces, description=description)