Configuration Management

Configuration Management

The MLFramework Template leverages Hydra to handle hyperparameter tuning, model composition, and execution settings. By utilizing Hydra, the framework completely decouples configuration parameters from the source code, enabling complex experimental tracking without requiring code modifications.

Core Philosophy: Instantiation

The fundamental principle of this configuration setup is dynamic object instantiation. Instead of writing boilerplate code to parse arguments and initialize classes, Hydra directly instantiates Python objects from YAML definitions.

Every component that requires initialization (e.g., DataModules, Architectures, Tasks) must define a _target_ key in its YAML configuration. The remaining keys must strictly map to the __init__ signature of the specified target class.

Example: Model Configuration

Below is an example of a configuration file for a model architecture, typically located in conf/model/my_model.yaml:

_target_: src.models.architectures.convkan_example.SimpleConvKAN
input_channels: 3
num_classes: 10
hidden_dims: [64, 128, 256]
dropout_rate: 0.3

When the pipeline executes, Hydra automatically resolves this configuration into the equivalent Python instantiation:

# Internal Hydra behavior
model = SimpleConvKAN(
    input_channels=3, 
    num_classes=10, 
    hidden_dims=[64, 128, 256], 
    dropout_rate=0.3
)

Hierarchical Composition

Configurations are structured hierarchically. The primary entrypoint configuration (e.g., conf/example_config.yaml) acts as the root node, composing various sub-configurations from specialized directories.

# conf/example_config.yaml

defaults:
  - _self_
  - data: cifar10_example
  - model: convkan_example

trainer:
  _target_: lightning.Trainer
  max_epochs: 100
  accelerator: "gpu"
  devices: 1

# Variable interpolation example
seed: 42

In this setup, the defaults block dictates which sub-configurations to load. If data: cifar10_example is specified, Hydra looks for conf/data/cifar10_example.yaml and injects its contents into the data namespace of the final configuration tree.

Command-Line Overrides

One of the most powerful features of Hydra is the ability to override any parameter directly from the command line interface (CLI). This eliminates the need to maintain dozens of slightly modified YAML files for hyperparameter sweeps.

Modifying Nested Parameters

To override a parameter nested within the configuration tree, specify the exact dot-notation path:

python -m src.cli train -c example_config.yaml trainer.max_epochs=200 data.batch_size=128

Swapping Sub-configurations

To entirely replace a sub-configuration module (e.g., swapping the model architecture from CNN to KAN), utilize the override syntax in the defaults list:

python -m src.cli train -c example_config.yaml model=resnet50_example

Variable Interpolation

Hydra supports dynamic variable interpolation, allowing parameters to reference other values within the configuration tree. This is highly beneficial for maintaining consistency.

paths:
  data_dir: "./data"

data:
  _target_: src.data.cifar10_example.CIFAR10DataModule
  # Resolves to "./data" dynamically
  data_dir: ${paths.data_dir}