voxcity.simulator_gpu.solar.epw =============================== .. py:module:: voxcity.simulator_gpu.solar.epw .. autoapi-nested-parse:: 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 ------- .. toctree:: :hidden: /autoapi/voxcity/simulator_gpu/solar/epw/EPWLocation /autoapi/voxcity/simulator_gpu/solar/epw/EPWSolarData .. autoapisummary:: voxcity.simulator_gpu.solar.epw.EPWLocation voxcity.simulator_gpu.solar.epw.EPWSolarData Functions --------- .. autoapisummary:: voxcity.simulator_gpu.solar.epw.read_epw_header voxcity.simulator_gpu.solar.epw.read_epw_solar_data voxcity.simulator_gpu.solar.epw.prepare_cumulative_simulation_input voxcity.simulator_gpu.solar.epw.get_typical_days voxcity.simulator_gpu.solar.epw.estimate_annual_irradiance Module Contents --------------- .. py:function:: read_epw_header(epw_path: Union[str, pathlib.Path]) -> EPWLocation Read location metadata from EPW file header. :param epw_path: Path to EPW file :returns: EPWLocation with site metadata :raises FileNotFoundError: If EPW file doesn't exist :raises ValueError: If LOCATION line cannot be parsed .. py:function:: read_epw_solar_data(epw_path: Union[str, pathlib.Path], start_month: Optional[int] = None, end_month: Optional[int] = None, start_day: Optional[int] = None, end_day: Optional[int] = None) -> EPWSolarData Read solar radiation data from EPW file. This function extracts DNI, DHI, and GHI values along with temporal information needed for solar position calculations. :param epw_path: Path to EPW file :param start_month: Filter to start from this month (1-12) :param end_month: Filter to end at this month (1-12) :param start_day: Filter to start from this day (1-31) :param end_day: Filter to end at this day (1-31) :returns: EPWSolarData containing radiation data and location metadata .. rubric:: 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²") .. py:function:: prepare_cumulative_simulation_input(epw_path: Union[str, pathlib.Path], start_month: Optional[int] = None, end_month: Optional[int] = None, start_day: Optional[int] = None, end_day: Optional[int] = None, filter_daytime: bool = True, min_elevation_deg: float = 5.0) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, EPWLocation] 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. :param epw_path: Path to EPW file :param start_month: Filter start month (1-12) :param end_month: Filter end month (1-12) :param start_day: Filter start day (1-31) :param end_day: Filter end day (1-31) :param filter_daytime: If True, filter out hours with sun below horizon :param 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 :rtype: Tuple of .. rubric:: 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)}") .. py:function:: get_typical_days(epw_path: Union[str, pathlib.Path], months: Optional[List[int]] = None) -> pandas.DataFrame 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. :param epw_path: Path to EPW file :param months: List of months to process (default: all 12) :returns: month, hour, dni_avg, dhi_avg, ghi_avg :rtype: DataFrame with columns .. rubric:: Example >>> typical = get_typical_days("weather.epw", months=[6, 12]) >>> june = typical[typical.month == 6] .. py:function:: estimate_annual_irradiance(epw_path: Union[str, pathlib.Path]) -> dict Estimate annual solar irradiance statistics from EPW file. Provides quick overview of solar resource without full simulation. :param 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 :rtype: Dictionary with annual statistics .. rubric:: Example >>> stats = estimate_annual_irradiance("weather.epw") >>> print(f"Annual GHI: {stats['total_ghi_kwh_m2']:.0f} kWh/m²")