(v3.5.10) - Sinergym terminal logging level set and intallation secti…

…on documentation fix (#444) * Update MODELING layer to MODEL * Develop sinergym package function to update loggers level * Logger: Develop simple logger for environment prints * Environment: Updated prints with simple logger from previous commit * set logger levels fix: wrapper loggers managed as set * Documentation: Added sinergym update logger level example in notebooks, and update documentation reference * Update sphinx modules * Update installation section in documentation * Updated Sinergym version from 3.5.9 to 3.5.10
ugr-sail · Sep 17, 2024 · 745b8df · 745b8df
1 parent 8299a28
commit 745b8df
Show file tree

Hide file tree

Showing 15 changed files with 267 additions and 17 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -27,7 +27,7 @@ documentation in the subsequent sections.
 We provide a **Dockerfile** to install all dependencies and prepare the 
 image for running *Sinergym*. 
 
-By default, the *Dockerfile* executes `pip install -e .[extras]`. If you wish 
+By default, the *Dockerfile* executes pip installation of sinergym with all extras. If you wish 
 to install a different setup, you need to execute the following command in the 
 **root repository**:
 
@@ -75,7 +75,7 @@ $ source env_sinergym/bin/activate
 $ pip install -e .[extras]
 ```
 
-Alternatively, you can use **conda environments** (*recommended*). 
+Alternatively, you can use **conda environments**. 
 *Conda* is user-friendly and we provide a file for automatic configuration:
 
 ```sh
@@ -88,15 +88,15 @@ With this, you have the correct Python version and the necessary modules to run
 *Sinergym*. Let's proceed with the installation of other required programs 
 outside of Python to run the simulations:
 
-### Install EnergyPlus 23.1.0
+### Install EnergyPlus 24.1.0
 
 You need to install *EnergyPlus*. We have tested and confirmed compatibility 
-with version `23.1.0`. The code might work with other versions, but we 
+with version `24.1.0`. The code might work with other versions, but we 
 have not tested them.
 
 Follow the instructions [here](https://energyplus.net/downloads) to install 
 it for Linux (we only support **Ubuntu**). You can choose any location for the 
-installation. After installation, a folder named `Energyplus-23-1-0` should 
+installation. After installation, a folder named `Energyplus-24-1-0` should 
 appear in the chosen location.
 
 ### Include Energyplus Python API in Python Path

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -91,6 +91,7 @@ If you use *Sinergym* in your work, please cite our `paper <https://dl.acm.org/d
 
    pages/notebooks/basic_example.nblink
    pages/notebooks/getting_env_information.nblink
+   pages/notebooks/sinergym_package.nblink
    pages/notebooks/change_environment.nblink
    pages/notebooks/default_building_control.nblink
    pages/notebooks/wrappers_examples.nblink

diff --git a/docs/source/pages/installation.rst b/docs/source/pages/installation.rst
@@ -37,7 +37,7 @@ Docker container
 We provide a **Dockerfile** to install all dependencies and prepare the 
 image for running *Sinergym*. 
 
-By default, the *Dockerfile* executes ``pip install -e .[extras]``. If you wish 
+By default, the *Dockerfile* executes pip installation of sinergym with all extras. If you wish 
 to install a different setup, you need to execute the following command in the 
 **root repository**:
 
@@ -94,7 +94,7 @@ Configure Python Environment
     $ source env_sinergym/bin/activate
     $ pip install -e .[extras]
 
-Alternatively, you can use **conda environments** (*recommended*). 
+Alternatively, you can use **conda environments**. 
 *Conda* is user-friendly and we provide a file for automatic configuration:
 
 .. code:: sh
@@ -107,16 +107,16 @@ With this, you have the correct Python version and the necessary modules to run
 *Sinergym*. Let's proceed with the installation of other required programs 
 outside of Python to run the simulations:
 
-Install EnergyPlus 23.1.0
+Install EnergyPlus 24.1.0
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You need to install *EnergyPlus*. We have tested and confirmed compatibility 
-with version ``23.1.0``. The code might work with other versions, but we 
+with version ``24.1.0``. The code might work with other versions, but we 
 have not tested them.
 
 Follow the instructions `here <https://energyplus.net/downloads>`__ to install 
 it for Linux (we only support **Ubuntu**). You can choose any location for the 
-installation. After installation, a folder named ``Energyplus-23-1-0`` should 
+installation. After installation, a folder named ``Energyplus-24-1-0`` should 
 appear in the chosen location.
 
 Include Energyplus Python API in Python Path

diff --git a/docs/source/pages/logging.rst b/docs/source/pages/logging.rst
@@ -13,6 +13,9 @@ TerminalLogger
 * Messages are structured in layers (``ENVIRONMENT``, ``MODELING``, ``WRAPPER``, ``SIMULATION``, ``REWARD``) and levels 
   (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``).
 
+* The levels of each module can be updated in execution time using the set level method of *Sinergym*. For more information
+  about how to use it, see :ref:`Set terminal loggers' level`.
+
 ***************
 LoggerStorage
 ***************

diff --git a/docs/source/pages/modules/sinergym.envs.eplus_env.EplusEnv.rst b/docs/source/pages/modules/sinergym.envs.eplus_env.EplusEnv.rst
@@ -50,6 +50,7 @@
       ~EplusEnv.reward_range
       ~EplusEnv.runperiod
       ~EplusEnv.schedulers
+      ~EplusEnv.simple_printer
       ~EplusEnv.spec
       ~EplusEnv.step_size
       ~EplusEnv.timestep_per_episode

diff --git a/docs/source/pages/modules/sinergym.utils.logger.LoggerStorage.rst b/docs/source/pages/modules/sinergym.utils.logger.LoggerStorage.rst
@@ -16,8 +16,10 @@ sinergym.utils.logger.LoggerStorage
    .. autosummary::
 
       ~LoggerStorage.__init__
+      ~LoggerStorage.log_info
       ~LoggerStorage.log_interaction
       ~LoggerStorage.log_norm_obs
+      ~LoggerStorage.log_obs
       ~LoggerStorage.reset_data
 
 

diff --git a/docs/source/pages/modules/sinergym.utils.logger.SimpleLogger.rst b/docs/source/pages/modules/sinergym.utils.logger.SimpleLogger.rst
@@ -0,0 +1,25 @@
+sinergym.utils.logger.SimpleLogger
+==================================
+
+.. currentmodule:: sinergym.utils.logger
+
+.. autoclass:: SimpleLogger
+   :members:                                                           
+   :undoc-members:               
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~SimpleLogger.__init__
+      ~SimpleLogger.getLogger
+
+
+
+
+
+
diff --git a/docs/source/pages/modules/sinergym.utils.logger.rst b/docs/source/pages/modules/sinergym.utils.logger.rst
@@ -21,6 +21,7 @@
 
       CustomFormatter
       LoggerStorage
+      SimpleLogger
       TerminalLogger
       TqdmLoggingHandler
       WandBOutputFormat

diff --git a/docs/source/pages/notebooks/sinergym_package.nblink b/docs/source/pages/notebooks/sinergym_package.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../../examples/sinergym_package.ipynb"
+}
diff --git a/examples/sinergym_package.ipynb b/examples/sinergym_package.ipynb
@@ -0,0 +1,164 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Sinergym package information"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can view or modify information directly from the *Sinergym* package without needing to set up any environment."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Available environments ids and version"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Couldn't import dot_parser, loading of dot files will not be possible.\n",
+      "3.5.9\n",
+      "['Eplus-demo-v1', 'Eplus-office-hot-continuous-v1', 'Eplus-office-hot-discrete-v1', 'Eplus-office-hot-continuous-stochastic-v1', 'Eplus-office-hot-discrete-stochastic-v1', 'Eplus-office-mixed-continuous-v1', 'Eplus-office-mixed-discrete-v1', 'Eplus-office-mixed-continuous-stochastic-v1', 'Eplus-office-mixed-discrete-stochastic-v1', 'Eplus-office-cool-continuous-v1', 'Eplus-office-cool-discrete-v1', 'Eplus-office-cool-continuous-stochastic-v1', 'Eplus-office-cool-discrete-stochastic-v1', 'Eplus-warehouse-hot-continuous-v1', 'Eplus-warehouse-hot-discrete-v1', 'Eplus-warehouse-hot-continuous-stochastic-v1', 'Eplus-warehouse-hot-discrete-stochastic-v1', 'Eplus-warehouse-mixed-continuous-v1', 'Eplus-warehouse-mixed-discrete-v1', 'Eplus-warehouse-mixed-continuous-stochastic-v1', 'Eplus-warehouse-mixed-discrete-stochastic-v1', 'Eplus-warehouse-cool-continuous-v1', 'Eplus-warehouse-cool-discrete-v1', 'Eplus-warehouse-cool-continuous-stochastic-v1', 'Eplus-warehouse-cool-discrete-stochastic-v1', 'Eplus-radiant-hot-discrete-v1', 'Eplus-radiant-hot-discrete-stochastic-v1', 'Eplus-radiant-mixed-discrete-v1', 'Eplus-radiant-mixed-discrete-stochastic-v1', 'Eplus-radiant-cool-discrete-v1', 'Eplus-radiant-cool-discrete-stochastic-v1', 'Eplus-radiant-stockholm-discrete-v1', 'Eplus-radiant-stockholm-discrete-stochastic-v1', 'Eplus-datacenter-hot-continuous-v1', 'Eplus-datacenter-hot-discrete-v1', 'Eplus-datacenter-hot-continuous-stochastic-v1', 'Eplus-datacenter-hot-discrete-stochastic-v1', 'Eplus-datacenter-mixed-continuous-v1', 'Eplus-datacenter-mixed-discrete-v1', 'Eplus-datacenter-mixed-continuous-stochastic-v1', 'Eplus-datacenter-mixed-discrete-stochastic-v1', 'Eplus-datacenter-cool-continuous-v1', 'Eplus-datacenter-cool-discrete-v1', 'Eplus-datacenter-cool-continuous-stochastic-v1', 'Eplus-datacenter-cool-discrete-stochastic-v1', 'Eplus-shop-hot-continuous-v1', 'Eplus-shop-hot-discrete-v1', 'Eplus-shop-hot-continuous-stochastic-v1', 'Eplus-shop-hot-discrete-stochastic-v1', 'Eplus-shop-mixed-continuous-v1', 'Eplus-shop-mixed-discrete-v1', 'Eplus-shop-mixed-continuous-stochastic-v1', 'Eplus-shop-mixed-discrete-stochastic-v1', 'Eplus-shop-cool-continuous-v1', 'Eplus-shop-cool-discrete-v1', 'Eplus-shop-cool-continuous-stochastic-v1', 'Eplus-shop-cool-discrete-stochastic-v1', 'Eplus-smalldatacenter-hot-continuous-v1', 'Eplus-smalldatacenter-hot-continuous-stochastic-v1', 'Eplus-smalldatacenter-mixed-continuous-v1', 'Eplus-smalldatacenter-mixed-continuous-stochastic-v1', 'Eplus-smalldatacenter-cool-continuous-v1', 'Eplus-smalldatacenter-cool-continuous-stochastic-v1', 'Eplus-officegrid-hot-continuous-v1', 'Eplus-officegrid-hot-discrete-v1', 'Eplus-officegrid-hot-continuous-stochastic-v1', 'Eplus-officegrid-hot-discrete-stochastic-v1', 'Eplus-officegrid-mixed-continuous-v1', 'Eplus-officegrid-mixed-discrete-v1', 'Eplus-officegrid-mixed-continuous-stochastic-v1', 'Eplus-officegrid-mixed-discrete-stochastic-v1', 'Eplus-officegrid-cool-continuous-v1', 'Eplus-officegrid-cool-discrete-v1', 'Eplus-officegrid-cool-continuous-stochastic-v1', 'Eplus-officegrid-cool-discrete-stochastic-v1', 'Eplus-5zone-hot-continuous-v1', 'Eplus-5zone-hot-discrete-v1', 'Eplus-5zone-hot-continuous-stochastic-v1', 'Eplus-5zone-hot-discrete-stochastic-v1', 'Eplus-5zone-mixed-continuous-v1', 'Eplus-5zone-mixed-discrete-v1', 'Eplus-5zone-mixed-continuous-stochastic-v1', 'Eplus-5zone-mixed-discrete-stochastic-v1', 'Eplus-5zone-cool-continuous-v1', 'Eplus-5zone-cool-discrete-v1', 'Eplus-5zone-cool-continuous-stochastic-v1', 'Eplus-5zone-cool-discrete-stochastic-v1']\n"
+     ]
+    }
+   ],
+   "source": [
+    "import sinergym\n",
+    "\n",
+    "print(sinergym.__version__)\n",
+    "print(sinergym.__ids__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Set terminal loggers' level"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The logging level for each module is set by default in the Sinergym constants. However, these can be modified from the package once the environment has been created to take effect.\n",
+    "\n",
+    "The currently available levels are: ENVIRONMENT, SIMULATOR, MODEL, REWARD, COMMON, WRAPPER (or WRAPPERS, both options are detected), and CALLBACK.\n",
+    "\n",
+    "Below is an example of how to use them:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "#==============================================================================================#\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Creating Gymnasium environment.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Name: demo-v1\u001b[0m\n",
+      "#==============================================================================================#\n",
+      "\u001b[38;20m[MODEL] (INFO) : Experiment working directory created.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Working directory: /workspaces/sinergym/examples/Eplus-env-demo-v1-res8\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Model Config is correct.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Update building model Output:Variable with variable names.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Update building model Output:Meter with meter names.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Extra config: runperiod updated to {'apply_weekend_holiday_rule': 'No', 'begin_day_of_month': 1, 'begin_month': 1, 'begin_year': 1991, 'day_of_week_for_start_day': 'Monday', 'end_day_of_month': 1, 'end_month': 3, 'end_year': 1991, 'use_weather_file_daylight_saving_period': 'Yes', 'use_weather_file_holidays_and_special_days': 'Yes', 'use_weather_file_rain_indicators': 'Yes', 'use_weather_file_snow_indicators': 'Yes'}\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Updated episode length (seconds): 5184000.0\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Updated timestep size (seconds): 3600.0\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Updated timesteps per episode: 1440\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Runperiod established.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Episode length (seconds): 5184000.0\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : timestep size (seconds): 3600.0\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : timesteps per episode: 1440\u001b[0m\n",
+      "\u001b[38;20m[REWARD] (INFO) : Reward function initialized.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Environment created successfully.\u001b[0m\n",
+      "#----------------------------------------------------------------------------------------------#\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Starting a new episode.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Episode 1: demo-v1\u001b[0m\n",
+      "#----------------------------------------------------------------------------------------------#\n",
+      "\u001b[38;20m[MODEL] (INFO) : Episode directory created.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Weather file USA_PA_Pittsburgh-Allegheny.County.AP.725205_TMY3.epw used.\u001b[0m\n",
+      "\u001b[38;20m[MODEL] (INFO) : Adapting weather to building model.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Saving episode output path.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : Path: /workspaces/sinergym/examples/Eplus-env-demo-v1-res8/Eplus-env-sub_run1/output\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Episode 1 started.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : Waiting for finishing WARMUP process.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : WARMUP process finished.\u001b[0m\n",
+      "\u001b[38;20m[SIMULATOR] (INFO) : handlers initialized.\u001b[0m\n",
+      "\u001b[38;20m[SIMULATOR] (INFO) : handlers are ready.\u001b[0m\n",
+      "\u001b[38;20m[SIMULATOR] (INFO) : System is ready.\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : RESET observation received: {'month': 1, 'day_of_month': 1, 'hour': 0, 'outdoor_temperature': 7.2, 'htg_setpoint': 12.8, 'clg_setpoint': 40.0, 'air_temperature': 19.7479730060398, 'air_humidity': 54.12386596530383, 'HVAC_electricity_demand_rate': 87.36488027634958}\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : RESET info received: {'time_elapsed(hours)': 1.5, 'month': 1, 'day': 1, 'hour': 0, 'is_raining': False, 'timestep': 0}\u001b[0m\n",
+      "\u001b[38;20m[ENVIRONMENT] (DEBUG) : STEP queues not receive value, simulation must be completed. changing TRUNCATED flag to TRUE\u001b[0m\n",
+      "Simulation Progress [Episode 1]: 100%|██████████| 100/100 [00:02<00:00, 36.37%/s, 100% completed] \n",
+      "\u001b[38;20m[ENVIRONMENT] (INFO) : Environment closed. [demo-v1]\u001b[0m\n"
+     ]
+    }
+   ],
+   "source": [
+    "import gymnasium as gym\n",
+    "import sinergym\n",
+    "\n",
+    "env = gym.make('Eplus-demo-v1')\n",
+    "# Update log levels to DEBUG in Environment instead of info\n",
+    "sinergym.set_logger_level('ENVIRONMENT', 'DEBUG')\n",
+    "\n",
+    "env.reset()\n",
+    "terminated=truncated=False\n",
+    "\n",
+    "# Run an episode\n",
+    "while not terminated and not truncated:\n",
+    "    action = env.action_space.sample()\n",
+    "    _, _, terminated, truncated, _ = env.step(action)\n",
+    "env.close()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "info = env.step(action)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/sinergym/__init__.py b/sinergym/__init__.py
@@ -1,4 +1,5 @@
 import json
+import logging
 import os
 
 import gymnasium as gym
@@ -136,3 +137,19 @@
 # --------------------------- Set __ids__ in module -------------------------- #
 __ids__ = [env_id for env_id in gym.envs.registration.registry.keys()
            if env_id.startswith('Eplus')]
+
+
+# ----------------------------- Log level system ----------------------------- #
+def set_logger_level(name: str, level: Union[str, int]):
+    if name.upper() == 'WRAPPER' or name.upper() == 'WRAPPERS':
+        # Get all logger whose name contains 'WRAPPER'
+        for logger_name in logging.root.manager.loggerDict.keys():
+            if 'WRAPPER' in logger_name.upper():
+                logger = logging.getLogger(logger_name)
+                logger.setLevel(level)
+    else:
+        logger = logging.getLogger(name.upper())
+        logger.setLevel(level)
+        if name == 'ENVIRONMENT':
+            logger = logging.getLogger('Printer')
+            logger.setLevel(level)
diff --git a/sinergym/config/modeling.py b/sinergym/config/modeling.py
@@ -44,7 +44,7 @@ class ModelJSON(object):
     """
 
     logger = TerminalLogger().getLogger(
-        name='MODELING',
+        name='MODEL',
         level=LOG_MODEL_LEVEL)
 
     def __init__(