feat: add wind speed height correction to read_epw (GH #149) (#1016)

* feat: add wind speed height correction to read_epw utility (GH #149)

Add optional target_height and z0m parameters to read_epw() to enable logarithmic wind profile correction when EPW data must be extrapolated to different measurement heights. EPW files standardise wind speed at 10m, but SUEWS forcing can use any height. This enhancement allows users to:

- Keep default behaviour (no correction) for backward compatibility
- Apply log-law wind profile correction when target height differs from 10m
- Emit warning about neutral atmosphere assumption when correcting

Also add comprehensive documentation explaining EPW height assumptions and troubleshooting guide for common wind speed discrepancies.

Fixes GH #149

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add input validation and floating-point comparison to read_epw

- Add explicit validation for z0m and target_height (must be positive)
- Use np.isclose() for floating-point comparison to avoid edge cases

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: remove duplicate icon files from site/brand/assets/icon

Remove icon files that are duplicates of the disk-style icons.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sunt05

docs/source/inputs/forcing-data.rst

@@ -286,6 +286,115 @@ For model-level data or spatial grids, use the gridded dataset:
 
 See :func:`~supy.util.gen_forcing_era5` API documentation for all options.
 
+Using EPW Weather Files
+-----------------------
+
+EPW (EnergyPlus Weather) files are a common format for building energy simulation, often derived from Typical Meteorological Year (TMY) data. SUEWS can read EPW data via the :func:`~supy.util.read_epw` utility function.
+
+**Important: Measurement Height Assumptions**
+
+EPW files follow standard meteorological station conventions with fixed measurement heights:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - Variable
+     - EPW Height
+     - SUEWS Forcing Variable
+   * - Wind speed
+     - 10 m agl
+     - U
+   * - Air temperature
+     - 2 m agl
+     - Tair
+   * - Relative humidity
+     - 2 m agl
+     - RH
+
+**Correct Configuration for EPW Data**
+
+When using EPW data, set the forcing height to match the wind speed measurement:
+
+.. code-block:: yaml
+
+   sites:
+     - name: "MySite"
+       properties:
+         z: 10.0  # Must be 10 m to match EPW wind speed height
+
+.. warning::
+
+   Using EPW data with a different forcing height (e.g., ``z: 50``) will cause incorrect wind profile calculations, as SUEWS assumes all forcing data originate from the specified height.
+
+**Basic Workflow**
+
+.. code-block:: python
+
+   import supy as sp
+   import pandas as pd
+   from pathlib import Path
+
+   # 1. Read EPW file (wind speed at 10 m by default)
+   df_epw = sp.util.read_epw(Path("weather.epw"))
+
+   # 2. Extract and rename columns for SUEWS forcing
+   df_forcing = pd.DataFrame({
+       'U': df_epw['Wind Speed'],
+       'Tair': df_epw['Dry Bulb Temperature'],
+       'RH': df_epw['Relative Humidity'],
+       'pres': df_epw['Atmospheric Station Pressure'] / 1000,  # Pa to kPa
+       'kdown': df_epw['Global Horizontal Radiation'],
+       'ldown': df_epw['Horizontal Infrared Radiation Intensity'],
+       'rain': df_epw['Liquid Precipitation Depth'],
+   }, index=df_epw.index)
+
+   # 3. Fill required time columns
+   df_forcing['iy'] = df_forcing.index.year
+   df_forcing['id'] = df_forcing.index.dayofyear
+   df_forcing['it'] = df_forcing.index.hour
+   df_forcing['imin'] = df_forcing.index.minute
+
+**Wind Speed Height Correction**
+
+If you need EPW wind speed at a different height (e.g., to match flux tower measurements at 50 m), use the ``target_height`` parameter:
+
+.. code-block:: python
+
+   # Read EPW and extrapolate wind speed from 10 m to 50 m
+   df_epw = sp.util.read_epw(
+       Path("weather.epw"),
+       target_height=50.0,  # Target height [m]
+       z0m=0.5              # Urban roughness length [m]
+   )
+
+This applies a logarithmic wind profile correction assuming neutral atmospheric conditions.
+
+.. note::
+
+   The log-law correction assumes neutral atmospheric stability. Under strongly stable or unstable conditions, actual wind profiles may differ significantly. For most applications using EPW data, setting ``z=10`` in your site configuration is the simpler and recommended approach.
+
+**Comparison with ERA5**
+
+Unlike EPW files with fixed heights, ERA5 forcing data from :func:`~supy.util.gen_forcing_era5` are extrapolated to a user-specified height (default 100 m) using Monin-Obukhov Similarity Theory.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 35 40
+
+   * - Data Source
+     - Wind Speed Height
+     - Recommended ``z`` Setting
+   * - EPW files
+     - Fixed at 10 m
+     - ``z: 10``
+   * - ERA5 (timeseries)
+     - Extrapolated to ``hgt_agl_diag`` (default 100 m)
+     - Match ``hgt_agl_diag`` value
+   * - Flux tower
+     - Tower-specific
+     - Actual measurement height
+
 Data Preparation Tips
 ---------------------
 

docs/source/troubleshooting.rst

@@ -188,6 +188,41 @@ Please check the following:
 A general rule of thumb is to use the ``load_SampleData`` to generate the initial model states from the sample data shipped by SuPy.
 
 
+Wind speed seems incorrect when using EPW data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom**: Wind-related outputs (turbulent fluxes, roughness parameters, u*) appear unrealistic when using EPW weather files.
+
+**Likely cause**: Mismatch between EPW wind speed measurement height (10 m) and configured forcing height (``z``).
+
+EPW files contain wind speed measured at 10 m above ground level. If your site configuration uses a different forcing height (e.g., ``z: 50``), SUEWS will incorrectly assume the EPW wind data originated from 50 m, leading to erroneous friction velocity and flux calculations.
+
+**Solution**: Ensure your site configuration sets ``z: 10`` when using EPW data:
+
+.. code-block:: yaml
+
+   sites:
+     - name: "MySite"
+       properties:
+         z: 10.0  # Match EPW standard wind measurement height
+
+Alternatively, use the ``target_height`` parameter in :func:`~supy.util.read_epw` to extrapolate wind speed to your desired forcing height:
+
+.. code-block:: python
+
+   import supy as sp
+   from pathlib import Path
+
+   # Extrapolate EPW wind speed from 10 m to 50 m
+   df_epw = sp.util.read_epw(
+       Path("weather.epw"),
+       target_height=50.0,
+       z0m=0.5  # roughness length for urban areas
+   )
+
+See :ref:`met_forcing` for detailed guidance on EPW data usage.
+
+
 YAML Configuration Validation Errors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

site/brand/assets/icon/suews-icon-512-dark.png

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 from typing import Optional, Tuple, Union
 
@@ -6,6 +7,9 @@
 
 from .._post import resample_output
 
+# Logger for this module
+logger = logging.getLogger(__name__)
+
 
 #################################################################
 # generate TMY dataframe from supy results
@@ -313,19 +317,91 @@ def conv_0to24(df_TMY):
 
 
 # function to read in EPW file
-def read_epw(path_epw: Path) -> pd.DataFrame:
-    """Read in `epw` file as a DataFrame
+def read_epw(
+    path_epw: Path,
+    target_height: float = 10.0,
+    z0m: float = 0.1,
+) -> pd.DataFrame:
+    """Read in EPW (EnergyPlus Weather) file as a DataFrame.
 
     Parameters
     ----------
     path_epw : Path
-        path to `epw` file
+        Path to EPW file.
+    target_height : float, optional
+        Target height for wind speed extrapolation [m]. EPW files contain
+        wind speed at 10 m agl. If target_height differs from 10 m, the
+        wind speed will be adjusted using a logarithmic wind profile.
+        Default is 10.0 (no correction applied).
+    z0m : float, optional
+        Roughness length for momentum [m], used in wind profile correction.
+        Typical values: 0.01 (open water), 0.1 (grassland), 0.5-2.0 (urban).
+        Default is 0.1.
 
     Returns
     -------
-    df_tmy: pd.DataFrame
-        TMY results of `epw` file
+    df_tmy : pd.DataFrame
+        DataFrame containing weather data with columns named according
+        to EPW standard variable names.
+
+    Notes
+    -----
+    **Measurement Height Assumptions**
+
+    EPW files follow standard meteorological station conventions:
+
+    - **Wind Speed**: 10 m above ground level (agl)
+    - **Temperature and Humidity**: 2 m agl (screen height)
+
+    When using EPW data with SUEWS, ensure the forcing height parameter
+    ``z`` in your site configuration matches these heights. For EPW data,
+    set ``z = 10`` to match the wind speed measurement height.
+
+    **Wind Speed Height Correction**
+
+    If ``target_height != 10.0``, the wind speed is adjusted using the
+    logarithmic wind profile (assuming neutral atmospheric conditions):
+
+    .. math::
+
+        U(z_2) = U(z_1) \\frac{\\ln((z_2 + z_0) / z_0)}{\\ln((z_1 + z_0) / z_0)}
+
+    where :math:`z_1 = 10` m (EPW height), :math:`z_2` is the target height,
+    and :math:`z_0` is the roughness length.
+
+    .. warning::
+
+        The log-law profile assumes neutral atmospheric stability. Under
+        strongly stable or unstable conditions, actual wind profiles may
+        differ significantly from this approximation.
+
+    See Also
+    --------
+    gen_epw : Generate EPW file from SUEWS simulation output.
+    supy.util.gen_forcing_era5 : Generate forcing from ERA5 (extrapolated
+        to user-specified height).
+
+    Examples
+    --------
+    >>> import supy as sp
+    >>> from pathlib import Path
+    >>>
+    >>> # Read EPW file without height correction (default)
+    >>> df_epw = sp.util.read_epw(Path("weather.epw"))
+    >>>
+    >>> # Read EPW file and extrapolate wind speed to 50 m
+    >>> df_epw = sp.util.read_epw(
+    ...     Path("weather.epw"),
+    ...     target_height=50.0,
+    ...     z0m=0.5  # urban roughness length
+    ... )
     """
+    # Input validation
+    if z0m <= 0:
+        raise ValueError(f"z0m must be positive, got {z0m}")
+    if target_height <= 0:
+        raise ValueError(f"target_height must be positive, got {target_height}")
+
     df_tmy = pd.read_csv(path_epw, skiprows=8, sep=",", header=None)
     df_tmy.columns = [x.strip() for x in header_EPW.split("\n")[1:-1]]
     df_tmy["DateTime"] = pd.to_datetime(
@@ -336,6 +412,21 @@ def read_epw(path_epw: Path) -> pd.DataFrame:
         + pd.to_timedelta(df_tmy["Hour"], unit="h")
     )
     df_tmy = df_tmy.set_index("DateTime")
+
+    # Apply wind speed height correction if target height differs from EPW standard (10 m)
+    epw_height = 10.0
+    if not np.isclose(target_height, epw_height):
+        logger.warning(
+            f"Applying wind speed height correction from {epw_height}m to {target_height}m "
+            f"using log-law profile (assumes neutral atmospheric conditions). "
+            f"This approximation may be less accurate under strongly stable or unstable conditions."
+        )
+        # Log-law wind profile correction (neutral conditions)
+        correction_factor = np.log((target_height + z0m) / z0m) / np.log(
+            (epw_height + z0m) / z0m
+        )
+        df_tmy["Wind Speed"] = df_tmy["Wind Speed"] * correction_factor
+
     return df_tmy