# README.md

## Overview

This repository contains a single entrypoint script, `run.sh`, designed to reproduce our experimental results for **GEMS** and **PSRO**. These runs specifically use **PettingZoo MPE environments**: `simple_spread_v3` and `simple_tag_v3`.

Running `run.sh` automatically:

* Sets up environment variables and hyperparameters.
* Launches **GEMS** (`gems.py`) and/or **PSRO** (`psro.py`) experiments over multiple seeds.
* Saves per-seed logs, CSV files, and optional GIF visualizations.
* Aggregates results across seeds into a single combined CSV file for easy analysis.

> **Note:** You only need to make `run.sh` executable. Python files like `gems.py` and `psro.py` are run through this script.

---

## 1. Installation

### Requirements

* **OS:** Linux or macOS (Windows users can use WSL or Git Bash).
* **Python Version:** 3.11.9
* **Dependencies and versions used in our experiments:**

  * `torch==2.8.0+cu128`
  * `numpy==2.1.3`
  * `pettingzoo==1.24.3`
  * `imageio.v2==2.37.0`

Install them using:

```bash
pip install torch==2.8.0+cu128 numpy==2.1.3 pettingzoo==1.24.3 imageio==2.37.0 matplotlib tqdm opencv-python gymnasium supersuit
```

* **FFmpeg (optional for GIFs):**

  ```bash
  # Ubuntu/Debian
  sudo apt-get install ffmpeg

  # macOS (Homebrew)
  brew install ffmpeg
  ```

---

## 2. Make `run.sh` Executable

Before running the experiment script, make it executable:

```bash
chmod +x run.sh
```

Now you can run it directly:

```bash
./run.sh
```

---

## 3. Quick Start

Run with **default settings**:

```bash
./run.sh
```

This will:

* Run both GEMS and PSRO algorithms.
* Use seeds `0 1 2 3 4`.
* Save outputs to a timestamped folder under `runs/`.

Example custom overrides:

```bash
# Run only GEMS with custom tag
RUN_PSRO=0 OUT_TAG=mytest ./run.sh

# Run only PSRO with a different environment
RUN_GEMS=0 ENV_NAME=simple_spread_v3 ./run.sh

# Run both with fewer seeds
SEEDS="0 1" ./run.sh
```

---

## 4. Output Structure

After execution, the script creates a folder like:

```
runs/20250925_123456_exp/
  _run_meta.txt                # metadata of run settings
  gems/
    seed_0/
      gems_seed0.csv
      gems_seed0.gif
      gems_seed0.log
    ...
  psro/
    seed_0/
      psro_seed0.csv
      psro_seed0.gif
      psro_seed0.log
    ...
  gems_combined.csv            # aggregated GEMS results
  psro_combined.csv            # aggregated PSRO results
```

* **CSV files** contain per-iteration metrics (reward, exploitability, etc.).
* **GIF files** visualize sample rollouts.
* **_run_meta.txt** logs the exact hyperparameters and environment variables for reproducibility.

---

## 5. Running Python Scripts Directly (Optional)

You can also run the Python files directly for single runs.

Example:

```bash
python gems.py \
  --env simple_tag_v3 \
  --iters 50 \
  --csv runs/scratch/gems_seed0.csv \
  --video runs/scratch/gems_seed0.gif \
  --seed 0
```

Or for PSRO:

```bash
python psro.py \
  --env simple_tag_v3 \
  --iters 50 \
  --csv runs/scratch/psro_seed0.csv \
  --video runs/scratch/psro_seed0.gif \
  --seed 0
```

This is useful for debugging or small-scale tests.

---

## 6. Key Environment Variables

You can override these variables inline when calling `run.sh`:

| Variable   | Default         | Purpose                           |
| ---------- | --------------- | --------------------------------- |
| `RUN_GEMS` | 1               | Run GEMS (1=yes, 0=no)            |
| `RUN_PSRO` | 1               | Run PSRO (1=yes, 0=no)            |
| `SEEDS`    | `0 1 2 3 4`     | Space-separated list of seeds     |
| `ENV_NAME` | `simple_tag_v3` | PettingZoo environment            |
| `OUT_TAG`  | `exp`           | Tag appended to output folder     |
| `DEVICE`   | `auto`          | Compute device: `cpu` or `cuda:0` |
| `ITERS`    | `100`           | Training iterations               |

Example:

```bash
RUN_PSRO=0 SEEDS="0 1" OUT_TAG=test ./run.sh
```

---

## 7. Reproducibility Checklist

To exactly replicate our results:

1. Use Python 3.11.9.
2. Use the exact dependency versions listed above.
3. Ensure `CUBLAS_WORKSPACE_CONFIG` is set (done automatically by `run.sh`).
4. Run with the exact default hyperparameters (do not override variables).
5. Collect results from `gems_combined.csv` and `psro_combined.csv`.

---

## 8. Troubleshooting

* **Permission denied:** Ensure `chmod +x run.sh` was done.
* **Missing packages:** Install dependencies with the exact versions specified.
* **Windows issues:** Run under WSL or Git Bash.
* **Blank combined CSV:** Check logs inside `seed_*/` folders for errors.
