82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# 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](https://hydra.cc/). 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:
|
|
```bash
|
|
cp configs/experiment/base.yaml configs/experiment/my_experiment.yaml
|
|
```
|
|
|
|
2. **Edit `configs/experiment/my_experiment.yaml`** to set your experiment parameters:
|
|
|
|
```yaml
|
|
# @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`:
|
|
|
|
```bash
|
|
uv run python scripts/train.py
|
|
```
|
|
|
|
### Using a Custom Experiment Configuration
|
|
|
|
To run with your custom experiment file:
|
|
|
|
```bash
|
|
uv run python scripts/train.py experiment=my_experiment
|
|
```
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](./evaluation.md).
|
|
|
|
For more details on tracking your experiments, see [Tracking & Monitoring](./tracking.md).
|