From 511c3ebd958682b8d16d7d6863e4fda6c52f42a1 Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Wed, 20 May 2026 14:54:01 +0200 Subject: [PATCH] docs: restructure docs for clarity --- README.md | 2 +- docs/README.md | 25 +++++++++++++------------ docs/{ => api}/reproduction.md | 2 +- docs/api/simulation.md | 6 +++--- docs/api/training.md | 4 ++-- mkdocs.yml | 21 +++++++++++++++++++++ 6 files changed, 41 insertions(+), 19 deletions(-) rename docs/{ => api}/reproduction.md (99%) diff --git a/README.md b/README.md index 9bb9ee2..6e56334 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ For detailed instructions on how to use the project, please refer to the **[API ## Results & Reproduction -See **[docs/reproduction.md](docs/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. +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 diff --git a/docs/README.md b/docs/README.md index 1e0c21d..ec73a8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ For the core codebase, scripts, and contribution history, visit our [GitHub Repo - **[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](./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). +- **[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). - **[Repository Structure](#repository-structure)**: Overview of the directories and files within the codebase. ## Repository Structure @@ -31,20 +31,21 @@ For the core codebase, scripts, and contribution history, visit our [GitHub Repo 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/reward_function.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. \ No newline at end of file +- [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. \ No newline at end of file diff --git a/docs/reproduction.md b/docs/api/reproduction.md similarity index 99% rename from docs/reproduction.md rename to docs/api/reproduction.md index f6fba01..87df150 100644 --- a/docs/reproduction.md +++ b/docs/api/reproduction.md @@ -105,4 +105,4 @@ Once the best checkpoints for each architecture are identified, they are compare * **`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](./api/analysis.md)**. +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)**. diff --git a/docs/api/simulation.md b/docs/api/simulation.md index 1e288b9..bde8b93 100644 --- a/docs/api/simulation.md +++ b/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 @@ -38,4 +38,4 @@ uv run scripts/simulate.py \ Videos and evaluation metadata are stored in timestamped folders alongside the model: `runs/your_run/final_model_evaluations/eval_/simulation.mp4` -For batch evaluation and cross-model comparison, see the **[Evaluation Guide](./evaluation.md)**. +For batch evaluation, checkpoint analysis, and cross-model architecture comparisons, see the **[Checkpoint & Model Evaluation Guide](./evaluation.md)**. diff --git a/docs/api/training.md b/docs/api/training.md index a3b813a..197e76f 100644 --- a/docs/api/training.md +++ b/docs/api/training.md @@ -53,10 +53,10 @@ uv run python scripts/train.py evaluation.evaluate_checkpoints=true ## 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 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 [Evaluation](./evaluation.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). diff --git a/mkdocs.yml b/mkdocs.yml index 7e6c856..cc60194 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,27 @@ 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: