Merge pull request #22 from airboxlab/feat_21

project structure rework

.github/workflows/tests.yml

@@ -12,26 +12,24 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-
   unit-tests:
-    name: Test RLlib EnergyPlus
+    name: Test RL EnergyPlus
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
       - name: Checkout repo
         uses: actions/checkout@v3
 
+      - name: Setup Poetry
+        uses: abatilo/actions-poetry@v2.0.0
+        with:
+          poetry-version: "1.5.1"
+
       - name: Setup python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
-          cache: 'pip'
-
-      - name: Install python dependencies
-        run: |
-          pip install --upgrade pip
-          pip install keyring keyrings.alt
-          pip install -r requirements.txt
+          python-version: "3.10"
+          cache: "poetry"
 
       - name: Install EnergyPlus
         run: |
@@ -44,6 +42,6 @@ jobs:
       - name: Execute tests
         env:
           PYTHON_KEYRING_BACKEND: keyring.backends.null.Keyring
-          PYTHONPATH: "/usr/local/EnergyPlus-23-2-0/:.:$PYTHONPATH"
         run: |
-          python tests/__init__.py
+          poetry install
+          poetry run tests

.gitignore

@@ -1,3 +1,2 @@
-env/
 __pycache__/
 .idea/

.pre-commit-config.yaml

@@ -0,0 +1,87 @@
+default_language_version:
+  python: python3
+
+ci:
+  autofix_prs: true
+  autoupdate_commit_msg: "[pre-commit.ci] pre-commit suggestions"
+  autoupdate_schedule: quarterly
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      # list of supported hooks: https://pre-commit.com/hooks.html
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-case-conflict
+      - id: debug-statements
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: ["--maxkb=5000", "--enforce-all"]
+        exclude: |
+          (?x)^(
+          )$
+
+  - repo: https://github.com/python-poetry/poetry
+    rev: "1.5.0"
+    hooks:
+      - id: poetry-check
+      # too slow
+      # - id: poetry-lock
+      - id: poetry-export
+        args: ["-f", "requirements.txt", "-o", "requirements.txt"]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.7.0
+    hooks:
+      - id: pyupgrade
+        args: [--py37-plus]
+        name: Upgrade code
+
+  # python formatting
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+        name: Format code
+        args: ["--line-length=120"]
+
+  - repo: https://github.com/hadialqattan/pycln
+    rev: v2.1.5 # Possible releases: https://github.com/hadialqattan/pycln/releases
+    hooks:
+      - id: pycln
+        args: [--all]
+
+  # ref: https://github.com/microsoft/vscode-isort]
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        name: isort (python)
+        args: [--profile, "black"]
+
+  # python docstring formatting
+  - repo: https://github.com/myint/docformatter
+    rev: v1.7.3
+    hooks:
+      - id: docformatter
+        args: [--in-place, --wrap-summaries, "99", --wrap-descriptions, "92"]
+
+  # yaml formatting
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.0.0-alpha.9-for-vscode
+    hooks:
+      - id: prettier
+        types: [yaml]
+
+  # markdown formatting
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.16
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-gfm
+          #- mdformat-black
+          - mdformat_frontmatter
+        exclude: CHANGELOG.md

README.md

