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

voxcity/simulator/solar/__init__.py

@@ -64,3 +64,16 @@ from .integration import (  # noqa: F401
     save_irradiance_mesh,
     load_irradiance_mesh,
 )
+
+# Computation mask utilities (re-export from simulator_gpu for convenience)
+try:
+    from voxcity.simulator_gpu.solar.mask import (  # noqa: F401
+        create_computation_mask,
+        draw_computation_mask,
+        get_mask_from_drawing,
+        visualize_computation_mask,
+        get_mask_info,
+    )
+except ImportError:
+    # simulator_gpu may not be installed
+    pass

voxcity/simulator_gpu/__init__.py

@@ -1,115 +1,90 @@
-"""simulator_gpu: GPU-accelerated simulation modules using Taichi.
+"""simulator_gpu: GPU-accelerated urban simulation using Taichi.
 
-Compatibility goal:
-    Allow the common VoxCity pattern to work without code changes beyond the
-    import alias:
+This package provides GPU-accelerated implementations for:
+- Solar radiation simulation (direct, diffuse, cumulative)
+- View analysis (green view index, sky view factor)
+- Landmark visibility analysis
 
-        import simulator_gpu as simulator
+Submodules:
+    solar: Solar radiation calculations
+    visibility: View and visibility analysis
 
