From 2ee9a6b00407383dddedec8f0392319ce9d1ad22 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 15 Feb 2022 17:55:14 +0000 Subject: [PATCH 001/113] aux: create separate extended version for usage inside containers --- setup.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/setup.py b/setup.py index 44d1d342..dbfced2d 100644 --- a/setup.py +++ b/setup.py @@ -10,20 +10,21 @@ with open("HISTORY.rst", encoding="UTF-8") as history_file: history = history_file.read() -version = "0.3.0" +version = "0.3.0" # pylint: disable=invalid-name requirements = [ - "wandb", "docker", - "ray[rllib]", "click", +] + +# The extended requirements are only used inside experiment/gym containers +extended_requirements = [ + "ray[rllib]", + "wandb", "torch", "gym", ] - -test_requirements = [] - setup( author="rdnfn", python_requires=">=3.6", @@ -39,6 +40,9 @@ ], description="Beobench is a toolbox for benchmarking reinforcement learning (RL) algorithms on building energy optimisation (BEO) problems.", # pylint: disable=line-too-long install_requires=requirements, + extras_require={ + "extended": extended_requirements, + }, license="MIT license", long_description=readme + "\n\n" + history, include_package_data=True, @@ -51,7 +55,6 @@ ], }, test_suite="tests", - tests_require=test_requirements, project_urls={ "Documentation": "https://beobench.readthedocs.io/", "Code": "https://github.com/rdnfn/beobench", From a4280d0b11991abf3c7c11c86aca377e35932dfe Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 15 Feb 2022 17:57:44 +0000 Subject: [PATCH 002/113] docs: add change to history --- HISTORY.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/HISTORY.rst b/HISTORY.rst index d41120c8..ee1d4f57 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,6 +2,11 @@ History ======= +0.3.1 (2022-00-00) +------------------ + +* Make dependencies that are only used inside experiment/gym containers optional (for all dependencies install via ``pip install beobench[extended]``) + 0.3.0 (2022-02-14) ------------------ From 8e96882daa5470e19ba1a7561bfda6a0b89458f5 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 10:28:16 +0000 Subject: [PATCH 003/113] docs: simplify pypi readme --- PYPI_README.rst | 83 +------------------------------------------------ 1 file changed, 1 insertion(+), 82 deletions(-) diff --git a/PYPI_README.rst b/PYPI_README.rst index 14dd34bc..923dd5b0 100644 --- a/PYPI_README.rst +++ b/PYPI_README.rst @@ -1,84 +1,3 @@ -.. image:: https://github.com/rdnfn/beobench/raw/master/docs/_static/beobench_logo.png - :align: center - :width: 300 px - :alt: Beobench - -.. start-in-sphinx-docs - -.. image:: https://img.shields.io/pypi/v/beobench.svg - :target: https://pypi.python.org/pypi/beobench - -.. image:: https://readthedocs.org/projects/beobench/badge/?version=latest - :target: https://beobench.readthedocs.io/en/latest/?version=latest - :alt: Documentation Status - -.. image:: https://img.shields.io/badge/License-MIT-blue.svg - :target: https://opensource.org/licenses/MIT - :alt: License - A toolbox for benchmarking reinforcement learning (RL) algorithms on building energy optimisation (BEO) problems. Beobench tries to make working on RL for BEO easier: it provides simple access to existing libraries defining BEO problems (such as `BOPTEST `_) and provides a large set of pre-configured RL algorithms. Beobench is *not* a gym library itself - instead it leverages the brilliant work done by many existing gym-type projects and makes their work more easily accessible. -Features --------- - -*Some of the features are work in progress* - -Main features - -- *RL algorithm collection:* what's the best RL method for your BEO problem? Building on `Ray RLlib `_, beobench provides a large collection of pre-configured RL algorithm experiments that can be easily applied to your new BEO problem. -- *Problem collection:* beobench provides ready-to-use docker containers for popular BEO gym-type problem libraries. By enforcing a strict OpenAI ``gym.Env`` it makes testing your method on different libraries easy. - -Additional features - -- *Experiment logging:* log experiment results in a reproducible and shareable manner via `Weights and Biases`_. -- *Hyperparameter tuning:* easily tune hyperparameters using the extensive `Ray Tune Search API `_. -- *Simple installation:* beobench can be installed via pip and only requires docker as an additional non-python dependency. -- *Easily extendable:* beobench is designed for the user to add both environments and methods. - -.. _Weights and Biases: https://wandb.ai/ - -.. end-in-sphinx-docs - - -.. start-quickstart - -Quickstart ----------- - -Run your first beobench experiment in three steps: - -1. `Install docker `_ on your machine (if on Linux, check the `additional installation steps `_) -2. Install *beobench* using: - - .. code-block:: console - - pip install beobench - -3. Finally, start your first experiment using: - - .. code-block:: console - - python -m beobench.experiment.scheduler - -Done, you have just started your first experiment... congrats! Check out the `full getting started guide in the documentation `_ for the next steps. - -.. end-quickstart - -Documentation -------------- -https://beobench.readthedocs.io - -License -------- -MIT license - - - -Credits -------- - -This package was originally created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. - -.. _Cookiecutter: https://github.com/audreyr/cookiecutter -.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage - +For more information go to the `documentation `_ and the `GitHub code repository `_. \ No newline at end of file From 36a75d5548b2b8dc1ce542a067ff37002f06d875 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 12:15:58 +0000 Subject: [PATCH 004/113] aux: add beobench_contrib as submodule --- .gitmodules | 3 +++ beobench_contrib | 1 + 2 files changed, 4 insertions(+) create mode 100644 .gitmodules create mode 160000 beobench_contrib diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..0aea4b24 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "beobench_contrib"] + path = beobench_contrib + url = https://github.com/rdnfn/beobench_contrib.git diff --git a/beobench_contrib b/beobench_contrib new file mode 160000 index 00000000..dab4fd6e --- /dev/null +++ b/beobench_contrib @@ -0,0 +1 @@ +Subproject commit dab4fd6e7c6f96d687fc6eb7efaf5caac49fed6b From 613741ddb672a6231086028df2ef88b8217f27df Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 12:21:10 +0000 Subject: [PATCH 005/113] aux: remove adapted mounts from devcontainer --- .devcontainer/devcontainer.json | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 2bd80550..87399f46 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -17,12 +17,11 @@ "workspaceFolder": "/workspace", // "workspaceMount": "source=remote-workspace,target=/workspace,type=volume", // ADAPT: the mount must be adapted to cloned repo location - "workspaceMount": "source=/home/rdnfn-docker/main/repos/github/beobench/,target=/workspace/beobench/,type=bind,consistency=cached", + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace/beobench/,type=bind,consistency=cached", // ADAPT: the mount must be adapted to the gitconfig location on the remote machine - "mounts": [ - "source=/home/rdnfn-docker/.gitconfig,target=/root/.gitconfig,type=bind,consistency=cached", - "source=/home/rdnfn-docker/main/repos/github/beobench_contrib,target=/workspace/beobench_contrib/,type=bind,consistency=cached" - ], + //"mounts": [ + // "source=${localEnv:HOME}/.gitconfig,target=/root/.gitconfig,type=bind,consistency=cached", + //], "postCreateCommand": "cd ./beobench && pip install -e .", // Set *default* container specific settings.json values on container create. "settings": { @@ -66,6 +65,8 @@ }, "runArgs": [ "--shm-size=32gb", - "--gpus=all" + "--gpus=all", + "--env-file", + ".devcontainer/devcontainer.env", ] } \ No newline at end of file From 74b296e8e8ab0affde6dd5ac8d6ef5e84f61dc7b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 14:01:43 +0000 Subject: [PATCH 006/113] aux: update main devcontainer --- .devcontainer/devcontainer.json | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 87399f46..b4ecd374 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -14,15 +14,15 @@ "NODE_VERSION": "none" } }, - "workspaceFolder": "/workspace", + "workspaceFolder": "/beobench", // "workspaceMount": "source=remote-workspace,target=/workspace,type=volume", // ADAPT: the mount must be adapted to cloned repo location - "workspaceMount": "source=${localWorkspaceFolder},target=/workspace/beobench/,type=bind,consistency=cached", + "workspaceMount": "source=${localWorkspaceFolder},target=/beobench,type=bind,consistency=cached", // ADAPT: the mount must be adapted to the gitconfig location on the remote machine //"mounts": [ // "source=${localEnv:HOME}/.gitconfig,target=/root/.gitconfig,type=bind,consistency=cached", //], - "postCreateCommand": "cd ./beobench && pip install -e .", + "postCreateCommand": "pip install -e .", // Set *default* container specific settings.json values on container create. "settings": { "python.defaultInterpreterPath": "/usr/local/bin/python", @@ -66,7 +66,5 @@ "runArgs": [ "--shm-size=32gb", "--gpus=all", - "--env-file", - ".devcontainer/devcontainer.env", ] } \ No newline at end of file From 56355b7e5d292dd488e541fa87e5a4f782e1599b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 14:04:50 +0000 Subject: [PATCH 007/113] aux: move remote devcontainer to separate folder --- .../remote/.devcontainer/devcontainer.json | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .devcontainer/remote/.devcontainer/devcontainer.json diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json new file mode 100644 index 00000000..d4be1627 --- /dev/null +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -0,0 +1,70 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: +// https://github.com/microsoft/vscode-dev-containers/tree/v0.205.2/containers/python-3 +{ + "name": "beobench dev (python3.10)", + "build": { + "dockerfile": "../../Dockerfile", + "context": "../../..", + "args": { + // Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6 + // Append -bullseye or -buster to pin to an OS version. + // Use -bullseye variants on local on arm64/Apple Silicon. + "VARIANT": "3.8", + // Options + "NODE_VERSION": "none" + } + }, + "workspaceFolder": "/beobench", + // "workspaceMount": "source=remote-workspace,target=/workspace,type=volume", + // ADAPT: the mount must be adapted to cloned repo location + "workspaceMount": "source=/home/rdnfn-docker/main/repos/github/beobench/,target=/beobench/,type=bind,consistency=cached", + // ADAPT: the mount must be adapted to the gitconfig location on the remote machine + "mounts": [ + "source=/home/rdnfn-docker/.gitconfig,target=/root/.gitconfig,type=bind,consistency=cached", + ], + "postCreateCommand": "pip install -e .", + // Set *default* container specific settings.json values on container create. + "settings": { + "python.defaultInterpreterPath": "/usr/local/bin/python", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true, + "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8", + "python.formatting.blackPath": "/usr/local/py-utils/bin/black", + "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf", + "python.linting.banditPath": "/usr/local/py-utils/bin/bandit", + "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8", + "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy", + "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle", + "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle", + "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint", + "files.trimTrailingWhitespace": true, + "python.formatting.provider": "black", + "editor.formatOnSave": true, + "editor.rulers": [ + 88 + ] + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "ms-python.python", + "ms-python.vscode-pylance", + "ms-azuretools.vscode-docker", + "trond-snekvik.simple-rst", + "lextudio.restructuredtext", + "njpwerner.autodocstring" + ], + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + // Use 'postCreateCommand' to run commands after the container is created. + // "postCreateCommand": "pip3 install --user -r requirements.txt", + // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. + // "remoteUser": "vscode", + "features": { + "git": "latest", + "docker-in-docker": "20.10" + }, + "runArgs": [ + "--shm-size=32gb", + "--gpus=all", + ] +} \ No newline at end of file From 522680f736c09ff26d3b898df54fd88d328345f0 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 14:50:41 +0000 Subject: [PATCH 008/113] aux: update docker files - fix debian version to buster because ray not available on bullseye image - make nvidia support optional --- .devcontainer/Dockerfile | 3 ++- .devcontainer/devcontainer.json | 6 ++++-- .devcontainer/remote/.devcontainer/devcontainer.json | 3 ++- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 75e291eb..7d83d0da 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -10,12 +10,13 @@ RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/ # [Optional] If your pip requirements rarely change, uncomment this section to add them to the image. COPY requirements/dev_requirements.txt requirements/doc_requirements.txt /tmp/pip-tmp/ +RUN pip3 install --upgrade pip RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/dev_requirements.txt \ -r /tmp/pip-tmp/doc_requirements.txt \ && rm -rf /tmp/pip-tmp # Install nvidia container runtime -RUN wget -O tmp/nvidia-container-toolkit.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/nvidia-container-toolkit_1.7.0-1_amd64.deb \ +RUN if [ "${NVIDIA_SUPPORT}" != "none" ]; then wget -O tmp/nvidia-container-toolkit.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/nvidia-container-toolkit_1.7.0-1_amd64.deb \ && wget -O tmp/nvidia-container-tools.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container-tools_1.7.0-1_amd64.deb \ && wget -O tmp/libnvidia-container.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container1_1.7.0-1_amd64.deb \ && dpkg --install --recursive tmp \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index b4ecd374..5832395a 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,9 +9,11 @@ // Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6 // Append -bullseye or -buster to pin to an OS version. // Use -bullseye variants on local on arm64/Apple Silicon. - "VARIANT": "3.8", + // Note: ray[rllib] is not available on debian 11 (bullseye) + "VARIANT": "3.9-buster", // Options - "NODE_VERSION": "none" + "NODE_VERSION": "none", + "NVIDIA_SUPPORT": "none" } }, "workspaceFolder": "/beobench", diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index d4be1627..25469520 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -11,7 +11,8 @@ // Use -bullseye variants on local on arm64/Apple Silicon. "VARIANT": "3.8", // Options - "NODE_VERSION": "none" + "NODE_VERSION": "none", + "NVIDIA_SUPPORT": "true" } }, "workspaceFolder": "/beobench", From a39e9f0aa14bf5e953386f22d21aeecd0039a9fb Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 15:33:50 +0000 Subject: [PATCH 009/113] fix: correct if statement in dockerfile and change container name --- .devcontainer/Dockerfile | 2 +- .devcontainer/devcontainer.json | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 7d83d0da..ab8455ac 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -20,7 +20,7 @@ RUN if [ "${NVIDIA_SUPPORT}" != "none" ]; then wget -O tmp/nvidia-container-tool && wget -O tmp/nvidia-container-tools.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container-tools_1.7.0-1_amd64.deb \ && wget -O tmp/libnvidia-container.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container1_1.7.0-1_amd64.deb \ && dpkg --install --recursive tmp \ - && rm tmp/nvidia-container-toolkit.deb + && rm tmp/nvidia-container-toolkit.deb; fi diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 5832395a..75c5719c 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,7 +1,7 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: // https://github.com/microsoft/vscode-dev-containers/tree/v0.205.2/containers/python-3 { - "name": "beobench dev (python3.10)", + "name": "beobench_devcontainer", "build": { "dockerfile": "Dockerfile", "context": "..", @@ -24,6 +24,7 @@ //"mounts": [ // "source=${localEnv:HOME}/.gitconfig,target=/root/.gitconfig,type=bind,consistency=cached", //], + //"initializeCommand": "export DOCKER_BUILDKIT=0 && export COMPOSE_DOCKER_CLI_BUILD=0", "postCreateCommand": "pip install -e .", // Set *default* container specific settings.json values on container create. "settings": { From ecb4db7cab15bce53e0b18e92f8c264ecef6bb1b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 16:01:03 +0000 Subject: [PATCH 010/113] fix: add nvidia support as arg to dockerfile --- .devcontainer/Dockerfile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index ab8455ac..4461e8c3 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -15,7 +15,8 @@ RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/dev_ -r /tmp/pip-tmp/doc_requirements.txt \ && rm -rf /tmp/pip-tmp -# Install nvidia container runtime +# [Optional] install nvidia container runtime (custom to beobench, this enables gpu-using containers within devcontainer) +ARG NVIDIA_SUPPORT="none" RUN if [ "${NVIDIA_SUPPORT}" != "none" ]; then wget -O tmp/nvidia-container-toolkit.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/nvidia-container-toolkit_1.7.0-1_amd64.deb \ && wget -O tmp/nvidia-container-tools.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container-tools_1.7.0-1_amd64.deb \ && wget -O tmp/libnvidia-container.deb https://nvidia.github.io/libnvidia-container/stable/debian10/amd64/libnvidia-container1_1.7.0-1_amd64.deb \ From c9fd7a373d67f6b44bcd0161aae96385c3010ab4 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 16:26:08 +0000 Subject: [PATCH 011/113] aux: remove gpu requirement from default devcontainer --- .devcontainer/devcontainer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 75c5719c..4f8a6a16 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -67,7 +67,7 @@ "docker-in-docker": "20.10" }, "runArgs": [ - "--shm-size=32gb", - "--gpus=all", + //"--shm-size=32gb", + //"--gpus=all", ] } \ No newline at end of file From 0d55a4e2ab153cbbfcf944c5e72026da80ddcfd8 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 16:40:32 +0000 Subject: [PATCH 012/113] aux: update devcontainer to bullseye - to achieve this remove ray dependency (directly in dev container) --- .devcontainer/devcontainer.json | 2 +- requirements/dev_requirements.txt | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 4f8a6a16..d44470a8 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -10,7 +10,7 @@ // Append -bullseye or -buster to pin to an OS version. // Use -bullseye variants on local on arm64/Apple Silicon. // Note: ray[rllib] is not available on debian 11 (bullseye) - "VARIANT": "3.9-buster", + "VARIANT": "3.9-bullseye", // Options "NODE_VERSION": "none", "NVIDIA_SUPPORT": "none" diff --git a/requirements/dev_requirements.txt b/requirements/dev_requirements.txt index 66db0b5b..61976f21 100644 --- a/requirements/dev_requirements.txt +++ b/requirements/dev_requirements.txt @@ -20,10 +20,10 @@ build # PyPA build tool jupyterlab # ML & RL tools -gym -torch -ray[rllib] -wandb +# gym +# torch +# ray[rllib] +# wandb # Convex solver tools (OPTIONAL) # cvxpy \ No newline at end of file From 7400af4959219c1c53e90521b38df734073eac15 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 17:26:42 +0000 Subject: [PATCH 013/113] feat: separate rllib integration into module --- beobench/cli.py | 2 +- beobench/experiment/definitions/default.py | 3 +- beobench/experiment/scheduler.py | 141 +++------------------ beobench/integration/rllib.py | 121 ++++++++++++++++++ 4 files changed, 139 insertions(+), 128 deletions(-) create mode 100644 beobench/integration/rllib.py diff --git a/beobench/cli.py b/beobench/cli.py index 6d78d146..b6e141e9 100644 --- a/beobench/cli.py +++ b/beobench/cli.py @@ -124,7 +124,7 @@ def run( docker_shm_size=docker_shm_size, no_additional_container=no_additional_container, use_no_cache=use_no_cache, - _dev_beobench_location=dev_beobench_location, + dev_beobench_location=dev_beobench_location, ) diff --git a/beobench/experiment/definitions/default.py b/beobench/experiment/definitions/default.py index 30575885..9d396ff4 100644 --- a/beobench/experiment/definitions/default.py +++ b/beobench/experiment/definitions/default.py @@ -1,6 +1,5 @@ """Default experiment definitions.""" -import ray.tune problem = { "name": "problem_001", @@ -56,7 +55,7 @@ "framework": "torch", "log_level": "WARNING", "num_workers": 8, # 1 for silent mode, can at least be 6 - "seed": ray.tune.randint(0, 10000000), + # "seed": ray.tune.randint(0, 10000000), }, "log_to_file": True, "checkpoint_freq": 10000, diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 41a436c2..764e0b34 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -5,9 +5,12 @@ import subprocess import pathlib import importlib.util -import ray.tune -import ray.tune.integration.wandb -import ray.tune.integration.mlflow + +# RLlib integration is only available inside experiment container +try: + import beobench.integration.rllib +except ImportError: + pass import beobench.experiment.definitions.utils @@ -32,7 +35,7 @@ def run( docker_shm_size: str = "2gb", no_additional_container: bool = False, use_no_cache: bool = False, - _dev_beobench_location: str = None, + dev_beobench_location: str = None, ) -> None: """Run experiment. @@ -65,7 +68,7 @@ def run( is started to run experiments in. use_no_cache (bool, optional): whether to use cache to build experiment container. - _dev_beobench_location (str, optional): github path to beobench package. For + dev_beobench_location (str, optional): github path to beobench package. For developement purpose only. This will install a custom beobench version inside the experiment container. By default the latest PyPI version is installed. @@ -82,32 +85,16 @@ def run( # Execute experiment # (this is usually reached from inside an experiment container) - # Add wandb callback if sufficient information - # TODO: add earlier check to see that also API key available - if wandb_project and wandb_entity: - callbacks = [_create_wandb_callback(wandb_project, wandb_entity)] - elif wandb_project or wandb_entity: - raise ValueError( - "Only one of wandb_project or wandb_entity given, but both required." - ) - elif mlflow_name: - callbacks = [_create_mlflow_callback(mlflow_name)] - else: - callbacks = [] - - # change RLlib setup if GPU used - if use_gpu: - experiment_def["rllib_setup"]["rllib_experiment_config"]["config"][ - "num_gpus" - ] = 1 - # run experiment in ray tune if not agent_file: - run_in_tune( + beobench.integration.rllib.run_in_tune( problem_def=experiment_def["problem"], method_def=experiment_def["method"], rllib_setup=experiment_def["rllib_setup"], - rllib_callbacks=callbacks, + wandb_entity=wandb_entity, + wandb_project=wandb_project, + mlflow_name=mlflow_name, + use_gpu=use_gpu, ) else: # run custom RL agent @@ -192,9 +179,9 @@ def run( cmd_list_in_container = [""] # dev mode where custom beobench is installed directly from git - if _dev_beobench_location is not None: + if dev_beobench_location is not None: cmd_list_in_container.append("pip uninstall --yes beobench") - cmd_list_in_container.append(f"pip install {_dev_beobench_location}") + cmd_list_in_container.append(f"pip install {dev_beobench_location}") cmd_in_container = " && ".join(cmd_list_in_container) @@ -224,102 +211,6 @@ def run( subprocess.check_call(args) -def run_in_tune( - problem_def: dict, method_def: dict, rllib_setup: dict, rllib_callbacks: list = None -) -> ray.tune.ExperimentAnalysis: - """Run beobench experiment. - - Additional info: note that RLlib is a submodule of the ray package, i.e. it is - imported as `ray.rllib`. For experiment definitions it uses the `ray.tune` - submodule. Therefore ray tune experiment definition means the same as ray rllib - experiment defintions. To avoid confusion all variable/argument names use rllib - instead of ray tune but strictly speaking these are ray tune experiment - definitions. - - Args: - problem_def (dict): definition of problem. This is an incomplete - ray tune experiment defintion that only defines the problem side. - method_def (dict): definition of method. This is an incomplete - ray tune experiment defintion that only defines the method side. - rllib_setup (dict): rllib setup. This is an incomplete - ray tune experiment defintion that only defines the ray tune/rllib setup - (e.g. number of workers, etc.). - rllib_callbacks (list, optional): callbacks to add to ray.tune.run command. - Defaults to None. - - Returns: - ray.tune.ExperimentAnalysis: analysis object of completed experiment. - """ - if rllib_callbacks is None: - rllib_callbacks = [] - - # combine the three incomplete ray tune experiment - # definitions into a single complete one. - exp_config = beobench.experiment.definitions.utils.get_experiment_config( - problem_def, method_def, rllib_setup - ) - - # register the problem environment with ray tune - # env_creator is a module available in experiment containers - import env_creator # pylint: disable=import-outside-toplevel,import-error - - ray.tune.registry.register_env( - problem_def["rllib_experiment_config"]["config"]["env"], - env_creator.create_env, - ) - - # if run in notebook, change the output reported throughout experiment. - if beobench.utils.check_if_in_notebook(): - reporter = ray.tune.JupyterNotebookReporter(overwrite=True) - else: - reporter = None - - # running the experiment - analysis = ray.tune.run( - progress_reporter=reporter, - callbacks=rllib_callbacks, - **exp_config, - ) - - return analysis - - -def _create_wandb_callback( - wandb_project: str, - wandb_entity: str, -): - """Create an RLlib weights and biases (wandb) callback. - - Args: - wandb_project (str): name of wandb project. - wandb_entity (str): name of wandb entity that owns project. - - Returns: - : a wandb callback - """ - wandb_callback = ray.tune.integration.wandb.WandbLoggerCallback( - project=wandb_project, log_config=True, entity=wandb_entity - ) - return wandb_callback - - -def _create_mlflow_callback( - mlflow_name: str, -): - """Create an RLlib MLflow callback. - - Args: - mlflow_name (str, optional): name of MLflow experiment. - - Returns: - : a wandb callback - """ - mlflow_callback = ray.tune.integration.mlflow.MLflowLoggerCallback( - experiment_name=mlflow_name, tracking_uri="file:/root/ray_results/mlflow" - ) - return mlflow_callback - - def _create_experiment_def( experiment_file: pathlib.Path, method: str, env: str ) -> dict: @@ -385,7 +276,7 @@ def _load_experiment_file(experiment_file: pathlib.Path) -> dict: experiment_file_mod = importlib.util.module_from_spec(spec) spec.loader.exec_module(experiment_file_mod) - experiment_def = dict() + experiment_def = {} # Create experiment def dictionary, and set default values if not available # from experiment_file (module). diff --git a/beobench/integration/rllib.py b/beobench/integration/rllib.py new file mode 100644 index 00000000..7c985f4c --- /dev/null +++ b/beobench/integration/rllib.py @@ -0,0 +1,121 @@ +"""RLlib integration in beobench.""" + +import ray.tune +import ray.tune.integration.wandb +import ray.tune.integration.mlflow + +import beobench.utils + + +def run_in_tune( + problem_def: dict, + method_def: dict, + rllib_setup: dict, + wandb_project: str = None, + wandb_entity: str = None, + mlflow_name: str = None, + use_gpu: bool = False, +) -> ray.tune.ExperimentAnalysis: + """Run beobench experiment. + + Additional info: note that RLlib is a submodule of the ray package, i.e. it is + imported as `ray.rllib`. For experiment definitions it uses the `ray.tune` + submodule. Therefore ray tune experiment definition means the same as ray rllib + experiment defintions. To avoid confusion all variable/argument names use rllib + instead of ray tune but strictly speaking these are ray tune experiment + definitions. + + Args: + problem_def (dict): definition of problem. This is an incomplete + ray tune experiment defintion that only defines the problem side. + method_def (dict): definition of method. This is an incomplete + ray tune experiment defintion that only defines the method side. + rllib_setup (dict): rllib setup. This is an incomplete + ray tune experiment defintion that only defines the ray tune/rllib setup + (e.g. number of workers, etc.). + rllib_callbacks (list, optional): callbacks to add to ray.tune.run command. + Defaults to None. + + Returns: + ray.tune.ExperimentAnalysis: analysis object of completed experiment. + """ + if wandb_project and wandb_entity: + callbacks = [_create_wandb_callback(wandb_project, wandb_entity)] + elif wandb_project or wandb_entity: + raise ValueError( + "Only one of wandb_project or wandb_entity given, but both required." + ) + elif mlflow_name: + callbacks = [_create_mlflow_callback(mlflow_name)] + else: + callbacks = [] + + # change RLlib setup if GPU used + if use_gpu: + rllib_setup["rllib_experiment_config"]["config"]["num_gpus"] = 1 + + # combine the three incomplete ray tune experiment + # definitions into a single complete one. + exp_config = beobench.experiment.definitions.utils.get_experiment_config( + problem_def, method_def, rllib_setup + ) + + # register the problem environment with ray tune + # env_creator is a module available in experiment containers + import env_creator # pylint: disable=import-outside-toplevel,import-error + + ray.tune.registry.register_env( + problem_def["rllib_experiment_config"]["config"]["env"], + env_creator.create_env, + ) + + # if run in notebook, change the output reported throughout experiment. + if beobench.utils.check_if_in_notebook(): + reporter = ray.tune.JupyterNotebookReporter(overwrite=True) + else: + reporter = None + + # running the experiment + analysis = ray.tune.run( + progress_reporter=reporter, + callbacks=callbacks, + **exp_config, + ) + + return analysis + + +def _create_wandb_callback( + wandb_project: str, + wandb_entity: str, +): + """Create an RLlib weights and biases (wandb) callback. + + Args: + wandb_project (str): name of wandb project. + wandb_entity (str): name of wandb entity that owns project. + + Returns: + : a wandb callback + """ + wandb_callback = ray.tune.integration.wandb.WandbLoggerCallback( + project=wandb_project, log_config=True, entity=wandb_entity + ) + return wandb_callback + + +def _create_mlflow_callback( + mlflow_name: str, +): + """Create an RLlib MLflow callback. + + Args: + mlflow_name (str, optional): name of MLflow experiment. + + Returns: + : a wandb callback + """ + mlflow_callback = ray.tune.integration.mlflow.MLflowLoggerCallback( + experiment_name=mlflow_name, tracking_uri="file:/root/ray_results/mlflow" + ) + return mlflow_callback From 80b04b114211196d3760c3af349c2de129d8b96d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 17:49:48 +0000 Subject: [PATCH 014/113] aux: remove ray dependency from experiment definitions --- beobench/experiment/definitions/experiment_003_sinergym.py | 6 +++--- beobench/experiment/definitions/experiment_004_energym.py | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/beobench/experiment/definitions/experiment_003_sinergym.py b/beobench/experiment/definitions/experiment_003_sinergym.py index 5da9de21..392c801f 100644 --- a/beobench/experiment/definitions/experiment_003_sinergym.py +++ b/beobench/experiment/definitions/experiment_003_sinergym.py @@ -1,7 +1,7 @@ """An experiment to test sinergym integration.""" -import ray.tune -from beobench.experiment.definitions.default import problem, method, rllib_setup +# import ray.tune +# from beobench.experiment.definitions.default import problem, method, rllib_setup problem = { @@ -34,7 +34,7 @@ "log_level": "WARNING", "num_workers": 8, # 1 for silent mode, can at least be 6 "num_gpus": 1, - "seed": ray.tune.randint(0, 10000000), + # "seed": ray.tune.randint(0, 10000000), }, # "log_to_file": True, "checkpoint_freq": 10000, diff --git a/beobench/experiment/definitions/experiment_004_energym.py b/beobench/experiment/definitions/experiment_004_energym.py index 1bfabcbe..f6b96683 100644 --- a/beobench/experiment/definitions/experiment_004_energym.py +++ b/beobench/experiment/definitions/experiment_004_energym.py @@ -1,13 +1,12 @@ """An experiment to test sinergym integration.""" -import ray.tune -from beobench.experiment.definitions.default import problem, method, rllib_setup +# import ray.tune problem = { "name": "sinergym_test_problem", "description": ("Control problem corresponding to " "created by sinergym env ''."), - "problem_library": "https://github.com/rdnfn/beobench_contrib.git#dev/energym-integration:gyms/energym", + "problem_library": "energym", "rllib_experiment_config": { "config": { "env": "MixedUseFanFCU-v0", @@ -40,7 +39,7 @@ "log_level": "WARNING", "num_workers": 1, # 1 for silent mode, can at least be 6 "num_gpus": 1, - "seed": ray.tune.randint(0, 10000000), + # "seed": ray.tune.randint(0, 10000000), }, # "log_to_file": True, "checkpoint_freq": 10000, From a9d2b947f33f77568ef5a6bc1046dd9db8c5eaec Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 19:29:35 +0000 Subject: [PATCH 015/113] docs: update contributing guide to devcontainer setup --- CONTRIBUTING.rst | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 74d680a0..857affb1 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -64,13 +64,9 @@ Ready to contribute? Here's how to set up `beobench` for local development. $ git clone git@github.com:your_name_here/beobench.git -3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:: +3. Follow the :doc:`this guide ` to setup the development environment. - $ mkvirtualenv beobench - $ cd beobench/ - $ python setup.py develop - -4. Create a branch for local development:: +4. Inside the devcontainer just setup, create a branch for local development:: $ git checkout -b name-of-your-bugfix-or-feature @@ -80,11 +76,9 @@ Ready to contribute? Here's how to set up `beobench` for local development. tests, including testing other Python versions with tox:: $ flake8 beobench tests - $ python setup.py test or pytest + $ python setup.py test $ tox - To get flake8 and tox, just pip install them into your virtualenv. - 6. Commit your changes and push your branch to GitHub:: $ git add . @@ -102,8 +96,9 @@ Before you submit a pull request, check that it meets these guidelines: 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. -3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check - https://travis-ci.com/rdnfn/beobench/pull_requests +3. The pull request should work for Python 3.6, 3.7, 3.8 and 3.9. + +.. Check https://travis-ci.com/rdnfn/beobench/pull_requests and make sure that the tests pass for all supported Python versions. Tips From 90df793a5e878f362df5fb3f316e5cce66254353 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 16 Feb 2022 20:03:41 +0000 Subject: [PATCH 016/113] docs: update the dev env guide --- docs/guides/dev_env.rst | 43 ++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/guides/dev_env.rst b/docs/guides/dev_env.rst index e5ef68cd..12a78787 100644 --- a/docs/guides/dev_env.rst +++ b/docs/guides/dev_env.rst @@ -6,39 +6,46 @@ Setting up development environment Requirements ^^^^^^^^^^^^^^^^^^ -Beobench uses `vscode dev containers `_ for its development environment. The installation has the following pre-requisites on the local machine: +Beobench uses `vscode devcontainers `_ for its development environment. A devcontainer allows all developers to work on (almost) identical systems, ensuring that not only python packages but also operating systems are the same. The installation of this development environment has the following pre-requisites: 1. `Docker `_ 2. `Visual Studio Code (vscode) `_ 3. `vscode remote extension pack `_ -Additionally, for remote development, the remote machine must have docker installed. +Standard development +^^^^^^^^^^^^^^^^^^^^ -Local development -^^^^^^^^^^^^^^^^^^ - +1. Fork the Beobench repo on GitHub (if you are a maintainer you can skip this step). +2. Clone your fork locally using -1. Clone the repo locally to your machine using + .. code-block:: - .. code-block:: + git clone --recursive git@github.com:your_name_here/beobench.git - git clone git@github.com:rdnfn/beobench.git + (if you are a maintainer you can clone directly from the main repository) -2. Open the git repo folder in vscode -3. Inside vscode, open the command palette (shortcut is ``shift`` + ``cmd`` + ``P`` on macos), and use the ``Remote-containers: open folder in container`` command. Select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo). +3. Open the beobench repo folder in vscode +4. Inside vscode, open the command palette (e.g. on macOS shortcut is ``shift`` + ``cmd`` + ``P``), and use the ``Remote-containers: reopen in container`` command. -This should have opened a new vscode window running in the docker dev container -- once the dev container is ready you're done! (Note: this gets faster after the first docker build) +This should have opened a new vscode window running in the docker dev container --- once the dev container is ready you're done! (Note: this gets faster after the first docker build) Remote development ^^^^^^^^^^^^^^^^^^ -It may be desireable to run your dev container on a remote machine. In order to do this you need to follow the following steps: +.. note:: + Remote development is only useful if you have a separate server available to develop on. The standard development in the previous section will be more useful in most scenarios. + + +It may be desireable to run your devcontainer not directly on your local machine (e.g. laptop) but instead on a remote machine (i.e. server). The local machine then just provides an interface to the remote machine. + +In order to set this up you need to follow these steps: -1. Follow all the instructions for local development above (apart from the final step 3). -2. Clone the repo to your *remote* machine. -3. In the cloned repo on your local machine, in ``.devcontainer/devcontainer.json`` replace the line +1. Follow all the instructions for local development above (apart from the final step 4). +2. Ensure that docker is installed on the remote machine. +3. Clone the repo to your *remote* machine. +4. In the cloned repo on your local machine, in ``.devcontainer/remote/.devcontainer/devcontainer.json`` replace the line .. code-block:: @@ -51,8 +58,8 @@ It may be desireable to run your dev container on a remote machine. In order to "workspaceMount": "source=,target=/workspace,type=bind,consistency=cached" - where ``PATH_TO_CLONED_REPO`` is the path to your repo on the remote machine. + where ``PATH_TO_CLONED_REPO`` is the path to your repo on the remote machine. Similarly, adapt the path in the ``"mounts"`` argument to the location of your ``.gitconfig`` file on the remote machine. -4. Create a docker context on your local machine that connects to docker on your remote machine (`See the instructions here `_). -5. Use the ``Remote-containers: open folder in container`` command and select the ``beobench`` repo in the pop-up window (NOT the ``beobench`` folder inside the repo). +5. Create a docker context on your local machine that connects to docker on your remote machine (`See the instructions here `_). +6. Use the ``Remote-containers: open folder in container`` command and select the ``beobench/.devcontainer/remote`` folder in the pop-up window (beobench here is the main repo folder). From 222e04d1e326e94313663dfd42835bb9bf568762 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 17 Feb 2022 09:11:18 +0000 Subject: [PATCH 017/113] docs: update contributing guide --- CONTRIBUTING.rst | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 857affb1..de2da604 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -59,33 +59,28 @@ Get Started! Ready to contribute? Here's how to set up `beobench` for local development. -1. Fork the `beobench` repo on GitHub. -2. Clone your fork locally:: +1. Follow :doc:`this guide ` to fork the repo and setup the development environment. - $ git clone git@github.com:your_name_here/beobench.git +2. Inside the devcontainer just set up, create a branch for local development:: -3. Follow the :doc:`this guide ` to setup the development environment. - -4. Inside the devcontainer just setup, create a branch for local development:: - - $ git checkout -b name-of-your-bugfix-or-feature + $ git checkout -b dev/name-of-your-bugfix-or-feature Now you can make your changes locally. -5. When you're done making changes, check that your changes pass flake8 and the +3. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:: $ flake8 beobench tests $ python setup.py test $ tox -6. Commit your changes and push your branch to GitHub:: +4. Commit your changes and push your branch to GitHub:: $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature -7. Submit a pull request through the GitHub website. +5. Submit a pull request through the GitHub website. Pull Request Guidelines ----------------------- @@ -96,7 +91,7 @@ Before you submit a pull request, check that it meets these guidelines: 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. -3. The pull request should work for Python 3.6, 3.7, 3.8 and 3.9. +.. 3. The pull request should work for Python 3.6, 3.7, 3.8 and 3.9. .. Check https://travis-ci.com/rdnfn/beobench/pull_requests and make sure that the tests pass for all supported Python versions. From aaa1c097b1c06a43d6dc2a3553a15cd594d3939b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 17 Feb 2022 09:20:28 +0000 Subject: [PATCH 018/113] aux: add git history extension to dev container --- .devcontainer/devcontainer.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index d44470a8..a25e0a81 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -54,7 +54,8 @@ "ms-azuretools.vscode-docker", "trond-snekvik.simple-rst", "lextudio.restructuredtext", - "njpwerner.autodocstring" + "njpwerner.autodocstring", + "donjayamanne.githistory", ], // Use 'forwardPorts' to make a list of ports inside the container available locally. // "forwardPorts": [], From 7615b8a618e0897449ad6d1fd6d046477f474d0a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sat, 5 Mar 2022 16:27:36 +0000 Subject: [PATCH 019/113] aux: rename remote devcontainer --- .devcontainer/remote/.devcontainer/devcontainer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 25469520..3e64153b 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -1,7 +1,7 @@ // For format details, see https://aka.ms/devcontainer.json. For config options, see the README at: // https://github.com/microsoft/vscode-dev-containers/tree/v0.205.2/containers/python-3 { - "name": "beobench dev (python3.10)", + "name": "beobench_devcontainer_remote", "build": { "dockerfile": "../../Dockerfile", "context": "../../..", From 975363f970a7424d8ea79c87586f4cdaef5bdffd Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sat, 5 Mar 2022 17:29:30 +0000 Subject: [PATCH 020/113] feat: add config argument to scheduler --- beobench/experiment/config_parser.py | 25 +++++++++++++++++++++++++ beobench/experiment/scheduler.py | 13 ++++++++++++- setup.py | 1 + 3 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 beobench/experiment/config_parser.py diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py new file mode 100644 index 00000000..d839a64a --- /dev/null +++ b/beobench/experiment/config_parser.py @@ -0,0 +1,25 @@ +"""Experiment config parser module""" + +from typing import Union +import pathlib +import yaml + + +def parse(config: Union[str, pathlib.Path]) -> dict: + """Parse experiment config from yaml file to dict. + + Args: + config (Union[str, pathlib.Path]): path of yaml file + """ + + # load config dict if path given + if isinstance(config, (str, pathlib.Path)): + # make sure config is a real path + if isinstance(config, str): + config = pathlib.Path(config) + with open(config) as config_file: + config_dict = yaml.safe_load(config_file) + else: + config_dict = config + + return config_dict diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 764e0b34..c9958705 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -5,6 +5,8 @@ import subprocess import pathlib import importlib.util +import warnings +from typing import Union # RLlib integration is only available inside experiment container try: @@ -18,10 +20,12 @@ import beobench.experiment.definitions.methods import beobench.experiment.definitions.envs import beobench.experiment.containers +import beobench.experiment.config_parser import beobench.utils def run( + config: Union[str, dict] = None, experiment_file: str = None, agent_file: str = None, method: str = None, @@ -43,8 +47,10 @@ def run( interface. Args: + config (str or dict, optional): experiment configuration. This can either be + a dictionary or a path to a yaml file. experiment_file (str, optional): File that defines experiment. - Defaults to None. + Defaults to None. DEPRECATED. agent_file (str, optional): File that defines custom agent. This script is executed inside the gym container. method (str, optional): RL method to use in experiment. This overwrites any @@ -74,9 +80,14 @@ def run( installed. """ + config = beobench.experiment.config_parser.parse(config) # Create a definition of experiment from inputs if experiment_file is not None: experiment_file = pathlib.Path(experiment_file) + warnings.warn( + "The experiment_file argmunet has been replaced by config", + DeprecationWarning, + ) if agent_file is not None: agent_file = pathlib.Path(agent_file) experiment_def = _create_experiment_def(experiment_file, method, env) diff --git a/setup.py b/setup.py index dbfced2d..b80bd49d 100644 --- a/setup.py +++ b/setup.py @@ -15,6 +15,7 @@ requirements = [ "docker", "click", + "pyyaml", ] # The extended requirements are only used inside experiment/gym containers From 8b0559506aa37ac838278449b2a57ce9b002dfd9 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sat, 5 Mar 2022 21:21:10 +0000 Subject: [PATCH 021/113] feat: add template yaml config --- beobench/experiment/definitions/default.yaml | 29 ++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 beobench/experiment/definitions/default.yaml diff --git a/beobench/experiment/definitions/default.yaml b/beobench/experiment/definitions/default.yaml new file mode 100644 index 00000000..ecdce75b --- /dev/null +++ b/beobench/experiment/definitions/default.yaml @@ -0,0 +1,29 @@ +# agent config +agent: + type: rllib + rllib_config: # given to ray.tune.run() as kwargs + run_or_experiment: PPO + stop: + timesteps_total: 400000 + config: + lr: 0.005 + model: + fcnet_activation: relu + fcnet_hiddens: [256,256,256,256] + post_fcnet_activation: tanh + batch_mode: complete_episodes + gamma: 0.999 + horizon: 1000 + metrics_smoothing_episodes: 5 +# environment config +env: + gym: energym + name: MixedUseFanFCU-v0 + config: + days: 365 + energym_environment: MixedUseFanFCU-v0 + gym_kwargs: + max_episode_length: 35040 + normalize: true + step_period: 15 + weather: GRC_A_Athens From e6cd0a98fd2873b65ae02e69a021f19a50b3dc91 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:11:39 +0000 Subject: [PATCH 022/113] feat: add config to rllib config parser --- beobench/experiment/config_parser.py | 29 +++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index d839a64a..0a426311 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -10,6 +10,9 @@ def parse(config: Union[str, pathlib.Path]) -> dict: Args: config (Union[str, pathlib.Path]): path of yaml file + + Returns: + dict: config in dictionary """ # load config dict if path given @@ -17,9 +20,33 @@ def parse(config: Union[str, pathlib.Path]) -> dict: # make sure config is a real path if isinstance(config, str): config = pathlib.Path(config) - with open(config) as config_file: + with open(config, "r", encoding="utf-8") as config_file: config_dict = yaml.safe_load(config_file) else: config_dict = config return config_dict + + +def create_rllib_config(config: dict) -> dict: + """Create a configuration for ray.tune.run() method. + + Args: + config (dict): beobench config + + Raises: + ValueError: this is raised if the config does not specify an rllib agent. + + Returns: + dict: kwargs for ray.tune.run() method + """ + + # Check if config is with rllib agent + if config["agent"]["origin"] is not "rllib": + raise ValueError("Configuration does not have rllib agent origin set.") + + rllib_config = config["agent"]["config"] + rllib_config["config"]["env_config"] = config["env"]["config"] + rllib_config["config"]["env"] = config["env"]["name"] + + return rllib_config From 3d5f4a3110f34ff7cbbfa0d5321a5324be8b2f10 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:20:38 +0000 Subject: [PATCH 023/113] feat: update rllib integration to use config --- beobench/integration/rllib.py | 40 ++++++++++++++++------------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/beobench/integration/rllib.py b/beobench/integration/rllib.py index 7c985f4c..f4cd75e1 100644 --- a/beobench/integration/rllib.py +++ b/beobench/integration/rllib.py @@ -5,12 +5,11 @@ import ray.tune.integration.mlflow import beobench.utils +import beobench.experiment.config_parser def run_in_tune( - problem_def: dict, - method_def: dict, - rllib_setup: dict, + config: dict, wandb_project: str = None, wandb_entity: str = None, mlflow_name: str = None, @@ -26,18 +25,17 @@ def run_in_tune( definitions. Args: - problem_def (dict): definition of problem. This is an incomplete - ray tune experiment defintion that only defines the problem side. - method_def (dict): definition of method. This is an incomplete - ray tune experiment defintion that only defines the method side. - rllib_setup (dict): rllib setup. This is an incomplete - ray tune experiment defintion that only defines the ray tune/rllib setup - (e.g. number of workers, etc.). - rllib_callbacks (list, optional): callbacks to add to ray.tune.run command. - Defaults to None. + config (dict): beobench config + wandb_project (str, optional): name of wandb project. Defaults to None. + wandb_entity (str, optional): name of wandb entirty. Defaults to None. + mlflow_name (str, optional): name of mlflow experiment. Defaults to None. + use_gpu (bool, optional): whether to use GPU. Defaults to False. + + Raises: + ValueError: raised if only one of wandb project or wandb entity given. Returns: - ray.tune.ExperimentAnalysis: analysis object of completed experiment. + ray.tune.ExperimentAnalysis: analysis object from experiment. """ if wandb_project and wandb_entity: callbacks = [_create_wandb_callback(wandb_project, wandb_entity)] @@ -50,22 +48,20 @@ def run_in_tune( else: callbacks = [] - # change RLlib setup if GPU used - if use_gpu: - rllib_setup["rllib_experiment_config"]["config"]["num_gpus"] = 1 - # combine the three incomplete ray tune experiment # definitions into a single complete one. - exp_config = beobench.experiment.definitions.utils.get_experiment_config( - problem_def, method_def, rllib_setup - ) + rllib_config = beobench.experiment.config_parser.create_rllib_config(config) + + # change RLlib setup if GPU used + if use_gpu: + rllib_config["config"]["num_gpus"] = 1 # register the problem environment with ray tune # env_creator is a module available in experiment containers import env_creator # pylint: disable=import-outside-toplevel,import-error ray.tune.registry.register_env( - problem_def["rllib_experiment_config"]["config"]["env"], + rllib_config["config"]["env"], env_creator.create_env, ) @@ -79,7 +75,7 @@ def run_in_tune( analysis = ray.tune.run( progress_reporter=reporter, callbacks=callbacks, - **exp_config, + **rllib_config, ) return analysis From 2ba39a09ec0ba5e5ceba373f1b9e8a9916c17879 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:41:03 +0000 Subject: [PATCH 024/113] feat: add default config to config parser --- beobench/experiment/config_parser.py | 46 ++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index 0a426311..6b694094 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -50,3 +50,49 @@ def create_rllib_config(config: dict) -> dict: rllib_config["config"]["env"] = config["env"]["name"] return rllib_config + + +def get_default() -> dict: + """Get default beobench config + + Returns: + dict: default beobench config dict + """ + + config = { + "agent": { + "origin": "rllib", + "config": { + "run_or_experiment": "PPO", + "stop": {"timesteps_total": 400000}, + "config": { + "lr": 0.005, + "model": { + "fcnet_activation": "relu", + "fcnet_hiddens": [256, 256, 256, 256], + "post_fcnet_activation": "tanh", + }, + "batch_mode": "complete_episodes", + "gamma": 0.999, + "horizon": 1000, + "metrics_smoothing_episodes": 5, + }, + }, + }, + "env": { + "name": "MixedUseFanFCU-v0", + "gym": "energym", + "config": { + "days": 365, + "energym_environment": "MixedUseFanFCU-v0", + "gym_kwargs": { + "max_episode_length": 35040, + "normalize": True, + "step_period": 15, + }, + "weather": "GRC_A_Athens", + }, + }, + } + + return config From 14520a9e274ac2c6205be056d4a17a9482f0d2d3 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:43:30 +0000 Subject: [PATCH 025/113] feat: update scheduler to use config file --- beobench/experiment/scheduler.py | 38 +++++++++++++++++++------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index c9958705..0e97a902 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -52,7 +52,7 @@ def run( experiment_file (str, optional): File that defines experiment. Defaults to None. DEPRECATED. agent_file (str, optional): File that defines custom agent. This script is - executed inside the gym container. + executed inside the gym container. DEPRECATED, this should be set in config. method (str, optional): RL method to use in experiment. This overwrites any method that is set in experiment file. For example 'PPO'. Defaults to None. env (str, optional): environment to apply method to in experiment. This @@ -80,28 +80,39 @@ def run( installed. """ - config = beobench.experiment.config_parser.parse(config) + # get config dict from config argument + if config: + config = beobench.experiment.config_parser.parse(config) + else: + config = beobench.experiment.config_parser.get_default_config() # Create a definition of experiment from inputs if experiment_file is not None: - experiment_file = pathlib.Path(experiment_file) warnings.warn( "The experiment_file argmunet has been replaced by config", DeprecationWarning, ) if agent_file is not None: - agent_file = pathlib.Path(agent_file) - experiment_def = _create_experiment_def(experiment_file, method, env) + warnings.warn( + "The agent_file argmunet has been replaced by config", + DeprecationWarning, + ) + + if config["agent"]["origin"] == "rllib": + agent_file = None + else: + agent_file = pathlib.Path(config["agent"]["origin"]) + + # TODO add parsing of high level API arguments env and agent if no_additional_container: # Execute experiment # (this is usually reached from inside an experiment container) # run experiment in ray tune - if not agent_file: + + if config["agent"]["origin"] == "rllib": beobench.integration.rllib.run_in_tune( - problem_def=experiment_def["problem"], - method_def=experiment_def["method"], - rllib_setup=experiment_def["rllib_setup"], + config, wandb_entity=wandb_entity, wandb_project=wandb_project, mlflow_name=mlflow_name, @@ -122,7 +133,7 @@ def run( # docker setup image_tag = beobench.experiment.containers.build_experiment_container( - build_context=experiment_def["problem"]["problem_library"], + build_context=config["env"]["gym"], use_no_cache=use_no_cache, ) @@ -148,7 +159,7 @@ def run( ] # enable docker-from-docker access only for built-in boptest integration. - if experiment_def["problem"]["problem_library"] == "boptest": + if config["env"]["gym"] == "boptest": # Create docker network (only useful if starting other containers) beobench.experiment.containers.create_docker_network("beobench-net") @@ -171,16 +182,13 @@ def run( # define flags for beobench scheduler call inside experiment container beobench_flags = [] - if experiment_file: - beobench_flags.append(f"--experiment-file={exp_file_on_docker}") + beobench_flags.append(f"--config={config}") if wandb_project: beobench_flags.append(f"--wandb-project={wandb_project}") if wandb_entity: beobench_flags.append(f"--wandb-entity={wandb_entity}") if use_gpu: beobench_flags.append("--use-gpu") - if agent_file: - beobench_flags.append(f"--agent-file={agent_file}") beobench_flag_str = " ".join(beobench_flags) # if no wandb API key is given try to get it from env From 4543c7ed8b8d3265453c9c8c344dc3f861667237 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:43:46 +0000 Subject: [PATCH 026/113] aux: update default config --- beobench/experiment/definitions/default.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/beobench/experiment/definitions/default.yaml b/beobench/experiment/definitions/default.yaml index ecdce75b..02593072 100644 --- a/beobench/experiment/definitions/default.yaml +++ b/beobench/experiment/definitions/default.yaml @@ -1,7 +1,7 @@ # agent config agent: - type: rllib - rllib_config: # given to ray.tune.run() as kwargs + origin: rllib # either path to agent script or name of agent library (rllib) + config: # given to ray.tune.run() as arguments (since rllib set before) run_or_experiment: PPO stop: timesteps_total: 400000 @@ -17,8 +17,8 @@ agent: metrics_smoothing_episodes: 5 # environment config env: - gym: energym name: MixedUseFanFCU-v0 + gym: energym config: days: 365 energym_environment: MixedUseFanFCU-v0 From d7aa24f5dfdc232c437912eba11b520ff8cd4528 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 12:54:06 +0000 Subject: [PATCH 027/113] docs: add note on github auth --- docs/guides/dev_env.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/dev_env.rst b/docs/guides/dev_env.rst index 12a78787..a30700ef 100644 --- a/docs/guides/dev_env.rst +++ b/docs/guides/dev_env.rst @@ -25,6 +25,8 @@ Standard development (if you are a maintainer you can clone directly from the main repository) + Note that this requires having your github authentification setup, `see here `_ + 3. Open the beobench repo folder in vscode 4. Inside vscode, open the command palette (e.g. on macOS shortcut is ``shift`` + ``cmd`` + ``P``), and use the ``Remote-containers: reopen in container`` command. From e164081c741c2b237bf85be270794d77338c0651 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 13:49:02 +0000 Subject: [PATCH 028/113] aux: update devcontainer --- .devcontainer/remote/.devcontainer/devcontainer.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 3e64153b..65cb1ef6 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -9,10 +9,10 @@ // Update 'VARIANT' to pick a Python version: 3, 3.10, 3.9, 3.8, 3.7, 3.6 // Append -bullseye or -buster to pin to an OS version. // Use -bullseye variants on local on arm64/Apple Silicon. - "VARIANT": "3.8", + "VARIANT": "3.9", // Options "NODE_VERSION": "none", - "NVIDIA_SUPPORT": "true" + "NVIDIA_SUPPORT": "none" } }, "workspaceFolder": "/beobench", From 47edcd71db4be8f4995b6d2b4f4fe386fe3345c6 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 14:37:06 +0000 Subject: [PATCH 029/113] aux: change dind feature config --- .devcontainer/remote/.devcontainer/devcontainer.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 65cb1ef6..5dc671fc 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -62,7 +62,10 @@ // "remoteUser": "vscode", "features": { "git": "latest", - "docker-in-docker": "20.10" + "docker-in-docker": { + "version": "latest", + "moby": true + } }, "runArgs": [ "--shm-size=32gb", From 0ef1b5fdd8e4bcfa6bb205844a1a314d2c6a7fc2 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 14:55:23 +0000 Subject: [PATCH 030/113] aux: add init arg to devcontainer --- .devcontainer/remote/.devcontainer/devcontainer.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 65cb1ef6..668d03c0 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -67,5 +67,6 @@ "runArgs": [ "--shm-size=32gb", "--gpus=all", + "--init" ] } \ No newline at end of file From d80364f88fbd93ee632d826911f172f37aaab27b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Sun, 6 Mar 2022 15:04:21 +0000 Subject: [PATCH 031/113] aux: remove init arg in remote devcontainer json --- .devcontainer/remote/.devcontainer/devcontainer.json | 1 - 1 file changed, 1 deletion(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 91532df0..5dc671fc 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -70,6 +70,5 @@ "runArgs": [ "--shm-size=32gb", "--gpus=all", - "--init" ] } \ No newline at end of file From d0f15bc6dbf7b58d38c5ee62f82b238f0b5d463b Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 21 Mar 2022 19:05:09 +0000 Subject: [PATCH 032/113] fix: update name of default function --- beobench/experiment/scheduler.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 0e97a902..63b3111e 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -79,12 +79,13 @@ def run( inside the experiment container. By default the latest PyPI version is installed. """ + # pylint: disable=unused-argument # get config dict from config argument if config: config = beobench.experiment.config_parser.parse(config) else: - config = beobench.experiment.config_parser.get_default_config() + config = beobench.experiment.config_parser.get_default() # Create a definition of experiment from inputs if experiment_file is not None: warnings.warn( From d620ae2b64ac22e6f486880cb69f86a79ebdfc1e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 13:53:15 +0000 Subject: [PATCH 033/113] feat: add config to cli --- beobench/cli.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/beobench/cli.py b/beobench/cli.py index b6e141e9..6deb8768 100644 --- a/beobench/cli.py +++ b/beobench/cli.py @@ -1,6 +1,8 @@ """Command line interface for beobench.""" import click +import ast + import beobench.experiment.scheduler import beobench.utils @@ -11,6 +13,12 @@ def cli(): @cli.command() +@click.option( + "--config", + default=None, + help="Json or filepath with yaml that defines beobench experiment configuration.", + type=str, +) @click.option( "--experiment-file", default=None, @@ -85,6 +93,7 @@ def cli(): help="For developer use only: location of custom beobench package version.", ) def run( + config: str, experiment_file: str, agent_file: str, method: str, @@ -110,7 +119,12 @@ def run( # # See https://stackoverflow.com/a/40094408. + # Parse config str to dict if + if config[0] == "{": + config = ast.literal_eval(config) + beobench.experiment.scheduler.run( + config=config, experiment_file=experiment_file, agent_file=agent_file, method=method, From d49ee09fd0663f844c44cf2586133f35fa72c82e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 13:54:11 +0000 Subject: [PATCH 034/113] fix: allow for no config passed --- beobench/cli.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench/cli.py b/beobench/cli.py index 6deb8768..e88d8dec 100644 --- a/beobench/cli.py +++ b/beobench/cli.py @@ -120,7 +120,7 @@ def run( # See https://stackoverflow.com/a/40094408. # Parse config str to dict if - if config[0] == "{": + if config and config[0] == "{": config = ast.literal_eval(config) beobench.experiment.scheduler.run( From d6cd28e4f62040221d6632a4aed5587a76cfa3d6 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:11:34 +0000 Subject: [PATCH 035/113] fix: enable correct config parsing --- beobench/experiment/scheduler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 63b3111e..87296fd6 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -183,7 +183,7 @@ def run( # define flags for beobench scheduler call inside experiment container beobench_flags = [] - beobench_flags.append(f"--config={config}") + beobench_flags.append(f'--config="{config}"') if wandb_project: beobench_flags.append(f"--wandb-project={wandb_project}") if wandb_entity: From 2f07157122d9c4a2bf0b5f9445d8432cceaa6b3c Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:12:50 +0000 Subject: [PATCH 036/113] aux: add note on availability of rllib --- beobench/experiment/scheduler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 87296fd6..392ec0a2 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -12,7 +12,7 @@ try: import beobench.integration.rllib except ImportError: - pass + print("Note: RLlib beobench integration not available.") import beobench.experiment.definitions.utils From aa29809f03d34177c28dcbf66ddd1528ca39c873 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:26:34 +0000 Subject: [PATCH 037/113] aux: add import error --- beobench/experiment/scheduler.py | 1 + 1 file changed, 1 insertion(+) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 392ec0a2..4200d88d 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -12,6 +12,7 @@ try: import beobench.integration.rllib except ImportError: + raise ImportError print("Note: RLlib beobench integration not available.") From 0a7d35aa19836cdb161e452529e6e5eaaf681cb9 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:27:36 +0000 Subject: [PATCH 038/113] aux: add full integration import --- beobench/experiment/scheduler.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 4200d88d..92b228ce 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -9,10 +9,11 @@ from typing import Union # RLlib integration is only available inside experiment container +import beobench.integration.rllib + try: import beobench.integration.rllib except ImportError: - raise ImportError print("Note: RLlib beobench integration not available.") From 6619b7a89d35984a84d55f01eb17e9c2da0dc3fa Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:30:55 +0000 Subject: [PATCH 039/113] aux: add init module to integrations --- beobench/integration/__init__.py | 1 + 1 file changed, 1 insertion(+) create mode 100644 beobench/integration/__init__.py diff --git a/beobench/integration/__init__.py b/beobench/integration/__init__.py new file mode 100644 index 00000000..296a4adb --- /dev/null +++ b/beobench/integration/__init__.py @@ -0,0 +1 @@ +"""Subpackage with integrations""" From d2cfa563addbffa823e6453f41261480901ba0ee Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:32:33 +0000 Subject: [PATCH 040/113] aux: remove rllib integration export --- beobench/experiment/scheduler.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 92b228ce..e742f52f 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -8,9 +8,7 @@ import warnings from typing import Union -# RLlib integration is only available inside experiment container -import beobench.integration.rllib - +# RLlib integration is only available with extended extras. try: import beobench.integration.rllib except ImportError: From 7f6bae6f551af7c0749b20e29d938f6f4ac17c2d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:36:16 +0000 Subject: [PATCH 041/113] aux: improve config parser error message --- beobench/experiment/config_parser.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index 6b694094..941877a0 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -42,8 +42,13 @@ def create_rllib_config(config: dict) -> dict: """ # Check if config is with rllib agent - if config["agent"]["origin"] is not "rllib": - raise ValueError("Configuration does not have rllib agent origin set.") + if config["agent"]["origin"] != "rllib": + raise ValueError( + ( + "Configuration does not have rllib agent origin set." + f"Config is set to: {config}" + ) + ) rllib_config = config["agent"]["config"] rllib_config["config"]["env_config"] = config["env"]["config"] From 2cc7dd76d4dfa4251c82eaacc1c244482bc7539d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:40:18 +0000 Subject: [PATCH 042/113] fix: add torch as framework to default config --- beobench/experiment/config_parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index 941877a0..b5b3265e 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -70,6 +70,7 @@ def get_default() -> dict: "config": { "run_or_experiment": "PPO", "stop": {"timesteps_total": 400000}, + "framework": "torch", "config": { "lr": 0.005, "model": { From e3c6df0e4de535553ef48196077331a054e27c7c Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:41:32 +0000 Subject: [PATCH 043/113] fix: change location of framework in config --- beobench/experiment/config_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index b5b3265e..0cedb954 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -70,7 +70,6 @@ def get_default() -> dict: "config": { "run_or_experiment": "PPO", "stop": {"timesteps_total": 400000}, - "framework": "torch", "config": { "lr": 0.005, "model": { @@ -82,6 +81,7 @@ def get_default() -> dict: "gamma": 0.999, "horizon": 1000, "metrics_smoothing_episodes": 5, + "framework": "torch", }, }, }, From e2346acfbcf15e9bac35811ee1924fc60de8e374 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 17:28:50 +0000 Subject: [PATCH 044/113] add torch framework to default experiment config --- beobench/experiment/definitions/default.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/beobench/experiment/definitions/default.yaml b/beobench/experiment/definitions/default.yaml index 02593072..6de6a702 100644 --- a/beobench/experiment/definitions/default.yaml +++ b/beobench/experiment/definitions/default.yaml @@ -15,6 +15,7 @@ agent: gamma: 0.999 horizon: 1000 metrics_smoothing_episodes: 5 + framework: torch # environment config env: name: MixedUseFanFCU-v0 From 8dd619e5f64ac707996067bb10d785c90020d845 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 17:29:13 +0000 Subject: [PATCH 045/113] feat: include experiment definitions in package --- MANIFEST.in | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/MANIFEST.in b/MANIFEST.in index b1b593db..95c17ced 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -9,4 +9,6 @@ recursive-include tests * recursive-exclude * __pycache__ recursive-exclude * *.py[co] -recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif +recursive-include beobench/experiment/definitions * + +recursive-exclude docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif From a25b07ed2ab813c2d798c71344e57e4b53d5f98f Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 19:13:06 +0000 Subject: [PATCH 046/113] feat: load default config from yaml --- beobench/experiment/config_parser.py | 39 +++------------------------- 1 file changed, 3 insertions(+), 36 deletions(-) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index 0cedb954..acf289ca 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -3,6 +3,7 @@ from typing import Union import pathlib import yaml +import importlib.resources def parse(config: Union[str, pathlib.Path]) -> dict: @@ -64,41 +65,7 @@ def get_default() -> dict: dict: default beobench config dict """ - config = { - "agent": { - "origin": "rllib", - "config": { - "run_or_experiment": "PPO", - "stop": {"timesteps_total": 400000}, - "config": { - "lr": 0.005, - "model": { - "fcnet_activation": "relu", - "fcnet_hiddens": [256, 256, 256, 256], - "post_fcnet_activation": "tanh", - }, - "batch_mode": "complete_episodes", - "gamma": 0.999, - "horizon": 1000, - "metrics_smoothing_episodes": 5, - "framework": "torch", - }, - }, - }, - "env": { - "name": "MixedUseFanFCU-v0", - "gym": "energym", - "config": { - "days": 365, - "energym_environment": "MixedUseFanFCU-v0", - "gym_kwargs": { - "max_episode_length": 35040, - "normalize": True, - "step_period": 15, - }, - "weather": "GRC_A_Athens", - }, - }, - } + defs_path = importlib.resources.files("beobench.experiment.definitions") + config = parse(defs_path.joinpath("default.yaml")) return config From 6f214fdf51951e782ae52fdd81b9dedd47e1e763 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 19:13:47 +0000 Subject: [PATCH 047/113] feat: add separation of base and complete experiment images --- beobench/experiment/containers.py | 55 +++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/beobench/experiment/containers.py b/beobench/experiment/containers.py index 6babe49e..712e6f83 100644 --- a/beobench/experiment/containers.py +++ b/beobench/experiment/containers.py @@ -2,10 +2,13 @@ import subprocess import os +import importlib.resources def build_experiment_container( - build_context: str, docker_tag: str = None, use_no_cache: bool = False + build_context: str, + use_no_cache: bool = False, + version="latest", ) -> None: """Build experiment container from beobench/integrations/boptest/Dockerfile. @@ -17,6 +20,7 @@ def build_experiment_container( use_no_cache (bool, optional): wether to use cache in build. Defaults to False. """ + # Flags are shared between gym image build and gym_and_beobench image build flags = [] if use_no_cache: flags.append("--no-cache") @@ -28,7 +32,7 @@ def build_experiment_container( ] # pylint: disable=invalid-name if build_context in AVAILABLE_INTEGRATIONS: - docker_tag = f"beobench_{build_context}:latest" + image_name = f"beobench_{build_context}" integration_name = build_context build_context = ( f"https://github.com/rdnfn/" @@ -41,18 +45,20 @@ def build_experiment_container( ) ) else: - if docker_tag is None: - # get alphanumeric name from context - context_name = "".join(e for e in build_context if e.isalnum()) - docker_tag = f"beobench_custom_{context_name}:latest" + # get alphanumeric name from context + context_name = "".join(e for e in build_context if e.isalnum()) + image_name = f"beobench_custom_{context_name}" - print(f"Building experiment container `{docker_tag}`...") + base_image_tag = f"{image_name}_base:{version}" + print(f"Building experiment base image `{base_image_tag}`...") + + # Part 1: build base experiment image args = [ "docker", "build", "-t", - docker_tag, + base_image_tag, "-f", "Dockerfile", # change to non-default name *flags, @@ -65,9 +71,38 @@ def build_experiment_container( env=env, # this enables accessing dockerfile in subdir ) - print("Experiment container build finished.") + # Part 2: build complete experiment image + # This includes installation of beobench in experiment image + complete_image_tag = f"{image_name}_complete:{version}" + complete_dockerfile = str( + importlib.resources.files("beobench.experiment.dockerfiles").joinpath( + "Dockerfile.experiment" + ) + ) + # Load dockerfile into pipe + with subprocess.Popen(["cat", complete_dockerfile], stdout=subprocess.PIPE) as proc: + beobench_build_args = [ + "docker", + "build", + "-t", + complete_image_tag, + "-f", + "-", + "--build-arg", + f"GYM_IMAGE={base_image_tag}", + *flags, + build_context, + ] + print("Running command: " + " ".join(beobench_build_args)) + subprocess.check_call( + beobench_build_args, + stdin=proc.stdout, + env=env, # this enables accessing dockerfile in subdir + ) + + print("Experiment gym image build finished.") - return docker_tag + return complete_image_tag def create_docker_network(network_name: str) -> None: From fc1a302c7e0d32e24fa1bc49c1156162dcc1e786 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 19:14:27 +0000 Subject: [PATCH 048/113] feat: add shared dockerfile for complete experiment images --- beobench/experiment/dockerfiles/Dockerfile.experiment | 10 ++++++++++ beobench/experiment/dockerfiles/__init__.py | 1 + 2 files changed, 11 insertions(+) create mode 100644 beobench/experiment/dockerfiles/Dockerfile.experiment create mode 100644 beobench/experiment/dockerfiles/__init__.py diff --git a/beobench/experiment/dockerfiles/Dockerfile.experiment b/beobench/experiment/dockerfiles/Dockerfile.experiment new file mode 100644 index 00000000..5394c7e7 --- /dev/null +++ b/beobench/experiment/dockerfiles/Dockerfile.experiment @@ -0,0 +1,10 @@ +ARG GYM_IMAGE +FROM ${GYM_IMAGE} + +# install beobench +RUN pip3 --disable-pip-version-check --no-cache-dir install git+https://github.com/rdnfn/beobench + +# add env creator +COPY env_creator.py /opt/beobench/experiment_setup/ +# add env creator to python path +ENV PYTHONPATH "${PYTHONPATH}:/opt/beobench/experiment_setup/" \ No newline at end of file diff --git a/beobench/experiment/dockerfiles/__init__.py b/beobench/experiment/dockerfiles/__init__.py new file mode 100644 index 00000000..731c16b9 --- /dev/null +++ b/beobench/experiment/dockerfiles/__init__.py @@ -0,0 +1 @@ +"""Subpackage with dockerfiles for experiments.""" From e6f85d6fb79bcc799a4e2f3bf70b25090d03e318 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Tue, 22 Mar 2022 19:17:13 +0000 Subject: [PATCH 049/113] aux: add changes to history --- HISTORY.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/HISTORY.rst b/HISTORY.rst index ee1d4f57..ba257106 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -6,6 +6,8 @@ History ------------------ * Make dependencies that are only used inside experiment/gym containers optional (for all dependencies install via ``pip install beobench[extended]``) +* Add two part experiment image build process so that there is shared beobench installation dockerfile +* Add support for yaml config files 0.3.0 (2022-02-14) ------------------ From 8c43038a1977edb24580dde42d4b801e7da1c982 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 00:49:42 +0000 Subject: [PATCH 050/113] feat: make importlib.resources import compatible with python3.6 --- beobench/experiment/config_parser.py | 10 +++++++++- beobench/experiment/containers.py | 10 +++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/beobench/experiment/config_parser.py b/beobench/experiment/config_parser.py index acf289ca..a5abc600 100644 --- a/beobench/experiment/config_parser.py +++ b/beobench/experiment/config_parser.py @@ -3,7 +3,15 @@ from typing import Union import pathlib import yaml -import importlib.resources + +# To enable compatiblity with Python<=3.6 (e.g. for sinergym dockerfile) +try: + import importlib.resources +except ImportError: + import importlib_resources + import importlib + + importlib.resources = importlib_resources def parse(config: Union[str, pathlib.Path]) -> dict: diff --git a/beobench/experiment/containers.py b/beobench/experiment/containers.py index 712e6f83..6f86a833 100644 --- a/beobench/experiment/containers.py +++ b/beobench/experiment/containers.py @@ -2,7 +2,15 @@ import subprocess import os -import importlib.resources + +# To enable compatiblity with Python<=3.6 (e.g. for sinergym dockerfile) +try: + import importlib.resources +except ImportError: + import importlib_resources + import importlib + + importlib.resources = importlib_resources def build_experiment_container( From 4c67170ea9ca87e5f52b41cbb029f5a96f238097 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 00:58:01 +0000 Subject: [PATCH 051/113] aux: add example configurations --- .../definitions/example_energym.yaml | 30 +++++++++++++++++++ .../definitions/example_sinergym.yaml | 25 ++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 beobench/experiment/definitions/example_energym.yaml create mode 100644 beobench/experiment/definitions/example_sinergym.yaml diff --git a/beobench/experiment/definitions/example_energym.yaml b/beobench/experiment/definitions/example_energym.yaml new file mode 100644 index 00000000..6de6a702 --- /dev/null +++ b/beobench/experiment/definitions/example_energym.yaml @@ -0,0 +1,30 @@ +# agent config +agent: + origin: rllib # either path to agent script or name of agent library (rllib) + config: # given to ray.tune.run() as arguments (since rllib set before) + run_or_experiment: PPO + stop: + timesteps_total: 400000 + config: + lr: 0.005 + model: + fcnet_activation: relu + fcnet_hiddens: [256,256,256,256] + post_fcnet_activation: tanh + batch_mode: complete_episodes + gamma: 0.999 + horizon: 1000 + metrics_smoothing_episodes: 5 + framework: torch +# environment config +env: + name: MixedUseFanFCU-v0 + gym: energym + config: + days: 365 + energym_environment: MixedUseFanFCU-v0 + gym_kwargs: + max_episode_length: 35040 + normalize: true + step_period: 15 + weather: GRC_A_Athens diff --git a/beobench/experiment/definitions/example_sinergym.yaml b/beobench/experiment/definitions/example_sinergym.yaml new file mode 100644 index 00000000..2a68a5ba --- /dev/null +++ b/beobench/experiment/definitions/example_sinergym.yaml @@ -0,0 +1,25 @@ +# agent config +agent: + origin: rllib # either path to agent script or name of agent library (rllib) + config: # given to ray.tune.run() as arguments (since rllib set before) + run_or_experiment: PPO + stop: + timesteps_total: 400000 + config: + lr: 0.005 + model: + fcnet_activation: relu + fcnet_hiddens: [256,256,256,256] + post_fcnet_activation: tanh + batch_mode: complete_episodes + gamma: 0.999 + horizon: 1000 + metrics_smoothing_episodes: 5 + framework: torch +# environment config +env: + name: Eplus-5Zone-hot-continuous-v1 + gym: sinergym + config: + name: Eplus-5Zone-hot-continuous-v1 + normalize: True \ No newline at end of file From 49b2e087deb7c5b0f6613f4907ee9738d99b283e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 10:46:52 +0000 Subject: [PATCH 052/113] docs: add env table to readme --- README.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.rst b/README.rst index 2b3620e3..6459fa40 100644 --- a/README.rst +++ b/README.rst @@ -26,6 +26,13 @@ A toolbox for benchmarking reinforcement learning (RL) algorithms on building energy optimisation (BEO) problems. Beobench tries to make working on RL for BEO easier: it provides simple access to existing libraries defining BEO problems (such as `BOPTEST `_) and provides a large set of pre-configured RL algorithms. Beobench is *not* a gym library itself - instead it leverages the brilliant work done by many existing gym-type projects and makes their work more easily accessible. +Available environments +---------------------- + +.. csv-table:: Available environments + :file: ./docs/available_envs_parsed.csv + + Features -------- From b261b9a087837289a7633d42bc0660ad83ed473f Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 10:47:53 +0000 Subject: [PATCH 053/113] docs: add available envs tables --- docs/available_envs.csv | 41 ++++++++++++++++++++++++++++++++++ docs/available_envs_parsed.csv | 41 ++++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/available_envs.csv create mode 100644 docs/available_envs_parsed.csv diff --git a/docs/available_envs.csv b/docs/available_envs.csv new file mode 100644 index 00000000..ba8ed8b2 --- /dev/null +++ b/docs/available_envs.csv @@ -0,0 +1,41 @@ +Gym,Environment,House type +BOPTEST,bestest_air,residential +,bestest_hydronic,residential +,bestest_hydronic_heat_pump,residential +,multizone_residential_hydronic,residential +,singlezone_commercial_hydronic,office +Energym,Apartments2Thermal-v0,residential +,Apartments2Grid-v0,residential +,ApartmentsThermal-v0,residential +,ApartmentsGrid-v0,residential +,OfficesThermostat-v0,office +,MixedUseFanFCU-v0,office +,SeminarcenterThermostat-v0,office +,SeminarcenterFull-v0,office +,SimpleHouseRad-v0,residential +,SimpleHouseRSla-v0,residential +,SwissHouseRSlaW2W-v0,residential +,SwissHouseRSlaA2W-v0,residential +,SwissHouseRSlaTank-v0,residential +,SwissHouseRSlaTankDhw-v0,residential +Sinergym,Eplus-demo-v1,residential +,Eplus-5Zone-hot-discrete-v1,residential +,Eplus-5Zone-mixed-discrete-v1,residential +,Eplus-5Zone-cool-discrete-v1,residential +,Eplus-5Zone-hot-continuous-v1,residential +,Eplus-5Zone-mixed-continuous-v1,residential +,Eplus-5Zone-cool-continuous-v1,residential +,Eplus-5Zone-hot-discrete-stochastic-v1,residential +,Eplus-5Zone-mixed-discrete-stochastic-v1,residential +,Eplus-5Zone-cool-discrete-stochastic-v1,residential +,Eplus-5Zone-hot-continuous-stochastic-v1,residential +,Eplus-5Zone-mixed-continuous-stochastic-v1,residential +,Eplus-5Zone-cool-continuous-stochastic-v1,residential +,Eplus-datacenter-discrete-v1,industrial +,Eplus-datacenter-continuous-v1,industrial +,Eplus-datacenter-discrete-stochastic-v1,industrial +,Eplus-datacenter-continuous-stochastic-v1,industrial +,Eplus-IWMullion-discrete-v1,office +,Eplus-IWMullion-continuous-v1,office +,Eplus-IWMullion-discrete-stochastic-v1,office +,Eplus-IWMullion-continuous-stochastic-v1,office \ No newline at end of file diff --git a/docs/available_envs_parsed.csv b/docs/available_envs_parsed.csv new file mode 100644 index 00000000..f18ca2e1 --- /dev/null +++ b/docs/available_envs_parsed.csv @@ -0,0 +1,41 @@ +Gym,Environment,Type +BOPTEST,bestest_air,:house: +,bestest_hydronic,:house: +,bestest_hydronic_heat_pump,:house: +,multizone_residential_hydronic,:house: +,singlezone_commercial_hydronic,:office: +Energym,Apartments2Thermal-v0,:house: +,Apartments2Grid-v0,:house: +,ApartmentsThermal-v0,:house: +,ApartmentsGrid-v0,:house: +,OfficesThermostat-v0,:office: +,MixedUseFanFCU-v0,:office: +,SeminarcenterThermostat-v0,:office: +,SeminarcenterFull-v0,:office: +,SimpleHouseRad-v0,:house: +,SimpleHouseRSla-v0,:house: +,SwissHouseRSlaW2W-v0,:house: +,SwissHouseRSlaA2W-v0,:house: +,SwissHouseRSlaTank-v0,:house: +,SwissHouseRSlaTankDhw-v0,:house: +Sinergym,Eplus-demo-v1,:house: +,Eplus-5Zone-hot-discrete-v1,:house: +,Eplus-5Zone-mixed-discrete-v1,:house: +,Eplus-5Zone-cool-discrete-v1,:house: +,Eplus-5Zone-hot-continuous-v1,:house: +,Eplus-5Zone-mixed-continuous-v1,:house: +,Eplus-5Zone-cool-continuous-v1,:house: +,Eplus-5Zone-hot-discrete-stochastic-v1,:house: +,Eplus-5Zone-mixed-discrete-stochastic-v1,:house: +,Eplus-5Zone-cool-discrete-stochastic-v1,:house: +,Eplus-5Zone-hot-continuous-stochastic-v1,:house: +,Eplus-5Zone-mixed-continuous-stochastic-v1,:house: +,Eplus-5Zone-cool-continuous-stochastic-v1,:house: +,Eplus-datacenter-discrete-v1,:factory: +,Eplus-datacenter-continuous-v1,:factory: +,Eplus-datacenter-discrete-stochastic-v1,:factory: +,Eplus-datacenter-continuous-stochastic-v1,:factory: +,Eplus-IWMullion-discrete-v1,:office: +,Eplus-IWMullion-continuous-v1,:office: +,Eplus-IWMullion-discrete-stochastic-v1,:office: +,Eplus-IWMullion-continuous-stochastic-v1,:office: From d676d429ec8e561e1e3919fe57939c53586c3735 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 10:52:19 +0000 Subject: [PATCH 054/113] docs: update envs csv to use emojis --- docs/available_envs_parsed.csv | 80 +++++++++++++++++----------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/available_envs_parsed.csv b/docs/available_envs_parsed.csv index f18ca2e1..47238b13 100644 --- a/docs/available_envs_parsed.csv +++ b/docs/available_envs_parsed.csv @@ -1,41 +1,41 @@ Gym,Environment,Type -BOPTEST,bestest_air,:house: -,bestest_hydronic,:house: -,bestest_hydronic_heat_pump,:house: -,multizone_residential_hydronic,:house: -,singlezone_commercial_hydronic,:office: -Energym,Apartments2Thermal-v0,:house: -,Apartments2Grid-v0,:house: -,ApartmentsThermal-v0,:house: -,ApartmentsGrid-v0,:house: -,OfficesThermostat-v0,:office: -,MixedUseFanFCU-v0,:office: -,SeminarcenterThermostat-v0,:office: -,SeminarcenterFull-v0,:office: -,SimpleHouseRad-v0,:house: -,SimpleHouseRSla-v0,:house: -,SwissHouseRSlaW2W-v0,:house: -,SwissHouseRSlaA2W-v0,:house: -,SwissHouseRSlaTank-v0,:house: -,SwissHouseRSlaTankDhw-v0,:house: -Sinergym,Eplus-demo-v1,:house: -,Eplus-5Zone-hot-discrete-v1,:house: -,Eplus-5Zone-mixed-discrete-v1,:house: -,Eplus-5Zone-cool-discrete-v1,:house: -,Eplus-5Zone-hot-continuous-v1,:house: -,Eplus-5Zone-mixed-continuous-v1,:house: -,Eplus-5Zone-cool-continuous-v1,:house: -,Eplus-5Zone-hot-discrete-stochastic-v1,:house: -,Eplus-5Zone-mixed-discrete-stochastic-v1,:house: -,Eplus-5Zone-cool-discrete-stochastic-v1,:house: -,Eplus-5Zone-hot-continuous-stochastic-v1,:house: -,Eplus-5Zone-mixed-continuous-stochastic-v1,:house: -,Eplus-5Zone-cool-continuous-stochastic-v1,:house: -,Eplus-datacenter-discrete-v1,:factory: -,Eplus-datacenter-continuous-v1,:factory: -,Eplus-datacenter-discrete-stochastic-v1,:factory: -,Eplus-datacenter-continuous-stochastic-v1,:factory: -,Eplus-IWMullion-discrete-v1,:office: -,Eplus-IWMullion-continuous-v1,:office: -,Eplus-IWMullion-discrete-stochastic-v1,:office: -,Eplus-IWMullion-continuous-stochastic-v1,:office: +BOPTEST,bestest_air,🏠 +,bestest_hydronic,🏠 +,bestest_hydronic_heat_pump,🏠 +,multizone_residential_hydronic,🏠 +,singlezone_commercial_hydronic,🏢 +Energym,Apartments2Thermal-v0,🏠 +,Apartments2Grid-v0,🏠 +,ApartmentsThermal-v0,🏠 +,ApartmentsGrid-v0,🏠 +,OfficesThermostat-v0,🏢 +,MixedUseFanFCU-v0,🏢 +,SeminarcenterThermostat-v0,🏢 +,SeminarcenterFull-v0,🏢 +,SimpleHouseRad-v0,🏠 +,SimpleHouseRSla-v0,🏠 +,SwissHouseRSlaW2W-v0,🏠 +,SwissHouseRSlaA2W-v0,🏠 +,SwissHouseRSlaTank-v0,🏠 +,SwissHouseRSlaTankDhw-v0,🏠 +Sinergym,Eplus-demo-v1,🏠 +,Eplus-5Zone-hot-discrete-v1,🏠 +,Eplus-5Zone-mixed-discrete-v1,🏠 +,Eplus-5Zone-cool-discrete-v1,🏠 +,Eplus-5Zone-hot-continuous-v1,🏠 +,Eplus-5Zone-mixed-continuous-v1,🏠 +,Eplus-5Zone-cool-continuous-v1,🏠 +,Eplus-5Zone-hot-discrete-stochastic-v1,🏠 +,Eplus-5Zone-mixed-discrete-stochastic-v1,🏠 +,Eplus-5Zone-cool-discrete-stochastic-v1,🏠 +,Eplus-5Zone-hot-continuous-stochastic-v1,🏠 +,Eplus-5Zone-mixed-continuous-stochastic-v1,🏠 +,Eplus-5Zone-cool-continuous-stochastic-v1,🏠 +,Eplus-datacenter-discrete-v1,🏭 +,Eplus-datacenter-continuous-v1,🏭 +,Eplus-datacenter-discrete-stochastic-v1,🏭 +,Eplus-datacenter-continuous-stochastic-v1,🏭 +,Eplus-IWMullion-discrete-v1,🏢 +,Eplus-IWMullion-continuous-v1,🏢 +,Eplus-IWMullion-discrete-stochastic-v1,🏢 +,Eplus-IWMullion-continuous-stochastic-v1,🏢 From 252135747fef063d922fbd180dace6844cdfbd05 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 11:13:14 +0000 Subject: [PATCH 055/113] docs: update envs table --- README.rst | 48 ++++++++++++++++++++++++++++++++-- docs/available_envs_parsed.csv | 6 ++--- 2 files changed, 49 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 6459fa40..32834b6e 100644 --- a/README.rst +++ b/README.rst @@ -29,8 +29,52 @@ A toolbox for benchmarking reinforcement learning (RL) algorithms on building en Available environments ---------------------- -.. csv-table:: Available environments - :file: ./docs/available_envs_parsed.csv +.. csv-table:: + :header-rows: 1 + :widths: auto + + Gym,Environment,Type + *BOPTEST*,bestest_air,🏠 + ,bestest_hydronic,🏠 + ,bestest_hydronic_heat_pump,🏠 + ,multizone_residential_hydronic,🏠 + ,singlezone_commercial_hydronic,🏢 + *Energym*,Apartments2Thermal-v0,🏠 + ,Apartments2Grid-v0,🏠 + ,ApartmentsThermal-v0,🏠 + ,ApartmentsGrid-v0,🏠 + ,OfficesThermostat-v0,🏢 + ,MixedUseFanFCU-v0,🏢 + ,SeminarcenterThermostat-v0,🏢 + ,SeminarcenterFull-v0,🏢 + ,SimpleHouseRad-v0,🏠 + ,SimpleHouseRSla-v0,🏠 + ,SwissHouseRSlaW2W-v0,🏠 + ,SwissHouseRSlaA2W-v0,🏠 + ,SwissHouseRSlaTank-v0,🏠 + ,SwissHouseRSlaTankDhw-v0,🏠 + *Sinergym*,Eplus-demo-v1,🏠 + ,Eplus-5Zone-hot-discrete-v1,🏠 + ,Eplus-5Zone-mixed-discrete-v1,🏠 + ,Eplus-5Zone-cool-discrete-v1,🏠 + ,Eplus-5Zone-hot-continuous-v1,🏠 + ,Eplus-5Zone-mixed-continuous-v1,🏠 + ,Eplus-5Zone-cool-continuous-v1,🏠 + ,Eplus-5Zone-hot-discrete-stochastic-v1,🏠 + ,Eplus-5Zone-mixed-discrete-stochastic-v1,🏠 + ,Eplus-5Zone-cool-discrete-stochastic-v1,🏠 + ,Eplus-5Zone-hot-continuous-stochastic-v1,🏠 + ,Eplus-5Zone-mixed-continuous-stochastic-v1,🏠 + ,Eplus-5Zone-cool-continuous-stochastic-v1,🏠 + ,Eplus-datacenter-discrete-v1,🏭 + ,Eplus-datacenter-continuous-v1,🏭 + ,Eplus-datacenter-discrete-stochastic-v1,🏭 + ,Eplus-datacenter-continuous-stochastic-v1,🏭 + ,Eplus-IWMullion-discrete-v1,🏢 + ,Eplus-IWMullion-continuous-v1,🏢 + ,Eplus-IWMullion-discrete-stochastic-v1,🏢 + ,Eplus-IWMullion-continuous-stochastic-v1,🏢 + Features diff --git a/docs/available_envs_parsed.csv b/docs/available_envs_parsed.csv index 47238b13..460b7cae 100644 --- a/docs/available_envs_parsed.csv +++ b/docs/available_envs_parsed.csv @@ -1,10 +1,10 @@ Gym,Environment,Type -BOPTEST,bestest_air,🏠 +*BOPTEST*,bestest_air,🏠 ,bestest_hydronic,🏠 ,bestest_hydronic_heat_pump,🏠 ,multizone_residential_hydronic,🏠 ,singlezone_commercial_hydronic,🏢 -Energym,Apartments2Thermal-v0,🏠 +*Energym*,Apartments2Thermal-v0,🏠 ,Apartments2Grid-v0,🏠 ,ApartmentsThermal-v0,🏠 ,ApartmentsGrid-v0,🏠 @@ -18,7 +18,7 @@ Energym,Apartments2Thermal-v0,🏠 ,SwissHouseRSlaA2W-v0,🏠 ,SwissHouseRSlaTank-v0,🏠 ,SwissHouseRSlaTankDhw-v0,🏠 -Sinergym,Eplus-demo-v1,🏠 +*Sinergym*,Eplus-demo-v1,🏠 ,Eplus-5Zone-hot-discrete-v1,🏠 ,Eplus-5Zone-mixed-discrete-v1,🏠 ,Eplus-5Zone-cool-discrete-v1,🏠 From e5bafe381e7d16c30b791b4b3c0853f394b67713 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 12:23:23 +0000 Subject: [PATCH 056/113] docs: add envs to docs --- docs/conf.py | 1 + docs/envs.rst | 21 +++++++++++++++++++++ docs/envs/boptest.rst | 2 ++ docs/envs/energym.rst | 2 ++ docs/envs/sinergym.rst | 2 ++ docs/guides.rst | 4 ++-- 6 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 docs/envs.rst create mode 100644 docs/envs/boptest.rst create mode 100644 docs/envs/energym.rst create mode 100644 docs/envs/sinergym.rst diff --git a/docs/conf.py b/docs/conf.py index c8f82cd7..d793ef0e 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ "sphinx.ext.viewcode", "sphinx.ext.autosummary", "sphinx_tabs.tabs", + "myst_parser", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/envs.rst b/docs/envs.rst new file mode 100644 index 00000000..c486b3f4 --- /dev/null +++ b/docs/envs.rst @@ -0,0 +1,21 @@ +============ +Environments +============ + +Beobench provides easy access to a large number of RL building control environments. More information about the different libraries can be found here: + +.. toctree:: + :maxdepth: 1 + + envs/boptest + envs/energym + envs/sinergym + + +Complete environment list +------------------------- + +.. csv-table:: + :header-rows: 1 + :widths: auto + :file: available_envs_parsed.csv \ No newline at end of file diff --git a/docs/envs/boptest.rst b/docs/envs/boptest.rst new file mode 100644 index 00000000..383aac1b --- /dev/null +++ b/docs/envs/boptest.rst @@ -0,0 +1,2 @@ +.. include:: ../../beobench_contrib/gyms/boptest/README.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/envs/energym.rst b/docs/envs/energym.rst new file mode 100644 index 00000000..0bd333da --- /dev/null +++ b/docs/envs/energym.rst @@ -0,0 +1,2 @@ +.. include:: ../../beobench_contrib/gyms/energym/README.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/envs/sinergym.rst b/docs/envs/sinergym.rst new file mode 100644 index 00000000..aef4af9d --- /dev/null +++ b/docs/envs/sinergym.rst @@ -0,0 +1,2 @@ +.. include:: ../../beobench_contrib/gyms/sinergym/README.md + :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/guides.rst b/docs/guides.rst index c47c9ee6..f097f742 100644 --- a/docs/guides.rst +++ b/docs/guides.rst @@ -1,6 +1,6 @@ -===== +====== Guides -===== +====== Welcome to beobench's usage guides! From 987f530e79f4aee3e5a3624715a13b9848f5e43d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 12:26:27 +0000 Subject: [PATCH 057/113] aux: add myst parser to doc requirements --- requirements/doc_requirements.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/requirements/doc_requirements.txt b/requirements/doc_requirements.txt index 0c4cdeeb..ccd8b306 100644 --- a/requirements/doc_requirements.txt +++ b/requirements/doc_requirements.txt @@ -1 +1,2 @@ -sphinx-tabs \ No newline at end of file +sphinx-tabs +myst-parser \ No newline at end of file From 4730257f0d9589156c4bf4d289cff5942c22e318 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 12:29:08 +0000 Subject: [PATCH 058/113] docs: add envs section to main index --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index 785c075c..b6c85d3a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Contents self guides/installation + envs guides api contributing From 02476b8337036309f0c0618b6186dc7747192f3d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 12:36:33 +0000 Subject: [PATCH 059/113] docs: ensure readthedocs clones submodules --- .readthedocs.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 40f72ae1..6252d08b 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -24,4 +24,8 @@ python: install: - method: pip path: . - - requirements: requirements/doc_requirements.txt \ No newline at end of file + - requirements: requirements/doc_requirements.txt + +# Ensure the beobench_contrib submodule is included +submodules: + include: all \ No newline at end of file From 3824d9b7f5b481196d647f2a093478caa6134776 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 12:37:07 +0000 Subject: [PATCH 060/113] aux: update submodule commit --- beobench_contrib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench_contrib b/beobench_contrib index dab4fd6e..0051d8dc 160000 --- a/beobench_contrib +++ b/beobench_contrib @@ -1 +1 @@ -Subproject commit dab4fd6e7c6f96d687fc6eb7efaf5caac49fed6b +Subproject commit 0051d8dc64233ecbaf9efed595f52fec7b3786d0 From f7c10994a1813d4045f91ee960b2818320284c65 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:31:59 +0000 Subject: [PATCH 061/113] docs: rewrite intro and features of readme --- README.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 32834b6e..696b5919 100644 --- a/README.rst +++ b/README.rst @@ -24,7 +24,16 @@ :target: https://opensource.org/licenses/MIT :alt: License -A toolbox for benchmarking reinforcement learning (RL) algorithms on building energy optimisation (BEO) problems. Beobench tries to make working on RL for BEO easier: it provides simple access to existing libraries defining BEO problems (such as `BOPTEST `_) and provides a large set of pre-configured RL algorithms. Beobench is *not* a gym library itself - instead it leverages the brilliant work done by many existing gym-type projects and makes their work more easily accessible. +A toolkit providing easy and unified access to building control reinforcement learning environments from multiple frameworks. Out of the box, Beobench provides access to environments from *BOPTEST*, *Energym*, and *Sinergym*. If required Beobench can be easily extended to be used with other environments. + +Features +-------- +- **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments. +- **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (:ref:`see quickstart `). Other packages require the user to manage building simulation installations or deal directly with docker images. +- **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. +- **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included in Beobench? The use of docker contexts makes it easy to use Beobench with any RL environment. + + Available environments ---------------------- @@ -100,6 +109,7 @@ Additional features .. start-quickstart +.. _sec_quickstart: Quickstart ---------- From 4d8846d5f32d5d1ea7b33dac91a86557063b82f9 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:37:54 +0000 Subject: [PATCH 062/113] docs: reorder main readme --- README.rst | 86 ++++++++++++++++++++---------------------------------- 1 file changed, 32 insertions(+), 54 deletions(-) diff --git a/README.rst b/README.rst index 696b5919..016c7e39 100644 --- a/README.rst +++ b/README.rst @@ -33,7 +33,39 @@ Features - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. - **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included in Beobench? The use of docker contexts makes it easy to use Beobench with any RL environment. +.. end-in-sphinx-docs + +.. start-quickstart +.. _sec_quickstart: + +Quickstart +---------- + +Run your first beobench experiment in three steps: + +1. `Install docker `_ on your machine (if on Linux, check the `additional installation steps `_) +2. Install *beobench* using: + + .. code-block:: console + + pip install beobench + +3. Finally, start your first experiment using: + + .. code-block:: console + + beobench run + +Done, you have just started your first experiment... congrats! Check out the `full getting started guide in the documentation `_ for the next steps. +.. end-quickstart + +Documentation +------------- +https://beobench.readthedocs.io + + +.. _sec_envs: Available environments ---------------------- @@ -85,64 +117,10 @@ Available environments ,Eplus-IWMullion-continuous-stochastic-v1,🏢 - -Features --------- - -*Some of the features are work in progress* - -Main features - -- *RL algorithm collection:* what's the best RL method for your BEO problem? Building on `Ray RLlib `_, beobench provides a large collection of pre-configured RL algorithm experiments that can be easily applied to your new BEO problem. -- *Problem collection:* beobench provides ready-to-use docker containers for popular BEO gym-type problem libraries. By enforcing a strict OpenAI ``gym.Env`` it makes testing your method on different libraries easy. - -Additional features - -- *Experiment logging:* log experiment results in a reproducible and shareable manner via `Weights and Biases`_. -- *Hyperparameter tuning:* easily tune hyperparameters using the extensive `Ray Tune Search API `_. -- *Simple installation:* beobench can be installed via pip and only requires docker as an additional non-python dependency. -- *Easily extendable:* beobench is designed for the user to add both environments and methods. - -.. _Weights and Biases: https://wandb.ai/ - -.. end-in-sphinx-docs - - -.. start-quickstart -.. _sec_quickstart: - -Quickstart ----------- - -Run your first beobench experiment in three steps: - -1. `Install docker `_ on your machine (if on Linux, check the `additional installation steps `_) -2. Install *beobench* using: - - .. code-block:: console - - pip install beobench - -3. Finally, start your first experiment using: - - .. code-block:: console - - beobench run - -Done, you have just started your first experiment... congrats! Check out the `full getting started guide in the documentation `_ for the next steps. - -.. end-quickstart - -Documentation -------------- -https://beobench.readthedocs.io - License ------- MIT license - - Credits ------- From 23880f16a5a598b3a57482b06335c34a8dc24d25 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:42:41 +0000 Subject: [PATCH 063/113] aux: update submodule comit --- beobench_contrib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/beobench_contrib b/beobench_contrib index 0051d8dc..f2bc0fd0 160000 --- a/beobench_contrib +++ b/beobench_contrib @@ -1 +1 @@ -Subproject commit 0051d8dc64233ecbaf9efed595f52fec7b3786d0 +Subproject commit f2bc0fd0db9c1c43afe7479952644768355ecf43 From a939d05129f01cb65d8b427ea5d171103631cd65 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:42:57 +0000 Subject: [PATCH 064/113] docs: minor fixes in main readme --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 016c7e39..f4a9be5b 100644 --- a/README.rst +++ b/README.rst @@ -24,14 +24,14 @@ :target: https://opensource.org/licenses/MIT :alt: License -A toolkit providing easy and unified access to building control reinforcement learning environments from multiple frameworks. Out of the box, Beobench provides access to environments from *BOPTEST*, *Energym*, and *Sinergym*. If required Beobench can be easily extended to be used with other environments. +A toolkit providing easy and unified access to building control reinforcement learning environments from multiple frameworks. Out of the box, Beobench provides access to environments from *BOPTEST*, *Energym*, and *Sinergym*. If required, Beobench can be easily extended to be used with other environments. Features -------- - **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments. - **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (:ref:`see quickstart `). Other packages require the user to manage building simulation installations or deal directly with docker images. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. -- **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included in Beobench? The use of docker contexts makes it easy to use Beobench with any RL environment. +- **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included? The use of docker contexts makes it easy to use Beobench with any RL environment. .. end-in-sphinx-docs From cb4b48423e879e44eb0a205f55129bc3a2fc33ce Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:50:51 +0000 Subject: [PATCH 065/113] docs: fix links in readme --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index f4a9be5b..68e19b51 100644 --- a/README.rst +++ b/README.rst @@ -28,8 +28,8 @@ A toolkit providing easy and unified access to building control reinforcement le Features -------- -- **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments. -- **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (:ref:`see quickstart `). Other packages require the user to manage building simulation installations or deal directly with docker images. +- **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments (`see environment list here `_). +- **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to manage building simulation installations or deal directly with docker images. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. - **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included? The use of docker contexts makes it easy to use Beobench with any RL environment. From 5e5cee00187b39e42ff60a4580a3feeb8bab3816 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 16:54:15 +0000 Subject: [PATCH 066/113] docs: make extendability feature more understandable --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 68e19b51..45313f15 100644 --- a/README.rst +++ b/README.rst @@ -31,7 +31,7 @@ Features - **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments (`see environment list here `_). - **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to manage building simulation installations or deal directly with docker images. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. -- **Easily extendable:** want to use Beobench to evaluate RL agents on an environment not yet included? The use of docker contexts makes it easy to use Beobench with any RL environment. +- **Easily extendable:** want to use Beobench with an environment not yet included? The support for user-defined docker contexts makes it easy to use Beobench with any RL environment. .. end-in-sphinx-docs From 7bd9e894a6c6921d2d384ec4f72d7e40bdf4b270 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 19:08:16 +0000 Subject: [PATCH 067/113] docs: update guides to new yaml based config syntax --- README.rst | 4 ++-- docs/guides/add_env.rst | 23 ++++++++++---------- docs/guides/intro_experiment.rst | 26 ++++------------------- docs/snippets/run_standard_experiment.rst | 4 ++-- 4 files changed, 20 insertions(+), 37 deletions(-) diff --git a/README.rst b/README.rst index 45313f15..48c7070b 100644 --- a/README.rst +++ b/README.rst @@ -29,9 +29,9 @@ A toolkit providing easy and unified access to building control reinforcement le Features -------- - **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments (`see environment list here `_). -- **Clean and light-weight installation:** Beobench is installed via pip and only requires docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to manage building simulation installations or deal directly with docker images. +- **Clean and light-weight installation:** Beobench is installed via pip and only requires Docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to manage building simulation installations or deal directly with docker images. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. -- **Easily extendable:** want to use Beobench with an environment not yet included? The support for user-defined docker contexts makes it easy to use Beobench with any RL environment. +- **Easily extendable:** want to use Beobench with an environment not yet included? The support for user-defined Docker contexts makes it easy to use Beobench with any RL environment. .. end-in-sphinx-docs diff --git a/docs/guides/add_env.rst b/docs/guides/add_env.rst index edb127e5..30cd1951 100644 --- a/docs/guides/add_env.rst +++ b/docs/guides/add_env.rst @@ -14,35 +14,36 @@ Creating build context To add an environment to beobench we need to create a special *docker build context* (for more details `see the official docker build documentation `_). Such a beobench-specific *docker build context* consists at least of the following two files in a folder ``/``: 1. A dockerfile ``Dockerfile`` that defines a docker container that has everything necessary for your environment installed. In addition to any of your packages/modules, the dockerfile must also install `beobench` via pip. -2. A ``env_creator.py`` file that defines a function with the signature ``create_env(env_config: dict = None) -> gym.Env``. This ``create_env()`` function should take an ``env_config`` dictionary (that completely configures your environment) as input and return an instance of your environment with this configuration. If your environment is not yet implementing the commonly used ``gym.Env`` class (`see here `_), you will need to wrap your environment in a class that implements this ``gym.Env`` class within the ``create_env()`` function. +2. An ``env_creator.py`` file that defines a function with the signature ``create_env(env_config: dict = None) -> gym.Env``. This ``create_env()`` function should take an ``env_config`` dictionary (that completely configures your environment) as input and return an instance of your environment with this configuration. If your environment is not yet implementing the commonly used ``gym.Env`` class (`see here `_), you will need to wrap your environment in a class that implements this ``gym.Env`` class within the ``create_env()`` function. The path to the folder with these two files, ``path/to/folder//``, can either be on your local file system or on github. It can also contain additional files that help with the installation process. -**Example**: for an example of such a *docker context folder* see `the official BOPTEST integration folder `_. +**Example**: for an example of such a *docker context folder* see `the official BOPTEST integration folder `_. Defining experiment ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order run an experiment on your gym, we need to add the build context to an experiment definition. This can be done by adding/changing the following parameter in your experiment definition file ``example_experiment_def.py`` (see the :doc:`usage` page for how to create a complete experiment definition file): +In order run an experiment on your gym, we need to add the build context to an experiment definition. This can be done by adding/changing the following parameter in your experiment definition file ``example.yaml`` (see :doc:`/guides/intro_experiment` for how to create a complete experiment definition file): -.. code-block:: python +.. code-block:: yaml - problem = { - "problem_library": "path/to/folder//", - ... - } + # ... + env: + gym: "path/to/folder//" + # ... -For example, we could set the ``problem_library`` key to ``"https://github.com/rdnfn/beobench.git#master:beobench/integrations/boptest"``. + +For example, we could set the ``gym`` key to ``"https://github.com/rdnfn/beobench_contrib.git#main:gyms/boptest"``. .. warning:: - Only set ``problem_library`` to experiment build contexts from authors that you trust. This setting can create an arbitrary docker container on your system. + Only set ``gym`` to experiment build contexts from authors that you trust. This setting can create an arbitrary docker container on your system. Running experiment ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With a complete experiment definition file ``example_experiment_def.py``, we can then use the standard command below to start the experiment: +With a complete experiment definition file ``example.yaml``, we can then use the standard command below to start the experiment: .. include:: ../snippets/run_standard_experiment.rst diff --git a/docs/guides/intro_experiment.rst b/docs/guides/intro_experiment.rst index 6bfd8bf0..14227f80 100644 --- a/docs/guides/intro_experiment.rst +++ b/docs/guides/intro_experiment.rst @@ -14,33 +14,15 @@ The diagram below gives an overview of how beobench experiments work. The ``beob Experiment configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ -Beobench defines experiments using three separate dictionaries for problem, method and machine configuration. Each defines the parameters relevant to one of these configurations. Internally, beobench then merges these three dictionaries into a single dictionary that is passed to the ``ray.tune.run()`` function. A beobench configuration file is a ``.py`` file that defines the variables ``problem``, ``method`` and ``rllib_setup``. For example, let the following be the content of a file named ``example_experiment_def.py``: +Beobench experiments are configured either using a *Python dictionary* or an equivalent *yaml file*. For example, the following ``example.yaml`` file configures an experiment that evaluates an RLlib-based *proximal policy optimisation* (PPO) agent on the ``MixedUseFanFCU-v0`` environment of Energym: -.. include:: ../../beobench/experiment/definitions/default.py - :start-line: 2 - :code: python +.. literalinclude:: ../../beobench/experiment/definitions/default.yaml + :language: yaml -Given this configuration file ``example_experiment_def.py``, we can the experiment using the following commands: +Given this configuration file ``example.yaml``, we can the experiment using the following commands: .. include:: ../snippets/run_standard_experiment.rst - -Hyperparameter Search Spaces -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -So far, we only configured a single experiment. However, we likely want to test multiple experiment configurations. As beobench builds on *Ray RLlib* and *Ray Tune*, we can use the powerful `Ray Tune Search Space API `_. This API allows us to configure pretty much any hyperparameter search space. For example to do grid search on the learning rate, we can replace the following line in the previously shown ``example_experiment_def.py`` - -.. code-block:: python - - "lr": 5e-3, - -with - -.. code-block:: python - - "lr": ray.tune.grid_search([5e-3, 5e-4, 5e-5]), - -Beobench will then run three experiments trying three different values of the learning rate (``lr``). Note that ``import ray.tune`` must also be included in ``example_experiment_def.py``. In addition to simple grid search, it is also possible to use *Ray Tune's* `Random Distribution API `_. This allows us to create probabilistic hyperparameter search spaces, that we can either randomly sample or apply optimisation algorithms to. See the `Ray Tune Search Space API documentation `_ for a more complete description of the functionality. \ No newline at end of file diff --git a/docs/snippets/run_standard_experiment.rst b/docs/snippets/run_standard_experiment.rst index 5ec46ce7..1aed4ff5 100644 --- a/docs/snippets/run_standard_experiment.rst +++ b/docs/snippets/run_standard_experiment.rst @@ -2,10 +2,10 @@ .. code-tab:: console Console - beobench run --experiment-file example_experiment_def.py + beobench run --config example.yaml .. code-tab:: python import beobench - beobench.run(experiment_file = "example_experiment_def.py") \ No newline at end of file + beobench.run(config = "example.yaml") \ No newline at end of file From d147533e2ce61aa1552ef687c84d331c118a9dc6 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Wed, 23 Mar 2022 19:23:35 +0000 Subject: [PATCH 068/113] docs: minor changes to readme --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 48c7070b..dff3b42c 100644 --- a/README.rst +++ b/README.rst @@ -29,7 +29,7 @@ A toolkit providing easy and unified access to building control reinforcement le Features -------- - **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments (`see environment list here `_). -- **Clean and light-weight installation:** Beobench is installed via pip and only requires Docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to manage building simulation installations or deal directly with docker images. +- **Clean and light-weight installation:** Beobench is installed via pip and only requires Docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to deal with building simulator installations or manage docker images directly. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. - **Easily extendable:** want to use Beobench with an environment not yet included? The support for user-defined Docker contexts makes it easy to use Beobench with any RL environment. From 3f9a1c0e25caec141907958b51d5a0b3692c0d79 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 00:29:15 +0000 Subject: [PATCH 069/113] docs: update env list --- docs/available_envs_parsed.csv | 82 +++++++++++++++++----------------- docs/envs.rst | 14 +++++- 2 files changed, 53 insertions(+), 43 deletions(-) diff --git a/docs/available_envs_parsed.csv b/docs/available_envs_parsed.csv index 460b7cae..9b480d3a 100644 --- a/docs/available_envs_parsed.csv +++ b/docs/available_envs_parsed.csv @@ -1,41 +1,41 @@ -Gym,Environment,Type -*BOPTEST*,bestest_air,🏠 -,bestest_hydronic,🏠 -,bestest_hydronic_heat_pump,🏠 -,multizone_residential_hydronic,🏠 -,singlezone_commercial_hydronic,🏢 -*Energym*,Apartments2Thermal-v0,🏠 -,Apartments2Grid-v0,🏠 -,ApartmentsThermal-v0,🏠 -,ApartmentsGrid-v0,🏠 -,OfficesThermostat-v0,🏢 -,MixedUseFanFCU-v0,🏢 -,SeminarcenterThermostat-v0,🏢 -,SeminarcenterFull-v0,🏢 -,SimpleHouseRad-v0,🏠 -,SimpleHouseRSla-v0,🏠 -,SwissHouseRSlaW2W-v0,🏠 -,SwissHouseRSlaA2W-v0,🏠 -,SwissHouseRSlaTank-v0,🏠 -,SwissHouseRSlaTankDhw-v0,🏠 -*Sinergym*,Eplus-demo-v1,🏠 -,Eplus-5Zone-hot-discrete-v1,🏠 -,Eplus-5Zone-mixed-discrete-v1,🏠 -,Eplus-5Zone-cool-discrete-v1,🏠 -,Eplus-5Zone-hot-continuous-v1,🏠 -,Eplus-5Zone-mixed-continuous-v1,🏠 -,Eplus-5Zone-cool-continuous-v1,🏠 -,Eplus-5Zone-hot-discrete-stochastic-v1,🏠 -,Eplus-5Zone-mixed-discrete-stochastic-v1,🏠 -,Eplus-5Zone-cool-discrete-stochastic-v1,🏠 -,Eplus-5Zone-hot-continuous-stochastic-v1,🏠 -,Eplus-5Zone-mixed-continuous-stochastic-v1,🏠 -,Eplus-5Zone-cool-continuous-stochastic-v1,🏠 -,Eplus-datacenter-discrete-v1,🏭 -,Eplus-datacenter-continuous-v1,🏭 -,Eplus-datacenter-discrete-stochastic-v1,🏭 -,Eplus-datacenter-continuous-stochastic-v1,🏭 -,Eplus-IWMullion-discrete-v1,🏢 -,Eplus-IWMullion-continuous-v1,🏢 -,Eplus-IWMullion-discrete-stochastic-v1,🏢 -,Eplus-IWMullion-continuous-stochastic-v1,🏢 +Gym,Environment,Type*,Description +*BOPTEST*,``bestest_air``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``bestest_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``bestest_hydronic_heat_pump``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``multizone_residential_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``singlezone_commercial_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +*Energym*,``Apartments2Thermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Apartments2Grid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``ApartmentsThermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``ApartmentsGrid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``OfficesThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``MixedUseFanFCU-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``SeminarcenterThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``SeminarcenterFull-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``SimpleHouseRad-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``SimpleHouseRSla-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``SwissHouseRSlaW2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``SwissHouseRSlaA2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``SwissHouseRSlaTank-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``SwissHouseRSlaTankDhw-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +*Sinergym*,``Eplus-demo-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-hot-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-mixed-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-cool-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-hot-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-mixed-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-cool-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-hot-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-mixed-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-cool-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-hot-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-mixed-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-5Zone-cool-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" +,``Eplus-datacenter-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" +,``Eplus-datacenter-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" +,``Eplus-datacenter-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" +,``Eplus-datacenter-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" +,``Eplus-IWMullion-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``Eplus-IWMullion-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``Eplus-IWMullion-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +,``Eplus-IWMullion-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" diff --git a/docs/envs.rst b/docs/envs.rst index c486b3f4..0c4b4e37 100644 --- a/docs/envs.rst +++ b/docs/envs.rst @@ -12,10 +12,20 @@ Beobench provides easy access to a large number of RL building control environme envs/sinergym -Complete environment list +Environment list ------------------------- .. csv-table:: :header-rows: 1 :widths: auto - :file: available_envs_parsed.csv \ No newline at end of file + :file: available_envs_parsed.csv + +\* Types of environments: + +* residential |home| +* office |office| +* commercial |industry| + +.. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg +.. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg +.. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg \ No newline at end of file From dbd23aec206d4acfa9f66f1633f3cadd38616836 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 00:43:23 +0000 Subject: [PATCH 070/113] feat: add env list creator notebook --- notebooks/utils/nb001_create_envs_table.ipynb | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 notebooks/utils/nb001_create_envs_table.ipynb diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb new file mode 100644 index 00000000..c7962bfe --- /dev/null +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -0,0 +1,107 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "%reload_ext autoreload\n", + "%autoreload 2\n", + "%config IPCompleter.greedy=True\n", + "%config IPCompleter.use_jedi=False" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "import numpy as np\n", + "\n", + "# Load data from google sheet\n", + "sheet_id = \"1QaXBrhDY8tyF9cIBjejDTGMiv5vDUQG0KQ7iVapGQoY\"\n", + "gid = 1987847080\n", + "link = f\"https://docs.google.com/feeds/download/spreadsheets/Export?key={sheet_id}&exportFormat=csv&gid={gid}\"\n", + "envs = pd.read_csv(link)\n", + "\n", + "\n", + "# format data for rst\n", + "def emojify(row): \n", + " house_type = row[\"House type\"]\n", + " if house_type == \"residential\":\n", + " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg\"\n", + " elif house_type == \"office\":\n", + " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg\"\n", + " elif house_type == \"industrial\":\n", + " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg\"\n", + " return \"other\"\n", + "\n", + "def italicise(row, col):\n", + " value = row[col]\n", + " if value is not np.nan:\n", + " return f\"*{value}*\"\n", + " else:\n", + " return \"\"\n", + "\n", + "def codify(row, col):\n", + " value = row[col]\n", + " if value is not np.nan:\n", + " return f\"``{value}``\"\n", + " else:\n", + " return \"\"\n", + "\n", + "def create_doc_links(row):\n", + " original_url = row[\"Original docs\"]\n", + " beobench_url = row[\"Beobench docs\"]\n", + " link_str = f\"`original <{original_url}>`_, `beobench <{beobench_url}>`_\"\n", + " return link_str\n", + "\n", + "envs['Type*'] = envs.apply(lambda row: emojify(row), axis=1)\n", + "envs['Gym'] = envs.apply(lambda row: italicise(row, col=\"Gym\"), axis=1)\n", + "envs['Environment'] = envs.apply(lambda row: codify(row, col=\"Environment\"), axis=1)\n", + "envs['Description'] = envs.apply(lambda row: create_doc_links(row), axis=1)\n", + "\n", + "# Save data to csv\n", + "printable_envs = envs[[\"Gym\",\"Environment\",\"Type*\",\"Description\"]]\n", + "printable_envs.to_csv(\"../../docs/available_envs_parsed.csv\", index=False)\n" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "# printable_envs" + ] + } + ], + "metadata": { + "interpreter": { + "hash": "949777d72b0d2535278d3dc13498b2535136f6dfe0678499012e853ee9abcab1" + }, + "kernelspec": { + "display_name": "Python 3.9.7 64-bit", + "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.9.7" + }, + "orig_nbformat": 4 + }, + "nbformat": 4, + "nbformat_minor": 2 +} From 1e8bb31bf4ff4d244b37b1603e4a17b2e822ddf8 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 10:48:14 +0000 Subject: [PATCH 071/113] docs: update envs table in main readme --- README.rst | 85 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 41 deletions(-) diff --git a/README.rst b/README.rst index dff3b42c..cfd5572f 100644 --- a/README.rst +++ b/README.rst @@ -74,47 +74,50 @@ Available environments :header-rows: 1 :widths: auto - Gym,Environment,Type - *BOPTEST*,bestest_air,🏠 - ,bestest_hydronic,🏠 - ,bestest_hydronic_heat_pump,🏠 - ,multizone_residential_hydronic,🏠 - ,singlezone_commercial_hydronic,🏢 - *Energym*,Apartments2Thermal-v0,🏠 - ,Apartments2Grid-v0,🏠 - ,ApartmentsThermal-v0,🏠 - ,ApartmentsGrid-v0,🏠 - ,OfficesThermostat-v0,🏢 - ,MixedUseFanFCU-v0,🏢 - ,SeminarcenterThermostat-v0,🏢 - ,SeminarcenterFull-v0,🏢 - ,SimpleHouseRad-v0,🏠 - ,SimpleHouseRSla-v0,🏠 - ,SwissHouseRSlaW2W-v0,🏠 - ,SwissHouseRSlaA2W-v0,🏠 - ,SwissHouseRSlaTank-v0,🏠 - ,SwissHouseRSlaTankDhw-v0,🏠 - *Sinergym*,Eplus-demo-v1,🏠 - ,Eplus-5Zone-hot-discrete-v1,🏠 - ,Eplus-5Zone-mixed-discrete-v1,🏠 - ,Eplus-5Zone-cool-discrete-v1,🏠 - ,Eplus-5Zone-hot-continuous-v1,🏠 - ,Eplus-5Zone-mixed-continuous-v1,🏠 - ,Eplus-5Zone-cool-continuous-v1,🏠 - ,Eplus-5Zone-hot-discrete-stochastic-v1,🏠 - ,Eplus-5Zone-mixed-discrete-stochastic-v1,🏠 - ,Eplus-5Zone-cool-discrete-stochastic-v1,🏠 - ,Eplus-5Zone-hot-continuous-stochastic-v1,🏠 - ,Eplus-5Zone-mixed-continuous-stochastic-v1,🏠 - ,Eplus-5Zone-cool-continuous-stochastic-v1,🏠 - ,Eplus-datacenter-discrete-v1,🏭 - ,Eplus-datacenter-continuous-v1,🏭 - ,Eplus-datacenter-discrete-stochastic-v1,🏭 - ,Eplus-datacenter-continuous-stochastic-v1,🏭 - ,Eplus-IWMullion-discrete-v1,🏢 - ,Eplus-IWMullion-continuous-v1,🏢 - ,Eplus-IWMullion-discrete-stochastic-v1,🏢 - ,Eplus-IWMullion-continuous-stochastic-v1,🏢 + Gym,Environment,Type*,Description + *BOPTEST*,``bestest_air``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``bestest_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``bestest_hydronic_heat_pump``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``multizone_residential_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``singlezone_commercial_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + *Energym*,``Apartments2Thermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Apartments2Grid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``ApartmentsThermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``ApartmentsGrid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``OfficesThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``MixedUseFanFCU-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``SeminarcenterThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``SeminarcenterFull-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``SimpleHouseRad-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``SimpleHouseRSla-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``SwissHouseRSlaW2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``SwissHouseRSlaA2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``SwissHouseRSlaTank-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``SwissHouseRSlaTankDhw-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + *Sinergym*,``Eplus-demo-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-hot-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-mixed-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-cool-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-hot-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-mixed-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-cool-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-hot-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-mixed-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-cool-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-hot-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-mixed-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-5Zone-cool-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" + ,``Eplus-datacenter-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" + ,``Eplus-datacenter-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" + ,``Eplus-datacenter-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" + ,``Eplus-datacenter-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" + ,``Eplus-IWMullion-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``Eplus-IWMullion-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``Eplus-IWMullion-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + ,``Eplus-IWMullion-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" + + + License From abff5e6e0768f79e774067d6f2986f0ad4056e28 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 10:48:40 +0000 Subject: [PATCH 072/113] docs: slight tweaks in dev env guide --- docs/guides/dev_env.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/dev_env.rst b/docs/guides/dev_env.rst index a30700ef..b78eafc4 100644 --- a/docs/guides/dev_env.rst +++ b/docs/guides/dev_env.rst @@ -21,11 +21,11 @@ Standard development .. code-block:: - git clone --recursive git@github.com:your_name_here/beobench.git + git clone --recursive git@github.com:/beobench.git (if you are a maintainer you can clone directly from the main repository) - Note that this requires having your github authentification setup, `see here `_ + Note that this requires having your github authentification setup, `see here `_. 3. Open the beobench repo folder in vscode 4. Inside vscode, open the command palette (e.g. on macOS shortcut is ``shift`` + ``cmd`` + ``P``), and use the ``Remote-containers: reopen in container`` command. From 84bbd191ef6f3d7683d42a1bad264f0770c9753d Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:09:53 +0000 Subject: [PATCH 073/113] docs: extend credits page to include licenses --- AUTHORS.rst | 13 ++++--------- README.rst | 8 +------- docs/authors.rst | 1 - docs/credits.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- 5 files changed, 49 insertions(+), 18 deletions(-) delete mode 100644 docs/authors.rst create mode 100644 docs/credits.rst diff --git a/AUTHORS.rst b/AUTHORS.rst index 20669df0..95414258 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,13 +1,8 @@ -======= -Credits -======= +Contributors +------------ +* Arduin Findeis (https://github.com/rdnfn) +* Scott Jeen (https://github.com/enjeeneer) -Development Lead ----------------- -* rdnfn <-> -Contributors ------------- -None yet. Why not be the first? diff --git a/README.rst b/README.rst index cfd5572f..40ccaf92 100644 --- a/README.rst +++ b/README.rst @@ -122,12 +122,6 @@ Available environments License ------- -MIT license +MIT license, see `credits and license page in docs `_ for more detailed information. -Credits -------- - -This package was originally created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. -.. _Cookiecutter: https://github.com/audreyr/cookiecutter -.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e122f914..00000000 --- a/docs/authors.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../AUTHORS.rst diff --git a/docs/credits.rst b/docs/credits.rst new file mode 100644 index 00000000..758879b6 --- /dev/null +++ b/docs/credits.rst @@ -0,0 +1,43 @@ +=================== +Credits and license +=================== + +.. include:: ../AUTHORS.rst + +Further acknowledgements +------------------------ + +The starting package structure was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. + +.. _Cookiecutter: https://github.com/audreyr/cookiecutter +.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage + +License +------- + +The code in this repository is published under MIT license (see ``LICENSE`` file). + +Further the icons used in the environment list in the documentation are licensed under the following MIT license: + + MIT License + + Copyright (c) 2020 Paweł Kuna + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + diff --git a/docs/index.rst b/docs/index.rst index b6c85d3a..295db3b9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,7 @@ Contents guides api contributing - authors + credits history Indices and tables From 4747e0e4b64c579939435bed2ac11b769a63e856 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:15:37 +0000 Subject: [PATCH 074/113] docs: update icon description --- README.rst | 5 ++++- docs/envs.rst | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 40ccaf92..96b43a1f 100644 --- a/README.rst +++ b/README.rst @@ -116,8 +116,11 @@ Available environments ,``Eplus-IWMullion-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" ,``Eplus-IWMullion-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" +\* Types of environments: - +* residential |home| +* office |office| +* data center |industry| License diff --git a/docs/envs.rst b/docs/envs.rst index 0c4b4e37..371cbf76 100644 --- a/docs/envs.rst +++ b/docs/envs.rst @@ -24,7 +24,7 @@ Environment list * residential |home| * office |office| -* commercial |industry| +* data center |industry| .. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg .. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg From e8c303d13a658dba9825fe48001ccb5a52fe2c11 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:16:51 +0000 Subject: [PATCH 075/113] docs: add missing image links to readme --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index 96b43a1f..871999ed 100644 --- a/README.rst +++ b/README.rst @@ -122,6 +122,10 @@ Available environments * office |office| * data center |industry| +.. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg +.. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg +.. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg + License ------- From 33437d5cc8bffa581e9cc89cfc898c5a9fefa509 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:25:34 +0000 Subject: [PATCH 076/113] docs: minor fixes for credits page --- docs/credits.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/credits.rst b/docs/credits.rst index 758879b6..d806e10c 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -7,7 +7,7 @@ Credits and license Further acknowledgements ------------------------ -The starting package structure was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. +The initial package structure was created using Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. .. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage @@ -17,7 +17,9 @@ License The code in this repository is published under MIT license (see ``LICENSE`` file). -Further the icons used in the environment list in the documentation are licensed under the following MIT license: +Further, the icons used in the environment list in the documentation are licensed under the following MIT license: + +.. code-block:: txt MIT License @@ -40,4 +42,3 @@ Further the icons used in the environment list in the documentation are licensed LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - From c8aa6ad6225347a1215b6a86bf46a1bff0cfb937 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:29:15 +0000 Subject: [PATCH 077/113] aux: simplify issue template --- .github/ISSUE_TEMPLATE.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index ff0c7858..fb0c2da2 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,15 +1,8 @@ -* beobench version: -* Python version: -* Operating System: - -### Description +### Problem Describe what you were trying to get done. Tell us what happened, what went wrong, and what you expected to happen. -### What I Did +### Potential Solution -``` -Paste the command(s) you ran and the output. -If there was a crash, please include the traceback here. -``` +Describe a potential solution to the problem, if you have any. From 645260b8c1db19e8184cff76de07140ff5128212 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Thu, 24 Mar 2022 11:47:55 +0000 Subject: [PATCH 078/113] docs: change order in index --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 295db3b9..aaffebb3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,8 @@ Contents self guides/installation - envs guides + envs api contributing credits From 044f37f0e768bd1797cf4a61669454305bcd9972 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 14:06:25 +0000 Subject: [PATCH 079/113] aux: remove old config file parsing functions from scheduler --- beobench/experiment/scheduler.py | 86 -------------------------------- 1 file changed, 86 deletions(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index e742f52f..33f06260 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -4,7 +4,6 @@ import uuid import subprocess import pathlib -import importlib.util import warnings from typing import Union @@ -14,11 +13,7 @@ except ImportError: print("Note: RLlib beobench integration not available.") - import beobench.experiment.definitions.utils -import beobench.experiment.definitions.default -import beobench.experiment.definitions.methods -import beobench.experiment.definitions.envs import beobench.experiment.containers import beobench.experiment.config_parser import beobench.utils @@ -229,84 +224,3 @@ def run( ] print("Executing docker command: ", " ".join(args)) subprocess.check_call(args) - - -def _create_experiment_def( - experiment_file: pathlib.Path, method: str, env: str -) -> dict: - """Create a Beobench experiment definition. - - Args: - experiment_file (str): path to experiment file. - method (str): name of RL method. - env (str): name of environment. - """ - experiment_def = _load_experiment_file(experiment_file) - - # parsing high level interface options - - # methods - if method: - if method == "ppo": - experiment_def["method"] = beobench.experiment.definitions.methods.PPO - else: - raise ValueError( - ( - f"The supplied method '{method}' does not match any of " - "the pre-configured beobench methods." - ) - ) - - if env: - if env == "boptest_bestest-hydronic-heat-pump-v1": - experiment_def["problem"] = getattr( - beobench.experiment.definitions.envs, - env.replace("-", "_"), - ) - if env == "sinergym_eplus-5zone-hot-continous-v1": - experiment_def["problem"] = getattr( - beobench.experiment.definitions.envs, - env.replace("-", "_"), - ) - if env == "energym_mixed-use-fan-fcu-v0": - experiment_def["problem"] = getattr( - beobench.experiment.definitions.envs, - env.replace("-", "_"), - ) - - return experiment_def - - -def _load_experiment_file(experiment_file: pathlib.Path) -> dict: - """Load a Beobench experiment file. - - Args: - experiment_file (str): path to experiment file. - """ - - # Load experiment definition file - if experiment_file is None: - experiment_file_mod = beobench.experiment.definitions.default - else: - # import experiment definition file as module - spec = importlib.util.spec_from_file_location( - "experiment_definition", - str(experiment_file.absolute()), - ) - experiment_file_mod = importlib.util.module_from_spec(spec) - spec.loader.exec_module(experiment_file_mod) - - experiment_def = {} - - # Create experiment def dictionary, and set default values if not available - # from experiment_file (module). - for exp_part in ["problem", "method", "rllib_setup"]: - if hasattr(experiment_file_mod, exp_part): - experiment_def[exp_part] = getattr(experiment_file_mod, exp_part) - else: - experiment_def[exp_part] = getattr( - beobench.experiment.definitions.default, - exp_part, - ) - - return experiment_def From ab8c4b0522eb471d2516f946a87f851e27b50b51 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 14:06:59 +0000 Subject: [PATCH 080/113] aux: move old exp def files to archive --- beobench/experiment/definitions/{ => archive}/default.py | 0 beobench/experiment/definitions/{ => archive}/envs.py | 0 .../definitions/{ => archive}/experiment_001_dqn_boptest.py | 0 .../definitions/{ => archive}/experiment_002_rllib_setup.py | 0 .../definitions/{ => archive}/experiment_003_sinergym.py | 0 .../definitions/{ => archive}/experiment_004_energym.py | 0 beobench/experiment/definitions/{ => archive}/methods.py | 0 7 files changed, 0 insertions(+), 0 deletions(-) rename beobench/experiment/definitions/{ => archive}/default.py (100%) rename beobench/experiment/definitions/{ => archive}/envs.py (100%) rename beobench/experiment/definitions/{ => archive}/experiment_001_dqn_boptest.py (100%) rename beobench/experiment/definitions/{ => archive}/experiment_002_rllib_setup.py (100%) rename beobench/experiment/definitions/{ => archive}/experiment_003_sinergym.py (100%) rename beobench/experiment/definitions/{ => archive}/experiment_004_energym.py (100%) rename beobench/experiment/definitions/{ => archive}/methods.py (100%) diff --git a/beobench/experiment/definitions/default.py b/beobench/experiment/definitions/archive/default.py similarity index 100% rename from beobench/experiment/definitions/default.py rename to beobench/experiment/definitions/archive/default.py diff --git a/beobench/experiment/definitions/envs.py b/beobench/experiment/definitions/archive/envs.py similarity index 100% rename from beobench/experiment/definitions/envs.py rename to beobench/experiment/definitions/archive/envs.py diff --git a/beobench/experiment/definitions/experiment_001_dqn_boptest.py b/beobench/experiment/definitions/archive/experiment_001_dqn_boptest.py similarity index 100% rename from beobench/experiment/definitions/experiment_001_dqn_boptest.py rename to beobench/experiment/definitions/archive/experiment_001_dqn_boptest.py diff --git a/beobench/experiment/definitions/experiment_002_rllib_setup.py b/beobench/experiment/definitions/archive/experiment_002_rllib_setup.py similarity index 100% rename from beobench/experiment/definitions/experiment_002_rllib_setup.py rename to beobench/experiment/definitions/archive/experiment_002_rllib_setup.py diff --git a/beobench/experiment/definitions/experiment_003_sinergym.py b/beobench/experiment/definitions/archive/experiment_003_sinergym.py similarity index 100% rename from beobench/experiment/definitions/experiment_003_sinergym.py rename to beobench/experiment/definitions/archive/experiment_003_sinergym.py diff --git a/beobench/experiment/definitions/experiment_004_energym.py b/beobench/experiment/definitions/archive/experiment_004_energym.py similarity index 100% rename from beobench/experiment/definitions/experiment_004_energym.py rename to beobench/experiment/definitions/archive/experiment_004_energym.py diff --git a/beobench/experiment/definitions/methods.py b/beobench/experiment/definitions/archive/methods.py similarity index 100% rename from beobench/experiment/definitions/methods.py rename to beobench/experiment/definitions/archive/methods.py From 19db3d880c618b8fc8941e21866e4bd068f2236a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 14:32:35 +0000 Subject: [PATCH 081/113] feat: add short config option for CLI --- beobench/cli.py | 1 + 1 file changed, 1 insertion(+) diff --git a/beobench/cli.py b/beobench/cli.py index e88d8dec..bff805cd 100644 --- a/beobench/cli.py +++ b/beobench/cli.py @@ -15,6 +15,7 @@ def cli(): @cli.command() @click.option( "--config", + "-c", default=None, help="Json or filepath with yaml that defines beobench experiment configuration.", type=str, From ace7bea9649180fb9e60bdb6c136a57c405c8a19 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:19:10 +0000 Subject: [PATCH 082/113] feat: enable local beobench dev path --- beobench/cli.py | 7 ++++--- beobench/experiment/scheduler.py | 26 +++++++++++++++++++++----- 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/beobench/cli.py b/beobench/cli.py index bff805cd..775b6be9 100644 --- a/beobench/cli.py +++ b/beobench/cli.py @@ -89,7 +89,8 @@ def cli(): help="Whether to use cache to build experiment container.", ) @click.option( - "--dev-beobench-location", + "--dev-path", + "-d", default=None, help="For developer use only: location of custom beobench package version.", ) @@ -108,7 +109,7 @@ def run( docker_shm_size: str, no_additional_container: bool, use_no_cache: bool, - dev_beobench_location: str, + dev_path: str, ) -> None: """Run beobench experiment from command line. @@ -139,7 +140,7 @@ def run( docker_shm_size=docker_shm_size, no_additional_container=no_additional_container, use_no_cache=use_no_cache, - dev_beobench_location=dev_beobench_location, + dev_path=dev_path, ) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 33f06260..1ba7a233 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -34,7 +34,7 @@ def run( docker_shm_size: str = "2gb", no_additional_container: bool = False, use_no_cache: bool = False, - dev_beobench_location: str = None, + dev_path: str = None, ) -> None: """Run experiment. @@ -69,7 +69,7 @@ def run( is started to run experiments in. use_no_cache (bool, optional): whether to use cache to build experiment container. - dev_beobench_location (str, optional): github path to beobench package. For + dev_path (str, optional): file or github path to beobench package. For developement purpose only. This will install a custom beobench version inside the experiment container. By default the latest PyPI version is installed. @@ -192,11 +192,27 @@ def run( # this will return "" if env var not set wandb_api_key = os.getenv("WANDB_API_KEY", "") + # dev mode where custom beobench is installed directly from github or local path cmd_list_in_container = [""] - # dev mode where custom beobench is installed directly from git - if dev_beobench_location is not None: + if dev_path is not None: cmd_list_in_container.append("pip uninstall --yes beobench") - cmd_list_in_container.append(f"pip install {dev_beobench_location}") + if "https" in dev_path: + cmd_list_in_container.append(f"pip install {dev_path}") + else: + # mount local beobench repo + dev_path = pathlib.Path(dev_path) + dev_abs = dev_path.absolute() + dev_path_on_docker = "/tmp/beobench/beobench" + docker_flags += [ + "-v", + f"{dev_abs}:{dev_path_on_docker}_mount:ro", + ] + cmd_list_in_container.append( + f"cp -r {dev_path_on_docker}_mount {dev_path_on_docker}" + ) + cmd_list_in_container.append( + f"python -m pip install {dev_path_on_docker}" + ) cmd_in_container = " && ".join(cmd_list_in_container) From 605a3b300f04b1ff4ba758f16e40bfdc527f4e5a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:43:49 +0000 Subject: [PATCH 083/113] aux: add rewex experiment 01 --- beobench/experiment/definitions/rewex01.yaml | 43 ++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 beobench/experiment/definitions/rewex01.yaml diff --git a/beobench/experiment/definitions/rewex01.yaml b/beobench/experiment/definitions/rewex01.yaml new file mode 100644 index 00000000..7e706ac6 --- /dev/null +++ b/beobench/experiment/definitions/rewex01.yaml @@ -0,0 +1,43 @@ +# REWEX Experiment 01 +# Run with the command +# beobench run -c beobench/experiment/definitions/rewex01.yaml -d . --use-gpu --docker-shm-size 32gb + +# agent config +agent: + origin: rllib # either path to agent script or name of agent library (rllib) + config: # given to ray.tune.run() as arguments (since rllib set before) + run_or_experiment: PPO + stop: + timesteps_total: 400000 + config: + lr: 0.005 + model: + fcnet_activation: relu + fcnet_hiddens: [256,256,256,256] + post_fcnet_activation: tanh + batch_mode: complete_episodes + gamma: 0.999 + horizon: 1000 + metrics_smoothing_episodes: 5 + framework: torch + log_level: "WARNING" + num_workers: 1 # this is required for energym to work (can fail silently otherwise) + num_gpus: 1 +# environment config +env: + name: Apartments2Thermal-v0 + gym: energym + config: + # Number of simulation days + days: 365 + # Name of energym environment + energym_environment: Apartments2Thermal-v0 + gym_kwargs: + # Maximum number of timesteps in one episode + max_episode_length: 35040 # corresponds to a year of 15 min steps + # User-provided flag to require state and action spaces to be normalized + normalize: true + # Number of real-world minutes between timesteps in building simulation + step_period: 15 + # Weather file to use for the scenario (possible files depend on env chosen) + weather: ESP_CT_Barcelona \ No newline at end of file From 397a675b8440be3b1cf65850d4dd764cba90f6d4 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 15:44:01 +0000 Subject: [PATCH 084/113] docs: update env table script --- notebooks/utils/nb001_create_envs_table.ipynb | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb index c7962bfe..c29824af 100644 --- a/notebooks/utils/nb001_create_envs_table.ipynb +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -71,12 +71,19 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "# printable_envs" + "print(printable_envs.to_csv(index=False).replace(\"\\n\",\"\\n \"))" ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { From db44845be17d3dd2143c70547bb8197ae5a21d32 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 16:31:46 +0000 Subject: [PATCH 085/113] aux: change moby version in docker container --- .devcontainer/remote/.devcontainer/devcontainer.json | 2 +- beobench/experiment/definitions/rewex01.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 5dc671fc..77849218 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -63,7 +63,7 @@ "features": { "git": "latest", "docker-in-docker": { - "version": "latest", + "version": "20.10.13", "moby": true } }, diff --git a/beobench/experiment/definitions/rewex01.yaml b/beobench/experiment/definitions/rewex01.yaml index 7e706ac6..6b433602 100644 --- a/beobench/experiment/definitions/rewex01.yaml +++ b/beobench/experiment/definitions/rewex01.yaml @@ -1,6 +1,6 @@ # REWEX Experiment 01 # Run with the command -# beobench run -c beobench/experiment/definitions/rewex01.yaml -d . --use-gpu --docker-shm-size 32gb +# beobench run -c beobench/experiment/definitions/rewex01.yaml -d . --use-gpu --docker-shm-size 28gb # agent config agent: From fbb65609d1c2b77fe7b4e4c67a73a5c529cf89cc Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 16:41:39 +0000 Subject: [PATCH 086/113] aux: downgrade moby version for devcontainer --- .devcontainer/remote/.devcontainer/devcontainer.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index 77849218..a0208912 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -63,7 +63,8 @@ "features": { "git": "latest", "docker-in-docker": { - "version": "20.10.13", + // fixing version because potential cause of problem with --gpus docker run option. + "version": "20.10.12", "moby": true } }, From 4659054a576bac270fa98a8def32fa55f8e674eb Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 16:45:02 +0000 Subject: [PATCH 087/113] fix: activate nvidia part of dockerfile --- .devcontainer/remote/.devcontainer/devcontainer.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.devcontainer/remote/.devcontainer/devcontainer.json b/.devcontainer/remote/.devcontainer/devcontainer.json index a0208912..f21da5c1 100644 --- a/.devcontainer/remote/.devcontainer/devcontainer.json +++ b/.devcontainer/remote/.devcontainer/devcontainer.json @@ -12,7 +12,7 @@ "VARIANT": "3.9", // Options "NODE_VERSION": "none", - "NVIDIA_SUPPORT": "none" + "NVIDIA_SUPPORT": "True", } }, "workspaceFolder": "/beobench", @@ -63,8 +63,7 @@ "features": { "git": "latest", "docker-in-docker": { - // fixing version because potential cause of problem with --gpus docker run option. - "version": "20.10.12", + "version": "latest", "moby": true } }, From bc299a4f45881e9557dfa795285aaeb8d4058b81 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 17:41:39 +0000 Subject: [PATCH 088/113] docs: switch to sphinx book theme --- docs/conf.py | 39 +++++++++++++++++++++---------- requirements/doc_requirements.txt | 4 +++- 2 files changed, 30 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d793ef0e..14e0ccb0 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,7 +91,8 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "alabaster" +# html_theme = "alabaster" +html_theme = "sphinx_book_theme" # Theme options are theme-specific and customize the look and feel of a # theme further. For a list of options available for each theme, see the @@ -163,16 +164,30 @@ ## Custom elements +html_logo = "_static/beobench_logo.png" html_favicon = "_static/beobench_favicon_v2.png" -html_theme_options = { - "logo_name": False, - "logo": "/beobench_logo.png", - "github_repo": "beobench", - "github_user": "rdnfn", - "github_button": True, - "github_count": False, - "github_type": "star", - "fixed_sidebar": True, - # "sidebar_width": "200pt", -} +if html_theme == "alabaster": + html_theme_options = { + "logo_name": False, + "logo": "/beobench_logo.png", + "github_repo": "beobench", + "github_user": "rdnfn", + "github_button": True, + "github_count": False, + "github_type": "star", + "fixed_sidebar": True, + # "sidebar_width": "200pt", + } +elif html_theme == "sphinx_book_theme": + html_theme_options = { + "extra_navbar": "", + "home_page_in_toc": False, + "use_fullscreen_button": False, + "use_download_button": True, + "repository_url": "https://github.com/rdnfn/beobench", + "use_repository_button": True, + "use_issues_button": True, + "logo_only": True, + #'prev_next_buttons_location': None, + } diff --git a/requirements/doc_requirements.txt b/requirements/doc_requirements.txt index ccd8b306..6ccec260 100644 --- a/requirements/doc_requirements.txt +++ b/requirements/doc_requirements.txt @@ -1,2 +1,4 @@ sphinx-tabs -myst-parser \ No newline at end of file +myst-parser +sphinx-book-theme +docutils>=0.17 \ No newline at end of file From 576a48106e5a8a1f0864eee604ecb9517ced622e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 17:47:08 +0000 Subject: [PATCH 089/113] fix: reduce jinja2 version because of bug --- requirements/doc_requirements.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/requirements/doc_requirements.txt b/requirements/doc_requirements.txt index 6ccec260..a91601fd 100644 --- a/requirements/doc_requirements.txt +++ b/requirements/doc_requirements.txt @@ -1,4 +1,8 @@ sphinx-tabs myst-parser sphinx-book-theme -docutils>=0.17 \ No newline at end of file +docutils>=0.17 + +# Because of the following bug +# https://github.com/readthedocs/readthedocs.org/issues/9038 +Jinja2<3.1 \ No newline at end of file From 64095a538f253a9b15053b37b78a3491e61bd9ba Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 17:58:09 +0000 Subject: [PATCH 090/113] docs: add max width css --- docs/_static/custom.css | 3 +++ docs/conf.py | 1 + 2 files changed, 4 insertions(+) create mode 100644 docs/_static/custom.css diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..b2bd7411 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,3 @@ +.container-xl { + max-width: 1000px; + } \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 14e0ccb0..12301578 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -104,6 +104,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_css_files = ["custom.css"] # -- Options for HTMLHelp output --------------------------------------- From c91940f5a3ff0d5944c77ba8895997e585c8748e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Fri, 25 Mar 2022 18:02:21 +0000 Subject: [PATCH 091/113] docs: minor changes --- docs/_static/custom.css | 2 +- docs/conf.py | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index b2bd7411..83848a78 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -1,3 +1,3 @@ .container-xl { max-width: 1000px; - } \ No newline at end of file +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 12301578..7a96609a 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -104,7 +104,6 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] -html_css_files = ["custom.css"] # -- Options for HTMLHelp output --------------------------------------- @@ -192,3 +191,5 @@ "logo_only": True, #'prev_next_buttons_location': None, } + +html_css_files = ["custom.css"] From 93a00f53e7c6ec5c6cfa63426e09c5c552faa7da Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 10:08:16 +0000 Subject: [PATCH 092/113] docs: improve first parts of main readme --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 871999ed..07064230 100644 --- a/README.rst +++ b/README.rst @@ -24,11 +24,11 @@ :target: https://opensource.org/licenses/MIT :alt: License -A toolkit providing easy and unified access to building control reinforcement learning environments from multiple frameworks. Out of the box, Beobench provides access to environments from *BOPTEST*, *Energym*, and *Sinergym*. If required, Beobench can be easily extended to be used with other environments. +A toolkit providing easy and unified access to building control environments for reinforcement learning (RL). Features -------- -- **Largest collection of building control environments:** by combining the environments from *BOPTEST*, *Energym*, and *Sinergym*, Beobench is able to provide the (to the best of our knowledge) largest collection of building control environments (`see environment list here `_). +- **Large collection of building control environments:** Out-of-the-box Beobench provides access to environments from `BOPTEST `_, `Energym `_, and `Sinergym `_. By providing access to all the environments from these frameworks, Beobench is able to provide the (to the best of our knowledge) largest single collection of building control environments (`see environment list here `_). - **Clean and light-weight installation:** Beobench is installed via pip and only requires Docker as an additional non-python dependency (`see installation guide `_). Other packages require the user to deal with building simulator installations or manage docker images directly. - **Built-in RL agents:** Beobench allows the user to apply any agent from the `Ray RLlib collection `_ *in addition* to agents provided by the user directly. - **Easily extendable:** want to use Beobench with an environment not yet included? The support for user-defined Docker contexts makes it easy to use Beobench with any RL environment. From 062211e574b834e7a823113001d3e2b7413e672a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 10:52:55 +0000 Subject: [PATCH 093/113] docs: test field list build --- docs/envs.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/envs.rst b/docs/envs.rst index 371cbf76..38b58d58 100644 --- a/docs/envs.rst +++ b/docs/envs.rst @@ -2,19 +2,18 @@ Environments ============ -Beobench provides easy access to a large number of RL building control environments. More information about the different libraries can be found here: - -.. toctree:: - :maxdepth: 1 - - envs/boptest - envs/energym - envs/sinergym +Beobench provides easy access to a large number of building control environments for reinforcement learning. Each environment comes form a different framework. Environment list ------------------------- +:BOPTEST: + - `bestest_air `_ + - `bestest_hydronic `_ + +:Energym: - `another env `_ + .. csv-table:: :header-rows: 1 :widths: auto From bd6c584210976dc4eea45cd2e139b7b3dce968ca Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 12:42:01 +0000 Subject: [PATCH 094/113] docs: update available envs page --- docs/available_envs.csv | 41 -------- docs/available_envs_parsed.csv | 41 -------- docs/envs.rst | 52 ++++++---- docs/envs/BOPTEST_descriptions.rst | 36 +++++++ docs/envs/Energym_descriptions.rst | 99 +++++++++++++++++++ docs/envs/Sinergym_descriptions.rst | 148 ++++++++++++++++++++++++++++ docs/envs/boptest.rst | 2 - docs/envs/energym.rst | 2 - docs/envs/envs_list.rst | 54 ++++++++++ docs/envs/sinergym.rst | 2 - 10 files changed, 371 insertions(+), 106 deletions(-) delete mode 100644 docs/available_envs.csv delete mode 100644 docs/available_envs_parsed.csv create mode 100644 docs/envs/BOPTEST_descriptions.rst create mode 100644 docs/envs/Energym_descriptions.rst create mode 100644 docs/envs/Sinergym_descriptions.rst delete mode 100644 docs/envs/boptest.rst delete mode 100644 docs/envs/energym.rst create mode 100644 docs/envs/envs_list.rst delete mode 100644 docs/envs/sinergym.rst diff --git a/docs/available_envs.csv b/docs/available_envs.csv deleted file mode 100644 index ba8ed8b2..00000000 --- a/docs/available_envs.csv +++ /dev/null @@ -1,41 +0,0 @@ -Gym,Environment,House type -BOPTEST,bestest_air,residential -,bestest_hydronic,residential -,bestest_hydronic_heat_pump,residential -,multizone_residential_hydronic,residential -,singlezone_commercial_hydronic,office -Energym,Apartments2Thermal-v0,residential -,Apartments2Grid-v0,residential -,ApartmentsThermal-v0,residential -,ApartmentsGrid-v0,residential -,OfficesThermostat-v0,office -,MixedUseFanFCU-v0,office -,SeminarcenterThermostat-v0,office -,SeminarcenterFull-v0,office -,SimpleHouseRad-v0,residential -,SimpleHouseRSla-v0,residential -,SwissHouseRSlaW2W-v0,residential -,SwissHouseRSlaA2W-v0,residential -,SwissHouseRSlaTank-v0,residential -,SwissHouseRSlaTankDhw-v0,residential -Sinergym,Eplus-demo-v1,residential -,Eplus-5Zone-hot-discrete-v1,residential -,Eplus-5Zone-mixed-discrete-v1,residential -,Eplus-5Zone-cool-discrete-v1,residential -,Eplus-5Zone-hot-continuous-v1,residential -,Eplus-5Zone-mixed-continuous-v1,residential -,Eplus-5Zone-cool-continuous-v1,residential -,Eplus-5Zone-hot-discrete-stochastic-v1,residential -,Eplus-5Zone-mixed-discrete-stochastic-v1,residential -,Eplus-5Zone-cool-discrete-stochastic-v1,residential -,Eplus-5Zone-hot-continuous-stochastic-v1,residential -,Eplus-5Zone-mixed-continuous-stochastic-v1,residential -,Eplus-5Zone-cool-continuous-stochastic-v1,residential -,Eplus-datacenter-discrete-v1,industrial -,Eplus-datacenter-continuous-v1,industrial -,Eplus-datacenter-discrete-stochastic-v1,industrial -,Eplus-datacenter-continuous-stochastic-v1,industrial -,Eplus-IWMullion-discrete-v1,office -,Eplus-IWMullion-continuous-v1,office -,Eplus-IWMullion-discrete-stochastic-v1,office -,Eplus-IWMullion-continuous-stochastic-v1,office \ No newline at end of file diff --git a/docs/available_envs_parsed.csv b/docs/available_envs_parsed.csv deleted file mode 100644 index 9b480d3a..00000000 --- a/docs/available_envs_parsed.csv +++ /dev/null @@ -1,41 +0,0 @@ -Gym,Environment,Type*,Description -*BOPTEST*,``bestest_air``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``bestest_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``bestest_hydronic_heat_pump``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``multizone_residential_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``singlezone_commercial_hydronic``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -*Energym*,``Apartments2Thermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Apartments2Grid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``ApartmentsThermal-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``ApartmentsGrid-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``OfficesThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``MixedUseFanFCU-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``SeminarcenterThermostat-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``SeminarcenterFull-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``SimpleHouseRad-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``SimpleHouseRSla-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``SwissHouseRSlaW2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``SwissHouseRSlaA2W-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``SwissHouseRSlaTank-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``SwissHouseRSlaTankDhw-v0``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -*Sinergym*,``Eplus-demo-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-hot-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-mixed-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-cool-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-hot-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-mixed-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-cool-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-hot-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-mixed-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-cool-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-hot-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-mixed-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-5Zone-cool-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg,"`original `_, `beobench `_" -,``Eplus-datacenter-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" -,``Eplus-datacenter-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" -,``Eplus-datacenter-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" -,``Eplus-datacenter-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg,"`original `_, `beobench `_" -,``Eplus-IWMullion-discrete-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``Eplus-IWMullion-continuous-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``Eplus-IWMullion-discrete-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" -,``Eplus-IWMullion-continuous-stochastic-v1``,.. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg,"`original `_, `beobench `_" diff --git a/docs/envs.rst b/docs/envs.rst index 38b58d58..56492b45 100644 --- a/docs/envs.rst +++ b/docs/envs.rst @@ -2,29 +2,45 @@ Environments ============ -Beobench provides easy access to a large number of building control environments for reinforcement learning. Each environment comes form a different framework. +Beobench provides easy access to a large number of building control environments for reinforcement learning. Each environment comes from one of the integrated frameworks `BOPTEST `_, `Energym `_ and `Sinergym `_. The list below shows links to all environments available out-of-the-box. Each environment is marked based on whether it represents a residential building (|home|), office (|office|) or data center (|industry|). +.. include:: envs/envs_list.rst -Environment list -------------------------- -:BOPTEST: - - `bestest_air `_ - - `bestest_hydronic `_ +.. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg +.. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg +.. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg -:Energym: - `another env `_ +---- -.. csv-table:: - :header-rows: 1 - :widths: auto - :file: available_envs_parsed.csv +BOPTEST +------- -\* Types of environments: +.. include:: ../beobench_contrib/gyms/boptest/README.md + :parser: myst_parser.sphinx_ + :start-line: 2 -* residential |home| -* office |office| -* data center |industry| +.. include:: envs/BOPTEST_descriptions.rst -.. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg -.. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg -.. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg \ No newline at end of file + +---- + +Energym +------- + +.. include:: ../beobench_contrib/gyms/energym/README.md + :parser: myst_parser.sphinx_ + :start-line: 2 + +.. include:: envs/Energym_descriptions.rst + +---- + +Sinergym +-------- + +.. include:: ../beobench_contrib/gyms/sinergym/README.md + :parser: myst_parser.sphinx_ + :start-line: 2 + +.. include:: envs/Sinergym_descriptions.rst \ No newline at end of file diff --git a/docs/envs/BOPTEST_descriptions.rst b/docs/envs/BOPTEST_descriptions.rst new file mode 100644 index 00000000..e726b71d --- /dev/null +++ b/docs/envs/BOPTEST_descriptions.rst @@ -0,0 +1,36 @@ + + +.. _env-bestest_air: + +``bestest_air`` +^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-bestest_hydronic: + +``bestest_hydronic`` +^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-bestest_hydronic_heat_pump: + +``bestest_hydronic_heat_pump`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-multizone_residential_hydronic: + +``multizone_residential_hydronic`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-singlezone_commercial_hydronic: + +``singlezone_commercial_hydronic`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) \ No newline at end of file diff --git a/docs/envs/Energym_descriptions.rst b/docs/envs/Energym_descriptions.rst new file mode 100644 index 00000000..3494025f --- /dev/null +++ b/docs/envs/Energym_descriptions.rst @@ -0,0 +1,99 @@ + + +.. _env-Apartments2Thermal-v0: + +``Apartments2Thermal-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Apartments2Grid-v0: + +``Apartments2Grid-v0`` +^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-ApartmentsThermal-v0: + +``ApartmentsThermal-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-ApartmentsGrid-v0: + +``ApartmentsGrid-v0`` +^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-OfficesThermostat-v0: + +``OfficesThermostat-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-MixedUseFanFCU-v0: + +``MixedUseFanFCU-v0`` +^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-SeminarcenterThermostat-v0: + +``SeminarcenterThermostat-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-SeminarcenterFull-v0: + +``SeminarcenterFull-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-SimpleHouseRad-v0: + +``SimpleHouseRad-v0`` +^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-SimpleHouseRSla-v0: + +``SimpleHouseRSla-v0`` +^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-SwissHouseRSlaW2W-v0: + +``SwissHouseRSlaW2W-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-SwissHouseRSlaA2W-v0: + +``SwissHouseRSlaA2W-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-SwissHouseRSlaTank-v0: + +``SwissHouseRSlaTank-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-SwissHouseRSlaTankDhw-v0: + +``SwissHouseRSlaTankDhw-v0`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) \ No newline at end of file diff --git a/docs/envs/Sinergym_descriptions.rst b/docs/envs/Sinergym_descriptions.rst new file mode 100644 index 00000000..dba45da8 --- /dev/null +++ b/docs/envs/Sinergym_descriptions.rst @@ -0,0 +1,148 @@ + + +.. _env-Eplus-demo-v1: + +``Eplus-demo-v1`` +^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-hot-discrete-v1: + +``Eplus-5Zone-hot-discrete-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-mixed-discrete-v1: + +``Eplus-5Zone-mixed-discrete-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-cool-discrete-v1: + +``Eplus-5Zone-cool-discrete-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-hot-continuous-v1: + +``Eplus-5Zone-hot-continuous-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-mixed-continuous-v1: + +``Eplus-5Zone-mixed-continuous-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-cool-continuous-v1: + +``Eplus-5Zone-cool-continuous-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-hot-discrete-stochastic-v1: + +``Eplus-5Zone-hot-discrete-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-mixed-discrete-stochastic-v1: + +``Eplus-5Zone-mixed-discrete-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-cool-discrete-stochastic-v1: + +``Eplus-5Zone-cool-discrete-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-hot-continuous-stochastic-v1: + +``Eplus-5Zone-hot-continuous-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-mixed-continuous-stochastic-v1: + +``Eplus-5Zone-mixed-continuous-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-5Zone-cool-continuous-stochastic-v1: + +``Eplus-5Zone-cool-continuous-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: residential building (|home|) + +.. _env-Eplus-datacenter-discrete-v1: + +``Eplus-datacenter-discrete-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: |industry| (|industry|) + +.. _env-Eplus-datacenter-continuous-v1: + +``Eplus-datacenter-continuous-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: |industry| (|industry|) + +.. _env-Eplus-datacenter-discrete-stochastic-v1: + +``Eplus-datacenter-discrete-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: |industry| (|industry|) + +.. _env-Eplus-datacenter-continuous-stochastic-v1: + +``Eplus-datacenter-continuous-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: |industry| (|industry|) + +.. _env-Eplus-IWMullion-discrete-v1: + +``Eplus-IWMullion-discrete-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-Eplus-IWMullion-continuous-v1: + +``Eplus-IWMullion-continuous-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-Eplus-IWMullion-discrete-stochastic-v1: + +``Eplus-IWMullion-discrete-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) + +.. _env-Eplus-IWMullion-continuous-stochastic-v1: + +``Eplus-IWMullion-continuous-stochastic-v1`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:Type: office building (|office|) \ No newline at end of file diff --git a/docs/envs/boptest.rst b/docs/envs/boptest.rst deleted file mode 100644 index 383aac1b..00000000 --- a/docs/envs/boptest.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../beobench_contrib/gyms/boptest/README.md - :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/envs/energym.rst b/docs/envs/energym.rst deleted file mode 100644 index 0bd333da..00000000 --- a/docs/envs/energym.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../beobench_contrib/gyms/energym/README.md - :parser: myst_parser.sphinx_ \ No newline at end of file diff --git a/docs/envs/envs_list.rst b/docs/envs/envs_list.rst new file mode 100644 index 00000000..98bf063d --- /dev/null +++ b/docs/envs/envs_list.rst @@ -0,0 +1,54 @@ +:BOPTEST: + - :ref:`bestest_air ` |home| + - :ref:`bestest_hydronic ` |home| + - :ref:`bestest_hydronic_heat_pump ` |home| + - :ref:`multizone_residential_hydronic ` |home| + - :ref:`singlezone_commercial_hydronic ` |office| + +---- + +:Energym: + - :ref:`Apartments2Thermal-v0 ` |home| + - :ref:`Apartments2Grid-v0 ` |home| + - :ref:`ApartmentsThermal-v0 ` |home| + - :ref:`ApartmentsGrid-v0 ` |home| + - :ref:`OfficesThermostat-v0 ` |office| + - :ref:`MixedUseFanFCU-v0 ` |office| + - :ref:`SeminarcenterThermostat-v0 ` |office| + - :ref:`SeminarcenterFull-v0 ` |office| + - :ref:`SimpleHouseRad-v0 ` |home| + - :ref:`SimpleHouseRSla-v0 ` |home| + - :ref:`SwissHouseRSlaW2W-v0 ` |home| + - :ref:`SwissHouseRSlaA2W-v0 ` |home| + - :ref:`SwissHouseRSlaTank-v0 ` |home| + - :ref:`SwissHouseRSlaTankDhw-v0 ` |home| + +---- + +:Sinergym: + - :ref:`Eplus-demo-v1 ` |home| + - :ref:`Eplus-5Zone-hot-discrete-v1 ` |home| + - :ref:`Eplus-5Zone-mixed-discrete-v1 ` |home| + - :ref:`Eplus-5Zone-cool-discrete-v1 ` |home| + - :ref:`Eplus-5Zone-hot-continuous-v1 ` |home| + - :ref:`Eplus-5Zone-mixed-continuous-v1 ` |home| + - :ref:`Eplus-5Zone-cool-continuous-v1 ` |home| + - :ref:`Eplus-5Zone-hot-discrete-stochastic-v1 ` |home| + - :ref:`Eplus-5Zone-mixed-discrete-stochastic-v1 ` |home| + - :ref:`Eplus-5Zone-cool-discrete-stochastic-v1 ` |home| + - :ref:`Eplus-5Zone-hot-continuous-stochastic-v1 ` |home| + - :ref:`Eplus-5Zone-mixed-continuous-stochastic-v1 ` |home| + - :ref:`Eplus-5Zone-cool-continuous-stochastic-v1 ` |home| + - :ref:`Eplus-datacenter-discrete-v1 ` |industry| + - :ref:`Eplus-datacenter-continuous-v1 ` |industry| + - :ref:`Eplus-datacenter-discrete-stochastic-v1 ` |industry| + - :ref:`Eplus-datacenter-continuous-stochastic-v1 ` |industry| + - :ref:`Eplus-IWMullion-discrete-v1 ` |office| + - :ref:`Eplus-IWMullion-continuous-v1 ` |office| + - :ref:`Eplus-IWMullion-discrete-stochastic-v1 ` |office| + - :ref:`Eplus-IWMullion-continuous-stochastic-v1 ` |office| + + .. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg + .. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg + .. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg + \ No newline at end of file diff --git a/docs/envs/sinergym.rst b/docs/envs/sinergym.rst deleted file mode 100644 index aef4af9d..00000000 --- a/docs/envs/sinergym.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../beobench_contrib/gyms/sinergym/README.md - :parser: myst_parser.sphinx_ \ No newline at end of file From 150021dd9b1b5fccbec2249f7ec77db652edad3c Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 12:43:30 +0000 Subject: [PATCH 095/113] docs: update envs list notebook --- notebooks/utils/nb001_create_envs_table.ipynb | 118 +++++++++++++----- 1 file changed, 84 insertions(+), 34 deletions(-) diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb index c29824af..5ec4e703 100644 --- a/notebooks/utils/nb001_create_envs_table.ipynb +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -27,55 +27,105 @@ "link = f\"https://docs.google.com/feeds/download/spreadsheets/Export?key={sheet_id}&exportFormat=csv&gid={gid}\"\n", "envs = pd.read_csv(link)\n", "\n", + "# Preprocessing\n", "\n", - "# format data for rst\n", + "# Add house type icons\n", "def emojify(row): \n", " house_type = row[\"House type\"]\n", " if house_type == \"residential\":\n", - " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg\"\n", + " return \"|home|\"\n", " elif house_type == \"office\":\n", - " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg\"\n", + " return \"|office|\"\n", " elif house_type == \"industrial\":\n", - " return \".. image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg\"\n", + " return \"|industry|\"\n", " return \"other\"\n", "\n", - "def italicise(row, col):\n", - " value = row[col]\n", - " if value is not np.nan:\n", - " return f\"*{value}*\"\n", - " else:\n", - " return \"\"\n", - "\n", - "def codify(row, col):\n", - " value = row[col]\n", - " if value is not np.nan:\n", - " return f\"``{value}``\"\n", - " else:\n", - " return \"\"\n", - "\n", - "def create_doc_links(row):\n", - " original_url = row[\"Original docs\"]\n", - " beobench_url = row[\"Beobench docs\"]\n", - " link_str = f\"`original <{original_url}>`_, `beobench <{beobench_url}>`_\"\n", - " return link_str\n", - "\n", - "envs['Type*'] = envs.apply(lambda row: emojify(row), axis=1)\n", - "envs['Gym'] = envs.apply(lambda row: italicise(row, col=\"Gym\"), axis=1)\n", - "envs['Environment'] = envs.apply(lambda row: codify(row, col=\"Environment\"), axis=1)\n", - "envs['Description'] = envs.apply(lambda row: create_doc_links(row), axis=1)\n", - "\n", - "# Save data to csv\n", - "printable_envs = envs[[\"Gym\",\"Environment\",\"Type*\",\"Description\"]]\n", - "printable_envs.to_csv(\"../../docs/available_envs_parsed.csv\", index=False)\n" + "def new_type(row): \n", + " house_type = row[\"House type\"]\n", + " if house_type == \"residential\":\n", + " return \"residential building\"\n", + " elif house_type == \"office\":\n", + " return \"office building\"\n", + " elif house_type == \"industrial\":\n", + " return \"|industry|\"\n", + " return \"data center\"\n", + "\n", + "envs['Type'] = envs.apply(lambda row: emojify(row), axis=1)\n", + "envs['new_type'] = envs.apply(lambda row: new_type(row), axis=1)\n", + "\n", + "# Make sure each env has gym\n", + "envs['Gym'] = envs['Gym'].replace('', np.NaN)\n", + "envs['Gym'] = envs['Gym'].fillna(method='ffill',axis=0)\n", + "\n", + "\n", + "\n", + "\n" ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "# Create main environment list\n", + "\n", + "def create_main_list(filepath=\"../../docs/envs/envs_list.rst\"):\n", + "\n", + " rst_out = \"\"\n", + "\n", + " for i, gym in enumerate(envs['Gym'].unique()):\n", + " gym_envs = envs[envs['Gym']==gym]\n", + "\n", + " rst_out += f\":{gym}:\\n\"\n", + "\n", + " for index, row in gym_envs.iterrows():\n", + " env = row[\"Environment\"]\n", + " symbol = row[\"Type\"]\n", + " rst_out += f\" - :ref:`{env} ` {symbol}\\n\"\n", + "\n", + " # Add hline between gyms\n", + " if i < len(envs['Gym'].unique()) - 1:\n", + " rst_out += \"\\n----\\n\\n\"\n", + "\n", + " # Add image links\n", + " rst_out += \"\"\"\n", + " .. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg\n", + " .. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg\n", + " .. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg\n", + " \"\"\"\n", + "\n", + " with open(filepath, 'w') as file:\n", + " file.write(rst_out)\n", + "\n", + "\n", + "create_main_list(filepath=\"../../docs/envs/envs_list.rst\")" + ] + }, + { + "cell_type": "code", + "execution_count": 4, "metadata": {}, "outputs": [], "source": [ - "print(printable_envs.to_csv(index=False).replace(\"\\n\",\"\\n \"))" + "def create_env_descriptions():\n", + " for _, gym in enumerate(envs['Gym'].unique()):\n", + " env_descr_file = f\"../../docs/envs/{gym}_descriptions.rst\"\n", + " rst_out = \"\"\n", + " gym_envs = envs[envs['Gym']==gym]\n", + "\n", + " for _, row in gym_envs.iterrows():\n", + " env = row[\"Environment\"]\n", + " rst_out += f\"\\n\\n.. _env-{env}: \\n\\n\"\n", + " rst_out += f\"``{env}``\\n\"\n", + " rst_out += '^' * (len(env) + 4) + \"\\n\\n\"\n", + " rst_out += f\":Type: {row['new_type']} ({row['Type']})\"\n", + "\n", + " with open(env_descr_file, 'w') as file:\n", + " file.write(rst_out)\n", + "\n", + "create_env_descriptions()\n", + " " ] }, { From 7646e7c1ef05a11145bbb93f82103e23eecc952a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 12:52:45 +0000 Subject: [PATCH 096/113] docs: update links in env list to local headings --- docs/envs/envs_list.rst | 80 ++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/envs/envs_list.rst b/docs/envs/envs_list.rst index 98bf063d..79b48207 100644 --- a/docs/envs/envs_list.rst +++ b/docs/envs/envs_list.rst @@ -1,52 +1,52 @@ :BOPTEST: - - :ref:`bestest_air ` |home| - - :ref:`bestest_hydronic ` |home| - - :ref:`bestest_hydronic_heat_pump ` |home| - - :ref:`multizone_residential_hydronic ` |home| - - :ref:`singlezone_commercial_hydronic ` |office| + - `bestest_air`_ |home| + - `bestest_hydronic`_ |home| + - `bestest_hydronic_heat_pump`_ |home| + - `multizone_residential_hydronic`_ |home| + - `singlezone_commercial_hydronic`_ |office| ---- :Energym: - - :ref:`Apartments2Thermal-v0 ` |home| - - :ref:`Apartments2Grid-v0 ` |home| - - :ref:`ApartmentsThermal-v0 ` |home| - - :ref:`ApartmentsGrid-v0 ` |home| - - :ref:`OfficesThermostat-v0 ` |office| - - :ref:`MixedUseFanFCU-v0 ` |office| - - :ref:`SeminarcenterThermostat-v0 ` |office| - - :ref:`SeminarcenterFull-v0 ` |office| - - :ref:`SimpleHouseRad-v0 ` |home| - - :ref:`SimpleHouseRSla-v0 ` |home| - - :ref:`SwissHouseRSlaW2W-v0 ` |home| - - :ref:`SwissHouseRSlaA2W-v0 ` |home| - - :ref:`SwissHouseRSlaTank-v0 ` |home| - - :ref:`SwissHouseRSlaTankDhw-v0 ` |home| + - `Apartments2Thermal-v0`_ |home| + - `Apartments2Grid-v0`_ |home| + - `ApartmentsThermal-v0`_ |home| + - `ApartmentsGrid-v0`_ |home| + - `OfficesThermostat-v0`_ |office| + - `MixedUseFanFCU-v0`_ |office| + - `SeminarcenterThermostat-v0`_ |office| + - `SeminarcenterFull-v0`_ |office| + - `SimpleHouseRad-v0`_ |home| + - `SimpleHouseRSla-v0`_ |home| + - `SwissHouseRSlaW2W-v0`_ |home| + - `SwissHouseRSlaA2W-v0`_ |home| + - `SwissHouseRSlaTank-v0`_ |home| + - `SwissHouseRSlaTankDhw-v0`_ |home| ---- :Sinergym: - - :ref:`Eplus-demo-v1 ` |home| - - :ref:`Eplus-5Zone-hot-discrete-v1 ` |home| - - :ref:`Eplus-5Zone-mixed-discrete-v1 ` |home| - - :ref:`Eplus-5Zone-cool-discrete-v1 ` |home| - - :ref:`Eplus-5Zone-hot-continuous-v1 ` |home| - - :ref:`Eplus-5Zone-mixed-continuous-v1 ` |home| - - :ref:`Eplus-5Zone-cool-continuous-v1 ` |home| - - :ref:`Eplus-5Zone-hot-discrete-stochastic-v1 ` |home| - - :ref:`Eplus-5Zone-mixed-discrete-stochastic-v1 ` |home| - - :ref:`Eplus-5Zone-cool-discrete-stochastic-v1 ` |home| - - :ref:`Eplus-5Zone-hot-continuous-stochastic-v1 ` |home| - - :ref:`Eplus-5Zone-mixed-continuous-stochastic-v1 ` |home| - - :ref:`Eplus-5Zone-cool-continuous-stochastic-v1 ` |home| - - :ref:`Eplus-datacenter-discrete-v1 ` |industry| - - :ref:`Eplus-datacenter-continuous-v1 ` |industry| - - :ref:`Eplus-datacenter-discrete-stochastic-v1 ` |industry| - - :ref:`Eplus-datacenter-continuous-stochastic-v1 ` |industry| - - :ref:`Eplus-IWMullion-discrete-v1 ` |office| - - :ref:`Eplus-IWMullion-continuous-v1 ` |office| - - :ref:`Eplus-IWMullion-discrete-stochastic-v1 ` |office| - - :ref:`Eplus-IWMullion-continuous-stochastic-v1 ` |office| + - `Eplus-demo-v1`_ |home| + - `Eplus-5Zone-hot-discrete-v1`_ |home| + - `Eplus-5Zone-mixed-discrete-v1`_ |home| + - `Eplus-5Zone-cool-discrete-v1`_ |home| + - `Eplus-5Zone-hot-continuous-v1`_ |home| + - `Eplus-5Zone-mixed-continuous-v1`_ |home| + - `Eplus-5Zone-cool-continuous-v1`_ |home| + - `Eplus-5Zone-hot-discrete-stochastic-v1`_ |home| + - `Eplus-5Zone-mixed-discrete-stochastic-v1`_ |home| + - `Eplus-5Zone-cool-discrete-stochastic-v1`_ |home| + - `Eplus-5Zone-hot-continuous-stochastic-v1`_ |home| + - `Eplus-5Zone-mixed-continuous-stochastic-v1`_ |home| + - `Eplus-5Zone-cool-continuous-stochastic-v1`_ |home| + - `Eplus-datacenter-discrete-v1`_ |industry| + - `Eplus-datacenter-continuous-v1`_ |industry| + - `Eplus-datacenter-discrete-stochastic-v1`_ |industry| + - `Eplus-datacenter-continuous-stochastic-v1`_ |industry| + - `Eplus-IWMullion-discrete-v1`_ |office| + - `Eplus-IWMullion-continuous-v1`_ |office| + - `Eplus-IWMullion-discrete-stochastic-v1`_ |office| + - `Eplus-IWMullion-continuous-stochastic-v1`_ |office| .. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg .. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg From 09652a46dad8c7fd8d5bc616020ec6144b248f77 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 12:59:56 +0000 Subject: [PATCH 097/113] docs: update envs header in env list --- docs/envs.rst | 17 ++++++++---- docs/envs/BOPTEST_descriptions.rst | 10 +++---- docs/envs/Energym_descriptions.rst | 28 +++++++++---------- docs/envs/Sinergym_descriptions.rst | 42 ++++++++++++++--------------- 4 files changed, 52 insertions(+), 45 deletions(-) diff --git a/docs/envs.rst b/docs/envs.rst index 56492b45..e61143f6 100644 --- a/docs/envs.rst +++ b/docs/envs.rst @@ -6,11 +6,6 @@ Beobench provides easy access to a large number of building control environments .. include:: envs/envs_list.rst - -.. |office| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-skyscraper.svg -.. |home| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/home.svg -.. |industry| image:: https://raw.githubusercontent.com/tabler/tabler-icons/master/icons/building-factory.svg - ---- BOPTEST @@ -20,6 +15,10 @@ BOPTEST :parser: myst_parser.sphinx_ :start-line: 2 + +BOPTEST Envs +^^^^^^^^^^^^ + .. include:: envs/BOPTEST_descriptions.rst @@ -32,6 +31,10 @@ Energym :parser: myst_parser.sphinx_ :start-line: 2 + +Energym Envs +^^^^^^^^^^^^ + .. include:: envs/Energym_descriptions.rst ---- @@ -43,4 +46,8 @@ Sinergym :parser: myst_parser.sphinx_ :start-line: 2 + +Sinergym Envs +^^^^^^^^^^^^^ + .. include:: envs/Sinergym_descriptions.rst \ No newline at end of file diff --git a/docs/envs/BOPTEST_descriptions.rst b/docs/envs/BOPTEST_descriptions.rst index e726b71d..4bf1edcd 100644 --- a/docs/envs/BOPTEST_descriptions.rst +++ b/docs/envs/BOPTEST_descriptions.rst @@ -3,34 +3,34 @@ .. _env-bestest_air: ``bestest_air`` -^^^^^^^^^^^^^^^ +""""""""""""""" :Type: residential building (|home|) .. _env-bestest_hydronic: ``bestest_hydronic`` -^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""" :Type: residential building (|home|) .. _env-bestest_hydronic_heat_pump: ``bestest_hydronic_heat_pump`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-multizone_residential_hydronic: ``multizone_residential_hydronic`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-singlezone_commercial_hydronic: ``singlezone_commercial_hydronic`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""" :Type: office building (|office|) \ No newline at end of file diff --git a/docs/envs/Energym_descriptions.rst b/docs/envs/Energym_descriptions.rst index 3494025f..582a369f 100644 --- a/docs/envs/Energym_descriptions.rst +++ b/docs/envs/Energym_descriptions.rst @@ -3,97 +3,97 @@ .. _env-Apartments2Thermal-v0: ``Apartments2Thermal-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Apartments2Grid-v0: ``Apartments2Grid-v0`` -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" :Type: residential building (|home|) .. _env-ApartmentsThermal-v0: ``ApartmentsThermal-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" :Type: residential building (|home|) .. _env-ApartmentsGrid-v0: ``ApartmentsGrid-v0`` -^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""" :Type: residential building (|home|) .. _env-OfficesThermostat-v0: ``OfficesThermostat-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" :Type: office building (|office|) .. _env-MixedUseFanFCU-v0: ``MixedUseFanFCU-v0`` -^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""" :Type: office building (|office|) .. _env-SeminarcenterThermostat-v0: ``SeminarcenterThermostat-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""" :Type: office building (|office|) .. _env-SeminarcenterFull-v0: ``SeminarcenterFull-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" :Type: office building (|office|) .. _env-SimpleHouseRad-v0: ``SimpleHouseRad-v0`` -^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""" :Type: residential building (|home|) .. _env-SimpleHouseRSla-v0: ``SimpleHouseRSla-v0`` -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" :Type: residential building (|home|) .. _env-SwissHouseRSlaW2W-v0: ``SwissHouseRSlaW2W-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" :Type: residential building (|home|) .. _env-SwissHouseRSlaA2W-v0: ``SwissHouseRSlaA2W-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" :Type: residential building (|home|) .. _env-SwissHouseRSlaTank-v0: ``SwissHouseRSlaTank-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-SwissHouseRSlaTankDhw-v0: ``SwissHouseRSlaTankDhw-v0`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""" :Type: residential building (|home|) \ No newline at end of file diff --git a/docs/envs/Sinergym_descriptions.rst b/docs/envs/Sinergym_descriptions.rst index dba45da8..8d8f339a 100644 --- a/docs/envs/Sinergym_descriptions.rst +++ b/docs/envs/Sinergym_descriptions.rst @@ -3,146 +3,146 @@ .. _env-Eplus-demo-v1: ``Eplus-demo-v1`` -^^^^^^^^^^^^^^^^^ +""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-hot-discrete-v1: ``Eplus-5Zone-hot-discrete-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-mixed-discrete-v1: ``Eplus-5Zone-mixed-discrete-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-cool-discrete-v1: ``Eplus-5Zone-cool-discrete-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-hot-continuous-v1: ``Eplus-5Zone-hot-continuous-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-mixed-continuous-v1: ``Eplus-5Zone-mixed-continuous-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-cool-continuous-v1: ``Eplus-5Zone-cool-continuous-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-hot-discrete-stochastic-v1: ``Eplus-5Zone-hot-discrete-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-mixed-discrete-stochastic-v1: ``Eplus-5Zone-mixed-discrete-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-cool-discrete-stochastic-v1: ``Eplus-5Zone-cool-discrete-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-hot-continuous-stochastic-v1: ``Eplus-5Zone-hot-continuous-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-mixed-continuous-stochastic-v1: ``Eplus-5Zone-mixed-continuous-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-5Zone-cool-continuous-stochastic-v1: ``Eplus-5Zone-cool-continuous-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) .. _env-Eplus-datacenter-discrete-v1: ``Eplus-datacenter-discrete-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) .. _env-Eplus-datacenter-continuous-v1: ``Eplus-datacenter-continuous-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) .. _env-Eplus-datacenter-discrete-stochastic-v1: ``Eplus-datacenter-discrete-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) .. _env-Eplus-datacenter-continuous-stochastic-v1: ``Eplus-datacenter-continuous-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) .. _env-Eplus-IWMullion-discrete-v1: ``Eplus-IWMullion-discrete-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""" :Type: office building (|office|) .. _env-Eplus-IWMullion-continuous-v1: ``Eplus-IWMullion-continuous-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""" :Type: office building (|office|) .. _env-Eplus-IWMullion-discrete-stochastic-v1: ``Eplus-IWMullion-discrete-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""" :Type: office building (|office|) .. _env-Eplus-IWMullion-continuous-stochastic-v1: ``Eplus-IWMullion-continuous-stochastic-v1`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""" :Type: office building (|office|) \ No newline at end of file From 41add1e890fe885247d4b30b5ecd9813a341eba2 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 13:10:33 +0000 Subject: [PATCH 098/113] docs: update env table creator --- notebooks/utils/nb001_create_envs_table.ipynb | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb index 5ec4e703..d6eeb2b5 100644 --- a/notebooks/utils/nb001_create_envs_table.ipynb +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -64,7 +64,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 6, "metadata": {}, "outputs": [], "source": [ @@ -82,7 +82,7 @@ " for index, row in gym_envs.iterrows():\n", " env = row[\"Environment\"]\n", " symbol = row[\"Type\"]\n", - " rst_out += f\" - :ref:`{env} ` {symbol}\\n\"\n", + " rst_out += f\" - `{env}`_ {symbol}\\n\"\n", "\n", " # Add hline between gyms\n", " if i < len(envs['Gym'].unique()) - 1:\n", @@ -104,7 +104,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": 7, "metadata": {}, "outputs": [], "source": [ @@ -118,7 +118,7 @@ " env = row[\"Environment\"]\n", " rst_out += f\"\\n\\n.. _env-{env}: \\n\\n\"\n", " rst_out += f\"``{env}``\\n\"\n", - " rst_out += '^' * (len(env) + 4) + \"\\n\\n\"\n", + " rst_out += '\"' * (len(env) + 4) + \"\\n\\n\"\n", " rst_out += f\":Type: {row['new_type']} ({row['Type']})\"\n", "\n", " with open(env_descr_file, 'w') as file:\n", From 4446ae90e337c9d80e59f41357833c65cf8b754e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 13:17:16 +0000 Subject: [PATCH 099/113] docs: add link to framework docs to envs --- docs/envs/BOPTEST_descriptions.rst | 11 +++++++- docs/envs/Energym_descriptions.rst | 29 ++++++++++++++++++- docs/envs/Sinergym_descriptions.rst | 43 ++++++++++++++++++++++++++++- 3 files changed, 80 insertions(+), 3 deletions(-) diff --git a/docs/envs/BOPTEST_descriptions.rst b/docs/envs/BOPTEST_descriptions.rst index 4bf1edcd..d314dc12 100644 --- a/docs/envs/BOPTEST_descriptions.rst +++ b/docs/envs/BOPTEST_descriptions.rst @@ -6,6 +6,8 @@ """"""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-bestest_hydronic: @@ -13,6 +15,8 @@ """""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-bestest_hydronic_heat_pump: @@ -20,6 +24,8 @@ """""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-multizone_residential_hydronic: @@ -27,10 +33,13 @@ """""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-singlezone_commercial_hydronic: ``singlezone_commercial_hydronic`` """""""""""""""""""""""""""""""""" -:Type: office building (|office|) \ No newline at end of file +:Type: office building (|office|) +:More info: `framework docs `_ diff --git a/docs/envs/Energym_descriptions.rst b/docs/envs/Energym_descriptions.rst index 582a369f..0a021e9e 100644 --- a/docs/envs/Energym_descriptions.rst +++ b/docs/envs/Energym_descriptions.rst @@ -6,6 +6,8 @@ """"""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Apartments2Grid-v0: @@ -13,6 +15,8 @@ """""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-ApartmentsThermal-v0: @@ -20,6 +24,8 @@ """""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-ApartmentsGrid-v0: @@ -27,6 +33,8 @@ """"""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-OfficesThermostat-v0: @@ -34,6 +42,8 @@ """""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-MixedUseFanFCU-v0: @@ -41,6 +51,8 @@ """"""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-SeminarcenterThermostat-v0: @@ -48,6 +60,8 @@ """""""""""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-SeminarcenterFull-v0: @@ -55,6 +69,8 @@ """""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-SimpleHouseRad-v0: @@ -62,6 +78,8 @@ """"""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-SimpleHouseRSla-v0: @@ -69,6 +87,8 @@ """""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-SwissHouseRSlaW2W-v0: @@ -76,6 +96,8 @@ """""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-SwissHouseRSlaA2W-v0: @@ -83,6 +105,8 @@ """""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-SwissHouseRSlaTank-v0: @@ -90,10 +114,13 @@ """"""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-SwissHouseRSlaTankDhw-v0: ``SwissHouseRSlaTankDhw-v0`` """""""""""""""""""""""""""" -:Type: residential building (|home|) \ No newline at end of file +:Type: residential building (|home|) +:More info: `framework docs `_ diff --git a/docs/envs/Sinergym_descriptions.rst b/docs/envs/Sinergym_descriptions.rst index 8d8f339a..c3b7a0e6 100644 --- a/docs/envs/Sinergym_descriptions.rst +++ b/docs/envs/Sinergym_descriptions.rst @@ -6,6 +6,8 @@ """"""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-hot-discrete-v1: @@ -13,6 +15,8 @@ """"""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-mixed-discrete-v1: @@ -20,6 +24,8 @@ """"""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-cool-discrete-v1: @@ -27,6 +33,8 @@ """""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-hot-continuous-v1: @@ -34,6 +42,8 @@ """"""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-mixed-continuous-v1: @@ -41,6 +51,8 @@ """"""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-cool-continuous-v1: @@ -48,6 +60,8 @@ """""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-hot-discrete-stochastic-v1: @@ -55,6 +69,8 @@ """""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-mixed-discrete-stochastic-v1: @@ -62,6 +78,8 @@ """""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-cool-discrete-stochastic-v1: @@ -69,6 +87,8 @@ """"""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-hot-continuous-stochastic-v1: @@ -76,6 +96,8 @@ """""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-mixed-continuous-stochastic-v1: @@ -83,6 +105,8 @@ """""""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-5Zone-cool-continuous-stochastic-v1: @@ -90,6 +114,8 @@ """"""""""""""""""""""""""""""""""""""""""""" :Type: residential building (|home|) +:More info: `framework docs `_ + .. _env-Eplus-datacenter-discrete-v1: @@ -97,6 +123,8 @@ """""""""""""""""""""""""""""""" :Type: |industry| (|industry|) +:More info: `framework docs `_ + .. _env-Eplus-datacenter-continuous-v1: @@ -104,6 +132,8 @@ """""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) +:More info: `framework docs `_ + .. _env-Eplus-datacenter-discrete-stochastic-v1: @@ -111,6 +141,8 @@ """"""""""""""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) +:More info: `framework docs `_ + .. _env-Eplus-datacenter-continuous-stochastic-v1: @@ -118,6 +150,8 @@ """"""""""""""""""""""""""""""""""""""""""""" :Type: |industry| (|industry|) +:More info: `framework docs `_ + .. _env-Eplus-IWMullion-discrete-v1: @@ -125,6 +159,8 @@ """"""""""""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-Eplus-IWMullion-continuous-v1: @@ -132,6 +168,8 @@ """"""""""""""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-Eplus-IWMullion-discrete-stochastic-v1: @@ -139,10 +177,13 @@ """""""""""""""""""""""""""""""""""""""""" :Type: office building (|office|) +:More info: `framework docs `_ + .. _env-Eplus-IWMullion-continuous-stochastic-v1: ``Eplus-IWMullion-continuous-stochastic-v1`` """""""""""""""""""""""""""""""""""""""""""" -:Type: office building (|office|) \ No newline at end of file +:Type: office building (|office|) +:More info: `framework docs `_ From c36caecef9de6713a0f9f87c09904ec65f90d0b9 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 13:20:14 +0000 Subject: [PATCH 100/113] docs: update industrial type misprint --- docs/envs/Sinergym_descriptions.rst | 8 ++++---- notebooks/utils/nb001_create_envs_table.ipynb | 11 ++++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/envs/Sinergym_descriptions.rst b/docs/envs/Sinergym_descriptions.rst index c3b7a0e6..33d9307f 100644 --- a/docs/envs/Sinergym_descriptions.rst +++ b/docs/envs/Sinergym_descriptions.rst @@ -122,7 +122,7 @@ ``Eplus-datacenter-discrete-v1`` """""""""""""""""""""""""""""""" -:Type: |industry| (|industry|) +:Type: industry (|industry|) :More info: `framework docs `_ @@ -131,7 +131,7 @@ ``Eplus-datacenter-continuous-v1`` """""""""""""""""""""""""""""""""" -:Type: |industry| (|industry|) +:Type: industry (|industry|) :More info: `framework docs `_ @@ -140,7 +140,7 @@ ``Eplus-datacenter-discrete-stochastic-v1`` """"""""""""""""""""""""""""""""""""""""""" -:Type: |industry| (|industry|) +:Type: industry (|industry|) :More info: `framework docs `_ @@ -149,7 +149,7 @@ ``Eplus-datacenter-continuous-stochastic-v1`` """"""""""""""""""""""""""""""""""""""""""""" -:Type: |industry| (|industry|) +:Type: industry (|industry|) :More info: `framework docs `_ diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb index d6eeb2b5..5c5072cf 100644 --- a/notebooks/utils/nb001_create_envs_table.ipynb +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -14,7 +14,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 15, "metadata": {}, "outputs": [], "source": [ @@ -47,7 +47,7 @@ " elif house_type == \"office\":\n", " return \"office building\"\n", " elif house_type == \"industrial\":\n", - " return \"|industry|\"\n", + " return \"industry\"\n", " return \"data center\"\n", "\n", "envs['Type'] = envs.apply(lambda row: emojify(row), axis=1)\n", @@ -64,7 +64,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 16, "metadata": {}, "outputs": [], "source": [ @@ -104,7 +104,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 17, "metadata": {}, "outputs": [], "source": [ @@ -119,7 +119,8 @@ " rst_out += f\"\\n\\n.. _env-{env}: \\n\\n\"\n", " rst_out += f\"``{env}``\\n\"\n", " rst_out += '\"' * (len(env) + 4) + \"\\n\\n\"\n", - " rst_out += f\":Type: {row['new_type']} ({row['Type']})\"\n", + " rst_out += f\":Type: {row['new_type']} ({row['Type']})\\n\"\n", + " rst_out += f\":More info: `framework docs <{row['Original docs']}>`_\\n\"\n", "\n", " with open(env_descr_file, 'w') as file:\n", " file.write(rst_out)\n", From a76f5e05fbeb5bb26f4b7340e01983d9ae517320 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 14:24:20 +0000 Subject: [PATCH 101/113] docs: update data center descriptions --- docs/envs/Sinergym_descriptions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/envs/Sinergym_descriptions.rst b/docs/envs/Sinergym_descriptions.rst index 33d9307f..3dac008c 100644 --- a/docs/envs/Sinergym_descriptions.rst +++ b/docs/envs/Sinergym_descriptions.rst @@ -122,7 +122,7 @@ ``Eplus-datacenter-discrete-v1`` """""""""""""""""""""""""""""""" -:Type: industry (|industry|) +:Type: data center (|industry|) :More info: `framework docs `_ @@ -131,7 +131,7 @@ ``Eplus-datacenter-continuous-v1`` """""""""""""""""""""""""""""""""" -:Type: industry (|industry|) +:Type: data center (|industry|) :More info: `framework docs `_ @@ -140,7 +140,7 @@ ``Eplus-datacenter-discrete-stochastic-v1`` """"""""""""""""""""""""""""""""""""""""""" -:Type: industry (|industry|) +:Type: data center (|industry|) :More info: `framework docs `_ @@ -149,7 +149,7 @@ ``Eplus-datacenter-continuous-stochastic-v1`` """"""""""""""""""""""""""""""""""""""""""""" -:Type: industry (|industry|) +:Type: data center (|industry|) :More info: `framework docs `_ From e9c9f73d1188d49113dfa6a3cb94e3142a47d4b3 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 14:24:38 +0000 Subject: [PATCH 102/113] docs: change data center naming --- notebooks/utils/nb001_create_envs_table.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/notebooks/utils/nb001_create_envs_table.ipynb b/notebooks/utils/nb001_create_envs_table.ipynb index 5c5072cf..0e4eaad0 100644 --- a/notebooks/utils/nb001_create_envs_table.ipynb +++ b/notebooks/utils/nb001_create_envs_table.ipynb @@ -47,7 +47,7 @@ " elif house_type == \"office\":\n", " return \"office building\"\n", " elif house_type == \"industrial\":\n", - " return \"industry\"\n", + " return \"data center\"\n", " return \"data center\"\n", "\n", "envs['Type'] = envs.apply(lambda row: emojify(row), axis=1)\n", From e6689b198173ebe664bb200be0b2cd64d2c3c510 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:05:02 +0000 Subject: [PATCH 103/113] feat: improve support for custom agents --- beobench/experiment/scheduler.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index 1ba7a233..c0c0052c 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -5,6 +5,7 @@ import subprocess import pathlib import warnings +import yaml from typing import Union # RLlib integration is only available with extended extras. @@ -25,7 +26,7 @@ def run( agent_file: str = None, method: str = None, env: str = None, - local_dir: str = "./beobench_results/ray_results", + local_dir: str = "./beobench_results", wandb_project: str = "", wandb_entity: str = "", wandb_api_key: str = "", @@ -84,7 +85,7 @@ def run( # Create a definition of experiment from inputs if experiment_file is not None: warnings.warn( - "The experiment_file argmunet has been replaced by config", + "The experiment_file argmunent has been replaced by config", DeprecationWarning, ) if agent_file is not None: @@ -116,16 +117,28 @@ def run( ) else: # run custom RL agent - args = ["python -m", f"/tmp/beobench/{agent_file.name}"] + args = ["python", f"/tmp/beobench/{agent_file.name}"] subprocess.check_call(args) else: # build and run experiments in docker container + docker_flags = [] # Ensure local_dir exists, and create otherwise local_dir_path = pathlib.Path(local_dir) local_dir_path.mkdir(parents=True, exist_ok=True) - local_dir_abs = str(local_dir_path.absolute()) + ray_path_abs = str((local_dir_path / "ray_results").absolute()) + + # Save config to local dir and add mount flag for config + config_path = local_dir_path / "tmp" / "config.yaml" + config_path.parent.mkdir(parents=True, exist_ok=True) + config_path_abs = config_path.absolute() + with open(config_path, "w", encoding="utf-8") as conf_file: + yaml.dump(config, conf_file) + docker_flags += [ + "-v", + f"{config_path_abs}:/tmp/beobench/config.yaml:ro", + ] # docker setup image_tag = beobench.experiment.containers.build_experiment_container( @@ -137,7 +150,6 @@ def run( unique_id = uuid.uuid4().hex[:6] container_name = f"auto_beobench_experiment_{unique_id}" - docker_flags = [] if experiment_file is not None: exp_file_abs = experiment_file.absolute() exp_file_on_docker = f"/tmp/beobench/{experiment_file.name}" @@ -221,7 +233,7 @@ def run( "run", # mount experiment data dir "-v", - f"{local_dir_abs}:/root/ray_results", + f"{ray_path_abs}:/root/ray_results", # automatically remove container when stopped/exited "--rm", # add more memory From 580eac457eee344d187c5bc26d85366a91cc347a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:07:06 +0000 Subject: [PATCH 104/113] aux: add random agent to repo --- beobench/data/agents/random_agent.py | 17 +++++++++++++++ beobench/data/configs/rewex01_test01.yaml | 25 +++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 beobench/data/agents/random_agent.py create mode 100644 beobench/data/configs/rewex01_test01.yaml diff --git a/beobench/data/agents/random_agent.py b/beobench/data/agents/random_agent.py new file mode 100644 index 00000000..f3189259 --- /dev/null +++ b/beobench/data/agents/random_agent.py @@ -0,0 +1,17 @@ +"""Random agent for testing beobench experiment containers""" + +import beobench.experiment.provider + +print("Random agent: creating env.") +env = beobench.experiment.provider.create_env() +print("Random agent: resetting env.") +observation = env.reset() +for _ in range(10): + print("Random agent: taking action.") + action = env.action_space.sample() + print(action) + observation, reward, done, info = env.step(action) + if done: + observation = env.reset() +env.close() +print("Random agent: completed test.") diff --git a/beobench/data/configs/rewex01_test01.yaml b/beobench/data/configs/rewex01_test01.yaml new file mode 100644 index 00000000..7ac157e3 --- /dev/null +++ b/beobench/data/configs/rewex01_test01.yaml @@ -0,0 +1,25 @@ +# REWEX Experiment 01 +# Run with the command +# beobench run -c beobench/data/configs/rewex01_test01.yaml -d . --use-gpu --docker-shm-size 28gb + +# agent config +agent: + origin: beobench/data/agents/random_agent.py # either path to agent script or name of agent library (rllib) +# environment config +env: + name: Apartments2Thermal-v0 + gym: energym + config: + # Number of simulation days + days: 365 + # Name of energym environment + energym_environment: Apartments2Thermal-v0 + gym_kwargs: + # Maximum number of timesteps in one episode + max_episode_length: 35040 # corresponds to a year of 15 min steps + # User-provided flag to require state and action spaces to be normalized + normalize: true + # Number of real-world minutes between timesteps in building simulation + step_period: 15 + # Weather file to use for the scenario (possible files depend on env chosen) + weather: ESP_CT_Barcelona \ No newline at end of file From 51b3fdaf3af1a226c9818c9fc11167d436b4a49a Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:12:06 +0000 Subject: [PATCH 105/113] feat: add provider module --- beobench/data/configs/rewex01.yaml | 43 ++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 beobench/data/configs/rewex01.yaml diff --git a/beobench/data/configs/rewex01.yaml b/beobench/data/configs/rewex01.yaml new file mode 100644 index 00000000..6b433602 --- /dev/null +++ b/beobench/data/configs/rewex01.yaml @@ -0,0 +1,43 @@ +# REWEX Experiment 01 +# Run with the command +# beobench run -c beobench/experiment/definitions/rewex01.yaml -d . --use-gpu --docker-shm-size 28gb + +# agent config +agent: + origin: rllib # either path to agent script or name of agent library (rllib) + config: # given to ray.tune.run() as arguments (since rllib set before) + run_or_experiment: PPO + stop: + timesteps_total: 400000 + config: + lr: 0.005 + model: + fcnet_activation: relu + fcnet_hiddens: [256,256,256,256] + post_fcnet_activation: tanh + batch_mode: complete_episodes + gamma: 0.999 + horizon: 1000 + metrics_smoothing_episodes: 5 + framework: torch + log_level: "WARNING" + num_workers: 1 # this is required for energym to work (can fail silently otherwise) + num_gpus: 1 +# environment config +env: + name: Apartments2Thermal-v0 + gym: energym + config: + # Number of simulation days + days: 365 + # Name of energym environment + energym_environment: Apartments2Thermal-v0 + gym_kwargs: + # Maximum number of timesteps in one episode + max_episode_length: 35040 # corresponds to a year of 15 min steps + # User-provided flag to require state and action spaces to be normalized + normalize: true + # Number of real-world minutes between timesteps in building simulation + step_period: 15 + # Weather file to use for the scenario (possible files depend on env chosen) + weather: ESP_CT_Barcelona \ No newline at end of file From 77930fad4b02e7452b212b77ecb6a357381f112e Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:12:17 +0000 Subject: [PATCH 106/113] docs: minor fixes --- docs/guides/intro_experiment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/intro_experiment.rst b/docs/guides/intro_experiment.rst index 14227f80..1858b00c 100644 --- a/docs/guides/intro_experiment.rst +++ b/docs/guides/intro_experiment.rst @@ -22,7 +22,7 @@ Beobench experiments are configured either using a *Python dictionary* or an equ -Given this configuration file ``example.yaml``, we can the experiment using the following commands: +Given this configuration file ``example.yaml``, we can run the experiment using the following commands: .. include:: ../snippets/run_standard_experiment.rst From a6621bf83d0e8cf5050859d688dc2eee13192fd8 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:15:41 +0000 Subject: [PATCH 107/113] aux: simplify provider module --- beobench/experiment/provider.py | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 beobench/experiment/provider.py diff --git a/beobench/experiment/provider.py b/beobench/experiment/provider.py new file mode 100644 index 00000000..1bcb1102 --- /dev/null +++ b/beobench/experiment/provider.py @@ -0,0 +1,36 @@ +""" The experiment provider provides access to environments inside containers.""" + +import beobench.experiment.config_parser + +try: + import env_creator # pylint: disable=import-outside-toplevel,import-error +except ImportError as e: + raise ImportError( + ( + "Cannot import env_creator module. Is Beobench being executed" + "inside beobench experiment container?" + ) + ) from e + +config = beobench.experiment.config_parser.parse("/tmp/beobench/config.yaml") + + +def create_env(env_config: dict = None) -> object: + """Create environment. + + Create environment from Beobench integration currently being used. + This only works INSIDE a beobench experiment container. + + Args: + env_config (dict, optional): env configuration. Defaults to None. + + Returns: + object: environment instance + """ + + # Access env_creator script that is only available inside + # experiment container. + if env_config is None: + env_config = config["env"]["config"] + + return env_creator.create_env(env_config) From 5536a36c231383eaa8f2588534b1880db25b39fd Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:31:45 +0000 Subject: [PATCH 108/113] aux: update setup.py to separate rllib and other exp container deps --- setup.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/setup.py b/setup.py index b80bd49d..2bce94c0 100644 --- a/setup.py +++ b/setup.py @@ -19,11 +19,13 @@ ] # The extended requirements are only used inside experiment/gym containers -extended_requirements = [ +extended_requirements = [] + +rllib_requirements = [ "ray[rllib]", - "wandb", "torch", "gym", + "wandb", ] setup( @@ -43,6 +45,7 @@ install_requires=requirements, extras_require={ "extended": extended_requirements, + "rllib": rllib_requirements, }, license="MIT license", long_description=readme + "\n\n" + history, From 28a7f731874064fe6d56b5c5b847f3c994e2a659 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:32:45 +0000 Subject: [PATCH 109/113] feat: enable changing the extras installations in dockerfile of exp image --- beobench/experiment/dockerfiles/Dockerfile.experiment | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/beobench/experiment/dockerfiles/Dockerfile.experiment b/beobench/experiment/dockerfiles/Dockerfile.experiment index 5394c7e7..145373a0 100644 --- a/beobench/experiment/dockerfiles/Dockerfile.experiment +++ b/beobench/experiment/dockerfiles/Dockerfile.experiment @@ -2,7 +2,8 @@ ARG GYM_IMAGE FROM ${GYM_IMAGE} # install beobench -RUN pip3 --disable-pip-version-check --no-cache-dir install git+https://github.com/rdnfn/beobench +ARG EXTRAS="extended, rllib" +RUN pip3 --disable-pip-version-check --no-cache-dir install "beobench[${EXTRAS}]" # add env creator COPY env_creator.py /opt/beobench/experiment_setup/ From 329b80e4415cbf338b711b7f219e6ded89e5c8ec Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:44:47 +0000 Subject: [PATCH 110/113] feat: remove rllib deps from exp images that don't need it --- beobench/experiment/containers.py | 10 ++++++++++ beobench/experiment/scheduler.py | 19 ++++++++++++------- 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/beobench/experiment/containers.py b/beobench/experiment/containers.py index 6f86a833..d9d50180 100644 --- a/beobench/experiment/containers.py +++ b/beobench/experiment/containers.py @@ -17,6 +17,7 @@ def build_experiment_container( build_context: str, use_no_cache: bool = False, version="latest", + enable_rllib=False, ) -> None: """Build experiment container from beobench/integrations/boptest/Dockerfile. @@ -87,6 +88,13 @@ def build_experiment_container( "Dockerfile.experiment" ) ) + + # Which extras to install beobench container + # e.g. using pip install beobench[extras] + if enable_rllib: + beobench_extras = '"extended,rllib"' + else: + beobench_extras = "extended" # Load dockerfile into pipe with subprocess.Popen(["cat", complete_dockerfile], stdout=subprocess.PIPE) as proc: beobench_build_args = [ @@ -98,6 +106,8 @@ def build_experiment_container( "-", "--build-arg", f"GYM_IMAGE={base_image_tag}", + "--build-arg", + f"EXTRAS={beobench_extras}", *flags, build_context, ] diff --git a/beobench/experiment/scheduler.py b/beobench/experiment/scheduler.py index c0c0052c..50d28364 100644 --- a/beobench/experiment/scheduler.py +++ b/beobench/experiment/scheduler.py @@ -1,5 +1,6 @@ """Module to schedule experiments.""" +from cgitb import enable import os import uuid import subprocess @@ -122,6 +123,16 @@ def run( else: # build and run experiments in docker container + + ### part 1: build docker images + enable_rllib = config["agent"]["origin"] == "rllib" + image_tag = beobench.experiment.containers.build_experiment_container( + build_context=config["env"]["gym"], + use_no_cache=use_no_cache, + enable_rllib=enable_rllib, + ) + + ### part 2: create args and run command in docker container docker_flags = [] # Ensure local_dir exists, and create otherwise @@ -140,13 +151,7 @@ def run( f"{config_path_abs}:/tmp/beobench/config.yaml:ro", ] - # docker setup - image_tag = beobench.experiment.containers.build_experiment_container( - build_context=config["env"]["gym"], - use_no_cache=use_no_cache, - ) - - # define docker arguments/options/flags + # define more docker arguments/options/flags unique_id = uuid.uuid4().hex[:6] container_name = f"auto_beobench_experiment_{unique_id}" From 76415fa0485904431bf205b636b659d85af39934 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 17:49:18 +0000 Subject: [PATCH 111/113] docs: update contributors --- AUTHORS.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index 95414258..2b9b1eda 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,8 +1,4 @@ -Contributors ------------- +Code Contributors +----------------- * Arduin Findeis (https://github.com/rdnfn) * Scott Jeen (https://github.com/enjeeneer) - - - - From 3ce08eb17050267de3f1b55add6c4972c00bdc73 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 18:03:24 +0000 Subject: [PATCH 112/113] docs: update history prior to version change --- HISTORY.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/HISTORY.rst b/HISTORY.rst index ba257106..6819a2d0 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,12 +2,17 @@ History ======= -0.3.1 (2022-00-00) +0.4.0 (2022-03-28) ------------------ * Make dependencies that are only used inside experiment/gym containers optional (for all dependencies install via ``pip install beobench[extended]``) * Add two part experiment image build process so that there is shared beobench installation dockerfile -* Add support for yaml config files +* Add support for yaml config files (!) +* Overhaul of documentation, including new envs page and new theme +* Enable RLlib free experiment containers when not required +* Add beobench_contrib as submodule +* Simplify Pypi readme file +* Remove GPU requirement for devcontainer 0.3.0 (2022-02-14) ------------------ From 5869c49a77412a636eee0ca28687edeedd5f7137 Mon Sep 17 00:00:00 2001 From: rdnfn <75615911+rdnfn@users.noreply.github.com> Date: Mon, 28 Mar 2022 18:04:10 +0000 Subject: [PATCH 113/113] =?UTF-8?q?Bump=20version:=200.3.0=20=E2=86=92=200?= =?UTF-8?q?.4.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- beobench/__init__.py | 2 +- setup.cfg | 2 +- setup.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/beobench/__init__.py b/beobench/__init__.py index 635554e2..1ac5307a 100644 --- a/beobench/__init__.py +++ b/beobench/__init__.py @@ -2,7 +2,7 @@ __author__ = """rdnfn""" __email__ = "-" -__version__ = "0.3.0" +__version__ = "0.4.0" from beobench.utils import restart from beobench.experiment.scheduler import run diff --git a/setup.cfg b/setup.cfg index 48467b0f..d798603a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.3.0 +current_version = 0.4.0 commit = True tag = True diff --git a/setup.py b/setup.py index 2bce94c0..53fe9b53 100644 --- a/setup.py +++ b/setup.py @@ -10,7 +10,7 @@ with open("HISTORY.rst", encoding="UTF-8") as history_file: history = history_file.read() -version = "0.3.0" # pylint: disable=invalid-name +version = "0.4.0" # pylint: disable=invalid-name requirements = [ "docker",