Repo Setup (DRAFT)

.gitignore

@@ -0,0 +1,26 @@
+
+# ignore hidden files created by Mac OS:
+.DS_Store
+
+# ignore the .venv directory which configures the virtual environment:
+.venv/
+
+# ignore the .env file which contains environment variables:
+.env
+
+# ignore cache files
+__pycache__
+
+
+# ignore the video path, if storing in this repo:
+geometric_sim_videos/
+# ignore video:
+geometric_sim_videossample.mp4
+
+# these are for the SAC Demo notebook...
+
+# ignore the root path, if storing in this repo:
+root/
+
+# ignore the metrics path, if storing in this repo:
+metrics/

Makefile

@@ -0,0 +1,6 @@
+
+hello:
+	echo "Hello, World"
+
+activate:
+	source .venv/bin/activate

README.md

@@ -24,23 +24,56 @@ Before you run this notebook, make sure to go through the setup instructions bel
 
 ## Setup
 
-Follow these steps to setup locally before you run the `notebooks/SAC_Demo.ipynb` notebook. Note: this will only work on linux, as some libraries are not supported by other operating systems.
+Follow these steps to setup locally before you run the `notebooks/SAC_Demo.ipynb` notebook. 
 
-1. Clone the repository
+> NOTE: this will only work on Linux, as some libraries are not supported by other operating systems.
 
-2. Ensure you have `protoc` and `ffmpeg` installed, as well as `python >=3.10.12 and <3.12`. You can install these running `sudo apt install -y protobuf-compiler` and `sudo apt install -y ffmpeg`
+1. Clone the repository.
 
-3. Create a virtual environment by running `python -m venv .venv`. Activate the environment `source .venv/bin/activate`. Then, install poetry with `pip install poetry`
+2. Ensure you have `protoc` and `ffmpeg` installed, as well as `python >=3.10.12 and <3.12`. You can install these running `sudo apt install -y protobuf-compiler` and `sudo apt install -y ffmpeg`.
 
-4. Install the dependencies by running `poetry install`
+3. Create a virtual environment by running `python -m venv .venv`. Activate the environment `source .venv/bin/activate`. Then, install poetry with `pip install poetry`.
 
-5. Build the `.proto` files at `smart_control/proto`into python files by running `cd smart_control/proto && protoc --python_out=. smart_control_building.proto smart_control_normalization.proto smart_control_reward.proto && cd ../..`  
+> NOTE: on Google machines you may need to use `python3` instead of `python`.
 
-6. Modify the value of `VIDEO_PATH_ROOT` at `smart_control/simulator/constants.py`. This is the path where simulation videos will be stored
+> NOTE: on Google machines you may need to first install venv by running `apt install python3.12-venv` (prefixed with `sudo` as necessary).
 
-7. Now in the `notebooks/SAC_Demo.ipynb` notebook, modify the values of `data_path`, `metrics_path`, `output_data_path` and `root_dir`. In particular, `data_path` should point to the `sim_config.gin` file at `smart_control/configs/sim_config.gin`
+4. Install the dependencies by running `poetry install --with dev`.
 
-8. Now you are ready to run the `notebooks/SAC_Demo.ipynb` notebook 
+> NOTE: you may need to first use a Python version that is compatible with this project, by running `poetry env use 3.11` (for example if you want to use Python version 3.11).
+
+> NOTE: on Google machines, you may need to first install a compatible Python version by running `pyenv install 3.11` (for example if you want to use Python version 3.11), and then `pyenv versions` to list the installed versions, and then `pyenv global 3.11.11` to use the specific version that was installed.
+
+> NOTE: on Google machines you may need to first [install and configure pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation).
+
+5. Build the `.proto` files at `smart_control/proto` into python files by running `cd smart_control/proto && protoc --python_out=. smart_control_building.proto smart_control_normalization.proto smart_control_reward.proto && cd ../..`.
+
+6. Create a local `.env` file in the root directory of this repo, and specify the following environment variables (see example `.env` file contents below):
+
+  + `VIDEO_PATH_ROOT`: used by `smart_control/simulator/constants.py`, this is the path where simulation videos will be stored.
+  + `DATA_PATH`: used by demo notebooks, this should point to the directory in this repository where the `sim_config.gin` file is located (currently `smart_control/configs/resources/sb1`).
+  + `METRICS_PATH`: used by demo notebooks
+  + `OUTPUT_DATA_PATH`: used by demo notebooks
+  + `ROOT_DIR`: used by demo notebooks
+
+
+```sh
+# example .env file ...
+
+VIDEO_PATH_ROOT="/path/to/sbsim/geometric_sim_videos"
+
+DATA_PATH="/path/to/sbsim/smart_control/configs/resources/sb1/"
+METRICS_PATH="/path/to/sbsim/metrics" 
+OUTPUT_DATA_PATH='/path/to/sbsim/smart_control/sb_colab_demo'
+ROOT_DIR="/path/to/sbsim/root" 
+
+# fall back to using Python instead of C extensions (for the wrapt package):
+# WRAPT_DISABLE_EXTENSIONS="true"
+```
+
+7. Now you are ready to run the `notebooks/SAC_Demo.ipynb` notebook. 
+
+> NOTE: if you would like to use jupyter to run the notebook, first create a kernel by running `poetry run python -m ipykernel install --user --name=sbsim-kernel`, then choose this kernel when running the notebook in VS Code. Otherwise you can run `poetry run jupyter notebook` to run the notebook with Jupyter.
 
 ## Real World Data