voxcity.simulator_gpu.solar.integration.ground ============================================== .. py:module:: voxcity.simulator_gpu.solar.integration.ground .. autoapi-nested-parse:: Ground-level solar irradiance functions for VoxCity. This module provides GPU-accelerated ground-level solar irradiance calculations: - Direct solar irradiance map - Diffuse solar irradiance map (SVF-based) - Global solar irradiance map (direct + diffuse) - Cumulative solar irradiance over time periods - Sunlight hours (PSH and DSH modes) These functions match the voxcity.simulator.solar API signatures for drop-in replacement with GPU acceleration. Functions --------- .. autoapisummary:: voxcity.simulator_gpu.solar.integration.ground.get_direct_solar_irradiance_map voxcity.simulator_gpu.solar.integration.ground.get_diffuse_solar_irradiance_map voxcity.simulator_gpu.solar.integration.ground.get_global_solar_irradiance_map voxcity.simulator_gpu.solar.integration.ground.get_cumulative_global_solar_irradiance voxcity.simulator_gpu.solar.integration.ground.get_sunlight_hours Module Contents --------------- .. py:function:: get_direct_solar_irradiance_map(voxcity, azimuth_degrees_ori: float, elevation_degrees: float, direct_normal_irradiance: float, show_plot: bool = False, with_reflections: bool = False, **kwargs) -> numpy.ndarray GPU-accelerated direct horizontal irradiance map computation. :param voxcity: VoxCity object :param azimuth_degrees_ori: Solar azimuth in degrees (0=North, clockwise) :param elevation_degrees: Solar elevation in degrees above horizon :param direct_normal_irradiance: DNI in W/m² :param show_plot: Whether to display a matplotlib plot :param with_reflections: If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple ray-tracing for faster but less accurate results. :param \*\*kwargs: Additional parameters including: - view_point_height (float): Observer height above ground (default: 1.5) - tree_k (float): Tree extinction coefficient (default: 0.6) - tree_lad (float): Leaf area density (default: 1.0) - colormap (str): Matplotlib colormap name (default: 'magma') - vmin, vmax (float): Colormap limits - obj_export (bool): Export to OBJ file (default: False) - n_reflection_steps (int): Number of reflection bounces when with_reflections=True (default: 2) - progress_report (bool): Print progress (default: False) :returns: 2D numpy array of direct horizontal irradiance (W/m²) .. py:function:: get_diffuse_solar_irradiance_map(voxcity, diffuse_irradiance: float = 1.0, show_plot: bool = False, with_reflections: bool = False, azimuth_degrees_ori: float = 180.0, elevation_degrees: float = 45.0, **kwargs) -> numpy.ndarray GPU-accelerated diffuse horizontal irradiance map computation using SVF. :param voxcity: VoxCity object :param diffuse_irradiance: Diffuse horizontal irradiance in W/m² :param show_plot: Whether to display a matplotlib plot :param with_reflections: If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple SVF-based computation. :param azimuth_degrees_ori: Solar azimuth (only used when with_reflections=True) :param elevation_degrees: Solar elevation (only used when with_reflections=True) :param \*\*kwargs: Additional parameters :returns: 2D numpy array of diffuse horizontal irradiance (W/m²) .. py:function:: get_global_solar_irradiance_map(voxcity, azimuth_degrees_ori: float, elevation_degrees: float, direct_normal_irradiance: float, diffuse_irradiance: float, show_plot: bool = False, with_reflections: bool = False, **kwargs) -> numpy.ndarray GPU-accelerated global (direct + diffuse) horizontal irradiance map. :param voxcity: VoxCity object :param azimuth_degrees_ori: Solar azimuth in degrees (0=North, clockwise) :param elevation_degrees: Solar elevation in degrees above horizon :param direct_normal_irradiance: DNI in W/m² :param diffuse_irradiance: DHI in W/m² :param show_plot: Whether to display a matplotlib plot :param with_reflections: If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple ray-tracing/SVF. :param \*\*kwargs: Additional parameters including: - computation_mask (np.ndarray): Optional 2D boolean mask - n_reflection_steps (int): Number of reflection bounces - progress_report (bool): Print progress (default: False) :returns: 2D numpy array of global horizontal irradiance (W/m²) .. py:function:: get_cumulative_global_solar_irradiance(voxcity, df, lon: float, lat: float, tz: float, direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, show_plot: bool = False, with_reflections: bool = False, **kwargs) -> numpy.ndarray GPU-accelerated cumulative global solar irradiance over a period. Uses sky patch optimization for efficient multi-timestep calculations. :param voxcity: VoxCity object :param df: pandas DataFrame with 'DNI' and 'DHI' columns, datetime-indexed :param lon: Longitude in degrees :param lat: Latitude in degrees :param tz: Timezone offset in hours :param direct_normal_irradiance_scaling: Scaling factor for DNI :param diffuse_irradiance_scaling: Scaling factor for DHI :param show_plot: Whether to display a matplotlib plot :param with_reflections: If True, use full RadiationModel with reflections :param \*\*kwargs: Additional parameters including: - computation_mask (np.ndarray): Optional 2D boolean mask - start_time (str): Start time 'MM-DD HH:MM:SS' - end_time (str): End time 'MM-DD HH:MM:SS' - view_point_height (float): Observer height - use_sky_patches (bool): Use sky patch optimization (default: True) - sky_discretization (str): 'tregenza', 'reinhart', etc. - progress_report (bool): Print progress :returns: 2D numpy array of cumulative irradiance (Wh/m²) .. py:function:: get_sunlight_hours(voxcity, mode: str = 'PSH', epw_file_path: str = None, download_nearest_epw: bool = False, dni_threshold: float = 120.0, show_plot: bool = False, lon: float = None, lat: float = None, tz: float = None, **kwargs) -> numpy.ndarray GPU-accelerated ground-level sunlight hours computation. Supports two modes: **PSH (Probable Sunlight Hours)**: Uses EPW weather data to account for cloud cover. Requires an EPW file (via epw_file_path or download_nearest_epw). **DSH (Direct Sun Hours)**: Assumes clear sky for all hours. Does NOT require an EPW file. Location (lon/lat) is automatically extracted from the VoxCity object, and timezone is inferred from the location. These can be overridden via the lon, lat, tz parameters. :param voxcity: VoxCity object :param mode: 'PSH' (Probable Sunlight Hours) or 'DSH' (Direct Sun Hours) :param epw_file_path: Path to EPW file (required for PSH, optional for DSH) :param download_nearest_epw: If True, download nearest EPW based on location :param dni_threshold: DNI threshold for PSH mode (default: 120.0 W/m², WMO standard) :param show_plot: Whether to display a matplotlib plot :param lon: Longitude in degrees (optional, extracted from voxcity if not provided) :param lat: Latitude in degrees (optional, extracted from voxcity if not provided) :param tz: Timezone offset in hours (optional, inferred from location if not provided) :param \*\*kwargs: Additional parameters :returns: 2D numpy array with sunlight hours and metadata attribute