CityLearn 2.4.0__tar.gz → 2.4.2__tar.gz

{CityLearn-2.4.0 → CityLearn-2.4.2}/CityLearn.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CityLearn
-Version: 2.4.0
+Version: 2.4.2
 Summary: An open source Farama Foundation Gymnasium environment for benchmarking distributed energy resource control algorithms to provide energy flexibility in a district of buildings.
 Home-page: https://github.com/intelligent-environments-lab/CityLearn
 Author: Jose Ramon Vazquez-Canteli, Kingsley Nweye, Zoltan Nagy

{CityLearn-2.4.0 → CityLearn-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CityLearn
-Version: 2.4.0
+Version: 2.4.2
 Summary: An open source Farama Foundation Gymnasium environment for benchmarking distributed energy resource control algorithms to provide energy flexibility in a district of buildings.
 Home-page: https://github.com/intelligent-environments-lab/CityLearn
 Author: Jose Ramon Vazquez-Canteli, Kingsley Nweye, Zoltan Nagy

CityLearn-2.4.2/citylearn/__init__.py

@@ -0,0 +1 @@
+__version__ = '2.4.2'

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/__main__.py

@@ -18,7 +18,7 @@ from citylearn.agents.base import Agent as CityLearnAgent
 from citylearn.citylearn import CityLearnEnv
 from citylearn.data import DataSet, get_settings
 from citylearn.__init__ import __version__
-from citylearn.utilities import read_pickle, write_json, write_pickle
+from citylearn.utilities import FileHandler
 import pandas as pd
 import simplejson as json
 
@@ -291,7 +291,7 @@ class Simulator:
     def __save_agent(self):
         if isinstance(self.agent, CityLearnAgent):
             filepath = os.path.join(self.output_directory, f'{self.simulation_id}-agent.pkl')
-            write_pickle(filepath, self.agent)
+            FileHandler.write_pickle(filepath, self.agent)
         
         else:
             filepath = os.path.join(self.output_directory, f'{self.simulation_id}-agent')
@@ -307,7 +307,7 @@ class Simulator:
 
         else:
             if str(self.agent_filepath).endswith('.pkl'):
-                agent = read_pickle(self.agent_filepath)
+                agent = FileHandler.read_pickle(self.agent_filepath)
                 agent.env = self.env
 
             else:
@@ -349,7 +349,7 @@ class Simulator:
         simulator = cls(**kwargs)
         simulator.__evaluate()
         filepath = os.path.join(simulator.output_directory, f'{simulator.simulation_id}-evaluation.json')
-        write_json(filepath, simulator.__get_evaluation_summary())
+        FileHandler.write_json(filepath, simulator.__get_evaluation_summary())
 
     @classmethod
     def train(cls, episodes: int = None, evaluate: bool = None, evaluation_episode_time_steps: Tuple[int, int] = None, save_agent: bool = None, **kwargs):
@@ -357,7 +357,7 @@ class Simulator:
         episodes = 1 if episodes is None else episodes
         simulator.__train(episodes)
         filepath = os.path.join(simulator.output_directory, f'{simulator.simulation_id}-train.json')
-        write_json(filepath, simulator.__get_training_summary())
+        FileHandler.write_json(filepath, simulator.__get_training_summary())
 
         if save_agent:
             simulator.__save_agent()

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/building.py

@@ -1356,8 +1356,6 @@ class Building(Environment):
 
             except NotImplementedError:
                 pass
-        
-        self.update_variables()
 
     def update_cooling_demand(self, action: float):
         """Update space cooling demand for current time step."""
@@ -2243,8 +2241,6 @@ class Building(Environment):
         self.__chargers_electricity_consumption = np.zeros(self.episode_tracker.episode_time_steps, dtype='float32')
         self.__washing_machines_electricity_consumption = np.zeros(self.episode_tracker.episode_time_steps, dtype='float32')
 
-        self.update_variables()
-
     def reset_power_outage_signal(self) -> np.ndarray:
         """Resets power outage signal time series.
         

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/citylearn.py

@@ -10,7 +10,6 @@ from gymnasium import Env, spaces
 import csv
 import shutil
 import datetime
-from itertools import zip_longest
 import numpy as np
 import pandas as pd
 import random
@@ -21,7 +20,7 @@ from citylearn.data import CarbonIntensity, DataSet, ChargerSimulation, EnergySi
 from citylearn.electric_vehicle import ElectricVehicle
 from citylearn.energy_model import Battery, PV, WashingMachine
 from citylearn.reward_function import MultiBuildingRewardFunction, RewardFunction
-from citylearn.utilities import read_json
+from citylearn.utilities import FileHandler
 
 LOGGER = logging.getLogger()
 logging.getLogger('matplotlib.font_manager').disabled = True
@@ -796,7 +795,7 @@ class CityLearnEnv(Environment, Env):
 
         if isinstance(schema, (str, Path)) and os.path.isfile(schema):
             schema_filepath = Path(schema) if isinstance(schema, str) else schema
-            schema = read_json(schema)
+            schema = FileHandler.read_json(schema)
             schema['root_directory'] = os.path.split(schema_filepath.absolute())[0] if schema['root_directory'] is None \
                 else schema['root_directory']
         
@@ -1454,6 +1453,9 @@ class CityLearnEnv(Environment, Env):
         return self.observations, self.get_info()
 
     def update_variables(self):
+        for b in self.buildings:
+            b.update_variables()
+
         # net electricity consumption
         self.__net_electricity_consumption.append(sum([b.net_electricity_consumption[self.time_step] for b in self.buildings]))
 

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/data.py

@@ -10,9 +10,7 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 from citylearn.__init__ import __version__
-from citylearn.utilities import join_url, read_json, read_yaml, write_json
-from citylearn.utilities import read_json, read_yaml, write_json
-from citylearn.utils.noise import NoiseUtils
+from citylearn.utilities import FileHandler, NoiseUtils
 
 LOGGER = logging.getLogger()
 logging.basicConfig(level=logging.INFO)
@@ -26,7 +24,7 @@ SETTINGS_FILEPATH = os.path.join(MISC_DIRECTORY, 'settings.yaml')
 def get_settings():
     directory = os.path.join(os.path.join(os.path.dirname(__file__), 'misc'))
     filepath = os.path.join(directory, 'settings.yaml')
-    settings = read_yaml(filepath)
+    settings = FileHandler.read_yaml(filepath)
 
     return settings
 
@@ -36,10 +34,10 @@ class DataSet:
     GITHUB_ACCOUNT = 'intelligent-environments-lab'
     REPOSITORY_NAME = 'CityLearn'
     REPOSITORY_TAG = f'v{__version__}'
-    REPOSITORY_DATA_PATH = join_url('data')
-    REPOSITORY_DATA_DATASETS_PATH = join_url(REPOSITORY_DATA_PATH, 'datasets')
-    REPOSITORY_DATA_MISC_PATH = join_url(REPOSITORY_DATA_PATH, 'misc')
-    GITHUB_API_CONTENT_URL = join_url('https://api.github.com/repos/', GITHUB_ACCOUNT, REPOSITORY_NAME, 'contents')
+    REPOSITORY_DATA_PATH = FileHandler.join_url('data')
+    REPOSITORY_DATA_DATASETS_PATH = FileHandler.join_url(REPOSITORY_DATA_PATH, 'datasets')
+    REPOSITORY_DATA_MISC_PATH = FileHandler.join_url(REPOSITORY_DATA_PATH, 'misc')
+    GITHUB_API_CONTENT_URL = FileHandler.join_url('https://api.github.com/repos/', GITHUB_ACCOUNT, REPOSITORY_NAME, 'contents')
     DEFAULT_CACHE_DIRECTORY = os.path.join(user_cache_dir('citylearn'), REPOSITORY_TAG)
     BATTERY_CHOICES_FILENAME = 'battery_choices.yaml'
     PV_CHOICES_FILENAME = 'lbl-tracking_the_sun-res-pv.csv'
@@ -114,7 +112,7 @@ class DataSet:
 
     def get_schema(self, name: str) -> dict:
         schema_filepath = self.get_dataset(name)
-        schema = read_json(schema_filepath)
+        schema = FileHandler.read_json(schema_filepath)
         schema['root_directory'] = os.path.split(Path(schema_filepath).absolute())[0]
 
         return schema
@@ -123,7 +121,7 @@ class DataSet:
         datasets_directory = os.path.join(self.cache_directory, 'datasets')
         root_directory = os.path.join(datasets_directory, name)
         schema_filepath = os.path.join(root_directory, 'schema.json')
-        path = join_url(self.datasets_path, name)
+        path = FileHandler.join_url(self.datasets_path, name)
 
         # check that dataset does not already exist using the schema as a proxy
         LOGGER.info(f'Go here {schema_filepath} ')
@@ -172,7 +170,7 @@ class DataSet:
         filepath = os.path.join(self.cache_directory, 'dataset_names.json')
 
         if os.path.isfile(filepath):
-            contents = read_json(filepath)
+            contents = FileHandler.read_json(filepath)
         
         else:
             LOGGER.info(f'The dataset names DNE in cache. Will download from '
@@ -184,7 +182,7 @@ class DataSet:
                     if r.get('type') == 'dir' 
                         and r.get('path').replace(r['name'], '').strip('/') == self.datasets_path
             ]
-            write_json(filepath, contents)
+            FileHandler.write_json(filepath, contents)
             
         contents = sorted(contents)
 
@@ -201,7 +199,7 @@ class DataSet:
         misc_directory = os.path.join(self.cache_directory, 'misc')
         os.makedirs(misc_directory, exist_ok=True)
         filepath = os.path.join(misc_directory, self.PV_CHOICES_FILENAME)
-        path = join_url(self.misc_path)
+        path = FileHandler.join_url(self.misc_path)
 
         # check that file DNE
         if not os.path.isfile(filepath):
@@ -234,7 +232,7 @@ class DataSet:
         misc_directory = os.path.join(self.cache_directory, 'misc')
         os.makedirs(misc_directory, exist_ok=True)
         filepath = os.path.join(misc_directory, self.BATTERY_CHOICES_FILENAME)
-        path = join_url(self.misc_path)
+        path = FileHandler.join_url(self.misc_path)
 
         # check that file DNE
         if not os.path.isfile(filepath):
@@ -252,7 +250,7 @@ class DataSet:
         else:
             pass
 
-        data = read_yaml(filepath)
+        data = FileHandler.read_yaml(filepath)
         data = pd.DataFrame([{'model': k, **v['attributes']} for k, v in data.items()])
         data = data.set_index('model')
 
@@ -266,7 +264,7 @@ class DataSet:
             pass
 
     def get_github_contents(self, path: str = None) -> List[Mapping[str, Any]]:
-        url = self.GITHUB_API_CONTENT_URL if path is None else join_url(self.GITHUB_API_CONTENT_URL, path) 
+        url = self.GITHUB_API_CONTENT_URL if path is None else FileHandler.join_url(self.GITHUB_API_CONTENT_URL, path) 
         params = dict(ref=self.tag)
         contents = self.get_requests_session().get(url, params=params)
 

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/end_use_load_profiles/neighborhood.py

@@ -23,7 +23,7 @@ from citylearn.end_use_load_profiles.clustering import MetadataClustering
 from citylearn.end_use_load_profiles.lstm_model.model_generation_wrapper import run_one_model
 from citylearn.end_use_load_profiles.simulate import EndUseLoadProfilesEnergyPlusPartialLoadSimulator
 from citylearn.preprocessing import PeriodicNormalization, Normalize
-from citylearn.utilities import read_json, write_json
+from citylearn.utilities import FileHandler
 
 BuildingSimulators = Mapping[
     str, 
@@ -255,7 +255,7 @@ class Neighborhood:
     
     def test_lstm(self, bldg_ix: int, training_data: pd.DataFrame, schema_filepath: Path) -> Tuple[int, pd.DataFrame]:
         # set data
-        schema = read_json(schema_filepath)
+        schema = FileHandler.read_json(schema_filepath)
         schema_directory = Path(schema_filepath).parents[0]
         bldg_key = list(schema['buildings'].keys())[bldg_ix]
         dynamics_model = schema['buildings'][bldg_key]['dynamics']
@@ -511,7 +511,7 @@ class Neighborhood:
 
         schema_filepath = os.path.join(schema_directory, f'schema.json')
         template = user_customization_function(template) if user_customization_function is not None else template
-        write_json(schema_filepath, template)
+        FileHandler.write_json(schema_filepath, template)
         
         return schema_filepath
     

{CityLearn-2.4.0 → CityLearn-2.4.2}/citylearn/occupant.py

@@ -4,7 +4,7 @@ import numpy as np
 from sklearn.tree import DecisionTreeClassifier
 from citylearn.base import Environment
 from citylearn.data import LogisticRegressionOccupantParameters
-from citylearn.utilities import read_pickle
+from citylearn.utilities import FileHandler
 
 class Occupant(Environment):
     def __init__(self, **kwargs) -> None:
@@ -48,12 +48,12 @@ class LogisticRegressionOccupant(Occupant):
     @setpoint_increase_model_filepath.setter
     def setpoint_increase_model_filepath(self, value: Union[Path, str]):
         self.__setpoint_increase_model_filepath = value
-        self.__setpoint_increase_model = read_pickle(self.setpoint_increase_model_filepath)
+        self.__setpoint_increase_model = FileHandler.read_pickle(self.setpoint_increase_model_filepath)
 
     @setpoint_decrease_model_filepath.setter
     def setpoint_decrease_model_filepath(self, value: Union[Path, str]):
         self.__setpoint_decrease_model_filepath = value
-        self.__setpoint_decrease_model = read_pickle(self.setpoint_decrease_model_filepath)
+        self.__setpoint_decrease_model = FileHandler.read_pickle(self.setpoint_decrease_model_filepath)
 
     @delta_output_map.setter
     def delta_output_map(self, value: Mapping[Union[str, int], float]):

CityLearn-2.4.2/citylearn/utilities.py

@@ -0,0 +1,175 @@
+import pickle
+from typing import Any, Iterable, Union
+import numpy as np
+import simplejson as json
+import yaml
+
+class FileHandler:
+    @staticmethod
+    def read_json(filepath: str, **kwargs) -> dict:
+        """Return JSON document as dictionary.
+        
+        Parameters
+        ----------
+        filepath : str
+        pathname of JSON document.
+
+        Other Parameters
+        ----------------
+        **kwargs : dict
+            Other infrequently used keyword arguments to be parsed to `simplejson.load`.
+        
+        Returns
+        -------
+        dict
+            JSON document converted to dictionary.
+        """
+
+        with open(filepath) as f:
+            json_file = json.load(f, **kwargs)
+
+        return json_file
+
+    @staticmethod
+    def write_json(filepath: str, dictionary: dict, **kwargs):
+        """Write dictionary to JSON file.
+        
+        Parameters
+        ----------
+        filepath : str
+            pathname of JSON document.
+        dictionary: dict
+            dictionary to convert to JSON.
+
+        Other Parameters
+        ----------------
+        **kwargs : dict
+            Other infrequently used keyword arguments to be parsed to `simplejson.dump`.
+        """
+
+        kwargs = {'ignore_nan': True, 'sort_keys': False, 'default': str, 'indent': 2, **kwargs}
+        
+        with open(filepath,'w') as f:
+            json.dump(dictionary, f, **kwargs)
+
+    @staticmethod
+    def read_yaml(filepath: str) -> dict:
+        """Return YAML document as dictionary.
+        
+        Parameters
+        ----------
+        filepath : str
+        pathname of YAML document.
+        
+        Returns
+        -------
+        dict
+            YAML document converted to dictionary.
+        """
+
+        with open(filepath, 'r') as f:
+            data = yaml.safe_load(f)
+
+        return data
+
+    @staticmethod
+    def write_yaml(filepath: str, dictionary: dict, **kwargs):
+        """Write dictionary to YAML file. 
+        
+        Parameters
+        ----------
+        filepath : str
+            pathname of YAML document.
+        dictionary: dict
+            dictionary to convert to YAML.
+
+        Other Parameters
+        ----------------
+        **kwargs : dict
+            Other infrequently used keyword arguments to be parsed to `yaml.safe_dump`.
+        """
+
+        kwargs = {'sort_keys': False, 'indent': 2, **kwargs}
+        
+        with open(filepath, 'w') as f:
+            yaml.safe_dump(dictionary, f, **kwargs)
+
+    @staticmethod
+    def read_pickle(filepath: str, **kwargs) -> Any:
+        """Return pickle file as some Python class object.
+        
+        Parameters
+        ----------
+        filepath : str
+        pathname of pickle file.
+
+        Other Parameters
+        ----------------
+        **kwargs : dict
+            Other infrequently used keyword arguments to be parsed to `pickle.load`.
+        
+        Returns
+        -------
+        Any
+            Pickle file as a Python object.
+        """
+
+        with (open(filepath, 'rb')) as f:
+            data = pickle.load(f, **kwargs)
+
+        return data
+
+    @staticmethod
+    def write_pickle(filepath: str, data: Any, **kwargs):
+        """Write Python object to pickle file. 
+        
+        Parameters
+        ----------
+        filepath : str
+            pathname of pickle document.
+        data: dict
+            object to convert to pickle.
+
+        Other Parameters
+        ----------------
+        **kwargs : dict
+            Other infrequently used keyword arguments to be parsed to `pickle.dump`.
+        """
+
+        with open(filepath, 'wb') as f:
+            pickle.dump(data, f, **kwargs)
+
+    @staticmethod
+    def join_url(*args: str) -> str:
+        url = '/'.join([a.strip('/') for a in args])
+
+        return url
+    
+class NoiseUtils:
+    @staticmethod
+    def generate_gaussian_noise(input_data: Union[np.ndarray, Iterable[float]], noise_std: float) -> np.ndarray:
+        """Generates Gaussian noise matching input shape.
+        
+        Parameters
+        ----------
+        input_data : Union[np.ndarray, Iterable[float]]
+            Time series to add noise to.
+        noise_std : float
+            Noise standard deviation (ignored if <= 0)
+            
+        Returns
+        -------
+            noise: np.ndarray
+                Zero-mean noise array with same shape as input
+        """
+
+        arr = np.asarray(input_data)  # Handles both ndarray and Iterable
+        if noise_std <= 0:
+            return np.zeros(arr.shape)
+        return np.random.normal(loc=0, scale=noise_std, size=arr.shape)
+
+    @staticmethod
+    def generate_scaled_noise(input_data: Union[np.ndarray, Iterable[float]], noise_std: float, scale: float = 1.0) -> np.ndarray:
+        """Generates pre-scaled noise (e.g., for percentage values)."""
+        
+        return NoiseUtils.generate_gaussian_noise(input_data, noise_std) * scale

CityLearn-2.4.0/citylearn/__init__.py

@@ -1 +0,0 @@
-__version__ = '2.4.0'

CityLearn-2.4.0/citylearn/utilities.py

@@ -1,137 +0,0 @@
-import pickle
-from typing import Any
-import simplejson as json
-import yaml
-
-def read_json(filepath: str, **kwargs) -> dict:
-    """Return JSON document as dictionary.
-    
-    Parameters
-    ----------
-    filepath : str
-       pathname of JSON document.
-
-    Other Parameters
-    ----------------
-    **kwargs : dict
-        Other infrequently used keyword arguments to be parsed to `simplejson.load`.
-       
-    Returns
-    -------
-    dict
-        JSON document converted to dictionary.
-    """
-
-    with open(filepath) as f:
-        json_file = json.load(f, **kwargs)
-
-    return json_file
-
-def write_json(filepath: str, dictionary: dict, **kwargs):
-    """Write dictionary to JSON file.
-    
-    Parameters
-    ----------
-    filepath : str
-        pathname of JSON document.
-    dictionary: dict
-        dictionary to convert to JSON.
-
-    Other Parameters
-    ----------------
-    **kwargs : dict
-        Other infrequently used keyword arguments to be parsed to `simplejson.dump`.
-    """
-
-    kwargs = {'ignore_nan': True, 'sort_keys': False, 'default': str, 'indent': 2, **kwargs}
-    
-    with open(filepath,'w') as f:
-        json.dump(dictionary, f, **kwargs)
-
-def read_yaml(filepath: str) -> dict:
-    """Return YAML document as dictionary.
-    
-    Parameters
-    ----------
-    filepath : str
-       pathname of YAML document.
-       
-    Returns
-    -------
-    dict
-        YAML document converted to dictionary.
-    """
-
-    with open(filepath, 'r') as f:
-        data = yaml.safe_load(f)
-
-    return data
-
-def write_yaml(filepath: str, dictionary: dict, **kwargs):
-    """Write dictionary to YAML file. 
-    
-    Parameters
-    ----------
-    filepath : str
-        pathname of YAML document.
-    dictionary: dict
-        dictionary to convert to YAML.
-
-    Other Parameters
-    ----------------
-    **kwargs : dict
-        Other infrequently used keyword arguments to be parsed to `yaml.safe_dump`.
-    """
-
-    kwargs = {'sort_keys': False, 'indent': 2, **kwargs}
-    
-    with open(filepath, 'w') as f:
-        yaml.safe_dump(dictionary, f, **kwargs)
-
-def read_pickle(filepath: str, **kwargs) -> Any:
-    """Return pickle file as some Python class object.
-    
-    Parameters
-    ----------
-    filepath : str
-       pathname of pickle file.
-
-    Other Parameters
-    ----------------
-    **kwargs : dict
-        Other infrequently used keyword arguments to be parsed to `pickle.load`.
-       
-    Returns
-    -------
-    Any
-        Pickle file as a Python object.
-    """
-
-    with (open(filepath, 'rb')) as f:
-        data = pickle.load(f, **kwargs)
-
-    return data
-
-def write_pickle(filepath: str, data: Any, **kwargs):
-    """Write Python object to pickle file. 
-    
-    Parameters
-    ----------
-    filepath : str
-        pathname of pickle document.
-    data: dict
-        object to convert to pickle.
-
-    Other Parameters
-    ----------------
-    **kwargs : dict
-        Other infrequently used keyword arguments to be parsed to `pickle.dump`.
-    """
-
-    with open(filepath, 'wb') as f:
-        pickle.dump(data, f, **kwargs)
-
-def join_url(*args: str) -> str:
-    url = '/'.join([a.strip('/') for a in args])
-
-    return url