Merge branch 'dev' into docs/reward_and_mlp-design

docs/CONTRIBUTING.md

@@ -32,4 +32,4 @@ Code readability is paramount, as code is read far more frequently than it is wr
 * **Algorithms & Frameworks:** Proximal Policy Optimization (PPO) is the recommended baseline algorithm. CleanRL should be used as a starting point and adapted for continuous action spaces. All Artificial Neural Network (ANN) controller architectures must be implemented using Flax.
 * **Simulation:** The simulation environment utilizes a MuJoCo brittle star. XML MuJoCo structures must remain realistic and respect morphological constraints.
 * **Experiment Tracking:** Weights & Biases (wandb) must be utilized for tracking and logging all experiments.
-* **Code Styling:** All code must conform to the chosen style guide (i.e. Google standard). This is enforced using build tools and pre-commit hooks such as flake8, black, or isort.
+* **Code Styling:** All code must conform to the chosen style guide (Google standard). This is enforced via `uv` using **ruff** and pre-commit hooks.

docs/HPC.md

@@ -0,0 +1,85 @@
+# HPC Guide
+
+Full documentation: <https://docs.hpc.ugent.be/>
+
+## Storage Overview
+
+- **Run Outputs**: Written to `$VSC_SCRATCH` during the job (fast I/O) and copied to `$VSC_DATA` at the end for persistence.
+- **Virtual Environments**: Managed on **`$VSC_DATA`** by mirroring configuration files. This avoids the 3GB home quota without requiring symlinks in the project root.
+
+## Initial Environment Setup
+
+Run **once** after cloning the repository. This script handles all modules, mirroring, and environment synchronization.
+
+```bash
+# Option A: Interactive (on a compute node)
+module swap cluster/donphan  # Debug cluster (CPU only)
+# OR for GPU clusters:
+# module swap cluster/joltik
+# module swap cluster/accelgor
+# module swap cluster/litleo
+
+qsub -I -l nodes=1:gpus=1  # Only for GPU clusters
+cd "${PBS_O_WORKDIR}"
+bash scripts/hpc/install.sh
+
+# Option B: Batch (Run in background)
+# NOTE: GPU clusters (joltik/accelgor/litleo) require -l gpus=1 at runtime
+qsub -l gpus=1 scripts/hpc/install.sh
+```
+
+## Production vs. Debug Clusters
+
+Our scripts are cluster-agnostic and do **not** have hardcoded GPU requirements. Instead, you must request GPUs at runtime using the `-l gpus=1` flag when submitting to a production GPU cluster.
+
+### Debugging (Donphan)
+The `donphan` cluster does not support GPUs. Simply run the scripts without extra resource flags:
+```bash
+module swap cluster/donphan
+qsub scripts/hpc/train.pbs
+```
+
+### Production (Joltik, Accelgor, Litleo)
+These clusters provide GPU acceleration and **require** a GPU request at runtime:
+```bash
+module swap cluster/joltik  # or accelgor/litleo
+qsub -l gpus=1 scripts/hpc/train.pbs
+```
+
+## Interactive Debugging
+
+To activate your environment for interactive work, simply run the same `install.sh` script.
+
+```bash
+qsub -I -l nodes=1:ppn=4 -l walltime=1:00:00
+cd "$PBS_O_WORKDIR"
+bash scripts/hpc/install.sh
+```
+
+### Verification Commands
+
+After installation, run these commands to ensure your environment is set up correctly:
+
+1. **Verify Quota Safety**:
+   ```bash
+   ls -d venvs 2>/dev/null && echo "FAIL" || echo ">>> PASS: Project root is clean."
+   ```
+2. **Verify Library Versions (NumPy Fix)**:
+   ```bash
+   python -c "import numpy; print(f'NumPy: {numpy.__version__}')"
+   # Expected: 2.x.x (Venv version), not 1.2x (System version)
+   ```
+3. **Verify GPU Access**:
+   ```bash
+   python -c "import torch, jax; print(f'GPU: {torch.cuda.is_available()}'); print(f'JAX: {jax.devices()}')"
+   ```
+
+## Managing Dependencies
+
+`env/hpc/requirements.txt` is auto-generated from `pyproject.toml`. To regenerate:
+
+```bash
+uv run scripts/hpc/export_requirements.py
+```
+
+Modules listed in `env/hpc/modules.txt` are automatically excluded from the pip requirements to save space and use HPC-optimized binaries.

docs/api/simulate.md

@@ -0,0 +1,14 @@
+# Training and Simulation for Brittle Star Models
+
+## Simulating a model
+
+In order to simulate and view the behavior of a trained model, you can use the `simulate.py` script. This script allows you to specify the path to a trained model and will launch a simulation using that model. This script has the following parameters:
+
+- `--model`: The path to the trained model artifact to simulate.
+- `--model-type`: The type of model to simulate (e.g., `random`, ...)
+- `--task`: The task to simulate (e.g., `directed_locomotion`, ...)
+- `--seed`: The random seed for reproducibility.
+
+```bash
+python simulate.py --model artifacts/my_model --model-type random --task directed_locomotion --seed 0
+```

docs/api/train_simulate.md

@@ -1,30 +0,0 @@
-# Training and Simulation for Brittle Star Models
-
-## Training a model
-
-To train a model, you can use the `train.py` script. This script allows to pass some parameters to customize the training process:
-
-- `--out`: The output path where the trained model will be saved.
-- `--model_type`: The type of model to train (e.g., `random`, ...)
-- `--task`: The task to train on (e.g., `directed_locomotion`, ...)
-- `--seed`: The random seed for reproducibility.
-- `--epochs`: The number of epochs to train for.
-
-This will then train the specified model on the specified task for the given number of epochs and save the trained model to the specified output path.
-
-```bash
-python train.py --out artifacts/my_model --model-type random --task directed_locomotion --seed 0 --epochs 50 
-```
-
-## Simulating a model
-
-In order to simulate and view the behavior of a trained model, you can use the `simulate.py` script. This script allows you to specify the path to a trained model and will launch a simulation using that model. This script has the following parameters:
-
-- `--model`: The path to the trained model artifact to simulate.
-- `--model-type`: The type of model to simulate (e.g., `random`, ...)
-- `--task`: The task to simulate (e.g., `directed_locomotion`, ...)
-- `--seed`: The random seed for reproducibility.
-
-```bash
-python simulate.py --model artifacts/my_model --model-type random --task directed_locomotion --seed 0
-```