54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# Brittle Star Configuration System
|
|
|
|
This project uses **Hydra** for a modular, hierarchical, and strictly-typed configuration system.
|
|
|
|
## Core Concepts
|
|
|
|
1. **Composition over Inheritance**: Instead of one giant config file, the configuration is composed of small, domain-specific modules (PPO settings, architecture, morphology, etc.).
|
|
2. **Strict Typing**: Every configuration is validated against a Python dataclass schema (`ConfigStore`). Misspelled keys throw a `ConfigAttributeError` immediately.
|
|
3. **CLI Swapping**: You can swap entire modules or override individual values from the command line without touching code.
|
|
|
|
## Directory Structure
|
|
|
|
- `main_config.yaml`: The root entry point defining the default composition.
|
|
- `experiment/`: High-level experiment settings (seed, device).
|
|
- `logging/`: WandB and checkpointing configuration.
|
|
- `ppo/`: PPO training hyperparameters.
|
|
- `architecture/`: Polymorphic network architectures (centralized vs. decentralized).
|
|
- `morphology/`: Physical robot definitions (number of segments, amputations).
|
|
- `arena/`: Environment physics and visual settings.
|
|
- `environment/`: Task-specific settings (Directed Locomotion, Light Escape).
|
|
|
|
## Common Commands
|
|
|
|
### Local Debugging
|
|
Run a quick test with minimal iterations:
|
|
```bash
|
|
python scripts/train.py experiment=dev_test ppo=fast
|
|
```
|
|
|
|
### Swapping Architectures or Morphologies
|
|
Test a decentralized controller on a 3-arm robot:
|
|
```bash
|
|
python scripts/train.py architecture=decentralized morphology=3_arms
|
|
```
|
|
|
|
### HPC Production
|
|
Run stable PPO with WandB enabled (HPC submission scripts handle the `hydra.run.dir` redirection):
|
|
```bash
|
|
python scripts/train.py ppo=stable logging=wandb_enabled
|
|
```
|
|
|
|
### Dry-Run Validation
|
|
Check if your configuration is valid without starting the simulation:
|
|
```bash
|
|
python scripts/train.py --cfg job
|
|
```
|
|
|
|
## Developer Notes
|
|
|
|
- **Adding a new group**: Create a subdirectory in `configs/` and register the new dataclass in `src/brittle_star_project/configs/register_configs.py`.
|
|
- **Typo Catching**: If you see a `ConfigAttributeError`, check for typos in your YAML keys or CLI overrides.
|
|
- **Output Redirection**: We use `experiment.base_run_dir` to configure where logs and models are stored (defaults to `runs/`).
|
|
- To change it locally: `python scripts/train.py experiment.base_run_dir=/path/to/custom/dir`
|
|
- On HPC, ensure this points to a fast scratch storage.
|