-    by flattening a VoxCity-like public namespace (view/visibility/solar/utils).
+Example:
+    from voxcity.simulator_gpu import solar, visibility
+    
+    # Solar radiation
+    irradiance = solar.get_global_solar_irradiance_using_epw(voxcity, ...)
+    
+    # View analysis
+    gvi = visibility.get_view_index(voxcity, mode='green')
 """
 
 import os
 
-# Disable Numba caching to prevent stale cache issues when module paths change.
-# This avoids "ModuleNotFoundError: No module named 'simulator_gpu'" errors
-# that can occur when Numba tries to load cached functions with old module paths.
-os.environ.setdefault("NUMBA_CACHE_DIR", "")  # Disable disk caching
-os.environ.setdefault("NUMBA_DISABLE_JIT", "0")  # Keep JIT enabled for performance
-
-# Import Taichi initialization utilities first
-from .init_taichi import (  # noqa: F401
-    init_taichi,
-    ensure_initialized,
-    is_initialized,
-)
-
-# Check if Taichi is available
-try:
-    import taichi as ti
-    _TAICHI_AVAILABLE = True
-except ImportError:
-    _TAICHI_AVAILABLE = False
+# Disable Numba caching to prevent stale cache issues
+os.environ.setdefault("NUMBA_CACHE_DIR", "")
+os.environ.setdefault("NUMBA_DISABLE_JIT", "0")
 
-# VoxCity-style flattening
-from .view import *  # noqa: F401,F403
-from .solar import *  # noqa: F401,F403
-from .utils import *  # noqa: F401,F403
+# Taichi initialization
+from .init_taichi import init_taichi, ensure_initialized, is_initialized
 
-# Export submodules for explicit access
-from . import solar  # noqa: F401
-from . import visibility  # noqa: F401
-from . import view  # noqa: F401
-from . import utils  # noqa: F401
-from . import common  # noqa: F401
-
-# VoxCity-flattened module names that some code expects to exist on the toplevel
-from . import sky  # noqa: F401
-from . import kernels  # noqa: F401
-from . import radiation  # noqa: F401
-from . import temporal  # noqa: F401
-from . import integration  # noqa: F401
-
-# Commonly re-exported VoxCity solar helpers
-from .kernels import compute_direct_solar_irradiance_map_binary  # noqa: F401
-from .radiation import compute_solar_irradiance_for_all_faces  # noqa: F401
-
-# Backward compatibility: some code treats `simulator.view` as `simulator.visibility`
-# (VoxCity provides `view.py` wrapper; we also provide that module).
-
-# Export shared modules (kept; extra symbols are fine)
-from .core import (  # noqa: F401
+# Core utilities
+from .core import (
     Vector3, Point3,
     PI, TWO_PI, DEG_TO_RAD, RAD_TO_DEG,
     SOLAR_CONSTANT, EXT_COEF,
 )
-from .domain import Domain, IUP, IDOWN, INORTH, ISOUTH, IEAST, IWEST  # noqa: F401
-
 
-def clear_numba_cache():
-    """Clear Numba's compiled function cache to resolve stale cache issues.
-    
-    Call this function if you encounter errors like:
-        ModuleNotFoundError: No module named 'simulator_gpu'
-    
-    After calling this function, restart your Python kernel/interpreter.
-    """
-    import shutil
-    import glob
-    from pathlib import Path
-    
-    cleared = []
-    
-    # Clear .nbc and .nbi files in the package directory
-    package_dir = Path(__file__).parent
-    for pattern in ["**/*.nbc", "**/*.nbi"]:
-        for cache_file in package_dir.glob(pattern):
-            try:
-                cache_file.unlink()
-                cleared.append(str(cache_file))
-            except Exception:
-                pass
-    
-    # Clear __pycache__ directories
-    for pycache in package_dir.glob("**/__pycache__"):
-        try:
-            shutil.rmtree(pycache)
-            cleared.append(str(pycache))
-        except Exception:
-            pass
-    
-    # Try to clear user's .numba_cache if it exists
-    home = Path.home()
-    numba_cache = home / ".numba_cache"
-    if numba_cache.exists():
-        try:
-            shutil.rmtree(numba_cache)
-            cleared.append(str(numba_cache))
-        except Exception:
-            pass
-    
-    print(f"Cleared {len(cleared)} cache items. Please restart your Python kernel.")
-    return cleared
+# Domain (shared between solar and visibility)
+from .domain import Domain, Surfaces, extract_surfaces_from_domain
+from .domain import IUP, IDOWN, INORTH, ISOUTH, IEAST, IWEST
+
+# Submodules
+from . import solar
+from . import visibility
+
+# Convenience imports from solar
+from .solar import (
+    get_global_solar_irradiance_using_epw,
+    get_building_global_solar_irradiance_using_epw,
+    get_direct_solar_irradiance_map,
+    get_diffuse_solar_irradiance_map,
+    get_global_solar_irradiance_map,
+)
 
+# Convenience imports from visibility
+from .visibility import (
+    get_view_index,
+    get_sky_view_factor_map,
+    get_surface_view_factor,
+    get_landmark_visibility_map,
+    get_surface_landmark_visibility,
+)
 
 __version__ = "0.1.0"
+
+__all__ = [
+    # Initialization
+    'init_taichi', 'ensure_initialized', 'is_initialized',
+    # Core
+    'Vector3', 'Point3',
+    'PI', 'TWO_PI', 'DEG_TO_RAD', 'RAD_TO_DEG',
+    'SOLAR_CONSTANT', 'EXT_COEF',
+    # Domain
+    'Domain', 'Surfaces', 'extract_surfaces_from_domain',
+    'IUP', 'IDOWN', 'INORTH', 'ISOUTH', 'IEAST', 'IWEST',
+    # Submodules
+    'solar', 'visibility',
+    # Solar (convenience)
+    'get_global_solar_irradiance_using_epw',
+    'get_building_global_solar_irradiance_using_epw',
+    'get_direct_solar_irradiance_map',
+    'get_diffuse_solar_irradiance_map',
+    'get_global_solar_irradiance_map',
+    # Visibility (convenience)
+    'get_view_index',
+    'get_sky_view_factor_map',
+    'get_surface_view_factor',
+    'get_landmark_visibility_map',
+    'get_surface_landmark_visibility',
+]

voxcity/simulator_gpu/domain.py

@@ -1,262 +1,36 @@
 """
 Shared domain definition for simulator_gpu.
 
-Represents the 3D computational domain with:
-- Grid cells (dx, dy, dz spacing)
-- Topography (terrain height)
-- Building geometry (3D obstacles)
-- Plant canopy (Leaf Area Density - LAD)
-- Tree mask for view analysis
+This module re-exports the Domain class from solar.domain for backward compatibility.
+The main implementation is in simulator_gpu.solar.domain which includes:
+- Domain class with full grid, terrain, building, and vegetation support
+- Surfaces class for radiation calculations
+- Surface extraction utilities
 """
 
-import taichi as ti
-import numpy as np
-from typing import Tuple, Optional, Union
-from .core import Vector3, Point3, EXT_COEF
-from .init_taichi import ensure_initialized
+# Re-export from solar.domain (the main implementation)
+from .solar.domain import (
+    Domain,
+    Surfaces,
+    extract_surfaces_from_domain,
+    IUP,
+    IDOWN,
+    INORTH,
+    ISOUTH,
+    IEAST,
+    IWEST,
+    DIR_NORMALS,
+)
 
-
-# Surface direction indices (matching PALM convention)
-IUP = 0      # Upward facing (horizontal roof/ground)
-IDOWN = 1    # Downward facing
-INORTH = 2   # North facing (positive y)
-ISOUTH = 3   # South facing (negative y)
-IEAST = 4    # East facing (positive x)
-IWEST = 5    # West facing (negative x)
-
-# Direction normal vectors (x, y, z)
-DIR_NORMALS = {
-    IUP: (0.0, 0.0, 1.0),
-    IDOWN: (0.0, 0.0, -1.0),
-    INORTH: (0.0, 1.0, 0.0),
-    ISOUTH: (0.0, -1.0, 0.0),
-    IEAST: (1.0, 0.0, 0.0),
-    IWEST: (-1.0, 0.0, 0.0),
-}
-
-
-@ti.data_oriented
-class Domain:
-    """
-    3D computational domain for simulation.
-    
-    The domain uses a regular grid with:
-    - x: West to East
-    - y: South to North  
-    - z: Ground to Sky
-    
-    Attributes:
-        nx, ny, nz: Number of grid cells in each direction
-        dx, dy, dz: Grid spacing in meters
-        origin: (x, y, z) coordinates of domain origin
-    """
-    
-    def __init__(
-        self,
-        nx: int,
-        ny: int, 
-        nz: int,
-        dx: float = 1.0,
-        dy: float = 1.0,
-        dz: float = 1.0,
-        origin: Tuple[float, float, float] = (0.0, 0.0, 0.0),
-        origin_lat: Optional[float] = None,
-        origin_lon: Optional[float] = None
-    ):
-        """
-        Initialize the domain.
-        
-        Args:
-            nx, ny, nz: Grid dimensions
-            dx, dy, dz: Grid spacing (m)
-            origin: Domain origin coordinates
-            origin_lat: Latitude for solar calculations (degrees)
-            origin_lon: Longitude for solar calculations (degrees)
-        """
-        # Ensure Taichi is initialized before creating any fields
-        ensure_initialized()
-        
-        self.nx = nx
-        self.ny = ny
-        self.nz = nz
-        self.dx = dx
-        self.dy = dy
-        self.dz = dz
-        self.origin = origin
-        self.origin_lat = origin_lat if origin_lat is not None else 0.0
-        self.origin_lon = origin_lon if origin_lon is not None else 0.0
-        
-        # Domain bounds
-        self.x_min = origin[0]
-        self.x_max = origin[0] + nx * dx
-        self.y_min = origin[1]
-        self.y_max = origin[1] + ny * dy
-        self.z_min = origin[2]
-        self.z_max = origin[2] + nz * dz
-        
-        # Grid cell volume
-        self.cell_volume = dx * dy * dz
-        
-        # Topography: terrain height at each (i, j) column
-        self.topo_top = ti.field(dtype=ti.i32, shape=(nx, ny))
-        
-        # Building mask: 1 if cell is solid (building), 0 if air
-        self.is_solid = ti.field(dtype=ti.i32, shape=(nx, ny, nz))
-        
-        # Tree mask: 1 if cell is tree canopy, 0 otherwise
-        self.is_tree = ti.field(dtype=ti.i32, shape=(nx, ny, nz))
-        
-        # Leaf Area Density (m^2/m^3) for plant canopy
-        self.lad = ti.field(dtype=ti.f32, shape=(nx, ny, nz))
-        
-        # Plant canopy top index for each column
-        self.plant_top = ti.field(dtype=ti.i32, shape=(nx, ny))
-        
-        # Surface count
-        self.n_surfaces = ti.field(dtype=ti.i32, shape=())
-        
-        # Initialize arrays
-        self._init_arrays()
-        
-    @ti.kernel
-    def _init_arrays(self):
-        """Initialize all arrays to default values."""
-        for i, j in self.topo_top:
-            self.topo_top[i, j] = 0
-            self.plant_top[i, j] = 0
-        
-        for i, j, k in self.is_solid:
-            self.is_solid[i, j, k] = 0
-            self.is_tree[i, j, k] = 0
-            self.lad[i, j, k] = 0.0
-    
-    def set_flat_terrain(self, height: float = 0.0):
-        """Set flat terrain at given height."""
-        k_top = int(height / self.dz)
-        self._set_flat_terrain_kernel(k_top)
-    
-    def initialize_terrain(self, height: float = 0.0):
-        """Alias for set_flat_terrain."""
-        self.set_flat_terrain(height)
-    
-    @ti.kernel
-    def _set_flat_terrain_kernel(self, k_top: ti.i32):
-        for i, j in self.topo_top:
-            self.topo_top[i, j] = k_top
-            for k in range(k_top + 1):
-                self.is_solid[i, j, k] = 1
-    
-    def set_terrain_from_array(self, terrain_height: np.ndarray):
-        """
-        Set terrain from 2D numpy array of heights.
-        
-        Args:
-            terrain_height: 2D array (nx, ny) of terrain heights in meters
-        """
-        terrain_k = (terrain_height / self.dz).astype(np.int32)
-        self._set_terrain_kernel(terrain_k)
-    
-    @ti.kernel
-    def _set_terrain_kernel(self, terrain_k: ti.types.ndarray()):
-        for i, j in self.topo_top:
-            k_top = terrain_k[i, j]
-            self.topo_top[i, j] = k_top
-            for k in range(self.nz):
-                if k <= k_top:
-                    self.is_solid[i, j, k] = 1
-                else:
-                    self.is_solid[i, j, k] = 0
-    
-    def add_building(
-        self,
-        x_range: Optional[Tuple[int, int]] = None,
-        y_range: Optional[Tuple[int, int]] = None,
-        z_range: Optional[Tuple[int, int]] = None,
-        *,
-        x_start: Optional[int] = None,
-        x_end: Optional[int] = None,
-        y_start: Optional[int] = None,
-        y_end: Optional[int] = None,
-        height: Optional[float] = None
-    ):
-        """
-        Add a rectangular building to the domain.
-        """
-        # Handle convenience parameters
-        if x_start is not None and x_end is not None:
-            x_range = (x_start, x_end)
-        if y_start is not None and y_end is not None:
-            y_range = (y_start, y_end)
-        if height is not None and z_range is None:
-            k_top = int(height / self.dz) + 1
-            z_range = (0, k_top)
-        
-        if x_range is None or y_range is None or z_range is None:
-            raise ValueError("Must provide either range tuples or individual parameters")
-        
-        self._add_building_kernel(x_range[0], x_range[1], y_range[0], y_range[1], z_range[0], z_range[1])
-    
-    @ti.kernel
-    def _add_building_kernel(self, i_min: ti.i32, i_max: ti.i32, j_min: ti.i32, j_max: ti.i32, k_min: ti.i32, k_max: ti.i32):
-        for i, j, k in ti.ndrange((i_min, i_max), (j_min, j_max), (k_min, k_max)):
-            self.is_solid[i, j, k] = 1
-    
-    def add_tree(
-        self,
-        x_range: Tuple[int, int],
-        y_range: Tuple[int, int],
-        z_range: Tuple[int, int],
-        lad_value: float = 1.0
-    ):
-        """
-        Add a tree canopy region to the domain.
-        
-        Args:
-            x_range, y_range, z_range: Grid index ranges
-            lad_value: Leaf Area Density value
-        """
-        self._add_tree_kernel(x_range[0], x_range[1], y_range[0], y_range[1], z_range[0], z_range[1], lad_value)
-    
-    @ti.kernel
-    def _add_tree_kernel(self, i_min: ti.i32, i_max: ti.i32, j_min: ti.i32, j_max: ti.i32, k_min: ti.i32, k_max: ti.i32, lad: ti.f32):
-        for i, j, k in ti.ndrange((i_min, i_max), (j_min, j_max), (k_min, k_max)):
-            self.is_tree[i, j, k] = 1
-            self.lad[i, j, k] = lad
-    
-    def set_from_voxel_data(self, voxel_data: np.ndarray, tree_code: int = -2, solid_codes: Optional[list] = None):
-        """
-        Set domain from a 3D voxel data array.
-        
-        Args:
-            voxel_data: 3D numpy array with voxel class codes
-            tree_code: Class code for trees (default -2)
-            solid_codes: List of codes that are solid (default: all non-zero except tree_code)
-        """
-        if solid_codes is None:
-            # All non-zero codes except tree are solid
-            solid_codes = []
-        
-        self._set_from_voxel_data_kernel(voxel_data, tree_code)
-    
-    @ti.kernel
-    def _set_from_voxel_data_kernel(self, voxel_data: ti.types.ndarray(), tree_code: ti.i32):
-        for i, j, k in ti.ndrange(self.nx, self.ny, self.nz):
-            val = voxel_data[i, j, k]
-            if val == tree_code:
-                self.is_tree[i, j, k] = 1
-                self.is_solid[i, j, k] = 0
-            elif val != 0:
-                self.is_solid[i, j, k] = 1
-                self.is_tree[i, j, k] = 0
-            else:
-                self.is_solid[i, j, k] = 0
-                self.is_tree[i, j, k] = 0
-    
-    def get_max_dist(self) -> float:
-        """Get maximum ray distance (domain diagonal)."""
-        import math
-        return math.sqrt(
-            (self.nx * self.dx)**2 + 
-            (self.ny * self.dy)**2 + 
-            (self.nz * self.dz)**2
-        )
+__all__ = [
+    'Domain',
+    'Surfaces',
+    'extract_surfaces_from_domain',
+    'IUP',
+    'IDOWN',
+    'INORTH',
+    'ISOUTH',
+    'IEAST',
+    'IWEST',
+    'DIR_NORMALS',
+]

voxcity/simulator_gpu/raytracing.py

@@ -466,6 +466,159 @@ def ray_canopy_absorption(
     return transmissivity, total_lad_path
 
 
+@ti.func
+def ray_point_to_point_transmissivity(
+    pos_from: Vector3,
+    pos_to: Vector3,
+    lad: ti.template(),
+    is_solid: ti.template(),
+    nx: ti.i32,
+    ny: ti.i32,
+    nz: ti.i32,
+    dx: ti.f32,
+    dy: ti.f32,
+    dz: ti.f32,
+    ext_coef: ti.f32
+):
+    """
+    Compute transmissivity of radiation between two points through canopy.
+    
+    This is used for surface-to-surface reflections where reflected radiation
+    must pass through any intervening vegetation.
+    
+    Args:
+        pos_from: Start position (emitting surface center)
+        pos_to: End position (receiving surface center)
+        lad: 3D field of Leaf Area Density
+        is_solid: 3D field of solid cells (buildings/terrain)
+        nx, ny, nz: Grid dimensions
+        dx, dy, dz: Cell sizes
+        ext_coef: Extinction coefficient
+    
+    Returns:
+        Tuple of (transmissivity, blocked_by_solid)
+        - transmissivity: 0-1 fraction of radiation that gets through
+        - blocked_by_solid: 1 if ray hits a solid cell, 0 otherwise
+    """
+    # Compute ray direction and distance
+    diff = pos_to - pos_from
+    dist = diff.norm()
+    
+    transmissivity = 1.0
+    blocked = 0
+    
+    # Only trace if distance is significant
+    if dist >= 0.01:
+        ray_dir = diff / dist
+        
+        # Starting voxel
+        pos = pos_from + ray_dir * 0.01  # Slight offset to avoid self-intersection
+        
+        ix = ti.cast(ti.floor(pos[0] / dx), ti.i32)
+        iy = ti.cast(ti.floor(pos[1] / dy), ti.i32)
+        iz = ti.cast(ti.floor(pos[2] / dz), ti.i32)
+        
+        # Clamp to valid range
+        ix = ti.max(0, ti.min(nx - 1, ix))
+        iy = ti.max(0, ti.min(ny - 1, iy))
+        iz = ti.max(0, ti.min(nz - 1, iz))
+        
+        # Step directions
+        step_x = 1 if ray_dir[0] >= 0 else -1
+        step_y = 1 if ray_dir[1] >= 0 else -1
+        step_z = 1 if ray_dir[2] >= 0 else -1
+        
+        # Initialize DDA variables
+        t_max_x = 1e30
+        t_max_y = 1e30
+        t_max_z = 1e30
+        t_delta_x = 1e30
+        t_delta_y = 1e30
+        t_delta_z = 1e30
+        
+        t = 0.01  # Start offset
+        
+        if ti.abs(ray_dir[0]) > 1e-10:
+            if step_x > 0:
+                t_max_x = ((ix + 1) * dx - pos_from[0]) / ray_dir[0]
+            else:
+                t_max_x = (ix * dx - pos_from[0]) / ray_dir[0]
+            t_delta_x = ti.abs(dx / ray_dir[0])
+        
+        if ti.abs(ray_dir[1]) > 1e-10:
+            if step_y > 0:
+                t_max_y = ((iy + 1) * dy - pos_from[1]) / ray_dir[1]
+            else:
+                t_max_y = (iy * dy - pos_from[1]) / ray_dir[1]
+            t_delta_y = ti.abs(dy / ray_dir[1])
+        
+        if ti.abs(ray_dir[2]) > 1e-10:
+            if step_z > 0:
+                t_max_z = ((iz + 1) * dz - pos_from[2]) / ray_dir[2]
+            else:
+                t_max_z = (iz * dz - pos_from[2]) / ray_dir[2]
+            t_delta_z = ti.abs(dz / ray_dir[2])
+        
+        t_prev = t
+        max_steps = nx + ny + nz
+        done = 0
+        
+        for _ in range(max_steps):
+            if done == 1:
+                continue  # Skip remaining iterations
+            
+            if ix < 0 or ix >= nx or iy < 0 or iy >= ny or iz < 0 or iz >= nz:
+                done = 1
+                continue
+            if t > dist:  # Reached target
+                done = 1
+                continue
+            
+            # Check for solid obstruction (but skip first and last cell as they're the surfaces)
+            if is_solid[ix, iy, iz] == 1 and t > 0.1 and t < dist - 0.1:
+                blocked = 1
+                transmissivity = 0.0
+                done = 1
+                continue
+            
+            # Get step distance
+            t_next = t_max_x
+            if t_max_y < t_next:
+                t_next = t_max_y
+            if t_max_z < t_next:
+                t_next = t_max_z
+            
+            # Limit to target distance
+            t_next = ti.min(t_next, dist)
+            
+            # Path length through this cell
+            path_len = t_next - t_prev
+            
+            # Accumulate absorption from LAD
+            cell_lad = lad[ix, iy, iz]
+            if cell_lad > 0.0:
+                # Beer-Lambert: T = exp(-ext_coef * LAD * path)
+                transmissivity *= ti.exp(-ext_coef * cell_lad * path_len)
+            
+            t_prev = t_next
+            
+            # Step to next voxel
+            if t_max_x < t_max_y and t_max_x < t_max_z:
+                t = t_max_x
+                ix += step_x
+                t_max_x += t_delta_x
+            elif t_max_y < t_max_z:
+                t = t_max_y
+                iy += step_y
+                t_max_y += t_delta_y
+            else:
+                t = t_max_z
+                iz += step_z
+                t_max_z += t_delta_z
+    
+    return transmissivity, blocked
+
+
 @ti.func
 def ray_trace_to_target(
     origin: Vector3,