voxcity.simulator_gpu.solar.integration.volumetric ================================================== .. py:module:: voxcity.simulator_gpu.solar.integration.volumetric .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_GROUND_CODE voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_TREE_CODE voxcity.simulator_gpu.solar.integration.volumetric.VOXCITY_BUILDING_CODE Functions --------- .. autoapisummary:: voxcity.simulator_gpu.solar.integration.volumetric.get_volumetric_solar_irradiance_map voxcity.simulator_gpu.solar.integration.volumetric.get_cumulative_volumetric_solar_irradiance voxcity.simulator_gpu.solar.integration.volumetric.get_volumetric_solar_irradiance_using_epw voxcity.simulator_gpu.solar.integration.volumetric.get_global_solar_irradiance_using_epw voxcity.simulator_gpu.solar.integration.volumetric.save_irradiance_mesh voxcity.simulator_gpu.solar.integration.volumetric.load_irradiance_mesh Module Contents --------------- .. py:data:: VOXCITY_GROUND_CODE :value: -1 .. py:data:: VOXCITY_TREE_CODE :value: -2 .. py:data:: VOXCITY_BUILDING_CODE :value: -3 .. py:function:: 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 :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 volumetric_height: Height above ground for irradiance extraction (meters) :param with_reflections: If True, include reflected radiation from surfaces. If False (default), only direct + diffuse sky radiation. :param show_plot: Whether to display a matplotlib plot :param \*\*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²) .. py:function:: 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. :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 volumetric_height: Height above ground for irradiance extraction (meters) :param with_reflections: If True, include reflected radiation from buildings, ground, and tree canopy surfaces. If False (default), only direct + diffuse sky radiation. :param show_plot: Whether to display a matplotlib plot :param \*\*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²) .. py:function:: 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 :param voxcity: VoxCity object :param calc_type: 'instantaneous' or 'cumulative' :param direct_normal_irradiance_scaling: Scaling factor for DNI :param diffuse_irradiance_scaling: Scaling factor for DHI :param volumetric_height: Height above ground for irradiance extraction (meters) :param with_reflections: If True, include reflected radiation from buildings, ground, and tree canopy surfaces. If False (default), only direct + diffuse sky radiation. :param show_plot: Whether to display a matplotlib plot :param \*\*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²) .. py:function:: 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. :param voxcity: VoxCity object :param temporal_mode: Time integration mode: - 'instantaneous': Single time point (requires calc_time) - 'cumulative': Integrate over time range (requires start_time, end_time) :param spatial_mode: Spatial computation mode: - 'horizontal': 2D ground-level irradiance at view_point_height - 'volumetric': 3D radiation field extracted at volumetric_height above terrain :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 calc_type: DEPRECATED. Use temporal_mode and spatial_mode instead. Legacy values 'instantaneous', 'cumulative', 'volumetric' are still supported. :param 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. :param \*\*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) .. rubric:: 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' ) .. py:function:: save_irradiance_mesh(mesh, filepath: str) -> None Save irradiance mesh to pickle file. :param mesh: Trimesh object with irradiance metadata :param filepath: Output file path .. py:function:: load_irradiance_mesh(filepath: str) Load irradiance mesh from pickle file. :param filepath: Input file path :returns: Trimesh object with irradiance metadata