Localities & MockupSPWXLSX — Belgian admin data & stormwater sizing

• ``Localities`` — Belgian municipality lookup by INS code or name

• ``MockupSPWXLSX`` — stormwater retention basin sizing (SPW methodology)

Part 1 — Localities: INS code lookup

The Localities class provides bidirectional lookup between Belgian municipality names and their INS codes (Statbel/REFNIS).

from wolfhece.ins import Localities

# Available datasets: 2018, 2019, 2025
loc = Localities(which=2019)

# Name -> INS code
code = loc.get_INSfromname('Liège')
print(f"Liège -> INS {code}")

# INS code -> Name
name = loc.get_namefromINS(62063)
print(f"INS 62063 -> {name}")

# List all
all_names = loc.get_allnames()
print(f"\nTotal municipalities: {len(all_names)}")
print(f"First 5: {all_names[:5]}")

Liège -> INS 62063
INS 62063 -> Liège

Total municipalities: 637
First 5: ['royaume', 'région de bruxelles-capitale', 'arrondissement de bruxelles-capitale', 'anderlecht', 'auderghem']

---

Part 2 — MockupSPWXLSX: stormwater retention basin sizing

This class implements the SPW (Service Public de Wallonie) methodology for computing the required retention capacity of a stormwater basin, using:

• IRM rainfall data (QDF / Montana curves)

• Land-use weighted runoff coefficients

• Infiltration parameters (Darcy)

• Admissible outflow

All quantities use pint units for automatic conversion.

from wolfhece.mockup_spw_xlsx import MockupSPWXLSX, UNITS, LandUse

m = MockupSPWXLSX()

# 1. Set the locality (for IRM rainfall data)
m.set_locality('Liège')

# 2. Define sub-areas by land use
m.add_area('parking',  LandUse.IMPERVIOUS_SURFACES, 500)            # 500 m²
m.add_area('building', LandUse.IMPERVIOUS_SURFACES, 200)            # 200 m²
m.add_area('garden',   LandUse.GRASSLANDS, 0.1 * UNITS.hectare)     # 1000 m²

print(f"Total area            : {m.total_area.to('m**2'):.1f}")
print(f"Weighted (runoff) area: {m.total_area_ponderated.to('m**2'):.1f}")

Total area            : 1700.0 meter ** 2
Weighted (runoff) area: 780.0 meter ** 2

# 3. Set infiltration and outflow parameters
m.infiltration_area = 100 * UNITS.meter**2
m.infiltration_darcy = 1e-5 * UNITS.meter / UNITS.second
m.admissible_outflow = 5.0  # L/s/ha (default unit)

# 4. Compute retention capacity for a 25-year return period
vol = m.get_retention_capacity(return_period=25)
print(f"\nRetention capacity (T=25): {vol.to('m**3'):.2f}")
print(f"Design rainfall duration : {m.design_rainfall_duration.to('hour'):.2f}")
print(f"Emptying time           : {m.emptying_time.to('hour'):.2f}")

Retention capacity (T=25): 22.00 meter ** 3
Design rainfall duration : 1.33 hour
Emptying time           : 4.53 hour

# 5. Save / reload as JSON
import tempfile
from pathlib import Path

tmpdir = Path(tempfile.mkdtemp())
m.to_json(str(tmpdir / 'project.json'))

m2 = MockupSPWXLSX.from_json(str(tmpdir / 'project.json'))
vol2 = m2.get_retention_capacity(return_period=25)
print(f"Reloaded capacity: {vol2.to('m**3'):.2f}")

Reloaded capacity: 22.00 meter ** 3

Summary

Class	Purpose
Localities	Belgian INS code ↔ municipality name lookup
MockupSPWXLSX	Stormwater retention basin sizing (SPW method)
LandUse	Enum of land-use categories with runoff coefficients
UNITS	pint.UnitRegistry for physical quantities