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’ - daily_start_hour (int): Optional inclusive hour-of-day lower bound (0-23) - daily_end_hour (int): Optional inclusive hour-of-day upper bound (0-23) - 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