Tip

1. Need help? Please let us know in the SUEWS Community.

2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

3. Please cite SUEWS with proper information from our Zenodo page.

6.3.2.1. supy.util.gen_epw

supy.util.gen_epw(df_output: DataFrame, lat: float, lon: float, tz: float = 0, path_epw: str | Path = PosixPath('uTMY.epw'), freq: str | None = None, grid: int | None = None) → Tuple[DataFrame, str, Path]

Generate an epw file of uTMY (urbanised Typical Meteorological Year) using SUEWS simulation results.

Parameters:

• df_output (pandas.DataFrame) –

  SUEWS simulation results. Can be either:

  • Full MultiIndex output from run_supy (grid, datetime) x (group, var)

  • Pre-extracted single-grid SUEWS output (datetime) x (var)

• lat (float) – Latitude of the site, used for calculating solar angle.

• lon (float) – Longitude of the site, used for calculating solar angle.

• tz (float, optional) – Time zone represented by time difference from UTC+0 (e.g., 8 for UTC+8), by default 0 (i.e., UTC+0).

• path_epw (pathlib.Path or str, optional) – Path to store generated epw file, by default Path(‘./uTMY.epw’).

• freq (str, optional) – Target frequency for resampling (e.g., ‘h’, ‘60min’, ‘1h’). If provided, the output is resampled before EPW generation using variable-appropriate aggregation methods. Recommended for sub-hourly simulation output. Default is None (no resampling).

• grid (int, optional) – Grid number to extract if df_output has MultiIndex (grid, datetime). If not provided and MultiIndex detected, uses the first grid.

Returns:

• df_epw: pandas.DataFrame - uTMY result

• text_meta: str - meta-info text

• path_epw: pathlib.Path - path to generated epw file

Return type:

tuple

Raises:

ImportError – If pvlib is not installed. Install with: pip install pvlib

Notes

This function requires pvlib for solar position and irradiance calculations. pvlib is not included as a required dependency due to its h5py requirement which can cause build issues on some platforms.

Examples

Basic usage with pre-extracted data:

>>> df_epw, meta, path = sp.util.gen_epw(
...     df_output.loc[grid, "SUEWS"], lat=51.5, lon=-0.1
... )

With automatic resampling and grid extraction:

>>> df_epw, meta, path = sp.util.gen_epw(
...     df_output,  # Full MultiIndex output from run_supy
...     lat=51.5,
...     lon=-0.1,
...     freq="h",  # Resample to hourly
... )

See also

supy.resample_output

Resample output with variable-appropriate aggregation