voxcity.simulator_gpu.solar
===========================

.. py:module:: voxcity.simulator_gpu.solar

.. autoapi-nested-parse::

   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

   Coordinate System
   -----------------
   VoxCity uses a grid-index coordinate system where:
   - x (index i/u): Row direction, increases toward North
   - y (index j/v): Column direction, increases toward East
   - z (index k): Vertical direction, increases upward

   This differs from standard ENU (East-North-Up) coordinates:
   - ENU: x=East, y=North, z=Up
   - VoxCity grid: x=North, y=East, z=Up

   The relationship is:
       grid_x = +enu_north
       grid_y = +enu_east
       grid_z = +enu_up

   Sun Direction Vector
   --------------------
   Sun direction vectors in this module are in VoxCity grid coordinates:
   - sun_x > 0: Sun is in the North (azimuth ~0°)
   - sun_x < 0: Sun is in the South (azimuth ~180°)
   - sun_y > 0: Sun is in the East (azimuth ~90°)
   - sun_y < 0: Sun is in the West (azimuth ~270°)
   - sun_z > 0: Sun is above horizon

   Surface Direction Indices (PALM convention)
   --------------------------------------------
   Direction indices follow PALM naming but map to VoxCity grid:
   - IUP (0): +z, upward-facing surfaces
   - IDOWN (1): -z, downward-facing surfaces
   - INORTH (2): +y normal = East-facing in geographic terms
   - ISOUTH (3): -y normal = West-facing in geographic terms
   - IEAST (4): +x normal = North-facing in geographic terms (legacy PALM label)
   - IWEST (5): -x normal = South-facing in geographic terms (legacy PALM label)

   The naming (INORTH, ISOUTH, etc.) is legacy from PALM. In VoxCity's grid:
   - "IEAST" surfaces receive sun when sun_x > 0 (sun in North)
   - "INORTH" surfaces receive sun when sun_y > 0 (sun in East)

   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



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/voxcity/simulator_gpu/solar/core/index
   /autoapi/voxcity/simulator_gpu/solar/csf/index
   /autoapi/voxcity/simulator_gpu/solar/domain/index
   /autoapi/voxcity/simulator_gpu/solar/epw/index
   /autoapi/voxcity/simulator_gpu/solar/integration/index
   /autoapi/voxcity/simulator_gpu/solar/mask/index
   /autoapi/voxcity/simulator_gpu/solar/radiation/index
   /autoapi/voxcity/simulator_gpu/solar/raytracing/index
   /autoapi/voxcity/simulator_gpu/solar/reflection/index
   /autoapi/voxcity/simulator_gpu/solar/sky/index
   /autoapi/voxcity/simulator_gpu/solar/solar/index
   /autoapi/voxcity/simulator_gpu/solar/svf/index
   /autoapi/voxcity/simulator_gpu/solar/volumetric/index