voxcity.simulator_gpu.solar.integration.volumetric

Volumetric Solar Irradiance Module

This module provides functions for computing volumetric (3D) solar irradiance fields and extracting 2D slices at specified heights above terrain. Useful for: - Mean Radiant Temperature (MRT) calculations - Pedestrian thermal comfort analysis - Light availability assessment

Functions:

  • get_volumetric_solar_irradiance_map: Single-timestep volumetric irradiance

  • get_cumulative_volumetric_solar_irradiance: Time-integrated volumetric irradiance

  • get_volumetric_solar_irradiance_using_epw: High-level EPW-based interface

  • get_global_solar_irradiance_using_epw: Unified interface for ground/volumetric modes

Attributes

VOXCITY_GROUND_CODE

VOXCITY_TREE_CODE

VOXCITY_BUILDING_CODE

Functions

get_volumetric_solar_irradiance_map(→ numpy.ndarray)

GPU-accelerated volumetric solar irradiance map at a specified height.

get_cumulative_volumetric_solar_irradiance(→ numpy.ndarray)

GPU-accelerated cumulative volumetric solar irradiance over a period.

get_volumetric_solar_irradiance_using_epw(→ numpy.ndarray)

GPU-accelerated volumetric solar irradiance from EPW file.

get_global_solar_irradiance_using_epw(→ numpy.ndarray)

GPU-accelerated global irradiance from EPW file.

save_irradiance_mesh(→ None)

Save irradiance mesh to pickle file.

load_irradiance_mesh(filepath)

Load irradiance mesh from pickle file.

Module Contents

voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_GROUND_CODE = -1
voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_TREE_CODE = -2
voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_BUILDING_CODE = -3
voxcity.simulator_gpu.solar.integration.volumetric.get_volumetric_solar_irradiance_map(voxcity, azimuth_degrees_ori: float, elevation_degrees: float, direct_normal_irradiance: float, diffuse_irradiance: float, volumetric_height: float = 1.5, with_reflections: bool = False, show_plot: bool = False, **kwargs) → numpy.ndarray

GPU-accelerated volumetric solar irradiance map at a specified height.

Computes the 3D radiation field at each grid cell and extracts a 2D horizontal slice at the specified height. This is useful for: - Mean Radiant Temperature (MRT) calculations - Pedestrian thermal comfort analysis - Light availability assessment

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²

  • volumetric_height – Height above ground for irradiance extraction (meters)

  • with_reflections – If True, include reflected radiation from surfaces. If False (default), only direct + diffuse sky radiation.

  • show_plot – Whether to display a matplotlib plot

  • **kwargs –

    Additional parameters: - n_azimuth (int): Number of azimuthal directions for SVF (default: 36) - n_zenith (int): Number of zenith angles for SVF (default: 9) - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).

    Grid cells outside the masked region are set to NaN.

    • progress_report (bool): Print progress (default: False)

    • colormap (str): Colormap for plot (default: ‘magma’)

    • vmin, vmax (float): Colormap bounds

    • n_reflection_steps (int): Reflection bounces when with_reflections=True (default: 2)

Returns:

2D numpy array of volumetric irradiance at the specified height (W/m²)

voxcity.simulator_gpu.solar.integration.volumetric.get_cumulative_volumetric_solar_irradiance(voxcity, df: pandas.DataFrame, lon: float, lat: float, tz: float, direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, volumetric_height: float = 1.5, with_reflections: bool = False, show_plot: bool = False, **kwargs) → numpy.ndarray

GPU-accelerated cumulative volumetric solar irradiance over a period.

Integrates the 3D radiation field over time and extracts a 2D horizontal slice at the specified height.

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

  • volumetric_height – Height above ground for irradiance extraction (meters)

  • with_reflections – If True, include reflected radiation from buildings, ground, and tree canopy surfaces. If False (default), only direct + diffuse sky radiation.

  • show_plot – Whether to display a matplotlib plot

  • **kwargs –

    Additional parameters: - start_time (str): Start time ‘MM-DD HH:MM:SS’ (default: ‘01-01 05:00:00’) - end_time (str): End time ‘MM-DD HH:MM:SS’ (default: ‘01-01 20:00:00’) - use_sky_patches (bool): Use sky patch optimization (default: True) - sky_discretization (str): ‘tregenza’, ‘reinhart’, ‘uniform’, ‘fibonacci’ - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).

    Grid cells outside the masked region are set to NaN.

    • progress_report (bool): Print progress (default: False)

    • n_reflection_steps (int): Reflection bounces when with_reflections=True (default: 2)

Returns:

2D numpy array of cumulative volumetric irradiance at the specified height (Wh/m²)

voxcity.simulator_gpu.solar.integration.volumetric.get_volumetric_solar_irradiance_using_epw(voxcity, calc_type: str = 'instantaneous', direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, volumetric_height: float = 1.5, with_reflections: bool = False, show_plot: bool = False, **kwargs) → numpy.ndarray

