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.
• Results & Reproduction: 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: Standards, rules, and best practices for developing and adding code to the repository.
• 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 Scheme: Message propagation, Nerve-Net style.
• Modularity & Topology: Macroscopic brain topology, centralized, arm-level, segment-level.
• Input & Action Spaces: Description of the model's input and output.
• Reinforcement Learning Algorithm: RL techniques, i.e. PPO.
• Reward Function & Observation Space: Goals, fitness tracking, and reward structures.

API reference (/api)

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

• Brittle Star Environment: MuJoCo environment interaction and configuration.
• Training Models: How to configure and run experiments.
• Tracking & Monitoring: Setting up WandB and TensorBoard to monitor runs.
• Checkpoint & Model Evaluation: Evaluating checkpoints and comparing fault tolerance.
• Interactive Simulation & Visualization: Visualizing models in the MuJoCo viewer or rendering simulation videos.
• Analysis & Plotting Tools: Comparing checkpoints and generating plots.
• Results & Reproduction: Accessing WandB results and running reproduction pipelines.