(v3.2.2) - New Building 1ZoneDatacenter (ugr-sail#389)

* Added new building - 1ZoneDatacenter

* Improved container layer modularization

* Improved documentation about including new buildings and weathers

* Updating Sinergym version from 3.2.1 to 3.2.2

* Added documentation for new building

.devcontainer/Dockerfile

@@ -1,5 +1,81 @@
-# Use the image created with ../Dockerfile and stored in DockerHub
+# Base on nrel/energyplus from Nicholas Long but using 
+# Ubuntu, Python 3.10 and BCVTB
+ARG UBUNTU_VERSION=22.04
+FROM ubuntu:${UBUNTU_VERSION}
 
-FROM sailugr/sinergym:latest
+# Arguments for EnergyPlus version (default values of version 8.6.0 if is not specified)
+ARG ENERGYPLUS_VERSION=23.1.0
+ARG ENERGYPLUS_INSTALL_VERSION=23-1-0
+ARG ENERGYPLUS_SHA=87ed9199d4
+
+# Argument for Sinergym extras libraries
+ARG SINERGYM_EXTRAS=[extras]
+
+# Argument for choosing Python version
+ARG PYTHON_VERSION=3.10
+
+# WANDB_API_KEY
+ARG WANDB_API_KEY
+ENV WANDB_API_KEY=${WANDB_API_KEY}
+
+# LC_ALL for python locale error (https://bobbyhadz.com/blog/locale-error-unsupported-locale-setting-in-python)
+ENV LC_ALL=C
+
+ENV ENERGYPLUS_VERSION=$ENERGYPLUS_VERSION
+ENV ENERGYPLUS_TAG=v$ENERGYPLUS_VERSION
+ENV ENERGYPLUS_SHA=$ENERGYPLUS_SHA
+
+# This should be x.y.z, but EnergyPlus convention is x-y-z
+ENV ENERGYPLUS_INSTALL_VERSION=$ENERGYPLUS_INSTALL_VERSION
+ENV EPLUS_PATH=/usr/local/EnergyPlus-$ENERGYPLUS_INSTALL_VERSION
+
+# Downloading from Github
+# e.g. https://github.com/NREL/EnergyPlus/releases/download/v23.1.0/EnergyPlus-23.1.0-87ed9199d4-Linux-Ubuntu22.04-x86_64.sh
+ENV ENERGYPLUS_DOWNLOAD_BASE_URL https://github.com/NREL/EnergyPlus/releases/download/$ENERGYPLUS_TAG
+ENV ENERGYPLUS_DOWNLOAD_FILENAME EnergyPlus-$ENERGYPLUS_VERSION-$ENERGYPLUS_SHA-Linux-Ubuntu22.04-x86_64.sh 
+ENV ENERGYPLUS_DOWNLOAD_URL $ENERGYPLUS_DOWNLOAD_BASE_URL/$ENERGYPLUS_DOWNLOAD_FILENAME
+
+# Mandatory apt packages
+RUN apt update && apt upgrade -y
+RUN apt install -y ca-certificates curl libx11-6 libexpat1 git wget
+
+#Energyplus installation
+RUN curl -SLO $ENERGYPLUS_DOWNLOAD_URL \
+    && chmod +x $ENERGYPLUS_DOWNLOAD_FILENAME \
+    && echo "y\r" | ./$ENERGYPLUS_DOWNLOAD_FILENAME \
+    && rm $ENERGYPLUS_DOWNLOAD_FILENAME \
+    && cd /usr/local/EnergyPlus-$ENERGYPLUS_INSTALL_VERSION \
+    && rm -rf PostProcess/EP-Compare PreProcess/FMUParser PreProcess/ParametricPreProcessor PreProcess/IDFVersionUpdater \
+    # Remove the broken symlinks
+    && cd /usr/local/bin find -L . -type l -delete
+
+# Install pip, and make python point to python3
+RUN apt install python3-pip -y \
+    && ln -s /usr/bin/python3 /usr/bin/python \
+    # Install some apt dependencies
+    && echo "Y\r" | apt install python3-enchant -y \
+    && echo "Y\r" | apt install pandoc -y 
+
+# clean files
+RUN apt autoremove -y && apt autoclean -y \
+    && rm -rf /var/lib/apt/lists/* 
+
+
+# Python add pyenergyplus path in order to detect API package
+ENV PYTHONPATH="/usr/local/EnergyPlus-${ENERGYPLUS_INSTALL_VERSION}"
+
+WORKDIR /workspaces/sinergym
+COPY requirements.txt /workspaces/sinergym/requirements.txt
+COPY MANIFEST.in /workspaces/sinergym/MANIFEST.in
+COPY setup.py /workspaces/sinergym/setup.py
+COPY scripts /workspaces/sinergym/scripts
+COPY sinergym /workspaces/sinergym/sinergym
+COPY tests /workspaces/sinergym/tests
+COPY examples /workspaces/sinergym/examples
+COPY docs/source /workspaces/sinergym/docs/source
+COPY .git/ /workspaces/sinergym/.git
+RUN pip install -e .${SINERGYM_EXTRAS}
+
+#RUN pip install idna && pip install six
+CMD ["/bin/bash"]
 
-CMD ["/bin/bash"]

.devcontainer/devcontainer.json

@@ -11,7 +11,7 @@
 			"WANDB_API_KEY": "${localEnv:WANDB_API_KEY}"
 		}
 	},
-	"dockerFile": "../Dockerfile",
+	"dockerFile": "./Dockerfile",
 	"context": "..",
 	"customizations": {
 		"vscode": {

Dockerfile

@@ -35,27 +35,31 @@ ENV ENERGYPLUS_DOWNLOAD_BASE_URL https://github.com/NREL/EnergyPlus/releases/dow
 ENV ENERGYPLUS_DOWNLOAD_FILENAME EnergyPlus-$ENERGYPLUS_VERSION-$ENERGYPLUS_SHA-Linux-Ubuntu22.04-x86_64.sh 
 ENV ENERGYPLUS_DOWNLOAD_URL $ENERGYPLUS_DOWNLOAD_BASE_URL/$ENERGYPLUS_DOWNLOAD_FILENAME
 
-RUN apt-get update && apt-get upgrade -y \
-    && apt-get install -y ca-certificates curl libx11-6 libexpat1 \
-    && apt-get install -y git wget \
-    #Energyplus installation
-    && curl -SLO $ENERGYPLUS_DOWNLOAD_URL \
+# Mandatory apt packages
+RUN apt update && apt upgrade -y
+RUN apt install -y ca-certificates curl libx11-6 libexpat1 git wget
+
+#Energyplus installation
+RUN curl -SLO $ENERGYPLUS_DOWNLOAD_URL \
     && chmod +x $ENERGYPLUS_DOWNLOAD_FILENAME \
     && echo "y\r" | ./$ENERGYPLUS_DOWNLOAD_FILENAME \
     && rm $ENERGYPLUS_DOWNLOAD_FILENAME \
     && cd /usr/local/EnergyPlus-$ENERGYPLUS_INSTALL_VERSION \
     && rm -rf PostProcess/EP-Compare PreProcess/FMUParser PreProcess/ParametricPreProcessor PreProcess/IDFVersionUpdater \
     # Remove the broken symlinks
-    && cd /usr/local/bin find -L . -type l -delete \
-    # Install pip, and make python point to python3
-    && apt install python3-pip -y \
+    && cd /usr/local/bin find -L . -type l -delete
+
+# Install pip, and make python point to python3
+RUN apt install python3-pip -y \
     && ln -s /usr/bin/python3 /usr/bin/python \
     # Install some apt dependencies
-    && echo "Y\r" | apt-get install python3-enchant -y \
-    && echo "Y\r" | apt-get install pandoc -y \
-    # clean files
-    && apt-get autoremove -y && apt-get autoclean -y \
+    && echo "Y\r" | apt install python3-enchant -y \
+    && echo "Y\r" | apt install pandoc -y 
+
+# clean files
+RUN apt autoremove -y && apt autoclean -y \
     && rm -rf /var/lib/apt/lists/* 
+
 
 # Python add pyenergyplus path in order to detect API package
 ENV PYTHONPATH="/usr/local/EnergyPlus-${ENERGYPLUS_INSTALL_VERSION}"

docs/source/pages/buildings.rst

@@ -28,6 +28,25 @@ main source of heat comes from the hosted servers.
   :alt: Datacenter building
   :align: center
 
+**************************
+Small Datacenter
+**************************
+
+**1ZoneDataCenterCRAC_wApproachTemp.epJSON**:
+This file demonstrates a simple data center model with air-cooled IT equipment 
+(ITE) served by a CRAC system.
+The air-cooled ITE illustrates the user of various schedules and curves to 
+vary server power use. The CRAC system has been setup to represent a Lieber 
+DSE 125 with pumped refrigerant economizer DX cooling coil system.
+Fictional 1 zone building with resistive walls. No windows. Data Center server 
+ITE object for internal gains.  No internal mass.  The building is oriented due north.
+
+
+.. image:: /_static/small_datacenter.png
+  :width: 700
+  :alt: Small Datacenter building
+  :align: center
+
 **************************
 5Zone
 **************************

docs/source/pages/environments.rst

@@ -420,54 +420,64 @@ available for *Sinergym* visit section :ref:`Extra Configuration in Sinergym sim
 Adding new weathers for environments
 **************************************
 
-*Sinergym* includes several weathers covering different types of climate in different areas of the world. 
-The aim is to provide the greatest possible diversity for the experiments taking into account certain 
-characteristics.
+*Sinergym* includes diverse weather files covering various climates worldwide to maximize experiment diversity.
 
-However, you may need or want to include a **new weather** for an experiment. Therefore, this section 
-is dedicated to give an explanation of how to do it:
+To add a **new weather**:
 
-1. Download **EPW** file and **DDY** file in `EnergyPlus page <https://energyplus.net/weather>`__. *DDY* file
-   contains information about the location and different design days available for that weather.
-2. Both files (*EPW* and *DDY*) must have exactly the same name, being the extension the only difference. 
-   They should be placed in the `weathers <https://github.com/ugr-sail/sinergym/tree/main/sinergym/data/weather>`__ folder.
+1. Download an **EPW** and a corresponding **DDY** file from the `EnergyPlus page <https://energyplus.net/weather>`__.
+   The *DDY* file specifies location and design day information.
 
-That is all! *Sinergym* should be able to adapt ``SizingPeriod:DesignDays`` and ``Site:Location`` fields in building 
-model file using *DDY* automatically for that weather.
+2. Ensure both files have identical names, differing only in their extensions, and place them in 
+   the `weathers <https://github.com/ugr-sail/sinergym/tree/main/sinergym/data/weather>`__ folder.
+
+*Sinergym* will automatically adjust the ``SizingPeriod:DesignDays`` and ``Site:Location`` fields in 
+the building model file using the *DDY* file for the added weather.
 
 **************************************
 Adding new buildings for environments
 **************************************
 
-As we have already mentioned, a user can change the already available environments or even create new environment 
-definitions including new climates, action and observation spaces, etc. However, perhaps you want to use a 
-**new building model** (*epJSON* file) than the ones we support.
+Users can modify existing environments or create new environment definitions, incorporating new climates, 
+action and observation spaces. Additionally, they have the option to use a different **building model** (epJSON file) 
+than the ones currently supported.
+
+To add new buildings for use with *Sinergym*, follow these steps:
+
+1. **Add your building file** (*epJSON*) to the `buildings <https://github.com/ugr-sail/sinergym/tree/main/sinergym/data/buildings>`__.
+   Ensure compatibility with EnergyPlus version used in *Sinergym*.
+   If you are using an *IDF* file with an older version, it is advisable to update it with **IDFVersionUpdater** and then convert 
+   it to *epJSON* format using **ConvertInputFormat**. Both tools are accessible in the EnergyPlus installation folder.
+
+2. **Adjusting building objects** like ``RunPeriod`` and ``SimulationControl`` to meet user needs, 
+   as these elements define how interaction episodes will be in *Sinergym*.
 
-This section is intended to provide information if someone decides to add new buildings for use with *Sinergym*. 
-The main steps you have to follow are the next:
+3. We need to **identify the components** of the building that we want to observe and control, respectively. This is the most 
+   challenging part of the process. Typically, the user is already familiar with the building and therefore knows the *name* 
+   and *key* of the elements in advance. If not, the following process can be followed.
 
-1. Add your building file (*epJSON*) to `buildings <https://github.com/ugr-sail/sinergym/tree/main/sinergym/data/buildings>`__.
-   *EnergyPlus* pretends to work with *JSON* format instead of *IDF* format in their building definitions and simulations. Then,
-   *Sinergym* pretends to work with this format from v2.4.0 or higher directly. You can download a *IDF* file and convert
-   to *epJSON* using their **ConvertInputFormat tool** from *EnergyPlus*.
-   **Be sure that new epJSON model version is compatible with EnergyPlus version**.
+   To view the different ``OutputVariables`` and ``Meters``, a preliminary simulation with EnergyPlus can be conducted directly 
+   without establishing any control flow. The output files, specifically the file with the *RDD* extension, can be consulted 
+   to identify the possible observable variables.
 
-2. Add your own *EPW* file for weather conditions (section :ref:`Adding new weathers for environments`) 
-   or use ours in environment constructor. 
+   The challenge lies in knowing the names but not the possible *Keys* (EnergyPlus does not initially provide this information). 
+   These names can be used to define the environment (see step 3). If the *Key* is incorrect, *Sinergym* will notify of the 
+   error and provide a file called **data_available.txt** in the aoutput, since it has already connected with the EnergyPlus API. This file will 
+   contain all the **controllable schedulers** for the actions and all the **observable variables**, this time with their respective *Keys*, 
+   enabling the correct definition of the environment.
 
-3. *Sinergym* will check that observation and action variables specified in environments constructor are 
-   available in the simulation before starting. You need to ensure that the variables definition are correct. 
+4. Once this information is obtained, the next step is **defining the environment** using the building model. 
+   We have several options:
 
-4. Use the environment constructor or register your own environment ID `here <https://github.com/ugr-sail/sinergym/blob/main/sinergym/__init__.py>`__ 
-   following the same structure than the demo environment. You will have to specify environment components. 
-   We have examples about how to get environment information in :ref:`Getting information about Sinergym environments`.
+  a. Use the *Sinergym* environment constructor directly. The arguments for building observation and 
+     control are explained within the class and should be specified in the same format as the EnergyPlus API.
 
-5. Now, you can use your own environment ID with ``gym.make()`` like our documentation examples.
+  b. Set up the configuration to register environment IDs directly. For detailed information on this, refer to 
+     the documentation :ref:`Environments Configuration and Registration`. *Sinergym* will verify that the 
+     established configuration is entirely correct and notify of any potential errors.
 
-Once the first step has been performed, it is also possible to **register a set of environments 
-automatically** in *Sinergym* by writing its corresponding configuration file in ``sinergym/data/default_configuration/<configuration_JSON_file>``. 
-For more information on this, see :ref:`Environments Configuration and Registration`.
+5. If you've used *Sinergym*'s registry, you'll have access to environment IDs paired with your building. Use them 
+   with ``gym.make(<environment_id>)`` as usual. If you've created an environment instance directly, simply use 
+   that instance to start interacting with the building.
 
-.. important:: In order to know the available variables, meters, actuators, etc. You can try to do an empty control in the building and look for files
-               such as RDD, MDD, MTD or ``data_available.txt`` file generated with *EnergyPlus* API in the output folder by *Sinergym*.
+.. note:: For obtain information about the environment instance with the new building model, see reference :ref:`Getting information about Sinergym environments`.