voxcity.simulator_gpu.solar.integration.ground

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

get_direct_solar_irradiance_map(→ numpy.ndarray)

GPU-accelerated direct horizontal irradiance map computation.

get_diffuse_solar_irradiance_map(→ numpy.ndarray)

GPU-accelerated diffuse horizontal irradiance map computation using SVF.

get_global_solar_irradiance_map(→ numpy.ndarray)

GPU-accelerated global (direct + diffuse) horizontal irradiance map.

get_cumulative_global_solar_irradiance(→ numpy.ndarray)

GPU-accelerated cumulative global solar irradiance over a period.

get_sunlight_hours(→ numpy.ndarray)

GPU-accelerated ground-level sunlight hours computation.

Module Contents

voxcity.simulator_gpu.solar.integration.ground.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.

Parameters:

  • voxcity – VoxCity object

  • azimuth_degrees_ori – Solar azimuth in degrees (0=North, clockwise)

  • elevation_degrees – Solar elevation in degrees above horizon

  • direct_normal_irradiance – DNI in W/m²

  • show_plot – Whether to display a matplotlib plot

  • with_reflections – If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple ray-tracing for faster but less accurate results.

  • **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²)

voxcity.simulator_gpu.solar.integration.ground.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.

Parameters:

  • voxcity – VoxCity object

  • diffuse_irradiance – Diffuse horizontal irradiance in W/m²

  • show_plot – Whether to display a matplotlib plot

  • with_reflections – If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple SVF-based computation.

  • azimuth_degrees_ori – Solar azimuth (only used when with_reflections=True)

  • elevation_degrees – Solar elevation (only used when with_reflections=True)

  • **kwargs – Additional parameters

Returns:

2D numpy array of diffuse horizontal irradiance (W/m²)

voxcity.simulator_gpu.solar.integration.ground.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.

Parameters:

  • voxcity – VoxCity object

  • azimuth_degrees_ori – Solar azimuth in degrees (0=North, clockwise)

  • elevation_degrees – Solar elevation in degrees above horizon

  • direct_normal_irradiance – DNI in W/m²

  • diffuse_irradiance – DHI in W/m²

  • show_plot – Whether to display a matplotlib plot

  • with_reflections – If True, use full RadiationModel with multi-bounce reflections. If False (default), use simple ray-tracing/SVF.

  • **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²)

voxcity.simulator_gpu.solar.integration.ground.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.

Parameters:

  • voxcity – VoxCity object

  • df – pandas DataFrame with ‘DNI’ and ‘DHI’ columns, datetime-indexed

  • lon – Longitude in degrees

  • lat – Latitude in degrees

  • tz – Timezone offset in hours

  • direct_normal_irradiance_scaling – Scaling factor for DNI

  • diffuse_irradiance_scaling – Scaling factor for DHI

  • show_plot – Whether to display a matplotlib plot

  • with_reflections – If True, use full RadiationModel with reflections

  • **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²)

voxcity.simulator_gpu.solar.integration.ground.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.

Parameters:

  • voxcity – VoxCity object

  • mode – ‘PSH’ (Probable Sunlight Hours) or ‘DSH’ (Direct Sun Hours)

  • epw_file_path – Path to EPW file (required for PSH, optional for DSH)

  • download_nearest_epw – If True, download nearest EPW based on location

  • dni_threshold – DNI threshold for PSH mode (default: 120.0 W/m², WMO standard)

  • show_plot – Whether to display a matplotlib plot

  • lon – Longitude in degrees (optional, extracted from voxcity if not provided)

  • lat – Latitude in degrees (optional, extracted from voxcity if not provided)

  • tz – Timezone offset in hours (optional, inferred from location if not provided)

  • **kwargs – Additional parameters

Returns:

2D numpy array with sunlight hours and metadata attribute