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

voxcity/simulator_gpu/solar/__init__.py

@@ -0,0 +1,222 @@
+"""
+palm-solar: GPU-accelerated solar radiation simulation for urban environments
+
+This package emulates PALM's Radiative Transfer Model (RTM) using Taichi for
+GPU acceleration. It computes:
+- Direct and diffuse solar radiation on surfaces
+- Shadows from buildings and vegetation
+- Sky View Factors (SVF) 
+- Canopy Sink Factors (CSF) for plant canopy absorption
+- Surface-to-surface radiative exchange
+
+References:
+- Resler et al., GMD 2017: https://doi.org/10.5194/gmd-10-3635-2017
+- Krč et al., GMD 2021: https://doi.org/10.5194/gmd-14-3095-2021
+"""
+
+from .core import (
+    Vector3, Point3, 
+    SOLAR_CONSTANT, EXT_COEF, MIN_STABLE_COSZEN,
+    PI, TWO_PI, DEG_TO_RAD, RAD_TO_DEG,
+    normalize, dot, cross, spherical_to_cartesian
+)
+
+from .domain import Domain, Surfaces, extract_surfaces_from_domain
+
+from .solar import (
+    SolarPosition, SolarCalculator,
+    calc_zenith, calc_solar_position_datetime,
+    discretize_sky_directions
+)
+
+from .raytracing import (
+    RayTracer,
+    ray_aabb_intersect,
+    ray_voxel_first_hit,
+    ray_canopy_absorption,
+    ray_voxel_transmissivity,
+    ray_trace_to_target,
+    ray_point_to_point_transmissivity,
+    sample_hemisphere_direction,
+    hemisphere_solid_angle,
+)
+
+from .svf import SVFCalculator
+
+from .csf import CSFCalculator
+
+from .radiation import RadiationModel, RadiationConfig
+
+from .volumetric import VolumetricFluxCalculator, VolumetricFluxMode
+
+# EPW file processing for cumulative irradiance
+from .epw import (
+    EPWLocation,
+    EPWSolarData,
+    read_epw_header,
+    read_epw_solar_data,
+    prepare_cumulative_simulation_input,
+    get_typical_days,
+    estimate_annual_irradiance,
+)
+
+# Sky discretization for cumulative irradiance
+from .sky import (
+    SkyPatches,
+    BinnedSolarData,
+    generate_tregenza_patches,
+    generate_reinhart_patches,
+    generate_uniform_grid_patches,
+    generate_fibonacci_patches,
+    generate_sky_patches,
+    bin_sun_positions_to_patches,
+    get_tregenza_patch_index,
+    get_tregenza_patch_index_fast,
+    bin_sun_positions_to_tregenza_fast,
+    get_patch_info,
+    calculate_cumulative_irradiance_weights,
+    visualize_sky_patches,
+    TREGENZA_BANDS,
+    TREGENZA_BAND_BOUNDARIES,
+)
+
+# Computation mask utilities
+from .mask import (
+    create_computation_mask,
+    draw_computation_mask,
+    get_mask_from_drawing,
+    visualize_computation_mask,
+    get_mask_info,
+)
+
+# VoxCity integration
+from .integration import (
+    load_voxcity,
+    convert_voxcity_to_domain,
+    apply_voxcity_albedo,
+    create_radiation_config_for_voxcity,
+    LandCoverAlbedo,
+    VoxCityDomainResult,
+    VOXCITY_GROUND_CODE,
+    VOXCITY_TREE_CODE,
+    VOXCITY_BUILDING_CODE,
+    # VoxCity API-compatible solar functions
+    get_direct_solar_irradiance_map,
+    get_diffuse_solar_irradiance_map,
+    get_global_solar_irradiance_map,
+    get_cumulative_global_solar_irradiance,
+    get_building_solar_irradiance,
+    get_cumulative_building_solar_irradiance,
+    get_global_solar_irradiance_using_epw,
+    get_building_global_solar_irradiance_using_epw,
+    # Volumetric solar irradiance functions
+    get_volumetric_solar_irradiance_map,
+    get_cumulative_volumetric_solar_irradiance,
+    get_volumetric_solar_irradiance_using_epw,
+    clear_volumetric_flux_cache,
+    save_irradiance_mesh,
+    load_irradiance_mesh,
+    # Temporal utilities
+    get_solar_positions_astral,
+    # Cache management
+    clear_radiation_model_cache,
+    clear_building_radiation_model_cache,
+    clear_all_radiation_caches,
+    clear_all_caches,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Core
+    'Vector3', 'Point3',
+    'SOLAR_CONSTANT', 'EXT_COEF', 'MIN_STABLE_COSZEN',
+    'PI', 'TWO_PI', 'DEG_TO_RAD', 'RAD_TO_DEG',
+    'normalize', 'dot', 'cross', 'spherical_to_cartesian',
+    # Domain
+    'Domain', 'Surfaces', 'extract_surfaces_from_domain',
+    # Solar
+    'SolarPosition', 'SolarCalculator',
+    'calc_zenith', 'calc_solar_position_datetime',
+    'discretize_sky_directions',
+    # Ray tracing
+    'RayTracer',
+    'ray_aabb_intersect',
+    'ray_voxel_first_hit',
+    'ray_canopy_absorption',
+    'ray_voxel_transmissivity',
+    'ray_trace_to_target',
+    'ray_point_to_point_transmissivity',
+    'sample_hemisphere_direction',
+    'hemisphere_solid_angle',
+    # SVF
+    'SVFCalculator',
+    # CSF
+    'CSFCalculator',
+    # Radiation
+    'RadiationModel', 'RadiationConfig',
+    # Volumetric flux
+    'VolumetricFluxCalculator',
+    # EPW file processing
+    'EPWLocation',
+    'EPWSolarData',
+    'read_epw_header',
+    'read_epw_solar_data',
+    'prepare_cumulative_simulation_input',
+    'get_typical_days',
+    'estimate_annual_irradiance',
+    # Sky discretization (VoxCity API compatible)
+    'SkyPatches',
+    'BinnedSolarData',
+    'generate_tregenza_patches',
+    'generate_reinhart_patches',
+    'generate_uniform_grid_patches',
+    'generate_fibonacci_patches',
+    'generate_sky_patches',
+    'bin_sun_positions_to_patches',
+    'bin_sun_positions_to_tregenza_fast',
+    'get_tregenza_patch_index',
+    'get_tregenza_patch_index_fast',
+    'get_patch_info',
+    'calculate_cumulative_irradiance_weights',
+    'visualize_sky_patches',
+    'TREGENZA_BANDS',
+    'TREGENZA_BAND_BOUNDARIES',
+    # Computation mask utilities
+    'create_computation_mask',
+    'draw_computation_mask',
+    'get_mask_from_drawing',
+    'visualize_computation_mask',
+    'get_mask_info',
+    # VoxCity integration
+    'load_voxcity',
+    'convert_voxcity_to_domain',
+    'apply_voxcity_albedo',
+    'create_radiation_config_for_voxcity',
+    'LandCoverAlbedo',
+    'VoxCityDomainResult',
+    'VOXCITY_GROUND_CODE',
+    'VOXCITY_TREE_CODE',
+    'VOXCITY_BUILDING_CODE',
+    # VoxCity API-compatible solar functions
+    'get_direct_solar_irradiance_map',
+    'get_diffuse_solar_irradiance_map',
+    'get_global_solar_irradiance_map',
+    'get_cumulative_global_solar_irradiance',
+    'get_building_solar_irradiance',
+    'get_cumulative_building_solar_irradiance',
+    'get_global_solar_irradiance_using_epw',
+    'get_building_global_solar_irradiance_using_epw',
+    # Volumetric solar irradiance functions
+    'get_volumetric_solar_irradiance_map',
+    'get_cumulative_volumetric_solar_irradiance',
+    'get_volumetric_solar_irradiance_using_epw',
+    'clear_volumetric_flux_cache',
+    'save_irradiance_mesh',
+    'load_irradiance_mesh',
+    # Cache management
+    'clear_radiation_model_cache',
+    'clear_building_radiation_model_cache',
+    'clear_all_radiation_caches',
+    # Temporal utilities (VoxCity API compatible)
+    'get_solar_positions_astral',
+]