GPU-accelerated volumetric solar irradiance from EPW file.

Computes 3D radiation fields and extracts a 2D horizontal slice at the specified height above ground. This is useful for: - Mean Radiant Temperature (MRT) calculations - Pedestrian thermal comfort analysis - Light availability assessment

Parameters:

  • voxcity – VoxCity object

  • calc_type – ‘instantaneous’ or ‘cumulative’

  • direct_normal_irradiance_scaling – Scaling factor for DNI

  • diffuse_irradiance_scaling – Scaling factor for DHI

  • volumetric_height – Height above ground for irradiance extraction (meters)

  • with_reflections – If True, include reflected radiation from buildings, ground, and tree canopy surfaces. If False (default), only direct + diffuse sky radiation.

  • show_plot – Whether to display a matplotlib plot

  • **kwargs –

    Additional parameters including: - epw_file_path (str): Path to EPW file - download_nearest_epw (bool): Download nearest EPW (default: False) - calc_time (str): For instantaneous: ‘MM-DD HH:MM:SS’ - start_time, end_time (str): For cumulative: ‘MM-DD HH:MM:SS’ - rectangle_vertices: Location vertices (for EPW download) - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).

    Grid cells outside the masked region are set to NaN.

    • n_reflection_steps (int): Reflection bounces when with_reflections=True (default: 2)

Returns:

2D numpy array of volumetric irradiance at the specified height (W/m² or Wh/m²)

voxcity.simulator_gpu.solar.integration.volumetric.get_global_solar_irradiance_using_epw(voxcity, temporal_mode: str = 'instantaneous', spatial_mode: str = 'horizontal', direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, show_plot: bool = False, calc_type: str = None, computation_mask: numpy.ndarray = None, **kwargs) → numpy.ndarray

GPU-accelerated global irradiance from EPW file.

This function provides a unified interface for both ground-level and volumetric irradiance calculations using Taichi GPU acceleration.

Parameters:

  • voxcity – VoxCity object

  • temporal_mode – Time integration mode: - ‘instantaneous’: Single time point (requires calc_time) - ‘cumulative’: Integrate over time range (requires start_time, end_time)

  • spatial_mode – Spatial computation mode: - ‘horizontal’: 2D ground-level irradiance at view_point_height - ‘volumetric’: 3D radiation field extracted at volumetric_height above terrain

  • direct_normal_irradiance_scaling – Scaling factor for DNI

  • diffuse_irradiance_scaling – Scaling factor for DHI

  • show_plot – Whether to display a matplotlib plot

  • calc_type – DEPRECATED. Use temporal_mode and spatial_mode instead. Legacy values ‘instantaneous’, ‘cumulative’, ‘volumetric’ are still supported.

  • computation_mask – Optional 2D boolean numpy array of shape (nx, ny). If provided, only cells where mask is True will be computed. Cells where mask is False will be set to NaN in the output.

  • **kwargs – Additional parameters including: - epw_file_path (str): Path to EPW file - download_nearest_epw (bool): Download nearest EPW (default: False) - calc_time (str): For instantaneous: ‘MM-DD HH:MM:SS’ - start_time, end_time (str): For cumulative: ‘MM-DD HH:MM:SS’ - rectangle_vertices: Location vertices (for EPW download) - view_point_height (float): Height for horizontal mode (default: 1.5) - volumetric_height (float): Height for volumetric mode (default: 1.5) - with_reflections (bool): Include reflections (default: False) - n_reflection_steps (int): Reflection bounces (default: 2)

Returns:

2D numpy array of irradiance (W/m² for instantaneous, Wh/m² for cumulative)

Examples

# Instantaneous ground-level irradiance grid = get_global_solar_irradiance_using_epw(

voxcity, temporal_mode=’instantaneous’, spatial_mode=’horizontal’, calc_time=’08-03 10:00:00’, epw_file_path=’weather.epw’

)

# Cumulative volumetric irradiance with reflections grid = get_global_solar_irradiance_using_epw(

voxcity, temporal_mode=’cumulative’, spatial_mode=’volumetric’, start_time=’01-01 09:00:00’, end_time=’01-31 19:00:00’, volumetric_height=1.5, with_reflections=True, epw_file_path=’weather.epw’

)

voxcity.simulator_gpu.solar.integration.volumetric.save_irradiance_mesh(mesh, filepath: str) → None

Save irradiance mesh to pickle file.

Parameters:

  • mesh – Trimesh object with irradiance metadata

  • filepath – Output file path

voxcity.simulator_gpu.solar.integration.volumetric.load_irradiance_mesh(filepath: str)

Load irradiance mesh from pickle file.

Parameters:

filepath – Input file path

Returns:

Trimesh object with irradiance metadata