Merge pull request #60 from SELab-3-2026/docs/mkdocs

docs: configure mkDocs GH Pages

.github/scripts/prepare_docs.py

@@ -0,0 +1,28 @@
+import os
+import glob
+import re
+import shutil
+
+folders_to_copy = ["src", "scripts", "configs"]
+for folder in folders_to_copy:
+    if os.path.exists(folder):
+        shutil.copytree(folder, f"docs/{folder}", dirs_exist_ok=True)
+
+for filepath in glob.glob("docs/**/*.md", recursive=True):
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # RULE A: Fix links pointing OUT to src/, scripts/, or configs/
+    # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
+    content = re.sub(
+        r"\]\(\.\./((?:\.\./)*)(src|scripts|configs)/([^)]*)\)", r"](\1\2/\3)", content
+    )
+
+    # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
+    # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
+    content = re.sub(r"\]\(((?:\.\./)+)docs/([^)]*)\)", r"](\1\2)", content)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(content)
+
+print("Successfully imported external files and adjusted markdown links.")

.github/workflows/publish-docs.yml

@@ -0,0 +1,38 @@
+name: Publish docs via GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - docs/*
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Prepare external docs
+        run: python .github/scripts/prepare_docs.py
+
+      - name: Configure Git identity
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

README.md

@@ -22,9 +22,10 @@ uv sync --frozen
 ├── runs/                   # Default output directory for Hydra and training artifacts
 ├── scripts/                # High-level entrypoints for training, simulation, and evaluation
 ├── src/
-│   └── brittle_star_project/ # Core library and environment logic
-│       ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
-│       └── trainers/       # Training loop implementations (e.g., PPO)
+│   ├── brittle_star_project/ # Core library and environment logic
+│   │   ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
+│   │   └── trainers/       # Training loop implementations (e.g., PPO)
+│   └── experiment_logger/  # Standalone logging package
 └── tests/                  # Unit and integration tests
 ```
 
@@ -48,6 +49,10 @@ For detailed instructions on how to use the project, please refer to the **[API
 4. **Compare fault tolerance of models:**
    See [Checkpoint & Model Evaluation](docs/api/evaluation.md)
 
+## Results & Reproduction
+
+See **[docs/api/reproduction.md](docs/api/reproduction.md)** to learn how to access our public [Weights & Biases (WandB) project](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2?nw=96mloffsyq), retrieve specific run parameters, and run the training/evaluation reproduction workflow.
+
 ## HPC
 
 See **[docs/HPC.md](docs/HPC.md)** for the full guide, including environment setup, cluster selection, interactive debugging, and job submission.

docs/CONTRIBUTING.md

@@ -24,7 +24,7 @@ Code readability is paramount, as code is read far more frequently than it is wr
 
 * **Git Practices:** Commits must be frequent and small. Each commit should relate to exactly one piece of functionality.
 * **Branching Strategy:** The `dev` branch serves as the integration branch for pushing and merging code. Only stable releases may be pushed to the `main` branch.
-* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see `DEVELOPMENT.md` for setup).
+* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see [DEVELOPMENT.md](./DEVELOPMENT.md) for setup).
 * **Repository Layout:** The repository must maintain the following core directories: `src/` for algorithms, `env/` for MuJoCo wrappers, `config/` for experiment configurations, `experiments/` for scripts, `docs/` for Doxygen or ReadTheDocs documentation, and `tests/` for unit tests.
 
 ## 4. Architecture & Tooling

docs/DEVELOPMENT.md

@@ -2,7 +2,7 @@
 
 This guide outlines how to set up the development environment for this project, prioritizing **reproducible builds**, **environment parity**, and **cross-hardware compatibility**.
 
-## Reproducibility &uv
+## Reproducibility & uv
 
 This project uses [uv](https://github.com/astral-sh/uv) to manage dependencies and virtual environments. The `uv.lock` file is the absolute source of truth for package versions and must always be committed.
 
@@ -48,6 +48,7 @@ The devcontainer provides an identical experience to local development but with
 ## Local Development (Alternative)
 
 If you prefer not to use Docker:
+
 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
 2. Run `uv sync --frozen` (CPU) or `uv sync --frozen --extra cuda` (GPU).
 
@@ -58,6 +59,7 @@ Verify your setup by running the JAX initialization test:
 ```bash
 uv run pytest tests/test_jax_init.py
 ```
+
 In the devcontainer, this will succeed on both CPU and GPU. A `GpuDevice` is expected if a GPU is detected and the `cuda` extra was installed.
 
 ## Logging & Monitoring

docs/HPC.md

@@ -1,6 +1,6 @@
 # HPC Guide
 
-Full documentation: <https://docs.hpc.ugent.be/>
+Full documentation: [https://docs.hpc.ugent.be/](https://docs.hpc.ugent.be/)
 
 ## Storage Overview
 
@@ -33,6 +33,7 @@ qsub -l gpus=1 scripts/hpc/install.sh
 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
@@ -40,6 +41,7 @@ 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
@@ -64,11 +66,13 @@ After installation, run these commands to ensure your environment is set up corr
    ```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()}')"

docs/README.md

@@ -1,23 +1,52 @@
 # Documentation
 
+Welcome to the Brittle Star project documentation. This codebase contains the implementations and research for the scientific evaluation of controller modularity in brittle-star-like robots trained using Reinforcement Learning.
+
+For the core codebase, scripts, and contribution history, visit our [GitHub Repository](https://github.com/SELab-3-2026/SEL3-2026-Groep-4).
+
+## Core Requirements & Guides
+
+- **[Installation Instructions](./DEVELOPMENT.md)**: Steps to set up your development environment locally or in a devcontainer using `uv`, including GPU configuration. For High-Performance Computing (HPC) setup details, see the **[HPC Guide](./HPC.md)**.
+- **[How to Run Experiments](./api/training.md)**: A complete guide on running training jobs, setting custom hyperparameters, and overriding config options using Hydra.
+- **[Results & Reproduction](./api/reproduction.md)**: Guide on how to access our public WandB training runs table and reproduce our training and evaluation phases (determining the best checkpoint vs. comparing architectures).
+- **[Contribution Guidelines](./CONTRIBUTING.md)**: Standards, rules, and best practices for developing and adding code to the repository.
+- **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase.
+
+## Repository Structure
+
+```text
+.
+├── configs/                # Hydra configuration files (YAML)
+├── docs/                   # Comprehensive documentation and API guides
+├── runs/                   # Default output directory for Hydra and training artifacts
+├── scripts/                # High-level entrypoints for training, simulation, and evaluation
+├── src/
+│   ├── brittle_star_project/ # Core library and environment logic
+│   │   ├── evaluation/     # Checkpoint evaluation, rollout logic, and metrics persistence
+│   │   └── trainers/       # Training loop implementations (e.g., PPO)
+│   └── experiment_logger/  # Standalone logging package
+└── tests/                  # Unit and integration tests
+```
+
 ## Design & architecture (`/design`)
 
 If you are interested in the "why did you do it like this?"
 
-- [Actor/critic architecture](./design/actor-critic.md): Description of the actor-critic pipeline.
-- [Communication](./design/communication.md): Message propagation, Nerve-Net style.
-- [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
-- [Input/output](./design/input_action_spaces.md): Description of the model's input and output.
-- [Learning algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
-- [Reward function](./design/learning_algorithm.md): Goals, fitness tracking, and reward structures.
+- [Actor-Critic Architecture](./design/actor-critic.md): Description of the actor-critic pipeline.
+- [Communication Scheme](./design/communication.md): Message propagation, Nerve-Net style.
+- [Modularity & Topology](./design/controllers.md): Macroscopic brain topology, centralized, arm-level, segment-level.
+- [Input & Action Spaces](./design/input_action_spaces.md): Description of the model's input and output.
+- [Reinforcement Learning Algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
+- [Reward Function & Observation Space](./design/reward_function.md): Goals, fitness tracking, and reward structures.
 
 ## API reference (`/api`)
 
 If you are interested in the "how do I use it?"
 
-- [Training](./api/training.md): How to configure and run experiments.
+- [Brittle Star Environment](./api/environment.md): MuJoCo environment interaction and configuration.
+- [Training Models](./api/training.md): How to configure and run experiments.
 - [Tracking & Monitoring](./api/tracking.md): Setting up WandB and TensorBoard to monitor runs.
-- [Simulation](./api/simulation.md): Visualizing and evaluating models.
-- [Environment](./api/environment.md): MuJoCo environment interaction and configuration.
-- [Analysis](./api/analysis.md): Comparing checkpoints and generating plots.
-- [Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
+- [Checkpoint & Model Evaluation](./api/evaluation.md): Evaluating checkpoints and comparing fault tolerance.
+- [Interactive Simulation & Visualization](./api/simulation.md): Visualizing models in the MuJoCo viewer or rendering simulation videos.
+- [Analysis & Plotting Tools](./api/analysis.md): Comparing checkpoints and generating plots.
+- [Results & Reproduction](./api/reproduction.md): Accessing WandB results and running reproduction pipelines.

docs/api/analysis.md

@@ -5,6 +5,7 @@ This guide outlines the tools available for analyzing experimental data and gene
 ## Shared Configuration
 
 All plotting scripts share a central configuration in `scripts/plots/plot_config.py`. This file defines:
+
 - **Color Palette:** A color-blind friendly, high-contrast palette for different architectures.
 - **Typography:** Consistent font sizes and styles tailored for A0 posters.
 - **Markers:** Shared visual indicators, such as the ★ used for best performers.
@@ -40,6 +41,7 @@ uv run python scripts/plots/analyze_comparisons.py path/to/results.csv \
 ### Outputs
 
 The script generates four key plots, each saved as both `.png` and `.svg`:
+
 1.  **Forward Velocity:** Grouped bar chart (cm/s).
 2.  **Accumulated Reward:** Mean cumulative reward.
 3.  **Success Rate:** Target acquisition percentage.
@@ -65,6 +67,7 @@ uv run python scripts/plots/analyze_convergence.py --output_dir runs/convergence
 ### Outputs
 
 Generates three plots (PNG & SVG):
+
 1. `convergence_comparison`: Grouped horizontal bar chart.
 2. `progress_reward_curves`: Line plots of reward over time.
 3. `progress_velocity_curves`: Line plots of velocity over time.
@@ -74,7 +77,9 @@ Generates three plots (PNG & SVG):
 ## Poster Integration (Figma)
 
 ### SVG & Scaling
+
 We recommend using the **SVG** outputs for poster design in Figma:
+
 1. **No Resolution Loss:** SVGs are vector-based and will remain sharp at any size.
 2. **Native Text:** Text in the SVG imports as native text layers in Figma.
 3. **Exact Font Matching:** To ensure a `28pt` font in the plot matches a `28pt` font in your poster, set the `--fig_width` and `--fig_height` to match the physical dimensions of the plot box in your Figma layout.

docs/api/environment.md

@@ -1,12 +1,15 @@
 # Brittle star environment
 
 ## Creation
+
 The environment package contains a factory class `BrittleStarEnvFactory` 
 that creates instances of the environment/morphologies/... It uses the
 configuration classes defined in `env_config.py` to create the instances.
 
 ## Configuration
+
 The data classes in `env_config` have default values as stated in the tutorials.
+
 * MorphologyConfig: configuration for the morphology of the brittle star. Contains
 number of arms, number of segments per arm, and control mode.
 * ArenaConfig: configuration for the arena. Sets the size of the arena, whether to 
@@ -15,10 +18,13 @@ set the ground floor to sand, attach a target and sizes of the walls.
 such as camera locations, simulation time and the task.
 
 ## Backend and Task enums
+
 The Backend enum specifies either an MJC or MJX backend.
+
 * MJC: runs on CPU
 * MJX: uses jax on the gpu
 
 The Task enum specifies which task to use. 2 items are present:
+
 * DIRECTED_LOCOMOTION: move to a target location
 * LIGHT_ESCAPE: situation where the robot must move to a darker location

docs/api/evaluation.md

@@ -54,3 +54,7 @@ python scripts/evaluate_checkpoints.py \
 ```
 
 This script scans the `checkpoints/` directory of the specified run and evaluates every `.flax` file it finds using the model's training morphology.
+
+---
+
+For a step-by-step walkthrough on using these evaluation phases to reproduce our project results, see the **[Results & Reproduction Guide](./reproduction.md)**.

docs/api/reproduction.md

@@ -0,0 +1,108 @@
+# Results & Reproduction
+
+This guide explains how to access our official training logs and reproduce our results.
+
+Our official training runs, model configurations, and metrics are publicly hosted on Weights & Biases (WandB).
+
+---
+
+## Weights & Biases (WandB) Project
+
+All experiments, final models, and training logs are tracked in our public WandB project:
+
+* **Official Runs Table**: [WandB final-models-v2 Table](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2/table?nw=96mloffsyq)
+
+This page lists the verified runs with their architecture types, morphology definitions, evaluation metrics, and final model performance.
+
+### How to Reproduce a Run from WandB
+
+Weights & Biases provides a built-in feature to extract the exact parameters and commands used for any given run:
+
+1. Open the [WandB final-models-v2 Table](https://wandb.ai/SEL3-2026-Groep-4/final-models-v2/table?nw=96mloffsyq).
+2. Click on the name of the run you wish to reproduce to open its detail page.
+3. In the top-right corner of the run header (next to the run name, not the main workspace header), click the **three dots (`...`)** menu.
+4. Select **"Reproduce run"**. This will display the exact command-line arguments and configuration settings used to execute that run.
+
+---
+
+## Local & HPC Reproduction Workflow
+
+To reproduce our training and evaluation phases locally or on an HPC cluster, follow the procedures below.
+
+### 1. Environment Setup
+
+To ensure identical package versions (including JAX, Flax, and MuJoCo), sync your environment using the lockfile:
+
+```bash
+uv sync --frozen
+```
+
+### 2. Training Phase
+
+Run the training script using the exact parameters retrieved from WandB's "Reproduce run" page or from a downloaded `_metadata.yaml` file:
+
+```bash
+uv run python scripts/train.py experiment=my_experiment ppo.learning_rate=0.001 experiment.seed=42
+```
+
+---
+
+## Evaluation Phases
+
+Reproducing our evaluation results is divided into two distinct phases:
+
+### Phase 1: Determining the Best Checkpoint
+
+During training, checkpoints are saved at regular intervals. To determine which of these checkpoints performed the best:
+
+1. **Evaluate Checkpoints Post-Training**:
+   If checkpoint evaluation was not run during training, scan the completed run's checkpoints folder by pointing to the final model path:
+
+   ```bash
+   uv run python scripts/evaluate_checkpoints.py simulation.model_path=runs/your_run_dir/final_model.flax
+   ```
+
+   This script runs deterministic rollouts for every checkpoint in `runs/your_run_dir/checkpoints/`.
+
+2. **Locate the Results**:
+   The evaluations are saved to:
+
+   ```text
+   runs/your_run_dir/metrics/checkpoint_evaluation.csv
+   ```
+
+   Analyze this CSV to find the checkpoint iteration with the highest average return or target success rate. This checkpoint will be used for cross-architecture comparisons.
+
+### Phase 2: Comparing Checkpoints Between Architectures
+
+Once the best checkpoints for each architecture are identified, they are compared under shared, standardized environments (including fault tolerance checks such as leg amputations).
+
+1. **Configure the Comparison Models**:
+   Open or create an evaluation config file (e.g., `configs/evaluation/poster.yaml`) and add the paths to the best checkpoints:
+
+   ```yaml
+   # configs/evaluation/poster.yaml
+   evaluation:
+     comparison_models:
+       - runs/run_arch_centralized/checkpoints/checkpoint_best.flax
+       - runs/run_arch_decentralized/checkpoints/checkpoint_best.flax
+   ```
+
+2. **Execute the Comparison Script**:
+   Run the comparison script using your config:
+
+   ```bash
+   uv run python scripts/compare_models.py evaluation=poster
+   ```
+
+   This script runs multiple sequential evaluation episodes (defined by `comparison_num_episodes` starting at `comparison_base_seed`) for every model across the selected morphologies.
+
+3. **Analyze Comparison Metrics**:
+   The script writes a consolidated CSV file to `metrics/model_comparison.csv` containing:
+
+   * **`eval_return`**: The cumulative return.
+   * **`approx_max_velocity`**: The distance covered per step.
+   * **`reached_target`**: Navigational success rates.
+   * **`arm_0` to `arm_4`**: Active segments per arm (indicating damage/amputations).
+
+This CSV can then be passed to the plotting scripts (e.g., `scripts/plots/analyze_comparisons.py`) to generate visualization plots. For details on configuration and outputs, see the **[Analysis & Plotting Guide](./analysis.md)**.

docs/api/simulation.md

@@ -1,6 +1,6 @@
-# Simulation & Evaluation
+# Interactive Simulation & Visualization
 
-The simulation pipeline allows you to visualize trained models and evaluate their performance under various conditions.
+The simulation pipeline allows you to visualize trained models and observe their behavior under various conditions.
 
 ## Overview
 
@@ -50,5 +50,5 @@ uv run scripts/poster_visualisations/render_poster_videos.py \
   --max-steps 10000 --width 640 --height 480 --fps 60 \
   --output-root vids/poster/
 ```
+For batch evaluation, checkpoint analysis, and cross-model architecture comparisons, see the **[Checkpoint & Model Evaluation Guide](./evaluation.md)**.
 
-For batch evaluation and cross-model comparison, see the **[Evaluation Guide](./evaluation.md)**.

docs/api/tracking.md

@@ -47,7 +47,7 @@ All runs are recorded locally in the `runs/` directory (or the directory specifi
 tensorboard --logdir runs/
 ```
 
-Access the interface at `http://localhost:6006`.
+Access the interface at [http://localhost:6006](http://localhost:6006).
 
 ### CLI Exploration Tool
 
@@ -58,3 +58,7 @@ uv run python scripts/analysis/explore_tensorboard.py runs/your_run_name/
 ```
 
 See the detailed description in [`/scripts/analysis/README.md`](../../scripts/analysis/README.md).
+
+## Developer Logging API
+
+For details on the developer API of our internal logging library (how backend routing, checkpoint synchronization, and singleton initialization works), see the **[Experiment Logger API Guide](../../src/experiment_logger/README.md)**.

docs/api/training.md

@@ -6,6 +6,8 @@ This guide covers how to configure and run training experiments for the Brittle
 
 The project uses a modular configuration system powered by [Hydra](https://hydra.cc/). Instead of passing many command-line flags, you select and override configuration groups.
 
+For a detailed guide on the structure, validation, and usage of our Hydra configuration files, see the **[Brittle Star Configuration System Guide](../../configs/README.md)**.
+
 ### Creating a Custom Experiment
 
 1. **Create a new experiment file:**
@@ -15,6 +17,7 @@ The project uses a modular configuration system powered by [Hydra](https://hydra
    ```
 
 2. **Edit `configs/experiment/my_experiment.yaml`** to set your experiment parameters:
+
    ```yaml
    # @package _global_
    experiment:
@@ -50,6 +53,12 @@ By default, the trainer saves checkpoints but does not evaluate them. To enable
 uv run python scripts/train.py evaluation.evaluate_checkpoints=true
 ```
 
-For more details on evaluation metrics and comparison tools, see [Evaluation](./evaluation.md).
+## Reproducing Experiments
+
+For detailed steps on how to reproduce training runs, locate run configuration metadata, or reproduce our experiments using Weights & Biases (WandB), see the **[Results & Reproduction Guide](./reproduction.md)**.
+
+---
+
+For more details on evaluation metrics and comparison tools, see [Checkpoint & Model Evaluation](./evaluation.md).
 
 For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).

docs/design/actor-critic.md

@@ -98,13 +98,13 @@ graph TD
 
 ## Implementation Details (Network Depth)
 
-Inspired by: https://iclr-blog-track.github.io/2022/03/25/ppo-implementation-details/
+Inspired by: [PPO Implementation Details](https://iclr-blog-track.github.io/2022/03/25/ppo-implementation-details/)
 
 The MLPs used in both pipelines are defined with specific hidden layer configurations to balance learning capability
 and computational cost. As of right now, though this might change as we make progress in our experiments, we use:
 
 - Input Networks (Sensors & Feature Extractors): These networks map the raw state inputs to internal hidden states.
-  They are configured as standard dense networks with 2 hidden layers of 64 nodes each (`[64, 64]`) and utilize `tanh`
+  They are configured as standard dense networks with 3 hidden layers of 300 nodes each (`[300, 300, 300]`) and utilize `tanh`
   activation functions.
 - Output Networks (Motors, Actors & Critics): The final output models are intentionally kept shallow. The Actor
   directly projects the hidden state to a continuous action distribution (`mean` and `log_std`) using a single dense
@@ -116,6 +116,6 @@ by previous research to maintain learning stability.
 
 **References**
 
-- Ha, D. (2017, October 29). A Visual Guide to Evolution Strategies. 大トロ ・ Machine Learning. https://blog.otoro.net/2017/10/29/visual-evolution-strategies/
-- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. https://doi.org/10.48550/arXiv.1707.06347.
-- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613.
+- Ha, D. (2017, October 29). A Visual Guide to Evolution Strategies. 大トロ ・ Machine Learning. [https://blog.otoro.net/2017/10/29/visual-evolution-strategies/](https://blog.otoro.net/2017/10/29/visual-evolution-strategies/)
+- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. [https://doi.org/10.48550/arXiv.1707.06347](https://doi.org/10.48550/arXiv.1707.06347).
+- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. [https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613](https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613).

docs/design/communication.md

@@ -1,6 +1,7 @@
 # Communication scheme (Message Passing)
 
 Remember our research question:
+
 > "What is the impact of different levels of controller modularity on learning speed, coordination, and fault tolerance
 > (e.g. amputations) in brittle-star-like robots trained with Reinforcement Learning?"
 
@@ -39,5 +40,5 @@ extended morphologies.
 
 **References**
 
-- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613.
-- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. https://doi.org/10.48550/arXiv.2007.04976.
+- Wang, Tingwu, Renjie Liao, Jimmy Ba, and S. Fidler. ‘NerveNet: Learning Structured Policy with Graph Neural Networks’. Conference paper presented at International Conference on Learning Representations. 15 February 2018. [https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613](https://www.semanticscholar.org/paper/NerveNet:-Learning-Structured-Policy-with-Graph-Wang-Liao/249408527106d7595d45dd761dd53c83e5a02613).
+- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. [https://doi.org/10.48550/arXiv.2007.04976](https://doi.org/10.48550/arXiv.2007.04976).

docs/design/learning_algorithm.md

@@ -25,6 +25,6 @@ Alternative learning algorithms include:
 
 **References**
 
-- Fujimoto, Scott, Herke Hoof, and David Meger. ‘Addressing Function Approximation Error in Actor-Critic Methods’. Proceedings of the 35th International Conference on Machine Learning, 3 July 2018, 1587-96. https://proceedings.mlr.press/v80/fujimoto18a.html.
-- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. https://doi.org/10.48550/arXiv.2007.04976.
-- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. https://doi.org/10.48550/arXiv.1707.06347.
+- Fujimoto, Scott, Herke Hoof, and David Meger. ‘Addressing Function Approximation Error in Actor-Critic Methods’. Proceedings of the 35th International Conference on Machine Learning, 3 July 2018, 1587-96. [https://proceedings.mlr.press/v80/fujimoto18a.html](https://proceedings.mlr.press/v80/fujimoto18a.html).
+- Huang, Wenlong, Igor Mordatch, and Deepak Pathak. ‘One Policy to Control Them All: Shared Modular Policies for Agent-Agnostic Control’. arXiv:2007.04976. Preprint, arXiv, 9 July 2020. [https://doi.org/10.48550/arXiv.2007.04976](https://doi.org/10.48550/arXiv.2007.04976).
+- Schulman, John, Filip Wolski, Prafulla Dhariwal, Alec Radford, and Oleg Klimov. ‘Proximal Policy Optimization Algorithms’. arXiv:1707.06347. Preprint, arXiv, 28 August 2017. [https://doi.org/10.48550/arXiv.1707.06347](https://doi.org/10.48550/arXiv.1707.06347).

docs/design/reward_function.md

@@ -8,8 +8,7 @@ inputs must be distributed fairly to guarantee an objective comparison between d
 - The reward function is centered around minimizing the distance to the goal or maximizing the movement towards the goal
   within a finite number of timesteps $T$.
 - To motivate efficient movement, the amount of timesteps taken to reach the goal will be used as penalty.
-- An extra penalty based on movement relative to the current step and
-the previous is used to penalize a movement away from the target.
+- An extra penalty based on movement relative to the current step and the previous is used to penalize a movement away from the target.
 
 ## From reward to PPO
 

docs/javascripts/katex.js

@@ -0,0 +1,16 @@
+const renderMath = (el) => {
+  renderMathInElement(el, {
+    delimiters: [
+      { left: "$$",  right: "$$",  display: true },
+      { left: "$",   right: "$",   display: false },
+      { left: "\\(", right: "\\)", display: false },
+      { left: "\\[", right: "\\]", display: true }
+    ],
+  });
+};
+
+if (typeof document$ !== "undefined") {
+  document$.subscribe(({ body }) => renderMath(body));
+} else {
+  document.addEventListener("DOMContentLoaded", () => renderMath(document.body));
+}

mkdocs.yml

@@ -0,0 +1,41 @@
+site_name: Brittle Star Project
+theme:
+  name: material
+
+nav:
+  - Home: README.md
+  - Design & Architecture:
+      - Actor-Critic Architecture: design/actor-critic.md
+      - Communication Scheme: design/communication.md
+      - Modularity & Topology: design/controllers.md
+      - Input & Action Spaces: design/input_action_spaces.md
+      - Reinforcement Learning Algorithm: design/learning_algorithm.md
+      - Reward Function & Observation Space: design/reward_function.md
+  - API Reference:
+      - Brittle Star Environment: api/environment.md
+      - Training Models: api/training.md
+      - Tracking & Monitoring: api/tracking.md
+      - Checkpoint & Model Evaluation: api/evaluation.md
+      - Interactive Simulation & Visualization: api/simulation.md
+      - Analysis & Plotting Tools: api/analysis.md
+      - Results & Reproduction: api/reproduction.md
+  - HPC Guide: HPC.md
+  - Contribution Guidelines: CONTRIBUTING.md
+  - Development Guide: DEVELOPMENT.md
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_css:
+  - https://unpkg.com/katex@0/dist/katex.min.css
+
+extra_javascript:
+  - javascripts/katex.js
+  - https://unpkg.com/katex@0/dist/katex.min.js
+  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js