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

voxcity/simulator_gpu/solar/volumetric.py

@@ -117,6 +117,87 @@ class VolumetricFluxCalculator:
         
         # Flag for computed state
         self._skyvf_computed = False
+        
+        # ========== Cell-to-Surface View Factor (C2S-VF) Matrix Caching ==========
+        # Pre-compute which surfaces each voxel cell can see and their view factors.
+        # This makes reflected flux computation O(nnz) instead of O(N_cells * N_surfaces).
+        # 
+        # Stored in sparse COO format:
+        # - c2s_cell_idx[i]: Linear cell index (i * ny * nz + j * nz + k)
+        # - c2s_surf_idx[i]: Surface index
+        # - c2s_vf[i]: View factor (includes geometry + transmissivity)
+        #
+        # For multi-timestep simulations with reflections, call compute_c2s_matrix()
+        # once to pre-compute, then use fast compute_reflected_flux_vol_cached().
+        
+        self._c2s_matrix_cached = False
+        self._c2s_nnz = 0
+        
+        # Estimate max non-zeros: assume each cell sees ~50 surfaces on average
+        # For a 200x200x50 domain = 2M cells * 50 = 100M entries max
+        # Cap at reasonable memory limit (~1.6GB for the 4 arrays)
+        n_cells = self.nx * self.ny * self.nz
+        estimated_entries = min(n_cells * 50, 100_000_000)
+        self._max_c2s_entries = estimated_entries
+        
+        # Sparse COO arrays for C2S-VF matrix (allocated on demand)
+        self._c2s_cell_idx = None
+        self._c2s_surf_idx = None
+        self._c2s_vf = None
+        self._c2s_count = None
+        
+        # Pre-allocated surface outgoing field for efficient repeated calls
+        self._surf_out_field = None
+        self._surf_out_max_size = 0
+        
+        # ========== Cumulative Terrain-Following Accumulation (Optimization) ==========
+        # For cumulative simulations, accumulate terrain-following slices directly on GPU
+        # instead of transferring full 3D arrays each timestep/patch.
+        # This provides 10-15x speedup for cumulative volumetric calculations.
+        
+        # 2D cumulative map for terrain-following irradiance accumulation
+        self._cumulative_map = ti.field(dtype=ti.f64, shape=(self.nx, self.ny))
+        
+        # Ground k-levels for terrain-following extraction (set by init_cumulative_accumulation)
+        self._ground_k = ti.field(dtype=ti.i32, shape=(self.nx, self.ny))
+        
+        # Height offset for extraction (cells above ground)
+        self._height_offset_k = 0
+        
+        # Whether cumulative accumulation is initialized
+        self._cumulative_initialized = False
+        
+        # ========== Terrain-Following Cell-to-Surface VF (T2S-VF) Matrix Caching ==========
+        # Pre-compute view factors from terrain-following evaluation cells to surfaces.
+        # This is for O(nx*ny) cells only (at volumetric_height above ground), not full 3D.
+        #
+        # Stored in sparse COO format:
+        # - t2s_ij_idx[i]: 2D cell index (i * ny + j)
+        # - t2s_surf_idx[i]: Surface index
+        # - t2s_vf[i]: View factor (includes geometry + transmissivity)
+        #
+        # For cumulative volumetric simulations with reflections:
+        # 1. Call init_cumulative_accumulation() to set ground_k and height_offset
+        # 2. Call compute_t2s_matrix() once to pre-compute view factors
+        # 3. Use compute_reflected_flux_terrain_cached() for fast O(nnz) reflections
+        
+        self._t2s_matrix_cached = False
+        self._t2s_nnz = 0
+        
+        # Estimate max non-zeros: each terrain cell might see ~200 surfaces on average
+        # For a 300x300 domain = 90K cells * 200 = 18M entries max
+        n_terrain_cells = self.nx * self.ny
+        estimated_t2s_entries = min(n_terrain_cells * 200, 50_000_000)  # Cap at 50M
+        self._max_t2s_entries = estimated_t2s_entries
+        
+        # Sparse COO arrays for T2S-VF matrix (allocated on demand)
+        self._t2s_ij_idx = None
+        self._t2s_surf_idx = None
+        self._t2s_vf = None
+        self._t2s_count = None
+        
+        # Parameters used for cached T2S matrix (for validation)
+        self._t2s_height_offset_k = -1
     
     @ti.kernel
     def _init_azimuth_directions(self):
@@ -946,6 +1027,9 @@ class VolumetricFluxCalculator:
         For each grid cell, integrates reflected radiation from all visible
         surfaces weighted by view factor and transmissivity.
         
+        Uses a max distance cutoff for performance - view factor drops as 1/d²,
+        so distant surfaces contribute negligibly.
+        
         Args:
             n_surfaces: Number of surface elements
             surf_center: Surface center positions (n_surfaces, 3)
@@ -960,6 +1044,10 @@ class VolumetricFluxCalculator:
         # flux = Σ (surfout * area * transmissivity * cos_angle) / (4 * π * dist²)
         # The factor 0.25 accounts for sphere geometry (projected area / surface area)
         
+        # Maximum distance for reflections (meters). Beyond this, VF is negligible.
+        # At 30m with 1m² area, VF contribution is ~1/(π*900) ≈ 0.035%
+        max_dist_sq = 900.0  # 30m max distance
+        
         for i, j, k in ti.ndrange(self.nx, self.ny, self.nz):
             # Skip solid cells
             if is_solid[i, j, k] == 1:
