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

voxcity/simulator_gpu/domain.py

@@ -0,0 +1,262 @@
+"""
+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
+"""
+
+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
+
+
+# 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
+        )

voxcity/simulator_gpu/environment.yml

@@ -0,0 +1,11 @@
+name: voxcity_gpu
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.12
+  - gdal
+  - timezonefinder
+  - pip
+  - pip:
+    - voxcity[gpu]

voxcity/simulator_gpu/init_taichi.py

@@ -0,0 +1,154 @@
+"""
+Taichi initialization for simulator_gpu.
+
+This module provides centralized Taichi initialization to ensure ti.init()
+is called before any Taichi fields or kernels are used.
+"""
+
+import taichi as ti
+import os
+import warnings
+from typing import Optional
+
+# Track initialization state
+_TAICHI_INITIALIZED = False
+
+
+def init_taichi(
+    arch: Optional[str] = None,
+    default_fp: type = ti.f32,
+    default_ip: type = ti.i32,
+    debug: bool = False,
+    suppress_fp16_warnings: bool = True,
+    **kwargs
+) -> bool:
+    """
+    Initialize Taichi runtime if not already initialized.
+    
+    This function is idempotent - calling it multiple times is safe.
+    The first call will initialize Taichi, subsequent calls will be no-ops.
+    
+    Args:
+        arch: Architecture to use. Options:
+            - None (default): Auto-detect best available (GPU preferred)
+            - 'gpu': Use GPU (CUDA, Vulkan, Metal, etc.)
+            - 'cuda': Use CUDA specifically
+            - 'vulkan': Use Vulkan
+            - 'metal': Use Metal (macOS)
+            - 'cpu': Use CPU
+        default_fp: Default floating point type (ti.f32 or ti.f64)
+        default_ip: Default integer type (ti.i32 or ti.i64)
+        debug: Enable debug mode for better error messages
+        suppress_fp16_warnings: Suppress Taichi's fp16 precision loss warnings
+            (default: True). These warnings occur when using fp16 intermediate
+            buffers for memory bandwidth optimization.
+        **kwargs: Additional arguments passed to ti.init()
+        
+    Returns:
+        True if initialization was performed, False if already initialized.
+    """
+    global _TAICHI_INITIALIZED
+    
+    if _TAICHI_INITIALIZED:
+        return False
+    
+    # Suppress fp16 precision warnings if requested
+    # These occur when assigning f32 values to f16 fields, which is intentional
+    # for memory bandwidth optimization in intermediate buffers
+    if suppress_fp16_warnings:
+        # Filter Taichi's precision loss warnings via Python warnings module
+        warnings.filterwarnings(
+            'ignore',
+            message='.*Assign a value with precision.*',
+            category=UserWarning
+        )
+        warnings.filterwarnings(
+            'ignore',
+            message='.*Atomic add may lose precision.*',
+            category=UserWarning
+        )
+        # Also set Taichi log level to ERROR to suppress warnings from Taichi's internal logging
+        # This is needed because Taichi uses its own logging system for some warnings
+        if 'log_level' not in kwargs:
+            kwargs['log_level'] = ti.ERROR
+    
+    # Determine architecture
+    if arch is None:
+        # Auto-detect: prefer GPU, fall back to CPU
+        ti_arch = ti.gpu
+    elif arch == 'gpu':
+        ti_arch = ti.gpu
+    elif arch == 'cuda':
+        ti_arch = ti.cuda
+    elif arch == 'vulkan':
+        ti_arch = ti.vulkan
+    elif arch == 'metal':
+        ti_arch = ti.metal
+    elif arch == 'cpu':
+        ti_arch = ti.cpu
+    else:
+        raise ValueError(f"Unknown architecture: {arch}")
+    
+    # Check environment variable for override
+    env_arch = os.environ.get('TAICHI_ARCH', '').lower()
+    if env_arch == 'cpu':
+        ti_arch = ti.cpu
+    elif env_arch == 'cuda':
+        ti_arch = ti.cuda
+    elif env_arch == 'vulkan':
+        ti_arch = ti.vulkan
+    elif env_arch == 'gpu':
+        ti_arch = ti.gpu
+    
+    # Initialize Taichi
+    ti.init(
+        arch=ti_arch,
+        default_fp=default_fp,
+        default_ip=default_ip,
+        debug=debug,
+        **kwargs
+    )
+    
+    _TAICHI_INITIALIZED = True
+    return True
+
+
+def ensure_initialized():
+    """
+    Ensure Taichi is initialized with default settings.
+    
+    This is a convenience function for lazy initialization.
+    Call this before any Taichi operations if you're not sure
+    whether init_taichi() has been called.
+    """
+    if not _TAICHI_INITIALIZED:
+        init_taichi()
+
+
+def is_initialized() -> bool:
+    """Check if Taichi has been initialized."""
+    return _TAICHI_INITIALIZED
+
+
+def reset():
+    """
+    Reset initialization state.
+    
+    Note: This does NOT reset Taichi itself (which cannot be reset once initialized).
+    This only resets the tracking flag for testing purposes.
+    """
+    global _TAICHI_INITIALIZED
+    _TAICHI_INITIALIZED = False
+
+
+# Convenience: expose ti for direct access
+taichi = ti
+
+__all__ = [
+    'init_taichi',
+    'ensure_initialized', 
+    'is_initialized',
+    'reset',
+    'taichi',
+    'ti',
+]

voxcity/simulator_gpu/integration.py

@@ -0,0 +1,15 @@
+"""VoxCity-style `integration` module (toplevel) for compatibility."""
+
+from .solar.integration import (
+    get_global_solar_irradiance_using_epw,
+    get_building_global_solar_irradiance_using_epw,
+    save_irradiance_mesh,
+    load_irradiance_mesh,
+)
+
+__all__ = [
+    "get_global_solar_irradiance_using_epw",
+    "get_building_global_solar_irradiance_using_epw",
+    "save_irradiance_mesh",
+    "load_irradiance_mesh",
+]

voxcity/simulator_gpu/kernels.py

@@ -0,0 +1,56 @@
+"""VoxCity-style `kernels` module (toplevel) for compatibility.
+
+Implements a minimal subset of `voxcity.simulator.solar.kernels` so code that
+imports these symbols continues to run when using:
+
+    import simulator_gpu as simulator
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import numpy as np
+
+
+def compute_direct_solar_irradiance_map_binary(
+    voxel_data,
+    sun_direction,
+    view_point_height,
+    hit_values,
+    meshsize,
+    tree_k,
+    tree_lad,
+    inclusion_mode,
+):
+    """Approximate VoxCity kernel: return direct-beam transmittance map (0..1).
+
+    Signature matches `voxcity.simulator.solar.kernels.compute_direct_solar_irradiance_map_binary`.
+
+    Notes:
+        - `hit_values` and `inclusion_mode` are accepted for compatibility but
+          are not currently used in the GPU path.
+        - Output is flipped with `np.flipud`, matching VoxCity.
+    """
+    from .solar.integration import _compute_direct_transmittance_map_gpu
+
+    sd = np.array(sun_direction, dtype=np.float64)
+    L = float(np.sqrt((sd * sd).sum()))
+    if L == 0.0:
+        nx, ny = voxel_data.shape[0], voxel_data.shape[1]
+        return np.flipud(np.full((nx, ny), np.nan, dtype=np.float64))
+    sd /= L
+
+    trans = _compute_direct_transmittance_map_gpu(
+        voxel_data=np.asarray(voxel_data),
+        sun_direction=(float(sd[0]), float(sd[1]), float(sd[2])),
+        view_point_height=float(view_point_height),
+        meshsize=float(meshsize),
+        tree_k=float(tree_k),
+        tree_lad=float(tree_lad),
+    )
+
+    return np.flipud(trans)
+
+
+__all__ = ["compute_direct_solar_irradiance_map_binary"]

voxcity/simulator_gpu/radiation.py

@@ -0,0 +1,28 @@
+"""VoxCity-style `radiation` module (toplevel) for compatibility."""
+
+from .solar.integration import (
+    get_direct_solar_irradiance_map,
+    get_diffuse_solar_irradiance_map,
+    get_global_solar_irradiance_map,
+)
+
+
+def compute_solar_irradiance_for_all_faces(*args, **kwargs):
+    """Compatibility stub.
+
+    VoxCity's public API sometimes re-exports this symbol; if your workflow
+    depends on it, we can map it to a GPU equivalent (or implement it) once the
+    expected inputs/outputs are confirmed.
+    """
+    raise NotImplementedError(
+        "compute_solar_irradiance_for_all_faces is not implemented in simulator_gpu yet. "
+        "Use get_*_solar_irradiance_map functions or open an issue with the expected signature."
+    )
+
+
+__all__ = [
+    "get_direct_solar_irradiance_map",
+    "get_diffuse_solar_irradiance_map",
+    "get_global_solar_irradiance_map",
+    "compute_solar_irradiance_for_all_faces",
+]