Upload YEL_2_0_Inference.ipynb

YEL_2_0_Inference.ipynb

@@ -0,0 +1,290 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# YEL 2.0 wind-field inference\n",
+    "\n",
+    "This notebook downloads the public **SustainableUrbanSystemsLab/Yel-2.0** ONNX model and runs it using the same 8-channel, 504 × 504 feature layout as Eddy3D's `Wind Predictor` component.\n",
+    "\n",
+    "> Important: YEL 1.0 is a different, 3-channel GAN architecture. This notebook intentionally uses **YEL 2.0**.\n",
+    "\n",
+    "Your input CSV should contain one row per 2 m grid point and these columns:\n",
+    "\n",
+    "| Column | Meaning |\n",
+    "|---|---|\n",
+    "| `x`, `y` | World coordinates in metres |\n",
+    "| `z_relative` | Evaluation height relative to the local ground/building datum (m) |\n",
+    "| `sdf` | Signed-distance feature used by Eddy3D (m; typically negative distance to the nearest building) |\n",
+    "| `building_height` | Building height at the point (m) |\n",
+    "| `u_ratio` | Atmospheric-profile velocity at `z_relative`, divided by reference velocity |\n",
+    "\n",
+    "The notebook includes a synthetic open-terrain example so every cell can run before you load real data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install -q numpy pandas matplotlib onnxruntime huggingface_hub"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "import onnxruntime as ort\n",
+    "import pandas as pd\n",
+    "from huggingface_hub import hf_hub_download\n",
+    "\n",
+    "MODEL_REPO = \"SustainableUrbanSystemsLab/Yel-2.0\"\n",
+    "MODEL_FILE = \"Yel.onnx\"\n",
+    "\n",
+    "H = W = 504\n",
+    "CHANNELS = 8\n",
+    "X_MIN, X_MAX, X_STEP = -485.0, 521.0, 2.0\n",
+    "Y_MIN, Y_MAX, Y_STEP = -514.5, 491.5, 2.0\n",
+    "REQUIRED_COLUMNS = [\"x\", \"y\", \"z_relative\", \"sdf\", \"building_height\", \"u_ratio\"]\n",
+    "\n",
+    "# User settings\n",
+    "INPUT_CSV = None  # Example: Path(\"my_yel_features.csv\"); keep None to run the demo\n",
+    "WIND_DIRECTIONS_DEG = [0, 45, 90, 180, 270]\n",
+    "REFERENCE_WIND_SPEED = 5.0  # Uref in m/s\n",
+    "OUTPUT_CSV = Path(\"yel_predictions.csv\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Load features\n",
+    "\n",
+    "The demo represents open terrain at pedestrian level. It is useful for checking the inference pipeline, but meaningful building predictions require features prepared from your own geometry (or exported from Eddy3D's preprocessing workflow)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def make_demo_features(step=2.0, extent=160.0):\n",
+    "    xs = np.arange(-extent, extent + step, step, dtype=np.float32)\n",
+    "    ys = np.arange(-extent, extent + step, step, dtype=np.float32)\n",
+    "    xx, yy = np.meshgrid(xs, ys)\n",
+    "    n = xx.size\n",
+    "    return pd.DataFrame({\n",
+    "        \"x\": xx.ravel(),\n",
+    "        \"y\": yy.ravel(),\n",
+    "        \"z_relative\": np.full(n, 1.8, dtype=np.float32),\n",
+    "        \"sdf\": np.full(n, -100.0, dtype=np.float32),\n",
+    "        \"building_height\": np.zeros(n, dtype=np.float32),\n",
+    "        \"u_ratio\": np.ones(n, dtype=np.float32),\n",
+    "    })\n",
+    "\n",
+    "if INPUT_CSV is None:\n",
+    "    features = make_demo_features()\n",
+    "    print(\"Using the synthetic open-terrain demo.\")\n",
+    "else:\n",
+    "    features = pd.read_csv(INPUT_CSV)\n",
+    "    print(f\"Loaded {len(features):,} rows from {INPUT_CSV}\")\n",
+    "\n",
+    "missing = sorted(set(REQUIRED_COLUMNS) - set(features.columns))\n",
+    "if missing:\n",
+    "    raise ValueError(f\"Missing required CSV columns: {missing}\")\n",
+    "if features[REQUIRED_COLUMNS].isna().any().any():\n",
+    "    raise ValueError(\"The required feature columns contain missing values.\")\n",
+    "\n",
+    "features.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download and inspect YEL 2.0"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_path = Path(hf_hub_download(repo_id=MODEL_REPO, filename=MODEL_FILE))\n",
+    "providers = [\"CPUExecutionProvider\"]\n",
+    "session = ort.InferenceSession(str(model_path), providers=providers)\n",
+    "\n",
+    "input_meta = session.get_inputs()[0]\n",
+    "output_meta = session.get_outputs()[0]\n",
+    "print(f\"Model:  {model_path}\")\n",
+    "print(f\"Input:  {input_meta.name} {input_meta.shape} ({input_meta.type})\")\n",
+    "print(f\"Output: {output_meta.name} {output_meta.shape} ({output_meta.type})\")\n",
+    "\n",
+    "shape = input_meta.shape\n",
+    "known_shape = tuple(v if isinstance(v, int) else None for v in shape)\n",
+    "expected = (1, CHANNELS, H, W)\n",
+    "if any(actual is not None and actual != wanted for actual, wanted in zip(known_shape, expected)):\n",
+    "    raise ValueError(\n",
+    "        f\"Expected a YEL 2.0 input compatible with {expected}, but the model reports {shape}. \"\n",
+    "        \"Make sure you did not download YEL 1.0.\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Assemble Eddy3D-compatible tensors\n",
+    "\n",
+    "Channels are: `x`, `y`, `z_relative`, `sdf`, `building_height`, `u_ratio`, `-sin(direction)`, and `-cos(direction)`. Feature values and direction values are scattered only at supplied grid points, matching the plugin."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def prepare_base_tensor(frame):\n",
+    "    data = frame.copy().reset_index(drop=True)\n",
+    "    ix = np.rint((data[\"x\"].to_numpy() - X_MIN) / X_STEP).astype(np.int64)\n",
+    "    iy = np.rint((data[\"y\"].to_numpy() - Y_MIN) / Y_STEP).astype(np.int64)\n",
+    "    valid = (ix >= 0) & (ix < W) & (iy >= 0) & (iy < H)\n",
+    "    if not valid.any():\n",
+    "        raise ValueError(\"No input points fall inside YEL's fixed world grid.\")\n",
+    "\n",
+    "    tensor = np.zeros((1, CHANNELS, H, W), dtype=np.float32)\n",
+    "    tensor[0, 0] = np.broadcast_to(np.linspace(X_MIN, X_MAX, W, dtype=np.float32), (H, W))\n",
+    "    tensor[0, 1] = np.broadcast_to(np.linspace(Y_MIN, Y_MAX, H, dtype=np.float32)[:, None], (H, W))\n",
+    "\n",
+    "    rows, cols = iy[valid], ix[valid]\n",
+    "    for channel, column in enumerate(REQUIRED_COLUMNS[2:], start=2):\n",
+    "        tensor[0, channel, rows, cols] = data.loc[valid, column].to_numpy(dtype=np.float32)\n",
+    "\n",
+    "    return data, tensor, ix, iy, valid\n",
+    "\n",
+    "\n",
+    "def tensor_for_direction(base_tensor, ix, iy, valid, direction_deg):\n",
+    "    tensor = base_tensor.copy()\n",
+    "    radians = np.deg2rad(direction_deg)\n",
+    "    rows, cols = iy[valid], ix[valid]\n",
+    "    tensor[0, 6, rows, cols] = np.float32(-np.sin(radians))\n",
+    "    tensor[0, 7, rows, cols] = np.float32(-np.cos(radians))\n",
+    "    return tensor\n",
+    "\n",
+    "\n",
+    "data, base_tensor, grid_x, grid_y, valid_mask = prepare_base_tensor(features)\n",
+    "print(f\"{valid_mask.sum():,}/{len(data):,} points are inside the fixed YEL grid.\")\n",
+    "if valid_mask.sum() < len(data):\n",
+    "    print(f\"Grid limits: X={X_MIN}…{X_MAX}, Y={Y_MIN}…{Y_MAX} metres\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run inference\n",
+    "\n",
+    "YEL's velocity output is normalized as `U/Uref`; the code multiplies velocity channels by `REFERENCE_WIND_SPEED`. If the model has extra output channels, the Eddy3D convention is: pedestrian velocity, pedestrian TKE, roof velocity, roof TKE."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "CHANNEL_NAMES = [\"wind_speed_m_s\", \"tke_m2_s2\", \"roof_wind_speed_m_s\", \"roof_tke_m2_s2\"]\n",
+    "\n",
+    "\n",
+    "def run_direction(direction_deg):\n",
+    "    model_input = tensor_for_direction(base_tensor, grid_x, grid_y, valid_mask, direction_deg)\n",
+    "    output = session.run(None, {input_meta.name: model_input})[0]\n",
+    "    if output.ndim != 4:\n",
+    "        raise ValueError(f\"Expected a 4D model output, received shape {output.shape}\")\n",
+    "\n",
+    "    result = data[[\"x\", \"y\"]].copy()\n",
+    "    result[\"wind_direction_deg\"] = direction_deg\n",
+    "    for channel in range(min(output.shape[1], len(CHANNEL_NAMES))):\n",
+    "        values = np.zeros(len(data), dtype=np.float32)\n",
+    "        values[valid_mask] = output[0, channel, grid_y[valid_mask], grid_x[valid_mask]]\n",
+    "        if channel in (0, 2):\n",
+    "            values *= REFERENCE_WIND_SPEED\n",
+    "        result[CHANNEL_NAMES[channel]] = np.maximum(values, 0.0)\n",
+    "    return result\n",
+    "\n",
+    "\n",
+    "predictions = pd.concat(\n",
+    "    [run_direction(direction) for direction in WIND_DIRECTIONS_DEG],\n",
+    "    ignore_index=True,\n",
+    ")\n",
+    "predictions.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Plot and export results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "directions = list(dict.fromkeys(predictions[\"wind_direction_deg\"]))\n",
+    "fig, axes = plt.subplots(\n",
+    "    1, len(directions), figsize=(5 * len(directions), 4), squeeze=False, constrained_layout=True\n",
+    ")\n",
+    "\n",
+    "vmax = float(predictions[\"wind_speed_m_s\"].max()) or 1.0\n",
+    "for axis, direction in zip(axes.ravel(), directions):\n",
+    "    view = predictions[predictions[\"wind_direction_deg\"] == direction]\n",
+    "    artist = axis.scatter(\n",
+    "        view[\"x\"], view[\"y\"], c=view[\"wind_speed_m_s\"], s=8,\n",
+    "        cmap=\"turbo\", vmin=0, vmax=vmax\n",
+    "    )\n",
+    "    axis.set(title=f\"Wind from {direction:g}°\", xlabel=\"X (m)\", ylabel=\"Y (m)\", aspect=\"equal\")\n",
+    "    fig.colorbar(artist, ax=axis, label=\"Wind speed (m/s)\")\n",
+    "\n",
+    "plt.show()\n",
+    "predictions.to_csv(OUTPUT_CSV, index=False)\n",
+    "print(f\"Saved {len(predictions):,} predictions to {OUTPUT_CSV.resolve()}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Optional: faster hardware\n",
+    "\n",
+    "The notebook defaults to CPU for portability. On Windows with a supported GPU, install `onnxruntime-directml` instead of `onnxruntime` and create the session with `providers=[\"DmlExecutionProvider\", \"CPUExecutionProvider\"]`. For NVIDIA CUDA, use the matching `onnxruntime-gpu` package and `CUDAExecutionProvider`."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}