voxcity.simulator.solar.temporal
================================

.. py:module:: voxcity.simulator.solar.temporal

.. autoapi-nested-parse::

   Stage 3: Time-series integration.



Functions
---------

.. autoapisummary::

   voxcity.simulator.solar.temporal.get_solar_positions_astral
   voxcity.simulator.solar.temporal.get_cumulative_global_solar_irradiance
   voxcity.simulator.solar.temporal.get_cumulative_building_solar_irradiance


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

.. py:function:: get_solar_positions_astral(times, lon, lat)

   Compute solar azimuth and elevation for given times and location using Astral.
   Returns a DataFrame indexed by times with columns ['azimuth', 'elevation'] (degrees).


.. py:function:: get_cumulative_global_solar_irradiance(voxcity: voxcity.models.VoxCity, df, lon, lat, tz, direct_normal_irradiance_scaling=1.0, diffuse_irradiance_scaling=1.0, **kwargs)

   Integrate global horizontal irradiance over a period using EPW data.
   Returns W/m²·hour accumulation on the ground plane.

   :param voxcity: The VoxCity model.
   :type voxcity: VoxCity
   :param df: Weather data with 'DNI' and 'DHI' columns.
   :type df: pd.DataFrame
   :param lon: Longitude and latitude for solar position calculation.
   :type lon: float
   :param lat: Longitude and latitude for solar position calculation.
   :type lat: float
   :param tz: Timezone offset in hours.
   :type tz: float
   :param direct_normal_irradiance_scaling: Scaling factor for DNI.
   :type direct_normal_irradiance_scaling: float
   :param diffuse_irradiance_scaling: Scaling factor for DHI.
   :type diffuse_irradiance_scaling: float
   :param \*\*kwargs: Additional options:
                      - use_sky_patches : bool (default False)
                          If True, use sky patch aggregation for efficiency.
                          DNI is aggregated into sky patches and ray tracing is done
                          once per patch instead of per timestep.
                      - sky_discretization : str (default "tregenza")
                          Sky discretization method: "tregenza", "reinhart", "uniform", "fibonacci"
                      - reinhart_mf : int (default 4)
                          Multiplication factor for Reinhart subdivision.
                      - sky_n_patches : int (default 145)
                          Number of patches for Fibonacci method.
                      - progress_report : bool
                          Print progress information.
   :type \*\*kwargs: dict

   :returns: Cumulative global solar irradiance map (Wh/m²).
   :rtype: np.ndarray


.. py:function:: get_cumulative_building_solar_irradiance(voxcity: voxcity.models.VoxCity, building_svf_mesh, weather_df, lon, lat, tz, **kwargs)

   Cumulative Wh/m² on building faces over a period from weather dataframe.

   :param voxcity: The VoxCity model.
   :type voxcity: VoxCity
   :param building_svf_mesh: Building mesh with SVF in metadata.
   :type building_svf_mesh: trimesh.Trimesh
   :param weather_df: Weather data with 'DNI' and 'DHI' columns.
   :type weather_df: pd.DataFrame
   :param lon: Longitude and latitude.
   :type lon: float
   :param lat: Longitude and latitude.
   :type lat: float
   :param tz: Timezone offset in hours.
   :type tz: float
   :param \*\*kwargs: Additional options:
                      - use_sky_patches : bool (default False)
                          If True, use sky patch aggregation for efficiency.
                          Reduces computation from N timesteps to M patches (M << N).
                      - sky_discretization : str (default "tregenza")
                          Method: "tregenza", "reinhart", "uniform", "fibonacci"
                      - reinhart_mf : int (default 4)
                          Multiplication factor for Reinhart subdivision.
                      - fast_path : bool (default True)
                          Use optimized Numba kernels.
                      - progress_report : bool
                          Print progress information.
   :type \*\*kwargs: dict

   :returns: Mesh with cumulative irradiance in metadata (direct, diffuse, global in Wh/m²).
   :rtype: trimesh.Trimesh