2026SEL3-project-Brittle_Star_Controller_Modularity/docs/README.md

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.

Core Requirements & Guides

• Installation Instructions: 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.
• How to Run Experiments: A complete guide on running training jobs, setting custom hyperparameters, and overriding config options using Hydra.
• Reproducing Experiments: Best practices for reproducing past training runs using exact seeds, dependencies, and automatic metadata logging.
• Repository Structure: Overview of the directories and files within the codebase.

Repository Structure

.
├── 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: Description of the actor-critic pipeline.
• Communication: Message propagation, Nerve-Net style.
• Controllers: Macroscopig brain toplogy, centralized, arm-level, segment-level.
• Input/output: Description of the model's input and output.
• Learning algorithm: RL techniques, i.e. PPO.
• Reward function: Goals, fitness tracking, and reward structures.

API reference (/api)

If you are interested in the "how do I use it?"

• Training: How to configure and run experiments.
• Tracking & Monitoring: Setting up WandB and TensorBoard to monitor runs.
• Simulation: Visualizing and evaluating models.
• Environment: MuJoCo environment interaction and configuration.
• Analysis: Comparing checkpoints and generating plots.
• Evaluation: Evaluating checkpoints and comparing fault tolerance.