HPO Optimizers API¶

def search(self) -> dict[str, Any]:
    """
    Actual function performing hyperparameter optimization for the selected
    objective function.

    Returns
    -------
    dict[str, Any]
        The best set of parameters with achieved score.

    Raises
    ------
    OptimizationError
        When there were no successful evaluations for given constraints.
    """
    self.current_phase = "warm_start"
    self.evaluate_initial_random_nodes()

    self.current_phase = "gam"
    if len(self.evaluations) >= self.max_evals:
        logger.info(
            "All %d allowed evaluations were consumed by the warm-start phase; GAM iterations will be skipped.",
            self.max_evals,
        )
    self._remaining_gam_output_capacity = max(0, self.max_iterations - self.warm_start_output_count)
    try:
        for _ in range(self._get_gam_iterations_limit()):
            self._run_iteration()
    finally:
        self._remaining_gam_output_capacity = None

    self.current_phase = "complete"

    successful_evaluations = [evaluation for evaluation in self.evaluations if evaluation["score"] is not None]
    if not successful_evaluations:
        raise OptimizationError("Number of evaluations has reached limit. All iterations have failed.")

    # Sort in ascending order and take the last element (highest score).
    # This assumes we're maximizing the score.
    best_config_with_score = sorted(successful_evaluations, key=lambda d: d["score"])[-1]

    return best_config_with_score

def compute_warm_start_effective_target(self) -> int:
    """Return the effective number of successful warm-start nodes to evaluate.

    Returns
    -------
    int
        The effective warm-start target for the configured strategy.
    """
    return self._compute_warm_start_effective_target()

def evaluate_initial_random_nodes(self) -> None:
    """
    Perform evaluation of randomly chosen nodes from the solutions space.
    All strategies stop at the configured maximum evaluation count. Greedy
    and balanced starts may therefore finish before their coverage target
    when the evaluation budget is smaller than the coverage requirement.

    When the optimizer has been warm-started with known observations,
    already-successful evaluations count toward the n_random_nodes target
    and already-evaluated combinations are excluded from candidates.

    The selection order depends on warm_start_strategy:
    "random"   — shuffled order (no reordering).
    "greedy"   — greedy selection maximizing string-column coverage (each value >= 2 times).
    "balanced" — round-robin across fields_to_balance value tuples.
    """
    successful_evaluations = sum(1 for e in self.evaluations if e["score"] is not None)
    effective_target = self._compute_warm_start_effective_target()

    if successful_evaluations >= effective_target:
        logger.info(
            "Skipping random evaluation phase: %d known successful evaluations >= warm_start_target (%d).",
            successful_evaluations,
            effective_target,
        )
        return

    if len(self.evaluations) >= self.max_evals:
        return

    combinations_local = self._prepare_warm_start_combinations(effective_target, successful_evaluations)
    discrete_cols_in_space = _get_discrete_column_values(combinations_local)
    self._evaluate_warm_start_combinations(combinations_local, effective_target, successful_evaluations)

    self._log_uncovered_values(discrete_cols_in_space, self.evaluations, effective_target)

    self.warm_start_evaluation_count = len(self.evaluations)

def search(self) -> dict[str, Any]:
    """
    Actual function performing hyperparameter optimization for the selected
    objective function.

    Returns
    -------
    dict[str, Any]
        The best set of parameters with achieved score.

    Raises
    ------
    OptimizationError
        When there were no successful evaluations for given constraints.
    """
    combinations = list(self._search_space.combinations)
    random.Random(self.settings.random_state).shuffle(combinations)

    for idx in range(self.settings.max_evals):
        score = self._objective_function(combinations[idx])
        self._evaluated_combinations.append(combinations[idx] | {"score": score})

    successful_evaluations = [ev for ev in self._evaluated_combinations if ev["score"] is not None]

    if not successful_evaluations:
        raise OptimizationError("Number of evaluations has reached limit. All iterations have failed.")

    best_config_with_score = sorted(successful_evaluations, key=lambda d: d["score"])[-1]

    return best_config_with_score