voxcity.simulator_gpu.solar.integration.building
================================================

.. py:module:: voxcity.simulator_gpu.solar.integration.building

.. autoapi-nested-parse::

   Building surface solar irradiance functions for VoxCity.

   This module provides GPU-accelerated building surface solar irradiance calculations:
   - Building solar irradiance (instantaneous)
   - Cumulative building solar irradiance
   - Building sunlight hours (PSH and DSH modes)
   - EPW-based building irradiance wrapper

   These functions match the voxcity.simulator.solar API signatures for
   drop-in replacement with GPU acceleration.



Attributes
----------

.. autoapisummary::

   voxcity.simulator_gpu.solar.integration.building.logger


Functions
---------

.. autoapisummary::

   voxcity.simulator_gpu.solar.integration.building.get_building_solar_irradiance
   voxcity.simulator_gpu.solar.integration.building.get_cumulative_building_solar_irradiance
   voxcity.simulator_gpu.solar.integration.building.get_building_sunlight_hours
   voxcity.simulator_gpu.solar.integration.building.get_building_global_solar_irradiance_using_epw


Module Contents
---------------

.. py:data:: logger

.. py:function:: get_building_solar_irradiance(voxcity, building_svf_mesh=None, azimuth_degrees_ori: float = None, elevation_degrees: float = None, direct_normal_irradiance: float = None, diffuse_irradiance: float = None, **kwargs)

   GPU-accelerated building surface solar irradiance computation.

   Uses cached RadiationModel to avoid recomputing SVF/CSF matrices for each timestep.

   :param voxcity: VoxCity object
   :param building_svf_mesh: Pre-computed mesh with SVF values (optional)
   :param azimuth_degrees_ori: Solar azimuth in degrees (0=North, clockwise)
   :param elevation_degrees: Solar elevation in degrees above horizon
   :param direct_normal_irradiance: DNI in W/m²
   :param diffuse_irradiance: DHI in W/m²
   :param \*\*kwargs: Additional parameters including:
                      - with_reflections (bool): Enable multi-bounce reflections (default: False)
                      - n_reflection_steps (int): Number of reflection bounces (default: 2)
                      - building_class_id (int): Building voxel class code (default: -3)
                      - computation_mask (np.ndarray): Optional 2D boolean mask
                      - target_selectors (list): Optional surface selectors limiting returned faces
                      - reference_mesh: Optional reference mesh for target selector metadata fast path
                      - progress_report (bool): Print progress (default: False)

   :returns: Trimesh object with irradiance values in metadata


.. py:function:: get_cumulative_building_solar_irradiance(voxcity, building_svf_mesh, weather_df, lon: float, lat: float, tz: float, direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, **kwargs)

   GPU-accelerated cumulative solar irradiance on building surfaces.

   :param voxcity: VoxCity object
   :param building_svf_mesh: Trimesh object with SVF in metadata
   :param weather_df: pandas DataFrame with 'DNI' and 'DHI' columns
   :param lon: Longitude in degrees
   :param lat: Latitude in degrees
   :param tz: Timezone offset in hours
   :param direct_normal_irradiance_scaling: Scaling factor for DNI
   :param diffuse_irradiance_scaling: Scaling factor for DHI
   :param \*\*kwargs: Additional parameters

   :returns: Trimesh object with cumulative irradiance (Wh/m²) in metadata


.. py:function:: get_building_sunlight_hours(voxcity, building_svf_mesh=None, mode: str = 'PSH', epw_file_path: str = None, download_nearest_epw: bool = False, dni_threshold: float = 120.0, lon: float = None, lat: float = None, tz: float = None, **kwargs)

   GPU-accelerated sunlight hours computation for building surfaces.

   Supports PSH (Probable Sunlight Hours) and DSH (Direct Sun Hours) modes.

   **DSH mode** does NOT require an EPW file. Location is automatically
   extracted from the VoxCity object and timezone is inferred.

   :param voxcity: VoxCity object
   :param building_svf_mesh: Trimesh object with building surfaces (optional)
   :param mode: 'PSH' or 'DSH'
   :param epw_file_path: Path to EPW file (required for PSH, optional for DSH)
   :param download_nearest_epw: If True, download nearest EPW
   :param dni_threshold: DNI threshold for PSH mode (default: 120.0 W/m²)
   :param lon: Longitude in degrees (optional, extracted from voxcity if not provided)
   :param lat: Latitude in degrees (optional, extracted from voxcity if not provided)
   :param tz: Timezone offset in hours (optional, inferred from location if not provided)
   :param \*\*kwargs: Additional parameters

   :returns: Trimesh object with sunlight hours in metadata


.. py:function:: get_building_global_solar_irradiance_using_epw(voxcity, calc_type: str = 'instantaneous', direct_normal_irradiance_scaling: float = 1.0, diffuse_irradiance_scaling: float = 1.0, building_svf_mesh=None, **kwargs)

   GPU-accelerated building surface irradiance using EPW weather data.

   :param voxcity: VoxCity object
   :param calc_type: 'instantaneous' or 'cumulative'
   :param direct_normal_irradiance_scaling: Scaling factor for DNI
   :param diffuse_irradiance_scaling: Scaling factor for DHI
   :param building_svf_mesh: Pre-computed building mesh (optional)
   :param \*\*kwargs: Additional parameters

   :returns: Trimesh object with irradiance values in metadata