Skip to content

config_builder

orchard.optimization.objective.config_builder

Trial configuration building utilities.

This module provides a builder responsible for creating trial-specific Config instances for Optuna experiments, handling parameter mapping, metadata preservation, and validation.

TrialConfigBuilder(base_cfg)

Builds trial-specific Config instances for Optuna trials.

Handles parameter mapping from Optuna's flat namespace to Config's hierarchical structure, preserves dataset metadata excluded from serialization, and validates via Pydantic.

Attributes:

Name Type Description
base_cfg

Base configuration template
optuna_epochs

Number of epochs for Optuna trials (from cfg.optuna.epochs)
base_metadata

Cached dataset metadata
Example

builder = TrialConfigBuilder(base_cfg) trial_params = {"learning_rate": 0.001, "dropout": 0.3} trial_cfg = builder.build(trial_params)

Initialize config builder.

Parameters:

Name Type Description Default
base_cfg Config

Base configuration template

 required
Source code in orchard/optimization/objective/config_builder.py 
37
38
39
40
41
42
43
44
45
46
def __init__(self, base_cfg: Config) -> None:
    """
    Initialize config builder.

    Args:
        base_cfg: Base configuration template
    """
    self.base_cfg = base_cfg
    self.optuna_epochs = base_cfg.optuna.epochs
    self.base_metadata = base_cfg.dataset._ensure_metadata

build(trial_params)

Build trial-specific Config with parameter overrides.

Parameters:

Name Type Description Default
trial_params dict[str, Any]

Sampled hyperparameters from Optuna

 required

Returns:

Type Description
Config

Validated Config instance with trial parameters
Source code in orchard/optimization/objective/config_builder.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def build(self, trial_params: dict[str, Any]) -> Config:
    """
    Build trial-specific Config with parameter overrides.

    Args:
        trial_params: Sampled hyperparameters from Optuna

    Returns:
        Validated Config instance with trial parameters
    """
    config_dict = self.base_cfg.model_dump()

    # Preserve resolution
    if config_dict["dataset"].get("resolution") is None:
        config_dict["dataset"]["resolution"] = self.base_cfg.dataset.resolution

    # Re-inject metadata (excluded from serialization)
    config_dict["dataset"]["metadata"] = self.base_metadata

    # Override epochs for Optuna trials
    config_dict["training"]["epochs"] = self.optuna_epochs

    # Cap mixup_epochs to trial length (prevents _check_mixup_epochs ValueError)
    config_dict["training"]["mixup_epochs"] = min(
        config_dict["training"]["mixup_epochs"], self.optuna_epochs
    )

    # Apply trial-specific overrides
    self._apply_param_overrides(config_dict, trial_params)

    return Config(**config_dict)