Generate vertical gradients (wind, temperature, and RH) from EnergyPlus weather (EPW) files

Page 1 of 6 Method Statement Generate Vertical Gradients from EPW (Wind, Temperature, and RH) Version 3.0 | November 2025 Use freely with attribution © K. R. Gunawardena Ph.D (Cantab), TU Delft, Delft, Netherlands. 1.0 Purpose and Scope This method statement describes the workflow for generating vertical gradients of wind speed (and optionally temperature and relative humidity), from EPW weather files using two physical approaches: Neutral Logarithmic Wind Profile and KNMI Two-Layer Approximation. It also covers writing QA outputs (Excel + CSV), and optional EPW rewrite. This tool was initially developed as part of a project funded by the University of Bath (attribution for this work should be made to Gunawardena et al. (2019, 2017)).The current version (V3.0), has been updated to incorporate the KNMI (Royal Netherlands Meteorological Institute) wind downscaling method. This method enhances local wind speed accuracy by postprocessing numerical weather prediction (NWP) model outputs using a two-layer atmospheric boundary model and high-resolution roughness maps derived from land-use data. The integration of this method significantly improves surface wind speed estimates, particularly in heterogeneous terrain. 2.0 Theoretical background To estimate wind speeds at urban canopy-relevant heights from coarser atmospheric data, two physically-based downscaling methods are considered here: Logarithmic Wind Profile and KNMI Two-Layer Approximation. Each method offers a distinct approach to vertical wind extrapolation and is suitable under different assumptions and surface conditions. 2.1 Logarithmic Wind Profile The Logarithmic Wind Profile method is grounded in Monin-Obukhov similarity theory, which is applicable under neutral atmospheric stability conditions, and widely used in urban climatology (Monin & Obukhov 1988). It assumes a horizontally homogeneous surface and describes the vertical gradient of wind speed within the surface layer as: 𝒖(𝒛)=𝑢∗ 𝜅ln𝑧 𝑧0 Page 2 of 6 where: 𝒖(𝒛) is the wind speed at height (𝑧), 𝒖∗ is the friction velocity, 𝛋 is the von Kármán constant (≈ 0.4), 𝒛𝟎 is the surface roughness length. This method is particularly suitable for open terrain or urban areas where roughness length can be reasonably estimated, and where stability corrections are either negligible or can be incorporated separately. To estimate wind speeds at different heights within the urban boundary layer, the logarithmic wind profile can be employed with modifications to account for urban roughness and displacement effects. The wind speed at a target height (𝑧) could be calculated using the following formulation: 𝑼(𝒛)=𝑈𝑧∗𝑙𝑛(𝑧−𝑑)/𝑧0  𝑙𝑛󰇡𝑧 −𝑑/𝑧0 󰇢 where: 𝑼(𝒛) is the wind speed at the desired height (𝑧), 𝑼𝒛𝒓𝒆𝒇 is the known wind speed at reference height (𝑧𝑟𝑒𝑓), 𝒛𝟎 is the surface roughness length, 𝒅 is the displacement height, representing the effective height at which zero wind speed occurs due to obstacles such as buildings or vegetation. The inclusion of the displacement height (𝑑) allows for more accurate representation of wind profiles in densely built environments, where the aerodynamic effects of urban structures significantly alter near-surface wind behaviour. By normalising the wind speed at the reference height, the equation provides a scalable and physically consistent method for downscaling wind speeds to canopy-relevant levels, which is essential for microclimate modelling, pollutant dispersion studies, and urban comfort assessments (Gunawardena 2018b, 2018a). 2.2 KNMI Two-Layer Approximation The KNMI Two-Layer Approximation models the vertical wind profile by dividing the atmospheric boundary layer into two regimes separated by the blending height (ℎ). Below ℎ, wind speed is governed by the logarithmic law derived from Monin-Obukhov similarity theory: 𝑼(𝒛)=𝑢∗ κln𝑧−𝑑 𝑧 where: 𝒛𝟎 is the surface roughness length, and Page 3 of 6 𝒅 is the displacement height accounting for urban obstacles. Above the blending height ℎ, wind speed transitions to a power-law profile: 𝑈(𝑧)∝𝑧 ℎ where: 𝛂 is an empirically determined exponent (typically ranging from 0.1 to 0.3). The two profiles are matched at ℎ to ensure continuity and physical consistency across the transition. This hybrid formulation allows for accurate representation of wind speed from the urban canopy layer to the mesoscale domain. This approach has been validated and applied in several KNMI studies, including Verkaik et al. (2005) and Sterl (2019, KNMI TR-381), and is particularly suited for downscaling wind speeds in heterogeneous urban and coastal environments. 2.3 Temperature lapse rate The temperature lapse rate describes the rate at which air temperature decreases with altitude. In the troposphere, the standard atmospheric lapse rate is approximately: Γ=−6.5 K/km. However, actual lapse rates vary depending on atmospheric stability and moisture content:  Dry adiabatic lapse rate (DALR): ~9.8 K/km (unsaturated air)  Moist adiabatic lapse rate (MALR): ~4-7 K/km (saturated air, variable with temp. and pressure) In urban microclimate modelling, lapse rates are critical for vertical interpolation of temperature profiles and for estimating thermal stratification effects, especially in canyon-like geometries or near waterbodies (Gunawardena 2018a). 2.4 Relative humidity gradient The RH gradient refers to the vertical change in relative humidity with height. RH typically decreases with altitude due to the drop in temperature and pressure, which reduces the air’s capacity to hold moisture. The gradient is influenced by:  Surface moisture availability (e.g., vegetation, waterbodies)  Atmospheric mixing and stability  Diurnal cycles and radiation balance In urban environments, RH gradients are important for modelling evapotranspiration, thermal comfort, and pollutant dispersion. RH profiles are often derived from vertical profiles of temperature and dew point, or from reanalysis data interpolated using empirical or physical models. Page 4 of 6 3.0 Assumptions and limitations  Neutral stability assumed; no Monin-Obukhov corrections.  Anemometer height extracted from EPW header; default 10 m.  Gradients applied as provided (sign matters). 4.0 Tool inputs and outputs 4.1 Inputs:  Excel parameter sheet with columns Parameter | Value (and optional Comments). Required: downscaling_method, targetHeight_m. Optional: 𝑧 , displacement, blendingHeight, alphaUpper, gradient_params, dry_lapserate_Temp_10m, verticalGradient_RH_10m, FOXfile_update.  EPW weather file (.epw or .txt). 4.2 Outputs:  QA workbook (.xlsx): sheets DownscaledWind, VerticalSeries, ByHeight, Inputs_and_Metadata.  CSV file summarising ByHeight.  Rewritten EPW: wind only or wind+temp+RH depending on gradient_params. 5.0 Parameter behaviour Key input parameters:  targetHeight_m: single height (e.g., 2) or a list like “1, 2, 5, 10” (units: m).  downscaling_method: “Logarithmic Wind Profile” or “KNMI Two-Layer Approximation”.  gradient_params: “Wind only” or “Wind+Temp+RH”.  dry_lapserate_Temp_10m: °C per 10 m.  verticalGradient_RH_10m: % per 10 m.  FOXfile_update: Yes/No. 6.0 Workflow steps 1. Prepare Excel with required input parameters. 2. Run MATLAB or Python implementation. 3. Select EXCEL input file. 4. Select EPW file. Page 5 of 6 5. Compute wind at all heights using chosen method (Log or KNMI). 6. If Wind+Temp+RH: apply lapse/gradient to compute Air Temperature and RH. 7. Writes QA workbook + CSV. 8. Rewrites EPW. 7.0 MATLAB vs Python implementation Feature MATLAB (runVertGradientGeneratorV3) Python (VertGradients_FromEPW_V3) Input handling GUI prompts (Excel & EPW) CLI flags or GUI fallback QA output Excel (writetable) Excel (pandas + openpyxl) EPW rewrite Yes (with COMMENTS 2 note) Yes (with COMMENTS 2 note) FOX update Planned Planned Error handling try/catch blocks Exceptions + clear messages Licensing Proprietary MATLAB Open-source Python (use freely) 8.0 KNMI vs Logarithmic comparison Sample values from Amsterdam IWEC .epw (𝑧=1.5 m, 𝑑=10 m, ℎ=60 m, 𝛼=0.25): Height (m) EPW Wind (10 m) Log Profile (m/s) KNMI Two - Layer (m/s) 2 6.70 1.02 1.09 5 6.70 4.25 4.57 10 6.70 6.70 7.20 9.0 Open sharing license with attribution Copyright © 2025 Kanchane Gunawardena Permission is hereby granted, free of charge, to any person obtaining a copy of this work and associated documentation files (the “Work”), to use, reproduce, modify, publish, distribute, and create derivative works of the Work, subject to the following conditions: 1. Attribution You must give appropriate credit, provide a link to the license, and indicate if changes were made. Attribution must be clearly visible in any public use, publication, or redistribution of the Work. Suggested citation format: “Generate Vertical Gradients from EPW (Wind, Temperature, and RH), by K. Gunawardena, licensed under the Open Sharing License with Attribution.” 2. No Warranty The Work is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. Page 6 of 6 3. Redistribution Copies or substantial portions of the Work must retain this license and attribution notice. 4. Modifications You may modify the Work, but must clearly indicate that changes were made and retain attribution to the original author. 10.0 References Gunawardena, K. (2018a). Fundamentals of Urban Heat Islands: Concise guide for architects and urban planners, University of Cambridge, Cambridge. Gunawardena, K. (2018b). Methodologies for assessing urban microclimates. In University of Cambridge, Department of Architecture, PhD Symposium, Cambridge: University of Cambridge, pp. 1–20. Gunawardena, K., Kershaw, T., & Steemers, K. (2019). Simulation pathway for estimating heat island influence on urban/suburban building space-conditioning loads and response to facade material changes. Building and Environment, 150(January), 195–205. Gunawardena, K. R., Mccullen, N., & Kershaw, T. (2017). Heat island influence on space-conditioning loads of urban and suburban office buildings. In Cities and Climate Conference 2017, Potsdam: Potsdam Institute for Climate Impact Research, pp. 1–13. Monin, A. S., & Obukhov, A. M. (1988). Momentum and Heat Exchanges with Homogeneous Surfaces. In S. P. Arya, ed., Introduction to Micrometeorology, Vol. 42, Cambridge, Massachusetts: Academic Press Inc., pp. 157–181. Sterl, A. (2019). Wind across land-water transitions: Application of an analytical model to numerical model output. Verkaik, J. W., Jacobs, A. J. M., Tijm, A. B. C., & Onvlee, J. R. A. (2005). Local Wind Speed Estimation by Physical Downscaling of Weather Model Forecasts. Journal of Wind Engineering and Industrial Aerodynamics.