2026SEL3-project-Brittle_Star_Controller_Modularity/docs/api/training.md

Training Models

This guide covers how to configure and run training experiments for the Brittle Star project using Hydra-based configurations.

Configuration

The project uses a modular configuration system powered by Hydra. Instead of passing many command-line flags, you select and override configuration groups.

Creating a Custom Experiment

1. Create a new experiment file: Create a file at configs/experiment/my_experiment.yaml. You can copy an existing one as a template:

   cp configs/experiment/base.yaml configs/experiment/my_experiment.yaml
   

2. Edit configs/experiment/my_experiment.yaml to set your experiment parameters:

   # @package _global_
   experiment:
     exp_name: "my_custom_run"
     seed: 42
   

Training Execution

To start a training run with the default settings defined in configs/main_config.yaml:

uv run python scripts/train.py

Using a Custom Experiment Configuration

To run with your custom experiment file:

uv run python scripts/train.py experiment=my_experiment

uv run python scripts/train.py ppo.learning_rate=0.001 ppo.num_envs=32 logging.track=true

Evaluation During Training

By default, the trainer saves checkpoints but does not evaluate them. To enable automatic headless evaluation of every saved checkpoint, set evaluation.evaluate_checkpoints=true:

uv run python scripts/train.py evaluation.evaluate_checkpoints=true

Reproducing Experiments

To ensure scientific validity and allow other researchers to reproduce your training runs, follow these steps:

1. Lock Environment Dependencies: Always use the exact environment lockfile when running experiments. Run:

   uv sync --frozen
   

   This guarantees that the same package versions (including JAX, Flax, and MuJoCo) are used.

2. Save and Locate Configuration Metadata: Every time you start a training run, the configuration is fully resolved by Hydra and saved as a metadata YAML file:

   • For checkpointed steps: runs/<run_dir>/checkpoints/<prefix>_step_<step>_metadata.yaml
   • For the final model: runs/<run_dir>/final_model_metadata.yaml

   This metadata file contains every active hyperparameter (e.g., learning rate, morphology configuration, PPO parameters, etc.) for that specific run.

3. Re-Run with Pinning: To reproduce a run, execute the training script with the configuration parameters specified in the metadata file, making sure to reuse the same seed:

   uv run python scripts/train.py experiment=my_experiment ppo.learning_rate=0.001 experiment.seed=42
   

---

For more details on evaluation metrics and comparison tools, see Evaluation.

For more details on tracking your experiments, see Tracking & Monitoring.