voxcity.simulator_gpu.solar.integration.building

Building surface solar irradiance functions for VoxCity.

This module provides GPU-accelerated building surface solar irradiance calculations: - Building solar irradiance (instantaneous) - Cumulative building solar irradiance - Building sunlight hours (PSH and DSH modes) - EPW-based building irradiance wrapper

These functions match the voxcity.simulator.solar API signatures for drop-in replacement with GPU acceleration.

Attributes

logger

Functions

get_building_solar_irradiance(voxcity[, ...])

GPU-accelerated building surface solar irradiance computation.

get_cumulative_building_solar_irradiance(voxcity, ...)

GPU-accelerated cumulative solar irradiance on building surfaces.

get_building_sunlight_hours(voxcity[, ...])

GPU-accelerated sunlight hours computation for building surfaces.

get_building_global_solar_irradiance_using_epw(voxcity)

GPU-accelerated building surface irradiance using EPW weather data.

Module Contents

voxcity.simulator_gpu.solar.integration.building.logger
voxcity.simulator_gpu.solar.integration.building.get_building_solar_irradiance(voxcity, building_svf_mesh=None, azimuth_degrees_ori: float = None, elevation_degrees: float = None, direct_normal_irradiance: float = None, diffuse_irradiance: float = None, **kwargs)

GPU-accelerated building surface solar irradiance computation.

Uses cached RadiationModel to avoid recomputing SVF/CSF matrices for each timestep.

Parameters:

  • voxcity – VoxCity object

  • building_svf_mesh – Pre-computed mesh with SVF values (optional)

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

  • **kwargs – Additional parameters including: - with_reflections (bool): Enable multi-bounce reflections (default: False) - n_reflection_steps (int): Number of reflection bounces (default: 2) - building_class_id (int): Building voxel class code (default: -3) - computation_mask (np.ndarray): Optional 2D boolean mask - target_selectors (list): Optional surface selectors limiting returned faces - reference_mesh: Optional reference mesh for target selector metadata fast path - progress_report (bool): Print progress (default: False)

Returns:

Trimesh object with irradiance values in metadata

voxcity.simulator_gpu.solar.integration.building.get_cumulative_building_solar_irradiance(voxcity, building_svf_mesh, weather_df, lon: float, lat: float, tz: float, direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, **kwargs)

GPU-accelerated cumulative solar irradiance on building surfaces.

Parameters:

  • voxcity – VoxCity object

  • building_svf_mesh – Trimesh object with SVF in metadata

  • weather_df – pandas DataFrame with ‘DNI’ and ‘DHI’ columns

  • 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

  • **kwargs – Additional parameters

Returns:

Trimesh object with cumulative irradiance (Wh/m²) in metadata

voxcity.simulator_gpu.solar.integration.building.get_building_sunlight_hours(voxcity, building_svf_mesh=None, mode: str = 'PSH', epw_file_path: str = None, download_nearest_epw: bool = False, dni_threshold: float = 120.0, lon: float = None, lat: float = None, tz: float = None, **kwargs)

GPU-accelerated sunlight hours computation for building surfaces.

Supports PSH (Probable Sunlight Hours) and DSH (Direct Sun Hours) modes.

DSH mode does NOT require an EPW file. Location is automatically extracted from the VoxCity object and timezone is inferred.

Parameters:

  • voxcity – VoxCity object

  • building_svf_mesh – Trimesh object with building surfaces (optional)

  • mode – ‘PSH’ or ‘DSH’

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

  • download_nearest_epw – If True, download nearest EPW

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

  • 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:

Trimesh object with sunlight hours in metadata

voxcity.simulator_gpu.solar.integration.building.get_building_global_solar_irradiance_using_epw(voxcity, calc_type: str = 'instantaneous', direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, building_svf_mesh=None, **kwargs)

GPU-accelerated building surface irradiance using EPW weather data.

Parameters:

  • voxcity – VoxCity object

  • calc_type – ‘instantaneous’ or ‘cumulative’

  • direct_normal_irradiance_scaling – Scaling factor for DNI

  • diffuse_irradiance_scaling – Scaling factor for DHI

  • building_svf_mesh – Pre-computed building mesh (optional)

  • **kwargs – Additional parameters

Returns:

Trimesh object with irradiance values in metadata