@@ -1,8 +1,10 @@
 [![RLlib EnergyPlus Tests](https://github.com/airboxlab/rllib-energyplus/actions/workflows/tests.yml/badge.svg)](https://github.com/airboxlab/rllib-energyplus/actions/workflows/tests.yml)
 
-# Ray RLlib - EnergyPlus Python API integration
+# EnergyPlus environments for Reinforcement Learning
 
-An example of how to train a control policy using Ray RLlib and EnergyPlus Python API.
+This project implements a gym environment that handles [EnergyPlus](https://energyplus.net/) simulations
+for Reinforcement Learning (RL) experiments, using the EnergyPlus Python API.
+It also provides a set of examples and tools to train RL agents.
 
 Requires Python 3.8+, EnergyPlus 9.3+
 
@@ -25,6 +27,7 @@ docker run --rm --name rllib-energyplus -it rllib-energyplus
 ```
 
 Notes:
+
 - Remove `--rm` to keep the container after exiting.
 - If you want to use tensorboard, start the container with `--network host` parameter.
 - If you want to use a GPU, start the container with `--gpus all` parameter.
@@ -33,24 +36,47 @@ Inside the container, run the experiment
 
 ```shell
 cd /root/rllib-energyplus
-python3 rllibenergyplus/run.py --idf model.idf --epw LUX_LU_Luxembourg.AP.065900_TMYx.2004-2018.epw --framework torch
+# run the Amphitheater example
+python3 rleplus/train/rllib.py --env AmphitheaterEnv
 ```
 
-### Using virtual environment
+### Using a virtual environment
+
+#### Using poetry
+
+Install Poetry if you don't have it already:
+
+```shell
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+See more installation options [here](https://python-poetry.org/docs/#installation).
+
+This project comes with a `pyproject.toml` file that lists all dependencies.
+Packages versions are pinned (in `poetry.lock`) to ensure reproducibility.
+
+```shell
+poetry install
+```
 
-#### Package dependencies
+#### Using pip
 
-Edit `requirements.txt` and add the deep learning framework of your choice (TensorFlow or PyTorch)
+The poetry lock file is automatically converted to a requirements file, so you can also install dependencies with pip:
 
 ```shell
+# Create a virtual environment
 python3 -m venv env
+# Activate the virtual environment
 source env/bin/activate
+# Install dependencies
 pip install -r requirements.txt
 ```
 
-#### Path dependencies
+### Path dependencies
 
-Add EnergyPlus folder to `PYTHONPATH` environment variable:
+This project depends on the EnergyPlus Python API. An auto-discovery mechanism is used to find the API,
+but in case it fails, you can manually add the path to the API to the `PYTHONPATH` environment variable
+using the following:
 
 ```shell
 export PYTHONPATH="/usr/local/EnergyPlus-23-2-0/:$PYTHONPATH"
@@ -65,24 +91,42 @@ $ python3 -c 'from pyenergyplus.api import EnergyPlusAPI; print(EnergyPlusAPI.ap
 
 ## Run example
 
+Run the amphitheater example with default parameters using Ray RLlib PPO algorithm:
+
+### Using Poetry
+
 ```shell
-python3 rllibenergyplus/run.py \
-  --idf /path/to/model.idf \
-  --epw /path/to/LUX_LU_Luxembourg.AP.065900_TMYx.2004-2018.epw
+poetry run rllib --env AmphitheaterEnv
 ```
 
-Example of episode reward stats obtained training with PPO, 1e5 timesteps, 2 workers, with default parameters + LSTM, short E+ run period (2 first weeks of January). 
+### Using Python
+
+If you installed dependencies with pip, you can run the example with:
+
+```shell
+python3 rleplus/train/rllib.py --env AmphitheaterEnv
+```
+
+````shell
+Example of episode reward stats obtained training with PPO, 1e5 timesteps, 2 workers, with default parameters + LSTM, short E+ run period (2 first weeks of January).
 Experiment took ~20min.
 
 ![PPO stats](images/ppo_untuned.png "PPO training - Single AHU model")
 
+## Creating a new environment
+
+To create a new environment, you need to create a new class that inherits from `rleplus.envs.EnergyPlusEnv`
+and implement abstract methods. See existing environments for examples.
+
+Once your environment is ready, it must be declared in the `rleplus.examples.registry` module, so it gets registered.
+
 ## Tracking an experiment
 
-Tensorboard is installed with requirements. 
-To track an experiment running in a docker container, the container must be started with `--network host` parameter. 
+Tensorboard is installed with requirements.
+To track an experiment running in a docker container, the container must be started with `--network host` parameter.
 
 Start tensorboard with:
 
 ```shell
 tensorboard --logdir ~/ray_results --bind_all
-```
+````

docker/Dockerfile

@@ -1,7 +1,7 @@
 FROM ubuntu:22.04
 
 LABEL org.opencontainers.image.source="https://github.com/airboxlab/rllib-energyplus"
-LABEL org.opencontainers.image.description="RLlib + EnergyPlus for Reinforcement Learning in Building Energy Management Systems"
+LABEL org.opencontainers.image.description="EnergyPlus Env for Reinforcement Learning in Building Energy Management Systems"
 
 ARG EPLUS_VERSION=23-2-0
 ARG EPLUS_DL_URL=https://github.com/NREL/EnergyPlus/releases/download/v23.2.0/EnergyPlus-23.2.0-7636e6b3e9-Linux-Ubuntu22.04-x86_64.sh
@@ -35,8 +35,8 @@ RUN \
     # cleanup
     apt autoremove -qq -y && apt-get clean -qq && rm -rf /var/lib/apt/lists/*
 
-COPY model.idf LUX_LU_Luxembourg.AP.065900_TMYx.2004-2018.epw /root/rllib-energyplus/
-COPY rllibenergyplus /root/rllib-energyplus/rllibenergyplus
+COPY rleplus /root/rllib-energyplus/rleplus
+
+ENV PYTHONPATH=/root/rllib-energyplus
 
-ENV PYTHONPATH="/usr/local/EnergyPlus-${EPLUS_VERSION}"
 ENTRYPOINT "/bin/bash"