Merge pull request #4 from automl/dev/jan

Merge Dev/jan into experimental

Author: vonHartz

.github/workflows/gh-test.yml

@@ -0,0 +1,53 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Test
+
+on:
+  push:
+    branches: [ master, dev/jan ]
+  pull_request:
+    branches: [ master, dev/jan ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.6
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 pytest pytest-cov setuptools numpy
+        pip install -e .[extras_disc]
+        pip install ray[rllib,debug]==0.7.3
+        pip install tensorflow==1.13.0rc1
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings.
+        flake8 . --count --exit-zero --statistics
+    - name: Test with pytest
+      run: |
+        pytest tests
+    - name: Cov report
+      run: |
+        pytest --cov=./ --cov-report=xml tests
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v1
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml
+        directory: ./coverage/reports/
+        flags: unittests
+        env_vars: OS,PYTHON
+        name: codecov-umbrella
+        fail_ci_if_error: true
+        path_to_write_report: ./coverage/codecov_report.txt
+        verbose: true

.github/workflows/install-from-pypi.yml

@@ -0,0 +1,31 @@
+name: Test PyPI Installation
+
+on:
+  push:
+    branches: [ master, dev/jan ]
+  pull_request:
+    branches: [ master, dev/jan ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.6
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install tensorflow==2.2.0
+        wget 'https://ray-wheels.s3-us-west-2.amazonaws.com/master/8d0c1b5e068853bf748f72b1e60ec99d240932c6/ray-0.9.0.dev0-cp36-cp36m-manylinux1_x86_64.whl'
+        pip install ray-0.9.0.dev0-cp36-cp36m-manylinux1_x86_64.whl[rllib,debug]
+    - name: Install from PyPI
+      run: |
+        pip install -i https://test.pypi.org/pypi/ --extra-index-url https://pypi.org/simple mdp-playground
+    - name: Basic functionality test
+      run: |
+        run-mdpp-experiments --help

.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Build and Publish
+
+on:
+  release:
+    types:
+      - created  # see https://docs.github.com/en/rest/reference/repos#create-a-release and https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.6"
+      - name: Install Poetry
+        run: |
+          curl -fsS -o get-poetry.py https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py
+          python get-poetry.py -y
+          echo "$HOME/.poetry/bin" >> $GITHUB_PATH
+      - name: Configure poetry
+        run: poetry config virtualenvs.in-project true
+      - name: Set up cache
+        uses: actions/cache@v1
+        id: cache
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
+      - name: Ensure cache is healthy
+        if: steps.cache.outputs.cache-hit == 'true'
+        run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
+      - name: Install dependencies
+        run: poetry install --no-interaction
+      - name: Publish
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          poetry config pypi-token.pypi $PYPI_TOKEN
+          poetry publish --build -r pypi

.gitignore

@@ -67,9 +67,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Developer Installation
+
+For development, manual installation is the easiest way to stay up-to-date:
+```bash
+pip install -e .[extras]
+```
+
+In addition to the standard dependencies, please install the following:
+```bash
+pip install sphinx, sphinx-book-theme  # for generating documentation
+pip install pytest-cov  # for coverage report
+# install poetry for packaging and publishing to PyPI
+curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+```
+
+## Packaging
+
+The `pyproject.toml` is set up using `poetry`.
+
+Build via `poetry build`, and publish via `poetry publish`. There are automatic workflows in place to build and publish on new package revisions.
+
+To enable manual installation with `poetry`, we also include a `setup.py` which needs to be kept up-to-date.
+
+
+## Docs
+
+The documentation can be built using sphinx via:
+```bash
+cd docs
+make html
+```
+
+To clean up:
+```bash
+make clean
+rm -rf _autosummary  # optional
+```
+
+To publish:
+```bash
+git subtree push --prefix docs/_build/html/ origin gh-pages
+```

README.md

@@ -1,3 +1,23 @@
+<p align="center">
+
+<a href="https://github.com/automl/mdp-playground/actions/workflows/gh-test.yml" target="_blank">
+    <img src="https://github.com/automl/mdp-playground/actions/workflows/gh-test.yml/badge.svg" alt="Test">
+</a>
+<a href="https://github.com/automl/mdp-playground/actions/workflows/publish.yml" target="_blank">
+    <img src="https://github.com/automl/mdp-playground/actions/workflows/publish.yml/badge.svg" alt="Publish">
+</a>
+<a href="https://codecov.io/gh/automl/mdp-playground" target="_blank">
+    <img src="https://img.shields.io/codecov/c/github/automl/mdp-playground?color=%2334D058" alt="Coverage">
+</a>
+<a href="https://pypi.org/project/mdp-playground/" target="_blank">
+    <img src="https://img.shields.io/pypi/v/mdp-playground?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+<a href="https://pypi.org/project/mdp-playground/" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/mdp-playground.svg" alt="Python Versions">
+</a>
+</p>
+
+
 # MDP Playground
 A python package to inject low-level dimensions of difficulties in RL environments. There are toy environments to design and debug RL agents. And complex environment wrappers for Atari and Mujoco to test robustness to these dimensions in complex environments.
 
@@ -12,18 +32,36 @@ There are 4 parts to the package:
 4) **Analysis**: [`plot_experiments.ipynb`](plot_experiments.ipynb) contains code to plot the standard plots from the paper.
 
 ## Installation
+
+### Production use
+We recommend using `conda` to manage environments. After setup of the environment, you can install MDP Playground in two ways:
+#### Manual
+To install MDP Playground manually, clone the repository and run:
+```bash
+pip install -e .[extras]
+```
+This might be the preferred way if you want easy access to the included experiments.
+
+#### From PyPI
+MDP Playground is also on PyPI. Just run:
+```bash
+pip install mdp_playground[extras]
+```
+
+
+### Reproducing results from the paper
 We recommend using `conda` environments to manage virtual `Python` environments to run the experiments. Unfortunately, you will have to maintain 2 environments - 1 for the "older" **discrete toy** experiments and 1 for the "newer" **continuous and complex** experiments from the paper. As mentioned in Appendix P in the paper, this is because of issues with Ray, the library that we used for our baseline agents.
 
 Please follow the following commands to install for the discrete toy experiments:
-```
+```bash
 conda create -n py36_toy_rl_disc_toy python=3.6
 conda activate py36_toy_rl_disc_toy
 cd mdp-playground
 pip install -e .[extras_disc]
 ```
 
 Please follow the following commands to install for the continuous and complex experiments:
-```
+```bash
 conda create -n py36_toy_rl_cont_comp python=3.6
 conda activate py36_toy_rl_cont_comp
 cd mdp-playground
@@ -39,7 +77,7 @@ For general instructions, please continue reading.
 
 You can run experiments using:
 ```
-python run_experiments.py -c <config_file> -e <exp_name> -n <config_num>
+run-mdpp-experiments -c <config_file> -e <exp_name> -n <config_num>
 ```
 The `exp_name` is a prefix for the filenames of CSV files where stats for the experiments are recorded. The CSV stats files will be saved to the current directory.<br>
 Each of the command line arguments has defaults. Please refer to the documentation inside [`run_experiments.py`](run_experiments.py) for further details on the command line arguments. (Or run it with the `-h` flag to bring up help.)
@@ -53,7 +91,7 @@ For example, for algorithm **DQN** when varying dimensions **delay** and **seque
 
 ## Running experiments from the main paper
 We list here the commands for the experiments from the main paper:
-```
+```bash
 # Discrete toy environments:
 # Image representation experiments:
 conda activate py36_toy_rl_disc_toy

docs/_autosummary/mdp_playground.analysis.analysis.MDPP_Analysis.rst

@@ -1,4 +1,4 @@
-mdp\_playground.analysis.analysis.MDPP\_Analysis
+mdp\_playground.analysis.analysis.MDPP\_Analysis
 ================================================
 
 .. currentmodule:: mdp_playground.analysis.analysis

docs/_autosummary/mdp_playground.analysis.analysis.rst

@@ -1,4 +1,4 @@
-mdp\_playground.analysis.analysis
+mdp\_playground.analysis.analysis
 =================================
 
 .. automodule:: mdp_playground.analysis.analysis