@@ -980,18 +1068,20 @@ class VolumetricFluxCalculator:
                     surf_x = surf_center[surf_idx][0]
                     surf_y = surf_center[surf_idx][1]
                     surf_z = surf_center[surf_idx][2]
-                    surf_nx = surf_normal[surf_idx][0]
-                    surf_ny = surf_normal[surf_idx][1]
-                    surf_nz = surf_normal[surf_idx][2]
-                    area = surf_area[surf_idx]
                     
-                    # Distance to surface
+                    # Distance to surface - early exit for distant surfaces
                     dx = cell_x - surf_x
                     dy = cell_y - surf_y
                     dz = cell_z - surf_z
                     dist_sq = dx*dx + dy*dy + dz*dz
                     
-                    if dist_sq > 0.01:  # Avoid numerical issues
+                    # Skip if beyond max distance or too close
+                    if dist_sq > 0.01 and dist_sq < max_dist_sq:
+                        surf_nx = surf_normal[surf_idx][0]
+                        surf_ny = surf_normal[surf_idx][1]
+                        surf_nz = surf_normal[surf_idx][2]
+                        area = surf_area[surf_idx]
+                        
                         dist = ti.sqrt(dist_sq)
                         
                         # Direction from surface to cell (normalized)
@@ -1030,6 +1120,10 @@ class VolumetricFluxCalculator:
         This propagates reflected radiation from surfaces into the 3D volume.
         Should be called after surface reflection calculations are complete.
         
+        NOTE: This is O(N_cells * N_surfaces) and can be slow for large domains.
+        For repeated calls, use compute_c2s_matrix() once followed by
+        compute_reflected_flux_vol_cached() for O(nnz) computation.
+        
         Args:
             surfaces: Surfaces object with geometry (center, normal, area)
             surf_outgoing: Array of surface outgoing radiation (W/m²)
@@ -1038,17 +1132,19 @@ class VolumetricFluxCalculator:
         n_surfaces = surfaces.n_surfaces[None]
         
         if n_surfaces == 0:
-            print("Warning: No surfaces defined, skipping reflected flux calculation")
             return
         
-        # Create temporary taichi field for outgoing radiation
-        surf_out_field = ti.field(dtype=ti.f32, shape=(n_surfaces,))
-        surf_out_field.from_numpy(surf_outgoing[:n_surfaces].astype(np.float32))
+        # Re-use pre-allocated field if available, otherwise create temporary
+        if self._surf_out_field is not None and self._surf_out_max_size >= n_surfaces:
+            self._surf_out_field.from_numpy(surf_outgoing[:n_surfaces].astype(np.float32))
+            surf_out_field = self._surf_out_field
+        else:
+            # Create temporary taichi field for outgoing radiation
+            surf_out_field = ti.field(dtype=ti.f32, shape=(n_surfaces,))
+            surf_out_field.from_numpy(surf_outgoing[:n_surfaces].astype(np.float32))
         
         has_lad = 1 if self.domain.lad is not None else 0
         
-        print(f"Computing volumetric reflected flux from {n_surfaces} surfaces...")
-        
         if has_lad:
             self._compute_reflected_flux_kernel(
                 n_surfaces,
@@ -1071,8 +1167,6 @@ class VolumetricFluxCalculator:
                 self.domain.lad,
                 0
             )
-        
-        print("Volumetric reflected flux computation complete.")
     
     @ti.kernel
     def _add_reflected_to_total(self):
@@ -1086,6 +1180,136 @@ class VolumetricFluxCalculator:
         for i, j, k in ti.ndrange(self.nx, self.ny, self.nz):
             self.swflux_reflected_vol[i, j, k] = 0.0
     
