Eisenstadt

NEWS.md

@@ -1,7 +1,27 @@
 # kwb.raindrop (development version)
 
+## Bug fixes
+
+* `vignettes/example_wien_minimal.Rmd` now converts ET0 from mm/day to mm/h
+  (`value / period_et`) before writing `//Kurven/ET0`, mirroring the existing
+  rain conversion. The engine reads the ET0 curve as a mm/h rate, so the
+  unconverted daily values were integrated 24× too high — the cause of the
+  implausibly large modelled ET share. The timeseries-info summary now labels
+  ET0 as mm/h and recovers its total via `value * period_h`.
+
 ## New features
 
+* `inst/scripts/prepare_eisenstadt_swmm_timeseries.R` extracts the rain
+  (`/Kurven/Regen`) and ET0 (`/Kurven/ET0`) curves from an engine HDF5 and
+  writes SWMM-5 external time-series files. It converts **out** of the
+  engine's mm/h convention (rain → mm per interval for `[RAINGAGES]` VOLUME,
+  ET0 → mm/day for `[EVAPORATION]`). Pre-generated files for the bundled
+  Eisenstadt 2005 template ship under
+  `inst/extdata/models/eisenstadt-2005/swmm/` together with a README that
+  documents the mm/h-vs-mm/day pitfall: the kernel reads `/Kurven/ET0` as
+  **mm/h**, so a daily ET0 (mm/d) written there without dividing by 24 is
+  integrated 24× too high.
+
 * `download_engine()` fetches the Tandler "Regenwasserbewirtschaftung"
   Windows executable from the companion repository
   [`KWB-R/kwb.raindrop.binaries`](https://github.com/KWB-R/kwb.raindrop.binaries/releases)

inst/extdata/SOURCES.md

@@ -17,7 +17,11 @@ inst/extdata/models/
 │   ├── rain.csv.gz
 │   └── et.csv
 └── eisenstadt-2005/
-    └── base.h5
+    ├── base.h5
+    └── swmm/        # SWMM-5 rain / ET0 exported from base.h5 (see README)
+        ├── eisenstadt_rain.dat
+        ├── eisenstadt_et0.dat
+        └── README.md
 ```
 
 Access from R:
@@ -79,3 +83,12 @@ data:
   `source(system.file("scripts/prepare_wien_swmm_timeseries.R",
   package = "kwb.raindrop")); export_wien_swmm_timeseries(out_dir = ...)`
   or from the shell via `Rscript prepare_wien_swmm_timeseries.R <out_dir>`.
+
+* `prepare_eisenstadt_swmm_timeseries.R` — the Eisenstadt counterpart.
+  Eisenstadt ships no station CSVs, so this reads the rain (`/Kurven/Regen`)
+  and ET0 (`/Kurven/ET0`) curves straight from an engine `.h5` and writes
+  `eisenstadt_rain.dat` / `eisenstadt_et0.dat`. Crucially it converts out of
+  the engine's **mm/h** curve convention (rain → mm per interval, ET0 →
+  mm/day); see `models/eisenstadt-2005/swmm/README.md` for the mm/h-vs-mm/day
+  unit pitfall. Point `path_h5 =` at a real server input file to export the
+  measured Eisenstadt series.

inst/extdata/models/eisenstadt-2005/swmm/README.md

@@ -0,0 +1,74 @@
+# Eisenstadt 2005 — SWMM time series & ET0 units note
+
+Two SWMM-5 external time-series files extracted from the Eisenstadt engine
+template `../base.h5`, for cross-checking the Tandler calculation kernel
+against SWMM-UrbanEVA:
+
+| File                     | Content                         | Units in file                   | Rows   |
+|--------------------------|---------------------------------|---------------------------------|--------|
+| `eisenstadt_rain.dat`    | Rainfall, year 2005, 10-min     | mm per 10-min interval (VOLUME) | 52 560 |
+| `eisenstadt_rain_mmh.dat`| Rainfall, year 2005, 10-min     | mm/h, native (INTENSITY)        | 52 560 |
+| `eisenstadt_et0.dat`     | Reference ET0, year 2005, daily | mm/day                          | 365    |
+
+The rain is the **standard rain** baked into the engine template and is
+**already correct in mm/h** — the Eisenstadt run uses it as-is (no
+conversion). The two rain files are the *same* series in two SWMM-gage
+flavours: `*_mmh.dat` are the native mm/h intensities (peak 49.2 mm/h);
+`*_rain.dat` is the identical rain as depth per 10-min interval (peak
+8.2 mm = 49.2 / 6). Pick whichever your rain gage expects (INTENSITY vs
+VOLUME). **The rain is not where the unit problem is — only ET0 is.**
+
+Regenerate with:
+
+```r
+source(system.file("scripts/prepare_eisenstadt_swmm_timeseries.R",
+                   package = "kwb.raindrop"))
+export_eisenstadt_swmm_timeseries(out_dir = "<target>")                       # VOLUME rain + ET0
+export_eisenstadt_swmm_timeseries(out_dir = "<target>", rain_format = "intensity") # mm/h rain
+```
+
+## The units question (mm/h vs mm/d) — short answer
+
+**The engine curves `/Kurven/Regen` and `/Kurven/ET0` are RATES in mm/h on
+an hour-based time axis** (the axis runs `0 .. 8759.833 h` = one year, step
+1/6 h = 10 min). Evidence:
+
+* **Rain** only makes physical sense as mm/h: `sum(rate) * (1/6 h) = 657 mm/a`
+  for this template. Reading the same numbers as "mm per 10-min interval"
+  gives `3943 mm/a` — impossible for eastern Austria.
+* The **Wien / Bad Aussee vignettes explicitly convert** rain from mm-per-interval
+  to mm/h before writing the curve
+  (`workflow_wien.Rmd`: `### Convert rain from mm to mm/h; value <- value / period`).
+
+So the calculation kernel **expects ET0 in mm/h as well**. This is exactly
+the trap Daniel flagged: a value supplied in **mm/day** but written into the
+mm/h curve is integrated by the engine as mm/h and ends up **24× too high**.
+
+### Where this bites
+
+* **Wien / Bad Aussee:** the vignettes read a *daily* ET0 CSV (`et.csv`,
+  mm/day) and write it to `/Kurven/ET0` **without** the `/ 24` (or `/ period`)
+  step that rain gets — see `workflow_wien.Rmd`, the `vals$.../Kurven/ET0 <- timeseries_et`
+  line. If the kernel reads that curve as mm/h, Wien ET0 is ~24× too high,
+  which is consistent with the implausibly high ~46 % evaporation share.
+* **Eisenstadt:** the Eisenstadt vignettes do **not** inject any ET0/rain CSV
+  (there is no `et.csv` for Eisenstadt). They run on this template's curves,
+  i.e. a **constant placeholder ET0 = 0.2 mm/h (= 4.8 mm/d, 1752 mm/a)**.
+  That modest constant — not a measured series — is why Eisenstadt's
+  evaporation share (~17 %) lands lower than Wien's, while both stay too high.
+
+### Conversion applied in these files
+
+| Quantity | Engine curve | SWMM file | Conversion              |
+|----------|--------------|-----------|-------------------------|
+| Rain     | mm/h         | mm/10-min | `value[mm/h] * (10/60)` |
+| ET0      | mm/h         | mm/day    | `value[mm/h] * 24`      |
+
+> **Caveat — what these files represent:** all three bundled `base.h5`
+> templates (Wien, Bad Aussee, Eisenstadt) are byte-identical, so the rain
+> curve here is the template's 10-min year (657 mm/a) and the ET0 curve is
+> the constant 0.2 mm/h placeholder. They reproduce exactly what the
+> Eisenstadt *model template* feeds the kernel — **not** a measured
+> Eisenstadt meteorology. For a real Eisenstadt run, point
+> `export_eisenstadt_swmm_timeseries(path_h5 = ...)` at the actual server
+> input `.h5`; the same mm/h → SWMM conversion then yields the correct CSVs.