Basic CLAUDE.md

CLAUDE.md

+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`simstadtpy` is a Python library for running and testing [SimStadt](https://simstadt.hft-stuttgart.de/) workflows programmatically. SimStadt is a city simulation tool for energy/urban analysis. The library wraps SimStadt's CLI to execute workflows against CityGML files and parse the results into pandas DataFrames.
+
+This project is in early development. The goal is to consolidate code from two prior projects (`old/cgsc/` and `old/sektorsim/`) into a proper library under `src/simstadtpy/`.
+
+## Commands
+
+This project uses [uv](https://docs.astral.sh/uv/) as the package manager.
+
+```bash
+# Install dependencies and set up venv
+uv sync
+
+# Run the CLI entry point
+uv run simstadtpy
+
+# Run tests (once added — use pytest)
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_foo.py::TestClass::test_method
+```
+
+SimStadt itself must be installed separately. Its location is resolved via:
+1. `SIMSTADT_FOLDER` environment variable (preferred), or
+2. Glob search for `SimStadt2_0.*/` on `~/Desktop`
+
+## Architecture
+
+The library wraps SimStadt's command-line interface. The core flow is:
+
+1. **Workflow templates** (`.flow` directories containing `params.xml`) are copied to a project folder
+2. `params.xml` files are modified via regex substitution to inject CityGML file paths and simulation parameters
+3. SimStadt is invoked as a subprocess (`SimStadt.sh` / `SimStadt.bat`)
+4. Output files written by SimStadt are detected by comparing filesystem mtimes before/after the run
+5. Output files are parsed into typed `SimStadtResults` subclasses
+
+### Key classes to port from `old/`
+
+- **`SimStadtResults`** (`old/cgsc/lib/simstadt_results.py`) — Abstract base class with factory pattern. Subclasses:
+  - `HeatDemandResults` — parses DIN18599 CSV output
+  - `PhotovoltaicResults` — parses PV potential CSV output
+  - `GreenWaterResults` — parses hourly greenwater CSV with multi-level headers
+  - Each subclass exposes `.dataframe`, `.kpis`, `.diagrams`, `.csv_path`, `.to_json()`/`.from_json()`
+  - Provider-to-class registration via `__init_subclass__` (registry pattern)
+
+- **`run_workflow_with_citygml()`** (`old/cgsc/lib/run_simstadt_workflow.py`) — Main entry point for running a simulation. Takes a template name/path, a CityGML path, and optional parameter replacements dict.
+
+- **Workflow simulation helpers** (`old/cgsc/lib/simstadt_workflows.py`) — High-level functions (`photovoltaic_simulation`, `heatdemand_simulation`, `greenwater_simulation`) that call `run_workflow_with_citygml` with pre-built parameter dicts.
+
+### Parameter replacement convention
+
+Workflow parameters are replaced via regex on `params.xml` content. Keys are XML fragments, e.g.:
+```python
+{"<string>METEONORM_FILE</string>": "<string>Wuerzburg-hour.csv</string>"}
+```
+
+### Workflow templates
+
+Templates live in a `Template/` directory alongside the project. Template names follow the pattern `NNN_WorkflowName` (e.g. `101_HeatDemand`, `103_PV`, `104_HeatDemandWithShadow`).
+
+### SimStadt project structure on disk
+
+```
+<Repository>/
+  <ProjectName>.proj/
+    *.gml                    # CityGML input files
+    <workflow_id>.flow/      # Copied from template, contains params.xml + outputs
+```