voxcity.simulator_gpu.solar.epw

EPW (EnergyPlus Weather) File Processing for palm_solar.

This module provides utilities for reading EPW weather files and extracting solar radiation data for cumulative irradiance simulations.

EPW files contain hourly weather data including: - Direct Normal Irradiance (DNI) - Diffuse Horizontal Irradiance (DHI) - Global Horizontal Irradiance (GHI) - Location metadata (latitude, longitude, timezone, elevation)

References: - EnergyPlus Weather File Format: https://energyplus.net/weather - EPW Data Dictionary: https://bigladdersoftware.com/epx/docs/8-3/auxiliary-programs/energyplus-weather-file-epw-data-dictionary.html

Classes

EPWLocation

Location metadata from EPW file header.

EPWSolarData

Solar radiation data extracted from EPW file for simulation.

Functions

read_epw_header(→ EPWLocation)

Read location metadata from EPW file header.

read_epw_solar_data(→ EPWSolarData)

Read solar radiation data from EPW file.

prepare_cumulative_simulation_input(...)

Prepare solar simulation input data from EPW file.

get_typical_days(→ pandas.DataFrame)

Extract typical day profiles from EPW file for each month.

estimate_annual_irradiance(→ dict)

Estimate annual solar irradiance statistics from EPW file.

Module Contents

voxcity.simulator_gpu.solar.epw.read_epw_header(epw_path: str | pathlib.Path) → EPWLocation[source]

Read location metadata from EPW file header.

Parameters:

epw_path – Path to EPW file

Returns:

EPWLocation with site metadata

Raises:

  • FileNotFoundError – If EPW file doesn’t exist

  • ValueError – If LOCATION line cannot be parsed

voxcity.simulator_gpu.solar.epw.read_epw_solar_data(epw_path: str | pathlib.Path, start_month: int | None = None, end_month: int | None = None, start_day: int | None = None, end_day: int | None = None) → EPWSolarData[source]

Read solar radiation data from EPW file.

This function extracts DNI, DHI, and GHI values along with temporal information needed for solar position calculations.

Parameters:

  • epw_path – Path to EPW file

  • start_month – Filter to start from this month (1-12)

  • end_month – Filter to end at this month (1-12)

  • start_day – Filter to start from this day (1-31)

  • end_day – Filter to end at this day (1-31)

Returns:

EPWSolarData containing radiation data and location metadata

Example

>>> solar_data = read_epw_solar_data("weather.epw", start_month=6, end_month=6)
>>> print(f"June DNI max: {solar_data.dni.max():.1f} W/m²")
voxcity.simulator_gpu.solar.epw.prepare_cumulative_simulation_input(epw_path: str | pathlib.Path, start_month: int | None = None, end_month: int | None = None, start_day: int | None = None, end_day: int | None = None, filter_daytime: bool = True, min_elevation_deg: float = 5.0) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, EPWLocation][source]

Prepare solar simulation input data from EPW file.

This function reads EPW data and calculates solar positions for each timestep, filtering out nighttime hours. Returns data ready for sky patch binning and cumulative irradiance calculation.

Parameters:

  • epw_path – Path to EPW file

  • start_month – Filter start month (1-12)

  • end_month – Filter end month (1-12)

  • start_day – Filter start day (1-31)

  • end_day – Filter end day (1-31)

  • filter_daytime – If True, filter out hours with sun below horizon

  • min_elevation_deg – Minimum solar elevation to include (degrees)

Returns:

  • azimuth: Solar azimuth angles (degrees, 0=North, clockwise)

  • elevation: Solar elevation angles (degrees, 0=horizon, 90=zenith)

  • dni: Direct Normal Irradiance (W/m²)

  • dhi: Diffuse Horizontal Irradiance (W/m²)

  • location: EPWLocation with site metadata

Return type:

Tuple of

Example

>>> az, el, dni, dhi, loc = prepare_cumulative_simulation_input("weather.epw")
>>> print(f"Location: {loc.city}, {loc.country}")
>>> print(f"Daytime hours: {len(az)}")
voxcity.simulator_gpu.solar.epw.get_typical_days(epw_path: str | pathlib.Path, months: List[int] | None = None) → pandas.DataFrame[source]

Extract typical day profiles from EPW file for each month.

Calculates average hourly DNI and DHI for each month, useful for quick annual simulations using representative days.

Parameters:

  • epw_path – Path to EPW file

  • months – List of months to process (default: all 12)

Returns:

month, hour, dni_avg, dhi_avg, ghi_avg

Return type:

DataFrame with columns

Example

>>> typical = get_typical_days("weather.epw", months=[6, 12])
>>> june = typical[typical.month == 6]
voxcity.simulator_gpu.solar.epw.estimate_annual_irradiance(epw_path: str | pathlib.Path) → dict[source]

Estimate annual solar irradiance statistics from EPW file.

Provides quick overview of solar resource without full simulation.

Parameters:

epw_path – Path to EPW file

Returns:

  • total_dni_kwh_m2: Annual cumulative DNI (kWh/m²)

  • total_dhi_kwh_m2: Annual cumulative DHI (kWh/m²)

  • total_ghi_kwh_m2: Annual cumulative GHI (kWh/m²)

  • peak_dni: Maximum hourly DNI (W/m²)

  • peak_ghi: Maximum hourly GHI (W/m²)

  • sunshine_hours: Hours with DNI > 120 W/m²

  • location: EPWLocation metadata

Return type:

Dictionary with annual statistics

Example

>>> stats = estimate_annual_irradiance("weather.epw")
>>> print(f"Annual GHI: {stats['total_ghi_kwh_m2']:.0f} kWh/m²")