voxcity 1.0.13__py3-none-any.whl → 1.0.15__py3-none-any.whl

voxcity/simulator_gpu/solar/integration.py

@@ -33,6 +33,289 @@ VOXCITY_TREE_CODE = -2
 VOXCITY_BUILDING_CODE = -3
 
 
+# =============================================================================
+# Common Helper Functions (reduces code duplication)
+# =============================================================================
+
+def _get_location_from_voxcity(voxcity, default_lat: float = 1.35, default_lon: float = 103.82) -> Tuple[float, float]:
+    """
+    Extract latitude/longitude from VoxCity object or return defaults.
+    
+    Args:
+        voxcity: VoxCity object with extras containing rectangle_vertices
+        default_lat: Default latitude if not found (Singapore)
+        default_lon: Default longitude if not found (Singapore)
+        
+    Returns:
+        Tuple of (origin_lat, origin_lon)
+    """
+    extras = getattr(voxcity, 'extras', None)
+    if isinstance(extras, dict):
+        rectangle_vertices = extras.get('rectangle_vertices', None)
+    else:
+        rectangle_vertices = None
+    
+    if rectangle_vertices is not None and len(rectangle_vertices) > 0:
+        lons = [v[0] for v in rectangle_vertices]
+        lats = [v[1] for v in rectangle_vertices]
+        return np.mean(lats), np.mean(lons)
+    
+    return default_lat, default_lon
+
+
+def _convert_voxel_data_to_arrays(
+    voxel_data: np.ndarray,
+    default_lad: float = 1.0
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Convert VoxCity voxel codes to is_solid and LAD arrays using vectorized operations.
+    
+    This is 10-100x faster than triple-nested Python loops for large grids.
+    
+    Args:
+        voxel_data: 3D array of VoxCity voxel class codes
+        default_lad: Default Leaf Area Density for tree voxels (m²/m³)
+        
+    Returns:
+        Tuple of (is_solid, lad) numpy arrays with same shape as voxel_data
+    """
+    # Vectorized solid detection: buildings (-3), ground (-1), or positive land cover codes
+    is_solid = (
+        (voxel_data == VOXCITY_BUILDING_CODE) |
+        (voxel_data == VOXCITY_GROUND_CODE) |
+        (voxel_data > 0)
+    ).astype(np.int32)
+    
+    # Vectorized LAD assignment: only tree voxels (-2) have LAD
+    lad = np.where(voxel_data == VOXCITY_TREE_CODE, default_lad, 0.0).astype(np.float32)
+    
+    return is_solid, lad
+
+
+def _compute_valid_ground_vectorized(voxel_data: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Compute valid ground mask and ground k-levels using vectorized operations.
+    
+    Valid ground cells are those where:
+    - The transition from solid to air/tree occurs
+    - The solid below is not water (7,8,9) or building/underground (negative codes)
+    
+    Args:
+        voxel_data: 3D array of VoxCity voxel class codes (ni, nj, nk)
+        
+    Returns:
+        Tuple of (valid_ground 2D bool array, ground_k 2D int array)
+        ground_k[i,j] = -1 means no valid ground found
+    """
+    ni, nj, nk = voxel_data.shape
+    
+    # Water/special class codes to exclude
+    WATER_CLASSES = {7, 8, 9}
+    AIR_OR_TREE = {0, VOXCITY_TREE_CODE}
+    
+    valid_ground = np.zeros((ni, nj), dtype=bool)
+    ground_k = np.full((ni, nj), -1, dtype=np.int32)
+    
+    # Vectorize over k: find first transition from solid to air/tree
+    # For each (i,j), scan upward to find the first air/tree cell above a solid cell
+    for k in range(1, nk):
+        # Current cell is air (0) or tree (-2)
+        curr_is_air_or_tree = (voxel_data[:, :, k] == 0) | (voxel_data[:, :, k] == VOXCITY_TREE_CODE)
+        
+        # Cell below is NOT air or tree (i.e., it's solid)
+        below_val = voxel_data[:, :, k - 1]
+        below_is_solid = (below_val != 0) & (below_val != VOXCITY_TREE_CODE)
+        
+        # This is a transition point
+        is_transition = curr_is_air_or_tree & below_is_solid
+        
+        # Only process cells that haven't been assigned yet
+        unassigned = (ground_k == -1)
+        new_transitions = is_transition & unassigned
+        
+        if not np.any(new_transitions):
+            continue
+        
+        # Check validity: below is not water (7,8,9) and not negative (building/underground)
+        below_is_water = (below_val == 7) | (below_val == 8) | (below_val == 9)
+        below_is_negative = (below_val < 0)
+        below_is_invalid = below_is_water | below_is_negative
+        
+        # Valid ground: transition point where below is valid
+        valid_new = new_transitions & ~below_is_invalid
+        invalid_new = new_transitions & below_is_invalid
+        
+        # Assign ground_k for valid transitions
+        ground_k[valid_new] = k
+        valid_ground[valid_new] = True
+        
+        # Mark invalid transitions so we don't process them again
+        # (set ground_k to -2 temporarily to distinguish from unassigned)
+        ground_k[invalid_new] = -2
+    
+    # Reset -2 markers back to -1 (no valid ground)
+    ground_k[ground_k == -2] = -1
+    
+    return valid_ground, ground_k
+
+
+def _filter_df_to_period(df, start_time: str, end_time: str, tz: float):
+    """
+    Filter weather DataFrame to specified time period and convert to UTC.
+    
+    Args:
+        df: pandas DataFrame with datetime index
+        start_time: Start time in format 'MM-DD HH:MM:SS'
+        end_time: End time in format 'MM-DD HH:MM:SS'
+        tz: Timezone offset in hours
+        
+    Returns:
+        Tuple of (df_period_utc, df with hour_of_year column)
+        
+    Raises:
+        ValueError: If time format is invalid or no data in period
+    """
+    from datetime import datetime
+    import pytz
+    
+    try:
+        start_dt = datetime.strptime(start_time, '%m-%d %H:%M:%S')
+        end_dt = datetime.strptime(end_time, '%m-%d %H:%M:%S')
+    except ValueError as ve:
+        raise ValueError("start_time and end_time must be in format 'MM-DD HH:MM:SS'") from ve
+    
+    # Add hour_of_year column
+    df = df.copy()
+    df['hour_of_year'] = (df.index.dayofyear - 1) * 24 + df.index.hour + 1
+    
+    # Calculate start/end hours
+    start_doy = datetime(2000, start_dt.month, start_dt.day).timetuple().tm_yday
+    end_doy = datetime(2000, end_dt.month, end_dt.day).timetuple().tm_yday
+    start_hour = (start_doy - 1) * 24 + start_dt.hour + 1
+    end_hour = (end_doy - 1) * 24 + end_dt.hour + 1
+    
+    # Filter to period
+    if start_hour <= end_hour:
+        df_period = df[(df['hour_of_year'] >= start_hour) & (df['hour_of_year'] <= end_hour)]
+    else:
+        df_period = df[(df['hour_of_year'] >= start_hour) | (df['hour_of_year'] <= end_hour)]
+    
+    if df_period.empty:
+        raise ValueError("No weather data in the specified period.")
+    
+    # Localize and convert to UTC
+    offset_minutes = int(tz * 60)
+    local_tz = pytz.FixedOffset(offset_minutes)
+    df_period_local = df_period.copy()
+    df_period_local.index = df_period_local.index.tz_localize(local_tz)
+    df_period_utc = df_period_local.tz_convert(pytz.UTC)
+    
+    return df_period_utc
+
+
+def _load_epw_data(
+    epw_file_path: Optional[str] = None,
+    download_nearest_epw: bool = False,
+    voxcity = None,
+    **kwargs
+) -> Tuple:
+    """
+    Load EPW weather data, optionally downloading the nearest file.
+    
+    Args:
+        epw_file_path: Path to EPW file (required if download_nearest_epw=False)
+        download_nearest_epw: If True, download nearest EPW based on location
+        voxcity: VoxCity object (needed for location when downloading)
+        **kwargs: Additional parameters (output_dir, max_distance, rectangle_vertices)
+        
+    Returns:
+        Tuple of (df, lon, lat, tz) where df is the weather DataFrame
+        
+    Raises:
+        ValueError: If EPW file not provided and download_nearest_epw=False
+        ImportError: If required modules not available
+    """
+    rectangle_vertices = kwargs.get('rectangle_vertices', None)
+    if rectangle_vertices is None and voxcity is not None:
+        extras = getattr(voxcity, 'extras', None)
+        if isinstance(extras, dict):
+            rectangle_vertices = extras.get('rectangle_vertices', None)
+    
+    if download_nearest_epw:
+        if rectangle_vertices is None:
+            raise ValueError("rectangle_vertices required to download nearest EPW file")
+        
+        try:
+            from voxcity.utils.weather import get_nearest_epw_from_climate_onebuilding
+            lons = [coord[0] for coord in rectangle_vertices]
+            lats = [coord[1] for coord in rectangle_vertices]
+            center_lon = (min(lons) + max(lons)) / 2
+            center_lat = (min(lats) + max(lats)) / 2
+            output_dir = kwargs.get('output_dir', 'output')
+            max_distance = kwargs.get('max_distance', 100)
+            
+            epw_file_path, weather_data, metadata = get_nearest_epw_from_climate_onebuilding(
+                longitude=center_lon,
+                latitude=center_lat,
+                output_dir=output_dir,
+                max_distance=max_distance,
+                extract_zip=True,
+                load_data=True
+            )
+        except ImportError:
+            raise ImportError("VoxCity weather utilities required for EPW download")
+    
+    if not epw_file_path:
+        raise ValueError("epw_file_path must be provided when download_nearest_epw is False")
+    
+    # Read EPW file
+    try:
+        from voxcity.utils.weather import read_epw_for_solar_simulation
+        df, lon, lat, tz, elevation_m = read_epw_for_solar_simulation(epw_file_path)
+    except ImportError:
+        # Fallback to our EPW reader
+        from .epw import read_epw_header, read_epw_solar_data
+        location = read_epw_header(epw_file_path)
+        df = read_epw_solar_data(epw_file_path)
+        lon, lat, tz = location.longitude, location.latitude, location.timezone
+    
+    if df.empty:
+        raise ValueError("No data in EPW file.")
+    
+    return df, lon, lat, tz
+
+
+def _compute_sun_direction(azimuth_degrees_ori: float, elevation_degrees: float) -> Tuple[float, float, float, float]:
+    """
+    Compute sun direction vector from azimuth and elevation angles.
+    
+    Args:
+        azimuth_degrees_ori: Solar azimuth in VoxCity convention (0=North, clockwise)
+        elevation_degrees: Solar elevation in degrees above horizon
+        
+    Returns:
+        Tuple of (sun_dir_x, sun_dir_y, sun_dir_z, cos_zenith)
+    """
+    # Convert from VoxCity convention to model coordinates
+    azimuth_degrees = 180 - azimuth_degrees_ori
+    azimuth_radians = np.deg2rad(azimuth_degrees)
+    elevation_radians = np.deg2rad(elevation_degrees)
+    
+    cos_elev = np.cos(elevation_radians)
+    sin_elev = np.sin(elevation_radians)
+    
+    sun_dir_x = cos_elev * np.cos(azimuth_radians)
+    sun_dir_y = cos_elev * np.sin(azimuth_radians)
+    sun_dir_z = sin_elev
+    cos_zenith = sin_elev  # cos(zenith) = sin(elevation)
+    
+    return sun_dir_x, sun_dir_y, sun_dir_z, cos_zenith
+
+
+# =============================================================================
+# Data Classes
+# =============================================================================
+
 @dataclass
 class LandCoverAlbedo:
     """
@@ -180,16 +463,8 @@ def _get_or_create_radiation_model(
     if progress_report:
         print("Creating new RadiationModel (computing SVF/CSF matrices)...")
     
-    # Get location
-    rectangle_vertices = getattr(voxcity, 'extras', {}).get('rectangle_vertices', None)
-    if rectangle_vertices is not None:
-        lons = [v[0] for v in rectangle_vertices]
-        lats = [v[1] for v in rectangle_vertices]
-        origin_lat = np.mean(lats)
-        origin_lon = np.mean(lons)
-    else:
-        origin_lat = 1.35
-        origin_lon = 103.82
+    # Get location using helper function
+    origin_lat, origin_lon = _get_location_from_voxcity(voxcity)
     
     # Create domain
     domain = Domain(
@@ -199,37 +474,12 @@ def _get_or_create_radiation_model(
         origin_lon=origin_lon
     )
     
-    # Convert VoxCity voxel data to domain arrays
-    is_solid_np = np.zeros((ni, nj, nk), dtype=np.int32)
-    lad_np = np.zeros((ni, nj, nk), dtype=np.float32)
+    # Convert VoxCity voxel data to domain arrays using vectorized helper
     default_lad = kwargs.get('default_lad', 1.0)
+    is_solid_np, lad_np = _convert_voxel_data_to_arrays(voxel_data, default_lad)
     
-    valid_ground = np.zeros((ni, nj), dtype=bool)
-    
-    for i in range(ni):
-        for j in range(nj):
-            for k in range(nk):
-                voxel_val = voxel_data[i, j, k]
-                
-                if voxel_val == VOXCITY_BUILDING_CODE:
-                    is_solid_np[i, j, k] = 1
-                elif voxel_val == VOXCITY_GROUND_CODE:
-                    is_solid_np[i, j, k] = 1
-                elif voxel_val == VOXCITY_TREE_CODE:
-                    lad_np[i, j, k] = default_lad
-                elif voxel_val > 0:
-                    is_solid_np[i, j, k] = 1
-            
-            # Determine valid ground cells
-            for k in range(1, nk):
-                curr_val = voxel_data[i, j, k]
-                below_val = voxel_data[i, j, k - 1]
-                if curr_val in (0, VOXCITY_TREE_CODE) and below_val not in (0, VOXCITY_TREE_CODE):
-                    if below_val in (7, 8, 9) or below_val < 0:
-                        valid_ground[i, j] = False
-                    else:
-                        valid_ground[i, j] = True
-                    break
+    # Compute valid ground cells using vectorized helper
+    valid_ground, _ = _compute_valid_ground_vectorized(voxel_data)
     
     # Set domain arrays
     _set_solid_array(domain, is_solid_np)
@@ -316,6 +566,127 @@ def clear_radiation_model_cache():
     _radiation_model_cache = None
 
 
+def _compute_ground_k_from_voxels(voxel_data: np.ndarray) -> np.ndarray:
+    """
+    Compute ground surface k-level for each (i,j) cell from voxel data.
+    
+    This finds the terrain top - the highest k where the cell below the first air
+    cell is solid ground (not building). This is used for terrain-following
+    height extraction in volumetric calculations.
+    
+    Water areas (voxel classes 7, 8, 9) and building/underground cells (negative codes)
+    are excluded and marked as -1. This uses the same logic as the with_reflections=True
+    path in _get_or_create_radiation_model for consistency.
+    
+    Args:
+        voxel_data: 3D array of voxel class codes
+        
+    Returns:
+        2D array of ground k-levels (ni, nj). -1 means no valid ground found.
+    """
+    # Use the vectorized helper for consistency
+    _, ground_k = _compute_valid_ground_vectorized(voxel_data)
+    return ground_k
+
+
+def _extract_terrain_following_slice(
+    flux_3d: np.ndarray,
+    ground_k: np.ndarray,
+    height_offset_k: int,
+    is_solid: np.ndarray
+) -> np.ndarray:
+    """
+    Extract a terrain-following 2D slice from a 3D flux field (vectorized).
+    
+    For each (i,j), extracts the value at ground_k[i,j] + height_offset_k.
+    Cells that are solid at the extraction point, have no valid ground,
+    or are above the domain are marked as NaN.
+    
+    Args:
+        flux_3d: 3D array of flux values (ni, nj, nk)
+        ground_k: 2D array of ground k-levels (ni, nj), -1 means no valid ground
+        height_offset_k: Number of cells above ground to extract
+        is_solid: 3D array marking solid cells (ni, nj, nk)
+        
+    Returns:
+        2D array of extracted values (ni, nj) with NaN for invalid cells
+    """
+    ni, nj, nk = flux_3d.shape
+    result = np.full((ni, nj), np.nan, dtype=np.float64)
+    
+    # Calculate extraction k-levels
+    k_extract = ground_k + height_offset_k
+    
+    # Create valid mask: ground exists, within bounds, not solid
+    valid_ground = ground_k >= 0
+    within_bounds = k_extract < nk
+    valid_mask = valid_ground & within_bounds
+    
+    # Get indices for valid cells
+    ii, jj = np.where(valid_mask)
+    kk = k_extract[valid_mask]
+    
+    # Check solid cells at extraction points
+    not_solid = is_solid[ii, jj, kk] != 1
+    
+    # Extract values for non-solid cells
+    ii_valid = ii[not_solid]
+    jj_valid = jj[not_solid]
+    kk_valid = kk[not_solid]
+    
+    result[ii_valid, jj_valid] = flux_3d[ii_valid, jj_valid, kk_valid]
+    
+    return result
+
+
+def _accumulate_terrain_following_slice(
+    cumulative_map: np.ndarray,
+    flux_3d: np.ndarray,
+    ground_k: np.ndarray,
+    height_offset_k: int,
+    is_solid: np.ndarray,
+    weight: float = 1.0
+) -> None:
+    """
+    Accumulate terrain-following values from a 3D flux field into a 2D map (vectorized, in-place).
+    
+    For each (i,j), adds flux_3d[i,j,k_extract] * weight to cumulative_map[i,j]
+    where k_extract = ground_k[i,j] + height_offset_k.
+    
+    Args:
+        cumulative_map: 2D array to accumulate into (ni, nj), modified in-place
+        flux_3d: 3D array of flux values (ni, nj, nk)
+        ground_k: 2D array of ground k-levels (ni, nj), -1 means no valid ground
+        height_offset_k: Number of cells above ground to extract
+        is_solid: 3D array marking solid cells (ni, nj, nk)
+        weight: Multiplier for values before accumulating (e.g., time_step_hours)
+    """
+    ni, nj, nk = flux_3d.shape
+    
+    # Calculate extraction k-levels
+    k_extract = ground_k + height_offset_k
+    
+    # Create valid mask: ground exists, within bounds
+    valid_ground = ground_k >= 0
+    within_bounds = k_extract < nk
+    valid_mask = valid_ground & within_bounds
+    
+    # Get indices for valid cells
+    ii, jj = np.where(valid_mask)
+    kk = k_extract[valid_mask]
+    
+    # Check solid cells at extraction points
+    not_solid = is_solid[ii, jj, kk] != 1
+    
+    # Accumulate for non-solid cells
+    ii_valid = ii[not_solid]
+    jj_valid = jj[not_solid]
+    kk_valid = kk[not_solid]
+    
+    # Use np.add.at for proper in-place accumulation (handles duplicate indices)
+    np.add.at(cumulative_map, (ii_valid, jj_valid), flux_3d[ii_valid, jj_valid, kk_valid] * weight)
+
+
 def clear_gpu_ray_tracer_cache():
     """Clear the cached GPU ray tracer fields to free memory or force recomputation."""
     global _gpu_ray_tracer_cache
@@ -411,16 +782,8 @@ def _get_or_create_building_radiation_model(
     if progress_report:
         print("Creating new Building RadiationModel (computing SVF/CSF matrices)...")
     
-    # Get location
-    rectangle_vertices = getattr(voxcity, 'extras', {}).get('rectangle_vertices', None)
-    if rectangle_vertices is not None:
-        lons = [v[0] for v in rectangle_vertices]
-        lats = [v[1] for v in rectangle_vertices]
-        origin_lat = np.mean(lats)
-        origin_lon = np.mean(lons)
-    else:
-        origin_lat = 1.35
-        origin_lon = 103.82
+    # Get location using helper function
+    origin_lat, origin_lon = _get_location_from_voxcity(voxcity)
     
     # Create domain - consistent with ground-level model
     # VoxCity uses [row, col, z] = [i, j, k] convention
@@ -435,25 +798,9 @@ def _get_or_create_building_radiation_model(
         origin_lon=origin_lon
     )
     
-    # Convert VoxCity voxel data to domain arrays
-    # Use the same convention as ground-level model: direct indexing without swap
-    is_solid_np = np.zeros((ni, nj, nk), dtype=np.int32)
-    lad_np = np.zeros((ni, nj, nk), dtype=np.float32)
+    # Convert VoxCity voxel data to domain arrays using vectorized helper
     default_lad = kwargs.get('default_lad', 2.0)
-    
-    for i in range(ni):
-        for j in range(nj):
-            for z in range(nk):
-                voxel_val = voxel_data[i, j, z]
-                
-                if voxel_val == VOXCITY_BUILDING_CODE:
-                    is_solid_np[i, j, z] = 1
-                elif voxel_val == VOXCITY_GROUND_CODE:
-                    is_solid_np[i, j, z] = 1
-                elif voxel_val == VOXCITY_TREE_CODE:
-                    lad_np[i, j, z] = default_lad
-                elif voxel_val > 0:
-                    is_solid_np[i, j, z] = 1
+    is_solid_np, lad_np = _convert_voxel_data_to_arrays(voxel_data, default_lad)
     
     # Set domain arrays
     _set_solid_array(domain, is_solid_np)
@@ -1199,6 +1546,7 @@ def get_global_solar_irradiance_map(
             reflections. If False (default), use simple ray-tracing/SVF for 
             faster but less accurate results.
         **kwargs: Additional parameters (see get_direct_solar_irradiance_map)
+            - computation_mask (np.ndarray): Optional 2D boolean mask for sub-area computation
             - n_reflection_steps (int): Number of reflection bounces when 
                 with_reflections=True (default: 2)
             - progress_report (bool): Print progress (default: False)
@@ -1206,6 +1554,9 @@ def get_global_solar_irradiance_map(
     Returns:
         2D numpy array of global horizontal irradiance (W/m²)
     """
+    # Extract computation_mask from kwargs
+    computation_mask = kwargs.pop('computation_mask', None)
+    
     if with_reflections:
         # Use full RadiationModel with reflections (single call for all components)
         direct_map, diffuse_map, reflected_map = _compute_ground_irradiance_with_reflections(
@@ -1268,6 +1619,18 @@ def get_global_solar_irradiance_map(
             **kwargs
         )
     
+    # Apply computation mask if provided
+    if computation_mask is not None:
+        # Ensure mask shape matches output shape (note: output is flipped)
+        if computation_mask.shape == global_map.shape:
+            global_map = np.where(np.flipud(computation_mask), global_map, np.nan)
+        elif computation_mask.T.shape == global_map.shape:
+            global_map = np.where(np.flipud(computation_mask.T), global_map, np.nan)
+        else:
+            # Try to match without flip
+            if computation_mask.shape == global_map.shape:
+                global_map = np.where(computation_mask, global_map, np.nan)
+    
     return global_map
 
 
@@ -1308,6 +1671,7 @@ def get_cumulative_global_solar_irradiance(
             reflections for each timestep/patch. If False (default), use simple 
             ray-tracing/SVF for faster computation.
         **kwargs: Additional parameters including:
+            - computation_mask (np.ndarray): Optional 2D boolean mask for sub-area computation
             - 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')
             - view_point_height (float): Observer height (default: 1.5)
@@ -1327,6 +1691,7 @@ def get_cumulative_global_solar_irradiance(
     
     # Extract parameters that we pass explicitly (use pop to avoid duplicate kwargs)
     kwargs = kwargs.copy()  # Don't modify the original
+    computation_mask = kwargs.pop('computation_mask', None)
     view_point_height = kwargs.pop('view_point_height', 1.5)
     colormap = kwargs.pop('colormap', 'magma')
     start_time = kwargs.pop('start_time', '01-01 05:00:00')
@@ -1587,6 +1952,14 @@ def get_cumulative_global_solar_irradiance(
     # Apply mask for plotting
     cumulative_map = np.where(mask_map, cumulative_map, np.nan)
     
+    # Apply computation mask if provided
+    if computation_mask is not None:
+        # Handle different shape orientations
+        if computation_mask.shape == cumulative_map.shape:
+            cumulative_map = np.where(np.flipud(computation_mask), cumulative_map, np.nan)
+        elif computation_mask.T.shape == cumulative_map.shape:
+            cumulative_map = np.where(np.flipud(computation_mask.T), cumulative_map, np.nan)
+    
     if show_plot:
         vmax = kwargs.get('vmax', float(np.nanmax(cumulative_map)) if not np.all(np.isnan(cumulative_map)) else 1.0)
         vmin = kwargs.get('vmin', 0.0)
@@ -1637,6 +2010,9 @@ def get_building_solar_irradiance(
             - n_reflection_steps (int): Number of reflection bounces when with_reflections=True (default: 2)
             - tree_k (float): Tree extinction coefficient (default: 0.6)
             - building_class_id (int): Building voxel class code (default: -3)
+            - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).
+                Faces whose XY centroid falls outside the masked region are set to NaN.
+                Useful for focusing analysis on a sub-region of the domain.
             - progress_report (bool): Print progress (default: False)
             - colormap (str): Colormap name (default: 'magma')
             - obj_export (bool): Export mesh to OBJ (default: False)
@@ -1666,6 +2042,7 @@ def get_building_solar_irradiance(
     n_reflection_steps = kwargs.pop('n_reflection_steps', 2)
     colormap = kwargs.pop('colormap', 'magma')
     with_reflections = kwargs.pop('with_reflections', False)  # Default False for speed; set True for multi-bounce reflections
+    computation_mask = kwargs.pop('computation_mask', None)  # 2D boolean mask for sub-area filtering
     
     # If with_reflections=False, set n_reflection_steps=0 to skip expensive SVF matrix computation
     if not with_reflections:
@@ -1889,6 +2266,53 @@ def get_building_solar_irradiance(
         n_boundary = np.sum(is_boundary_vertical)
         print(f"  Boundary vertical faces set to NaN: {n_boundary}/{n_mesh_faces} ({100*n_boundary/n_mesh_faces:.1f}%)")
 
+    # -------------------------------------------------------------------------
+    # Apply computation_mask: set faces outside masked XY region to NaN
+    # -------------------------------------------------------------------------
+    if computation_mask is not None:
+        # Get mesh face centers (use cached if available)
+        if cache is not None and cache.mesh_face_centers is not None:
+            mesh_face_centers = cache.mesh_face_centers
+        else:
+            mesh_face_centers = building_mesh.triangles_center
+        
+        # Convert face XY positions to grid indices
+        face_x = mesh_face_centers[:, 0]
+        face_y = mesh_face_centers[:, 1]
+        
+        # Map to grid indices (face coords are in real-world units: 0 to nx*meshsize)
+        grid_i = (face_y / meshsize).astype(int)  # y -> i (row)
+        grid_j = (face_x / meshsize).astype(int)  # x -> j (col)
+        
+        # Handle mask shape orientation
+        if computation_mask.shape == (ny_vc, nx_vc):
+            mask_shape = computation_mask.shape
+        elif computation_mask.T.shape == (ny_vc, nx_vc):
+            computation_mask = computation_mask.T
+            mask_shape = computation_mask.shape
+        else:
+            # Best effort: assume it matches voxel grid
+            mask_shape = computation_mask.shape
+        
+        # Clamp indices to valid range
+        grid_i = np.clip(grid_i, 0, mask_shape[0] - 1)
+        grid_j = np.clip(grid_j, 0, mask_shape[1] - 1)
+        
+        # Determine which faces are outside the mask
+        # Flip mask to match coordinate system (same as ground-level functions)
+        flipped_mask = np.flipud(computation_mask)
+        outside_mask = ~flipped_mask[grid_i, grid_j]
+        
+        # Set values outside mask to NaN
+        sw_in_direct = np.where(outside_mask, np.nan, sw_in_direct)
+        sw_in_diffuse = np.where(outside_mask, np.nan, sw_in_diffuse)
+        sw_in_reflected = np.where(outside_mask, np.nan, sw_in_reflected)
+        total_sw = np.where(outside_mask, np.nan, total_sw)
+        
+        if progress_report:
+            n_outside = np.sum(outside_mask)
+            print(f"  Faces outside computation_mask set to NaN: {n_outside}/{n_mesh_faces} ({100*n_outside/n_mesh_faces:.1f}%)")
+
     building_mesh.metadata = {
         'irradiance_direct': sw_in_direct,
         'irradiance_diffuse': sw_in_diffuse,
@@ -1951,10 +2375,11 @@ def get_cumulative_building_solar_irradiance(
             - time_step_hours (float): Time step in hours (default: 1.0)
             - use_sky_patches (bool): Use sky patch optimization (default: True)
             - sky_discretization (str): 'tregenza', 'reinhart', etc.
+            - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).
+                Faces whose XY centroid falls outside the masked region are set to NaN.
             - progress_report (bool): Print progress (default: False)
             - with_reflections (bool): Enable multi-bounce surface reflections (default: False).
                 Set to True for more accurate results but slower computation.
-            - fast_path (bool): Use optimized paths (default: True)
     
     Returns:
         Trimesh object with cumulative irradiance (Wh/m²) in metadata
@@ -1969,6 +2394,7 @@ def get_cumulative_building_solar_irradiance(
     time_step_hours = float(kwargs.pop('time_step_hours', 1.0))
     progress_report = kwargs.pop('progress_report', False)
     use_sky_patches = kwargs.pop('use_sky_patches', False)  # Default False for accuracy, True for speed
+    computation_mask = kwargs.pop('computation_mask', None)  # 2D boolean mask for sub-area filtering
     
     if weather_df.empty:
         raise ValueError("No data in weather dataframe.")
@@ -2230,8 +2656,48 @@ def get_cumulative_building_solar_irradiance(
         n_boundary = np.sum(is_boundary_vertical)
         print(f"  Boundary vertical faces set to NaN: {n_boundary}/{n_faces} ({100*n_boundary/n_faces:.1f}%)")
 
-    # Store results in mesh metadata
-    result_mesh.metadata = getattr(result_mesh, 'metadata', {})
+    # -------------------------------------------------------------------------
+    # Apply computation_mask: set faces outside masked XY region to NaN
+    # -------------------------------------------------------------------------
+    if computation_mask is not None:
+        # Convert face XY positions to grid indices
+        face_x = mesh_face_centers[:, 0]
+        face_y = mesh_face_centers[:, 1]
+        
+        # Map to grid indices (face coords are in real-world units: 0 to nx*meshsize)
+        grid_i = (face_y / meshsize).astype(int)  # y -> i (row)
+        grid_j = (face_x / meshsize).astype(int)  # x -> j (col)
+        
+        # Handle mask shape orientation
+        if computation_mask.shape == (ny_vc, nx_vc):
+            mask_shape = computation_mask.shape
+        elif computation_mask.T.shape == (ny_vc, nx_vc):
+            computation_mask = computation_mask.T
+            mask_shape = computation_mask.shape
+        else:
+            # Best effort: assume it matches voxel grid
+            mask_shape = computation_mask.shape
+        
+        # Clamp indices to valid range
+        grid_i = np.clip(grid_i, 0, mask_shape[0] - 1)
+        grid_j = np.clip(grid_j, 0, mask_shape[1] - 1)
+        
+        # Determine which faces are outside the mask
+        # Flip mask to match coordinate system (same as ground-level functions)
+        flipped_mask = np.flipud(computation_mask)
+        outside_mask = ~flipped_mask[grid_i, grid_j]
+        
+        # Set values outside mask to NaN
+        cumulative_direct[outside_mask] = np.nan
+        cumulative_diffuse[outside_mask] = np.nan
+        cumulative_global[outside_mask] = np.nan
+        
+        if progress_report:
+            n_outside = np.sum(outside_mask)
+            print(f"  Faces outside computation_mask set to NaN: {n_outside}/{n_faces} ({100*n_outside/n_faces:.1f}%)")
+
+    # Store results in mesh metadata
+    result_mesh.metadata = getattr(result_mesh, 'metadata', {})
     result_mesh.metadata['cumulative_direct'] = cumulative_direct
     result_mesh.metadata['cumulative_diffuse'] = cumulative_diffuse
     result_mesh.metadata['cumulative_global'] = cumulative_global
@@ -2291,6 +2757,9 @@ def get_building_global_solar_irradiance_using_epw(
             - calc_time (str): For instantaneous: 'MM-DD HH:MM:SS'
             - period_start, period_end (str): For cumulative: 'MM-DD HH:MM:SS'
             - rectangle_vertices: Location vertices
+            - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).
+                Faces whose XY centroid falls outside the masked region are set to NaN.
+                Useful for analyzing specific buildings or sub-regions.
             - progress_report (bool): Print progress
             - with_reflections (bool): Enable multi-bounce surface reflections (default: False).
                 Set to True for more accurate results but slower computation.
@@ -2307,56 +2776,13 @@ def get_building_global_solar_irradiance_using_epw(
     kwargs = dict(kwargs)
     kwargs.pop('progress_report', None)
     
-    # Get EPW file
-    epw_file_path = kwargs.get('epw_file_path', None)
-    download_nearest_epw = kwargs.get('download_nearest_epw', False)
-    
-    rectangle_vertices = kwargs.get('rectangle_vertices', None)
-    if rectangle_vertices is None:
-        extras = getattr(voxcity, 'extras', None)
-        if isinstance(extras, dict):
-            rectangle_vertices = extras.get('rectangle_vertices', None)
-    
-    if download_nearest_epw:
-        if rectangle_vertices is None:
-            raise ValueError("rectangle_vertices required to download nearest EPW file")
-        
-        try:
-            from voxcity.utils.weather import get_nearest_epw_from_climate_onebuilding
-            lons = [coord[0] for coord in rectangle_vertices]
-            lats = [coord[1] for coord in rectangle_vertices]
-            center_lon = (min(lons) + max(lons)) / 2
-            center_lat = (min(lats) + max(lats)) / 2
-            output_dir = kwargs.get('output_dir', 'output')
-            max_distance = kwargs.get('max_distance', 100)
-            
-            epw_file_path, weather_data, metadata = get_nearest_epw_from_climate_onebuilding(
-                longitude=center_lon,
-                latitude=center_lat,
-                output_dir=output_dir,
-                max_distance=max_distance,
-                extract_zip=True,
-                load_data=True
-            )
-        except ImportError:
-            raise ImportError("VoxCity weather utilities required for EPW download")
-    
-    if not epw_file_path:
-        raise ValueError("epw_file_path must be provided when download_nearest_epw is False")
-    
-    # Read EPW
-    try:
-        from voxcity.utils.weather import read_epw_for_solar_simulation
-        df, lon, lat, tz, elevation_m = read_epw_for_solar_simulation(epw_file_path)
-    except ImportError:
-        # Fallback to our EPW reader
-        from .epw import read_epw_header, read_epw_solar_data
-        location = read_epw_header(epw_file_path)
-        df = read_epw_solar_data(epw_file_path)
-        lon, lat, tz = location.longitude, location.latitude, location.timezone
-    
-    if df.empty:
-        raise ValueError("No data in EPW file.")
+    # Load EPW data using helper function
+    df, lon, lat, tz = _load_epw_data(
+        epw_file_path=kwargs.pop('epw_file_path', None),
+        download_nearest_epw=kwargs.pop('download_nearest_epw', False),
+        voxcity=voxcity,
+        **kwargs
+    )
     
     # Create building mesh for output (just geometry, no SVF computation)
     # The RadiationModel computes SVF internally for voxel surfaces, so we don't need
@@ -2449,143 +2875,1105 @@ def get_building_global_solar_irradiance_using_epw(
         raise ValueError(f"Unknown calc_type: {calc_type}. Use 'instantaneous' or 'cumulative'.")
 
 
-def get_global_solar_irradiance_using_epw(
+# =============================================================================
+# Volumetric Solar Irradiance Functions
+# =============================================================================
+# Module-level cache for VolumetricFluxCalculator
+_volumetric_flux_cache: Optional[Dict] = None
+
+
+def clear_volumetric_flux_cache():
+    """Clear the cached VolumetricFluxCalculator to free memory or force recomputation."""
+    global _volumetric_flux_cache
+    _volumetric_flux_cache = None
+
+
+def _get_or_create_volumetric_calculator(
     voxcity,
-    calc_type: str = 'instantaneous',
-    direct_normal_irradiance_scaling: float = 1.0,
-    diffuse_irradiance_scaling: float = 1.0,
+    n_azimuth: int = 36,
+    n_zenith: int = 9,
+    progress_report: bool = False,
+    **kwargs
+):
+    """
+    Get cached VolumetricFluxCalculator or create a new one if cache is invalid.
+    
+    Args:
+        voxcity: VoxCity object
+        n_azimuth: Number of azimuthal directions
+        n_zenith: Number of zenith angle divisions
+        progress_report: Print progress messages
+        **kwargs: Additional parameters
+        
+    Returns:
+        Tuple of (VolumetricFluxCalculator, Domain)
+    """
+    global _volumetric_flux_cache
+    
+    from .volumetric import VolumetricFluxCalculator
+    from .domain import Domain
+    
+    voxel_data = voxcity.voxels.classes
+    meshsize = voxcity.voxels.meta.meshsize
+    ni, nj, nk = voxel_data.shape
+    
+    # Check if cache is valid
+    cache_valid = False
+    if _volumetric_flux_cache is not None:
+        cache = _volumetric_flux_cache
+        if (cache.get('voxcity_shape') == voxel_data.shape and
+            cache.get('meshsize') == meshsize and
+            cache.get('n_azimuth') == n_azimuth):
+            cache_valid = True
+            if progress_report:
+                print("Using cached VolumetricFluxCalculator (SVF already computed)")
+    
+    if cache_valid:
+        return _volumetric_flux_cache['calculator'], _volumetric_flux_cache['domain']
+    
+    # Need to create new calculator
+    if progress_report:
+        print("Creating new VolumetricFluxCalculator...")
+    
+    # Get location using helper function
+    origin_lat, origin_lon = _get_location_from_voxcity(voxcity)
+    
+    # Create domain
+    domain = Domain(
+        nx=ni, ny=nj, nz=nk,
+        dx=meshsize, dy=meshsize, dz=meshsize,
+        origin_lat=origin_lat,
+        origin_lon=origin_lon
+    )
+    
+    # Convert VoxCity voxel data to domain arrays using vectorized helper
+    default_lad = kwargs.get('default_lad', 1.0)
+    is_solid_np, lad_np = _convert_voxel_data_to_arrays(voxel_data, default_lad)
+    
+    # Set domain arrays
+    _set_solid_array(domain, is_solid_np)
+    domain.set_lad_from_array(lad_np)
+    _update_topo_from_solid(domain)
+    
+    # Create VolumetricFluxCalculator
+    calculator = VolumetricFluxCalculator(
+        domain,
+        n_azimuth=n_azimuth,
+        min_opaque_lad=kwargs.get('min_opaque_lad', 0.5)
+    )
+    
+    # Compute volumetric sky view factors (expensive, do once)
+    if progress_report:
+        print("Computing volumetric sky view factors...")
+    calculator.compute_skyvf_vol(n_zenith=n_zenith)
+    
+    # Cache the calculator
+    _volumetric_flux_cache = {
+        'calculator': calculator,
+        'domain': domain,
+        'voxcity_shape': voxel_data.shape,
+        'meshsize': meshsize,
+        'n_azimuth': n_azimuth
+    }
+    
+    if progress_report:
+        print(f"VolumetricFluxCalculator cached.")
+    
+    return calculator, domain
+
+
+def 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
 ) -> np.ndarray:
     """
-    GPU-accelerated global irradiance from EPW file.
+    GPU-accelerated volumetric solar irradiance map at a specified height.
     
-    This function matches the signature of voxcity.simulator.solar.get_global_solar_irradiance_using_epw
-    using Taichi GPU acceleration.
+    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
     
     Args:
         voxcity: VoxCity object
-        calc_type: 'instantaneous' or 'cumulative'
-        direct_normal_irradiance_scaling: Scaling factor for DNI
-        diffuse_irradiance_scaling: Scaling factor for DHI
+        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 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)
+        **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 irradiance (W/m² or Wh/m²)
+        2D numpy array of volumetric irradiance at the specified height (W/m²)
     """
-    from datetime import datetime
-    import pytz
+    import math
     
-    # Get EPW file
-    epw_file_path = kwargs.get('epw_file_path', None)
-    download_nearest_epw = kwargs.get('download_nearest_epw', False)
+    kwargs = kwargs.copy()  # Don't modify caller's kwargs
+    progress_report = kwargs.pop('progress_report', False)
+    n_azimuth = kwargs.pop('n_azimuth', 36)
+    n_zenith = kwargs.pop('n_zenith', 9)
+    computation_mask = kwargs.pop('computation_mask', None)
     
-    rectangle_vertices = kwargs.get('rectangle_vertices', None)
-    if rectangle_vertices is None:
-        extras = getattr(voxcity, 'extras', None)
-        if isinstance(extras, dict):
-            rectangle_vertices = extras.get('rectangle_vertices', None)
+    # Get or create cached calculator
+    calculator, domain = _get_or_create_volumetric_calculator(
+        voxcity,
+        n_azimuth=n_azimuth,
+        n_zenith=n_zenith,
+        progress_report=progress_report,
+        **kwargs
+    )
     
-    if download_nearest_epw:
-        if rectangle_vertices is None:
-            raise ValueError("rectangle_vertices required to download nearest EPW file")
-        
-        try:
-            from voxcity.utils.weather import get_nearest_epw_from_climate_onebuilding
-            lons = [coord[0] for coord in rectangle_vertices]
-            lats = [coord[1] for coord in rectangle_vertices]
-            center_lon = (min(lons) + max(lons)) / 2
-            center_lat = (min(lats) + max(lats)) / 2
-            output_dir = kwargs.get('output_dir', 'output')
-            max_distance = kwargs.get('max_distance', 100)
-            
-            epw_file_path, weather_data, metadata = get_nearest_epw_from_climate_onebuilding(
-                longitude=center_lon,
-                latitude=center_lat,
-                output_dir=output_dir,
-                max_distance=max_distance,
-                extract_zip=True,
-                load_data=True
-            )
-        except ImportError:
-            raise ImportError("VoxCity weather utilities required for EPW download")
+    voxel_data = voxcity.voxels.classes
+    meshsize = voxcity.voxels.meta.meshsize
+    ni, nj, nk = voxel_data.shape
     
-    if not epw_file_path:
-        raise ValueError("epw_file_path must be provided when download_nearest_epw is False")
+    # Convert solar angles to direction vector
+    # Match the coordinate system used in ground-level functions:
+    # azimuth_degrees_ori: 0=North, 90=East (clockwise from North)
+    # Transform to model coordinates: 180 - azimuth_degrees_ori
+    azimuth_degrees = 180 - azimuth_degrees_ori
+    azimuth_rad = math.radians(azimuth_degrees)
+    elevation_rad = math.radians(elevation_degrees)
     
-    # Read EPW
-    try:
-        from voxcity.utils.weather import read_epw_for_solar_simulation
-        df, lon, lat, tz, elevation_m = read_epw_for_solar_simulation(epw_file_path)
-    except ImportError:
-        # Fallback to our EPW reader
-        from .epw import read_epw_header, read_epw_solar_data
-        location = read_epw_header(epw_file_path)
-        df = read_epw_solar_data(epw_file_path)
-        lon, lat, tz = location.longitude, location.latitude, location.timezone
+    cos_elev = math.cos(elevation_rad)
+    sin_elev = math.sin(elevation_rad)
     
-    if df.empty:
-        raise ValueError("No data in EPW file.")
+    # Direction toward sun (matching ground-level function convention)
+    sun_dir_x = cos_elev * math.cos(azimuth_rad)
+    sun_dir_y = cos_elev * math.sin(azimuth_rad)
+    sun_dir_z = sin_elev
+    sun_direction = (sun_dir_x, sun_dir_y, sun_dir_z)
     
-    if calc_type == 'instantaneous':
-        calc_time = kwargs.get('calc_time', '01-01 12:00:00')
-        try:
-            calc_dt = datetime.strptime(calc_time, '%m-%d %H:%M:%S')
-        except ValueError:
-            raise ValueError("calc_time must be in format 'MM-DD HH:MM:SS'")
+    cos_zenith = sin_elev  # cos(zenith) = sin(elevation)
+    
+    # Compute volumetric flux
+    if with_reflections:
+        # Use full reflection model
+        if progress_report:
+            print("Computing volumetric flux with reflections...")
         
-        df_period = df[
-            (df.index.month == calc_dt.month) &
-            (df.index.day == calc_dt.day) &
-            (df.index.hour == calc_dt.hour)
-        ]
-        if df_period.empty:
-            raise ValueError("No EPW data at the specified time.")
+        # Get radiation model for surface reflections
+        n_reflection_steps = kwargs.pop('n_reflection_steps', 2)
+        model, valid_ground, ground_k = _get_or_create_radiation_model(
+            voxcity,
+            n_reflection_steps=n_reflection_steps,
+            progress_report=progress_report,
+            **kwargs
+        )
         
-        # Get solar position
-        offset_minutes = int(tz * 60)
-        local_tz = pytz.FixedOffset(offset_minutes)
-        df_local = df_period.copy()
-        df_local.index = df_local.index.tz_localize(local_tz)
-        df_utc = df_local.tz_convert(pytz.UTC)
+        # Manually set solar position on the model's solar_calc
+        model.solar_calc.cos_zenith[None] = cos_zenith
+        model.solar_calc.sun_direction[None] = [sun_direction[0], sun_direction[1], sun_direction[2]]
+        model.solar_calc.sun_up[None] = 1 if cos_zenith > 0 else 0
         
-        solar_positions = _get_solar_positions_astral(df_utc.index, lon, lat)
-        DNI = float(df_utc.iloc[0]['DNI']) * direct_normal_irradiance_scaling
-        DHI = float(df_utc.iloc[0]['DHI']) * diffuse_irradiance_scaling
-        azimuth_degrees = float(solar_positions.iloc[0]['azimuth'])
-        elevation_degrees = float(solar_positions.iloc[0]['elevation'])
+        # Compute shortwave radiation with the set solar position
+        model.compute_shortwave_radiation(
+            sw_direct=direct_normal_irradiance,
+            sw_diffuse=diffuse_irradiance
+        )
         
-        return get_global_solar_irradiance_map(
-            voxcity,
-            azimuth_degrees,
-            elevation_degrees,
-            DNI,
-            DHI,
-            show_plot=show_plot,
-            **kwargs
+        # Get surface outgoing radiation
+        n_surfaces = model.surfaces.count
+        surf_outgoing = model.surfaces.sw_out.to_numpy()[:n_surfaces]
+        
+        # Compute volumetric flux including reflections
+        # Use cached C2S-VF matrix if available, otherwise compute dynamically
+        if calculator.c2s_matrix_cached:
+            calculator.compute_swflux_vol_with_reflections_cached(
+                sw_direct=direct_normal_irradiance,
+                sw_diffuse=diffuse_irradiance,
+                cos_zenith=cos_zenith,
+                sun_direction=sun_direction,
+                surf_outgoing=surf_outgoing,
+                lad=domain.lad
+            )
+        else:
+            calculator.compute_swflux_vol_with_reflections(
+                sw_direct=direct_normal_irradiance,
+                sw_diffuse=diffuse_irradiance,
+                cos_zenith=cos_zenith,
+                sun_direction=sun_direction,
+                surfaces=model.surfaces,
+                surf_outgoing=surf_outgoing,
+                lad=domain.lad
+            )
+    else:
+        # Simple direct + diffuse only
+        if progress_report:
+            print("Computing volumetric flux (direct + diffuse)...")
+        
+        calculator.compute_swflux_vol(
+            sw_direct=direct_normal_irradiance,
+            sw_diffuse=diffuse_irradiance,
+            cos_zenith=cos_zenith,
+            sun_direction=sun_direction,
+            lad=domain.lad
         )
+        
+        # Compute ground_k for terrain-following extraction
+        ground_k = _compute_ground_k_from_voxels(voxel_data)
     
-    elif calc_type == 'cumulative':
-        return get_cumulative_global_solar_irradiance(
-            voxcity,
-            df,
-            lon,
-            lat,
-            tz,
-            direct_normal_irradiance_scaling=direct_normal_irradiance_scaling,
-            diffuse_irradiance_scaling=diffuse_irradiance_scaling,
-            show_plot=show_plot,
-            **kwargs
-        )
+    # Extract terrain-following horizontal slice at specified height above ground
+    # For each (i,j), extract at ground_k[i,j] + height_offset_k
+    height_offset_k = max(1, int(round(volumetric_height / meshsize)))
+    if progress_report:
+        print(f"Extracting volumetric irradiance at {volumetric_height}m above terrain (offset={height_offset_k} cells)")
     
-    else:
-        raise ValueError(f"Unknown calc_type: {calc_type}. Use 'instantaneous' or 'cumulative'.")
+    # Get full 3D volumetric flux and is_solid arrays
+    swflux_3d = calculator.get_swflux_vol()
+    is_solid = domain.is_solid.to_numpy()
+    
+    # Create output array
+    volumetric_map = np.full((ni, nj), np.nan, dtype=np.float64)
+    
+    # Extract terrain-following values
+    for i in range(ni):
+        for j in range(nj):
+            gk = ground_k[i, j]
+            if gk < 0:
+                # No valid ground - keep NaN
+                continue
+            k_extract = gk + height_offset_k
+            if k_extract >= nk:
+                # Above domain - keep NaN
+                continue
+            # Check if extraction point is in a solid cell
+            if is_solid[i, j, k_extract] == 1:
+                # Inside solid (building) - keep NaN
+                continue
+            volumetric_map[i, j] = swflux_3d[i, j, k_extract]
+    
+    # Flip to match VoxCity coordinate system
+    volumetric_map = np.flipud(volumetric_map)
+    
+    # Apply computation_mask if provided
+    if computation_mask is not None:
+        # Handle mask shape orientation
+        if computation_mask.shape == volumetric_map.shape:
+            flipped_mask = np.flipud(computation_mask)
+            volumetric_map = np.where(flipped_mask, volumetric_map, np.nan)
+        elif computation_mask.T.shape == volumetric_map.shape:
+            flipped_mask = np.flipud(computation_mask.T)
+            volumetric_map = np.where(flipped_mask, volumetric_map, np.nan)
+        else:
+            # Best effort - try direct application
+            if computation_mask.shape == volumetric_map.shape:
+                volumetric_map = np.where(computation_mask, volumetric_map, np.nan)
+        
+        if progress_report:
+            n_masked = np.sum(np.isnan(volumetric_map))
+            total = volumetric_map.size
+            print(f"  Cells outside computation_mask set to NaN: {n_masked}/{total} ({100*n_masked/total:.1f}%)")
+
+    if show_plot:
+        colormap = kwargs.get('colormap', 'magma')
+        vmin = kwargs.get('vmin', 0.0)
+        vmax = kwargs.get('vmax', max(float(np.nanmax(volumetric_map)), 1.0))
+        try:
+            import matplotlib.pyplot as plt
+            cmap = plt.cm.get_cmap(colormap).copy()
+            cmap.set_bad(color='lightgray')
+            plt.figure(figsize=(10, 8))
+            plt.imshow(volumetric_map, origin='lower', cmap=cmap, vmin=vmin, vmax=vmax)
+            plt.colorbar(label=f'Volumetric Solar Irradiance at {volumetric_height}m (W/m²)')
+            plt.title(f'Volumetric Irradiance (reflections={"on" if with_reflections else "off"})')
+            plt.axis('off')
+            plt.show()
+        except ImportError:
+            pass
+    
+    return volumetric_map
+
+
+def get_cumulative_volumetric_solar_irradiance(
+    voxcity,
+    df,
+    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
+) -> np.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.
+    
+    Args:
+        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²)
+    """
+    import time
+    from datetime import datetime
+    import pytz
+    import math
+    
+    # Extract parameters
+    kwargs = kwargs.copy()
+    progress_report = kwargs.pop('progress_report', False)
+    start_time = kwargs.pop('start_time', '01-01 05:00:00')
+    end_time = kwargs.pop('end_time', '01-01 20:00:00')
+    use_sky_patches = kwargs.pop('use_sky_patches', True)
+    sky_discretization = kwargs.pop('sky_discretization', 'tregenza')
+    n_azimuth = kwargs.pop('n_azimuth', 36)
+    n_zenith = kwargs.pop('n_zenith', 9)
+    computation_mask = kwargs.pop('computation_mask', None)
+    
+    if df.empty:
+        raise ValueError("No data in EPW dataframe.")
+    
+    # Parse time range
+    try:
+        start_dt = datetime.strptime(start_time, '%m-%d %H:%M:%S')
+        end_dt = datetime.strptime(end_time, '%m-%d %H:%M:%S')
+    except ValueError as ve:
+        raise ValueError("start_time and end_time must be in format 'MM-DD HH:MM:SS'") from ve
+    
+    # Filter dataframe to period
+    df = df.copy()
+    df['hour_of_year'] = (df.index.dayofyear - 1) * 24 + df.index.hour + 1
+    start_doy = datetime(2000, start_dt.month, start_dt.day).timetuple().tm_yday
+    end_doy = datetime(2000, end_dt.month, end_dt.day).timetuple().tm_yday
+    start_hour = (start_doy - 1) * 24 + start_dt.hour + 1
+    end_hour = (end_doy - 1) * 24 + end_dt.hour + 1
+    
+    if start_hour <= end_hour:
+        df_period = df[(df['hour_of_year'] >= start_hour) & (df['hour_of_year'] <= end_hour)]
+    else:
+        df_period = df[(df['hour_of_year'] >= start_hour) | (df['hour_of_year'] <= end_hour)]
+    
+    if df_period.empty:
+        raise ValueError("No EPW data in the specified period.")
+    
+    # Localize and convert to UTC
+    offset_minutes = int(tz * 60)
+    local_tz = pytz.FixedOffset(offset_minutes)
+    df_period_local = df_period.copy()
+    df_period_local.index = df_period_local.index.tz_localize(local_tz)
+    df_period_utc = df_period_local.tz_convert(pytz.UTC)
+    
+    # Get solar positions
+    solar_positions = _get_solar_positions_astral(df_period_utc.index, lon, lat)
+    
+    # Get or create cached calculator
+    calculator, domain = _get_or_create_volumetric_calculator(
+        voxcity,
+        n_azimuth=n_azimuth,
+        n_zenith=n_zenith,
+        progress_report=progress_report,
+        **kwargs
+    )
+    
+    voxel_data = voxcity.voxels.classes
+    meshsize = voxcity.voxels.meta.meshsize
+    ni, nj, nk = voxel_data.shape
+    
+    # Compute terrain-following extraction parameters
+    height_offset_k = max(1, int(round(volumetric_height / meshsize)))
+    if progress_report:
+        print(f"Extracting volumetric irradiance at {volumetric_height}m above terrain (offset={height_offset_k} cells)")
+    
+    # Get is_solid array for masking
+    is_solid = domain.is_solid.to_numpy()
+    
+    # Initialize cumulative map (will be NaN-masked at the end)
+    cumulative_map = np.zeros((ni, nj), dtype=np.float64)
+    time_step_hours = kwargs.get('time_step_hours', 1.0)
+    
+    # Get radiation model for reflections if needed
+    model = None
+    ground_k = None
+    if with_reflections:
+        n_reflection_steps = kwargs.pop('n_reflection_steps', 2)
+        model, valid_ground, ground_k = _get_or_create_radiation_model(
+            voxcity,
+            n_reflection_steps=n_reflection_steps,
+            progress_report=progress_report,
+            **kwargs
+        )
+    else:
+        # Compute ground_k for terrain-following extraction
+        ground_k = _compute_ground_k_from_voxels(voxel_data)
+    
+    # OPTIMIZATION: Initialize GPU-side cumulative accumulation
+    # This avoids transferring full 3D arrays for each patch/timestep
+    calculator.init_cumulative_accumulation(
+        ground_k=ground_k,
+        height_offset_k=height_offset_k,
+        is_solid=is_solid
+    )
+    
+    # OPTIMIZATION: Pre-compute Terrain-to-Surface VF matrix for cached reflections
+    # This makes reflection computation O(nnz) instead of O(N_cells * N_surfaces)
+    # for each sky patch, providing massive speedup for cumulative calculations.
+    if with_reflections and model is not None:
+        t2s_start = time.perf_counter() if progress_report else 0
+        calculator.compute_t2s_matrix(
+            surfaces=model.surfaces,
+            min_vf_threshold=1e-6,
+            progress_report=progress_report
+        )
+        if progress_report:
+            t2s_elapsed = time.perf_counter() - t2s_start
+            print(f"  T2S matrix pre-computation: {t2s_elapsed:.2f}s")
+    
+    # Extract arrays
+    azimuth_arr = solar_positions['azimuth'].to_numpy()
+    elevation_arr = solar_positions['elevation'].to_numpy()
+    dni_arr = df_period_utc['DNI'].to_numpy() * direct_normal_irradiance_scaling
+    dhi_arr = df_period_utc['DHI'].to_numpy() * diffuse_irradiance_scaling
+    
+    n_timesteps = len(azimuth_arr)
+    
+    if progress_report:
+        print(f"Computing cumulative volumetric irradiance for {n_timesteps} timesteps...")
+        print(f"  Height: {volumetric_height}m, Reflections: {'on' if with_reflections else 'off'}")
+        print(f"  Using GPU-optimized terrain-following accumulation")
+    
+    t0 = time.perf_counter() if progress_report else 0
+    
+    if use_sky_patches:
+        # Use sky patch aggregation for efficiency
+        from .sky import (
+            generate_tregenza_patches,
+            generate_reinhart_patches,
+            generate_uniform_grid_patches,
+            generate_fibonacci_patches,
+            get_tregenza_patch_index
+        )
+        
+        # Generate sky patches
+        if sky_discretization.lower() == 'tregenza':
+            patches, directions, solid_angles = generate_tregenza_patches()
+        elif sky_discretization.lower() == 'reinhart':
+            mf = kwargs.get('reinhart_mf', kwargs.get('mf', 4))
+            patches, directions, solid_angles = generate_reinhart_patches(mf=mf)
+        elif sky_discretization.lower() == 'uniform':
+            n_az = kwargs.get('sky_n_azimuth', 36)
+            n_el = kwargs.get('sky_n_elevation', 9)
+            patches, directions, solid_angles = generate_uniform_grid_patches(n_az, n_el)
+        elif sky_discretization.lower() == 'fibonacci':
+            n_patches = kwargs.get('sky_n_patches', 145)
+            patches, directions, solid_angles = generate_fibonacci_patches(n_patches=n_patches)
+        else:
+            raise ValueError(f"Unknown sky discretization method: {sky_discretization}")
+        
+        n_patches = len(patches)
+        cumulative_dni = np.zeros(n_patches, dtype=np.float64)
+        total_dhi = 0.0
+        
+        # Bin sun positions to patches
+        for i in range(n_timesteps):
+            elev = elevation_arr[i]
+            if elev <= 0:
+                continue
+            
+            az = azimuth_arr[i]
+            dni = dni_arr[i]
+            dhi = dhi_arr[i]
+            
+            if dni > 0:
+                patch_idx = get_tregenza_patch_index(az, elev)
+                if 0 <= patch_idx < n_patches:
+                    cumulative_dni[patch_idx] += dni * time_step_hours
+            
+            if dhi > 0:
+                total_dhi += dhi * time_step_hours
+        
+        # Process each patch with accumulated DNI
+        patches_with_dni = np.where(cumulative_dni > 0)[0]
+        
+        if progress_report:
+            print(f"  Processing {len(patches_with_dni)} sky patches with accumulated DNI...")
+        
+        for idx, patch_idx in enumerate(patches_with_dni):
+            patch_dni = cumulative_dni[patch_idx]
+            patch_dir = directions[patch_idx]
+            
+            # Convert patch direction to azimuth/elevation
+            patch_azimuth_ori = math.degrees(math.atan2(patch_dir[0], patch_dir[1]))
+            if patch_azimuth_ori < 0:
+                patch_azimuth_ori += 360
+            patch_elevation = math.degrees(math.asin(patch_dir[2]))
+            
+            # Apply same coordinate transform as ground-level functions
+            patch_azimuth = 180 - patch_azimuth_ori
+            azimuth_rad = math.radians(patch_azimuth)
+            elevation_rad = math.radians(patch_elevation)
+            cos_elev = math.cos(elevation_rad)
+            sin_elev = math.sin(elevation_rad)
+            
+            cos_zenith = sin_elev
+            sun_dir_x = cos_elev * math.cos(azimuth_rad)
+            sun_dir_y = cos_elev * math.sin(azimuth_rad)
+            sun_dir_z = sin_elev
+            sun_direction = (sun_dir_x, sun_dir_y, sun_dir_z)
+            
+            if with_reflections and model is not None:
+                # Set solar position on the model
+                model.solar_calc.cos_zenith[None] = cos_zenith
+                model.solar_calc.sun_direction[None] = [sun_direction[0], sun_direction[1], sun_direction[2]]
+                model.solar_calc.sun_up[None] = 1 if cos_zenith > 0 else 0
+                
+                # Compute surface irradiance with reflections (uses cached SVF matrix)
+                model.compute_shortwave_radiation(
+                    sw_direct=patch_dni / time_step_hours,  # Instantaneous for reflection calc
+                    sw_diffuse=0.0  # DHI handled separately
+                )
+                
+                n_surfaces = model.surfaces.count
+                surf_outgoing = model.surfaces.sw_out.to_numpy()[:n_surfaces]
+                
+                # OPTIMIZED: Compute direct+diffuse for full volume first
+                calculator.compute_swflux_vol(
+                    sw_direct=patch_dni / time_step_hours,
+                    sw_diffuse=0.0,
+                    cos_zenith=cos_zenith,
+                    sun_direction=sun_direction,
+                    lad=domain.lad
+                )
+                
+                # OPTIMIZED: Compute reflections using pre-computed T2S-VF matrix
+                # This is O(nnz) instead of O(N_terrain_cells * N_surfaces) per patch
+                calculator.compute_reflected_flux_terrain_cached(surf_outgoing=surf_outgoing)
+                
+                # Add reflections to swflux_vol at extraction level
+                calculator._add_reflected_to_total()
+            else:
+                calculator.compute_swflux_vol(
+                    sw_direct=patch_dni / time_step_hours,
+                    sw_diffuse=0.0,
+                    cos_zenith=cos_zenith,
+                    sun_direction=sun_direction,
+                    lad=domain.lad
+                )
+            
+            # OPTIMIZATION: Accumulate terrain-following slice directly on GPU
+            # This avoids transferring the full 3D array for each patch
+            calculator.accumulate_terrain_following_slice_gpu(weight=time_step_hours)
+            
+            if progress_report and (idx + 1) % 10 == 0:
+                elapsed = time.perf_counter() - t0
+                print(f"    Processed {idx + 1}/{len(patches_with_dni)} patches ({elapsed:.1f}s)")
+        
+        # Add diffuse contribution using GPU-optimized SVF accumulation
+        if total_dhi > 0:
+            calculator.accumulate_svf_diffuse_gpu(total_dhi=total_dhi)
+    
+    else:
+        # Process each timestep individually
+        for i in range(n_timesteps):
+            elev = elevation_arr[i]
+            if elev <= 0:
+                continue
+            
+            az = azimuth_arr[i]
+            dni = dni_arr[i]
+            dhi = dhi_arr[i]
+            
+            if dni <= 0 and dhi <= 0:
+                continue
+            
+            # Convert to direction vector
+            # Match the coordinate system used in ground-level functions
+            azimuth_degrees = 180 - az
+            azimuth_rad = math.radians(azimuth_degrees)
+            elevation_rad = math.radians(elev)
+            cos_elev = math.cos(elevation_rad)
+            sin_elev = math.sin(elevation_rad)
+            
+            sun_dir_x = cos_elev * math.cos(azimuth_rad)
+            sun_dir_y = cos_elev * math.sin(azimuth_rad)
+            sun_dir_z = sin_elev
+            sun_direction = (sun_dir_x, sun_dir_y, sun_dir_z)
+            cos_zenith = sin_elev
+            
+            if with_reflections and model is not None:
+                # Set solar position on the model
+                model.solar_calc.cos_zenith[None] = cos_zenith
+                model.solar_calc.sun_direction[None] = [sun_direction[0], sun_direction[1], sun_direction[2]]
+                model.solar_calc.sun_up[None] = 1 if cos_zenith > 0 else 0
+                
+                model.compute_shortwave_radiation(
+                    sw_direct=dni,
+                    sw_diffuse=dhi
+                )
+                
+                n_surfaces = model.surfaces.count
+                surf_outgoing = model.surfaces.sw_out.to_numpy()[:n_surfaces]
+                
+                # OPTIMIZED: Compute direct+diffuse for full volume first
+                calculator.compute_swflux_vol(
+                    sw_direct=dni,
+                    sw_diffuse=dhi,
+                    cos_zenith=cos_zenith,
+                    sun_direction=sun_direction,
+                    lad=domain.lad
+                )
+                
+                # OPTIMIZED: Compute reflections using pre-computed T2S-VF matrix
+                # This is O(nnz) instead of O(N_terrain_cells * N_surfaces) per timestep
+                calculator.compute_reflected_flux_terrain_cached(surf_outgoing=surf_outgoing)
+                
+                # Add reflections to swflux_vol at extraction level
+                calculator._add_reflected_to_total()
+            else:
+                calculator.compute_swflux_vol(
+                    sw_direct=dni,
+                    sw_diffuse=dhi,
+                    cos_zenith=cos_zenith,
+                    sun_direction=sun_direction,
+                    lad=domain.lad
+                )
+            
+            # OPTIMIZATION: Accumulate terrain-following slice directly on GPU
+            calculator.accumulate_terrain_following_slice_gpu(weight=time_step_hours)
+            
+            if progress_report and (i + 1) % 100 == 0:
+                elapsed = time.perf_counter() - t0
+                print(f"  Processed {i + 1}/{n_timesteps} timesteps ({elapsed:.1f}s)")
+    
+    if progress_report:
+        elapsed = time.perf_counter() - t0
+        print(f"Cumulative volumetric irradiance complete in {elapsed:.2f}s")
+    
+    # Get final cumulative map from GPU with NaN masking
+    cumulative_map = calculator.finalize_cumulative_map(apply_nan_mask=True)
+    
+    # Flip to match VoxCity coordinate system
+    cumulative_map = np.flipud(cumulative_map)
+    
+    # Apply computation_mask if provided
+    if computation_mask is not None:
+        # Handle mask shape orientation
+        if computation_mask.shape == cumulative_map.shape:
+            flipped_mask = np.flipud(computation_mask)
+            cumulative_map = np.where(flipped_mask, cumulative_map, np.nan)
+        elif computation_mask.T.shape == cumulative_map.shape:
+            flipped_mask = np.flipud(computation_mask.T)
+            cumulative_map = np.where(flipped_mask, cumulative_map, np.nan)
+        else:
+            # Best effort - try direct application
+            if computation_mask.shape == cumulative_map.shape:
+                cumulative_map = np.where(computation_mask, cumulative_map, np.nan)
+        
+        if progress_report:
+            n_masked = np.sum(np.isnan(cumulative_map))
+            total = cumulative_map.size
+            print(f"  Cells outside computation_mask set to NaN: {n_masked}/{total} ({100*n_masked/total:.1f}%)")
+
+    if show_plot:
+        colormap = kwargs.get('colormap', 'magma')
+        vmin = kwargs.get('vmin', 0.0)
+        vmax = kwargs.get('vmax', max(float(np.nanmax(cumulative_map)), 1.0))
+        try:
+            import matplotlib.pyplot as plt
+            cmap = plt.cm.get_cmap(colormap).copy()
+            cmap.set_bad(color='lightgray')
+            plt.figure(figsize=(10, 8))
+            plt.imshow(cumulative_map, origin='lower', cmap=cmap, vmin=vmin, vmax=vmax)
+            plt.colorbar(label=f'Cumulative Volumetric Irradiance at {volumetric_height}m (Wh/m²)')
+            plt.title(f'Cumulative Volumetric Irradiance (reflections={"on" if with_reflections else "off"})')
+            plt.axis('off')
+            plt.show()
+        except ImportError:
+            pass
+    
+    return cumulative_map
+
+
+def 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
+) -> np.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
+    
+    Args:
+        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²)
+    """
+    from datetime import datetime
+    import pytz
+    
+    # Load EPW data using helper function
+    kwargs_copy = dict(kwargs)
+    df, lon, lat, tz = _load_epw_data(
+        epw_file_path=kwargs_copy.pop('epw_file_path', None),
+        download_nearest_epw=kwargs_copy.pop('download_nearest_epw', False),
+        voxcity=voxcity,
+        **kwargs_copy
+    )
+    
+    if calc_type == 'instantaneous':
+        calc_time = kwargs.get('calc_time', '01-01 12:00:00')
+        try:
+            calc_dt = datetime.strptime(calc_time, '%m-%d %H:%M:%SS')
+        except ValueError:
+            try:
+                calc_dt = datetime.strptime(calc_time, '%m-%d %H:%M:%S')
+            except ValueError:
+                raise ValueError("calc_time must be in format 'MM-DD HH:MM:SS'")
+        
+        df_period = df[
+            (df.index.month == calc_dt.month) &
+            (df.index.day == calc_dt.day) &
+            (df.index.hour == calc_dt.hour)
+        ]
+        if df_period.empty:
+            raise ValueError("No EPW data at the specified time.")
+        
+        # Get solar position
+        offset_minutes = int(tz * 60)
+        local_tz = pytz.FixedOffset(offset_minutes)
+        df_local = df_period.copy()
+        df_local.index = df_local.index.tz_localize(local_tz)
+        df_utc = df_local.tz_convert(pytz.UTC)
+        
+        solar_positions = _get_solar_positions_astral(df_utc.index, lon, lat)
+        DNI = float(df_utc.iloc[0]['DNI']) * direct_normal_irradiance_scaling
+        DHI = float(df_utc.iloc[0]['DHI']) * diffuse_irradiance_scaling
+        azimuth_degrees = float(solar_positions.iloc[0]['azimuth'])
+        elevation_degrees = float(solar_positions.iloc[0]['elevation'])
+        
+        return get_volumetric_solar_irradiance_map(
+            voxcity,
+            azimuth_degrees,
+            elevation_degrees,
+            DNI,
+            DHI,
+            volumetric_height=volumetric_height,
+            with_reflections=with_reflections,
+            show_plot=show_plot,
+            **kwargs
+        )
+    
+    elif calc_type == 'cumulative':
+        return get_cumulative_volumetric_solar_irradiance(
+            voxcity,
+            df,
+            lon,
+            lat,
+            tz,
+            direct_normal_irradiance_scaling=direct_normal_irradiance_scaling,
+            diffuse_irradiance_scaling=diffuse_irradiance_scaling,
+            volumetric_height=volumetric_height,
+            with_reflections=with_reflections,
+            show_plot=show_plot,
+            **kwargs
+        )
+    
+    else:
+        raise ValueError(f"Unknown calc_type: {calc_type}. Use 'instantaneous' or 'cumulative'.")
+
+
+def 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,  # Deprecated, for backward compatibility
+    computation_mask: np.ndarray = None,
+    **kwargs
+) -> np.ndarray:
+    """
+    GPU-accelerated global irradiance from EPW file.
+    
+    This function matches the signature of voxcity.simulator.solar.get_global_solar_irradiance_using_epw
+    using Taichi GPU acceleration.
+    
+    Args:
+        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.
+            Use create_computation_mask() to create masks easily.
+        **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'
+        )
+    """
+    from datetime import datetime
+    import pytz
+    import warnings
+    
+    # Handle backward compatibility with calc_type parameter
+    if calc_type is not None:
+        warnings.warn(
+            "calc_type parameter is deprecated. Use temporal_mode and spatial_mode instead. "
+            "Example: temporal_mode='cumulative', spatial_mode='volumetric'",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        if calc_type == 'instantaneous':
+            temporal_mode = 'instantaneous'
+            spatial_mode = 'horizontal'
+        elif calc_type == 'cumulative':
+            temporal_mode = 'cumulative'
+            spatial_mode = 'horizontal'
+        elif calc_type == 'volumetric':
+            # Legacy volumetric: determine temporal mode from time parameters
+            spatial_mode = 'volumetric'
+            calc_time = kwargs.get('calc_time', None)
+            start_time = kwargs.get('start_time', None)
+            if calc_time is not None and start_time is None:
+                temporal_mode = 'instantaneous'
+            else:
+                temporal_mode = 'cumulative'
+        else:
+            raise ValueError(f"Unknown calc_type: {calc_type}. Use temporal_mode/spatial_mode instead.")
+    
+    # Validate parameters
+    if temporal_mode not in ('instantaneous', 'cumulative'):
+        raise ValueError(f"temporal_mode must be 'instantaneous' or 'cumulative', got '{temporal_mode}'")
+    if spatial_mode not in ('horizontal', 'volumetric'):
+        raise ValueError(f"spatial_mode must be 'horizontal' or 'volumetric', got '{spatial_mode}'")
+    
+    # Load EPW data using helper function
+    kwargs_copy = dict(kwargs)
+    df, lon, lat, tz = _load_epw_data(
+        epw_file_path=kwargs_copy.pop('epw_file_path', None),
+        download_nearest_epw=kwargs_copy.pop('download_nearest_epw', False),
+        voxcity=voxcity,
+        **kwargs_copy
+    )
+    
+    # Add computation_mask to kwargs for passing to underlying functions
+    if computation_mask is not None:
+        kwargs['computation_mask'] = computation_mask
+    
+    # Route to appropriate function based on temporal_mode × spatial_mode
+    if spatial_mode == 'horizontal':
+        # Ground-level horizontal irradiance
+        if temporal_mode == 'instantaneous':
+            calc_time = kwargs.get('calc_time', '01-01 12:00:00')
+            try:
+                calc_dt = datetime.strptime(calc_time, '%m-%d %H:%M:%S')
+            except ValueError:
+                raise ValueError("calc_time must be in format 'MM-DD HH:MM:SS'")
+            
+            df_period = df[
+                (df.index.month == calc_dt.month) &
+                (df.index.day == calc_dt.day) &
+                (df.index.hour == calc_dt.hour)
+            ]
+            if df_period.empty:
+                raise ValueError("No EPW data at the specified time.")
+            
+            offset_minutes = int(tz * 60)
+            local_tz = pytz.FixedOffset(offset_minutes)
+            df_local = df_period.copy()
+            df_local.index = df_local.index.tz_localize(local_tz)
+            df_utc = df_local.tz_convert(pytz.UTC)
+            
+            solar_positions = _get_solar_positions_astral(df_utc.index, lon, lat)
+            DNI = float(df_utc.iloc[0]['DNI']) * direct_normal_irradiance_scaling
+            DHI = float(df_utc.iloc[0]['DHI']) * diffuse_irradiance_scaling
+            azimuth_degrees = float(solar_positions.iloc[0]['azimuth'])
+            elevation_degrees = float(solar_positions.iloc[0]['elevation'])
+            
+            return get_global_solar_irradiance_map(
+                voxcity,
+                azimuth_degrees,
+                elevation_degrees,
+                DNI,
+                DHI,
+                show_plot=show_plot,
+                **kwargs
+            )
+        
+        else:  # cumulative
+            return get_cumulative_global_solar_irradiance(
+                voxcity,
+                df,
+                lon,
+                lat,
+                tz,
+                direct_normal_irradiance_scaling=direct_normal_irradiance_scaling,
+                diffuse_irradiance_scaling=diffuse_irradiance_scaling,
+                show_plot=show_plot,
+                **kwargs
+            )
+    
+    else:  # volumetric
+        # 3D volumetric radiation field
+        volumetric_height = kwargs.pop('volumetric_height', kwargs.pop('view_point_height', 1.5))
+        with_reflections = kwargs.pop('with_reflections', False)
+        
+        if temporal_mode == 'instantaneous':
+            calc_time = kwargs.get('calc_time', '01-01 12:00:00')
+            try:
+                calc_dt = datetime.strptime(calc_time, '%m-%d %H:%M:%S')
+            except ValueError:
+                raise ValueError("calc_time must be in format 'MM-DD HH:MM:SS'")
+            
+            df_period = df[
+                (df.index.month == calc_dt.month) &
+                (df.index.day == calc_dt.day) &
+                (df.index.hour == calc_dt.hour)
+            ]
+            if df_period.empty:
+                raise ValueError("No EPW data at the specified time.")
+            
+            offset_minutes = int(tz * 60)
+            local_tz = pytz.FixedOffset(offset_minutes)
+            df_local = df_period.copy()
+            df_local.index = df_local.index.tz_localize(local_tz)
+            df_utc = df_local.tz_convert(pytz.UTC)
+            
+            solar_positions = _get_solar_positions_astral(df_utc.index, lon, lat)
+            DNI = float(df_utc.iloc[0]['DNI']) * direct_normal_irradiance_scaling
+            DHI = float(df_utc.iloc[0]['DHI']) * diffuse_irradiance_scaling
+            azimuth_degrees = float(solar_positions.iloc[0]['azimuth'])
+            elevation_degrees = float(solar_positions.iloc[0]['elevation'])
+            
+            return get_volumetric_solar_irradiance_map(
+                voxcity,
+                azimuth_degrees,
+                elevation_degrees,
+                DNI,
+                DHI,
+                volumetric_height=volumetric_height,
+                with_reflections=with_reflections,
+                show_plot=show_plot,
+                **kwargs
+            )
+        
+        else:  # cumulative
+            return get_cumulative_volumetric_solar_irradiance(
+                voxcity,
+                df,
+                lon,
+                lat,
+                tz,
+                direct_normal_irradiance_scaling=direct_normal_irradiance_scaling,
+                diffuse_irradiance_scaling=diffuse_irradiance_scaling,
+                volumetric_height=volumetric_height,
+                with_reflections=with_reflections,
+                show_plot=show_plot,
+                **kwargs
+            )
 
 
 def save_irradiance_mesh(mesh, filepath: str) -> None:
@@ -2777,17 +4165,8 @@ def _get_or_create_gpu_ray_tracer(
                 return cache
             
             # Data changed, need to re-upload (but keep fields)
-            is_solid = np.zeros((nx, ny, nz), dtype=np.int32)
-            lad_array = np.zeros((nx, ny, nz), dtype=np.float32)
-            
-            for i in range(nx):
-                for j in range(ny):
-                    for k in range(nz):
-                        val = voxel_data[i, j, k]
-                        if val == VOXCITY_BUILDING_CODE or val == VOXCITY_GROUND_CODE or val > 0:
-                            is_solid[i, j, k] = 1
-                        elif val == VOXCITY_TREE_CODE:
-                            lad_array[i, j, k] = tree_lad
+            # Use vectorized helper
+            is_solid, lad_array = _convert_voxel_data_to_arrays(voxel_data, tree_lad)
             
             cache.is_solid_field.from_numpy(is_solid)
             cache.lad_field.from_numpy(lad_array)
@@ -2797,18 +4176,8 @@ def _get_or_create_gpu_ray_tracer(
             _compute_topo_gpu(cache.is_solid_field, cache.topo_top_field, nz)
             return cache
     
-    # Need to create new cache
-    is_solid = np.zeros((nx, ny, nz), dtype=np.int32)
-    lad_array = np.zeros((nx, ny, nz), dtype=np.float32)
-    
-    for i in range(nx):
-        for j in range(ny):
-            for k in range(nz):
-                val = voxel_data[i, j, k]
-                if val == VOXCITY_BUILDING_CODE or val == VOXCITY_GROUND_CODE or val > 0:
-                    is_solid[i, j, k] = 1
-                elif val == VOXCITY_TREE_CODE:
-                    lad_array[i, j, k] = tree_lad
+    # Need to create new cache - use vectorized helper
+    is_solid, lad_array = _convert_voxel_data_to_arrays(voxel_data, tree_lad)
     
     # Create Taichi fields
     is_solid_field = ti.field(dtype=ti.i32, shape=(nx, ny, nz))