Merge pull request #56 from rdnfn/dev/general

v0.4.2

Author: rdnfn

.devcontainer/devcontainer.json

@@ -45,7 +45,10 @@
 		"editor.formatOnSave": true,
 		"editor.rulers": [
 			88
-		]
+		],
+		"python.terminal.activateEnvInCurrentTerminal": true,
+		"esbonio.server.enabled": false,
+		"esbonio.sphinx.confDir": "${workspaceFolder}/docs"
 	},
 	// Add the IDs of extensions you want installed when the container is created.
 	"extensions": [

.gitignore

@@ -118,4 +118,5 @@ docs/generated/
 
 #beobench
 beobench_results*
-notebooks/archive
+notebooks/archive
+*beo.yaml

.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.7"
+    python: "3.9"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CONTRIBUTING.rst

@@ -82,15 +82,31 @@ Ready to contribute? Here's how to set up `beobench` for local development.
 
 5. Submit a pull request through the GitHub website.
 
-Pull Request Guidelines
------------------------
+Guidelines
+----------
+
+Commit messages
+~~~~~~~~~~~~~~~
+
+When committing to the Beobench repo, please try to follow `this style
+guide by Udacity <https://udacity.github.io/git-styleguide/>`_ for the
+commit messages with the following adaptions:
+
+1. Replace the ``chore:`` type with ``aux:``.
+2. Use a ``exp:`` type for commits relating to experiment data (e.g. experiment config files).
+
+
+Pull Requests
+~~~~~~~~~~~~~
 
 Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include tests.
 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.
 
 .. Check https://travis-ci.com/rdnfn/beobench/pull_requests
@@ -104,6 +120,15 @@ To run a subset of tests::
 
     $ python -m unittest tests.test_beobench
 
+
+Resources
+---------
+
+Documentation and cheatsheets for reStructuredText (``.rst`` files):
+
+* https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+* https://bashtage.github.io/sphinx-material/rst-cheatsheet/rst-cheatsheet.html
+
 Deploying
 ---------
 

HISTORY.rst

@@ -2,19 +2,35 @@
 History
 =======
 
+0.4.2 (2022-04-04)
+------------------
+
+* Feature: defining all relevant options/kwargs of CLI an API is now supported
+  yaml files (#54)
+* Feature: allow multiple configs to be given to both CLI
+  (giving multiple ``-c`` options) and Python API (as a list) (#51)
+* Fix: adapted Energym env reset() method to avoid triggering
+  long warm-up times with additional simulation runs (#43)
+* Fix: enable container build even if prior build failed midway
+  and left artifacts
+
 0.4.1 (2022-03-30)
 ------------------
 
 * Feature: enable package extras to be given in development mode
-* Feature: add support for arm64/aarch64-based development by forcing experiment containers to run as amd64 containers on those systems (#32)
+* Feature: add support for arm64/aarch64-based development by forcing
+  experiment containers to run as amd64 containers on those systems (#32)
 * Fix: add gym to extended package requirements
 
 
 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
+* 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 (!)
 * Overhaul of documentation, including new envs page and new theme
 * Enable RLlib free experiment containers when not required
@@ -25,7 +41,8 @@ History
 0.3.0 (2022-02-14)
 ------------------
 
-* Add complete redesign of CLI: main command changed from ``python -m beobench.experiment.scheduler`` to ``beobench run``.
+* Add complete redesign of CLI: main command changed from
+  ``python -m beobench.experiment.scheduler`` to ``beobench run``.
 * Add support for energym environments
 * Add support for MLflow experiment tracking
 * Add support for custom agents
@@ -41,7 +58,8 @@ History
 0.2.0 (2022-01-18)
 ------------------
 
-* Enable adding custom environments to beobench with *docker build context*-based syntax
+* Enable adding custom environments to beobench with
+  *docker build context*-based syntax
 * Save experiment results on host machine
 * Major improvements to documentation
 * Remove unnecessary wandb arguments in main CLI

beobench/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """rdnfn"""
 __email__ = "-"
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 from beobench.utils import restart
 from beobench.experiment.scheduler import run

beobench/cli.py

@@ -1,7 +1,6 @@
 """Command line interface for beobench."""
 
 import click
-import ast
 
 import beobench.experiment.scheduler
 import beobench.utils
@@ -19,48 +18,37 @@ def cli():
     default=None,
     help="Json or filepath with yaml that defines beobench experiment configuration.",
     type=str,
-)
-@click.option(
-    "--experiment-file",
-    default=None,
-    help="File that defines beobench experiment.",
-    type=click.Path(exists=True, file_okay=True, dir_okay=False),
-)
-@click.option(
-    "--agent-file",
-    default=None,
-    help="File that defines custom agent.",
-    type=click.Path(exists=True, file_okay=True, dir_okay=False),
+    multiple=True,
 )
 @click.option(
     "--method",
-    default="",
+    default=None,
     help="Name of RL method to use in experiment.",
 )
 @click.option(
     "--env",
-    default="",
+    default=None,
     help="Name of RL environment to use in experiment.",
 )
 @click.option(
     "--local-dir",
-    default="./beobench_results",
+    default=None,
     help="Local directory to write results to.",
     type=click.Path(exists=False, file_okay=False, dir_okay=True),
 )
 @click.option(
     "--wandb-project",
-    default="",
+    default=None,
     help="Weights and biases project name to log runs to.",
 )
 @click.option(
     "--wandb-entity",
-    default="",
+    default=None,
     help="Weights and biases entity name to log runs under.",
 )
 @click.option(
     "--wandb-api-key",
-    default="",
+    default=None,
     help="Weights and biases API key.",
 )
 @click.option(
@@ -75,7 +63,7 @@ def cli():
 )
 @click.option(
     "--docker-shm-size",
-    default="2gb",
+    default=None,
     help="Size of shared memory available to experiment container.",
 )
 @click.option(
@@ -96,8 +84,6 @@ def cli():
 )
 def run(
     config: str,
-    experiment_file: str,
-    agent_file: str,
     method: str,
     env: str,
     local_dir: str,
@@ -121,14 +107,8 @@ def run(
     #
     # See https://stackoverflow.com/a/40094408.
 
-    # Parse config str to dict if
-    if config and config[0] == "{":
-        config = ast.literal_eval(config)
-
     beobench.experiment.scheduler.run(
-        config=config,
-        experiment_file=experiment_file,
-        agent_file=agent_file,
+        config=list(config),
         method=method,
         env=env,
         local_dir=local_dir,

beobench/data/configs/rewex02.yaml

@@ -0,0 +1,52 @@
+# REWEX Experiment 02
+# Run with the command
+# beobench run -c beobench/data/configs/rewex01_test02.yaml -d .[extended] --use-gpu --docker-shm-size 28gb
+
+# Some of the descriptions of RLlib config values are taken from
+# https://docs.ray.io/en/latest/rllib/rllib-training.html
+
+# 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: 35040
+    config:
+      lr: 0.0005
+      model:
+        fcnet_activation: relu
+        fcnet_hiddens: [256,256,256,256]
+        post_fcnet_activation: tanh
+      batch_mode: complete_episodes
+      gamma: 0.999
+      # Number of steps after which the episode is forced to terminate. Defaults
+      # to `env.spec.max_episode_steps` (if present) for Gym envs.
+      horizon: 96
+      # Calculate rewards but don't reset the environment when the horizon is
+      # hit. This allows value estimation and RNN state to span across logical
+      # episodes denoted by horizon. This only has an effect if horizon != inf.
+      soft_horizon: True
+      # Number of timesteps collected for each SGD round. This defines the size
+      # of each SGD epoch.
+      train_batch_size: 94 # single day of 15min steps
+      # Total SGD batch size across all devices for SGD. This defines the
+      # minibatch size within each epoch.
+      sgd_minibatch_size: 24
+      metrics_smoothing_episodes: 1
+      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: 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

beobench/data/sweeps/sweep01.yaml

@@ -0,0 +1,13 @@
+program: beobench
+method: grid
+command:
+- ${program}
+- run
+- ${args}
+parameters:
+  config:
+    value:
+      - ./beobench/data/configs/rewex01.yaml
+      - ./wandb.beo.yaml
+  dev-path:
+    value: .

beobench/experiment/config_parser.py

@@ -3,38 +3,64 @@
 from typing import Union
 import pathlib
 import yaml
+import ast
+import sys
 
-# To enable compatiblity with Python<=3.6 (e.g. for sinergym dockerfile)
-try:
+import beobench.utils
+
+# To enable compatiblity with Python<=3.8 (e.g. for sinergym dockerfile)
+if sys.version_info[1] >= 9:
     import importlib.resources
-except ImportError:
+else:
     import importlib_resources
     import importlib
 
     importlib.resources = importlib_resources
 
 
-def parse(config: Union[str, pathlib.Path]) -> dict:
-    """Parse experiment config from yaml file to dict.
+def parse(config: Union[dict, str, pathlib.Path, list]) -> dict:
+    """Parse experiment config to dict.
 
     Args:
-        config (Union[str, pathlib.Path]): path of yaml file
+        config (Union[dict, str, pathlib.Path, list]): path of yaml file
 
     Returns:
         dict: config in dictionary
     """
-
-    # 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)
+    if isinstance(config, list):
+        # get list of config dicts
+        parsed_configs = []
+        for single_config in config:
+            parsed_configs.append(parse(single_config))
+
+        # merge config dicts
+        parsed_config = {}
+        for conf in parsed_configs:
+            parsed_config = beobench.utils.merge_dicts(parsed_config, conf)
+
+    elif isinstance(config, pathlib.Path):
+        # load config yaml to dict if path given
         with open(config, "r", encoding="utf-8") as config_file:
-            config_dict = yaml.safe_load(config_file)
+            parsed_config = yaml.safe_load(config_file)
+
+    elif isinstance(config, str):
+        if config[0] in ["{", "["]:
+            # if json str or list
+            parsed_config = parse(ast.literal_eval(config))
+        else:
+            # make sure config is a real path
+            config_path = pathlib.Path(config)
+            parsed_config = parse(config_path)
+
+    elif isinstance(config, dict):
+        parsed_config = config
+
     else:
-        config_dict = config
+        raise ValueError(
+            f"Config not one of allowed types (dict, str, pathlib.Path, list): {config}"
+        )
 
-    return config_dict
+    return parsed_config
 
 
 def create_rllib_config(config: dict) -> dict: