Update CONTRIBUTING and EVChargingEnv docs

chrisyeh96 · Nov 2, 2023 · 7d7be30 · 7d7be30
1 parent eca3ef8
commit 7d7be30
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 116 deletions.
diff --git 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
@@ -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
@@ -5,45 +5,59 @@
 # 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
 - nvidia            # for pytorch-cuda
 - 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
diff --git a/env_rllib.yml b/env_rllib.yml