Merge pull request #2 from rdnfn/docs

Docs

.gitignore

@@ -113,4 +113,5 @@ tmp/
 wandb/
 
 # Nohup
-*nohup.out
+*nohup.out
+docs/generated/

MANIFEST.in

@@ -3,6 +3,7 @@ include CONTRIBUTING.rst
 include HISTORY.rst
 include LICENSE
 include README.rst
+include PYPI_README.rst
 
 recursive-include tests *
 recursive-exclude * __pycache__

PYPI_README.rst

@@ -0,0 +1,49 @@
+.. image:: ./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 does not replace existing libraries defining BEO problems (such as `BOPTEST <https://github.com/ibpsa/project1-boptest>`_) — instead it makes working with them easier.
+
+Features
+--------
+
+- *Wide range of RL algorithms:* test the most common RL algorithms on BEO problems without re-implementing by using beobench's `Ray RLlib <https://github.com/ray-project/ray/tree/master/rllib>`_ integration.
+- *Experiment logging:* log experiment results in a reproducible and sharable manner via `Weights and Biases`_.
+- *Hyperparameter tuning:* easily tune hyperparameters using the extensive `Ray Tune syntax <https://docs.ray.io/en/master/tune/index.html>`_.
+- *Installers:* avoid having to manage messy Python namespaces yourself — just install beobench via pip and use its pre-configured docker containers to take care of managing other BEO packages and their dependencies.
+
+.. _Weights and Biases: https://wandb.ai/
+
+.. end-in-sphinx-docs
+
+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

beobench/constants.py

@@ -1,4 +1,4 @@
-"""Various configuration constants"""
+"""Module with various configuration constants"""
 
 import pathlib
 
@@ -17,4 +17,8 @@
     "flask-restful==0.3.9",
     "pandas==1.3.4",
     "flask_cors==3.0.10",
+    (
+        "boptest_gym@git+"
+        "https://github.com/rdnfn/project1-boptest-gym.git@rdnfn/feature-packaging"
+    ),
 ]

beobench/core.py

@@ -1,4 +1,4 @@
-"""Core functions of beobench."""
+"""Module with core functions of beobench."""
 import gym
 
 

beobench/experiment/__init__.py

@@ -0,0 +1 @@
+"""Subpackage with tools to run experiments"""

beobench/experiment/definitions/__init__.py

@@ -0,0 +1 @@
+"""Subpackage with different experiment definitions"""

beobench/experiment/definitions/default.py

@@ -3,7 +3,6 @@
 import ray.tune
 
 import beobench.integrations.boptest
-import beobench.utils
 
 PROBLEM_001_BOPTEST_HEATPUMP = {
     "name": "problem_001",

beobench/installer.py

@@ -1,4 +1,4 @@
-"""Installer for the different problem defining gym libraries"""
+"""Module to install different problem defining gym libraries"""
 
 # For python 3.7
 from __future__ import annotations

beobench/integrations/__init__.py

@@ -0,0 +1 @@
+"""Subpackage for integrations with other tools"""

docs/api.rst

@@ -0,0 +1,13 @@
+API
+===
+
+.. autosummary::
+    :toctree: generated
+    :recursive:
+
+    beobench.core
+    beobench.constants
+    beobench.experiment
+    beobench.installer
+    beobench.integrations
+    beobench.utils

docs/conf.py

@@ -33,7 +33,11 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.rst

@@ -1,5 +1,5 @@
-Welcome to beobench's documentation!
-======================================
+Home - Beobench Documentation
+=============================
 
 .. include:: ../README.rst
    :start-after: start-in-sphinx-docs
@@ -11,9 +11,10 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   index
    installation
    usage
-   modules
+   api
    contributing
    authors
    history

docs/usage.rst

@@ -2,6 +2,42 @@
 Usage
 =====
 
-To use beobench in a project::
+Running experiments
+-------------------
 
-    import beobench
+Basic 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()`` method. 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``:
+
+
+
+.. include:: ../beobench/experiment/definitions/default.py
+    :start-line: 2
+    :code: python
+
+
+
+Given this configuration file ``example_experiment_def.py``, we can the experiment using the following console command:
+
+.. code-block:: console
+
+    $ python -m beobench.experiment.scheduler --experiment-file example_experiment_def.py
+
+
+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 <https://docs.ray.io/en/master/tune/api_docs/search_space.html>`_. 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 <https://docs.ray.io/en/master/tune/api_docs/search_space.html#random-distributions-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 <https://docs.ray.io/en/master/tune/api_docs/search_space.html>`_ for a more complete description of the functionality.

pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

setup.py

@@ -4,7 +4,7 @@
 
 from setuptools import setup, find_packages
 
-with open("README.rst", encoding="UTF-8") as readme_file:
+with open("PYPI_README.rst", encoding="UTF-8") as readme_file:
     readme = readme_file.read()
 
 with open("HISTORY.rst", encoding="UTF-8") as history_file:
@@ -17,10 +17,6 @@
     "click",
     "torch",
     "gym",
-    (
-        "boptest_gym@git+"
-        "https://github.com/rdnfn/project1-boptest-gym.git@rdnfn/feature-packaging"
-    ),
 ]