From 7d7be3062b119a60d42d5d045ed88ecbd156c7ec Mon Sep 17 00:00:00 2001 From: Christopher Yeh Date: Thu, 2 Nov 2023 23:01:45 +0000 Subject: [PATCH] Update CONTRIBUTING and EVChargingEnv docs --- CONTRIBUTING.md | 27 ++++++++++--------- docs/evchargingenv.md | 6 +++-- env_ev.yml | 62 ++++++++++++++++++++++++++----------------- env_norl.yml | 37 -------------------------- env_rllib.yml | 40 ---------------------------- 5 files changed, 56 insertions(+), 116 deletions(-) delete mode 100755 env_norl.yml delete mode 100755 env_rllib.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25e78f0b..5d953662 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,33 @@ # Contributing code 1. Install [miniconda3](https://docs.conda.io/en/latest/miniconda.html). -2. Create conda environment. Replace `XX` below with the name of the SustainGym environment you want to work on. +2. (Optional, but recommended) If you are using a conda version `<=23.9.0`, set the conda solver to libmamba for faster dependency solving. Starting from conda version [`23.10.0`](https://github.com/conda/conda/releases/tag/23.10.0), libmamba is the default solver. ```bash - conda env update --file env_XX.yml --prune + conda config --set solver libmamba ``` - - If you are using RLLib with a GPU, you will also need to [configure TensorFlow for GPU](https://www.tensorflow.org/install/pip#4_gpu_setup): +3. Clone the SustainGym repo, and enter the `sustaingym` directory. ```bash - mkdir -p $CONDA_PREFIX/etc/conda/activate.d - echo 'CUDNN_PATH=$(dirname $(python -c "import nvidia.cudnn;print(nvidia.cudnn.__file__)"))' >> $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh - echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CONDA_PREFIX/lib/:$CUDNN_PATH/lib' >> $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh + git clone https://github.com/chrisyeh96/sustaingym.git + cd sustaingym ``` - -3. Make code modifications in a separate git branch +4. Create conda environment. Replace `XX` below with the name of the SustainGym environment you want to work on. By default, the `env_XX.yml` environment files assume that you have a NVIDIA GPU. If you do not have a NVIDIA GPU, you may need to modify the `env_XX.yml` file. + ```bash + conda env update --file env_XX.yml --prune + ``` +5. Make code modifications in a separate git branch ```bash git checkout -b new_feature ``` -4. From repo root folder, run mypy type checker and fix any errors. +6. From repo root folder, run mypy type checker and fix any errors. ```bash mypy sustaingym ``` -5. From repo root folder, run code linter and fix any linting errors. +7. From repo root folder, run code linter and fix any linting errors. ```bash flake8 sustaingym ``` -6. Commit changes in git and push. -7. Submit pull request on GitHub. +8. Commit changes in git and push. +9. Submit pull request on GitHub. ## Unit tests diff --git a/docs/evchargingenv.md b/docs/evchargingenv.md index 813d793b..f4c441cc 100644 --- a/docs/evchargingenv.md +++ b/docs/evchargingenv.md @@ -19,12 +19,14 @@ The reward function is a sum of three components: $r(t) = p(t) - c_V(t) - c_C(t) ### Installation -SustainGym is hosted on [PyPI](https://pypi.org/project/sustaingym/) and can be installed with `pip`: +SustainGym is designed for Linux machines. SustainGym is hosted on [PyPI](https://pypi.org/project/sustaingym/) and can be installed with `pip`: ```bash pip install sustaingym[ev] ``` +Specifically for `EVChargingEnv`, you also need to have a MOSEK license. You may either request a free [personal academic license](https://www.mosek.com/products/academic-licenses/), or a free 30-day [commercial trial license](https://www.mosek.com/products/trial/). The license file should be placed inside a folder called "mosek" under your home directory. Typically, that will be `~/mosek/mosek.lic`. + ### Custom RL Loop ```python @@ -48,7 +50,7 @@ while not terminated: ### Using our training script 1. Install [miniconda3](https://docs.conda.io/en/latest/miniconda-other-installer-links.html). -2. (Optional) Set the conda solver to libmamba for faster dependency solving. +2. (Optional, but recommended) Set the conda solver to libmamba for faster dependency solving. ```bash conda config --set solver libmamba ``` diff --git a/env_ev.yml b/env_ev.yml index 958aea99..6ccc5b7e 100755 --- a/env_ev.yml +++ b/env_ev.yml @@ -5,13 +5,21 @@ # conda remove --name sustaingym_ev --all # # Notes -# - the 2 main bottlenecks are acnportal and ray -# 1) acnportal v0.3.2 only supports up to Pandas 1.1, +# - ACNPortal +# - latest official release v0.3.2 only supports up to Pandas 1.1, # and Pandas 1.1 only supports up to Python 3.9 -# 2) ray[rllib]==2.7.0 only supports gymnasium 0.28.1, pettingzoo 0.24.* -# - technically, ray(2.7.0) needs Pandas >= 1.3, but we can bypass this requirement by installing -# it through pip instead of conda -# - last updated: September 27, 2023 +# - we install from the ACNPortal dev branch, which includes a fix that supports Pandas 2 +# +# - TensorFlow 2.14: +# - the GPU version only works with Python <=3.10 (see https://github.com/tensorflow/tensorflow/issues/61986) +# - TensorFlow 2.15 should fix this issue +# - Ray 2.7.1: +# - officially only supports up to Python 3.10 (see https://docs.ray.io/en/latest/ray-overview/installation.html) +# - only supports gymnasium 0.28.1 (see https://github.com/ray-project/ray/blob/ray-2.7.1/python/requirements.txt) +# - officially seems to only supports pettingzoo 1.23.1 (see https://github.com/ray-project/ray/blob/ray-2.7.1/python/requirements/ml/rllib-test-requirements.txt), +# but empirically seems to work with pettingzoo 1.24.* +# +# last updated: November 2, 2023 name: sustaingym_ev channels: - pytorch # for pytorch @@ -19,31 +27,37 @@ channels: - mosek # for mosek - conda-forge dependencies: -- python=3.9.16 -- cudatoolkit=11.8.0 # for TensorFlow 2.12 -- cvxpy=1.3.1 -- flake8=6.0.0 +- python=3.10.* +- cvxpy=1.4.* +- flake8=6.1.* - ipympl=0.9.3 # for Jupyter / VSCode notebooks - ipykernel # for Jupyter / VSCode notebooks -- matplotlib=3.7.1 -- mosek=10.0.44 +- matplotlib=3.8.* +- mosek=10.1.* - mypy=1.3.0 -- numpy=1.24.3 -- pandas=1.1.5 # acnportal 0.3.2 only works with Pandas 1.1 +- numpy=1.26.* +- pandas=2.1.* - pip -- pytorch=2.0.1 -- pytorch-cuda=11.8 # for PyTorch 2.0 +- pytorch=2.1.* - pytz=2023.3 - requests=2.31.0 -- scikit-learn=1.1.1 -- scipy=1.10.1 -- seaborn=0.12.2 -- tqdm=4.65.0 +- scikit-learn=1.1.* +- scipy=1.11.* +- seaborn=0.13.0 +- tqdm=4.66.* + +# for GPU. comment out for CPU-only. +- pytorch-cuda=11.8 # for PyTorch 2 - pip: - - acnportal==0.3.2 + - git+https://github.com/zach401/acnportal@0127a055cf - gymnasium==0.28.1 - pettingzoo==1.24.1 - - "ray[rllib]==2.7.0" - - tensorflow==2.12.0 - - nvidia-cudnn-cu11==8.6.0.163 # for TensorFlow 2.12 + - ray[rllib]==2.7.1 + - stable_baselines3>=2.0 + + # uncomment for CPU-only + # - tensorflow==2.14.* + + # for GPU. comment out for CPU-only. + - tensorflow[and-cuda]==2.14.* diff --git a/env_norl.yml b/env_norl.yml deleted file mode 100755 index 35497cc0..00000000 --- a/env_norl.yml +++ /dev/null @@ -1,37 +0,0 @@ -# Install or update environment -# conda env update --file env_norl.yml --prune -# -# Remove environment -# conda remove --name sustaingym_norl --all -# -# Notes -# - acnportal v0.3.2 only supports up to Pandas 1.1 -# - Pandas 1.1 only supports up to Python 3.9 -# - last updated: May 17, 2023 -name: sustaingym_norl -channels: -- mosek # for mosek -- conda-forge -dependencies: -- python=3.9 -- cvxpy=1.3.1 -- flake8 -- ipympl # for Jupyter / VSCode notebooks -- matplotlib=3.7.1 -- mosek=10.0.44 -- mypy=1.3.0 -- numpy=1.24.3 -- pandas=1.1.5 # acnportal 0.3.2 only works with Pandas 1.1 -- pip -- pytz -- requests -- scikit-learn -- scipy -- seaborn -- tensorboard -- tqdm - -- pip: - - acnportal==0.3.2 - - gymnasium==0.28.1 - - pettingzoo==1.22.3 diff --git a/env_rllib.yml b/env_rllib.yml deleted file mode 100755 index 0b9b7b2a..00000000 --- a/env_rllib.yml +++ /dev/null @@ -1,40 +0,0 @@ -# Install or update environment -# conda env update --file env_rllib.yml --prune -# -# Remove environment -# conda remove --name rllib --all -# -# rllib can use tensorflow back-end -# rllib supports gymnasium -# -name: rllib -channels: -- mosek -- conda-forge -dependencies: -- python=3.9 -- cudatoolkit=11.3 -- cvxpy -- flake8 -- gymnasium=0.27.1 -- ipympl -- matplotlib -- mosek=9.3.21 -- mypy=0.961 -- nodejs -- numpy -- pandas=1.1 -- pip -- pytz -- scikit-learn -- scipy -- seaborn -- tensorboard -- tqdm - -- pip: - - acnportal==0.3.2 - - atari_py - - GPUtil - - pettingzoo==1.22.3 - - "ray[rllib]"