voxcity/simulator_gpu/solar/core.py

@@ -0,0 +1,66 @@
+"""
+Vector and ray utilities for palm-solar using Taichi.
+Based on ray-tracing-one-weekend-taichi patterns.
+
+GPU Optimization Notes:
+- All functions use @ti.func for GPU inlining
+- Branchless operations preferred where possible
+- Memory coalescing friendly access patterns
+- done-flag pattern for early termination (reduces warp divergence)
+
+This module re-exports shared core utilities from simulator_gpu.core
+and adds solar-specific extensions.
+"""
+
+import taichi as ti
+import math
+
+# Import shared core utilities from parent package
+from ..core import (
+    Vector3,
+    Point3,
+    Color3,
+    PI,
+    TWO_PI,
+    HALF_PI,
+    DEG_TO_RAD,
+    RAD_TO_DEG,
+    SOLAR_CONSTANT,
+    EXT_COEF,
+    MIN_STABLE_COSZEN,
+    GPU_BLOCK_SIZE,
+    normalize,
+    normalize_safe,
+    dot,
+    cross,
+    reflect,
+    ray_at,
+    length_squared,
+    distance_squared,
+    min3,
+    max3,
+    clamp,
+    random_in_unit_sphere,
+    random_in_hemisphere,
+    random_cosine_hemisphere,
+    spherical_to_cartesian,
+    cartesian_to_spherical,
+    rotate_vector_axis_angle,
+    build_face_basis,
+    Rays,
+    HitRecord,
+)
+
+# Re-export all symbols for backward compatibility
+__all__ = [
+    'Vector3', 'Point3', 'Color3',
+    'PI', 'TWO_PI', 'HALF_PI', 'DEG_TO_RAD', 'RAD_TO_DEG',
+    'SOLAR_CONSTANT', 'EXT_COEF', 'MIN_STABLE_COSZEN', 'GPU_BLOCK_SIZE',
+    'normalize', 'normalize_safe', 'dot', 'cross', 'reflect',
+    'ray_at', 'length_squared', 'distance_squared',
+    'min3', 'max3', 'clamp',
+    'random_in_unit_sphere', 'random_in_hemisphere', 'random_cosine_hemisphere',
+    'spherical_to_cartesian', 'cartesian_to_spherical',
+    'rotate_vector_axis_angle', 'build_face_basis',
+    'Rays', 'HitRecord',
+]