{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "779bf92c",
   "metadata": {},
   "source": [
    "# Localities & MockupSPWXLSX — Belgian admin data & stormwater sizing\n",
    "\n",
    "- **`Localities`** — Belgian municipality lookup by INS code or name\n",
    "- **`MockupSPWXLSX`** — stormwater retention basin sizing (SPW methodology)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26c1afa3",
   "metadata": {},
   "source": [
    "## Part 1 — Localities: INS code lookup\n",
    "\n",
    "The `Localities` class provides bidirectional lookup between Belgian\n",
    "municipality names and their INS codes (Statbel/REFNIS)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "593a3514",
   "metadata": {},
   "outputs": [],
   "source": [
    "from wolfhece.ins import Localities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "270d5997",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Liège -> INS 62063\n",
      "INS 62063 -> Liège\n",
      "\n",
      "Total municipalities: 637\n",
      "First 5: ['royaume', 'région de bruxelles-capitale', 'arrondissement de bruxelles-capitale', 'anderlecht', 'auderghem']\n"
     ]
    }
   ],
   "source": [
    "# Available datasets: 2018, 2019, 2025\n",
    "loc = Localities(which=2019)\n",
    "\n",
    "# Name -> INS code\n",
    "code = loc.get_INSfromname('Liège')\n",
    "print(f\"Liège -> INS {code}\")\n",
    "\n",
    "# INS code -> Name\n",
    "name = loc.get_namefromINS(62063)\n",
    "print(f\"INS 62063 -> {name}\")\n",
    "\n",
    "# List all\n",
    "all_names = loc.get_allnames()\n",
    "print(f\"\\nTotal municipalities: {len(all_names)}\")\n",
    "print(f\"First 5: {all_names[:5]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bdb5a6e3",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Part 2 — MockupSPWXLSX: stormwater retention basin sizing\n",
    "\n",
    "This class implements the SPW (Service Public de Wallonie) methodology for computing\n",
    "the required retention capacity of a stormwater basin, using:\n",
    "\n",
    "- IRM rainfall data (QDF / Montana curves)\n",
    "- Land-use weighted runoff coefficients\n",
    "- Infiltration parameters (Darcy)\n",
    "- Admissible outflow\n",
    "\n",
    "All quantities use `pint` units for automatic conversion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "7e6e2595",
   "metadata": {},
   "outputs": [],
   "source": [
    "from wolfhece.mockup_spw_xlsx import MockupSPWXLSX, UNITS, LandUse"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "70e72811",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total area            : 1700.0 meter ** 2\n",
      "Weighted (runoff) area: 780.0 meter ** 2\n"
     ]
    }
   ],
   "source": [
    "m = MockupSPWXLSX()\n",
    "\n",
    "# 1. Set the locality (for IRM rainfall data)\n",
    "m.set_locality('Liège')\n",
    "\n",
    "# 2. Define sub-areas by land use\n",
    "m.add_area('parking',  LandUse.IMPERVIOUS_SURFACES, 500)            # 500 m²\n",
    "m.add_area('building', LandUse.IMPERVIOUS_SURFACES, 200)            # 200 m²\n",
    "m.add_area('garden',   LandUse.GRASSLANDS, 0.1 * UNITS.hectare)     # 1000 m²\n",
    "\n",
    "print(f\"Total area            : {m.total_area.to('m**2'):.1f}\")\n",
    "print(f\"Weighted (runoff) area: {m.total_area_ponderated.to('m**2'):.1f}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "8a89cdd5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Retention capacity (T=25): 22.00 meter ** 3\n",
      "Design rainfall duration : 1.33 hour\n",
      "Emptying time           : 4.53 hour\n"
     ]
    }
   ],
   "source": [
    "# 3. Set infiltration and outflow parameters\n",
    "m.infiltration_area = 100 * UNITS.meter**2\n",
    "m.infiltration_darcy = 1e-5 * UNITS.meter / UNITS.second\n",
    "m.admissible_outflow = 5.0  # L/s/ha (default unit)\n",
    "\n",
    "# 4. Compute retention capacity for a 25-year return period\n",
    "vol = m.get_retention_capacity(return_period=25)\n",
    "print(f\"\\nRetention capacity (T=25): {vol.to('m**3'):.2f}\")\n",
    "print(f\"Design rainfall duration : {m.design_rainfall_duration.to('hour'):.2f}\")\n",
    "print(f\"Emptying time           : {m.emptying_time.to('hour'):.2f}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "1d076dbd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Reloaded capacity: 22.00 meter ** 3\n"
     ]
    }
   ],
   "source": [
    "# 5. Save / reload as JSON\n",
    "import tempfile\n",
    "from pathlib import Path\n",
    "\n",
    "tmpdir = Path(tempfile.mkdtemp())\n",
    "m.to_json(str(tmpdir / 'project.json'))\n",
    "\n",
    "m2 = MockupSPWXLSX.from_json(str(tmpdir / 'project.json'))\n",
    "vol2 = m2.get_retention_capacity(return_period=25)\n",
    "print(f\"Reloaded capacity: {vol2.to('m**3'):.2f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18dc801f",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "| Class | Purpose |\n",
    "|-------|--------|\n",
    "| `Localities` | Belgian INS code ↔ municipality name lookup |\n",
    "| `MockupSPWXLSX` | Stormwater retention basin sizing (SPW method) |\n",
    "| `LandUse` | Enum of land-use categories with runoff coefficients |\n",
    "| `UNITS` | `pint.UnitRegistry` for physical quantities |"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python311",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}