Merge pull request #148 from Soft-CPS-Research-Group/master

Fixing identified #145, testing and adding toggles for rendering data for the UI

Author: calofonseca

.gitignore

@@ -123,6 +123,12 @@ ENV/
 env.bak/
 venv.bak/
 *env/
+# Virtual envs (stray names with tilde)
+venv~/
+**/venv~/
+
+# Editor backup files (just in case)
+*~
 
 # Spyder project settings
 .spyderproject
@@ -174,3 +180,7 @@ examples/*
 
 # ignore folder
 .ignore
+
+# Simulation outputs
+render_logs/
+results/

README.md

@@ -16,4 +16,19 @@ pip install CityLearn
 ```
 
 ## Documentation
-Refer to the [docs](https://intelligent-environments-lab.github.io/CityLearn/).
+Refer to the [docs](https://intelligent-environments-lab.github.io/CityLearn/).
+
+## CityLearn UI
+
+CityLearn UI is a visual dashboard for exploring simulation data generated by the CityLearn framework. It was developed to simplify the analysis of results from smart energy communities, district energy coordination, demand response (among other applications), allowing users to visually inspect building-level components, compare simulation KPIs, and create simulation schemas with ease.
+
+The interface is available in two options:
+
+* Web app: https://citylearn-ui.softcps.org (free hosted version — not recommended for sensitive/personal data)
+* Open-source code: https://github.com/SoftCPS/citylearn-ui
+
+You can check a tutorial at the official CityLearn [website](https://intelligent-environments-lab.github.io/CityLearn/ui.html) or in the CityLearn UI repository README.
+
+**Compatibility:** This version of the UI currently supports CityLearn v2.4 simulation data.
+
+**Developed by:** SoftCPS, Software for Cyber-Physical Systems (SoftCPS) research group (ISEP, Portugal) in collaboration with the Intelligent Environments Lab, University of Texas at Austin.

citylearn/building.py

@@ -439,13 +439,16 @@ def __init__(
         if time_delta < 0:
                 time_delta += 1440    
 
+        base_step_seconds = None
+
+        if time_delta is not None:
+            # Convert dataset spacing to seconds (guard against zero/negative values)
+            candidate = max(1, time_delta * 60)
+            base_step_seconds = candidate
+
         time_step_ratio = (
-            # Computes the ratio of the current time step (in seconds) relative to:
-            # - 1 hour (3600s) if time_delta ≤ 1 hour, OR
-            # - time_delta (converted to seconds) if time_delta > 1 hour
-            # Returns None if either time_delta or seconds_per_time_step is missing
-            seconds_per_time_step / max(3600, time_delta * 60)
-            if time_delta is not None and seconds_per_time_step
+            seconds_per_time_step / base_step_seconds
+            if seconds_per_time_step and base_step_seconds
             else None
         )
         time_step_ratios.append(time_step_ratio)
@@ -814,4 +817,4 @@ def parse_profile(profile_str):
                 return np.array([], dtype=float)
 
 
-        self.load_profile = np.array([parse_profile(lp) for lp in load_profile], dtype=object)
+        self.load_profile = np.array([parse_profile(lp) for lp in load_profile], dtype=object)

citylearn/citylearn.py

@@ -5,7 +5,10 @@
 from typing import Any, Dict, Iterable, List, Mapping, Tuple, Union
 import numpy as np
 import pandas as pd
-from PySAM import Pvwattsv8
+try:
+    from PySAM import Pvwattsv8
+except ModuleNotFoundError:  # pragma: no cover - optional dependency
+    Pvwattsv8 = None
 from citylearn.base import Environment, EpisodeTracker
 from citylearn.data import DataSet, ZERO_DIVISION_PLACEHOLDER, EnergySimulation, WashingMachineSimulation
 np.seterr(divide='ignore', invalid='ignore')
@@ -536,7 +539,9 @@ def autosize(self, demand: float, epw_filepath: Union[Path, str], use_sample_tar
 
         for i in range(tries):
             self._autosize_config = sizing_data.sample(1, random_state=random_seed + i).iloc[0].to_dict()
-            model = Pvwattsv8.default('PVWattsNone')
+            if Pvwattsv8 is None:
+                raise ModuleNotFoundError('PySAM is required for PV sizing but is not installed.')
+            model = Pvwattsv8.default('PVWattsNone')
             pv_nominal_power = self.autosize_config['nameplate_capacity_module_1']/1000.0
             model.SystemDesign.system_capacity = pv_nominal_power
             model.SystemDesign.dc_ac_ratio = self.autosize_config['inverter_loading_ratio']
@@ -660,11 +665,11 @@ def energy_init(self) -> float:
             return max(0.0, self.__soc[self.time_step]*self.capacity*(1 - self.loss_coefficient))
         return max(0.0, self.__soc[self.time_step - 1]*self.capacity*(1 - self.loss_coefficient))
 
-    @property
-    def energy_balance(self) -> np.ndarray:
-        r"""Charged/discharged energy time series in [kWh]."""
-
-        return self.__energy_balance * self.time_step_ratio
+    @property
+    def energy_balance(self) -> np.ndarray:
+        r"""Charged/discharged energy time series in [kWh]."""
+
+        return self.__energy_balance
 
     @property
     def round_trip_efficiency(self) -> float:
@@ -756,10 +761,11 @@ def set_energy_balance(self, energy: float, energy_init:float) -> float:
         actual energy charged/discharged irrespective of what is determined in the step function after taking into account storage design limits 
         e.g. maximum power input/output, capacity.
         """
-        energy = energy * self.time_step_ratio
-        energy -= energy_init
-        energy_balance = energy/self.round_trip_efficiency if energy >= 0 else energy*self.round_trip_efficiency
-        return energy_balance
+        delta_energy = energy - energy_init
+        if delta_energy >= 0:
+            return delta_energy / self.round_trip_efficiency
+
+        return delta_energy * self.round_trip_efficiency
 
     def autosize(self, demand: Iterable[float], safety_factor: Union[float, Tuple[float, float]] = None) -> float:
         r"""Autosize `capacity`.
@@ -1389,4 +1395,4 @@ def render_simulation_end_data(self) -> dict:
         return {
             "simulation_name": self.name if self.name else "WashingMachineSimulation",
             "data": time_steps
-        }
+        }

citylearn/data.py

@@ -18,9 +18,11 @@ class RewardFunction:
         Other keyword arguments for custom reward calculation.
     """
 
-    def __init__(self, env_metadata: Mapping[str, Any], exponent: float = None, **kwargs):
-        self.env_metadata = env_metadata
-        self.exponent = exponent
+    def __init__(self, env_metadata: Mapping[str, Any], exponent: float = None, **kwargs):
+        penalty_coefficient = kwargs.pop('charging_constraint_penalty_coefficient', None)
+        self.env_metadata = env_metadata
+        self.exponent = exponent
+        self.charging_constraint_penalty_coefficient = penalty_coefficient
 
     @property
     def env_metadata(self) -> Mapping[str, Any]:
@@ -41,8 +43,19 @@ def exponent(self) -> float:
         return self.__exponent
 
     @exponent.setter
-    def exponent(self, exponent: float):
-        self.__exponent = 1.0 if exponent is None else exponent
+    def exponent(self, exponent: float):
+        self.__exponent = 1.0 if exponent is None else exponent
+
+    @property
+    def charging_constraint_penalty_coefficient(self) -> float:
+        return getattr(self, '_charging_constraint_penalty_coefficient', 1.0)
+
+    @charging_constraint_penalty_coefficient.setter
+    def charging_constraint_penalty_coefficient(self, coefficient: float):
+        if coefficient is None:
+            self._charging_constraint_penalty_coefficient = 1.0
+        else:
+            self._charging_constraint_penalty_coefficient = float(coefficient)
 
     def reset(self):
         """Use to reset variables at the start of an episode."""
@@ -379,40 +392,56 @@ class Electric_Vehicles_Reward_Function(MARL):
     Only affects EV-related behavior; other building logic comes from the superclass.
     """
 
-    def __init__(self, env_metadata: Mapping[str, Any], weights: Mapping[str, float] = None):
-        super().__init__(env_metadata)
-
-        # Default tunable weights for EV-related reward components
-        self.weights = weights or {
-            "no_car_charging": -5.0,
-            "battery_limits": -2.0,
-            "soc_impossible": -10.0,
-            "soc_under": -5.0,
-            "close_soc": 10.0,
-            "self_ev_consumption": 5.0,
-            "extra_self_production": 5.0,
-        }
-
-    def calculate(self, observations: List[Mapping[str, Union[int, float, dict]]]) -> List[float]:
-        current_reward = super().calculate(observations)
-        reward_list = []
-
-        for i, o in enumerate(observations):
-            ev_info = o.get("electric_vehicles_chargers_dict", {})
-            if not ev_info:
-                reward=0
-            else:
-                if self.central_agent:
-                    reward_value = current_reward[0] if isinstance(current_reward, list) else current_reward
-                    reward = self.calculate_ev_penalty(o, reward_value)
-                else:
-                    reward = self.calculate_ev_penalty(o, current_reward[i])
-
-            reward_list.append(reward)
-
-        total_reward = [sum(reward_list)] if self.central_agent else reward_list
-        LOGGER.info(f"Calculated EV reward: {total_reward}")
-        return total_reward
+    def __init__(self, env_metadata: Mapping[str, Any], weights: Mapping[str, float] = None):
+        super().__init__(env_metadata)
+
+        # Default tunable weights for EV-related reward components
+        self.weights = weights or {
+            "no_car_charging": -5.0,
+            "battery_limits": -2.0,
+            "soc_impossible": -10.0,
+            "soc_under": -5.0,
+            "close_soc": 10.0,
+            "self_ev_consumption": 5.0,
+            "extra_self_production": 5.0,
+        }
+        self._last_base_reward_total = 0.0
+        self._last_penalty_total = 0.0
+        self._last_base_rewards_per_building: List[float] = []
+        self._last_penalties_per_building: List[float] = []
+
+    def calculate(self, observations: List[Mapping[str, Union[int, float, dict]]]) -> List[float]:
+        current_reward = super().calculate(observations)
+        reward_list = []
+        base_rewards = []
+        penalty_values = []
+
+        for i, o in enumerate(observations):
+            ev_info = o.get("electric_vehicles_chargers_dict", {})
+            if not ev_info:
+                reward = 0
+            else:
+                if self.central_agent:
+                    reward_value = current_reward[0] if isinstance(current_reward, list) else current_reward
+                    reward = self.calculate_ev_penalty(o, reward_value)
+                else:
+                    reward = self.calculate_ev_penalty(o, current_reward[i])
+
+            base_rewards.append(reward)
+            violation = float(o.get("charging_constraint_violation_kwh", 0.0) or 0.0)
+            penalty = violation * self.charging_constraint_penalty_coefficient if violation > 0.0 else 0.0
+            penalty_values.append(penalty)
+            reward -= penalty
+
+            reward_list.append(reward)
+
+        self._last_base_rewards_per_building = base_rewards
+        self._last_penalties_per_building = penalty_values
+        total_reward = [sum(reward_list)] if self.central_agent else reward_list
+        self._last_base_reward_total = sum(base_rewards) if self.central_agent else base_rewards
+        self._last_penalty_total = sum(penalty_values) if self.central_agent else penalty_values
+        LOGGER.info(f"Calculated EV reward: {total_reward}")
+        return total_reward
 
     def calculate_ev_penalty(self, o: Mapping[str, Union[int, float, dict]], current_reward: float) -> float:
 
@@ -437,7 +466,9 @@ def calculate_ev_penalty(self, o: Mapping[str, Union[int, float, dict]], current
             soc_now = data.get("battery_soc")
             capacity = data.get("battery_capacity")
             min_capacity = data.get("min_capacity")
-            last_charged_kwh = data.get("last_charged_kwh", 0)
+            last_charged_kwh = data.get("last_charged_kwh", 0)
+            if last_charged_kwh is None:
+                last_charged_kwh = 0.0
             required_soc = data.get("required_soc")
             hours_until_departure = data.get("hours_until_departure", 0)
             max_charging_power = data.get("max_charging_power", 0)
@@ -446,8 +477,8 @@ def calculate_ev_penalty(self, o: Mapping[str, Union[int, float, dict]], current
             if soc_prev is None or soc_now is None or capacity is None:
                 raise ValueError("Something went wrong, this values should not be none")
                 continue
-            # Battery limits
-            current_energy = soc_prev * capacity + last_charged_kwh
+            # Battery limits
+            current_energy = soc_prev * capacity + last_charged_kwh
             if current_energy > capacity or current_energy < min_capacity:
                 contributions["battery_limits"] += self.weights["battery_limits"] * penalty_multiplier
 

citylearn/energy_model.py

@@ -0,0 +1,61 @@
+"""Tests for timestep alignment and EV charger integration."""
+
+from pathlib import Path
+import math
+import numpy as np
+import pytest
+
+from citylearn.citylearn import CityLearnEnv
+
+
+DATASET = Path(__file__).resolve().parents[2] / 'data/datasets/citylearn_challenge_2022_phase_all_plus_evs/schema.json'
+
+
+def _finite(value):
+    if isinstance(value, (list, tuple, np.ndarray)):
+        return np.all(np.isfinite(value))
+
+    return math.isfinite(float(value))
+
+
+def test_timestep_and_chargers():
+    env = CityLearnEnv(str(DATASET), central_agent=True)
+
+    try:
+        obs, _ = env.reset()
+        zeros = np.zeros(env.action_space[0].shape[0], dtype='float32')
+
+        obs, r0, term, trunc, _ = env.step([zeros])
+        assert env.time_step == 1
+        assert _finite(r0)
+
+        names = env.action_names[0]
+        charger_index = next((i for i, name in enumerate(names) if name.startswith('electric_vehicle_storage_')), None)
+
+        if charger_index is None:
+            pytest.skip('Dataset does not expose EV storage actions.')
+
+        actions = np.zeros_like(zeros)
+        actions[charger_index] = 0.1
+
+        obs, r1, term, trunc, _ = env.step([actions])
+        assert env.time_step == 2
+        assert _finite(r1)
+
+        building = env.buildings[0]
+        t = env.time_step - 1
+        lhs = building.net_electricity_consumption[t]
+        rhs = (
+            building.cooling_electricity_consumption[t]
+            + building.heating_electricity_consumption[t]
+            + building.dhw_electricity_consumption[t]
+            + building.non_shiftable_load_electricity_consumption[t]
+            + building.electrical_storage_electricity_consumption[t]
+            + building.solar_generation[t]
+            + building.chargers_electricity_consumption[t]
+            + building.washing_machines_electricity_consumption[t]
+        )
+        assert abs(lhs - rhs) < 1e-4
+
+    finally:
+        env.close()