+    @ti.kernel
+    def _compute_reflected_flux_terrain_kernel(
+        self,
+        n_surfaces: ti.i32,
+        surf_center: ti.template(),
+        surf_normal: ti.template(),
+        surf_area: ti.template(),
+        surf_outgoing: ti.template(),
+        is_solid: ti.template(),
+        lad: ti.template(),
+        has_lad: ti.i32,
+        height_offset: ti.i32
+    ):
+        """
+        Compute reflected flux ONLY at terrain-following extraction level.
+        
+        This is an optimized version that only computes for the cells at
+        (i, j, ground_k[i,j] + height_offset_k) instead of all 3D cells.
+        
+        ~61x faster than full volumetric reflection computation.
+        
+        Requires init_cumulative_accumulation() to be called first.
+        """
+        max_dist_sq = 900.0  # 30m max distance
+        
+        for i, j in ti.ndrange(self.nx, self.ny):
+            k = self._ground_k[i, j] + height_offset
+            
+            # Skip out-of-bounds or solid cells
+            if k < 0 or k >= self.nz:
+                continue
+            if is_solid[i, j, k] == 1:
+                continue
+            
+            cell_x = (ti.cast(i, ti.f32) + 0.5) * self.dx
+            cell_y = (ti.cast(j, ti.f32) + 0.5) * self.dy
+            cell_z = (ti.cast(k, ti.f32) + 0.5) * self.dz
+            
+            total_reflected = 0.0
+            
+            for surf_idx in range(n_surfaces):
+                outgoing = surf_outgoing[surf_idx]
+                
+                if outgoing > 0.1:
+                    surf_x = surf_center[surf_idx][0]
+                    surf_y = surf_center[surf_idx][1]
+                    surf_z = surf_center[surf_idx][2]
+                    
+                    dx = cell_x - surf_x
+                    dy = cell_y - surf_y
+                    dz = cell_z - surf_z
+                    dist_sq = dx*dx + dy*dy + dz*dz
+                    
+                    if dist_sq > 0.01 and dist_sq < max_dist_sq:
+                        surf_nx = surf_normal[surf_idx][0]
+                        surf_ny = surf_normal[surf_idx][1]
+                        surf_nz = surf_normal[surf_idx][2]
+                        area = surf_area[surf_idx]
+                        
+                        dist = ti.sqrt(dist_sq)
+                        
+                        dir_x = dx / dist
+                        dir_y = dy / dist
+                        dir_z = dz / dist
+                        
+                        cos_angle = dir_x * surf_nx + dir_y * surf_ny + dir_z * surf_nz
+                        
+                        if cos_angle > 0.0:
+                            trans = self._trace_transmissivity_to_surface(
+                                i, j, k, surf_x, surf_y, surf_z,
+                                surf_nx, surf_ny, surf_nz,
+                                is_solid, lad, has_lad
+                            )
+                            
+                            if trans > 0.0:
+                                vf = area * cos_angle / (PI * dist_sq)
+                                contribution = outgoing * vf * trans * 0.25
+                                total_reflected += contribution
+            
+            self.swflux_reflected_vol[i, j, k] = total_reflected
+    
+    def compute_reflected_flux_terrain_following(
+        self,
+        surfaces,
+        surf_outgoing: np.ndarray
+    ):
+        """
+        Compute reflected flux only at terrain-following extraction level.
+        
+        This is ~61x faster than compute_reflected_flux_vol() because it only
+        computes for O(nx*ny) cells instead of O(nx*ny*nz) cells.
+        
+        Requires init_cumulative_accumulation() to be called first.
+        
+        Args:
+            surfaces: Surfaces object with geometry (center, normal, area)
+            surf_outgoing: Array of surface outgoing radiation (W/m²)
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Must call init_cumulative_accumulation() first")
+        
+        n_surfaces = surfaces.n_surfaces[None]
+        if n_surfaces == 0:
+            return
+        
+        # Re-use pre-allocated field if available
+        if self._surf_out_field is not None and self._surf_out_max_size >= n_surfaces:
+            self._surf_out_field.from_numpy(surf_outgoing[:n_surfaces].astype(np.float32))
+            surf_out_field = self._surf_out_field
+        else:
+            surf_out_field = ti.field(dtype=ti.f32, shape=(n_surfaces,))
+            surf_out_field.from_numpy(surf_outgoing[:n_surfaces].astype(np.float32))
+        
+        has_lad = 1 if self.domain.lad is not None else 0
+        
+        # Clear reflected flux field before computing
+        self._clear_reflected_flux()
+        
+        self._compute_reflected_flux_terrain_kernel(
+            n_surfaces,
+            surfaces.center,
+            surfaces.normal,
+            surfaces.area,
+            surf_out_field,
+            self.domain.is_solid,
+            self.domain.lad,
+            has_lad,
+            self._height_offset_k
+        )
+    
     def compute_swflux_vol_with_reflections(
         self,
         sw_direct: float,
@@ -1149,3 +1373,727 @@ class VolumetricFluxCalculator:
             'reflected': self.swflux_reflected_vol.to_numpy(),
             'skyvf': self.skyvf_vol.to_numpy()
         }
+
+    # =========================================================================
+    # Cell-to-Surface View Factor (C2S-VF) Matrix Caching
+    # =========================================================================
+    # These methods pre-compute which surfaces each voxel cell can see,
+    # making repeated reflected flux calculations O(nnz) instead of O(N*M).
+    
+    def compute_c2s_matrix(
+        self,
+        surfaces,
+        is_solid,
+        lad=None,
+        min_vf_threshold: float = 1e-6,
+        progress_report: bool = False
+    ):
+        """
+        Pre-compute Cell-to-Surface View Factor matrix for fast reflections.
+        
+        This is O(N_cells * N_surfaces) but only needs to be done once for
+        fixed geometry. Subsequent calls to compute_reflected_flux_vol_cached()
+        become O(nnz) instead of O(N*M).
+        
+        Call this before running multi-timestep simulations with reflections.
+        
+        Args:
+            surfaces: Surfaces object with center, normal, area fields
+            is_solid: 3D solid obstacle field
+            lad: Optional LAD field for vegetation attenuation
+            min_vf_threshold: Minimum view factor to store (sparsity threshold)
+            progress_report: Print progress messages
+        """
+        if self._c2s_matrix_cached:
+            if progress_report:
+                print("C2S-VF matrix already cached, skipping recomputation.")
+            return
+        
+        n_surfaces = surfaces.n_surfaces[None]
+        n_cells = self.nx * self.ny * self.nz
+        
+        if progress_report:
+            print(f"Pre-computing C2S-VF matrix: {n_cells:,} cells × {n_surfaces:,} surfaces")
+            print("  This is O(N*M) but only runs once for fixed geometry.")
+        
+        # Allocate sparse COO arrays if not already done
+        if self._c2s_cell_idx is None:
+            self._c2s_cell_idx = ti.field(dtype=ti.i32, shape=(self._max_c2s_entries,))
+            self._c2s_surf_idx = ti.field(dtype=ti.i32, shape=(self._max_c2s_entries,))
+            self._c2s_vf = ti.field(dtype=ti.f32, shape=(self._max_c2s_entries,))
+            self._c2s_count = ti.field(dtype=ti.i32, shape=())
+        
+        has_lad = 1 if lad is not None else 0
+        
+        # Compute the matrix
+        self._c2s_count[None] = 0
+        self._compute_c2s_matrix_kernel(
+            n_surfaces,
+            surfaces.center,
+            surfaces.normal,
+            surfaces.area,
+            is_solid,
+            lad if lad is not None else self.domain.lad,  # Fallback to domain LAD
+            has_lad,
+            min_vf_threshold
+        )
+        
+        computed_nnz = int(self._c2s_count[None])
+        if computed_nnz > self._max_c2s_entries:
+            print(f"Warning: C2S-VF matrix truncated! {computed_nnz:,} > {self._max_c2s_entries:,}")
+            print("  Consider increasing _max_c2s_entries.")
+            self._c2s_nnz = self._max_c2s_entries
+        else:
+            self._c2s_nnz = computed_nnz
+        
+        self._c2s_matrix_cached = True
+        
+        sparsity_pct = self._c2s_nnz / (n_cells * n_surfaces) * 100 if n_surfaces > 0 else 0
+        if progress_report:
+            print(f"  C2S-VF matrix computed: {self._c2s_nnz:,} non-zero entries")
+            print(f"  Sparsity: {sparsity_pct:.4f}% of full matrix")
+            speedup = (n_cells * n_surfaces) / max(1, self._c2s_nnz)
+            print(f"  Speedup factor: ~{speedup:.0f}x per timestep")
+    
+    @ti.kernel
+    def _compute_c2s_matrix_kernel(
+        self,
+        n_surfaces: ti.i32,
+        surf_center: ti.template(),
+        surf_normal: ti.template(),
+        surf_area: ti.template(),
+        is_solid: ti.template(),
+        lad: ti.template(),
+        has_lad: ti.i32,
+        min_threshold: ti.f32
+    ):
+        """
+        Compute C2S-VF matrix entries.
+        
+        For each (cell, surface) pair, compute the view factor including
+        geometry and transmissivity. Store if above threshold.
+        """
+        for i, j, k in ti.ndrange(self.nx, self.ny, self.nz):
+            # Skip solid cells
+            if is_solid[i, j, k] == 1:
+                continue
+            
+            cell_idx = i * (self.ny * self.nz) + j * self.nz + k
+            cell_x = (ti.cast(i, ti.f32) + 0.5) * self.dx
+            cell_y = (ti.cast(j, ti.f32) + 0.5) * self.dy
+            cell_z = (ti.cast(k, ti.f32) + 0.5) * self.dz
+            
+            for surf_idx in range(n_surfaces):
+                surf_x = surf_center[surf_idx][0]
+                surf_y = surf_center[surf_idx][1]
+                surf_z = surf_center[surf_idx][2]
+                surf_nx = surf_normal[surf_idx][0]
+                surf_ny = surf_normal[surf_idx][1]
+                surf_nz = surf_normal[surf_idx][2]
+                area = surf_area[surf_idx]
+                
+                # Distance to surface
+                dx = cell_x - surf_x
+                dy = cell_y - surf_y
+                dz = cell_z - surf_z
+                dist_sq = dx*dx + dy*dy + dz*dz
+                
+                if dist_sq > 0.01:  # Avoid numerical issues
+                    dist = ti.sqrt(dist_sq)
+                    
+                    # Direction from surface to cell (normalized)
+                    dir_x = dx / dist
+                    dir_y = dy / dist
+                    dir_z = dz / dist
+                    
+                    # Cosine of angle between normal and direction
+                    cos_angle = dir_x * surf_nx + dir_y * surf_ny + dir_z * surf_nz
+                    
+                    if cos_angle > 0.0:  # Surface faces the cell
+                        # Get transmissivity
+                        trans = self._trace_transmissivity_to_surface(
+                            i, j, k, surf_x, surf_y, surf_z,
+                            surf_nx, surf_ny, surf_nz,
+                            is_solid, lad, has_lad
+                        )
+                        
+                        if trans > 0.0:
+                            # View factor: (A * cos_θ) / (π * d²) * 0.25 for sphere
+                            vf = area * cos_angle / (PI * dist_sq) * trans * 0.25
+                            
+                            if vf > min_threshold:
+                                idx = ti.atomic_add(self._c2s_count[None], 1)
+                                if idx < self._max_c2s_entries:
+                                    self._c2s_cell_idx[idx] = cell_idx
+                                    self._c2s_surf_idx[idx] = surf_idx
+                                    self._c2s_vf[idx] = vf
+    
+    def compute_reflected_flux_vol_cached(
+        self,
+        surf_outgoing: np.ndarray,
+        progress_report: bool = False
+    ):
+        """
+        Compute volumetric reflected flux using cached C2S-VF matrix.
+        
+        This is O(nnz) instead of O(N_cells * N_surfaces), providing
+        massive speedup for repeated calls with different surface radiation.
+        
+        Must call compute_c2s_matrix() first.
+        
+        Args:
+            surf_outgoing: Array of surface outgoing radiation (W/m²)
+            progress_report: Print progress messages
+        """
+        if not self._c2s_matrix_cached:
+            raise RuntimeError("C2S-VF matrix not computed. Call compute_c2s_matrix() first.")
+        
+        n_surfaces = len(surf_outgoing)
+        
+        # Allocate or resize surface outgoing field if needed
+        if self._surf_out_field is None or self._surf_out_max_size < n_surfaces:
+            self._surf_out_field = ti.field(dtype=ti.f32, shape=(n_surfaces,))
+            self._surf_out_max_size = n_surfaces
+        
+        # Copy outgoing radiation to Taichi field
+        self._surf_out_field.from_numpy(surf_outgoing.astype(np.float32))
+        
+        # Clear reflected flux field
+        self._clear_reflected_flux()
+        
+        # Use sparse matrix-vector multiply
+        self._apply_c2s_matrix_kernel(self._c2s_nnz)
+        
+        if progress_report:
+            print(f"Computed volumetric reflected flux using cached C2S-VF ({self._c2s_nnz:,} entries)")
+    
+    @ti.kernel
+    def _apply_c2s_matrix_kernel(self, c2s_nnz: ti.i32):
+        """
+        Apply C2S-VF matrix to compute reflected flux.
+        
+        flux[cell] = Σ (vf[cell, surf] * outgoing[surf])
+        
+        Uses atomic operations for parallel accumulation.
+        """
+        for idx in range(c2s_nnz):
+            cell_idx = self._c2s_cell_idx[idx]
+            surf_idx = self._c2s_surf_idx[idx]
+            vf = self._c2s_vf[idx]
+            
+            outgoing = self._surf_out_field[surf_idx]
+            
+            if outgoing > 0.1:  # Threshold for negligible contributions
+                # Reconstruct 3D indices from linear index
+                # cell_idx = i * (ny * nz) + j * nz + k
+                tmp = cell_idx
+                k = tmp % self.nz
+                tmp //= self.nz
+                j = tmp % self.ny
+                i = tmp // self.ny
+                
+                ti.atomic_add(self.swflux_reflected_vol[i, j, k], outgoing * vf)
+    
+    def invalidate_c2s_cache(self):
+        """
+        Invalidate the cached C2S-VF matrix.
+        
+        Call this if geometry (buildings, terrain, vegetation) changes.
+        """
+        self._c2s_matrix_cached = False
+        self._c2s_nnz = 0
+    
+    @property
+    def c2s_matrix_cached(self) -> bool:
+        """Check if C2S-VF matrix is currently cached."""
+        return self._c2s_matrix_cached
+    
+    @property
+    def c2s_matrix_entries(self) -> int:
+        """Get number of non-zero entries in cached C2S-VF matrix."""
+        return self._c2s_nnz
+    
+    def compute_swflux_vol_with_reflections_cached(
+        self,
+        sw_direct: float,
+        sw_diffuse: float,
+        cos_zenith: float,
+        sun_direction: Tuple[float, float, float],
+        surf_outgoing: np.ndarray,
+        lad=None
+    ):
+        """
+        Compute volumetric shortwave flux with reflections using cached matrix.
+        
+        This is the fast path for multi-timestep simulations. Must call
+        compute_c2s_matrix() once before using this method.
+        
+        Args:
+            sw_direct: Direct normal irradiance (W/m²)
+            sw_diffuse: Diffuse horizontal irradiance (W/m²)
+            cos_zenith: Cosine of solar zenith angle
+            sun_direction: Unit vector toward sun (x, y, z)
+            surf_outgoing: Surface outgoing radiation array (W/m²)
+            lad: Optional LAD field for canopy attenuation
+        """
+        # Compute direct + diffuse
+        self.compute_swflux_vol(sw_direct, sw_diffuse, cos_zenith, sun_direction, lad)
+        
+        # Compute reflected using cached matrix
+        self.compute_reflected_flux_vol_cached(surf_outgoing)
+        self._add_reflected_to_total()
+
+    # =========================================================================
+    # Terrain-Following Cell-to-Surface VF (T2S-VF) Matrix Caching
+    # =========================================================================
+    # These methods pre-compute view factors from terrain-following evaluation
+    # cells (at volumetric_height above ground) to surfaces.
+    # This makes cumulative volumetric reflections O(nnz) instead of O(N*M).
+    
+    def compute_t2s_matrix(
+        self,
+        surfaces,
+        min_vf_threshold: float = 1e-6,
+        progress_report: bool = False
+    ):
+        """
+        Pre-compute Terrain-to-Surface View Factor matrix for fast reflections.
+        
+        This computes view factors only for cells at the terrain-following
+        extraction height (O(nx*ny) cells), not the full 3D volume.
+        
+        Requires init_cumulative_accumulation() to be called first to set
+        ground_k and height_offset_k.
+        
+        Args:
+            surfaces: Surfaces object with center, normal, area fields
+            min_vf_threshold: Minimum view factor to store (sparsity threshold)
+            progress_report: Print progress messages
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Must call init_cumulative_accumulation() first.")
+        
+        # Check if we already have a valid cache for this height offset
+        if (self._t2s_matrix_cached and 
+            self._t2s_height_offset_k == self._height_offset_k):
+            if progress_report:
+                print(f"T2S-VF matrix already cached for height_offset={self._height_offset_k}, skipping.")
+            return
+        
+        n_surfaces = surfaces.n_surfaces[None]
+        n_terrain_cells = self.nx * self.ny
+        
+        if progress_report:
+            print(f"Pre-computing T2S-VF matrix: {n_terrain_cells:,} terrain cells × {n_surfaces:,} surfaces")
+            print(f"  Height offset: {self._height_offset_k} cells above ground")
+        
+        # Allocate sparse COO arrays if not already done
+        if self._t2s_ij_idx is None:
+            self._t2s_ij_idx = ti.field(dtype=ti.i32, shape=(self._max_t2s_entries,))
+            self._t2s_surf_idx = ti.field(dtype=ti.i32, shape=(self._max_t2s_entries,))
+            self._t2s_vf = ti.field(dtype=ti.f32, shape=(self._max_t2s_entries,))
+            self._t2s_count = ti.field(dtype=ti.i32, shape=())
+        
+        has_lad = 1 if self.domain.lad is not None else 0
+        
+        # Clear count and compute the matrix
+        self._t2s_count[None] = 0
+        self._compute_t2s_matrix_kernel(
+            n_surfaces,
+            surfaces.center,
+            surfaces.normal,
+            surfaces.area,
+            self.domain.is_solid,
+            self.domain.lad,
+            has_lad,
+            self._height_offset_k,
+            min_vf_threshold
+        )
+        
+        computed_nnz = int(self._t2s_count[None])
+        if computed_nnz > self._max_t2s_entries:
+            print(f"Warning: T2S-VF matrix truncated! {computed_nnz:,} > {self._max_t2s_entries:,}")
+            print("  Consider increasing _max_t2s_entries.")
+            self._t2s_nnz = self._max_t2s_entries
+        else:
+            self._t2s_nnz = computed_nnz
+        
+        self._t2s_matrix_cached = True
+        self._t2s_height_offset_k = self._height_offset_k
+        
+        sparsity_pct = self._t2s_nnz / (n_terrain_cells * n_surfaces) * 100 if n_surfaces > 0 else 0
+        memory_mb = self._t2s_nnz * 12 / 1e6  # 12 bytes per entry (2 int32 + 1 float32)
+        if progress_report:
+            print(f"  T2S-VF matrix computed: {self._t2s_nnz:,} non-zero entries ({memory_mb:.1f} MB)")
+            print(f"  Sparsity: {sparsity_pct:.4f}% of full matrix")
+            speedup = (n_terrain_cells * n_surfaces) / max(1, self._t2s_nnz)
+            print(f"  Speedup factor: ~{speedup:.0f}x per sky patch")
+    
+    @ti.kernel
+    def _compute_t2s_matrix_kernel(
+        self,
+        n_surfaces: ti.i32,
+        surf_center: ti.template(),
+        surf_normal: ti.template(),
+        surf_area: ti.template(),
+        is_solid: ti.template(),
+        lad: ti.template(),
+        has_lad: ti.i32,
+        height_offset: ti.i32,
+        min_threshold: ti.f32
+    ):
+        """
+        Compute T2S-VF matrix entries for terrain-following cells only.
+        
+        For each terrain cell at (i, j, ground_k[i,j] + height_offset),
+        compute view factors to all visible surfaces.
+        """
+        max_dist_sq = 900.0  # 30m max distance (same as terrain kernel)
+        
+        for i, j in ti.ndrange(self.nx, self.ny):
+            gk = self._ground_k[i, j]
+            if gk < 0:
+                continue  # No valid ground
+            
+            k = gk + height_offset
+            if k < 0 or k >= self.nz:
+                continue
+            
+            # Skip solid cells
+            if is_solid[i, j, k] == 1:
+                continue
+            
+            ij_idx = i * self.ny + j
+            cell_x = (ti.cast(i, ti.f32) + 0.5) * self.dx
+            cell_y = (ti.cast(j, ti.f32) + 0.5) * self.dy
+            cell_z = (ti.cast(k, ti.f32) + 0.5) * self.dz
+            
+            for surf_idx in range(n_surfaces):
+                surf_x = surf_center[surf_idx][0]
+                surf_y = surf_center[surf_idx][1]
+                surf_z = surf_center[surf_idx][2]
+                surf_nx = surf_normal[surf_idx][0]
+                surf_ny = surf_normal[surf_idx][1]
+                surf_nz = surf_normal[surf_idx][2]
+                area = surf_area[surf_idx]
+                
+                # Distance to surface
+                dx = cell_x - surf_x
+                dy = cell_y - surf_y
+                dz = cell_z - surf_z
+                dist_sq = dx*dx + dy*dy + dz*dz
+                
+                if dist_sq > 0.01 and dist_sq < max_dist_sq:
+                    dist = ti.sqrt(dist_sq)
+                    
+                    # Direction from surface to cell (normalized)
+                    dir_x = dx / dist
+                    dir_y = dy / dist
+                    dir_z = dz / dist
+                    
+                    # Cosine of angle between normal and direction
+                    cos_angle = dir_x * surf_nx + dir_y * surf_ny + dir_z * surf_nz
+                    
+                    if cos_angle > 0.0:  # Surface faces the cell
+                        # Get transmissivity
+                        trans = self._trace_transmissivity_to_surface(
+                            i, j, k, surf_x, surf_y, surf_z,
+                            surf_nx, surf_ny, surf_nz,
+                            is_solid, lad, has_lad
+                        )
+                        
+                        if trans > 0.0:
+                            # View factor: (A * cos_θ) / (π * d²) * 0.25 for sphere
+                            vf = area * cos_angle / (PI * dist_sq) * trans * 0.25
+                            
+                            if vf > min_threshold:
+                                idx = ti.atomic_add(self._t2s_count[None], 1)
+                                if idx < self._max_t2s_entries:
+                                    self._t2s_ij_idx[idx] = ij_idx
+                                    self._t2s_surf_idx[idx] = surf_idx
+                                    self._t2s_vf[idx] = vf
+    
+    def compute_reflected_flux_terrain_cached(
+        self,
+        surf_outgoing: np.ndarray
+    ):
+        """
+        Compute reflected flux at terrain-following level using cached T2S matrix.
+        
+        This is O(nnz) instead of O(N_cells * N_surfaces), providing
+        massive speedup for cumulative simulations with multiple sky patches.
+        
+        Requires:
+        1. init_cumulative_accumulation() called first
+        2. compute_t2s_matrix() called to pre-compute view factors
+        
+        Args:
+            surf_outgoing: Array of surface outgoing radiation (W/m²)
+        """
+        if not self._t2s_matrix_cached:
+            raise RuntimeError("T2S-VF matrix not computed. Call compute_t2s_matrix() first.")
+        
+        n_surfaces = len(surf_outgoing)
+        
+        # Allocate or resize surface outgoing field if needed
+        if self._surf_out_field is None or self._surf_out_max_size < n_surfaces:
+            self._surf_out_field = ti.field(dtype=ti.f32, shape=(n_surfaces,))
+            self._surf_out_max_size = n_surfaces
+        
+        # Copy outgoing radiation to Taichi field
+        self._surf_out_field.from_numpy(surf_outgoing.astype(np.float32))
+        
+        # Clear reflected flux field
+        self._clear_reflected_flux()
+        
+        # Use sparse matrix-vector multiply
+        self._apply_t2s_matrix_kernel(self._t2s_nnz, self._height_offset_k)
+    
+    @ti.kernel
+    def _apply_t2s_matrix_kernel(self, t2s_nnz: ti.i32, height_offset: ti.i32):
+        """
+        Apply T2S-VF matrix to compute reflected flux at terrain level.
+        
+        flux[i,j,k_terrain] = Σ (vf[ij, surf] * outgoing[surf])
+        
+        Uses atomic operations for parallel accumulation.
+        """
+        for idx in range(t2s_nnz):
+            ij_idx = self._t2s_ij_idx[idx]
+            surf_idx = self._t2s_surf_idx[idx]
+            vf = self._t2s_vf[idx]
+            
+            outgoing = self._surf_out_field[surf_idx]
+            
+            if outgoing > 0.1:  # Threshold for negligible contributions
+                # Reconstruct indices from ij_idx
+                j = ij_idx % self.ny
+                i = ij_idx // self.ny
+                
+                # Get terrain-following k level
+                gk = self._ground_k[i, j]
+                if gk >= 0:
+                    k = gk + height_offset
+                    if k >= 0 and k < self.nz:
+                        ti.atomic_add(self.swflux_reflected_vol[i, j, k], outgoing * vf)
+    
+    def invalidate_t2s_cache(self):
+        """
+        Invalidate the cached T2S-VF matrix.
+        
+        Call this if geometry or volumetric_height changes.
+        """
+        self._t2s_matrix_cached = False
+        self._t2s_nnz = 0
+        self._t2s_height_offset_k = -1
+    
+    @property
+    def t2s_matrix_cached(self) -> bool:
+        """Check if T2S-VF matrix is currently cached."""
+        return self._t2s_matrix_cached
+    
+    @property
+    def t2s_matrix_entries(self) -> int:
+        """Get number of non-zero entries in cached T2S-VF matrix."""
+        return self._t2s_nnz
+
+    # =========================================================================
+    # Cumulative Terrain-Following Accumulation (GPU-Optimized)
+    # =========================================================================
+    # These methods enable efficient cumulative volumetric simulation by
+    # accumulating terrain-following slices directly on GPU, avoiding the
+    # expensive GPU-to-CPU transfer of full 3D arrays for each timestep/patch.
+    
+    def init_cumulative_accumulation(
+        self,
+        ground_k: np.ndarray,
+        height_offset_k: int,
+        is_solid: np.ndarray
+    ):
+        """
+        Initialize GPU-side cumulative terrain-following accumulation.
+        
+        Must be called before using accumulate_terrain_following_slice_gpu().
+        
+        Args:
+            ground_k: 2D array (nx, ny) of ground k-levels. -1 means no valid ground.
+            height_offset_k: Number of cells above ground for extraction.
+            is_solid: 3D array (nx, ny, nz) of solid flags.
+        """
+        # Copy ground_k to GPU
+        self._ground_k.from_numpy(ground_k.astype(np.int32))
+        self._height_offset_k = height_offset_k
+        
+        # Clear cumulative map
+        self._clear_cumulative_map()
+        
+        self._cumulative_initialized = True
+    
+    @ti.kernel
+    def _clear_cumulative_map(self):
+        """Clear the cumulative terrain-following map."""
+        for i, j in ti.ndrange(self.nx, self.ny):
+            self._cumulative_map[i, j] = 0.0
+    
+    @ti.kernel
+    def _accumulate_terrain_slice_kernel(
+        self,
+        height_offset_k: ti.i32,
+        weight: ti.f64,
+        is_solid: ti.template()
+    ):
+        """
+        Accumulate terrain-following slice from swflux_vol directly on GPU.
+        
+        For each (i,j), extracts swflux_vol[i,j,k_extract] * weight
+        where k_extract = ground_k[i,j] + height_offset_k.
+        
+        Args:
+            height_offset_k: Number of cells above ground for extraction.
+            weight: Multiplier for values before accumulating (e.g., time_step_hours).
+            is_solid: 3D solid field for masking.
+        """
+        for i, j in ti.ndrange(self.nx, self.ny):
+            gk = self._ground_k[i, j]
+            if gk < 0:
+                continue  # No valid ground
+            
+            k_extract = gk + height_offset_k
+            if k_extract >= self.nz:
+                continue  # Out of bounds
+            
+            # Skip if extraction point is inside solid
+            if is_solid[i, j, k_extract] == 1:
+                continue
+            
+            # Accumulate the flux value (atomic add for thread safety)
+            flux_val = ti.cast(self.swflux_vol[i, j, k_extract], ti.f64)
+            ti.atomic_add(self._cumulative_map[i, j], flux_val * weight)
+    
+    @ti.kernel
+    def _accumulate_terrain_slice_from_svf_kernel(
+        self,
+        height_offset_k: ti.i32,
+        weight: ti.f64,
+        is_solid: ti.template()
+    ):
+        """
+        Accumulate terrain-following slice from skyvf_vol directly on GPU.
+        
+        For each (i,j), extracts skyvf_vol[i,j,k_extract] * weight
+        where k_extract = ground_k[i,j] + height_offset_k.
+        
+        Args:
+            height_offset_k: Number of cells above ground for extraction.
+            weight: Multiplier (e.g., total_dhi for diffuse contribution).
+            is_solid: 3D solid field for masking.
+        """
+        for i, j in ti.ndrange(self.nx, self.ny):
+            gk = self._ground_k[i, j]
+            if gk < 0:
+                continue
+            
+            k_extract = gk + height_offset_k
+            if k_extract >= self.nz:
+                continue
+            
+            if is_solid[i, j, k_extract] == 1:
+                continue
+            
+            svf_val = ti.cast(self.skyvf_vol[i, j, k_extract], ti.f64)
+            ti.atomic_add(self._cumulative_map[i, j], svf_val * weight)
+    
+    def accumulate_terrain_following_slice_gpu(
+        self,
+        weight: float = 1.0
+    ):
+        """
+        Accumulate current swflux_vol terrain-following slice to cumulative map on GPU.
+        
+        This is the fast path for cumulative simulations. Must call 
+        init_cumulative_accumulation() first.
+        
+        Args:
+            weight: Multiplier for values (e.g., time_step_hours for Wh conversion).
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Cumulative accumulation not initialized. "
+                             "Call init_cumulative_accumulation() first.")
+        
+        self._accumulate_terrain_slice_kernel(
+            self._height_offset_k,
+            float(weight),
+            self.domain.is_solid
+        )
+    
+    def accumulate_svf_diffuse_gpu(
+        self,
+        total_dhi: float
+    ):
+        """
+        Accumulate diffuse contribution using SVF field directly on GPU.
+        
+        Args:
+            total_dhi: Total cumulative diffuse horizontal irradiance (Wh/m²).
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Cumulative accumulation not initialized. "
+                             "Call init_cumulative_accumulation() first.")
+        
+        self._accumulate_terrain_slice_from_svf_kernel(
+            self._height_offset_k,
+            float(total_dhi),
+            self.domain.is_solid
+        )
+    
+    def get_cumulative_map(self) -> np.ndarray:
+        """
+        Get the accumulated terrain-following cumulative map.
+        
+        Returns:
+            2D numpy array (nx, ny) of cumulative irradiance values.
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Cumulative accumulation not initialized.")
+        
+        return self._cumulative_map.to_numpy()
+    
+    def finalize_cumulative_map(self, apply_nan_mask: bool = True) -> np.ndarray:
+        """
+        Get final cumulative map with optional NaN masking for invalid cells.
+        
+        Args:
+            apply_nan_mask: If True, set cells with no valid ground or inside
+                           solid to NaN.
+        
+        Returns:
+            2D numpy array (nx, ny) of cumulative irradiance values.
+        """
+        if not self._cumulative_initialized:
+            raise RuntimeError("Cumulative accumulation not initialized.")
+        
+        result = self._cumulative_map.to_numpy()
+        
+        if apply_nan_mask:
+            ground_k_np = self._ground_k.to_numpy()
+            is_solid_np = self.domain.is_solid.to_numpy()
+            
+            for i in range(self.nx):
+                for j in range(self.ny):
+                    gk = ground_k_np[i, j]
+                    if gk < 0:
+                        result[i, j] = np.nan
+                        continue
+                    k_extract = gk + self._height_offset_k
+                    if k_extract >= self.nz:
+                        result[i, j] = np.nan
+                        continue
+                    if is_solid_np[i, j, k_extract] == 1:
+                        result[i, j] = np.nan
+        
+        return result
+    
+    def reset_cumulative_accumulation(self):
+        """Reset the cumulative map to zero without reinitializing ground_k."""
+        if self._cumulative_initialized:
+            self._clear_cumulative_map()