Merge feat/custom-solar-daily-hour: daily hour-of-day window for cumulative solar

Author: kunifujiwara

src/voxcity/simulator_gpu/solar/integration/building.py

@@ -405,6 +405,8 @@ def get_cumulative_building_solar_irradiance(
     kwargs = dict(kwargs)
     period_start = kwargs.pop('period_start', '01-01 00:00:00')
     period_end = kwargs.pop('period_end', '12-31 23:59:59')
+    daily_start_hour = kwargs.pop('daily_start_hour', None)
+    daily_end_hour = kwargs.pop('daily_end_hour', None)
     time_step_hours = float(kwargs.pop('time_step_hours', 1.0))
     progress_report = kwargs.pop('progress_report', False)
     use_sky_patches = kwargs.pop('use_sky_patches', False)
@@ -415,7 +417,9 @@ def get_cumulative_building_solar_irradiance(
         raise ValueError("No data in weather dataframe.")
 
     # Filter dataframe
-    df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz)
+    df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz,
+                                        daily_start_hour=daily_start_hour,
+                                        daily_end_hour=daily_end_hour)
 
     # Get solar positions
     solar_positions = get_solar_positions_astral(df_period_utc.index, lon, lat)
@@ -660,6 +664,8 @@ def get_building_sunlight_hours(
     kwargs = dict(kwargs)
     period_start = kwargs.pop('period_start', '01-01 00:00:00')
     period_end = kwargs.pop('period_end', '12-31 23:59:59')
+    daily_start_hour = kwargs.pop('daily_start_hour', None)
+    daily_end_hour = kwargs.pop('daily_end_hour', None)
     time_step_hours = float(kwargs.pop('time_step_hours', 1.0))
     progress_report = kwargs.pop('progress_report', False)
     computation_mask = kwargs.pop('computation_mask', None)
@@ -700,7 +706,9 @@ def get_building_sunlight_hours(
             raise ValueError("Weather dataframe must have 'DNI' column for PSH mode.")
 
     # Filter dataframe
-    df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz)
+    df_period_utc = filter_df_to_period(weather_df, period_start, period_end, tz,
+                                        daily_start_hour=daily_start_hour,
+                                        daily_end_hour=daily_end_hour)
 
     # Get solar positions
     solar_positions = get_solar_positions_astral(df_period_utc.index, lon, lat)

src/voxcity/simulator_gpu/solar/integration/ground.py

@@ -493,6 +493,8 @@ def get_cumulative_global_solar_irradiance(
             - computation_mask (np.ndarray): Optional 2D boolean mask
             - start_time (str): Start time 'MM-DD HH:MM:SS'
             - end_time (str): End time 'MM-DD HH:MM:SS'
+            - daily_start_hour (int): Optional inclusive hour-of-day lower bound (0-23)
+            - daily_end_hour (int): Optional inclusive hour-of-day upper bound (0-23)
             - view_point_height (float): Observer height
             - use_sky_patches (bool): Use sky patch optimization (default: True)
             - sky_discretization (str): 'tregenza', 'reinhart', etc.
@@ -511,6 +513,8 @@ def get_cumulative_global_solar_irradiance(
     colormap = kwargs.pop('colormap', 'magma')
     start_time = kwargs.pop('start_time', '01-01 05:00:00')
     end_time = kwargs.pop('end_time', '01-01 20:00:00')
+    daily_start_hour = kwargs.pop('daily_start_hour', None)
+    daily_end_hour = kwargs.pop('daily_end_hour', None)
     progress_report = kwargs.pop('progress_report', False)
     use_sky_patches = kwargs.pop('use_sky_patches', True)
     sky_discretization = kwargs.pop('sky_discretization', 'tregenza')
@@ -519,7 +523,9 @@ def get_cumulative_global_solar_irradiance(
         raise ValueError("No data in EPW dataframe.")
 
     # Filter dataframe to period
-    df_period_utc = filter_df_to_period(df, start_time, end_time, tz)
+    df_period_utc = filter_df_to_period(df, start_time, end_time, tz,
+                                        daily_start_hour=daily_start_hour,
+                                        daily_end_hour=daily_end_hour)
 
     # Get solar positions
     solar_positions = get_solar_positions_astral(df_period_utc.index, lon, lat)

src/voxcity/simulator_gpu/solar/integration/utils.py

@@ -233,7 +233,7 @@ def parse_time_period(
     return start_dt, end_dt
 
 
-def filter_df_to_period(df, start_time: str, end_time: str, tz: float):
+def filter_df_to_period(df, start_time: str, end_time: str, tz: float, daily_start_hour: Optional[int] = None, daily_end_hour: Optional[int] = None):
     """
     Filter weather DataFrame to specified time period and convert to UTC.
     
@@ -242,6 +242,11 @@ def filter_df_to_period(df, start_time: str, end_time: str, tz: float):
         start_time: Start time in format 'MM-DD HH:MM:SS'
         end_time: End time in format 'MM-DD HH:MM:SS'
         tz: Timezone offset in hours
+        daily_start_hour: Optional inclusive hour-of-day lower bound (0-23) for a
+            daily window crossed with the date range. None disables the daily filter.
+        daily_end_hour: Optional inclusive hour-of-day upper bound (0-23). None
+            disables the daily filter. Supports wraparound when start > end
+            (e.g. 22-3 spans overnight).
         
     Returns:
         Tuple of (df_period_utc, df with hour_of_year column)
@@ -269,6 +274,14 @@ def filter_df_to_period(df, start_time: str, end_time: str, tz: float):
     else:
         df_period = df[(df['hour_of_year'] >= start_hour) | (df['hour_of_year'] <= end_hour)]
 
+    # Optional daily hour-of-day window (crossed with the date range above).
+    if daily_start_hour is not None and daily_end_hour is not None:
+        hod = df_period.index.hour
+        if daily_start_hour <= daily_end_hour:
+            df_period = df_period[(hod >= daily_start_hour) & (hod <= daily_end_hour)]
+        else:  # wraparound, mirrors the continuous-span branch above
+            df_period = df_period[(hod >= daily_start_hour) | (hod <= daily_end_hour)]
+    
     if df_period.empty:
         raise ValueError("No weather data in the specified period.")
 

src/voxcity/simulator_gpu/solar/integration/volumetric.py

@@ -367,6 +367,8 @@ def get_cumulative_volumetric_solar_irradiance(
         **kwargs: Additional parameters:
             - start_time (str): Start time 'MM-DD HH:MM:SS' (default: '01-01 05:00:00')
             - end_time (str): End time 'MM-DD HH:MM:SS' (default: '01-01 20:00:00')
+            - daily_start_hour (int): Optional inclusive hour-of-day lower bound (0-23)
+            - daily_end_hour (int): Optional inclusive hour-of-day upper bound (0-23)
             - use_sky_patches (bool): Use sky patch optimization (default: True)
             - sky_discretization (str): 'tregenza', 'reinhart', 'uniform', 'fibonacci'
             - computation_mask (np.ndarray): Optional 2D boolean mask of shape (nx, ny).
@@ -382,6 +384,8 @@ def get_cumulative_volumetric_solar_irradiance(
     progress_report = kwargs.pop('progress_report', False)
     start_time = kwargs.pop('start_time', '01-01 05:00:00')
     end_time = kwargs.pop('end_time', '01-01 20:00:00')
+    daily_start_hour = kwargs.pop('daily_start_hour', None)
+    daily_end_hour = kwargs.pop('daily_end_hour', None)
     use_sky_patches = kwargs.pop('use_sky_patches', True)
     sky_discretization = kwargs.pop('sky_discretization', 'tregenza')
     n_azimuth = kwargs.pop('n_azimuth', 36)
@@ -412,6 +416,16 @@ def get_cumulative_volumetric_solar_irradiance(
     else:
         df_period = df[(df['hour_of_year'] >= start_hour) | (df['hour_of_year'] <= end_hour)]
 
+    # Optional daily hour-of-day window (crossed with the date range above).
+    # Mirrors filter_df_to_period in integration/utils.py; applied on the local
+    # naive index before UTC conversion.
+    if daily_start_hour is not None and daily_end_hour is not None:
+        hod = df_period.index.hour
+        if daily_start_hour <= daily_end_hour:
+            df_period = df_period[(hod >= daily_start_hour) & (hod <= daily_end_hour)]
+        else:  # wraparound, mirrors the continuous-span branch above
+            df_period = df_period[(hod >= daily_start_hour) | (hod <= daily_end_hour)]
+    
     if df_period.empty:
         raise ValueError("No EPW data in the specified period.")
 

tests/test_simulator_solar_temporal.py

@@ -320,3 +320,118 @@ def test_active_patches_count(self):
 
         # Only one patch should be active
         assert result['n_active_patches'] == 1
+
+
+import pandas as pd
+from voxcity.simulator_gpu.solar.integration.utils import filter_df_to_period
+
+
+def _year_df():
+    idx = pd.date_range("2000-01-01 00:00:00", "2000-12-31 23:00:00", freq="h")
+    return pd.DataFrame({"DNI": 1.0, "DHI": 1.0}, index=idx)
+
+
+def test_filter_df_daily_hour_window_crosses_date_range():
+    df = _year_df()
+    out = filter_df_to_period(
+        df, "07-01 00:00:00", "08-31 23:00:00", tz=0.0,
+        daily_start_hour=6, daily_end_hour=11,
+    )
+    hours = out.index.hour.unique().tolist()
+    assert min(hours) >= 6 and max(hours) <= 11
+    months = out.index.month.unique().tolist()
+    assert set(months) == {7, 8}
+
+
+def test_filter_df_daily_hour_wraparound():
+    df = _year_df()
+    out = filter_df_to_period(
+        df, "07-01 00:00:00", "07-02 23:00:00", tz=0.0,
+        daily_start_hour=22, daily_end_hour=3,
+    )
+    assert set(out.index.hour.unique().tolist()) <= {22, 23, 0, 1, 2, 3}
+
+
+def test_filter_df_none_daily_hours_unchanged():
+    df = _year_df()
+    out = filter_df_to_period(df, "07-01 06:00:00", "07-01 11:00:00", tz=0.0)
+    # Continuous span: all 6 hours present, no daily narrowing.
+    assert len(out) == 6
+
+
+from unittest.mock import patch
+
+
+def test_cumulative_global_forwards_daily_hours():
+    """Ground cumulative entry point must forward daily hour kwargs to filter_df_to_period."""
+    import voxcity.simulator_gpu.solar.integration as integ
+    # Patch filter_df_to_period as resolved inside the caller's own module.
+    target_module = integ.get_cumulative_global_solar_irradiance.__module__
+    with patch(f"{target_module}.filter_df_to_period") as mock_filter:
+        # Stop execution right after the filter call so no heavy work runs.
+        mock_filter.side_effect = RuntimeError("stop after filter")
+        try:
+            integ.get_cumulative_global_solar_irradiance(
+                voxcity=None, df=_year_df(), lon=0.0, lat=0.0, tz=0.0,
+                start_time="07-01 00:00:00", end_time="08-31 23:00:00",
+                daily_start_hour=6, daily_end_hour=11,
+            )
+        except Exception:
+            pass
+        assert mock_filter.called, "filter_df_to_period was not reached"
+        _, called_kwargs = mock_filter.call_args
+        assert called_kwargs.get("daily_start_hour") == 6
+        assert called_kwargs.get("daily_end_hour") == 11
+
+
+def test_cumulative_volumetric_applies_daily_hours():
+    """Volumetric cumulative entry point filters inline; verify the daily window is applied.
+
+    volumetric.get_cumulative_volumetric_solar_irradiance does NOT call
+    filter_df_to_period (it filters inline), so we prove the daily-hour bounds
+    reach the filtering by inspecting the timestamps passed to the first
+    downstream consumer (get_solar_positions_astral).
+    """
+    import voxcity.simulator_gpu.solar.integration as integ
+    mod = integ.get_cumulative_volumetric_solar_irradiance.__module__
+    captured = {}
+
+    def fake_solar_positions(index, lon, lat):
+        captured["hours"] = sorted(set(index.hour.tolist()))
+        raise RuntimeError("stop after filter")
+
+    with patch(f"{mod}.get_solar_positions_astral", side_effect=fake_solar_positions):
+        try:
+            integ.get_cumulative_volumetric_solar_irradiance(
+                voxcity=None, df=_year_df(), lon=0.0, lat=0.0, tz=0.0,
+                start_time="07-01 00:00:00", end_time="08-31 23:00:00",
+                daily_start_hour=6, daily_end_hour=11,
+            )
+        except Exception:
+            pass
+    assert captured.get("hours"), "get_solar_positions_astral was not reached"
+    assert set(captured["hours"]) == {6, 7, 8, 9, 10, 11}
+
+
+def test_building_cumulative_forwards_daily_hours():
+    """Building-surface cumulative entry point must forward daily hour kwargs
+    to filter_df_to_period."""
+    import voxcity.simulator_gpu.solar.integration.building as bld
+    with patch.object(bld, "filter_df_to_period") as mock_filter:
+        # Stop execution right after the filter call so no heavy work runs.
+        mock_filter.side_effect = RuntimeError("stop after filter")
+        try:
+            bld.get_cumulative_building_solar_irradiance(
+                voxcity=None,
+                building_svf_mesh=None,
+                weather_df=_year_df(),
+                lon=0.0, lat=0.0, tz=0.0,
+                period_start="07-01 00:00:00", period_end="08-31 23:00:00",
+                daily_start_hour=6, daily_end_hour=11,
+            )
+        except Exception:
+            pass
+        assert mock_filter.called, "filter_df_to_period was not reached"
+        _, called_kwargs = mock_filter.call_args
+        assert called_kwargs.get("daily_start_hour") == 6
+        assert called_kwargs.get("daily_end_hour") == 11