Applied changes to simplify exports and tested for SAC runs

Author: calofonseca

citylearn/agents/rbc.py

@@ -100,11 +100,26 @@ def predict(self, observations: List[List[float]], deterministic: bool = None) -
 
         else:
             for m, a, n, o in zip(self.action_map, self.action_names, self.observation_names, observations):
-                hour = o[n.index('hour')]
+                hour_observation = o[n.index('hour')]
+                hour = int(round(hour_observation))
+                # Support both 0-23 and 1-24 hour encodings.
+                hour_candidates = []
+
+                for candidate in (hour, hour % 24, ((hour - 1) % 24) + 1):
+                    if candidate not in hour_candidates:
+                        hour_candidates.append(candidate)
+
                 actions_ = []
 
                 for a_ in a:
-                    actions_.append(m[a_][hour]) 
+                    for candidate in hour_candidates:
+                        hour_map = m[a_]
+
+                        if candidate in hour_map:
+                            actions_.append(hour_map[candidate])
+                            break
+                    else:
+                        raise KeyError(f'Hour {hour_observation} not defined in action map for action {a_}.')
 
                 actions.append(actions_)
 

citylearn/citylearn.py

@@ -157,13 +157,14 @@ def __init__(self,
         if requested_render_mode not in {'none', 'during', 'end'}:
             raise ValueError("render_mode must be one of {'none', 'during', 'end'}.")
         self.render_mode = requested_render_mode
-        self._buffer_render = self.render_mode == 'end'
-        self._defer_render_flush = False
-        self._render_buffer = defaultdict(list)
-        self._render_start_date = self._parse_render_start_date(start_date if start_date is not None else schema_start_date)
-        self.previous_month = None
-        self.current_day = self._render_start_date.day
-        self.year = self._render_start_date.year
+        self._buffer_render = self.render_mode == 'end'
+        self._defer_render_flush = False
+        self._render_buffer = defaultdict(list)
+        self._render_start_date = self._parse_render_start_date(start_date if start_date is not None else schema_start_date)
+        self.previous_month = None
+        self.current_day = self._render_start_date.day
+        self.year = self._render_start_date.year
+        self._final_kpis_exported = False
         self.__rewards = None
         self.buildings = []
         self.random_seed = self.schema.get('random_seed', None) if random_seed is None else random_seed
@@ -1025,8 +1026,11 @@ def step(self, actions: List[List[float]]) -> Tuple[List[List[float]], List[floa
         # Advance to next timestep t+1
         self.next_time_step()
 
-        # store episode reward summary at the end of episode (upon reaching final timestep)
+        # store episode reward summary at the end of episode (upon reaching final timestep)
         if self.terminated:
+            if self.render_mode == 'during' and self.render_enabled:
+                # Capture the terminal timestep snapshot that occurs after the final transition.
+                self.render()
             rewards = np.array(self.__rewards[1:], dtype='float32')
             self.__episode_rewards.append({
                 'min': rewards.min(axis=0).tolist(),
@@ -1046,6 +1050,9 @@ def step(self, actions: List[List[float]]) -> Tuple[List[List[float]], List[floa
 
                 self._flush_render_buffer()
 
+            if self.render_enabled and not self._final_kpis_exported:
+                self.export_final_kpis()
+
         return self.observations, reward, self.terminated, self.truncated, self.get_info()
 
     def get_info(self) -> Mapping[Any, Any]:
@@ -1467,17 +1474,30 @@ def simulate_unconnected_ev_soc(self):
                     new_soc = np.clip(last_soc * variability, 0.0, 1.0)
                     ev.battery.force_set_soc(new_soc)
 
-    def export_final_kpis(self, model: 'citylearn.agents.base.Agent', filepath="exported_kpis.csv"):
-        # Ensure output directory exists even if rendering was disabled
-        self._ensure_render_output_dir()
-        file_path = os.path.join(self.new_folder_path, filepath)
-        kpis = model.env.evaluate()
-        kpis = kpis.pivot(index='cost_function', columns='name', values='value').round(3)
-        kpis = kpis.dropna(how='all')
-        kpis = kpis.fillna('')
-        kpis = kpis.reset_index()
-        kpis = kpis.rename(columns={'cost_function': 'KPI'})
-        kpis.to_csv(file_path, index=False, encoding='utf-8')
+    def export_final_kpis(self, model: 'citylearn.agents.base.Agent' = None, filepath: str = "exported_kpis.csv"):
+        """Export episode KPIs to csv.
+
+        Parameters
+        ----------
+        model: citylearn.agents.base.Agent, optional
+            Agent whose environment should be evaluated. Defaults to the current environment.
+        filepath: str, default: ``"exported_kpis.csv"``
+            Output filename placed inside :pyattr:`new_folder_path`.
+        """
+        # Ensure output directory exists even if rendering was disabled
+        self._ensure_render_output_dir()
+        file_path = os.path.join(self.new_folder_path, filepath)
+        if model is not None and getattr(model, 'env', None) is not None:
+            kpis = model.env.evaluate()
+        else:
+            kpis = self.evaluate()
+        kpis = kpis.pivot(index='cost_function', columns='name', values='value').round(3)
+        kpis = kpis.dropna(how='all')
+        kpis = kpis.fillna('')
+        kpis = kpis.reset_index()
+        kpis = kpis.rename(columns={'cost_function': 'KPI'})
+        kpis.to_csv(file_path, index=False, encoding='utf-8')
+        self._final_kpis_exported = True
 
     def render(self):
         """
@@ -1719,24 +1739,25 @@ def _get_series_value(series, index, default):
         next_hour = _get_series_value(hour_series, next_index, hour)
         next_minutes = _get_series_value(minutes_series, next_index, minutes)
 
+        raw_hour = hour
         timestamp_year = self.year
         timestamp_month = month
         timestamp_day = self.current_day
-        hour_for_timestamp = hour % 24
+        hour_for_timestamp = raw_hour % 24
+        next_hour_mod = next_hour % 24
+        next_minutes_clamped = max(0, min(59, next_minutes))
         minute_for_timestamp = max(0, min(59, minutes))
 
-        if hour >= 24:
-            hour_for_timestamp = hour % 24
-
+        if raw_hour >= 24:
             if next_month != month:
                 timestamp_month = next_month
-                
+
                 if next_month < month:
                     timestamp_year = self.year + 1
                 timestamp_day = 1
-
             else:
-                timestamp_day = self.current_day + (hour // 24)
+                # Keep the current day; the day roll-over is handled via next_day logic.
+                timestamp_day = self.current_day
 
         timestamp = f"{timestamp_year:04d}-{int(timestamp_month):02d}-{timestamp_day:02d}T{hour_for_timestamp:02d}:{minute_for_timestamp:02d}:00"
 
@@ -1747,7 +1768,7 @@ def _get_series_value(series, index, default):
             if next_month < month:
                 next_year = timestamp_year + 1
             next_day = 1
-        elif next_hour <= hour:
+        elif next_hour_mod <= hour_for_timestamp and next_minutes_clamped <= minute_for_timestamp:
             next_day = timestamp_day + 1
 
         self.year = next_year
@@ -1826,8 +1847,9 @@ def reset(self, seed: int = None, options: Mapping[str, Any] = None) -> Tuple[Li
             Override :meth"`get_info` to get custom key-value pairs in `info`.
         """
 
-        # object reset
-        super().reset()
+        # object reset
+        super().reset()
+        self._final_kpis_exported = False
 
         # update seed
         if seed is not None:
@@ -1929,21 +1951,24 @@ def load_agent(self, agent: Union[str, 'citylearn.agents.base.Agent'] = None, **
         else:
             agent_type = self.schema['agent']['type']
 
-        if kwargs is not None and len(kwargs) > 0:
-            agent_attributes = kwargs
-
-        elif agent is None:
-            agent_attributes = self.schema['agent'].get('attributes', {})
-
-        else:
-            agent_attributes = None
-
-        agent_module = '.'.join(agent_type.split('.')[0:-1])
-        agent_name = agent_type.split('.')[-1]
-        agent_constructor = getattr(importlib.import_module(agent_module), agent_name)
-        agent = agent_constructor() if agent_attributes is None else agent_constructor(**agent_attributes)
-
-        return agent
+        if kwargs is not None and len(kwargs) > 0:
+            agent_attributes = dict(kwargs)
+
+        elif agent is None:
+            agent_attributes = dict(self.schema['agent'].get('attributes', {}))
+
+        else:
+            agent_attributes = {}
+
+        if 'env' not in agent_attributes:
+            agent_attributes['env'] = self
+
+        agent_module = '.'.join(agent_type.split('.')[0:-1])
+        agent_name = agent_type.split('.')[-1]
+        agent_constructor = getattr(importlib.import_module(agent_module), agent_name)
+        agent = agent_constructor(**agent_attributes)
+
+        return agent
 
     def _load(self, schema: Mapping[str, Any], **kwargs) -> Tuple[Union[Path, str], List[Building], List[ElectricVehicle], Union[int, List[Tuple[int, int]]], bool, bool, float, RewardFunction, bool, List[str], EpisodeTracker]:
         """Return `CityLearnEnv` and `Controller` objects as defined by the `schema`.

docs/source/ui.rst

@@ -18,12 +18,13 @@ You can check a tutorial at the official CityLearn `website <https://intelligent
 Exporting Data From CityLearn into CityLearn UI
 ===============================================
 
-CityLearn automatically exports the folder structure expected by the UI. There are a few workflows to consider:
+CityLearn automatically exports the folder structure expected by the UI. The behaviour depends on :class:`citylearn.citylearn.CityLearnEnv` ``render_mode``:
 
-* ``render_mode='none'`` (default): no CSVs are produced, so the UI cannot ingest data.
-* ``render_mode='during'``: data is exported every simulation step into timestamped folders. You may keep the default location (``<project>/SimulationData/<timestamp>``) or set ``render_directory``/``render_directory_name``/:code:`render_session_name` on :class:`citylearn.citylearn.CityLearnEnv` to choose the destination and a custom subfolder.
-* ``render_mode='end'`` (buffered): the environment records each step in memory and automatically flushes the complete episode to disk when the episode finishes (or when you call :meth:`citylearn.citylearn.CityLearnEnv.render`). This produces the same per-timestep CSVs as the ``'during'`` mode but defers file I/O until the end.
-* ``render_mode='none'`` with explicit export: keep rendering off for faster runs and call :meth:`citylearn.citylearn.CityLearnEnv.export_final_kpis` (or a custom exporter) at the end. This lazily creates the render folder and only writes KPI summaries—suitable for the UI **KPIs page** but not for the time-series dashboards.
+* ``render_mode='none'`` (default): no CSVs are produced. Use this for fast headless runs where you do not need UI data, or call :meth:`citylearn.citylearn.CityLearnEnv.export_final_kpis` manually afterwards to obtain the KPI table only.
+* ``render_mode='during'``: the environment writes a row for every simulation step directly to disk (``<project>/SimulationData/<timestamp>`` by default). Final KPIs are appended automatically once the episode ends—no extra script code is required.
+* ``render_mode='end'``: per-step rows are buffered in memory and flushed to disk when the episode finishes (or whenever :meth:`~citylearn.citylearn.CityLearnEnv.render` is invoked). As with ``'during'``, the KPI export is triggered automatically at the end of the episode.
+
+You can customise the export location with ``render_directory``, ``render_directory_name`` and/or ``render_session_name`` when constructing the environment. When a session name is provided the folder is reused across runs; otherwise a timestamped folder is created.
 
 Per-Step Export Example
 -----------------------
@@ -50,7 +51,7 @@ Per-Step Export Example
         observations, reward, terminated, truncated, info = env.step(actions)
         # CSV rows are appended at each step when render_mode='during'.
 
-The code above writes per-step CSV files into ``outputs/ui_exports/<timestamp>/``. Omitting ``render_directory`` stores the results in ``SimulationData/<timestamp>/`` by default.
+The code above writes per-step CSV files into ``outputs/ui_exports/<timestamp>/``. Omitting ``render_directory`` stores the results in ``SimulationData/<timestamp>/`` by default, and the episode summary KPIs are written automatically to ``exported_kpis.csv``.
 
 Export-at-the-End Example
 -------------------------
@@ -100,16 +101,7 @@ Buffered End-of-Run Export Example
         actions = [env.action_space[0].sample()]
         observations, reward, terminated, truncated, info = env.step(actions)
 
-    # Episode completion automatically flushes the buffered CSVs.
-    # Call env.render() mid-run if you need an interim snapshot.
-    class _Model:
-        pass
-
-    model = _Model()
-    model.env = env
-    env.export_final_kpis(model)
-
-With ``render_mode='end'`` the per-step histories accumulate in memory while the episode runs. At episode completion the environment writes the full SimulationData folder (all timesteps plus components); you may still call :meth:`~citylearn.citylearn.CityLearnEnv.render` manually if you want to force a flush earlier than that.
+With ``render_mode='end'`` the per-step histories accumulate in memory while the episode runs. At episode completion the environment writes the full SimulationData folder (all timesteps plus components) and the KPI summary; you may still call :meth:`~citylearn.citylearn.CityLearnEnv.render` manually if you want to force a flush earlier than that.
 
 The UI consumes the directory produced by the ``'during'`` and ``'end'`` approaches. The system uses the :meth:`~citylearn.citylearn.CityLearnEnv.render` method to iterate over buildings, electric vehicles, batteries, chargers, pricing, etc., using their ``as_dict`` outputs to build CSV histories where each row corresponds to a time instant and columns include units. Timestamps are converted to calendar dates for display. You can disable step-wise exporting by keeping ``render_mode='none'`` and relying on the end-of-run exporter, but the resulting folder will only serve the KPI comparison page.
 

tests/scripts/run_ev_rbc_export_end.py

@@ -43,9 +43,6 @@ def main() -> None:
             if terminated or truncated:
                 break
 
-        print("Exporting simulation data. This may take a moment...")
-        env.export_final_kpis(controller)
-
         outputs_path = Path(env.new_folder_path)
         print(f"Exports written to: {outputs_path}")
     finally:

tests/scripts/run_ev_rbc_export_mid.py

@@ -32,20 +32,14 @@ def main() -> None:
     try:
         controller = Agent(env)
         observations, _ = env.reset()
-        mid_step = env.episode_tracker.episode_time_steps // 2
 
-        for step in range(env.episode_tracker.episode_time_steps):
+        for _ in range(env.episode_tracker.episode_time_steps):
             actions = controller.predict(observations, deterministic=True)
             observations, _, terminated, truncated, _ = env.step(actions)
 
-            if step == mid_step:
-                env.render()
-
             if terminated or truncated:
                 break
 
-        env.export_final_kpis(controller)
-
         outputs_path = Path(env.new_folder_path)
         print(f"Exports written to: {outputs_path}")
     finally:

tests/scripts/run_sac_training_export.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Run a short SAC training episode and verify automatic exports."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from citylearn.citylearn import CityLearnEnv  # noqa: E402
+
+SCHEMA = "baeda_3dem"
+
+
+def main() -> None:
+    logging.getLogger().setLevel(logging.WARNING)
+
+    render_root = ROOT / "SimulationData"
+    env = CityLearnEnv(
+        SCHEMA,
+        episode_time_steps=96,
+        render_mode="end",
+        render_directory=render_root,
+        render_session_name="sac_export_example",
+        random_seed=0,
+    )
+
+    try:
+        agent = env.load_agent()
+        agent.learn(episodes=1, deterministic_finish=False, logging_level=logging.INFO)
+        outputs_path = Path(env.new_folder_path)
+        print(f"Exports written to: {outputs_path}")
+    finally:
+        env.close()
+
+
+if __name__ == "__main__":
+    main()