Configurability with Hydra

This repository contains minimal working examples of machine learning experiment configuration using Hydra.

These examples are intended to highlight some of the properties of Hydra which make it incredibly useful for machine learning research, including:

1. Hierarchical composition, using the defaults list.

   hydra-ml-examples/examples/0_basic/config/main.yaml

   Lines 1 to 4 in ff84ff5

   	defaults:
   	- model: randomforest
   	- dataset: blobs
   	- override hydra/job_logging: colorlog

2. Variable interpolation¹, which ensures a single source of truth for inter-linked configuration options.

   hydra-ml-examples/examples/0_basic/config/model/mlp.yaml

   Line 12 in ff84ff5

   random_state: ${seed}

   hydra-ml-examples/examples/0_basic/config/dataset/blobs.yaml

   Line 6 in ff84ff5

   random_state: ${seed}

3. Object instantiation, which removes the need for boilerplate code to propagate configuration to backing classes/functions.

   hydra-ml-examples/examples/0_basic/script.py

   Lines 16 to 19 in ff84ff5

   	def main(cfg: DictConfig):
   	# Instantiate the model. Type hints on instantiations can improve readability.
   	model: SKLearnClassifier = hydra.utils.instantiate(cfg.model)
   	logger.info("Instantiated model: %s", model.__class__.__name__)

Getting started

The following commands can be used to perform run the basic example: a sweep over all combinations of model and dataset for a toy problem using scikit-learn.

With Conda

conda env create --file examples/0_basic/env/environment.yaml
conda activate hydra-example-0
python examples/0_basic/script.py --multirun dataset=blobs,circles,moons model=randomforest,mlp,svm

With Docker

docker build --build-arg EXAMPLE="0_basic" --tag hydra-example-0 .
docker run hydra-example-0 --multirun dataset=blobs,circles,moons model=randomforest,mlp,svm

Advanced usage

Overriding parameters of the underlying model or dataset:

python examples/0_basic/script.py model=mlp model.activation=tanh
python examples/0_basic/script.py model=randomforest model.n_estimators=400
python examples/0_basic/script.py --multirun dataset=blobs,circles,moons dataset.n_samples=100,500,1000

Any parameter supported by the backing class can be modified from the command line.

For parameters which aren't explicitly specified in the configuration file, this can be achieved using append syntax²:

python examples/0_basic/script.py --multirun model=mlp +model.momentum=0.5,0.7,0.9

In this example the backing class is an MLP from scikit-learn (docs).

This mechanism is even more convenient with complex neural network definitions e.g. using Pytorch.

Footnotes

1. Using OmegaConf ↩

2. Hydra override syntax. ↩