{ "cells": [ { "cell_type": "markdown", "id": "5d91d650", "metadata": {}, "source": [ "# Matching Custom Inlet\n", "\n", "You have $U(z)$ and $I_u(z)$ profiles from a wind tunnel test and want to reproduce\n", "those exact conditions in AeroSim. The obstacle is that AeroSim's inlet does not\n", "accept velocity and turbulence intensity directly - it requires a Reynolds stress\n", "tensor at each height. This notebook walks through converting your measured\n", "profiles into the format AeroSim expects, configuring the ground roughness to\n", "match your tunnel floor, and confirming the profile is preserved at the model\n", "location.\n", "\n", "
\n", "Note. If you are working from a standard terrain category (e.g., Eurocode\n", "Category I-IV) without measured profiles, the\n", "ABL guided case\n", "covers that workflow end to end.\n", "
\n" ] }, { "cell_type": "markdown", "id": "d9e374aa", "metadata": {}, "source": [ "## What the SEM Profile Requires\n", "\n", "Before building the profile, establish the target format. The inlet CSV must\n", "contain the following columns:\n", "\n", "```\n", "z,ux,Rxx,Rxy,Rxz,Ryy,Ryz,Rzz\n", "```\n", "\n", "| Column | Physical quantity | Units | Notes |\n", "| --- | --- | --- | --- |\n", "| `z` | Height above ground | m | Must start at or near the ground; values outside the CSV range are extrapolated as constants |\n", "| `ux` | Mean streamwise velocity | m/s | Positive in the flow direction |\n", "| `Rxx` | Reynolds stress $\\overline{u'u'}$ | m^2/s^2 | Streamwise normal stress; always positive |\n", "| `Rxy` | Reynolds stress $\\overline{u'v'}$ | m^2/s^2 | Typically zero for neutral ABL with flow aligned to x |\n", "| `Rxz` | Reynolds stress $\\overline{u'w'}$ | m^2/s^2 | **Negative** in a standard ABL |\n", "| `Ryy` | Reynolds stress $\\overline{v'v'}$ | m^2/s^2 | Lateral normal stress; always positive |\n", "| `Ryz` | Reynolds stress $\\overline{v'w'}$ | m^2/s^2 | Typically zero for neutral ABL |\n", "| `Rzz` | Reynolds stress $\\overline{w'w'}$ | m^2/s^2 | Vertical normal stress; always positive |\n", "\n", "The Reynolds stress tensor at each height must be **positive semi-definite** -\n", "otherwise the Cholesky decomposition used internally by the SEM will fail or\n", "produce unphysical turbulence.\n", "\n", "
\n", "Important. The necessary condition most commonly violated in practice is\n", "the determinant constraint along the xz plane:\n", "\n", "$$\n", "R_{xx} \\cdot R_{zz} \\geq R_{xz}^2\n", "$$\n", "
\n" ] }, { "cell_type": "markdown", "id": "64fc28ba", "metadata": {}, "source": [ "## Step 1: Prepare Your Input Data\n", "\n", "### Mean Velocity Profile U(z)\n", "\n", "Your input is a set of height samples with mean streamwise velocity $U(z)$ -\n", "typically from pitot tube or hot-wire probe traverses at discrete heights above\n", "the tunnel floor. Collect these into a two-column table (z in metres, U in m/s)\n", "before proceeding.\n", "\n", "If measurements do not cover the full inlet height, you can extrapolate using\n", "a log-law fit $U = a + b\\ln(z)$ through the measured points, where $b = u_*/\\kappa$.\n", "This is optional: only do it if you need values at heights not covered by the\n", "traverse.\n", "\n", "### Turbulence Intensity Profile Iu(z)\n", "\n", "Turbulence intensity is defined as:\n", "\n", "$$\n", "I_u(z) = \\frac{\\sigma_u}{U(z)}\n", "$$\n", "\n", "Use the $I_u(z)$ values directly from your wind tunnel calibration report.\n", "These are measured quantities - do not substitute a code formula unless\n", "measured data is unavailable.\n", "\n", "### Aerodynamic Roughness Length z0\n", "\n", "The SEM inlet and the ground boundary condition both require a roughness length\n", "$z_0$. Use the value that characterises your wind tunnel floor roughness, as\n", "specified in your tunnel calibration sheet.\n", "\n", "If $z_0$ is not explicitly stated, fit the log-law through your measured $U(z)$\n", "traverse:\n", "\n", "$$\n", "U(z) = \\frac{u_*}{\\kappa} \\ln\\left(\\frac{z}{z_0}\\right)\n", "$$\n", "\n", "Fitting $U = a + b\\ln(z)$ gives $b = u_*/\\kappa$ and $z_0 = z \\exp(-U(z)/b)$\n", "at any measured point.\n" ] }, { "cell_type": "markdown", "id": "b8fa1495", "metadata": {}, "source": [ "## Step 2: Build the Profile CSV\n", "\n", "The cells below read your measured U(z) and Iu(z) data, derive all Reynolds\n", "stress components, check the positive semi-definiteness constraint, and write\n", "the inlet CSV. The input file must have at least three columns: `z` (m),\n", "`ux` (m/s), and `Iu` (dimensionless). If you also have measured `Iv` and `Iw`,\n", "add them as additional columns.\n", "\n", "For a full explanation of how each stress component is derived, see\n", "[Reynolds Stress Derivation](./reynolds-stress-derivation.md).\n" ] }, { "cell_type": "code", "id": "3728465e", "metadata": {}, "execution_count": null, "outputs": [], "source": [ "import numpy as np\n", "import pandas as pd\n", "\n", "# --- Load your measured wind tunnel profile ---\n", "# Required columns: z (m), ux (m/s), Iu (dimensionless)\n", "# Optional columns: Iv, Iw - use measured values when available\n", "inp = pd.read_csv(\"my_profile.csv\")\n", "z = inp[\"z\"].to_numpy()\n", "ux = inp[\"ux\"].to_numpy()\n", "Iu = inp[\"Iu\"].to_numpy()" ] }, { "cell_type": "code", "id": "1fb586d3", "metadata": {}, "execution_count": null, "outputs": [], "source": [ "# --- Rxx ---\n", "sigma_u = Iu * ux\n", "Rxx = sigma_u ** 2\n", "\n", "# --- Ryy, Rzz ---\n", "# Use measured Iv, Iw if available; otherwise apply default ratios\n", "if \"Iv\" in inp.columns and \"Iw\" in inp.columns:\n", " Ryy = (inp[\"Iv\"].to_numpy() * ux) ** 2\n", " Rzz = (inp[\"Iw\"].to_numpy() * ux) ** 2\n", "else:\n", " Ryy = 0.5625 * Rxx # sigma_v / sigma_u ~ 0.75\n", " Rzz = 0.25 * Rxx # sigma_w / sigma_u ~ 0.50\n", "\n", "# --- Rxy, Ryz ---\n", "Rxy = np.zeros_like(z)\n", "Ryz = np.zeros_like(z)\n", "\n", "# --- Rxz ---\n", "# Default: simplified ratio - safe and sufficient for most wind tunnel profiles.\n", "# Alternative (commented out): derive from log-law fit of the traverse.\n", "Rxz = -0.3 * Rxx\n", "\n", "# Alternative Rxz using log-law (requires z0 from tunnel floor calibration):\n", "# kappa = 0.41\n", "# z0 = 0.05 # aerodynamic roughness length (m) - must match ground BC in AeroSim\n", "# delta = 500.0 # tunnel boundary layer depth (m, full-scale equivalent)\n", "# u_star = np.median(kappa * ux / np.log(z / z0))\n", "# taper = np.clip(1.0 - z / delta, 0.0, 1.0)\n", "# Rxz = -(u_star ** 2) * taper" ] }, { "cell_type": "code", "id": "b01e1d02", "metadata": {}, "execution_count": null, "outputs": [], "source": [ "# --- Positive semi-definiteness check ---\n", "check = Rxx * Rzz - Rxz ** 2\n", "if np.any(check < 0):\n", " failing = z[check < 0]\n", " raise ValueError(\n", " f\"Positive semi-definiteness violated at z = {failing} m.\\n\"\n", " \"Use the simplified Rxz = -0.3 * Rxx or reduce |Rxz|.\"\n", " )" ] }, { "cell_type": "code", "id": "c89104a6", "metadata": {}, "execution_count": null, "outputs": [], "source": [ "# --- Write CSV ---\n", "df = pd.DataFrame({\n", " \"z\": z,\n", " \"ux\": ux,\n", " \"Rxx\": Rxx,\n", " \"Rxy\": Rxy,\n", " \"Rxz\": Rxz,\n", " \"Ryy\": Ryy,\n", " \"Ryz\": Ryz,\n", " \"Rzz\": Rzz,\n", "})\n", "df.to_csv(\"inlet_profile.csv\", index=False)\n", "print(\"Written: inlet_profile.csv\")\n", "print(df.head())" ] }, { "cell_type": "markdown", "id": "b1be05c6", "metadata": {}, "source": [ "
\n", "Warning. The column header must contain\n", "z,ux,Rxx,Rxy,Rxz,Ryy,Ryz,Rzz - deviations will cause the interface to\n", "reject the file. Values outside the covered range of the profile are extrapolated\n", "as constants at the boundary values.\n", "
\n" ] }, { "cell_type": "markdown", "id": "c322d7e2", "metadata": {}, "source": [ "## Step 3: Upload the Profile in AeroSim\n", "\n", "In the AeroSim web interface, navigate to the **Inlet Boundary Condition**\n", "panel and:\n", "\n", "1. Upload the CSV file produced in Step 2.\n", "2. Set the **ground boundary condition $z_0$** to the same $z_0$ identified\n", " from your wind tunnel floor (Step 1).\n", "\n", "No additional backend parameters need to be configured. The $z_0$ in the\n", "ground BC panel and the $z_0$ that characterises your inlet profile must be\n", "consistent. A mismatch causes the profile to drift downstream as the solver\n", "equilibrates to the actual ground roughness.\n" ] }, { "cell_type": "markdown", "id": "12100a6b", "metadata": {}, "source": [ "## Step 4: Configure Ground Roughness\n", "\n", "The roughness fins must produce a floor roughness consistent with the $z_0$ of\n", "your wind tunnel profile. Select the fin category whose $z_0$ is closest to the\n", "value identified in Step 1:\n", "\n", "| Terrain Category | $z_0$ (m) | Fin height |\n", "| --- | --- | --- |\n", "| 0 (open sea) | 0.003 | no fins |\n", "| I | 0.01 | 1 m |\n", "| II | 0.05 | 2 m |\n", "| III | 0.3 | 6 m |\n", "| IV | 1.0 | 10 m |\n", "\n", "If your tunnel $z_0$ falls between two categories, interpolate the fin height\n", "between the adjacent defaults.\n", "\n", "
\n", "Note. See the\n", "ABL guided case for fin geometry\n", "details, IBM wall model settings, and lateral and top boundary conditions.\n", "
\n" ] }, { "cell_type": "markdown", "id": "f9385419", "metadata": {}, "source": [ "## Step 5: Run an Empty-Domain Validation\n", "\n", "Before adding any geometry, run an empty-domain case - no buildings, same\n", "domain dimensions and roughness configuration - to confirm the profile at the\n", "model location matches your target. Export velocity probes at one or more\n", "streamwise stations at the expected position of the model. See the\n", "[ABL guided case](../guided-cases/ABL/setup.md) for how to configure the domain\n", "and request probe exports in the interface.\n", "\n", "
\n", "Important. Do not skip this step. A profile that looks correct at the\n", "inlet may drift over the domain fetch if the inlet $z_0$ and the floor\n", "roughness are not well matched. Confirm that the profile at the model location\n", "reproduces your wind tunnel measurements before introducing geometry.\n", "
\n" ] }, { "cell_type": "markdown", "id": "d5272dbb", "metadata": {}, "source": [ "## Step 6: Compare Against the Target\n", "\n", "With probe data downloaded from AeroSim, compute time-averaged statistics at\n", "each height and compare against the target profile.\n", "\n", "**At each height, compute from the exported time series:**\n", "\n", "- Mean velocity: $\\bar{U}_{sim} = \\text{mean}(u_x)$\n", "- RMS: $\\sigma_u = \\text{std}(u_x)$\n", "- Turbulence intensity: $I_{u,sim} = \\sigma_u / \\bar{U}_{sim}$\n", "\n", "The full plotting workflow against EN 1991-1-4 reference profiles is in the\n", "[ABL Velocity and Turbulence Intensity from a Velocity Profile](abl-velocity-turbulence-from-profile.ipynb)\n", "notebook.\n" ] }, { "cell_type": "markdown", "id": "a63f14f4", "metadata": {}, "source": [ "## Troubleshooting\n", "\n", "| Symptom | Likely cause | Fix |\n", "| --- | --- | --- |\n", "| Simulation crashes / NaN values | Cholesky failure - tensor not positive semi-definite | Check $R_{xx} \\cdot R_{zz} \\geq R_{xz}^2$ at every height; verify $R_{xz}$ is negative |\n", "| $I_u$ in simulation much lower than target | $I_u$ underestimated in CSV | Recalculate $I_u$; verify stress component ratios against source data |\n", "| $I_u$ in simulation much higher than target | Stress components overestimated | Recalculate $\\sigma_u = I_u \\cdot U$; check $R_{yy}$, $R_{zz}$ ratios |\n", "| Profile drifts significantly downstream | Roughness $z_0$ inconsistent with inlet $z_0$ | Verify that the fin category matches your tunnel floor $z_0$; interpolate fin height between categories if needed |\n", "| Profile height mismatch in domain | Datum offset not accounted for | Shift the `z` column in the CSV by the offset between the domain floor and the measurement datum |\n", "| File not accepted / interface error | Column header mismatch | Verify header is exactly `z,ux,Rxx,Rxy,Rxz,Ryy,Ryz,Rzz` (case-sensitive) |\n" ] }, { "cell_type": "markdown", "id": "fc7a97fa", "metadata": {}, "source": [ "## Next Steps\n", "\n", "With a validated empty-domain profile, the inlet CSV and roughness configuration\n", "can be reused in the full engineering simulation. See:\n", "\n", "- [ABL guided case](../guided-cases/ABL/index.md) - standard terrain category setup, domain guidelines, and refinement recommendations.\n", "- [Pressure on Buildings (CAARC)](../guided-cases/pressure-buildings-caarc.md) - applying the validated profile to a reference high-rise.\n", "- [Pedestrian Comfort](../guided-cases/pedestriam-comfort.md) - extending the setup to evaluate wind conditions at ground level.\n", "- [Topography Factor (Bolund Hill)](../guided-cases/topography-factor.md) - accounting for terrain effects on the wind profile.\n" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "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.10" } }, "nbformat": 4, "nbformat_minor": 5 }